fix: tighten ReactFireOptions generic types, remove T | any widening

.npmignore

@@ -0,0 +1 @@
+src/*.type-test.ts

README.md

@@ -13,7 +13,7 @@ Firebase.
 
 ## Platform support
 
-ReactFire is designed for **web React apps** and wraps the [Firebase Web SDK](https://firebase.google.com/docs/web/setup). It is not compatible with React Native or Expo. For React Native projects, use [react-native-firebase](https://rnfirebase.io/) instead.
+ReactFire is designed for **web React apps** and wraps the [Firebase JavaScript SDK](https://firebase.google.com/docs/web/setup). It is not compatible with React Native or Expo. For React Native projects, use [react-native-firebase](https://rnfirebase.io/) instead.
 
 ## Install
 

src/firestore.tsx

@@ -39,7 +39,7 @@ function getDocObservableId<T = DocumentData>(ref: DocumentReference<T>) {
  *
  * You can preload data for this hook by calling `preloadFirestoreDoc`
  */
-export function useFirestoreDoc<T = DocumentData>(ref: DocumentReference<T>, options?: ReactFireOptions<T>): ObservableStatus<DocumentSnapshot<T>> {
+export function useFirestoreDoc<T = DocumentData>(ref: DocumentReference<T>, options?: ReactFireOptions<DocumentSnapshot<T>>): ObservableStatus<DocumentSnapshot<T>> {
   const observableId = getDocObservableId(ref);
   const observable$ = doc(ref);
 
@@ -49,7 +49,7 @@ export function useFirestoreDoc<T = DocumentData>(ref: DocumentReference<T>, opt
 /**
  * Get a firestore document and don't subscribe to changes
  */
-export function useFirestoreDocOnce<T = DocumentData>(ref: DocumentReference<T>, options?: ReactFireOptions<T>): ObservableStatus<DocumentSnapshot<T>> {
+export function useFirestoreDocOnce<T = DocumentData>(ref: DocumentReference<T>, options?: ReactFireOptions<DocumentSnapshot<T>>): ObservableStatus<DocumentSnapshot<T>> {
   const observableId = `firestore:docOnce:${ref.firestore.app.name}:${ref.path}`;
   const observable$ = doc(ref).pipe(first());
 
@@ -63,7 +63,7 @@ export function useFirestoreDocData<T = unknown>(ref: DocumentReference<T>, opti
   const idField = options ? checkIdField(options) : undefined;
 
   const observableId = `firestore:docData:${ref.firestore.app.name}:${ref.path}:idField=${JSON.stringify(idField)}`;
-  const observable = docData(ref, { idField });
+  const observable = docData(ref, { idField: idField as keyof T });
 
   return useObservable(observableId, observable, options) as ObservableStatus<T>;
 }
@@ -75,15 +75,15 @@ export function useFirestoreDocDataOnce<T = unknown>(ref: DocumentReference<T>,
   const idField = options ? checkIdField(options) : undefined;
 
   const observableId = `firestore:docDataOnce:${ref.firestore.app.name}:${ref.path}:idField=${JSON.stringify(idField)}`;
-  const observable$ = docData(ref, { idField }).pipe(first());
+  const observable$ = docData(ref, { idField: idField as keyof T }).pipe(first());
 
   return useObservable(observableId, observable$, options) as ObservableStatus<T>;
 }
 
 /**
  * Subscribe to a Firestore collection
  */
-export function useFirestoreCollection<T = DocumentData>(query: FirestoreQuery<T>, options?: ReactFireOptions<T[]>): ObservableStatus<QuerySnapshot<T>> {
+export function useFirestoreCollection<T = DocumentData>(query: FirestoreQuery<T>, options?: ReactFireOptions<QuerySnapshot<T>>): ObservableStatus<QuerySnapshot<T>> {
   const observableId = `firestore:collection:${getUniqueIdForFirestoreQuery(query)}`;
   const observable$ = fromRef(query);
 
@@ -96,7 +96,7 @@ export function useFirestoreCollection<T = DocumentData>(query: FirestoreQuery<T
 export function useFirestoreCollectionData<T = DocumentData>(query: FirestoreQuery<T>, options?: ReactFireOptions<T[]>): ObservableStatus<T[]> {
   const idField = options ? checkIdField(options) : undefined;
   const observableId = `firestore:collectionData:${getUniqueIdForFirestoreQuery(query)}:idField=${JSON.stringify(idField)}`;
-  const observable$ = collectionData(query, { idField });
+  const observable$ = collectionData(query, { idField: idField as (string & keyof T) });
 
   return useObservable(observableId, observable$, options);
 }

src/index.ts

@@ -23,14 +23,17 @@ export class ReactFireError extends Error {
 
 export interface ReactFireOptions<T = unknown> {
   idField?: string;
-  initialData?: T | any;
+  initialData?: T;
   /**
    * @deprecated use initialData instead
    */
-  startWithValue?: T | any;
+  startWithValue?: T;
   suspense?: boolean;
 }
 
+// Deprecated: unused internally as of the ReactFireOptions generic tightening.
+// Removal is tracked in #754 alongside the other deprecated exports, so it
+// lands as its own change rather than inside this one.
 export function checkOptions(options: ReactFireOptions, field: string) {
   // make sure the field passed in is a valid key of ReactFire Options
   if (field === 'idField' || field === 'initialData' || field === 'suspense') {
@@ -44,8 +47,8 @@ export function checkinitialData(options: ReactFireOptions) {
   return checkOptions(options, 'initialData');
 }
 
-export function checkIdField(options: ReactFireOptions) {
-  return checkOptions(options, 'idField');
+export function checkIdField(options: ReactFireOptions): string | undefined {
+  return options?.idField;
 }
 
 export * from './auth';

src/reactfire-options.type-test.ts

@@ -0,0 +1,46 @@
+/**
+ * Type-level regression tests for ReactFireOptions<T> generic constraints.
+ * Checked by `tsc --noEmit` in CI. No runtime behavior — not bundled.
+ */
+import type { ReactFireOptions } from './index';
+
+// ---- initialData must match T ----
+
+void ((): ReactFireOptions<string> => ({ initialData: 'hello' }))();
+void ((): ReactFireOptions<number> => ({ initialData: 42 }))();
+
+// @ts-expect-error initialData must be T, not a different type
+const _wrongInitialData: ReactFireOptions<string> = { initialData: 123 };
+void _wrongInitialData;
+
+// @ts-expect-error startWithValue must be T, not a different type
+const _wrongStartWithValue: ReactFireOptions<string> = { startWithValue: 123 };
+void _wrongStartWithValue;
+
+// ---- snapshot hooks take the snapshot, data hooks take the data (#741) ----
+//
+// Removing `T | any` also removed what was masking a mismatch: the raw snapshot
+// hooks resolve to a DocumentSnapshot/QuerySnapshot, so that is what a correct
+// initialData is. Without the hook-level fix, seeding them with a snapshot (the
+// only value you can actually have) stops compiling.
+
+import type { DocumentReference, DocumentSnapshot, Query, QuerySnapshot } from 'firebase/firestore';
+import type { useFirestoreCollection, useFirestoreDoc, useFirestoreDocData } from './firestore';
+
+declare const ref: DocumentReference<{ a: string }>;
+declare const query: Query<{ a: string }>;
+declare const snap: DocumentSnapshot<{ a: string }>;
+declare const querySnap: QuerySnapshot<{ a: string }>;
+declare const docHook: typeof useFirestoreDoc;
+declare const collectionHook: typeof useFirestoreCollection;
+declare const dataHook: typeof useFirestoreDocData;
+
+void (() => docHook(ref, { initialData: snap }));
+void (() => collectionHook(query, { initialData: querySnap }));
+void (() => dataHook(ref, { initialData: { a: 'x' } }));
+
+// @ts-expect-error a snapshot hook must not accept the unwrapped data type
+void (() => docHook(ref, { initialData: { a: 'x' } }));
+
+// @ts-expect-error a data hook must not accept a snapshot
+void (() => dataHook(ref, { initialData: snap }));