react-query-firebase 2.3.2 → 2.4.0

package/react-native/firestore/useCompositeFilter.js

@@ -1,49 +1,6 @@
-import firebase, { and, or, where } from "@react-native-firebase/firestore";
+import { and, or } from "@react-native-firebase/firestore";
 import { useMemo } from "react";
-/**
- * Constructs a composite or where query filter based on the provided query structure.
- * It recursively builds query constraints using logical "or" or "and" operators.
- *
- * @group Utility
- *
- * @param {QueryElement<AppModelType>} query
- *
- * @returns {QueryFilterConstraint | null}
- *
- * @example
- * ```jsx
- * export const MyComponent = () => {
- *  const filter = buildCompositeFilter({
- *      operator: "AND",
- *      children: [
- *          {
- *              field: "field",
- *              value: "value",
- *              op: "=="
- *          },
- *          ...(query ? [query] : [])
- *      ]
- *  });
- *  console.log(filter);
- * };
- * ```
- */
-export const buildCompositeFilter = (query) => {
-    if (query.children) {
-        const queryConstraints = query.children.map(buildCompositeFilter).filter((constraint) => !!constraint);
-        if (queryConstraints.length <= 0) {
-            return null;
-        }
-        if (queryConstraints.length <= 1) {
-            return queryConstraints[0];
-        }
-        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;
-};
+import { buildCompositeFilter } from "./utils/buildCompositeFilter";
 /**
  * A custom hook that constructs a composite or where query filter based on the provided query structure.
  * It recursively builds query constraints using logical "or" or "and" operators.

package/react-native/firestore/useCompositeFilter.ts

@@ -1,23 +1,7 @@
-import firebase, { FirebaseFirestoreTypes, and, or, where } from "@react-native-firebase/firestore";
+import { and, or } from "@react-native-firebase/firestore";
 import { useMemo } from "react";
 import { AppModel } from "../../types";
-
-export type QueryFilterConstraint =
-    | FirebaseFirestoreTypes.QueryCompositeFilterConstraint
-    | FirebaseFirestoreTypes.QueryFilterConstraint;
-
-export type QueryElement<AppModelType extends AppModel = AppModel> = {
-    operator?: "OR" | "AND";
-    children?: QueryElement[];
-    field?: keyof (AppModelType & { documentId?: string[] });
-    value?: AppModelType[keyof AppModelType];
-    op?: FirebaseFirestoreTypes.WhereFilterOp;
-};
-
-export type CompositeFilter<AppModelType extends AppModel = AppModel> = {
-    operator: "OR" | "AND";
-    children: QueryElement<AppModelType & { documentId?: string[] }>[];
-};
+import { buildCompositeFilter, CompositeFilter, QueryFilterConstraint } from "./utils/buildCompositeFilter";
 
 /**
  * @inline
@@ -26,62 +10,6 @@ export type UseCompositeFilter<AppModelType extends AppModel = AppModel> = {
     query?: CompositeFilter<AppModelType>;
 };
 
-/**
- * Constructs a composite or where query filter based on the provided query structure.
- * It recursively builds query constraints using logical "or" or "and" operators.
- *
- * @group Utility
- *
- * @param {QueryElement<AppModelType>} query
- *
- * @returns {QueryFilterConstraint | null}
- *
- * @example
- * ```jsx
- * export const MyComponent = () => {
- *  const filter = buildCompositeFilter({
- *      operator: "AND",
- *      children: [
- *          {
- *              field: "field",
- *              value: "value",
- *              op: "=="
- *          },
- *          ...(query ? [query] : [])
- *      ]
- *  });
- *  console.log(filter);
- * };
- * ```
- */
-export const buildCompositeFilter = <AppModelType extends AppModel = AppModel>(
-    query: QueryElement<AppModelType>
-): QueryFilterConstraint | null => {
-    if (query.children) {
-        const queryConstraints = query.children.map(buildCompositeFilter).filter((constraint) => !!constraint);
-
-        if (queryConstraints.length <= 0) {
-            return null;
-        }
-
-        if (queryConstraints.length <= 1) {
-            return queryConstraints[0];
-        }
-
-        return (query as CompositeFilter).operator === "OR" ? or(...queryConstraints) : and(...queryConstraints);
-    }
-
-    if (query.field && query.op) {
-        return where(
-            query.field === "documentId" ? firebase.FieldPath.documentId() : (query.field as string),
-            query.op,
-            query.value
-        ) as unknown as FirebaseFirestoreTypes.QueryFilterConstraint;
-    }
-
-    return null;
-};
-
 /**
  * A custom hook that constructs a composite or where query filter based on the provided query structure.
  * It recursively builds query constraints using logical "or" or "and" operators.

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

@@ -1,6 +1,6 @@
 import { FirebaseFirestoreTypes, QueryConstraint, QueryNonFilterConstraint } from "@react-native-firebase/firestore";
 import { UseQueryResult, UseQueryOptions as UseReactQueryOptions } from "@tanstack/react-query";
-import { QueryFilterConstraint } from "./useCompositeFilter";
+import { QueryFilterConstraint } from "./utils/buildCompositeFilter";
 import { AppModel } from "../../types";
 /**
  * @inline

package/react-native/firestore/useCountQuery.ts

@@ -11,7 +11,7 @@ import {
     useQuery as useReactQuery,
     UseQueryOptions as UseReactQueryOptions
 } from "@tanstack/react-query";
-import { QueryFilterConstraint } from "./useCompositeFilter";
+import { QueryFilterConstraint } from "./utils/buildCompositeFilter";
 import { AppModel } from "../../types";
 
 /**

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

@@ -1,18 +1,47 @@
 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> = {
+import { AppModel } from "../../types";
+/**
+ * @inline
+ */
+export type UseDeleteDocMutationValues<AppModelType extends AppModel = AppModel> = {
     data: WithFieldValue<AppModelType>;
 };
-export type UseDeleteDocMutationOptions<AppModelType extends FirebaseFirestoreTypes.DocumentData = FirebaseFirestoreTypes.DocumentData, TContext = unknown> = {
+/**
+ * @inline
+ */
+export type UseDeleteDocMutationOptions<AppModelType extends AppModel = AppModel, TContext = unknown> = {
+    /**
+     * A reference to a firestore document
+     */
     reference: FirebaseFirestoreTypes.DocumentReference<AppModelType> | null;
-    options?: Omit<UseMutationOptions<void, ReactNativeFirebase.NativeFirebaseError, void, TContext>, "mutationFn" | "mutationKey">;
+    /**
+     * Options for useMutation hook excluding mutationFn. MutationKey will be equal to reference.path by default.
+     */
+    options?: Omit<UseMutationOptions<void, Error, void, TContext>, "mutationFn">;
 };
 /**
- * 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.
+ * Executes a query with specified constraints and returns the count of matched documents.
+ *
+ * @group Hook
+ *
+ * @param {UseDeleteDocMutationOptions<AppModelType>} options - Configuration options for the query.
+ *
+ * @returns {UseMutationResult<void, Error, UseDeleteDocMutationValues<AppModelType>, TContext>}  A mutation result
+ *
+ * @example
+ * ```jsx
+ * export const MyComponent = () => {
+ *  const {mutate} = useDeleteDocMutation({
+ *      options: {
+ *      },
+ *      reference: document(),
+ *  });
+ *
+ *  // ....
+ *  mutate();
+ *  // ....
+ * };
+ * ```
  */
-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>;
+export declare const useDeleteDocMutation: <AppModelType extends FirebaseFirestoreTypes.DocumentData = FirebaseFirestoreTypes.DocumentData, TContext = unknown>({ reference, options }: UseDeleteDocMutationOptions<AppModelType, TContext>) => import("@tanstack/react-query").UseMutationResult<void, Error, void, TContext>;

package/react-native/firestore/useDeleteDocMutation.js

@@ -2,11 +2,28 @@ 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.
+ * Executes a query with specified constraints and returns the count of matched documents.
+ *
+ * @group Hook
+ *
+ * @param {UseDeleteDocMutationOptions<AppModelType>} options - Configuration options for the query.
+ *
+ * @returns {UseMutationResult<void, Error, UseDeleteDocMutationValues<AppModelType>, TContext>}  A mutation result
+ *
+ * @example
+ * ```jsx
+ * export const MyComponent = () => {
+ *  const {mutate} = useDeleteDocMutation({
+ *      options: {
+ *      },
+ *      reference: document(),
+ *  });
+ *
+ *  // ....
+ *  mutate();
+ *  // ....
+ * };
+ * ```
  */
 export const useDeleteDocMutation = ({ reference, options = {} }) => {
     const mutationKey = useMemo(() => [reference?.path], [reference?.path]);

package/react-native/firestore/useDeleteDocMutation.ts

@@ -1,30 +1,53 @@
 import { useMutation, UseMutationOptions } from "@tanstack/react-query";
 import { FirebaseFirestoreTypes, deleteDoc, WithFieldValue } from "@react-native-firebase/firestore";
 
-import { ReactNativeFirebase } from "@react-native-firebase/app";
 import { useMemo } from "react";
+import { AppModel } from "../../types";
 
-export type UseDeleteDocMutationValues<AppModelType> = {
+/**
+ * @inline
+ */
+export type UseDeleteDocMutationValues<AppModelType extends AppModel = AppModel> = {
     data: WithFieldValue<AppModelType>;
 };
 
-export type UseDeleteDocMutationOptions<
-    AppModelType extends FirebaseFirestoreTypes.DocumentData = FirebaseFirestoreTypes.DocumentData,
-    TContext = unknown
-> = {
+/**
+ * @inline
+ */
+export type UseDeleteDocMutationOptions<AppModelType extends AppModel = AppModel, TContext = unknown> = {
+    /**
+     * A reference to a firestore document
+     */
     reference: FirebaseFirestoreTypes.DocumentReference<AppModelType> | null;
-    options?: Omit<
-        UseMutationOptions<void, ReactNativeFirebase.NativeFirebaseError, void, TContext>,
-        "mutationFn" | "mutationKey"
-    >;
+    /**
+     * Options for useMutation hook excluding mutationFn. MutationKey will be equal to reference.path by default.
+     */
+    options?: Omit<UseMutationOptions<void, Error, void, TContext>, "mutationFn">;
 };
 
 /**
- * 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.
+ * Executes a query with specified constraints and returns the count of matched documents.
+ *
+ * @group Hook
+ *
+ * @param {UseDeleteDocMutationOptions<AppModelType>} options - Configuration options for the query.
+ *
+ * @returns {UseMutationResult<void, Error, UseDeleteDocMutationValues<AppModelType>, TContext>}  A mutation result
+ *
+ * @example
+ * ```jsx
+ * export const MyComponent = () => {
+ *  const {mutate} = useDeleteDocMutation({
+ *      options: {
+ *      },
+ *      reference: document(),
+ *  });
+ *
+ *  // ....
+ *  mutate();
+ *  // ....
+ * };
+ * ```
  */
 export const useDeleteDocMutation = <
     AppModelType extends FirebaseFirestoreTypes.DocumentData = FirebaseFirestoreTypes.DocumentData,

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

@@ -1,19 +1,27 @@
 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[];
-};
+import { AppModel } from "../../types";
+import { GetDocRefOptions } from "./utils/getDocRef";
 /**
- * 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.
+ * @inline
+ */
+export type UseDocReferenceOptions<AppModelType extends AppModel = AppModel> = Omit<GetDocRefOptions<AppModelType>, "db">;
+/**
+ * Gets a `CollectionReference` instance.
+ *
+ * @group Hook
+ *
+ * @param {UseDocReferenceOptions<AppModelType>} options - Options
  *
- * @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, AppModelType> | null} A reference to a Firestore document
  *
- * @returns {FirebaseFirestoreTypes.DocumentReference<AppModelType> | null} The Firestore document reference corresponding to the provided path and options, or null if not initialized.
+ * @example
+ * ```jsx
+ * export const MyComponent = () => {
+ *  const ref = useDocReference({
+ *      reference: collection('todos')
+ *      path: 'first'
+ *  });
+ * };
+ * ```
  */
-export declare const useDocReference: <AppModelType extends FirebaseFirestoreTypes.DocumentData = FirebaseFirestoreTypes.DocumentData>({ path, reference, pathSegments }: UseDocReferenceOptions<AppModelType>) => FirebaseFirestoreTypes.DocumentReference<AppModelType>;
+export declare const useDocReference: <AppModelType extends AppModel = AppModel>({ path, reference, pathSegments }: UseDocReferenceOptions<AppModelType>) => FirebaseFirestoreTypes.DocumentReference<AppModelType> | null;

package/react-native/firestore/useDocReference.js

@@ -1,36 +1,30 @@
-import { doc } from "@react-native-firebase/firestore";
-import { useMemo } from "react";
+import { useEffect, useRef } from "react";
 import { useFirestore } from "./useFirestore";
+import { getDocRef } from "./utils/getDocRef";
 /**
- * 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.
+ * Gets a `CollectionReference` instance.
  *
- * @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.
+ * @group Hook
  *
- * @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 - Options
  *
- * @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, AppModelType> | null} A reference to a Firestore document
  *
- * @returns {FirebaseFirestoreTypes.DocumentReference<AppModelType> | null} The Firestore document reference corresponding to the provided path and options, or null if not initialized.
+ * @example
+ * ```jsx
+ * export const MyComponent = () => {
+ *  const ref = useDocReference({
+ *      reference: collection('todos')
+ *      path: 'first'
+ *  });
+ * };
+ * ```
  */
 export const useDocReference = ({ path, reference, pathSegments }) => {
     const db = useFirestore();
-    return useMemo(() => {
-        return getDocReference(db, { path, pathSegments, reference });
-    }, [db, reference, path, pathSegments]);
+    const ref = useRef(getDocRef({ db, path, pathSegments, reference }));
+    useEffect(() => {
+        ref.current = getDocRef({ db, path, pathSegments, reference });
+    }, [path, reference, pathSegments, db]);
+    return ref.current;
 };

package/react-native/firestore/useDocReference.ts

@@ -1,63 +1,50 @@
-import { doc, FirebaseFirestoreTypes } from "@react-native-firebase/firestore";
+import { FirebaseFirestoreTypes } from "@react-native-firebase/firestore";
 
-import { useMemo } from "react";
+import { useEffect, useRef } from "react";
 import { useFirestore } from "./useFirestore";
-
-export type UseDocReferenceOptions<
-    AppModelType extends FirebaseFirestoreTypes.DocumentData = FirebaseFirestoreTypes.DocumentData
-> = {
-    reference?:
-        | FirebaseFirestoreTypes.CollectionReference<AppModelType>
-        | FirebaseFirestoreTypes.DocumentReference<AppModelType>;
-    path?: string;
-    pathSegments?: string[];
-};
+import { AppModel } from "../../types";
+import { getDocRef, GetDocRefOptions } from "./utils/getDocRef";
 
 /**
- * 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.
+ * @inline
  */
-const getDocReference = <
-    AppModelType extends FirebaseFirestoreTypes.DocumentData = FirebaseFirestoreTypes.DocumentData
->(
-    db: FirebaseFirestoreTypes.Module,
-    { path, pathSegments, reference }: UseDocReferenceOptions<AppModelType>
-) => {
-    return (
-        !reference ? doc(db, path || "", ...(pathSegments || [])) : doc(reference, path, ...(pathSegments || []))
-    ) as FirebaseFirestoreTypes.DocumentReference<AppModelType>;
-};
+export type UseDocReferenceOptions<AppModelType extends AppModel = AppModel> = Omit<
+    GetDocRefOptions<AppModelType>,
+    "db"
+>;
 
 /**
- * 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.
+ * Gets a `CollectionReference` instance.
+ *
+ * @group Hook
  *
- * @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.
+ * @param {UseDocReferenceOptions<AppModelType>} options - Options
  *
- * @returns {FirebaseFirestoreTypes.DocumentReference<AppModelType> | null} The Firestore document reference corresponding to the provided path and options, or null if not initialized.
+ * @returns {FirebaseFirestoreTypes.DocumentReference<AppModelType, AppModelType> | null} A reference to a Firestore document
+ *
+ * @example
+ * ```jsx
+ * export const MyComponent = () => {
+ *  const ref = useDocReference({
+ *      reference: collection('todos')
+ *      path: 'first'
+ *  });
+ * };
+ * ```
  */
-export const useDocReference = <
-    AppModelType extends FirebaseFirestoreTypes.DocumentData = FirebaseFirestoreTypes.DocumentData
->({
+export const useDocReference = <AppModelType extends AppModel = AppModel>({
     path,
     reference,
     pathSegments
-}: UseDocReferenceOptions<AppModelType>): FirebaseFirestoreTypes.DocumentReference<AppModelType> => {
+}: UseDocReferenceOptions<AppModelType>) => {
     const db = useFirestore();
+    const ref = useRef<FirebaseFirestoreTypes.DocumentReference<AppModelType> | null>(
+        getDocRef({ db, path, pathSegments, reference })
+    );
+
+    useEffect(() => {
+        ref.current = getDocRef({ db, path, pathSegments, reference });
+    }, [path, reference, pathSegments, db]);
 
-    return useMemo(() => {
-        return getDocReference(db, { path, pathSegments, reference });
-    }, [db, reference, path, pathSegments]);
+    return ref.current;
 };

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

@@ -1,23 +1,28 @@
-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[];
+import { AppModel } from "../../types";
+import { GetDocRefOptions } from "./utils/getDocRef";
+/**
+ * @inline
+ */
+export type UseDocReferencesOptions<AppModelType extends AppModel = AppModel> = {
+    references: Omit<GetDocRefOptions<AppModelType>, "db">[];
 };
 /**
- * A custom hook to generate document references for Firebase Firestore documents using given
- * reference options.
+ * Gets `CollectionReference` instances
+ *
+ * @group Hook
+ *
+ * @param {UseDocReferencesOptions<AppModelType>} options - 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.
+ * @returns {Array<FirebaseFirestoreTypes.DocumentReference<AppModelType> | null>} A reference to a Firestore document
  *
- * @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.
+ * @example
+ * ```jsx
+ * export const MyComponent = () => {
+ *  const ref = useDocReference({
+ *      reference: collection('todos')
+ *      path: 'first'
+ *  });
+ * };
+ * ```
  */
-export declare const useDocReferences: <AppModelType extends FirebaseFirestoreTypes.DocumentData = FirebaseFirestoreTypes.DocumentData>(references: UseDocReferencesOptions<AppModelType>[]) => FirebaseFirestoreTypes.DocumentReference<AppModelType>[];
+export declare const useDocReferences: <AppModelType extends AppModel = AppModel>({ references }: UseDocReferencesOptions<AppModelType>) => import("@react-native-firebase/firestore").FirebaseFirestoreTypes.DocumentReference<AppModelType>[];

package/react-native/firestore/useDocReferences.js

@@ -1,29 +1,28 @@
-import { doc } from "@react-native-firebase/firestore";
 import { useMemo } from "react";
 import { useFirestore } from "./useFirestore";
+import { getDocRef } from "./utils/getDocRef";
 /**
- * A custom hook to generate document references for Firebase Firestore documents using given
- * reference options.
+ * Gets `CollectionReference` instances
  *
- * 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.
+ * @group Hook
  *
- * @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.
+ * @param {UseDocReferencesOptions<AppModelType>} options - Options
+ *
+ * @returns {Array<FirebaseFirestoreTypes.DocumentReference<AppModelType> | null>} A reference to a Firestore document
+ *
+ * @example
+ * ```jsx
+ * export const MyComponent = () => {
+ *  const ref = useDocReference({
+ *      reference: collection('todos')
+ *      path: 'first'
+ *  });
+ * };
+ * ```
  */
-export const useDocReferences = (references) => {
+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 || [])));
-        });
+        return references.map(({ path, reference, pathSegments }) => getDocRef({ db, reference, path, pathSegments }));
     }, [references, db]);
 };