Merge pull request #191 from dylanwatsonsoftware/initial-value

Allow an initial value to be returned by the data hooks

Author: chrisbianca

.github/workflows/build.yml

@@ -0,0 +1,28 @@
+name: build
+on: push
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: actions/setup-node@v2
+        with:
+          node-version: '12'
+
+      - name: Cache node modules
+        uses: actions/cache@v2
+        env:
+          cache-name: cache-node-modules
+        with:
+          # npm cache files are stored in `~/.npm` on Linux/macOS
+          path: ~/.npm
+          key: ${{ runner.os }}-build-${{ env.cache-name }}-${{ hashFiles('**/package-lock.json') }}
+          restore-keys: |
+            ${{ runner.os }}-build-${{ env.cache-name }}-
+            ${{ runner.os }}-build-
+            ${{ runner.os }}-
+
+      - name: Install
+        run: npm install
+      - name: Build
+        run: npm run build

firestore/README.md

@@ -126,6 +126,7 @@ The `useCollectionData` hook takes the following parameters:
   - `snapshotListenOptions`: (optional) `firebase.firestore.SnapshotListenOptions` to customise how the collection is loaded
   - `snapshotOptions`: (optional) `firebase.firestore.SnapshotOptions` to customise how data is retrieved from snapshots
   - `transform`: (optional) a function that receives the raw `firebase.firestore.DocumentData` for each item in the collection to allow manual transformation of the data where required by the application. See [`Transforming data`](#transforming-data) below.
+  - `initialValue`: (optional) the initial value returned by the hook, until data from the firestore query has loaded
 
 Returns:
 
@@ -150,6 +151,7 @@ The `useCollectionDataOnce` hook takes the following parameters:
   - `refField`: (optional) name of the field that should be populated with the `firebase.firestore.QuerySnapshot.ref` property.
   - `snapshotOptions`: (optional) `firebase.firestore.SnapshotOptions` to customise how data is retrieved from snapshots
   - `transform`: (optional) a function that receives the raw `firebase.firestore.DocumentData` for each item in the collection to allow manual transformation of the data where required by the application. See [`Transforming data`](#transforming-data) below.
+  - `initialValue`: (optional) the initial value returned by the hook, until data from the firestore query has loaded
 
 Returns:
 
@@ -239,6 +241,7 @@ The `useDocumentData` hook takes the following parameters:
   - `snapshotListenOptions`: (optional) `firebase.firestore.SnapshotListenOptions` to customise how the collection is loaded
   - `snapshotOptions`: (optional) `firebase.firestore.SnapshotOptions` to customise how data is retrieved from snapshots
   - `transform`: (optional) a function that receives the raw `firebase.firestore.DocumentData` to allow manual transformation of the data where required by the application. See [`Transforming data`](#transforming-data) below.
+  - `initialValue`: (optional) the initial value returned by the hook, until data from the firestore query has loaded
 
 Returns:
 
@@ -263,6 +266,7 @@ The `useDocumentDataOnce` hook takes the following parameters:
   - `refField`: (optional) name of the field that should be populated with the `firebase.firestore.QuerySnapshot.ref` property.
   - `snapshotOptions`: (optional) `firebase.firestore.SnapshotOptions` to customise how data is retrieved from snapshots
   - `transform`: (optional) a function that receives the raw `firebase.firestore.DocumentData` to allow manual transformation of the data where required by the application. See [`Transforming data`](#transforming-data) below.
+  - `initialValue`: (optional) the initial value returned by the hook, until data from the firestore query has loaded
 
 Returns:
 

firestore/types.ts

@@ -11,6 +11,9 @@ export type Options = {
   snapshotListenOptions?: firebase.firestore.SnapshotListenOptions;
 };
 export type DataOptions<T> = Options & IDOptions<T>;
+export type InitialValueOptions<T> = {
+  initialValue?: T;
+};
 export type OnceOptions = {
   getOptions?: firebase.firestore.GetOptions;
 };

firestore/useCollection.ts

@@ -9,6 +9,7 @@ import {
   OnceOptions,
   OnceDataOptions,
   Options,
+  InitialValueOptions,
 } from './types';
 import { useIsEqualRef, useLoadingValue } from '../util';
 
@@ -32,7 +33,7 @@ export const useCollectionData = <
   RefField extends string = ''
 >(
   query?: firebase.firestore.Query | null,
-  options?: DataOptions<T>
+  options?: DataOptions<T> & InitialValueOptions<T[]>
 ): CollectionDataHook<T, IDField, RefField> => {
   return useCollectionDataInternal<T, IDField, RefField>(true, query, options);
 };
@@ -43,7 +44,7 @@ export const useCollectionDataOnce = <
   RefField extends string = ''
 >(
   query?: firebase.firestore.Query | null,
-  options?: OnceDataOptions<T>
+  options?: OnceDataOptions<T> & InitialValueOptions<T[]>
 ): CollectionDataHook<T, IDField, RefField> => {
   return useCollectionDataInternal<T, IDField, RefField>(false, query, options);
 };
@@ -100,7 +101,7 @@ const useCollectionDataInternal = <
 >(
   listen: boolean,
   query?: firebase.firestore.Query | null,
-  options?: DataOptions<T> & OnceDataOptions<T>
+  options?: DataOptions<T> & OnceDataOptions<T> & InitialValueOptions<T[]>
 ): CollectionDataHook<T, IDField, RefField> => {
   const idField = options ? options.idField : undefined;
   const refField = options ? options.refField : undefined;
@@ -123,7 +124,7 @@ const useCollectionDataInternal = <
               transform
             )
           )
-        : undefined) as Data<T, IDField, RefField>[],
+        : options && options.initialValue) as Data<T, IDField, RefField>[],
     [snapshots, snapshotOptions, idField, refField, transform]
   );
 

firestore/useDocument.ts

@@ -9,6 +9,7 @@ import {
   OnceOptions,
   OnceDataOptions,
   Options,
+  InitialValueOptions,
 } from './types';
 import { useIsEqualRef, useLoadingValue } from '../util';
 
@@ -32,7 +33,7 @@ export const useDocumentData = <
   RefField extends string = ''
 >(
   docRef?: firebase.firestore.DocumentReference | null,
-  options?: DataOptions<T>
+  options?: DataOptions<T> & InitialValueOptions<T>
 ): DocumentDataHook<T, IDField, RefField> => {
   return useDocumentDataInternal<T, IDField, RefField>(true, docRef, options);
 };
@@ -43,7 +44,7 @@ export const useDocumentDataOnce = <
   RefField extends string = ''
 >(
   docRef?: firebase.firestore.DocumentReference | null,
-  options?: OnceDataOptions<T>
+  options?: OnceDataOptions<T> & InitialValueOptions<T>
 ): DocumentDataHook<T, IDField, RefField> => {
   return useDocumentDataInternal<T, IDField, RefField>(false, docRef, options);
 };
@@ -100,7 +101,7 @@ const useDocumentDataInternal = <
 >(
   listen: boolean,
   docRef?: firebase.firestore.DocumentReference | null,
-  options?: DataOptions<T>
+  options?: DataOptions<T> & InitialValueOptions<T>
 ): DocumentDataHook<T, IDField, RefField> => {
   const idField = options ? options.idField : undefined;
   const refField = options ? options.refField : undefined;
@@ -121,7 +122,7 @@ const useDocumentDataInternal = <
             refField,
             transform
           )
-        : undefined) as Data<T, IDField, RefField>,
+        : options && options.initialValue) as Data<T, IDField, RefField>,
     [snapshot, snapshotOptions, idField, refField, transform]
   );