feat(database/firestore): add initialValue option (#165)

This might cause a minimal type issue for TypeScript if you have
imported and used the options interfaces.

src/database/useObjectValue.ts

@@ -11,6 +11,7 @@ export type UseObjectValueConverter<Value> = (snap: DataSnapshot) => Value;
 
 export interface UseObjectValueOptions<Value> {
     converter?: UseObjectValueConverter<Value>;
+    initialValue?: Value;
 }
 
 /**
@@ -20,6 +21,7 @@ export interface UseObjectValueOptions<Value> {
  * @param {Query | undefined | null} query Realtime Database query
  * @param {?UseObjectValueOptions} options Options to configure how the object is fetched
  * * `converter`: Function to extract the desired data from the DataSnapshot. Similar to Firestore converters. Default: `snap.val()`.
+ * * `initialValue`: Value that is returned while the object is being fetched.
  * @returns {UseObjectValueResult} User, loading state, and error
  * * value: Object value; `undefined` if query is currently being fetched, or an error occurred
  * * loading: `true` while fetching the query; `false` if the query was fetched successfully or an error occurred
@@ -36,5 +38,5 @@ export function useObjectValue<Value = unknown>(
         []
     );
 
-    return useListen(query ?? undefined, onChange, isQueryEqual, LoadingState);
+    return useListen(query ?? undefined, onChange, isQueryEqual, options?.initialValue ?? LoadingState);
 }

src/firestore/useCollectionData.ts

@@ -10,9 +10,10 @@ export type UseCollectionDataResult<Value extends DocumentData = DocumentData> =
 /**
  * Options to configure the subscription
  */
-export interface UseCollectionDataOptions {
+export interface UseCollectionDataOptions<Value extends DocumentData = DocumentData> {
     snapshotListenOptions?: SnapshotListenOptions;
     snapshotOptions?: SnapshotOptions;
+    initialValue?: Value[];
 }
 
 /**
@@ -21,14 +22,15 @@ export interface UseCollectionDataOptions {
  * @template Value Type of the collection data
  * @param {Query<Value> | undefined | null} query Firestore query that will be subscribed to
  * @param {?UseCollectionDataOptions} options Options to configure the subscription
+ * * `initialValue`: Value that is returned while the query is being fetched.
  * @returns {UseCollectionDataResult<Value>} Query data, loading state, and error
  * * value: Query data; `undefined` if query is currently being fetched, or an error occurred
  * * loading: `true` while fetching the query; `false` if the query was fetched successfully or an error occurred
  * * error: `undefined` if no error occurred
  */
 export function useCollectionData<Value extends DocumentData = DocumentData>(
     query: Query<Value> | undefined | null,
-    options?: UseCollectionDataOptions
+    options?: UseCollectionDataOptions<Value>
 ): UseCollectionDataResult<Value> {
     const { snapshotListenOptions = {}, snapshotOptions = {} } = options ?? {};
 
@@ -41,5 +43,5 @@ export function useCollectionData<Value extends DocumentData = DocumentData>(
         []
     );
 
-    return useListen(query ?? undefined, onChange, isQueryEqual, LoadingState);
+    return useListen(query ?? undefined, onChange, isQueryEqual, options?.initialValue ?? LoadingState);
 }

src/firestore/useDocumentData.ts

@@ -17,9 +17,10 @@ export type UseDocumentDataResult<Value extends DocumentData = DocumentData> = V
 /**
  * Options to configure the subscription
  */
-export interface UseDocumentDataOptions {
+export interface UseDocumentDataOptions<Value extends DocumentData = DocumentData> {
     snapshotListenOptions?: SnapshotListenOptions;
     snapshotOptions?: SnapshotOptions;
+    initialValue?: Value;
 }
 
 /**
@@ -28,14 +29,15 @@ export interface UseDocumentDataOptions {
  * @template Value Type of the document data
  * @param {DocumentReference<Value> | undefined | null} reference Firestore DocumentReference that will be subscribed to
  * @param {?UseDocumentDataOptions} options Options to configure the subscription
+ * * `initialValue`: Value that is returned while the document is being fetched.
  * @returns {UseDocumentDataResult<Value>} Document data, loading state, and error
  * * value: Document data; `undefined` if document does not exist, is currently being fetched, or an error occurred
  * * loading: `true` while fetching the document; `false` if the document was fetched successfully or an error occurred
  * * error: `undefined` if no error occurred
  */
 export function useDocumentData<Value extends DocumentData = DocumentData>(
     reference: DocumentReference<Value> | undefined | null,
-    options?: UseDocumentDataOptions
+    options?: UseDocumentDataOptions<Value>
 ): UseDocumentDataResult<Value> {
     const { snapshotListenOptions = {}, snapshotOptions } = options ?? {};
 
@@ -48,5 +50,5 @@ export function useDocumentData<Value extends DocumentData = DocumentData>(
         []
     );
 
-    return useListen(reference ?? undefined, onChange, isDocRefEqual, LoadingState);
+    return useListen(reference ?? undefined, onChange, isDocRefEqual, options?.initialValue ?? LoadingState);
 }