react-query-firebase 2.3.3 → 2.4.0

package/web/firestore/useCountQuery.ts

@@ -12,13 +12,13 @@ import {
     useQuery as useReactQuery,
     UseQueryOptions as UseReactQueryOptions
 } from "@tanstack/react-query";
-import { QueryFilterConstraint } from "./useCompositeFilter";
+import { QueryFilterConstraint } from "./utils/buildCompositeFilter";
 import { AppModel } from "../../types";
 
 /**
  * @inline
  */
-type UseCountQueryOptions<AppModelType extends AppModel = AppModel, DbModelType extends AppModel = AppModel> = {
+type UseCountQueryOptions<AppModelType extends AppModel = AppModel> = {
     /**
      * Reqct-query options that must include queryKey and shall not define queryFn
      */
@@ -28,7 +28,7 @@ type UseCountQueryOptions<AppModelType extends AppModel = AppModel, DbModelType
     /**
      * Reference to a Firestore collection
      */
-    collectionReference: CollectionReference<AppModelType, DbModelType>;
+    collectionReference: CollectionReference<AppModelType, AppModelType>;
 
     /**
      * Non composite filter constraints such as limit, order, where
@@ -63,12 +63,12 @@ type UseCountQueryOptions<AppModelType extends AppModel = AppModel, DbModelType
  * };
  * ```
  */
-export const useCountQuery = <AppModelType extends AppModel = AppModel, DbModelType extends AppModel = AppModel>({
+export const useCountQuery = <AppModelType extends AppModel = AppModel>({
     options,
     collectionReference,
     queryConstraints = [],
     compositeFilter
-}: UseCountQueryOptions<AppModelType, DbModelType>): UseQueryResult<number> => {
+}: UseCountQueryOptions<AppModelType>): UseQueryResult<number> => {
     return useReactQuery({
         ...options,
         queryFn: async () => {

package/web/firestore/useDeleteDocMutation.d.ts

@@ -1,18 +1,48 @@
 import { UseMutationOptions } from "@tanstack/react-query";
-import { DocumentData, WithFieldValue, DocumentReference } from "firebase/firestore";
+import { WithFieldValue, DocumentReference } from "firebase/firestore";
 import { FirebaseError } from "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 DocumentData = DocumentData, DbModelType extends DocumentData = DocumentData, TContext = unknown> = {
-    reference: DocumentReference<AppModelType, DbModelType> | null;
-    options?: Omit<UseMutationOptions<void, FirebaseError, void, TContext>, "mutationFn" | "mutationKey">;
+/**
+ * @inline
+ */
+export type UseDeleteDocMutationOptions<AppModelType extends AppModel = AppModel, TContext = unknown> = {
+    /**
+     * A reference to a firestore document
+     */
+    reference: DocumentReference<AppModelType, AppModelType> | null;
+    /**
+     * Options for useMutation hook excluding mutationFn. MutationKey will be equal to reference.path by default.
+     */
+    options?: Omit<UseMutationOptions<void, FirebaseError, 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 DocumentData = DocumentData, DbModelType extends DocumentData = DocumentData, TContext = unknown>({ reference, options }: UseDeleteDocMutationOptions<AppModelType, DbModelType, TContext>) => import("@tanstack/react-query").UseMutationResult<void, FirebaseError, void, TContext>;
+export declare const useDeleteDocMutation: <AppModelType extends AppModel = AppModel, TContext = unknown>({ reference, options }: UseDeleteDocMutationOptions<AppModelType, TContext>) => import("@tanstack/react-query").UseMutationResult<void, FirebaseError, void, TContext>;

package/web/firestore/useDeleteDocMutation.js

@@ -2,22 +2,39 @@ import { useMutation } from "@tanstack/react-query";
 import { deleteDoc } from "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]);
     return useMutation({
+        mutationKey,
         ...options,
         mutationFn: async () => {
             if (!reference) {
                 throw new Error("Reference is undefined");
             }
             await deleteDoc(reference);
-        },
-        mutationKey
+        }
     });
 };

package/web/firestore/useDeleteDocMutation.ts

@@ -1,47 +1,69 @@
 import { useMutation, UseMutationOptions } from "@tanstack/react-query";
-import { DocumentData, deleteDoc, WithFieldValue, DocumentReference } from "firebase/firestore";
+import { deleteDoc, WithFieldValue, DocumentReference } from "firebase/firestore";
 
 import { FirebaseError } from "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 DocumentData = DocumentData,
-    DbModelType extends DocumentData = DocumentData,
-    TContext = unknown
-> = {
-    reference: DocumentReference<AppModelType, DbModelType> | null;
-    options?: Omit<UseMutationOptions<void, FirebaseError, void, TContext>, "mutationFn" | "mutationKey">;
+/**
+ * @inline
+ */
+export type UseDeleteDocMutationOptions<AppModelType extends AppModel = AppModel, TContext = unknown> = {
+    /**
+     * A reference to a firestore document
+     */
+    reference: DocumentReference<AppModelType, AppModelType> | null;
+    /**
+     * Options for useMutation hook excluding mutationFn. MutationKey will be equal to reference.path by default.
+     */
+    options?: Omit<UseMutationOptions<void, FirebaseError, 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 DocumentData = DocumentData,
-    DbModelType extends DocumentData = DocumentData,
-    TContext = unknown
->({
+export const useDeleteDocMutation = <AppModelType extends AppModel = AppModel, TContext = unknown>({
     reference,
     options = {}
-}: UseDeleteDocMutationOptions<AppModelType, DbModelType, TContext>) => {
+}: UseDeleteDocMutationOptions<AppModelType, TContext>) => {
     const mutationKey = useMemo(() => [reference?.path], [reference?.path]);
 
     return useMutation({
+        mutationKey,
         ...options,
         mutationFn: async () => {
             if (!reference) {
                 throw new Error("Reference is undefined");
             }
-            await deleteDoc<AppModelType, DbModelType>(reference);
-        },
-        mutationKey
+            await deleteDoc<AppModelType, AppModelType>(reference);
+        }
     });
 };

package/web/firestore/useDocReference.d.ts

@@ -1,19 +1,27 @@
-import { CollectionReference, DocumentData, DocumentReference } from "firebase/firestore";
-export type UseDocReferenceOptions<AppModelType, DbModelType extends DocumentData = DocumentData> = {
-    reference?: CollectionReference<AppModelType, DbModelType> | DocumentReference<AppModelType, DbModelType>;
-    path?: string;
-    pathSegments?: string[];
-};
+import { DocumentReference } from "firebase/firestore";
+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, DbModelType>} 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 {DocumentReference<AppModelType, AppModelType> | null} A reference to a Firestore document
  *
- * @returns {DocumentReference<AppModelType, DbModelType> | 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, DbModelType extends DocumentData = DocumentData>({ path, reference, pathSegments }: UseDocReferenceOptions<AppModelType, DbModelType>) => DocumentReference<AppModelType, DbModelType> | null;
+export declare const useDocReference: <AppModelType extends AppModel = AppModel>({ path, reference, pathSegments }: UseDocReferenceOptions<AppModelType>) => DocumentReference<AppModelType, AppModelType> | null;

package/web/firestore/useDocReference.js

@@ -1,45 +1,30 @@
-import { doc } from "firebase/firestore";
 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, DbModelType>} 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, DbModelType> | null} A Firestore document reference if the path is specified; otherwise, returns null if path is not provided.
- */
-const getDocReference = (db, { path, pathSegments, reference }) => {
-    if (!path) {
-        return null;
-    }
-    return (!reference
-        ? doc(db, path || "", ...(pathSegments || []))
-        : reference.type === "collection"
-            ? doc(reference, 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, DbModelType>} 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 {DocumentReference<AppModelType, AppModelType> | null} A reference to a Firestore document
  *
- * @returns {DocumentReference<AppModelType, DbModelType> | 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();
-    const ref = useRef(getDocReference(db, { path, pathSegments, reference }));
+    const ref = useRef(getDocRef({ db, path, pathSegments, reference }));
     useEffect(() => {
-        ref.current = getDocReference(db, { path, pathSegments, reference });
+        ref.current = getDocRef({ db, path, pathSegments, reference });
     }, [path, reference, pathSegments, db]);
     return ref.current;
 };

package/web/firestore/useDocReference.ts

@@ -1,67 +1,49 @@
-import { doc, CollectionReference, DocumentData, DocumentReference, Firestore } from "firebase/firestore";
+import { DocumentReference } from "firebase/firestore";
 
 import { useEffect, useRef } from "react";
 import { useFirestore } from "./useFirestore";
-
-export type UseDocReferenceOptions<AppModelType, DbModelType extends DocumentData = DocumentData> = {
-    reference?: CollectionReference<AppModelType, DbModelType> | DocumentReference<AppModelType, DbModelType>;
-    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, DbModelType>} 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, DbModelType> | null} A Firestore document reference if the path is specified; otherwise, returns null if path is not provided.
+ * @inline
  */
-const getDocReference = <AppModelType, DbModelType extends DocumentData = DocumentData>(
-    db: Firestore,
-    { path, pathSegments, reference }: UseDocReferenceOptions<AppModelType, DbModelType>
-) => {
-    if (!path) {
-        return null;
-    }
-
-    return (
-        !reference
-            ? doc(db, path || "", ...(pathSegments || []))
-            : reference.type === "collection"
-              ? doc(reference, path, ...(pathSegments || []))
-              : doc(reference, path, ...(pathSegments || []))
-    ) as DocumentReference<AppModelType, DbModelType>;
-};
+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 - Options
  *
- * @param {UseDocReferenceOptions<AppModelType, DbModelType>} 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 {DocumentReference<AppModelType, AppModelType> | null} A reference to a Firestore document
  *
- * @returns {DocumentReference<AppModelType, DbModelType> | 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 = <AppModelType, DbModelType extends DocumentData = DocumentData>({
+export const useDocReference = <AppModelType extends AppModel = AppModel>({
     path,
     reference,
     pathSegments
-}: UseDocReferenceOptions<AppModelType, DbModelType>) => {
+}: UseDocReferenceOptions<AppModelType>) => {
     const db = useFirestore();
-    const ref = useRef<DocumentReference<AppModelType, DbModelType> | null>(
-        getDocReference(db, { path, pathSegments, reference })
+    const ref = useRef<DocumentReference<AppModelType, AppModelType> | null>(
+        getDocRef({ db, path, pathSegments, reference })
     );
 
     useEffect(() => {
-        ref.current = getDocReference(db, { path, pathSegments, reference });
+        ref.current = getDocRef({ db, path, pathSegments, reference });
     }, [path, reference, pathSegments, db]);
 
     return ref.current;

package/web/firestore/useDocReferences.d.ts

@@ -1,23 +1,28 @@
-import { CollectionReference, DocumentData, DocumentReference } from "firebase/firestore";
-export type UseDocReferencesOptions<AppModelType, DbModelType extends DocumentData = DocumentData> = {
-    reference?: CollectionReference<AppModelType, DbModelType> | DocumentReference<AppModelType, DbModelType>;
-    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<DocumentReference<AppModelType, AppModelType> | null>} A reference to a Firestore document
  *
- * @param {UseDocReferencesOptions<AppModelType, DbModelType>[]} 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, DbModelType>[]} 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, DbModelType extends DocumentData = DocumentData>(references: UseDocReferencesOptions<AppModelType, DbModelType>[]) => DocumentReference<AppModelType, DbModelType>[];
+export declare const useDocReferences: <AppModelType extends AppModel = AppModel>({ references }: UseDocReferencesOptions<AppModelType>) => import("@firebase/firestore").DocumentReference<AppModelType, AppModelType>[];

package/web/firestore/useDocReferences.js

@@ -1,31 +1,28 @@
-import { doc } from "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, DbModelType>[]} 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, DbModelType>[]} An array of Firestore document references
- * generated from the options provided.
+ * @param {UseDocReferencesOptions<AppModelType>} options - Options
+ *
+ * @returns {Array<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 useDocReferences = (references) => {
+export const useDocReferences = ({ references }) => {
     const db = useFirestore();
     return useMemo(() => {
-        return references.map(({ path, reference, pathSegments }) => {
-            return (!reference
-                ? doc(db, path || "", ...(pathSegments || []))
-                : reference.type === "collection"
-                    ? doc(reference, path, ...(pathSegments || []))
-                    : doc(reference, path, ...(pathSegments || [])));
-        });
+        return references.map(({ path, reference, pathSegments }) => getDocRef({ db, reference, path, pathSegments }));
     }, [references, db]);
 };

package/web/firestore/useDocReferences.ts

@@ -1,44 +1,40 @@
-import { CollectionReference, doc, DocumentData, DocumentReference } from "firebase/firestore";
-
 import { useMemo } from "react";
 import { useFirestore } from "./useFirestore";
+import { AppModel } from "../../types";
+import { getDocRef, GetDocRefOptions } from "./utils/getDocRef";
 
-export type UseDocReferencesOptions<AppModelType, DbModelType extends DocumentData = DocumentData> = {
-    reference?: CollectionReference<AppModelType, DbModelType> | DocumentReference<AppModelType, DbModelType>;
-    path: string;
-    pathSegments?: string[];
+/**
+ * @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<DocumentReference<AppModelType, AppModelType> | null>} A reference to a Firestore document
  *
- * @param {UseDocReferencesOptions<AppModelType, DbModelType>[]} 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, DbModelType>[]} 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 const useDocReferences = <AppModelType, DbModelType extends DocumentData = DocumentData>(
-    references: UseDocReferencesOptions<AppModelType, DbModelType>[]
-) => {
+export const useDocReferences = <AppModelType extends AppModel = AppModel>({
+    references
+}: UseDocReferencesOptions<AppModelType>) => {
     const db = useFirestore();
 
     return useMemo(() => {
-        return references.map(({ path, reference, pathSegments }) => {
-            return (
-                !reference
-                    ? doc(db, path || "", ...(pathSegments || []))
-                    : reference.type === "collection"
-                      ? doc(reference, path, ...(pathSegments || []))
-                      : doc(reference, path, ...(pathSegments || []))
-            ) as DocumentReference<AppModelType, DbModelType>;
-        });
+        return references.map(({ path, reference, pathSegments }) => getDocRef({ db, reference, path, pathSegments }));
     }, [references, db]);
 };

package/web/firestore/useFirestore.d.ts

@@ -1,7 +1,8 @@
 /**
- * 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 an instance of firestore bound to the closest context.
  *
- * @returns {firestore.Firestore} The Firestore instance from the Firebase context.
+ * @group Hook
+ *
+ * @returns {Firestore}
  */
 export declare const useFirestore: () => import("@firebase/firestore").Firestore;