react-query-firebase 2.0.0-rc5 → 2.0.0-rc7

package/web/auth/useUpdateProfileMutation.js

@@ -0,0 +1,17 @@
+import { useMutation } from "@tanstack/react-query";
+import { updateProfile } from "firebase/auth";
+import { CREATE_USER_WITH_EMAIL_AND_PASSWORD_MUTATION_KEY } from "./mutation-keys";
+/**
+ * Custom hook to manage the mutation for updating a user's profile.
+ * Utilizes Firebase for updating the user's display name.
+ *
+ * @param {Omit<UseMutationOptions<void, FirebaseError, UseUpdateProfileMutationVariables, TContext>, "mutationKey" | "mutationFn">} options - Configuration options for the mutation, excluding mutationKey and mutationFn.
+ * @returns {UseMutationResult<void, FirebaseError, UseUpdateProfileMutationVariables, TContext>} The result of the mutation operation including statuses, data, and error information.
+ */
+export const useUpdateProfileMutation = (options = {}) => {
+    return useMutation({
+        ...options,
+        mutationFn: async ({ displayName, user }) => await updateProfile(user, { displayName }),
+        mutationKey: CREATE_USER_WITH_EMAIL_AND_PASSWORD_MUTATION_KEY
+    });
+};

package/web/auth/useUpdateProfileMutation.ts

@@ -0,0 +1,30 @@
+import { useMutation, UseMutationOptions } from "@tanstack/react-query";
+import { updateProfile, User } from "firebase/auth";
+import { FirebaseError } from "firebase/app";
+import { CREATE_USER_WITH_EMAIL_AND_PASSWORD_MUTATION_KEY } from "./mutation-keys";
+
+export type UseUpdateProfileMutationVariables = {
+    displayName?: string;
+    user: User;
+};
+
+/**
+ * Custom hook to manage the mutation for updating a user's profile.
+ * Utilizes Firebase for updating the user's display name.
+ *
+ * @param {Omit<UseMutationOptions<void, FirebaseError, UseUpdateProfileMutationVariables, TContext>, "mutationKey" | "mutationFn">} options - Configuration options for the mutation, excluding mutationKey and mutationFn.
+ * @returns {UseMutationResult<void, FirebaseError, UseUpdateProfileMutationVariables, TContext>} The result of the mutation operation including statuses, data, and error information.
+ */
+export const useUpdateProfileMutation = <TContext = unknown>(
+    options: Omit<
+        UseMutationOptions<void, FirebaseError, UseUpdateProfileMutationVariables, TContext>,
+        "mutationKey" | "mutationFn"
+    > = {}
+) => {
+    return useMutation({
+        ...options,
+        mutationFn: async ({ displayName, user }: UseUpdateProfileMutationVariables) =>
+            await updateProfile(user, { displayName }),
+        mutationKey: CREATE_USER_WITH_EMAIL_AND_PASSWORD_MUTATION_KEY
+    });
+};

package/web/context/FirebaseContext.d.ts

@@ -0,0 +1,19 @@
+import { Auth } from "firebase/auth";
+import { Analytics } from "firebase/analytics";
+import { Firestore } from "firebase/firestore";
+import { FirebaseApp } from "firebase/app";
+import { RemoteConfig } from "firebase/remote-config";
+type FirebaseContextValue = {
+    auth: Auth;
+    analytics: Analytics;
+    firebase: FirebaseApp;
+    remoteConfig: RemoteConfig;
+    firestore: Firestore;
+};
+/**
+ * FirebaseContext is a shared context across children that provides access to firebase features
+ *
+ * @internal
+ */
+export declare const FirebaseContext: import("react").Context<FirebaseContextValue>;
+export {};

package/web/context/FirebaseContext.js

@@ -0,0 +1,8 @@
+"use client";
+import { createContext } from "react";
+/**
+ * FirebaseContext is a shared context across children that provides access to firebase features
+ *
+ * @internal
+ */
+export const FirebaseContext = createContext({});

package/web/context/FirebaseContext.ts

@@ -0,0 +1,25 @@
+"use client";
+
+import { createContext } from "react";
+
+import { Auth } from "firebase/auth";
+import { Analytics } from "firebase/analytics";
+import { Firestore } from "firebase/firestore";
+import { FirebaseApp } from "firebase/app";
+import { RemoteConfig } from "firebase/remote-config";
+
+type FirebaseContextValue = {
+    auth: Auth;
+    analytics: Analytics;
+    firebase: FirebaseApp;
+    remoteConfig: RemoteConfig;
+    firestore: Firestore;
+};
+
+/**
+ * FirebaseContext is a shared context across children that provides access to firebase features
+ *
+ * @internal
+ */
+
+export const FirebaseContext = createContext<FirebaseContextValue>({} as FirebaseContextValue);

package/web/context/FirebaseContextProvider.d.ts

@@ -0,0 +1,127 @@
+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
+ */
+export type FirebaseContextProviderFirestoreEmulatorConfig = {
+    /**
+     * Host to connect to Firebase Firestore Emulator
+     */
+    host: string;
+    /**
+     * Port to connect to Firebase Firestore Emulator
+     */
+    port: number;
+};
+/**
+ * @inline
+ */
+export type FirebaseContextProviderAuthEmulatorConfig = {
+    /**
+     * Host to connect to Firebase Auth Emulator
+     */
+    host: string;
+};
+/**
+ * @inline
+ */
+export type FirebaseContextProviderEmulators = {
+    /**
+     * Defines configuration for Firebase Firestore emulator. Optional.
+     */
+    firestore?: FirebaseContextProviderFirestoreEmulatorConfig;
+    /**
+     * Defines configuration for Firebase Auth emulator. Optional
+     */
+    auth?: FirebaseContextProviderAuthEmulatorConfig;
+};
+/**
+ * @inline
+ */
+export type FirebaseContextProviderProps = PropsWithChildren & {
+    /**
+     * Defines configuration for firebase emulators
+     */
+    emulators?: FirebaseContextProviderEmulators;
+    /**
+     * Configuration options for Firebase initialization. {@link https://firebase.google.com/docs/web/setup#config-object | Learn about the Firebase config object}
+     */
+    options: FirebaseOptions;
+    /**
+     * Flag indicating whether Firebase Auth should be enabled.
+     */
+    authEnabled?: boolean;
+    /**
+     * Flag indicating whether Firebase Analytics should be enabled.
+     * @defaultValue `true`
+     */
+    analyticsEnabled?: boolean;
+    /**
+     * Default user consent settings. Make sure to either use a consent platform or install custom consent form for a certain regions.
+     * @defaultValue {
+     *                  ad_personalization: "denied",
+     *                  ad_storage: "denied",
+     *                  ad_user_data: "denied",
+     *                  analytics_storage: "denied",
+     *                  functionality_storage: "denied",
+     *                  personalization_storage: "denied",
+     *                  security_storage: "denied"
+     *              }
+     */
+    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`
+     */
+    firestoreEnabled?: boolean;
+    /**
+     * Configuration options for Firebase Remote Config Settings. {@link https://firebase.google.com/docs/reference/js/remote-config.remoteconfigsettings | Learn about the Firebase Remote COnfig Settings object}
+     * @defaultValue `true`
+     */
+    remoteConfigSettings?: RemoteConfigSettings;
+    /**
+     * Configuration options for Firebase Remote Config Defaults.
+     */
+    remoteConfigDefaults?: {
+        [key: string]: string | number | boolean;
+    };
+    /**
+     * Flag indicating whether Firebase Remote Config should be enabled.
+     * @defaultValue `true`
+     */
+    remoteConfigEnabled?: boolean;
+};
+/**
+ * FirebaseContextProvider component configures and provides Firebase services to its children.
+ * Initializes Firebase app and enables optional Firebase services such as Firestore, Auth, Analytics,
+ * and Remote Config based on the provided configuration and parameters.
+ *
+ * @group Component
+ *
+ * @param {FirebaseContextProviderProps} props
+ *
+ * @returns {FirebaseContextProvider<FirebaseContextProviderProps>}
+ *
+ * @example
+ * ```jsx
+ * const firebaseConfig = {};
+ * export const App = () => {
+ *  return (
+ *      <FirebaseContextProvider options={firebaseConfig}>
+ *          <ChildComponent />
+ *      </FirebaseContextProvider>
+ *  );
+ * };
+ * ```
+ */
+export declare const FirebaseContextProvider: React.FC<FirebaseContextProviderProps>;

package/web/context/FirebaseContextProvider.js

@@ -0,0 +1,100 @@
+import React, { useEffect, useMemo } from "react";
+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, initializeFirestore } from "firebase/firestore";
+import { initializeApp } from "firebase/app";
+/**
+ * FirebaseContextProvider component configures and provides Firebase services to its children.
+ * Initializes Firebase app and enables optional Firebase services such as Firestore, Auth, Analytics,
+ * and Remote Config based on the provided configuration and parameters.
+ *
+ * @group Component
+ *
+ * @param {FirebaseContextProviderProps} props
+ *
+ * @returns {FirebaseContextProvider<FirebaseContextProviderProps>}
+ *
+ * @example
+ * ```jsx
+ * const firebaseConfig = {};
+ * export const App = () => {
+ *  return (
+ *      <FirebaseContextProvider options={firebaseConfig}>
+ *          <ChildComponent />
+ *      </FirebaseContextProvider>
+ *  );
+ * };
+ * ```
+ */
+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]);
+    useEffect(() => {
+        setConsent({
+            ad_personalization: "denied",
+            ad_storage: "denied",
+            ad_user_data: "denied",
+            analytics_storage: "denied",
+            functionality_storage: "denied",
+            personalization_storage: "denied",
+            security_storage: "denied",
+            ...consentSettings
+        });
+    }, [consentSettings]);
+    const firestore = useMemo(() => {
+        if (firestoreEnabled) {
+            const localFirestore = initializeFirestore(firebase, firestoreSettings || {});
+            if (emulators?.firestore?.host && emulators?.firestore?.port) {
+                connectFirestoreEmulator(localFirestore, emulators.firestore.host, emulators.firestore.port);
+            }
+            return localFirestore;
+        }
+        return null;
+    }, [firestoreSettings, emulators?.firestore, firestoreEnabled]);
+    const auth = useMemo(() => {
+        if (authEnabled) {
+            const localAuth = getAuth(firebase);
+            if (emulators?.auth?.host) {
+                connectAuthEmulator(localAuth, emulators?.auth?.host, {
+                    disableWarnings: true
+                });
+            }
+            return localAuth;
+        }
+        return null;
+    }, [emulators?.auth, authEnabled]);
+    const analytics = useMemo(() => {
+        if (analyticsEnabled && options.measurementId && typeof window !== "undefined") {
+            return getAnalytics(firebase);
+        }
+        return null;
+    }, [analyticsEnabled, options.measurementId]);
+    const remoteConfig = useMemo(() => {
+        if (remoteConfigEnabled && typeof window !== "undefined") {
+            const localRemoteConfig = getRemoteConfig(firebase);
+            if (remoteConfigSettings) {
+                localRemoteConfig.settings.fetchTimeoutMillis = remoteConfigSettings.fetchTimeoutMillis;
+                localRemoteConfig.settings.minimumFetchIntervalMillis = remoteConfigSettings.minimumFetchIntervalMillis;
+                localRemoteConfig.defaultConfig = remoteConfigDefaults;
+            }
+            return localRemoteConfig;
+        }
+        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");
+        }
+    }, [consentSettings]);
+    return (React.createElement(FirebaseContext.Provider, { value: contextValue }, children));
+};

package/web/context/FirebaseContextProvider.tsx

@@ -0,0 +1,231 @@
+import React, { PropsWithChildren, useEffect, useMemo } from "react";
+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, FirestoreSettings, initializeFirestore } from "firebase/firestore";
+import { FirebaseOptions, initializeApp } from "firebase/app";
+
+/**
+ * @inline
+ */
+export type FirebaseContextProviderFirestoreEmulatorConfig = {
+    /**
+     * Host to connect to Firebase Firestore Emulator
+     */
+    host: string;
+    /**
+     * Port to connect to Firebase Firestore Emulator
+     */
+    port: number;
+};
+
+/**
+ * @inline
+ */
+export type FirebaseContextProviderAuthEmulatorConfig = {
+    /**
+     * Host to connect to Firebase Auth Emulator
+     */
+    host: string;
+};
+
+/**
+ * @inline
+ */
+export type FirebaseContextProviderEmulators = {
+    /**
+     * Defines configuration for Firebase Firestore emulator. Optional.
+     */
+    firestore?: FirebaseContextProviderFirestoreEmulatorConfig;
+    /**
+     * Defines configuration for Firebase Auth emulator. Optional
+     */
+    auth?: FirebaseContextProviderAuthEmulatorConfig;
+};
+
+/**
+ * @inline
+ */
+export type FirebaseContextProviderProps = PropsWithChildren & {
+    /**
+     * Defines configuration for firebase emulators
+     */
+    emulators?: FirebaseContextProviderEmulators;
+    /**
+     * Configuration options for Firebase initialization. {@link https://firebase.google.com/docs/web/setup#config-object | Learn about the Firebase config object}
+     */
+    options: FirebaseOptions;
+    /**
+     * Flag indicating whether Firebase Auth should be enabled.
+     */
+    authEnabled?: boolean;
+    /**
+     * Flag indicating whether Firebase Analytics should be enabled.
+     * @defaultValue `true`
+     */
+    analyticsEnabled?: boolean;
+    /**
+     * Default user consent settings. Make sure to either use a consent platform or install custom consent form for a certain regions.
+     * @defaultValue {
+     *                  ad_personalization: "denied",
+     *                  ad_storage: "denied",
+     *                  ad_user_data: "denied",
+     *                  analytics_storage: "denied",
+     *                  functionality_storage: "denied",
+     *                  personalization_storage: "denied",
+     *                  security_storage: "denied"
+     *              }
+     */
+    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`
+     */
+    firestoreEnabled?: boolean;
+    /**
+     * Configuration options for Firebase Remote Config Settings. {@link https://firebase.google.com/docs/reference/js/remote-config.remoteconfigsettings | Learn about the Firebase Remote COnfig Settings object}
+     * @defaultValue `true`
+     */
+    remoteConfigSettings?: RemoteConfigSettings;
+    /**
+     * Configuration options for Firebase Remote Config Defaults.
+     */
+    remoteConfigDefaults?: { [key: string]: string | number | boolean };
+    /**
+     * Flag indicating whether Firebase Remote Config should be enabled.
+     * @defaultValue `true`
+     */
+    remoteConfigEnabled?: boolean;
+};
+
+/**
+ * FirebaseContextProvider component configures and provides Firebase services to its children.
+ * Initializes Firebase app and enables optional Firebase services such as Firestore, Auth, Analytics,
+ * and Remote Config based on the provided configuration and parameters.
+ *
+ * @group Component
+ *
+ * @param {FirebaseContextProviderProps} props
+ *
+ * @returns {FirebaseContextProvider<FirebaseContextProviderProps>}
+ *
+ * @example
+ * ```jsx
+ * const firebaseConfig = {};
+ * export const App = () => {
+ *  return (
+ *      <FirebaseContextProvider options={firebaseConfig}>
+ *          <ChildComponent />
+ *      </FirebaseContextProvider>
+ *  );
+ * };
+ * ```
+ */
+export const FirebaseContextProvider: React.FC<FirebaseContextProviderProps> = ({
+    emulators,
+    options,
+    children,
+    authEnabled = true,
+    firestoreEnabled = true,
+    analyticsEnabled = true,
+    consentSettings = {},
+    remoteConfigEnabled = true,
+    remoteConfigSettings,
+    remoteConfigDefaults = {},
+    firestoreSettings
+}) => {
+    const firebase = useMemo(() => {
+        return initializeApp(options);
+    }, [options]);
+
+    useEffect(() => {
+        setConsent({
+            ad_personalization: "denied",
+            ad_storage: "denied",
+            ad_user_data: "denied",
+            analytics_storage: "denied",
+            functionality_storage: "denied",
+            personalization_storage: "denied",
+            security_storage: "denied",
+            ...consentSettings
+        });
+    }, [consentSettings]);
+
+    const firestore = useMemo(() => {
+        if (firestoreEnabled) {
+            const localFirestore = initializeFirestore(firebase, firestoreSettings || {});
+
+            if (emulators?.firestore?.host && emulators?.firestore?.port) {
+                connectFirestoreEmulator(localFirestore, emulators.firestore.host, emulators.firestore.port);
+            }
+
+            return localFirestore;
+        }
+
+        return null;
+    }, [firestoreSettings, emulators?.firestore, firestoreEnabled]);
+
+    const auth = useMemo(() => {
+        if (authEnabled) {
+            const localAuth = getAuth(firebase);
+            if (emulators?.auth?.host) {
+                connectAuthEmulator(localAuth, emulators?.auth?.host, {
+                    disableWarnings: true
+                });
+            }
+            return localAuth;
+        }
+        return null;
+    }, [emulators?.auth, authEnabled]);
+
+    const analytics = useMemo(() => {
+        if (analyticsEnabled && options.measurementId && typeof window !== "undefined") {
+            return getAnalytics(firebase);
+        }
+        return null;
+    }, [analyticsEnabled, options.measurementId]);
+
+    const remoteConfig = useMemo(() => {
+        if (remoteConfigEnabled && typeof window !== "undefined") {
+            const localRemoteConfig = getRemoteConfig(firebase);
+            if (remoteConfigSettings) {
+                localRemoteConfig.settings.fetchTimeoutMillis = remoteConfigSettings.fetchTimeoutMillis;
+                localRemoteConfig.settings.minimumFetchIntervalMillis = remoteConfigSettings.minimumFetchIntervalMillis;
+                localRemoteConfig.defaultConfig = remoteConfigDefaults;
+            }
+            return localRemoteConfig;
+        }
+        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");
+        }
+    }, [consentSettings]);
+
+    return (
+        <FirebaseContext.Provider value={contextValue as React.ContextType<typeof FirebaseContext>}>
+            {children}
+        </FirebaseContext.Provider>
+    );
+};

package/web/context/index.d.ts

@@ -0,0 +1 @@
+export * from "./FirebaseContextProvider";

package/web/context/index.js

@@ -0,0 +1 @@
+export * from "./FirebaseContextProvider";

package/web/context/index.ts

@@ -0,0 +1 @@
+export * from "./FirebaseContextProvider";

package/web/firestore/index.d.ts

@@ -0,0 +1,16 @@
+export * from "./useFirestore";
+export * from "./useAddDocMutation";
+export * from "./useBatchWrite";
+export * from "./useCollectionReference";
+export * from "./useCompositeFilter";
+export * from "./useCountQuery";
+export * from "./useDeleteDocMutation";
+export * from "./useDocReference";
+export * from "./useDocReferences";
+export * from "./useGetDocData";
+export * from "./useInfiniteQuery";
+export * from "./useQuery";
+export * from "./useRunTransaction";
+export * from "./useSetDocMutation";
+export * from "./useUpdateDocMutation";
+export * from "./useGetRealtimeDocData";

package/web/firestore/index.js

@@ -0,0 +1,16 @@
+export * from "./useFirestore";
+export * from "./useAddDocMutation";
+export * from "./useBatchWrite";
+export * from "./useCollectionReference";
+export * from "./useCompositeFilter";
+export * from "./useCountQuery";
+export * from "./useDeleteDocMutation";
+export * from "./useDocReference";
+export * from "./useDocReferences";
+export * from "./useGetDocData";
+export * from "./useInfiniteQuery";
+export * from "./useQuery";
+export * from "./useRunTransaction";
+export * from "./useSetDocMutation";
+export * from "./useUpdateDocMutation";
+export * from "./useGetRealtimeDocData";

package/web/firestore/index.ts

@@ -0,0 +1,16 @@
+export * from "./useFirestore";
+export * from "./useAddDocMutation";
+export * from "./useBatchWrite";
+export * from "./useCollectionReference";
+export * from "./useCompositeFilter";
+export * from "./useCountQuery";
+export * from "./useDeleteDocMutation";
+export * from "./useDocReference";
+export * from "./useDocReferences";
+export * from "./useGetDocData";
+export * from "./useInfiniteQuery";
+export * from "./useQuery";
+export * from "./useRunTransaction";
+export * from "./useSetDocMutation";
+export * from "./useUpdateDocMutation";
+export * from "./useGetRealtimeDocData";

package/web/firestore/useAddDocMutation.d.ts

@@ -0,0 +1,23 @@
+import { UseMutationOptions } from "@tanstack/react-query";
+import { DocumentData, WithFieldValue, CollectionReference, FirestoreDataConverter } from "firebase/firestore";
+import { FirebaseError } from "firebase/app";
+export type UseAddDocMutationValues<AppModelType> = {
+    data: WithFieldValue<AppModelType>;
+};
+export type UseAddDocMutationOptions<AppModelType extends DocumentData = DocumentData, DbModelType extends DocumentData = DocumentData, TContext = unknown> = {
+    reference: CollectionReference<AppModelType, DbModelType>;
+    converter?: FirestoreDataConverter<AppModelType, DbModelType>;
+    options?: Omit<UseMutationOptions<AppModelType, FirebaseError, UseAddDocMutationValues<AppModelType>, TContext>, "mutationFn" | "mutationKey">;
+};
+/**
+ * Provides a mutation hook to add a document to a Firestore collection utilizing React Query's `useMutation`.
+ * It handles addition and optional conversion of the document data in Firestore.
+ *
+ * @param {Object} options - Options for the mutation hook
+ * @param {FirebaseFirestore.CollectionReference<AppModelType>} options.reference - Firestore collection reference where the document should be added.
+ * @param {FirebaseFirestore.FirestoreDataConverter<DbModelType>} [options.converter] - Optional data converter for reading and writing Firestore documents.
+ * @param {UseMutationOptions<AppModelType, Error, { data: DbModelType }, TContext>} [options.options={}] - Optional configuration for the mutation.
+ *
+ * @returns {UseMutationResult<AppModelType, Error, { data: DbModelType }, TContext>} The mutation hook result containing status, error, and data of the mutation process.
+ */
+export declare const useAddDocMutation: <AppModelType extends DocumentData = DocumentData, DbModelType extends DocumentData = DocumentData, TContext = unknown>({ reference, converter, options }: UseAddDocMutationOptions<AppModelType, DbModelType, TContext>) => import("@tanstack/react-query").UseMutationResult<AppModelType, FirebaseError, UseAddDocMutationValues<AppModelType>, TContext>;

package/web/firestore/useAddDocMutation.js

@@ -0,0 +1,26 @@
+import { useMutation } from "@tanstack/react-query";
+import { addDoc, getDoc } from "firebase/firestore";
+import { useMemo } from "react";
+/**
+ * Provides a mutation hook to add a document to a Firestore collection utilizing React Query's `useMutation`.
+ * It handles addition and optional conversion of the document data in Firestore.
+ *
+ * @param {Object} options - Options for the mutation hook
+ * @param {FirebaseFirestore.CollectionReference<AppModelType>} options.reference - Firestore collection reference where the document should be added.
+ * @param {FirebaseFirestore.FirestoreDataConverter<DbModelType>} [options.converter] - Optional data converter for reading and writing Firestore documents.
+ * @param {UseMutationOptions<AppModelType, Error, { data: DbModelType }, TContext>} [options.options={}] - Optional configuration for the mutation.
+ *
+ * @returns {UseMutationResult<AppModelType, Error, { data: DbModelType }, TContext>} The mutation hook result containing status, error, and data of the mutation process.
+ */
+export const useAddDocMutation = ({ reference, converter, options = {} }) => {
+    const mutationKey = useMemo(() => [reference.path], [reference.path]);
+    return useMutation({
+        ...options,
+        mutationFn: async ({ data }) => {
+            const docRef = await addDoc(reference, data);
+            const docSnap = await getDoc(converter ? docRef.withConverter(converter) : docRef);
+            return docSnap.data();
+        },
+        mutationKey
+    });
+};