react-query-firebase 2.1.1 → 2.1.3

package/react-native/context/FirebaseContextProvider.js

@@ -27,7 +27,7 @@ import firebase from "@react-native-firebase/app";
  * };
  * ```
  */
-export const FirebaseContextProvider = ({ emulators, options, children, authEnabled = true, firestoreEnabled = true, analyticsEnabled = true, consentSettings = {}, remoteConfigEnabled = true, remoteConfigSettings, remoteConfigDefaults = {}, firestoreSettings }) => {
+export const FirebaseContextProvider = ({ emulators, children, authEnabled = true, firestoreEnabled = true, analyticsEnabled = true, consentSettings = {}, remoteConfigEnabled = true, remoteConfigSettings, remoteConfigDefaults = {}, firestoreSettings }) => {
     const internalFirebase = useMemo(() => firebase, []);
     useEffect(() => {
         setConsent(firebase.analytics(), {
@@ -67,11 +67,11 @@ export const FirebaseContextProvider = ({ emulators, options, children, authEnab
         return null;
     }, [emulators?.auth, authEnabled, internalFirebase]);
     const internalAnalytics = useMemo(() => {
-        if (analyticsEnabled && options.measurementId) {
+        if (analyticsEnabled) {
             return internalFirebase.analytics();
         }
         return null;
-    }, [analyticsEnabled, options.measurementId, internalFirebase]);
+    }, [analyticsEnabled, internalFirebase]);
     const internalRemoteConfig = useMemo(() => {
         if (remoteConfigEnabled) {
             const localRemoteConfig = internalFirebase.remoteConfig();

package/react-native/context/FirebaseContextProvider.tsx

@@ -67,7 +67,6 @@ export type FirebaseContextProviderEmulators = {
  * @inline
  */
 export type FirebaseContextProviderProps = PropsWithChildren & {
-    platform: "Web" | "ReactNative";
     /**
      * Defines configuration for firebase emulators
      */
@@ -75,7 +74,7 @@ export type FirebaseContextProviderProps = PropsWithChildren & {
     /**
      * Configuration options for Firebase initialization. {@link https://firebase.google.com/docs/web/setup#config-object | Learn about the Firebase config object}
      */
-    options: ReactNativeFirebase.FirebaseAppOptions;
+    options?: ReactNativeFirebase.FirebaseAppOptions;
     /**
      * Flag indicating whether Firebase Auth should be enabled.
      */
@@ -151,7 +150,6 @@ export type FirebaseContextProviderProps = PropsWithChildren & {
  */
 export const FirebaseContextProvider: React.FC<FirebaseContextProviderProps> = ({
     emulators,
-    options,
     children,
     authEnabled = true,
     firestoreEnabled = true,
@@ -211,11 +209,11 @@ export const FirebaseContextProvider: React.FC<FirebaseContextProviderProps> = (
     }, [emulators?.auth, authEnabled, internalFirebase]);
 
     const internalAnalytics = useMemo(() => {
-        if (analyticsEnabled && options.measurementId) {
+        if (analyticsEnabled) {
             return internalFirebase.analytics();
         }
         return null;
-    }, [analyticsEnabled, options.measurementId, internalFirebase]);
+    }, [analyticsEnabled, internalFirebase]);
 
     const internalRemoteConfig = useMemo(() => {
         if (remoteConfigEnabled) {

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

@@ -0,0 +1,17 @@
+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";
+export * from "./useQueryConstraints";

package/react-native/firestore/index.js

@@ -0,0 +1,17 @@
+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";
+export * from "./useQueryConstraints";

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

@@ -0,0 +1,21 @@
+import { UseMutationOptions } from "@tanstack/react-query";
+import { FirebaseFirestoreTypes, WithFieldValue } from "@react-native-firebase/firestore";
+import { ReactNativeFirebase } from "@react-native-firebase/app";
+export type UseAddDocMutationValues<AppModelType> = {
+    data: WithFieldValue<AppModelType>;
+};
+export type UseAddDocMutationOptions<AppModelType extends FirebaseFirestoreTypes.DocumentData = FirebaseFirestoreTypes.DocumentData, TContext = unknown> = {
+    reference: FirebaseFirestoreTypes.CollectionReference<AppModelType>;
+    options?: Omit<UseMutationOptions<AppModelType, ReactNativeFirebase.NativeFirebaseError, 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.FirebaseFirestoreTypes.CollectionReference<AppModelType>} options.reference - Firestore collection reference where the document should be added.
+ * @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 FirebaseFirestoreTypes.DocumentData = FirebaseFirestoreTypes.DocumentData, TContext = unknown>({ reference, options }: UseAddDocMutationOptions<AppModelType, TContext>) => import("@tanstack/react-query").UseMutationResult<AppModelType, ReactNativeFirebase.NativeFirebaseError, UseAddDocMutationValues<AppModelType>, TContext>;

package/react-native/firestore/useAddDocMutation.js

@@ -0,0 +1,25 @@
+import { useMutation } from "@tanstack/react-query";
+import { addDoc, getDoc } from "@react-native-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.FirebaseFirestoreTypes.CollectionReference<AppModelType>} options.reference - Firestore collection reference where the document should be added.
+ * @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, options = {} }) => {
+    const mutationKey = useMemo(() => [reference.path], [reference.path]);
+    return useMutation({
+        ...options,
+        mutationFn: async ({ data }) => {
+            const docRef = await addDoc(reference, data);
+            const docSnap = await getDoc(docRef);
+            return docSnap.data();
+        },
+        mutationKey
+    });
+};

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

@@ -0,0 +1,15 @@
+import { UseMutationOptions } from "@tanstack/react-query";
+import { FirebaseFirestoreTypes } from "@react-native-firebase/firestore";
+import { ReactNativeFirebase } from "@react-native-firebase/app";
+export type UseBatchWriteVariables = (batch: FirebaseFirestoreTypes.WriteBatch) => Promise<void> | void;
+export type UseBatchWriteOptions<TContext = unknown> = {
+    options?: Omit<UseMutationOptions<void, ReactNativeFirebase.NativeFirebaseError, UseBatchWriteVariables, TContext>, "mutationFn">;
+};
+/**
+ * Custom hook to perform batch write operations using Firestore.
+ * Utilizes a mutation to carry out the batch write transaction.
+ * @template TContext - The type of context that can be passed into the hook, defaults to unknown.
+ * @param {Object} options - The configuration options for the mutation operation.
+ * @returns {Object} Returns an object composed of elements returned by useMutation, including properties such as status, and functions to trigger and control the mutation process.
+ */
+export declare const useBatchWrite: <TContext = unknown>({ options }?: UseBatchWriteOptions<TContext>) => import("@tanstack/react-query").UseMutationResult<void, ReactNativeFirebase.NativeFirebaseError, UseBatchWriteVariables, TContext>;

package/react-native/firestore/useBatchWrite.js

@@ -0,0 +1,21 @@
+import { useMutation } from "@tanstack/react-query";
+import { writeBatch } from "@react-native-firebase/firestore";
+import { useFirestore } from "./useFirestore";
+/**
+ * Custom hook to perform batch write operations using Firestore.
+ * Utilizes a mutation to carry out the batch write transaction.
+ * @template TContext - The type of context that can be passed into the hook, defaults to unknown.
+ * @param {Object} options - The configuration options for the mutation operation.
+ * @returns {Object} Returns an object composed of elements returned by useMutation, including properties such as status, and functions to trigger and control the mutation process.
+ */
+export const useBatchWrite = ({ options = {} } = {}) => {
+    const db = useFirestore();
+    return useMutation({
+        ...options,
+        mutationFn: async (batchWriteFn) => {
+            const batch = writeBatch(db);
+            await batchWriteFn(batch);
+            return batch.commit();
+        }
+    });
+};

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

@@ -0,0 +1,18 @@
+import { FirebaseFirestoreTypes } from "@react-native-firebase/firestore";
+export type UseCollectionReferenceOptions<AppModelType extends FirebaseFirestoreTypes.DocumentData = FirebaseFirestoreTypes.DocumentData> = {
+    reference?: FirebaseFirestoreTypes.CollectionReference<AppModelType> | FirebaseFirestoreTypes.DocumentReference<AppModelType>;
+    path: string;
+    pathSegments?: string[];
+};
+/**
+ * Creates a reference to a Firestore collection based on the provided path, reference, and path segments.
+ *
+ * This hook utilizes useMemo for optimization, ensuring the collection reference is recalculated only when its dependencies change.
+ *
+ * @param {UseCollectionReferenceOptions<AppModelType>} options - The options including path, reference, and pathSegments to construct the Firestore collection reference.
+ * @param {string} options.path - The base path for the collection.
+ * @param {FirestoreReference} options.reference - An optional Firestore reference object that should be of type "collection".
+ * @param {string[]} options.pathSegments - Additional path segments to append to the base path.
+ * @returns {CollectionReference} A Firestore collection reference constructed using the specified path, reference, and path segments.
+ */
+export declare const useCollectionReference: <AppModelType extends FirebaseFirestoreTypes.DocumentData = FirebaseFirestoreTypes.DocumentData>({ path, reference, pathSegments }: UseCollectionReferenceOptions<AppModelType>) => FirebaseFirestoreTypes.CollectionReference<AppModelType>;

package/react-native/firestore/useCollectionReference.js

@@ -0,0 +1,22 @@
+import { collection } from "@react-native-firebase/firestore";
+import { useMemo } from "react";
+import { useFirestore } from "./useFirestore";
+/**
+ * Creates a reference to a Firestore collection based on the provided path, reference, and path segments.
+ *
+ * This hook utilizes useMemo for optimization, ensuring the collection reference is recalculated only when its dependencies change.
+ *
+ * @param {UseCollectionReferenceOptions<AppModelType>} options - The options including path, reference, and pathSegments to construct the Firestore collection reference.
+ * @param {string} options.path - The base path for the collection.
+ * @param {FirestoreReference} options.reference - An optional Firestore reference object that should be of type "collection".
+ * @param {string[]} options.pathSegments - Additional path segments to append to the base path.
+ * @returns {CollectionReference} A Firestore collection reference constructed using the specified path, reference, and path segments.
+ */
+export const useCollectionReference = ({ path, reference, pathSegments }) => {
+    const db = useFirestore();
+    return useMemo(() => {
+        return !reference
+            ? collection(db, path || "", ...(pathSegments || []))
+            : collection(reference, path, ...(pathSegments || []));
+    }, [db, reference, path, pathSegments]);
+};

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

@@ -0,0 +1,40 @@
+import { FirebaseFirestoreTypes } from "@react-native-firebase/firestore";
+type CompositeFilterDocumentData = FirebaseFirestoreTypes.DocumentData;
+export type QueryElement<DbModelType extends CompositeFilterDocumentData = CompositeFilterDocumentData> = {
+    operator?: "OR" | "AND";
+    children?: QueryElement[];
+    field?: keyof (DbModelType & {
+        documentId?: string[];
+    });
+    value?: DbModelType[keyof DbModelType];
+    op?: FirebaseFirestoreTypes.WhereFilterOp;
+};
+export type CompositeFilter<DbModelType extends CompositeFilterDocumentData = CompositeFilterDocumentData> = {
+    operator: "OR" | "AND";
+    children: QueryElement<DbModelType & {
+        documentId?: string[];
+    }>[];
+};
+export type UseCompositeFilter<DbModelType extends CompositeFilterDocumentData = CompositeFilterDocumentData> = {
+    query?: CompositeFilter<DbModelType>;
+};
+/**
+ * Constructs a composite query filter based on the provided query structure.
+ * It recursively builds query constraints using logical "or" or "and" operators.
+ *
+ * @param {QueryElement<DbModelType>} query - The query element or structure to be evaluated and transformed into filter constraints.
+ * @returns {QueryFieldFilterConstraint | null} A constructed query filter constraint based on the input query, or null if no valid constraints can be derived.
+ */
+export declare const buildCompositeFilter: <DbModelType extends CompositeFilterDocumentData = CompositeFilterDocumentData>(query: QueryElement<DbModelType>) => FirebaseFirestoreTypes.QueryFilterConstraint | null;
+/**
+ * A custom hook that generates a composite filter for database queries, using the provided query configuration.
+ * It applies either an 'OR' or 'AND' logical operation based on the type specified in the query.
+ *
+ * @param {Object} query - The query configuration object that contains subqueries and a type for logical combination.
+ * @param {string} query.type - The type of composite operation ('or'/'and').
+ * @param {Array} query.children - An array of subqueries that will be processed to form the composite filter.
+ *
+ * @returns {(Function|undefined)} A composite query filter constraint function formed by combining subqueries or undefined if there are no valid constraints.
+ */
+export declare const useCompositeFilter: <DbModelType extends CompositeFilterDocumentData = CompositeFilterDocumentData>({ query }: UseCompositeFilter<DbModelType>) => FirebaseFirestoreTypes.QueryCompositeFilterConstraint | undefined;
+export {};

package/react-native/firestore/useCompositeFilter.js

@@ -0,0 +1,42 @@
+import firebase, { and, or, where } from "@react-native-firebase/firestore";
+import { useMemo } from "react";
+/**
+ * Constructs a composite query filter based on the provided query structure.
+ * It recursively builds query constraints using logical "or" or "and" operators.
+ *
+ * @param {QueryElement<DbModelType>} query - The query element or structure to be evaluated and transformed into filter constraints.
+ * @returns {QueryFieldFilterConstraint | null} A constructed query filter constraint based on the input query, or null if no valid constraints can be derived.
+ */
+export const buildCompositeFilter = (query) => {
+    if (query.children) {
+        const queryConstraints = query.children.map(buildCompositeFilter).filter((constraint) => !!constraint);
+        if (queryConstraints.length <= 0) {
+            return null;
+        }
+        return query.operator === "OR" ? or(...queryConstraints) : and(...queryConstraints);
+    }
+    if (query.field && query.op) {
+        return where(query.field === "documentId" ? firebase.FieldPath.documentId() : query.field, query.op, query.value);
+    }
+    return null;
+};
+/**
+ * A custom hook that generates a composite filter for database queries, using the provided query configuration.
+ * It applies either an 'OR' or 'AND' logical operation based on the type specified in the query.
+ *
+ * @param {Object} query - The query configuration object that contains subqueries and a type for logical combination.
+ * @param {string} query.type - The type of composite operation ('or'/'and').
+ * @param {Array} query.children - An array of subqueries that will be processed to form the composite filter.
+ *
+ * @returns {(Function|undefined)} A composite query filter constraint function formed by combining subqueries or undefined if there are no valid constraints.
+ */
+export const useCompositeFilter = ({ query }) => {
+    return useMemo(() => {
+        const queryConstraints = (query?.children?.map?.((subQuery) => buildCompositeFilter(subQuery))
+            ?.filter)?.((constraint) => !!constraint) ?? [];
+        if (queryConstraints.length <= 0) {
+            return undefined;
+        }
+        return query?.operator === "OR" ? or(...queryConstraints) : and(...queryConstraints);
+    }, [query]);
+};

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

@@ -0,0 +1,23 @@
+import { FirebaseFirestoreTypes, QueryConstraint, QueryNonFilterConstraint } from "@react-native-firebase/firestore";
+import { UseQueryResult, UseQueryOptions as UseReactQueryOptions } from "@tanstack/react-query";
+type UseCountQueryOptions<AppModelType extends FirebaseFirestoreTypes.DocumentData = FirebaseFirestoreTypes.DocumentData> = {
+    options: Omit<UseReactQueryOptions<number, Error, number>, "queryFn"> & Required<Pick<UseReactQueryOptions<number, Error, number>, "queryKey">>;
+    collectionReference: FirebaseFirestoreTypes.CollectionReference<AppModelType>;
+    queryConstraints?: QueryConstraint[] | QueryNonFilterConstraint[];
+    compositeFilter?: FirebaseFirestoreTypes.QueryCompositeFilterConstraint;
+};
+/**
+ * Executes a query with specified constraints and returns the count of matched documents.
+ *
+ * This function utilizes React Query to asynchronously fetch the count of documents from a server database
+ * that match the provided query constraints and an optional composite filter.
+ *
+ * @param {UseCountQueryOptions<AppModelType>} options - Configuration options for the query.
+ * @param {AppModelType extends FirebaseFirestoreTypes.DocumentData = FirebaseFirestoreTypes.DocumentData} [options.options] - Additional options for the React Query.
+ * @param {unknown} [options.query] - Reference to the query object to be executed.
+ * @param {unknown[]} [options.queryConstraints=[]] - An array of constraints to apply to the query.
+ * @param {unknown} [options.compositeFilter] - An optional composite filter to apply to the query.
+ * @returns {UseQueryResult<number>} An object containing the number of documents that match the query.
+ */
+export declare const useCountQuery: <AppModelType extends FirebaseFirestoreTypes.DocumentData = FirebaseFirestoreTypes.DocumentData>({ options, collectionReference, queryConstraints, compositeFilter }: UseCountQueryOptions<AppModelType>) => UseQueryResult<number>;
+export {};

package/react-native/firestore/useCountQuery.js

@@ -0,0 +1,30 @@
+import { getCountFromServer, query } from "@react-native-firebase/firestore";
+import { useQuery as useReactQuery } from "@tanstack/react-query";
+/**
+ * Executes a query with specified constraints and returns the count of matched documents.
+ *
+ * This function utilizes React Query to asynchronously fetch the count of documents from a server database
+ * that match the provided query constraints and an optional composite filter.
+ *
+ * @param {UseCountQueryOptions<AppModelType>} options - Configuration options for the query.
+ * @param {AppModelType extends FirebaseFirestoreTypes.DocumentData = FirebaseFirestoreTypes.DocumentData} [options.options] - Additional options for the React Query.
+ * @param {unknown} [options.query] - Reference to the query object to be executed.
+ * @param {unknown[]} [options.queryConstraints=[]] - An array of constraints to apply to the query.
+ * @param {unknown} [options.compositeFilter] - An optional composite filter to apply to the query.
+ * @returns {UseQueryResult<number>} An object containing the number of documents that match the query.
+ */
+export const useCountQuery = ({ options, collectionReference, queryConstraints = [], compositeFilter }) => {
+    return useReactQuery({
+        ...options,
+        queryFn: async () => {
+            const queryToExecute = compositeFilter
+                ? query(collectionReference, compositeFilter, ...queryConstraints)
+                : query(collectionReference, ...queryConstraints);
+            const querySnapshot = await getCountFromServer(queryToExecute);
+            if (querySnapshot) {
+                return querySnapshot.data().count;
+            }
+            return 0;
+        }
+    });
+};

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

@@ -0,0 +1,18 @@
+import { UseMutationOptions } from "@tanstack/react-query";
+import { FirebaseFirestoreTypes, WithFieldValue } from "@react-native-firebase/firestore";
+import { ReactNativeFirebase } from "@react-native-firebase/app";
+export type UseDeleteDocMutationValues<AppModelType> = {
+    data: WithFieldValue<AppModelType>;
+};
+export type UseDeleteDocMutationOptions<AppModelType extends FirebaseFirestoreTypes.DocumentData = FirebaseFirestoreTypes.DocumentData, TContext = unknown> = {
+    reference: FirebaseFirestoreTypes.DocumentReference<AppModelType> | null;
+    options?: Omit<UseMutationOptions<void, ReactNativeFirebase.NativeFirebaseError, void, TContext>, "mutationFn" | "mutationKey">;
+};
+/**
+ * A custom hook that provides a mutation function to delete a document from the database.
+ * @param {UseDeleteDocMutationOptions<AppModelType, DbModelType, TContext>} options - An object containing the reference to the document and additional options for the mutation.
+ * @param {FirestoreReference<AppModelType, DbModelType>} options.reference - The reference to the document that needs to be deleted.
+ * @param {object} options.options - Additional options for the mutation, if any (default is an empty object).
+ * @returns {UseMutationResult} An object returned by the `useMutation` hook which includes properties and methods to control the mutation's execution and track its state.
+ */
+export declare const useDeleteDocMutation: <AppModelType extends FirebaseFirestoreTypes.DocumentData = FirebaseFirestoreTypes.DocumentData, TContext = unknown>({ reference, options }: UseDeleteDocMutationOptions<AppModelType, TContext>) => import("@tanstack/react-query").UseMutationResult<void, ReactNativeFirebase.NativeFirebaseError, void, TContext>;

package/react-native/firestore/useDeleteDocMutation.js

@@ -0,0 +1,23 @@
+import { useMutation } from "@tanstack/react-query";
+import { deleteDoc } from "@react-native-firebase/firestore";
+import { useMemo } from "react";
+/**
+ * A custom hook that provides a mutation function to delete a document from the database.
+ * @param {UseDeleteDocMutationOptions<AppModelType, DbModelType, TContext>} options - An object containing the reference to the document and additional options for the mutation.
+ * @param {FirestoreReference<AppModelType, DbModelType>} options.reference - The reference to the document that needs to be deleted.
+ * @param {object} options.options - Additional options for the mutation, if any (default is an empty object).
+ * @returns {UseMutationResult} An object returned by the `useMutation` hook which includes properties and methods to control the mutation's execution and track its state.
+ */
+export const useDeleteDocMutation = ({ reference, options = {} }) => {
+    const mutationKey = useMemo(() => [reference?.path], [reference?.path]);
+    return useMutation({
+        ...options,
+        mutationFn: async () => {
+            if (!reference) {
+                throw new Error("Reference is undefined");
+            }
+            await deleteDoc(reference);
+        },
+        mutationKey
+    });
+};

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

@@ -0,0 +1,19 @@
+import { FirebaseFirestoreTypes } from "@react-native-firebase/firestore";
+export type UseDocReferenceOptions<AppModelType extends FirebaseFirestoreTypes.DocumentData = FirebaseFirestoreTypes.DocumentData> = {
+    reference?: FirebaseFirestoreTypes.CollectionReference<AppModelType> | FirebaseFirestoreTypes.DocumentReference<AppModelType>;
+    path?: string;
+    pathSegments?: string[];
+};
+/**
+ * Custom hook to generate and manage a Firestore document reference.
+ * This hook facilitates the retrieval of a Firestore document reference based on given options such as path and reference data.
+ * The reference is updated whenever the associated path, reference, or path segments change.
+ *
+ * @param {UseDocReferenceOptions<AppModelType>} options - Configuration options for setting up the document reference.
+ * @param {string} options.path - The path to the Firestore document.
+ * @param {DbModelType} options.reference - Reference data for the document, providing additional context or specifics.
+ * @param {string[]} options.pathSegments - Parts of the path to construct the full document path dynamically.
+ *
+ * @returns {FirebaseFirestoreTypes.DocumentReference<AppModelType> | null} The Firestore document reference corresponding to the provided path and options, or null if not initialized.
+ */
+export declare const useDocReference: <AppModelType extends FirebaseFirestoreTypes.DocumentData = FirebaseFirestoreTypes.DocumentData>({ path, reference, pathSegments }: UseDocReferenceOptions<AppModelType>) => FirebaseFirestoreTypes.DocumentReference<AppModelType>;

package/react-native/firestore/useDocReference.js

@@ -0,0 +1,36 @@
+import { doc } from "@react-native-firebase/firestore";
+import { useMemo } from "react";
+import { useFirestore } from "./useFirestore";
+/**
+ * Generates a document reference for a specified path or reference in Firestore.
+ * If a reference is not provided, it constructs a document reference using the Firestore instance, path, and path segments.
+ *
+ * @param {Firestore} db - The Firestore database instance used to create the document reference.
+ * @param {UseDocReferenceOptions<AppModelType>} options - An object containing the path, path segments, and optional reference.
+ * @param {string} options.path - The path to the document in the Firestore database.
+ * @param {string[]} [options.pathSegments] - Optional additional segments to join with the path.
+ * @param {DocumentReference | CollectionReference} [options.reference] - Optional Firestore reference object that influences how the document reference is constructed.
+ *
+ * @returns {DocumentReference<AppModelType> | null} A Firestore document reference if the path is specified; otherwise, returns null if path is not provided.
+ */
+const getDocReference = (db, { path, pathSegments, reference }) => {
+    return (!reference ? doc(db, path || "", ...(pathSegments || [])) : doc(reference, path, ...(pathSegments || [])));
+};
+/**
+ * Custom hook to generate and manage a Firestore document reference.
+ * This hook facilitates the retrieval of a Firestore document reference based on given options such as path and reference data.
+ * The reference is updated whenever the associated path, reference, or path segments change.
+ *
+ * @param {UseDocReferenceOptions<AppModelType>} options - Configuration options for setting up the document reference.
+ * @param {string} options.path - The path to the Firestore document.
+ * @param {DbModelType} options.reference - Reference data for the document, providing additional context or specifics.
+ * @param {string[]} options.pathSegments - Parts of the path to construct the full document path dynamically.
+ *
+ * @returns {FirebaseFirestoreTypes.DocumentReference<AppModelType> | null} The Firestore document reference corresponding to the provided path and options, or null if not initialized.
+ */
+export const useDocReference = ({ path, reference, pathSegments }) => {
+    const db = useFirestore();
+    return useMemo(() => {
+        return getDocReference(db, { path, pathSegments, reference });
+    }, [db, reference, path, pathSegments]);
+};

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

@@ -0,0 +1,23 @@
+import { FirebaseFirestoreTypes } from "@react-native-firebase/firestore";
+export type UseDocReferencesOptions<AppModelType extends FirebaseFirestoreTypes.DocumentData = FirebaseFirestoreTypes.DocumentData> = {
+    reference?: FirebaseFirestoreTypes.CollectionReference<AppModelType> | FirebaseFirestoreTypes.DocumentReference<AppModelType>;
+    path: string;
+    pathSegments?: string[];
+};
+/**
+ * A custom hook to generate document references for Firebase Firestore documents using given
+ * reference options.
+ *
+ * The hook accepts an array of options, where each option may contain a path,
+ * an existing reference, or path segments, and returns an array of generated
+ * Firestore document references based on those options. The references can be used
+ * to interact with the Firestore database documents. It uses memoization to optimize
+ * reference generation.
+ *
+ * @param {UseDocReferencesOptions<AppModelType>[]} references - An array of options
+ * specifying how to generate document references. Each option may include a `path`
+ * as a string, a `reference` as a Firestore reference, and `pathSegments` as an array of strings.
+ * @returns {DocumentReference<AppModelType>[]} An array of Firestore document references
+ * generated from the options provided.
+ */
+export declare const useDocReferences: <AppModelType extends FirebaseFirestoreTypes.DocumentData = FirebaseFirestoreTypes.DocumentData>(references: UseDocReferencesOptions<AppModelType>[]) => FirebaseFirestoreTypes.DocumentReference<AppModelType>[];

package/react-native/firestore/useDocReferences.js

@@ -0,0 +1,29 @@
+import { doc } from "@react-native-firebase/firestore";
+import { useMemo } from "react";
+import { useFirestore } from "./useFirestore";
+/**
+ * A custom hook to generate document references for Firebase Firestore documents using given
+ * reference options.
+ *
+ * The hook accepts an array of options, where each option may contain a path,
+ * an existing reference, or path segments, and returns an array of generated
+ * Firestore document references based on those options. The references can be used
+ * to interact with the Firestore database documents. It uses memoization to optimize
+ * reference generation.
+ *
+ * @param {UseDocReferencesOptions<AppModelType>[]} references - An array of options
+ * specifying how to generate document references. Each option may include a `path`
+ * as a string, a `reference` as a Firestore reference, and `pathSegments` as an array of strings.
+ * @returns {DocumentReference<AppModelType>[]} An array of Firestore document references
+ * generated from the options provided.
+ */
+export const useDocReferences = (references) => {
+    const db = useFirestore();
+    return useMemo(() => {
+        return references.map(({ path, reference, pathSegments }) => {
+            return (!reference
+                ? doc(db, path || "", ...(pathSegments || []))
+                : doc(reference, path, ...(pathSegments || [])));
+        });
+    }, [references, db]);
+};

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

@@ -0,0 +1,7 @@
+/**
+ * Provides a hook to access the Firestore instance from the Firebase context.
+ * It extracts the Firestore object from the Firebase context, allowing components to interact with Firestore services.
+ *
+ * @returns {firestore.Firestore} The Firestore instance from the Firebase context.
+ */
+export declare const useFirestore: () => import("@react-native-firebase/firestore").FirebaseFirestoreTypes.Module;

package/react-native/firestore/useFirestore.js

@@ -0,0 +1,12 @@
+import { useContext } from "react";
+import { FirebaseContext } from "../context/FirebaseContext";
+/**
+ * Provides a hook to access the Firestore instance from the Firebase context.
+ * It extracts the Firestore object from the Firebase context, allowing components to interact with Firestore services.
+ *
+ * @returns {firestore.Firestore} The Firestore instance from the Firebase context.
+ */
+export const useFirestore = () => {
+    const { firestore } = useContext(FirebaseContext);
+    return firestore;
+};

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

@@ -0,0 +1,18 @@
+import { FirebaseFirestoreTypes } from "@react-native-firebase/firestore";
+import { UseQueryOptions } from "@tanstack/react-query";
+type UseGetDocOptions<AppModelType extends FirebaseFirestoreTypes.DocumentData = FirebaseFirestoreTypes.DocumentData> = {
+    options: Omit<UseQueryOptions<AppModelType | null | undefined, Error, AppModelType>, "queryFn"> & Required<Pick<UseQueryOptions<AppModelType, Error, AppModelType>, "queryKey">>;
+    path?: string;
+    pathSegments?: string[];
+    reference: FirebaseFirestoreTypes.CollectionReference<AppModelType> | FirebaseFirestoreTypes.DocumentReference<AppModelType>;
+};
+/**
+ * Custom React Hook to retrieve document data from Firestore using specified parameters.
+ * @param {Object} options - The options for configuring the Firestore query.
+ * @param {string} reference - The reference to the document in Firestore.
+ * @param {string} path - The path to the document in Firestore.
+ * @param {Array<string>} pathSegments - Segments of the path to document in Firestore.
+ * @returns {Object} Result of the query containing document data and query status.
+ */
+export declare const useGetDocData: <AppModelType extends FirebaseFirestoreTypes.DocumentData = FirebaseFirestoreTypes.DocumentData>({ options, reference, path, pathSegments }: UseGetDocOptions<AppModelType>) => import("@tanstack/react-query").UseQueryResult<AppModelType, Error>;
+export {};

package/react-native/firestore/useGetDocData.js

@@ -0,0 +1,18 @@
+import { useFirestore } from "./useFirestore";
+import { getDocData } from "./utils/getDocData";
+import { useQuery } from "@tanstack/react-query";
+/**
+ * Custom React Hook to retrieve document data from Firestore using specified parameters.
+ * @param {Object} options - The options for configuring the Firestore query.
+ * @param {string} reference - The reference to the document in Firestore.
+ * @param {string} path - The path to the document in Firestore.
+ * @param {Array<string>} pathSegments - Segments of the path to document in Firestore.
+ * @returns {Object} Result of the query containing document data and query status.
+ */
+export const useGetDocData = ({ options, reference, path, pathSegments }) => {
+    const db = useFirestore();
+    return useQuery({
+        ...options,
+        queryFn: () => getDocData({ db, reference, path, pathSegments })
+    });
+};