react-query-firebase 2.4.1 → 2.6.0

package/package.json

@@ -74,5 +74,5 @@
         "docs:build": "vitepress build docs",
         "docs:preview": "vitepress preview docs"
     },
-    "version": "2.4.1"
+    "version": "2.6.0"
 }

package/react-native/auth/index.d.ts

@@ -11,3 +11,4 @@ export * from "./useIdToken";
 export * from "./useReauthenticateWitCredentialMutation";
 export * from "./useReauthenticateWitRedirectMutation";
 export * from "./useAuthStateReady";
+export * from "./useSignInAnonymouslyMutation";

package/react-native/auth/index.js

@@ -11,3 +11,4 @@ export * from "./useIdToken";
 export * from "./useReauthenticateWitCredentialMutation";
 export * from "./useReauthenticateWitRedirectMutation";
 export * from "./useAuthStateReady";
+export * from "./useSignInAnonymouslyMutation";

package/react-native/auth/index.ts

@@ -11,3 +11,4 @@ export * from "./useIdToken";
 export * from "./useReauthenticateWitCredentialMutation";
 export * from "./useReauthenticateWitRedirectMutation";
 export * from "./useAuthStateReady";
+export * from "./useSignInAnonymouslyMutation";

package/react-native/auth/mutation-keys.d.ts

@@ -1,5 +1,6 @@
 export declare const CREATE_USER_WITH_EMAIL_AND_PASSWORD_MUTATION_KEY: readonly ["FIREBASE", "AUTH", "CREATE_USER_WITH_EMAIL_AND_PASSWORD_MUTATION"];
 export declare const SEND_EMAIL_VERIFICATION_MUTATION_KEY: readonly ["FIREBASE", "AUTH", "SEND_EMAIL_VERIFICATION_MUTATION"];
+export declare const SIGN_IN_ANONYMOUSLY_MUTATION_KEY: readonly ["FIREBASE", "AUTH", "SIGN_IN_ANONYMOUSLY_MUTATION"];
 export declare const SIGN_IN_WITH_EMAIL_AND_PASSWORD_MUTATION_KEY: readonly ["FIREBASE", "AUTH", "SIGN_IN_WITH_EMAIL_AND_PASSWORD_MUTATION"];
 export declare const SIGN_IN_WITH_REDIRECT_MUTATION_KEY: readonly ["FIREBASE", "AUTH", "SIGN_IN_WITH_REDIRECT_MUTATION"];
 export declare const SIGN_OUT_MUTATION_KEY: readonly ["FIREBASE", "AUTH", "SIGN_OUT"];

package/react-native/auth/mutation-keys.js

@@ -4,6 +4,7 @@ export const CREATE_USER_WITH_EMAIL_AND_PASSWORD_MUTATION_KEY = [
     "CREATE_USER_WITH_EMAIL_AND_PASSWORD_MUTATION"
 ];
 export const SEND_EMAIL_VERIFICATION_MUTATION_KEY = ["FIREBASE", "AUTH", "SEND_EMAIL_VERIFICATION_MUTATION"];
+export const SIGN_IN_ANONYMOUSLY_MUTATION_KEY = ["FIREBASE", "AUTH", "SIGN_IN_ANONYMOUSLY_MUTATION"];
 export const SIGN_IN_WITH_EMAIL_AND_PASSWORD_MUTATION_KEY = [
     "FIREBASE",
     "AUTH",

package/react-native/auth/mutation-keys.ts

@@ -4,6 +4,7 @@ export const CREATE_USER_WITH_EMAIL_AND_PASSWORD_MUTATION_KEY = [
     "CREATE_USER_WITH_EMAIL_AND_PASSWORD_MUTATION"
 ] as const;
 export const SEND_EMAIL_VERIFICATION_MUTATION_KEY = ["FIREBASE", "AUTH", "SEND_EMAIL_VERIFICATION_MUTATION"] as const;
+export const SIGN_IN_ANONYMOUSLY_MUTATION_KEY = ["FIREBASE", "AUTH", "SIGN_IN_ANONYMOUSLY_MUTATION"] as const;
 export const SIGN_IN_WITH_EMAIL_AND_PASSWORD_MUTATION_KEY = [
     "FIREBASE",
     "AUTH",

package/react-native/auth/useSignInAnonymouslyMutation.d.ts

@@ -0,0 +1,36 @@
+import { UseMutationOptions } from "@tanstack/react-query";
+import { FirebaseAuthTypes } from "@react-native-firebase/auth";
+import { ReactNativeFirebase } from "@react-native-firebase/app";
+/**
+ * @inline
+ */
+export type UseSignInAnonymouslyMutationOptions = {
+    /**
+     * Options for useMutation hook excluding mutationFn. MutationKey will be equal to reference.path by default.
+     */
+    options?: Omit<UseMutationOptions<FirebaseAuthTypes.UserCredential, ReactNativeFirebase.NativeFirebaseError, void>, "mutationFn">;
+};
+/**
+ * Executes a mutation and returns users credentials
+ *
+ * @group Hook
+ *
+ * @param {useSignInAnonymouslyMutation} options - Configuration options for the mutation.
+ *
+ * @returns {UseMutationResult<AppModelType, Error, UseAddDocMutationValues<AppModelType>, TContext>}  A mutation result
+ *
+ * @example
+ * ```jsx
+ * export const MyComponent = () => {
+ *  const {mutate} = useSignInAnonymouslyMutation({
+ *      options: {
+ *      },
+ *  });
+ *
+ *  // ....
+ *  mutate();
+ *  // ....
+ * };
+ * ```
+ */
+export declare const useSignInAnonymouslyMutation: ({ options }?: UseSignInAnonymouslyMutationOptions) => import("@tanstack/react-query").UseMutationResult<FirebaseAuthTypes.UserCredential, ReactNativeFirebase.NativeFirebaseError, void, unknown>;

package/react-native/auth/useSignInAnonymouslyMutation.js

@@ -0,0 +1,35 @@
+import { useMutation } from "@tanstack/react-query";
+import { signInAnonymously } from "@react-native-firebase/auth";
+import { useAuth } from "./useAuth";
+import { SIGN_IN_ANONYMOUSLY_MUTATION_KEY } from "./mutation-keys";
+/**
+ * Executes a mutation and returns users credentials
+ *
+ * @group Hook
+ *
+ * @param {useSignInAnonymouslyMutation} options - Configuration options for the mutation.
+ *
+ * @returns {UseMutationResult<AppModelType, Error, UseAddDocMutationValues<AppModelType>, TContext>}  A mutation result
+ *
+ * @example
+ * ```jsx
+ * export const MyComponent = () => {
+ *  const {mutate} = useSignInAnonymouslyMutation({
+ *      options: {
+ *      },
+ *  });
+ *
+ *  // ....
+ *  mutate();
+ *  // ....
+ * };
+ * ```
+ */
+export const useSignInAnonymouslyMutation = ({ options = {} } = {}) => {
+    const firebaseAuth = useAuth();
+    return useMutation({
+        ...options,
+        mutationKey: SIGN_IN_ANONYMOUSLY_MUTATION_KEY,
+        mutationFn: async () => signInAnonymously(firebaseAuth)
+    });
+};

package/react-native/auth/useSignInAnonymouslyMutation.ts

@@ -0,0 +1,52 @@
+import { useMutation, UseMutationOptions } from "@tanstack/react-query";
+import { signInAnonymously, FirebaseAuthTypes } from "@react-native-firebase/auth";
+
+import { useAuth } from "./useAuth";
+import { SIGN_IN_ANONYMOUSLY_MUTATION_KEY } from "./mutation-keys";
+import { ReactNativeFirebase } from "@react-native-firebase/app";
+
+/**
+ * @inline
+ */
+export type UseSignInAnonymouslyMutationOptions = {
+    /**
+     * Options for useMutation hook excluding mutationFn. MutationKey will be equal to reference.path by default.
+     */
+    options?: Omit<
+        UseMutationOptions<FirebaseAuthTypes.UserCredential, ReactNativeFirebase.NativeFirebaseError, void>,
+        "mutationFn"
+    >;
+};
+
+/**
+ * Executes a mutation and returns users credentials
+ *
+ * @group Hook
+ *
+ * @param {useSignInAnonymouslyMutation} options - Configuration options for the mutation.
+ *
+ * @returns {UseMutationResult<AppModelType, Error, UseAddDocMutationValues<AppModelType>, TContext>}  A mutation result
+ *
+ * @example
+ * ```jsx
+ * export const MyComponent = () => {
+ *  const {mutate} = useSignInAnonymouslyMutation({
+ *      options: {
+ *      },
+ *  });
+ *
+ *  // ....
+ *  mutate();
+ *  // ....
+ * };
+ * ```
+ */
+export const useSignInAnonymouslyMutation = ({ options = {} }: UseSignInAnonymouslyMutationOptions = {}) => {
+    const firebaseAuth = useAuth();
+
+    return useMutation({
+        ...options,
+        mutationKey: SIGN_IN_ANONYMOUSLY_MUTATION_KEY,
+        mutationFn: async () => signInAnonymously(firebaseAuth)
+    });
+};

package/react-native/firestore/index.d.ts

@@ -20,3 +20,4 @@ export * from "./utils/getDocSnap";
 export * from "./utils/getDocRef";
 export * from "./utils/buildQueryConstraint";
 export * from "./utils/buildCompositeFilter";
+export * from "./useEnsureDoc";

package/react-native/firestore/index.js

@@ -20,3 +20,4 @@ export * from "./utils/getDocSnap";
 export * from "./utils/getDocRef";
 export * from "./utils/buildQueryConstraint";
 export * from "./utils/buildCompositeFilter";
+export * from "./useEnsureDoc";

package/react-native/firestore/index.ts

@@ -20,3 +20,4 @@ export * from "./utils/getDocSnap";
 export * from "./utils/getDocRef";
 export * from "./utils/buildQueryConstraint";
 export * from "./utils/buildCompositeFilter";
+export * from "./useEnsureDoc";

package/react-native/firestore/useEnsureDoc.d.ts

@@ -0,0 +1,40 @@
+import { UseQueryOptions } from "@tanstack/react-query";
+import { AppModel } from "../../types";
+import { GetDocDataOptions } from "./utils/getDocData";
+/**
+ * @inline
+ */
+export type UseEnsureDocOptions<AppModelType extends AppModel = AppModel> = {
+    /**
+     * Reference to a document that must be written
+     */
+    defaults: AppModelType;
+    /**
+     * Options for useMutation hook excluding mutationFn.
+     */
+    options: Omit<UseQueryOptions<AppModelType, Error, AppModelType>, "queryFn"> & Required<Pick<UseQueryOptions<AppModelType, Error, AppModelType>, "queryKey">>;
+} & Omit<GetDocDataOptions<AppModelType>, "db">;
+/**
+ * This hook checks if a doc with a requested reference exists.
+ * It creates a document with requested data if it does not exist.
+ *
+ * @group Hook
+ *
+ * @param {UseEnsureDocOptions<AppModelType>} options - Configuration options for mutation.
+ *
+ * @returns {UseQueryResult<AppModelType, Error>}  A mutation result
+ *
+ * @example
+ * ```jsx
+ * export const MyComponent = () => {
+ *  const {data} = useEnsureDocQuery({
+ *      options: {
+ *      },
+ *      reference: collection().doc(),
+ *      defaults: {prop1: 'value1'}
+ *  });
+ *
+ * };
+ * ```
+ */
+export declare const useEnsureDoc: <AppModelType extends AppModel = AppModel>({ reference, path, pathSegments, defaults, options }: UseEnsureDocOptions<AppModelType>) => import("@tanstack/react-query").UseQueryResult<AppModelType, Error>;

package/react-native/firestore/useEnsureDoc.js

@@ -0,0 +1,47 @@
+import { useQuery } from "@tanstack/react-query";
+import { getDoc, setDoc } from "@react-native-firebase/firestore";
+import { getDocRef } from "./utils/getDocRef";
+import { getDocSnap } from "./utils/getDocSnap";
+import { useFirestore } from "./useFirestore";
+/**
+ * This hook checks if a doc with a requested reference exists.
+ * It creates a document with requested data if it does not exist.
+ *
+ * @group Hook
+ *
+ * @param {UseEnsureDocOptions<AppModelType>} options - Configuration options for mutation.
+ *
+ * @returns {UseQueryResult<AppModelType, Error>}  A mutation result
+ *
+ * @example
+ * ```jsx
+ * export const MyComponent = () => {
+ *  const {data} = useEnsureDocQuery({
+ *      options: {
+ *      },
+ *      reference: collection().doc(),
+ *      defaults: {prop1: 'value1'}
+ *  });
+ *
+ * };
+ * ```
+ */
+export const useEnsureDoc = ({ reference, path, pathSegments, defaults, options }) => {
+    const db = useFirestore();
+    return useQuery({
+        ...options,
+        queryFn: async () => {
+            const existingDocSnap = await getDocSnap({ db, path, pathSegments, reference });
+            if (existingDocSnap?.exists) {
+                return { ...existingDocSnap.data(), uid: existingDocSnap.id };
+            }
+            const docRef = getDocRef({ db, reference, path, pathSegments });
+            if (!docRef) {
+                throw new Error(`Cannot fetch document reference using data: ${reference?.path}, ${path}, ${pathSegments?.join("/")}`);
+            }
+            await setDoc(docRef, defaults);
+            const docSnap = await getDoc(docRef);
+            return { ...docSnap.data(), uid: docSnap.id };
+        }
+    });
+};

package/react-native/firestore/useEnsureDoc.ts

@@ -0,0 +1,79 @@
+import { useQuery, UseQueryOptions } from "@tanstack/react-query";
+import { getDoc, setDoc } from "@react-native-firebase/firestore";
+
+import { AppModel } from "../../types";
+import { GetDocDataOptions } from "./utils/getDocData";
+import { getDocRef } from "./utils/getDocRef";
+import { getDocSnap } from "./utils/getDocSnap";
+import { useFirestore } from "./useFirestore";
+
+/**
+ * @inline
+ */
+export type UseEnsureDocOptions<AppModelType extends AppModel = AppModel> = {
+    /**
+     * Reference to a document that must be written
+     */
+    defaults: AppModelType;
+
+    /**
+     * Options for useMutation hook excluding mutationFn.
+     */
+    options: Omit<UseQueryOptions<AppModelType, Error, AppModelType>, "queryFn"> &
+        Required<Pick<UseQueryOptions<AppModelType, Error, AppModelType>, "queryKey">>;
+} & Omit<GetDocDataOptions<AppModelType>, "db">;
+
+/**
+ * This hook checks if a doc with a requested reference exists.
+ * It creates a document with requested data if it does not exist.
+ *
+ * @group Hook
+ *
+ * @param {UseEnsureDocOptions<AppModelType>} options - Configuration options for mutation.
+ *
+ * @returns {UseQueryResult<AppModelType, Error>}  A mutation result
+ *
+ * @example
+ * ```jsx
+ * export const MyComponent = () => {
+ *  const {data} = useEnsureDocQuery({
+ *      options: {
+ *      },
+ *      reference: collection().doc(),
+ *      defaults: {prop1: 'value1'}
+ *  });
+ *
+ * };
+ * ```
+ */
+export const useEnsureDoc = <AppModelType extends AppModel = AppModel>({
+    reference,
+    path,
+    pathSegments,
+    defaults,
+    options
+}: UseEnsureDocOptions<AppModelType>) => {
+    const db = useFirestore();
+
+    return useQuery({
+        ...options,
+        queryFn: async () => {
+            const existingDocSnap = await getDocSnap({ db, path, pathSegments, reference });
+
+            if (existingDocSnap?.exists) {
+                return { ...(existingDocSnap.data() as AppModelType), uid: existingDocSnap.id };
+            }
+
+            const docRef = getDocRef({ db, reference, path, pathSegments });
+            if (!docRef) {
+                throw new Error(
+                    `Cannot fetch document reference using data: ${reference?.path}, ${path}, ${pathSegments?.join("/")}`
+                );
+            }
+
+            await setDoc<AppModelType>(docRef, defaults);
+            const docSnap = await getDoc(docRef);
+            return { ...(docSnap.data() as AppModelType), uid: docSnap.id };
+        }
+    });
+};

package/web/auth/index.d.ts

@@ -11,3 +11,4 @@ export * from "./useSignOutMutation";
 export * from "./useIdToken";
 export * from "./useReauthenticateWitCredentialMutation";
 export * from "./useReauthenticateWitRedirectMutation";
+export * from "./useSignInAnonymouslyMutation";

package/web/auth/index.js

@@ -11,3 +11,4 @@ export * from "./useSignOutMutation";
 export * from "./useIdToken";
 export * from "./useReauthenticateWitCredentialMutation";
 export * from "./useReauthenticateWitRedirectMutation";
+export * from "./useSignInAnonymouslyMutation";

package/web/auth/index.ts

@@ -11,3 +11,4 @@ export * from "./useSignOutMutation";
 export * from "./useIdToken";
 export * from "./useReauthenticateWitCredentialMutation";
 export * from "./useReauthenticateWitRedirectMutation";
+export * from "./useSignInAnonymouslyMutation";

package/web/auth/mutation-keys.d.ts

@@ -1,5 +1,6 @@
 export declare const CREATE_USER_WITH_EMAIL_AND_PASSWORD_MUTATION_KEY: readonly ["FIREBASE", "AUTH", "CREATE_USER_WITH_EMAIL_AND_PASSWORD_MUTATION"];
 export declare const SEND_EMAIL_VERIFICATION_MUTATION_KEY: readonly ["FIREBASE", "AUTH", "SEND_EMAIL_VERIFICATION_MUTATION"];
+export declare const SIGN_IN_ANONYMOUSLY_MUTATION_KEY: readonly ["FIREBASE", "AUTH", "SIGN_IN_ANONYMOUSLY_MUTATION"];
 export declare const SIGN_IN_WITH_EMAIL_AND_PASSWORD_MUTATION_KEY: readonly ["FIREBASE", "AUTH", "SIGN_IN_WITH_EMAIL_AND_PASSWORD_MUTATION"];
 export declare const SIGN_IN_WITH_REDIRECT_MUTATION_KEY: readonly ["FIREBASE", "AUTH", "SIGN_IN_WITH_REDIRECT_MUTATION"];
 export declare const SIGN_OUT_MUTATION_KEY: readonly ["FIREBASE", "AUTH", "SIGN_OUT"];

package/web/auth/mutation-keys.js

@@ -4,6 +4,7 @@ export const CREATE_USER_WITH_EMAIL_AND_PASSWORD_MUTATION_KEY = [
     "CREATE_USER_WITH_EMAIL_AND_PASSWORD_MUTATION"
 ];
 export const SEND_EMAIL_VERIFICATION_MUTATION_KEY = ["FIREBASE", "AUTH", "SEND_EMAIL_VERIFICATION_MUTATION"];
+export const SIGN_IN_ANONYMOUSLY_MUTATION_KEY = ["FIREBASE", "AUTH", "SIGN_IN_ANONYMOUSLY_MUTATION"];
 export const SIGN_IN_WITH_EMAIL_AND_PASSWORD_MUTATION_KEY = [
     "FIREBASE",
     "AUTH",

package/web/auth/mutation-keys.ts

@@ -4,6 +4,7 @@ export const CREATE_USER_WITH_EMAIL_AND_PASSWORD_MUTATION_KEY = [
     "CREATE_USER_WITH_EMAIL_AND_PASSWORD_MUTATION"
 ] as const;
 export const SEND_EMAIL_VERIFICATION_MUTATION_KEY = ["FIREBASE", "AUTH", "SEND_EMAIL_VERIFICATION_MUTATION"] as const;
+export const SIGN_IN_ANONYMOUSLY_MUTATION_KEY = ["FIREBASE", "AUTH", "SIGN_IN_ANONYMOUSLY_MUTATION"] as const;
 export const SIGN_IN_WITH_EMAIL_AND_PASSWORD_MUTATION_KEY = [
     "FIREBASE",
     "AUTH",

package/web/auth/useSignInAnonymouslyMutation.d.ts

@@ -0,0 +1,36 @@
+import { UseMutationOptions } from "@tanstack/react-query";
+import { UserCredential } from "firebase/auth";
+import { ReactNativeFirebase } from "@react-native-firebase/app";
+/**
+ * @inline
+ */
+export type UseSignInAnonymouslyMutationOptions = {
+    /**
+     * Options for useMutation hook excluding mutationFn. MutationKey will be equal to reference.path by default.
+     */
+    options?: Omit<UseMutationOptions<UserCredential, ReactNativeFirebase.NativeFirebaseError, void>, "mutationFn">;
+};
+/**
+ * Executes a mutation and returns users credentials
+ *
+ * @group Hook
+ *
+ * @param {useSignInAnonymouslyMutation} options - Configuration options for the mutation.
+ *
+ * @returns {UseMutationResult<AppModelType, Error, UseAddDocMutationValues<AppModelType>, TContext>}  A mutation result
+ *
+ * @example
+ * ```jsx
+ * export const MyComponent = () => {
+ *  const {mutate} = useSignInAnonymouslyMutation({
+ *      options: {
+ *      },
+ *  });
+ *
+ *  // ....
+ *  mutate();
+ *  // ....
+ * };
+ * ```
+ */
+export declare const useSignInAnonymouslyMutation: ({ options }?: UseSignInAnonymouslyMutationOptions) => import("@tanstack/react-query").UseMutationResult<UserCredential, ReactNativeFirebase.NativeFirebaseError, void, unknown>;

package/web/auth/useSignInAnonymouslyMutation.js

@@ -0,0 +1,35 @@
+import { useMutation } from "@tanstack/react-query";
+import { signInAnonymously } from "firebase/auth";
+import { useAuth } from "./useAuth";
+import { SIGN_IN_ANONYMOUSLY_MUTATION_KEY } from "./mutation-keys";
+/**
+ * Executes a mutation and returns users credentials
+ *
+ * @group Hook
+ *
+ * @param {useSignInAnonymouslyMutation} options - Configuration options for the mutation.
+ *
+ * @returns {UseMutationResult<AppModelType, Error, UseAddDocMutationValues<AppModelType>, TContext>}  A mutation result
+ *
+ * @example
+ * ```jsx
+ * export const MyComponent = () => {
+ *  const {mutate} = useSignInAnonymouslyMutation({
+ *      options: {
+ *      },
+ *  });
+ *
+ *  // ....
+ *  mutate();
+ *  // ....
+ * };
+ * ```
+ */
+export const useSignInAnonymouslyMutation = ({ options = {} } = {}) => {
+    const firebaseAuth = useAuth();
+    return useMutation({
+        ...options,
+        mutationKey: SIGN_IN_ANONYMOUSLY_MUTATION_KEY,
+        mutationFn: async () => signInAnonymously(firebaseAuth)
+    });
+};

package/web/auth/useSignInAnonymouslyMutation.ts

@@ -0,0 +1,49 @@
+import { useMutation, UseMutationOptions } from "@tanstack/react-query";
+import { signInAnonymously, UserCredential } from "firebase/auth";
+
+import { useAuth } from "./useAuth";
+import { SIGN_IN_ANONYMOUSLY_MUTATION_KEY } from "./mutation-keys";
+import { ReactNativeFirebase } from "@react-native-firebase/app";
+
+/**
+ * @inline
+ */
+export type UseSignInAnonymouslyMutationOptions = {
+    /**
+     * Options for useMutation hook excluding mutationFn. MutationKey will be equal to reference.path by default.
+     */
+    options?: Omit<UseMutationOptions<UserCredential, ReactNativeFirebase.NativeFirebaseError, void>, "mutationFn">;
+};
+
+/**
+ * Executes a mutation and returns users credentials
+ *
+ * @group Hook
+ *
+ * @param {useSignInAnonymouslyMutation} options - Configuration options for the mutation.
+ *
+ * @returns {UseMutationResult<AppModelType, Error, UseAddDocMutationValues<AppModelType>, TContext>}  A mutation result
+ *
+ * @example
+ * ```jsx
+ * export const MyComponent = () => {
+ *  const {mutate} = useSignInAnonymouslyMutation({
+ *      options: {
+ *      },
+ *  });
+ *
+ *  // ....
+ *  mutate();
+ *  // ....
+ * };
+ * ```
+ */
+export const useSignInAnonymouslyMutation = ({ options = {} }: UseSignInAnonymouslyMutationOptions = {}) => {
+    const firebaseAuth = useAuth();
+
+    return useMutation({
+        ...options,
+        mutationKey: SIGN_IN_ANONYMOUSLY_MUTATION_KEY,
+        mutationFn: async () => signInAnonymously(firebaseAuth)
+    });
+};

package/web/firestore/index.d.ts

@@ -15,6 +15,7 @@ export * from "./useSetDocMutation";
 export * from "./useUpdateDocMutation";
 export * from "./useGetRealtimeDocData";
 export * from "./useQueryConstraints";
+export * from "./useEnsureDoc";
 export * from "./utils/getDocData";
 export * from "./utils/getDocSnap";
 export * from "./utils/getDocRef";

package/web/firestore/index.js

@@ -15,6 +15,7 @@ export * from "./useSetDocMutation";
 export * from "./useUpdateDocMutation";
 export * from "./useGetRealtimeDocData";
 export * from "./useQueryConstraints";
+export * from "./useEnsureDoc";
 export * from "./utils/getDocData";
 export * from "./utils/getDocSnap";
 export * from "./utils/getDocRef";

package/web/firestore/index.ts

@@ -15,6 +15,7 @@ export * from "./useSetDocMutation";
 export * from "./useUpdateDocMutation";
 export * from "./useGetRealtimeDocData";
 export * from "./useQueryConstraints";
+export * from "./useEnsureDoc";
 export * from "./utils/getDocData";
 export * from "./utils/getDocSnap";
 export * from "./utils/getDocRef";

package/web/firestore/useEnsureDoc.d.ts

@@ -0,0 +1,40 @@
+import { UseQueryOptions } from "@tanstack/react-query";
+import { AppModel } from "../../types";
+import { GetDocDataOptions } from "./utils/getDocData";
+/**
+ * @inline
+ */
+export type UseEnsureDocOptions<AppModelType extends AppModel = AppModel> = {
+    /**
+     * Reference to a document that must be written
+     */
+    defaults: AppModelType;
+    /**
+     * Options for useMutation hook excluding mutationFn.
+     */
+    options: Omit<UseQueryOptions<AppModelType, Error, AppModelType>, "queryFn"> & Required<Pick<UseQueryOptions<AppModelType, Error, AppModelType>, "queryKey">>;
+} & Omit<GetDocDataOptions<AppModelType>, "db">;
+/**
+ * This hook checks if a doc with a requested reference exists.
+ * It creates a document with requested data if it does not exist.
+ *
+ * @group Hook
+ *
+ * @param {UseEnsureDocOptions<AppModelType>} options - Configuration options for mutation.
+ *
+ * @returns {UseQueryResult<AppModelType, Error>}  A mutation result
+ *
+ * @example
+ * ```jsx
+ * export const MyComponent = () => {
+ *  const {data} = useEnsureDocQuery({
+ *      options: {
+ *      },
+ *      reference: collection().doc(),
+ *      defaults: {prop1: 'value1'}
+ *  });
+ *
+ * };
+ * ```
+ */
+export declare const useEnsureDoc: <AppModelType extends AppModel = AppModel>({ reference, path, pathSegments, defaults, options }: UseEnsureDocOptions<AppModelType>) => import("@tanstack/react-query").UseQueryResult<AppModelType, Error>;

package/web/firestore/useEnsureDoc.js

@@ -0,0 +1,47 @@
+import { useQuery } from "@tanstack/react-query";
+import { getDoc, setDoc } from "firebase/firestore";
+import { getDocRef } from "./utils/getDocRef";
+import { getDocSnap } from "./utils/getDocSnap";
+import { useFirestore } from "./useFirestore";
+/**
+ * This hook checks if a doc with a requested reference exists.
+ * It creates a document with requested data if it does not exist.
+ *
+ * @group Hook
+ *
+ * @param {UseEnsureDocOptions<AppModelType>} options - Configuration options for mutation.
+ *
+ * @returns {UseQueryResult<AppModelType, Error>}  A mutation result
+ *
+ * @example
+ * ```jsx
+ * export const MyComponent = () => {
+ *  const {data} = useEnsureDocQuery({
+ *      options: {
+ *      },
+ *      reference: collection().doc(),
+ *      defaults: {prop1: 'value1'}
+ *  });
+ *
+ * };
+ * ```
+ */
+export const useEnsureDoc = ({ reference, path, pathSegments, defaults, options }) => {
+    const db = useFirestore();
+    return useQuery({
+        ...options,
+        queryFn: async () => {
+            const existingDocSnap = await getDocSnap({ db, path, pathSegments, reference });
+            if (existingDocSnap?.exists) {
+                return { ...existingDocSnap.data(), uid: existingDocSnap.id };
+            }
+            const docRef = getDocRef({ db, reference, path, pathSegments });
+            if (!docRef) {
+                throw new Error(`Cannot fetch document reference using data: ${reference?.path}, ${path}, ${pathSegments?.join("/")}`);
+            }
+            await setDoc(docRef, defaults);
+            const docSnap = await getDoc(docRef);
+            return { ...docSnap.data(), uid: docSnap.id };
+        }
+    });
+};

package/web/firestore/useEnsureDoc.ts

@@ -0,0 +1,79 @@
+import { useQuery, UseQueryOptions } from "@tanstack/react-query";
+import { getDoc, setDoc } from "firebase/firestore";
+
+import { AppModel } from "../../types";
+import { GetDocDataOptions } from "./utils/getDocData";
+import { getDocRef } from "./utils/getDocRef";
+import { getDocSnap } from "./utils/getDocSnap";
+import { useFirestore } from "./useFirestore";
+
+/**
+ * @inline
+ */
+export type UseEnsureDocOptions<AppModelType extends AppModel = AppModel> = {
+    /**
+     * Reference to a document that must be written
+     */
+    defaults: AppModelType;
+
+    /**
+     * Options for useMutation hook excluding mutationFn.
+     */
+    options: Omit<UseQueryOptions<AppModelType, Error, AppModelType>, "queryFn"> &
+        Required<Pick<UseQueryOptions<AppModelType, Error, AppModelType>, "queryKey">>;
+} & Omit<GetDocDataOptions<AppModelType>, "db">;
+
+/**
+ * This hook checks if a doc with a requested reference exists.
+ * It creates a document with requested data if it does not exist.
+ *
+ * @group Hook
+ *
+ * @param {UseEnsureDocOptions<AppModelType>} options - Configuration options for mutation.
+ *
+ * @returns {UseQueryResult<AppModelType, Error>}  A mutation result
+ *
+ * @example
+ * ```jsx
+ * export const MyComponent = () => {
+ *  const {data} = useEnsureDocQuery({
+ *      options: {
+ *      },
+ *      reference: collection().doc(),
+ *      defaults: {prop1: 'value1'}
+ *  });
+ *
+ * };
+ * ```
+ */
+export const useEnsureDoc = <AppModelType extends AppModel = AppModel>({
+    reference,
+    path,
+    pathSegments,
+    defaults,
+    options
+}: UseEnsureDocOptions<AppModelType>) => {
+    const db = useFirestore();
+
+    return useQuery({
+        ...options,
+        queryFn: async () => {
+            const existingDocSnap = await getDocSnap({ db, path, pathSegments, reference });
+
+            if (existingDocSnap?.exists) {
+                return { ...(existingDocSnap.data() as AppModelType), uid: existingDocSnap.id };
+            }
+
+            const docRef = getDocRef({ db, reference, path, pathSegments });
+            if (!docRef) {
+                throw new Error(
+                    `Cannot fetch document reference using data: ${reference?.path}, ${path}, ${pathSegments?.join("/")}`
+                );
+            }
+
+            await setDoc<AppModelType, AppModelType>(docRef, defaults);
+            const docSnap = await getDoc(docRef);
+            return { ...(docSnap.data() as AppModelType), uid: docSnap.id };
+        }
+    });
+};