react-query-firebase 1.3.0 → 1.3.2

package/dist/src/context/FirebaseContextProvider.d.ts

@@ -1,6 +1,7 @@
 import React, { PropsWithChildren } from "react";
 import { ConsentSettings } from "firebase/analytics";
 import { RemoteConfigSettings } from "firebase/remote-config";
+import { FirestoreSettings } from "firebase/firestore";
 import { FirebaseOptions } from "firebase/app";
 /**
  * @inline
@@ -71,6 +72,13 @@ export type FirebaseContextProviderProps = PropsWithChildren & {
      *              }
      */
     consentSettings?: ConsentSettings;
+    /**
+     * Specifies custom configurations for your Cloud Firestore instance.
+     * You must set these before invoking any other methods.
+     * {@link https://firebase.google.com/docs/reference/js/firestore_.firestoresettings}
+     * @defaultValue {}
+     */
+    firestoreSettings?: FirestoreSettings;
     /**
      * Flag indicating whether Firebase Firestore should be enabled.
      * @defaultValue `true`

package/dist/src/context/FirebaseContextProvider.js

@@ -3,7 +3,7 @@ import { FirebaseContext } from "./FirebaseContext";
 import { connectAuthEmulator, getAuth } from "firebase/auth";
 import { getAnalytics, setAnalyticsCollectionEnabled, setConsent } from "firebase/analytics";
 import { getRemoteConfig } from "firebase/remote-config";
-import { connectFirestoreEmulator, getFirestore } from "firebase/firestore";
+import { connectFirestoreEmulator, initializeFirestore } from "firebase/firestore";
 import { initializeApp } from "firebase/app";
 /**
  * FirebaseContextProvider component configures and provides Firebase services to its children.
@@ -28,7 +28,7 @@ import { initializeApp } from "firebase/app";
  * };
  * ```
  */
-export const FirebaseContextProvider = ({ emulators, options, children, authEnabled = true, firestoreEnabled = true, analyticsEnabled = true, consentSettings = {}, remoteConfigEnabled = true, remoteConfigSettings, remoteConfigDefaults = {} }) => {
+export const FirebaseContextProvider = ({ emulators, options, children, authEnabled = true, firestoreEnabled = true, analyticsEnabled = true, consentSettings = {}, remoteConfigEnabled = true, remoteConfigSettings, remoteConfigDefaults = {}, firestoreSettings }) => {
     const firebase = useMemo(() => {
         return initializeApp(options);
     }, [options]);
@@ -44,39 +44,53 @@ export const FirebaseContextProvider = ({ emulators, options, children, authEnab
             ...consentSettings
         });
     }, [consentSettings]);
-    const contextValue = useMemo(() => {
-        const value = {};
+    const firestore = useMemo(() => {
         if (firestoreEnabled) {
-            const firestore = getFirestore(firebase);
+            const localFirestore = initializeFirestore(firebase, firestoreSettings || {});
             if (emulators?.firestore?.host && emulators?.firestore?.port) {
-                connectFirestoreEmulator(firestore, emulators.firestore.host, emulators.firestore.port);
+                connectFirestoreEmulator(localFirestore, emulators.firestore.host, emulators.firestore.port);
             }
-            value.firestore = firestore;
+            return localFirestore;
         }
+        return null;
+    }, [firestoreSettings, emulators?.firestore, firestoreEnabled]);
+    const auth = useMemo(() => {
         if (authEnabled) {
-            const auth = getAuth(firebase);
+            const localAuth = getAuth(firebase);
             if (emulators?.auth?.host) {
-                connectAuthEmulator(auth, emulators?.auth?.host, {
+                connectAuthEmulator(localAuth, emulators?.auth?.host, {
                     disableWarnings: true
                 });
             }
-            value.auth = auth;
+            return localAuth;
         }
+        return null;
+    }, [emulators?.auth, authEnabled]);
+    const analytics = useMemo(() => {
         if (analyticsEnabled && options.measurementId && typeof window !== "undefined") {
-            const analytics = getAnalytics(firebase);
-            value.analytics = analytics;
+            return getAnalytics(firebase);
         }
+        return null;
+    }, [analyticsEnabled, options.measurementId]);
+    const remoteConfig = useMemo(() => {
         if (remoteConfigEnabled && typeof window !== "undefined") {
-            const remoteConfig = getRemoteConfig(firebase);
+            const localRemoteConfig = getRemoteConfig(firebase);
             if (remoteConfigSettings) {
-                remoteConfig.settings.fetchTimeoutMillis = remoteConfigSettings.fetchTimeoutMillis;
-                remoteConfig.settings.minimumFetchIntervalMillis = remoteConfigSettings.minimumFetchIntervalMillis;
-                remoteConfig.defaultConfig = remoteConfigDefaults;
+                localRemoteConfig.settings.fetchTimeoutMillis = remoteConfigSettings.fetchTimeoutMillis;
+                localRemoteConfig.settings.minimumFetchIntervalMillis = remoteConfigSettings.minimumFetchIntervalMillis;
+                localRemoteConfig.defaultConfig = remoteConfigDefaults;
             }
-            value.remoteConfig = remoteConfig;
+            return localRemoteConfig;
         }
-        return { firebase, ...value };
-    }, [firebase]);
+        return null;
+    }, [remoteConfigEnabled]);
+    const contextValue = useMemo(() => ({
+        firebase,
+        auth,
+        analytics,
+        firestore,
+        remoteConfig
+    }), [firebase, auth, analytics, firestore, remoteConfig]);
     useEffect(() => {
         if (contextValue.analytics) {
             setAnalyticsCollectionEnabled(contextValue.analytics, consentSettings?.analytics_storage === "granted");

package/dist/src/firestore/useGetRealtimeDocData.d.ts

@@ -11,7 +11,7 @@ export type UseGetRealtimeDocDataOptions<AppModelType, DbModelType extends Docum
     /**
      * A reference to a collection.
      */
-    reference: CollectionReference<AppModelType, DbModelType> | DocumentReference<AppModelType, DbModelType>;
+    reference?: CollectionReference<AppModelType, DbModelType> | DocumentReference<AppModelType, DbModelType>;
     /**
      * Additional path segments that will be applied relative
      * to the first argument.
@@ -21,7 +21,16 @@ export type UseGetRealtimeDocDataOptions<AppModelType, DbModelType extends Docum
      * A callback to be called if the listen fails or is
      * cancelled. No further callbacks will occur.
      */
-    onError: (error: FirebaseError) => unknown;
+    onError?: (error: FirebaseError) => unknown;
+};
+/**
+ * @inline
+ */
+export type UseGetRealtimeDocDataResult<AppModelType> = {
+    data: AppModelType | null;
+    isError: boolean;
+    error: FirebaseError | null;
+    isFetching: boolean;
 };
 /**
  * A hook to get realtime updates to a firestore document.
@@ -30,19 +39,19 @@ export type UseGetRealtimeDocDataOptions<AppModelType, DbModelType extends Docum
  *
  * @param {UseGetRealtimeDocDataOptions<AppModelType, DbModelType>} options
  *
- * @returns {AppModelType | null}
+ * @returns {UseGetRealtimeDocDataResult<AppModelType>}
  *
  * @example
  * ```jsx
  * const firebaseConfig = {};
  * export const MyComponent = () => {
- *  const doc = useGetRealtimeDocData('collection/documentId');
+ *  const result = useGetRealtimeDocData('collection/documentId');
  *  return (
  *      <div>
- *          {JSON.stringify(doc)}
+ *          {JSON.stringify(result)}
  *      </div>
  *  );
  * };
  * ```
  */
-export declare const useGetRealtimeDocData: <AppModelType, DbModelType extends DocumentData = DocumentData>({ path, pathSegments, reference, onError }: UseGetRealtimeDocDataOptions<AppModelType, DbModelType>) => AppModelType | null;
+export declare const useGetRealtimeDocData: <AppModelType, DbModelType extends DocumentData = DocumentData>({ path, pathSegments, reference, onError }: UseGetRealtimeDocDataOptions<AppModelType, DbModelType>) => UseGetRealtimeDocDataResult<AppModelType>;

package/dist/src/firestore/useGetRealtimeDocData.js

@@ -1,5 +1,5 @@
 import { onSnapshot } from "firebase/firestore";
-import { useEffect, useState } from "react";
+import { useEffect, useMemo, useState } from "react";
 import { useDocReference } from "./useDocReference";
 /**
  * A hook to get realtime updates to a firestore document.
@@ -8,16 +8,16 @@ import { useDocReference } from "./useDocReference";
  *
  * @param {UseGetRealtimeDocDataOptions<AppModelType, DbModelType>} options
  *
- * @returns {AppModelType | null}
+ * @returns {UseGetRealtimeDocDataResult<AppModelType>}
  *
  * @example
  * ```jsx
  * const firebaseConfig = {};
  * export const MyComponent = () => {
- *  const doc = useGetRealtimeDocData('collection/documentId');
+ *  const result = useGetRealtimeDocData('collection/documentId');
  *  return (
  *      <div>
- *          {JSON.stringify(doc)}
+ *          {JSON.stringify(result)}
  *      </div>
  *  );
  * };
@@ -26,16 +26,31 @@ import { useDocReference } from "./useDocReference";
 export const useGetRealtimeDocData = ({ path, pathSegments, reference, onError }) => {
     const ref = useDocReference({ path, reference, pathSegments });
     const [doc, setDoc] = useState(null);
+    const [isError, setIsError] = useState(false);
+    const [isFetching, setIsFetching] = useState(true);
+    const [error, setError] = useState(null);
     useEffect(() => {
         const unsubscribe = ref
             ? onSnapshot(ref, {
                 next: async (snapshot) => {
+                    setIsFetching(false);
                     setDoc(snapshot.data() || null);
+                    setError(null);
+                    setIsError(false);
                 },
-                error: onError
+                error: (e) => {
+                    setIsError(true);
+                    setError(e);
+                    onError?.(e);
+                }
             })
             : () => { };
         return () => unsubscribe();
-    }, [ref, doc]);
-    return doc;
+    }, [ref, doc, isError, onError, isFetching, error]);
+    return useMemo(() => ({
+        data: doc,
+        isError,
+        isFetching,
+        error
+    }), [doc, isError, error]);
 };

package/package.json

@@ -60,5 +60,5 @@
         "docs:build": "vitepress build docs",
         "docs:preview": "vitepress preview docs"
     },
-    "version": "1.3.0"
+    "version": "1.3.2"
 }

package/src/context/FirebaseContextProvider.tsx

@@ -3,7 +3,7 @@ import { FirebaseContext } from "./FirebaseContext";
 import { connectAuthEmulator, getAuth } from "firebase/auth";
 import { ConsentSettings, getAnalytics, setAnalyticsCollectionEnabled, setConsent } from "firebase/analytics";
 import { getRemoteConfig, RemoteConfigSettings } from "firebase/remote-config";
-import { connectFirestoreEmulator, getFirestore } from "firebase/firestore";
+import { connectFirestoreEmulator, FirestoreSettings, initializeFirestore } from "firebase/firestore";
 import { FirebaseOptions, initializeApp } from "firebase/app";
 
 /**
@@ -78,6 +78,13 @@ export type FirebaseContextProviderProps = PropsWithChildren & {
      *              }
      */
     consentSettings?: ConsentSettings;
+    /**
+     * Specifies custom configurations for your Cloud Firestore instance.
+     * You must set these before invoking any other methods.
+     * {@link https://firebase.google.com/docs/reference/js/firestore_.firestoresettings}
+     * @defaultValue {}
+     */
+    firestoreSettings?: FirestoreSettings;
     /**
      * Flag indicating whether Firebase Firestore should be enabled.
      * @defaultValue `true`
@@ -132,7 +139,8 @@ export const FirebaseContextProvider: React.FC<FirebaseContextProviderProps> = (
     consentSettings = {},
     remoteConfigEnabled = true,
     remoteConfigSettings,
-    remoteConfigDefaults = {}
+    remoteConfigDefaults = {},
+    firestoreSettings
 }) => {
     const firebase = useMemo(() => {
         return initializeApp(options);
@@ -151,46 +159,63 @@ export const FirebaseContextProvider: React.FC<FirebaseContextProviderProps> = (
         });
     }, [consentSettings]);
 
-    const contextValue = useMemo(() => {
-        const value: Partial<React.ContextType<typeof FirebaseContext>> = {};
-
+    const firestore = useMemo(() => {
         if (firestoreEnabled) {
-            const firestore = getFirestore(firebase);
+            const localFirestore = initializeFirestore(firebase, firestoreSettings || {});
 
             if (emulators?.firestore?.host && emulators?.firestore?.port) {
-                connectFirestoreEmulator(firestore, emulators.firestore.host, emulators.firestore.port);
+                connectFirestoreEmulator(localFirestore, emulators.firestore.host, emulators.firestore.port);
             }
 
-            value.firestore = firestore;
+            return localFirestore;
         }
 
+        return null;
+    }, [firestoreSettings, emulators?.firestore, firestoreEnabled]);
+
+    const auth = useMemo(() => {
         if (authEnabled) {
-            const auth = getAuth(firebase);
+            const localAuth = getAuth(firebase);
             if (emulators?.auth?.host) {
-                connectAuthEmulator(auth, emulators?.auth?.host, {
+                connectAuthEmulator(localAuth, emulators?.auth?.host, {
                     disableWarnings: true
                 });
             }
-            value.auth = auth;
+            return localAuth;
         }
+        return null;
+    }, [emulators?.auth, authEnabled]);
 
+    const analytics = useMemo(() => {
         if (analyticsEnabled && options.measurementId && typeof window !== "undefined") {
-            const analytics = getAnalytics(firebase);
-            value.analytics = analytics;
+            return getAnalytics(firebase);
         }
+        return null;
+    }, [analyticsEnabled, options.measurementId]);
 
+    const remoteConfig = useMemo(() => {
         if (remoteConfigEnabled && typeof window !== "undefined") {
-            const remoteConfig = getRemoteConfig(firebase);
+            const localRemoteConfig = getRemoteConfig(firebase);
             if (remoteConfigSettings) {
-                remoteConfig.settings.fetchTimeoutMillis = remoteConfigSettings.fetchTimeoutMillis;
-                remoteConfig.settings.minimumFetchIntervalMillis = remoteConfigSettings.minimumFetchIntervalMillis;
-                remoteConfig.defaultConfig = remoteConfigDefaults;
+                localRemoteConfig.settings.fetchTimeoutMillis = remoteConfigSettings.fetchTimeoutMillis;
+                localRemoteConfig.settings.minimumFetchIntervalMillis = remoteConfigSettings.minimumFetchIntervalMillis;
+                localRemoteConfig.defaultConfig = remoteConfigDefaults;
             }
-            value.remoteConfig = remoteConfig;
+            return localRemoteConfig;
         }
-
-        return { firebase, ...value };
-    }, [firebase]);
+        return null;
+    }, [remoteConfigEnabled]);
+
+    const contextValue = useMemo(
+        () => ({
+            firebase,
+            auth,
+            analytics,
+            firestore,
+            remoteConfig
+        }),
+        [firebase, auth, analytics, firestore, remoteConfig]
+    );
 
     useEffect(() => {
         if (contextValue.analytics) {

package/src/firestore/useGetRealtimeDocData.ts

@@ -1,6 +1,6 @@
 import { CollectionReference, DocumentData, DocumentReference, onSnapshot } from "firebase/firestore";
 
-import { useEffect, useState } from "react";
+import { useEffect, useMemo, useState } from "react";
 import { FirebaseError } from "firebase/app";
 import { useDocReference } from "./useDocReference";
 
@@ -15,7 +15,7 @@ export type UseGetRealtimeDocDataOptions<AppModelType, DbModelType extends Docum
     /**
      * A reference to a collection.
      */
-    reference: CollectionReference<AppModelType, DbModelType> | DocumentReference<AppModelType, DbModelType>;
+    reference?: CollectionReference<AppModelType, DbModelType> | DocumentReference<AppModelType, DbModelType>;
     /**
      * Additional path segments that will be applied relative
      * to the first argument.
@@ -25,7 +25,17 @@ export type UseGetRealtimeDocDataOptions<AppModelType, DbModelType extends Docum
      * A callback to be called if the listen fails or is
      * cancelled. No further callbacks will occur.
      */
-    onError: (error: FirebaseError) => unknown;
+    onError?: (error: FirebaseError) => unknown;
+};
+
+/**
+ * @inline
+ */
+export type UseGetRealtimeDocDataResult<AppModelType> = {
+    data: AppModelType | null;
+    isError: boolean;
+    error: FirebaseError | null;
+    isFetching: boolean;
 };
 
 /**
@@ -35,16 +45,16 @@ export type UseGetRealtimeDocDataOptions<AppModelType, DbModelType extends Docum
  *
  * @param {UseGetRealtimeDocDataOptions<AppModelType, DbModelType>} options
  *
- * @returns {AppModelType | null}
+ * @returns {UseGetRealtimeDocDataResult<AppModelType>}
  *
  * @example
  * ```jsx
  * const firebaseConfig = {};
  * export const MyComponent = () => {
- *  const doc = useGetRealtimeDocData('collection/documentId');
+ *  const result = useGetRealtimeDocData('collection/documentId');
  *  return (
  *      <div>
- *          {JSON.stringify(doc)}
+ *          {JSON.stringify(result)}
  *      </div>
  *  );
  * };
@@ -55,22 +65,40 @@ export const useGetRealtimeDocData = <AppModelType, DbModelType extends Document
     pathSegments,
     reference,
     onError
-}: UseGetRealtimeDocDataOptions<AppModelType, DbModelType>): AppModelType | null => {
+}: UseGetRealtimeDocDataOptions<AppModelType, DbModelType>): UseGetRealtimeDocDataResult<AppModelType> => {
     const ref = useDocReference({ path, reference, pathSegments });
     const [doc, setDoc] = useState<AppModelType | null>(null);
+    const [isError, setIsError] = useState(false);
+    const [isFetching, setIsFetching] = useState(true);
+    const [error, setError] = useState<FirebaseError | null>(null);
 
     useEffect(() => {
         const unsubscribe = ref
             ? onSnapshot(ref, {
                   next: async (snapshot) => {
+                      setIsFetching(false);
                       setDoc(snapshot.data() || null);
+                      setError(null);
+                      setIsError(false);
                   },
-                  error: onError
+                  error: (e) => {
+                      setIsError(true);
+                      setError(e);
+                      onError?.(e);
+                  }
               })
             : () => {};
 
         return () => unsubscribe();
-    }, [ref, doc]);
+    }, [ref, doc, isError, onError, isFetching, error]);
 
-    return doc;
+    return useMemo(
+        () => ({
+            data: doc,
+            isError,
+            isFetching,
+            error
+        }),
+        [doc, isError, error]
+    );
 };