[firestore] Add snapshot to *Data responses to give more control to the developer

Author: chrisbianca

firestore/README.md

@@ -115,7 +115,8 @@ Returns:
 ### useCollectionData
 
 ```js
-const [values, loading, error] = useCollectionData < T > (query, options);
+const [values, loading, error, snapshot] =
+  useCollectionData < T > (query, options);
 ```
 
 As `useCollection`, but this hook extracts a typed list of the `firestore.QuerySnapshot.docs` values, rather than the
@@ -133,11 +134,13 @@ Returns:
 - `values`: an array of `T`, or `undefined` if no query is supplied
 - `loading`: a `boolean` to indicate if the data is still being loaded
 - `error`: Any `firestore.FirestoreError` returned by Firebase when trying to load the data, or `undefined` if there is no error
+- `snapshot`: a `firestore.QuerySnapshot`, or `undefined` if no query is supplied. This allows access to the underlying snapshot if needed for any reason, e.g. to view the snapshot metadata
 
 ### useCollectionDataOnce
 
 ```js
-const [values, loading, error] = useCollectionDataOnce < T > (query, options);
+const [values, loading, error, snapshot] =
+  useCollectionDataOnce < T > (query, options);
 ```
 
 As `useCollectionData`, but this hook will only read the current value of the `firestore.Query`.
@@ -155,6 +158,7 @@ Returns:
 - `values`: an array of `T`, or `undefined` if no query is supplied
 - `loading`: a `boolean` to indicate if the data is still being loaded
 - `error`: Any `firestore.FirestoreError` returned by Firebase when trying to load the data, or `undefined` if there is no error
+- `snapshot`: a `firestore.QuerySnapshot`, or `undefined` if no query is supplied. This allows access to the underlying snapshot if needed for any reason, e.g. to view the snapshot metadata
 
 ### useDocument
 
@@ -225,7 +229,8 @@ Returns:
 ### useDocumentData
 
 ```js
-const [value, loading, error] = useDocumentData < T > (reference, options);
+const [value, loading, error, snapshot] =
+  useDocumentData < T > (reference, options);
 ```
 
 As `useDocument`, but this hook extracts the typed contents of `firestore.DocumentSnapshot.data()`, rather than the
@@ -243,11 +248,13 @@ Returns:
 - `value`: `T`, or `undefined` if no query is supplied
 - `loading`: a `boolean` to indicate if the data is still being loaded
 - `error`: Any `firestore.FirestoreError` returned by Firebase when trying to load the data, or `undefined` if there is no error
+- `snapshot`: a `firestore.DocumentSnapshot`, or `undefined` if no query is supplied. This allows access to the underlying snapshot if needed for any reason, e.g. to view the snapshot metadata
 
 ### useDocumentDataOnce
 
 ```js
-const [value, loading, error] = useDocumentDataOnce < T > (reference, options);
+const [value, loading, error, snapshot] =
+  useDocumentDataOnce < T > (reference, options);
 ```
 
 As `useDocument`, but this hook will only read the current value of the `firestore.DocumentReference`.
@@ -265,6 +272,7 @@ Returns:
 - `value`: `T`, or `undefined` if no query is supplied
 - `loading`: a `boolean` to indicate if the data is still being loaded
 - `error`: Any `firestore.FirestoreError` returned by Firebase when trying to load the data, or `undefined` if there is no error
+- `snapshot`: a `firestore.DocumentSnapshot`, or `undefined` if no query is supplied. This allows access to the underlying snapshot if needed for any reason, e.g. to view the snapshot metadata
 
 ## Transforming data
 

firestore/types.ts

@@ -27,13 +27,20 @@ export type CollectionHook<T = DocumentData> = LoadingHook<
   QuerySnapshot<T>,
   FirestoreError
 >;
-export type CollectionDataHook<T = DocumentData> = LoadingHook<
-  T[],
-  FirestoreError
->;
+export type CollectionDataHook<T = DocumentData> = [
+  T[] | undefined,
+  boolean,
+  FirestoreError | undefined,
+  QuerySnapshot<T> | undefined
+];
 
 export type DocumentHook<T = DocumentData> = LoadingHook<
   DocumentSnapshot<T>,
   FirestoreError
 >;
-export type DocumentDataHook<T = DocumentData> = LoadingHook<T, FirestoreError>;
+export type DocumentDataHook<T = DocumentData> = [
+  T | undefined,
+  boolean,
+  FirestoreError | undefined,
+  DocumentSnapshot<T> | undefined
+];

firestore/useCollection.ts

@@ -125,7 +125,7 @@ const useCollectionDataInternal = <T = DocumentData>(
     [snapshots, snapshotOptions]
   );
 
-  const resArray: CollectionDataHook<T> = [values, loading, error];
+  const resArray: CollectionDataHook<T> = [values, loading, error, snapshots];
   return useMemo(() => resArray, resArray);
 };
 

firestore/useDocument.ts

@@ -124,7 +124,7 @@ const useDocumentDataInternal = <T = DocumentData>(
     snapshotOptions,
   ]);
 
-  const resArray: DocumentDataHook<T> = [value, loading, error];
+  const resArray: DocumentDataHook<T> = [value, loading, error, snapshot];
   return useMemo(() => resArray, resArray);
 };