feat: improved types to properly infer and include IDField and RefField options

Author: hannojg

docs/firestore.md

@@ -290,4 +290,4 @@ The `transform` function is passed a single row of a data, so will be called onc
 
 The `transform` function will not receive the `id` or `ref` values referenced in the properties named in the `idField` or `refField` options, nor it is expected to produce them. Either or both, if specified, will be merged afterwards.
 
-If the `transform` function is defined within your React component, it is recomended that you memoize the function to prevent unnecessry renders.
+If the `transform` function is defined within your React component, it is recommended that you memoize the function to prevent unnecessary renders.

src/firestore/helpers/index.ts

@@ -1,25 +1,37 @@
 import type { FirebaseFirestoreTypes } from '@react-native-firebase/firestore';
+import type { Data } from '../types';
 
-export const snapshotToData = <T = FirebaseFirestoreTypes.DocumentData>(
+export const snapshotToData = <
+  T = FirebaseFirestoreTypes.DocumentData,
+  IDField extends string | undefined = undefined,
+  RefField extends string | undefined = undefined
+>(
   snapshot: FirebaseFirestoreTypes.DocumentSnapshot<T>,
-  idField?: string,
-  refField?: string,
+  idField?: IDField,
+  refField?: RefField,
   transform?: (val: any) => T
-) => {
+): Data<T, IDField, RefField> | undefined => {
   if (!snapshot.exists) {
     return undefined;
   }
 
-  let data = snapshot.data() as FirebaseFirestoreTypes.DocumentData;
+  let data = snapshot.data();
+  // this case should never happen as, we did a earlier exists check
+  // so this line here is more to satisfy TS
+  if (data == null) return undefined;
+
   if (transform) {
     data = transform(data);
   }
-  if (idField) {
+  if (typeof idField === 'string') {
+    // @ts-expect-error We add a new field to a predefined object
     data[idField] = snapshot.id;
   }
-  if (refField) {
+  if (typeof refField === 'string') {
+    // @ts-expect-error We add a new field to a predefined object
     data[refField] = snapshot.ref;
   }
 
+  // @ts-expect-error TODO: is there any way we can convince it, that it conforms the Data type?
   return data;
 };

src/firestore/types.ts

@@ -1,36 +1,50 @@
 import type { LoadingHook } from '../util';
 import type { FirebaseFirestoreTypes } from '@react-native-firebase/firestore';
 
-export type IDOptions<T> = {
-  idField?: string;
-  refField?: string;
+export type IDOptions<
+  T,
+  IDField extends string | undefined = undefined,
+  RefField extends string | undefined = undefined
+> = {
+  idField?: IDField;
+  refField?: RefField;
   transform?: (val: any) => T;
 };
 export type Options = {
   snapshotListenOptions?: FirebaseFirestoreTypes.SnapshotListenOptions;
 };
-export type DataOptions<T> = Options & IDOptions<T>;
+export type DataOptions<
+  T,
+  IDField extends string | undefined = undefined,
+  RefField extends string | undefined = undefined
+> = Options & IDOptions<T, IDField, RefField>;
 export type OnceOptions = {
   getOptions?: GetOptions;
 };
 export type GetOptions = {
   source?: 'default' | 'server' | 'cache';
 };
-export type OnceDataOptions<T> = OnceOptions & IDOptions<T>;
+export type OnceDataOptions<
+  T,
+  IDField extends string | undefined = undefined,
+  RefField extends string | undefined = undefined
+> = OnceOptions & IDOptions<T, IDField, RefField>;
 export type Data<
   T = FirebaseFirestoreTypes.DocumentData,
-  IDField extends string = '',
-  RefField extends string = ''
+  IDField extends string | undefined = undefined,
+  RefField extends string | undefined = undefined
 > = T &
-  Record<IDField, string> &
-  Record<RefField, FirebaseFirestoreTypes.DocumentReference<T>>;
+  (IDField extends string ? Record<IDField, string> : {}) &
+  (RefField extends string
+    ? Record<RefField, FirebaseFirestoreTypes.DocumentReference<T>>
+    : {});
 
 export type CollectionHook<T = FirebaseFirestoreTypes.DocumentData> =
   LoadingHook<FirebaseFirestoreTypes.QuerySnapshot<T>, Error>;
 export type CollectionDataHook<
   T = FirebaseFirestoreTypes.DocumentData,
-  IDField extends string = '',
-  RefField extends string = ''
+  IDField extends string | undefined = undefined,
+  RefField extends string | undefined = undefined
 > = LoadingHook<Data<T, IDField, RefField>[], Error>;
 
 export type DocumentHook<T = FirebaseFirestoreTypes.DocumentData> = LoadingHook<
@@ -39,6 +53,6 @@ export type DocumentHook<T = FirebaseFirestoreTypes.DocumentData> = LoadingHook<
 >;
 export type DocumentDataHook<
   T = FirebaseFirestoreTypes.DocumentData,
-  IDField extends string = '',
-  RefField extends string = ''
+  IDField extends string | undefined = undefined,
+  RefField extends string | undefined = undefined
 > = LoadingHook<Data<T, IDField, RefField>, Error>;

src/firestore/useCollection.ts

@@ -28,19 +28,19 @@ export const useCollectionOnce = <T = FirebaseFirestoreTypes.DocumentData>(
 
 export const useCollectionData = <
   T = FirebaseFirestoreTypes.DocumentData,
-  IDField extends string = '',
-  RefField extends string = ''
+  IDField extends string | undefined = undefined,
+  RefField extends string | undefined = undefined
 >(
   query?: FirebaseFirestoreTypes.Query<T> | null,
-  options?: DataOptions<T>
+  options?: DataOptions<T, IDField, RefField>
 ): CollectionDataHook<T, IDField, RefField> => {
   return useCollectionDataInternal<T, IDField, RefField>(true, query, options);
 };
 
 export const useCollectionDataOnce = <
   T = FirebaseFirestoreTypes.DocumentData,
-  IDField extends string = '',
-  RefField extends string = ''
+  IDField extends string | undefined = undefined,
+  RefField extends string | undefined = undefined
 >(
   query?: FirebaseFirestoreTypes.Query<T> | null,
   options?: OnceDataOptions<T>
@@ -101,12 +101,13 @@ const useCollectionInternal = <T = FirebaseFirestoreTypes.DocumentData>(
 
 const useCollectionDataInternal = <
   T = FirebaseFirestoreTypes.DocumentData,
-  IDField extends string = '',
-  RefField extends string = ''
+  IDField extends string | undefined = undefined,
+  RefField extends string | undefined = undefined
 >(
   listen: boolean,
   query?: FirebaseFirestoreTypes.Query<T> | null,
-  options?: DataOptions<T> & OnceDataOptions<T>
+  options?: DataOptions<T, IDField, RefField> &
+    OnceDataOptions<T, IDField, RefField>
 ): CollectionDataHook<T, IDField, RefField> => {
   const idField = options ? options.idField : undefined;
   const refField = options ? options.refField : undefined;
@@ -120,7 +121,12 @@ const useCollectionDataInternal = <
     () =>
       (snapshots
         ? snapshots.docs.map((doc) =>
-            snapshotToData<T>(doc, idField, refField, transform)
+            snapshotToData<T, IDField, RefField>(
+              doc,
+              idField,
+              refField,
+              transform
+            )
           )
         : undefined) as Data<T, IDField, RefField>[],
     [snapshots, idField, refField, transform]

src/firestore/useDocument.ts

@@ -28,22 +28,22 @@ export const useDocumentOnce = <T = FirebaseFirestoreTypes.DocumentData>(
 
 export const useDocumentData = <
   T = FirebaseFirestoreTypes.DocumentData,
-  IDField extends string = '',
-  RefField extends string = ''
+  IDField extends string | undefined = undefined,
+  RefField extends string | undefined = undefined
 >(
   docRef?: FirebaseFirestoreTypes.DocumentReference<T> | null,
-  options?: DataOptions<T>
+  options?: DataOptions<T, IDField, RefField>
 ): DocumentDataHook<T, IDField, RefField> => {
   return useDocumentDataInternal<T, IDField, RefField>(true, docRef, options);
 };
 
 export const useDocumentDataOnce = <
   T = FirebaseFirestoreTypes.DocumentData,
-  IDField extends string = '',
-  RefField extends string = ''
+  IDField extends string | undefined = undefined,
+  RefField extends string | undefined = undefined
 >(
   docRef?: FirebaseFirestoreTypes.DocumentReference<T> | null,
-  options?: OnceDataOptions<T>
+  options?: OnceDataOptions<T, IDField, RefField>
 ): DocumentDataHook<T, IDField, RefField> => {
   return useDocumentDataInternal<T, IDField, RefField>(false, docRef, options);
 };
@@ -104,12 +104,12 @@ const useDocumentInternal = <T = FirebaseFirestoreTypes.DocumentData>(
 
 const useDocumentDataInternal = <
   T = FirebaseFirestoreTypes.DocumentData,
-  IDField extends string = '',
-  RefField extends string = ''
+  IDField extends string | undefined = undefined,
+  RefField extends string | undefined = undefined
 >(
   listen: boolean,
   docRef?: FirebaseFirestoreTypes.DocumentReference<T> | null,
-  options?: DataOptions<T>
+  options?: DataOptions<T, IDField, RefField>
 ): DocumentDataHook<T, IDField, RefField> => {
   const idField = options ? options.idField : undefined;
   const refField = options ? options.refField : undefined;
@@ -122,7 +122,12 @@ const useDocumentDataInternal = <
   const value = useMemo(
     () =>
       (snapshot
-        ? snapshotToData<T>(snapshot, idField, refField, transform)
+        ? snapshotToData<T, IDField, RefField>(
+            snapshot,
+            idField,
+            refField,
+            transform
+          )
         : undefined) as Data<T, IDField, RefField>,
     [snapshot, idField, refField, transform]
   );