react-query-firebase 2.5.0 → 2.6.0

package/package.json

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

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/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 };
+        }
+    });
+};