Add hooks to get firestore document data once (#211)

* Add hooks to get firestore document data once
* use checkStartWithValue for consistency

Co-authored-by: James Daniels <[email protected]>

Author: davepwsmith

docs/reference.md

@@ -22,7 +22,9 @@
   - Database
     - Cloud Firestore
       - [`useFirestoreDoc`](#useFirestoreDoc)
+      - [`useFirestoreDocOnce`](#useFirestoreDocOnce)
       - [`useFirestoreDocData`](#useFirestoreDocData)
+      - [`useFirestoreDocDataOnce`](#useFirestoreDocDataOnce)
       - [`useFirestoreCollection`](#useFirestoreCollection)
       - [`useFirestoreCollectionData`](#useFirestoreCollectionData)
     - Realtime Database
@@ -191,6 +193,23 @@ _Throws a Promise by default_
 
 [`DocumentSnapshot`](https://firebase.google.com/docs/reference/js/firebase.firestore.DocumentSnapshot)
 
+### `useFirestoreDocOnce`
+
+Get a firestore document, but don't listen for updates.
+
+_Throws a Promise by default_
+
+#### Parameters
+
+| Parameter   | Type                                                                                                      | Description                                                                  |
+| ----------- | --------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
+| ref         | [`DocumentReference`](https://firebase.google.com/docs/reference/js/firebase.firestore.DocumentReference) | A reference to the document you want to listen to                            |
+| options _?_ | ReactFireOptions                                                                                          | Options. This hook will not throw a Promise if you provide `startWithValue`. |
+
+#### Returns
+
+[`DocumentSnapshot`](https://firebase.google.com/docs/reference/js/firebase.firestore.DocumentSnapshot)
+
 ### `useFirestoreDocData`
 
 Listen to a Firestore Document.
@@ -208,6 +227,23 @@ _Throws a Promise by default_
 
 `T`
 
+### `useFirestoreDocDataOnce`
+
+Get a firestore document, but don't listen for updates.
+
+_Throws a Promise by default_
+
+#### Parameters
+
+| Parameter   | Type                                                                                                      | Description                                                                  |
+| ----------- | --------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
+| ref         | [`DocumentReference`](https://firebase.google.com/docs/reference/js/firebase.firestore.DocumentReference) | A reference to the document you want to listen to                            |
+| options _?_ | ReactFireOptions                                                                                          | Options. This hook will not throw a Promise if you provide `startWithValue`. |
+
+#### Returns
+
+`T`
+
 ### `useFirestoreCollection`
 
 Listen to a Firestore Collection.

reactfire/firestore/firestore.test.tsx

@@ -8,7 +8,9 @@ import {
   useFirestoreCollection,
   FirebaseAppProvider,
   useFirestoreCollectionData,
-  useFirestoreDocData
+  useFirestoreDocData,
+  useFirestoreDocDataOnce,
+  useFirestoreDocOnce
 } from '..';
 import { firestore } from 'firebase/app';
 
@@ -104,6 +106,75 @@ describe('Firestore', () => {
     });
   });
 
+  describe('useFirestoreDocOnce', () => {
+    it('works when the document does not exist, and does not update when it is created', async () => {
+      const ref = app
+        .firestore()
+        .collection('testDoc')
+        .doc('emptydoc');
+
+      const ReadFirestoreDoc = () => {
+        const dataOnce = useFirestoreDocOnce<any>(ref);
+
+        return (
+          <>
+            <h1 data-testid="once">{dataOnce.exists.toString()}</h1>
+          </>
+        );
+      };
+      const { getByTestId } = render(
+        <FirebaseAppProvider firebase={app}>
+          <React.Suspense fallback={<h1 data-testid="fallback">Fallback</h1>}>
+            <ReadFirestoreDoc />
+          </React.Suspense>
+        </FirebaseAppProvider>
+      );
+
+      await waitForElement(() => getByTestId('once'));
+      expect(getByTestId('once')).toContainHTML('false');
+
+      await act(() => ref.set({ a: 'test' }));
+      expect(getByTestId('once')).toContainHTML('false');
+    });
+  });
+
+  describe('useFirestoreDocDataOnce', () => {
+    it('does not update on database changes [TEST REQUIRES EMULATOR]', async () => {
+      const mockData1 = { a: 'hello' };
+      const mockData2 = { a: 'goodbye' };
+
+      const ref = app
+        .firestore()
+        .collection('testDoc')
+        .doc('readSuccess');
+
+      await ref.set(mockData1);
+
+      const ReadFirestoreDoc = () => {
+        const dataOnce = useFirestoreDocDataOnce<any>(ref, { idField: 'id' });
+
+        return (
+          <>
+            <h1 data-testid="once">{dataOnce.a}</h1>{' '}
+          </>
+        );
+      };
+      const { getByTestId } = render(
+        <FirebaseAppProvider firebase={app}>
+          <React.Suspense fallback={<h1 data-testid="fallback">Fallback</h1>}>
+            <ReadFirestoreDoc />
+          </React.Suspense>
+        </FirebaseAppProvider>
+      );
+
+      await waitForElement(() => getByTestId('once'));
+      expect(getByTestId('once')).toContainHTML(mockData1.a);
+
+      await act(() => ref.set(mockData2));
+      expect(getByTestId('once')).toContainHTML(mockData1.a);
+    });
+  });
+
   describe('useFirestoreCollection', () => {
     it('can get a Firestore collection [TEST REQUIRES EMULATOR]', async () => {
       const mockData1 = { a: 'hello' };

reactfire/firestore/index.tsx

@@ -13,6 +13,7 @@ import {
   checkStartWithValue
 } from '..';
 import { preloadObservable } from '../useObservable';
+import { first } from 'rxjs/operators';
 
 // starts a request for a firestore doc.
 // imports the firestore SDK automatically
@@ -52,6 +53,23 @@ export function useFirestoreDoc<T = unknown>(
   );
 }
 
+/**
+ * Get a firestore document and don't subscribe to changes
+ *
+ * @param ref - Reference to the document you want to get
+ * @param options
+ */
+export function useFirestoreDocOnce<T = unknown>(
+  ref: firestore.DocumentReference,
+  options?: ReactFireOptions<T>
+): T extends {} ? T : firestore.DocumentSnapshot {
+  return useObservable(
+    doc(ref).pipe(first()),
+    `firestore:docOnce:${ref.firestore.app.name}:${ref.path}`,
+    checkStartWithValue(options)
+  );
+}
+
 /**
  * Suscribe to Firestore Document changes
  *
@@ -70,6 +88,24 @@ export function useFirestoreDocData<T = unknown>(
   );
 }
 
+/**
+ * Get a firestore document and don't subscribe to changes
+ *
+ * @param ref - Reference to the document you want to get
+ * @param options
+ */
+export function useFirestoreDocDataOnce<T = unknown>(
+  ref: firestore.DocumentReference,
+  options?: ReactFireOptions<T>
+): T {
+  const idField = checkIdField(options);
+  return useObservable(
+    docData(ref, idField).pipe(first()),
+    `firestore:docDataOnce:${ref.firestore.app.name}:${ref.path}:idField=${idField}`,
+    checkStartWithValue(options)
+  );
+}
+
 /**
  * Subscribe to a Firestore collection
  *
@@ -87,7 +123,7 @@ export function useFirestoreCollection<T = { [key: string]: unknown }>(
   return useObservable(
     fromCollectionRef(query),
     queryId,
-    options ? options.startWithValue : undefined
+    checkStartWithValue(options)
   );
 }
 

sample/src/Firestore.js

@@ -5,6 +5,7 @@ import {
   SuspenseWithPerf,
   useFirestoreCollectionData,
   useFirestoreDocData,
+  useFirestoreDocDataOnce,
   useFirestore
 } from 'reactfire';
 
@@ -32,6 +33,16 @@ const Counter = props => {
   );
 };
 
+const StaticValue = props => {
+  const firestore = useFirestore();
+
+  const ref = firestore().doc('count/counter');
+
+  const { value } = useFirestoreDocDataOnce(ref);
+
+  return <span>{value}</span>;
+};
+
 const AnimalEntry = ({ saveAnimal }) => {
   const [text, setText] = useState('');
   const [disabled, setDisabled] = useState(false);
@@ -121,6 +132,14 @@ const SuspenseWrapper = props => {
           >
             <Counter />
           </SuspenseWithPerf>
+          <h3>Sample One-time Get</h3>
+          <SuspenseWithPerf
+            fallback="connecting to Firestore..."
+            traceId="firestore-demo-doc"
+          >
+            <StaticValue />
+          </SuspenseWithPerf>
+
           <h3>Sample Collection Listener</h3>
           <SuspenseWithPerf
             fallback="connecting to Firestore..."