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.