Add a published .d.ts diff to the release process to catch breaking type changes

[tyler-reitz]

Problem

4.2.4 shipped as a patch but contained breaking TypeScript type changes with no changelog note. The main one: ObservableStatus<T> was refactored from a flat interface (data: T) into a discriminated union (data: T | undefined unless narrowed on status), which breaks the standard destructure-and-use pattern across every data hook, including the documented suspense pattern. It is type-only (no runtime impact), but it reds strict-TS consumer CI on upgrade.

It slipped through because:

• The change came in via use useSyncExternalStore to sync data in useObservable #583 ("use useSyncExternalStore to sync data"), whose title looked like an internals change, not a public API break.
• It then sat unreleased for ~3 years (v4.2.3 was 2022-08, use useSyncExternalStore to sync data in useObservable #583 merged 2023-07).
• 4.2.4 batched 35 PRs of accumulated main into one bump, with no step auditing the cumulative public type surface.

Proposal

Add a release-time (or CI) check that diffs the candidate's emitted types against the last published version:

1. npm pack the latest published version, extract dist/*.d.ts.
2. npm pack the release candidate, extract dist/*.d.ts.
3. Diff them. Any non-additive change (removed/narrowed/changed signature) fails the check or requires an explicit "breaking" acknowledgment and a minor/major bump.

This exact diff would have flagged both the ObservableStatus union change and the useFirestoreDocData widening (#733) immediately.

Related

• Remediation for the live 4.2.4 release is tracked separately (deprecate + re-cut as 4.3.0 with a migration note).
• Surfaced while reviewing fix: tighten ReactFireOptions generic types, remove T | any widening #740.

[tyler-reitz]

End-to-end proof of the type break

Built a fresh consumer project, installed reactfire straight from npm, and ran tsc --strict on the documented suspense-mode pattern. Only the reactfire version changes between runs; tsconfig.json and app.tsx are identical.

app.tsx:

import { useFirestoreCollectionData } from 'reactfire';
import type { Query } from 'firebase/firestore';

interface Post { title: string; }

export function PostList({ postsQuery }: { postsQuery: Query<Post> }) {
  const { data: posts } = useFirestoreCollectionData(postsQuery);
  return posts.map((p) => p.title);
}

reactfire	Code	tsc --strict
4.2.3	posts.map(...)	green (exit 0)
4.2.4	posts.map(...)	red: app.tsx(10,10): error TS18048: 'posts' is possibly 'undefined'
4.2.4	posts?.map(...)	green (exit 0)

Root cause: ObservableStatus<T> went from a flat interface (data: T) to a discriminated union (data: T | undefined unless narrowed on status) in #583, shipped in 4.2.4. Confirmed the old shape directly: data: T in node_modules/reactfire/dist/useObservable.d.ts on 4.2.3.

This is exactly the diff a release-time .d.ts check (this issue) would have surfaced before publish.

[jhuleatt]

Thanks for investigating @tyler-reitz. Why didn't the ReactFire test suite catch this? There are suspense-mode tests in there:

reactfire/test/useObservable.test.tsx

Line 201 in 43dc25a

it('works with Suspense', async () => {

Is ReactFire's typescript config too loose to catch it? If possible, I'd rather catch issues like this in our test suite, instead of having to maintain a separate file just for type regressions.

[jhuleatt]

To fix the type break

1. @tyler-reitz Add typechecking to the test directory (and typecheck in the test workflow), and see if it catches the breaking type change
2. @tyler-reitz If it does, then we don't need a separate types test
3. @tyler-reitz Move ObservableStatus back to a strict type (take out the undefined union)
4. @tyler-reitz Verify in Suspense-mode sample app
5. @jhuleatt Release 4.2.5
6. @jhuleatt npm deprecate 4.2.4

Later

Move to a pnpm monorepo, and create another github workflow that builds the sample apps on merge to main

[tyler-reitz]

Steps 1-3 and 5 are done, #750 is merged to main: added a CI type-check over the test suite, reverted ObservableStatus to the strict (non-union) type, and verified the consumer contract (docs regenerated, .d.ts surface diff confirms 4.2.3's ObservableStatus is restored with #733's per-hook undefined preserved).

Ready for steps 6-7 (release 4.2.5 + deprecate 4.2.4) whenever you're online. Two notes: it removes the three types 4.2.4 added (ObservableStatusSuccess/Error/Loading), worth a release-notes line, and I left package.json at 4.2.3, so the version wants setting when you cut the release.