react-query-firebase 2.0.0-rc6 → 2.0.0-rc7

package/web/firestore/useBatchWrite.ts

@@ -0,0 +1,31 @@
+import { useMutation, UseMutationOptions } from "@tanstack/react-query";
+import { writeBatch, WriteBatch } from "firebase/firestore";
+
+import { FirebaseError } from "firebase/app";
+import { useFirestore } from "./useFirestore";
+
+export type UseBatchWriteVariables = (batch: WriteBatch) => Promise<void> | void;
+
+export type UseBatchWriteOptions<TContext = unknown> = {
+    options?: Omit<UseMutationOptions<void, FirebaseError, 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 const useBatchWrite = <TContext = unknown>({ options = {} }: UseBatchWriteOptions<TContext> = {}) => {
+    const db = useFirestore();
+
+    return useMutation({
+        ...options,
+        mutationFn: async (batchWriteFn) => {
+            const batch = writeBatch(db);
+            await batchWriteFn(batch);
+            return batch.commit();
+        }
+    });
+};

package/web/firestore/useCollectionReference.d.ts

@@ -0,0 +1,18 @@
+import { CollectionReference, DocumentData, DocumentReference } from "firebase/firestore";
+export type UseCollectionReferenceOptions<AppModelType, DbModelType extends DocumentData = DocumentData> = {
+    reference?: CollectionReference<AppModelType, DbModelType> | DocumentReference<AppModelType, DbModelType>;
+    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, DbModelType>} 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, DbModelType extends DocumentData = DocumentData>({ path, reference, pathSegments }: UseCollectionReferenceOptions<AppModelType, DbModelType>) => CollectionReference<DocumentData, DocumentData>;

package/web/firestore/useCollectionReference.js

@@ -0,0 +1,24 @@
+import { collection } from "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, DbModelType>} 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 || []))
+            : reference.type === "collection"
+                ? collection(reference, path, ...(pathSegments || []))
+                : collection(reference, path, ...(pathSegments || []));
+    }, [path, reference?.path, pathSegments]);
+};

package/web/firestore/useCollectionReference.ts

@@ -0,0 +1,37 @@
+import { collection, CollectionReference, DocumentData, DocumentReference } from "firebase/firestore";
+
+import { useMemo } from "react";
+import { useFirestore } from "./useFirestore";
+
+export type UseCollectionReferenceOptions<AppModelType, DbModelType extends DocumentData = DocumentData> = {
+    reference?: CollectionReference<AppModelType, DbModelType> | DocumentReference<AppModelType, DbModelType>;
+    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, DbModelType>} 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 = <AppModelType, DbModelType extends DocumentData = DocumentData>({
+    path,
+    reference,
+    pathSegments
+}: UseCollectionReferenceOptions<AppModelType, DbModelType>) => {
+    const db = useFirestore();
+
+    return useMemo(() => {
+        return !reference
+            ? collection(db, path || "", ...(pathSegments || []))
+            : reference.type === "collection"
+              ? collection(reference, path, ...(pathSegments || []))
+              : collection(reference, path, ...(pathSegments || []));
+    }, [path, reference?.path, pathSegments]);
+};

package/web/firestore/useCompositeFilter.d.ts

@@ -0,0 +1,30 @@
+import { DocumentData, QueryCompositeFilterConstraint, WhereFilterOp } from "firebase/firestore";
+type CompositeFilterDocumentData = DocumentData;
+export type QueryElement<DbModelType extends CompositeFilterDocumentData = CompositeFilterDocumentData> = Partial<QueryCompositeFilterConstraint> & {
+    children?: QueryElement[];
+    field?: keyof (DbModelType & {
+        documentId?: string[];
+    });
+    value?: DbModelType[keyof DbModelType];
+    op?: WhereFilterOp;
+};
+export type CompositeFilter<DbModelType extends CompositeFilterDocumentData = CompositeFilterDocumentData> = QueryCompositeFilterConstraint & {
+    children: QueryElement<DbModelType & {
+        documentId?: string[];
+    }>[];
+};
+export type UseCompositeFilter<DbModelType extends CompositeFilterDocumentData = CompositeFilterDocumentData> = {
+    query?: CompositeFilter<DbModelType>;
+};
+/**
+ * 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>) => QueryCompositeFilterConstraint | undefined;
+export {};

package/web/firestore/useCompositeFilter.js

@@ -0,0 +1,43 @@
+import { and, documentId, or, where } from "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 {QueryFilterConstraint | null} A constructed query filter constraint based on the input query, or null if no valid constraints can be derived.
+ */
+const buildCompositeQuery = (query) => {
+    if (query.children) {
+        const queryConstraints = query.children
+            .map((subQuery) => buildCompositeQuery(subQuery))
+            .filter((constraint) => !!constraint);
+        if (queryConstraints.length <= 0) {
+            return null;
+        }
+        return query.type === "or" ? or(...queryConstraints) : and(...queryConstraints);
+    }
+    if (query.field && query.op) {
+        return where(query.field === "documentId" ? 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) => buildCompositeQuery(subQuery))?.filter)?.((constraint) => !!constraint) ?? [];
+        if (queryConstraints.length <= 0) {
+            return undefined;
+        }
+        return query?.type === "or" ? or(...queryConstraints) : and(...queryConstraints);
+    }, [query]);
+};

package/web/firestore/useCompositeFilter.ts

@@ -0,0 +1,86 @@
+import {
+    DocumentData,
+    QueryCompositeFilterConstraint,
+    QueryFilterConstraint,
+    WhereFilterOp,
+    and,
+    documentId,
+    or,
+    where
+} from "firebase/firestore";
+import { useMemo } from "react";
+
+type CompositeFilterDocumentData = DocumentData;
+
+export type QueryElement<DbModelType extends CompositeFilterDocumentData = CompositeFilterDocumentData> =
+    Partial<QueryCompositeFilterConstraint> & {
+        children?: QueryElement[];
+        field?: keyof (DbModelType & { documentId?: string[] });
+        value?: DbModelType[keyof DbModelType];
+        op?: WhereFilterOp;
+    };
+
+export type CompositeFilter<DbModelType extends CompositeFilterDocumentData = CompositeFilterDocumentData> =
+    QueryCompositeFilterConstraint & {
+        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 {QueryFilterConstraint | null} A constructed query filter constraint based on the input query, or null if no valid constraints can be derived.
+ */
+
+const buildCompositeQuery = <DbModelType extends CompositeFilterDocumentData = CompositeFilterDocumentData>(
+    query: QueryElement<DbModelType>
+): QueryFilterConstraint | null => {
+    if (query.children) {
+        const queryConstraints = query.children
+            .map((subQuery) => buildCompositeQuery(subQuery))
+            .filter<QueryFilterConstraint>((constraint) => !!constraint);
+
+        if (queryConstraints.length <= 0) {
+            return null;
+        }
+
+        return (query as CompositeFilter).type === "or" ? or(...queryConstraints) : and(...queryConstraints);
+    }
+
+    if (query.field && query.op) {
+        return where(query.field === "documentId" ? documentId() : (query.field as string), 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 = <DbModelType extends CompositeFilterDocumentData = CompositeFilterDocumentData>({
+    query
+}: UseCompositeFilter<DbModelType>) => {
+    return useMemo(() => {
+        const queryConstraints =
+            query?.children?.map?.((subQuery) => buildCompositeQuery(subQuery))?.filter<QueryFilterConstraint>?.(
+                (constraint) => !!constraint
+            ) ?? [];
+
+        if (queryConstraints.length <= 0) {
+            return undefined;
+        }
+        return query?.type === "or" ? or(...queryConstraints) : and(...queryConstraints);
+    }, [query]);
+};

package/web/firestore/useCountQuery.d.ts

@@ -0,0 +1,23 @@
+import { DocumentData, Query, QueryCompositeFilterConstraint, QueryConstraint, QueryNonFilterConstraint } from "firebase/firestore";
+import { UseQueryResult, UseQueryOptions as UseReactQueryOptions } from "@tanstack/react-query";
+type UseCountQueryOptions<AppModelType extends DocumentData = DocumentData, DbModelType extends DocumentData = DocumentData> = {
+    options: Omit<UseReactQueryOptions<number, Error, number>, "queryFn"> & Required<Pick<UseReactQueryOptions<number, Error, number>, "queryKey">>;
+    query: Query<AppModelType, DbModelType>;
+    queryConstraints?: QueryConstraint[] | QueryNonFilterConstraint[];
+    compositeFilter?: 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, DbModelType>} options - Configuration options for the query.
+ * @param {AppModelType extends DocumentData = 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 DocumentData = DocumentData, DbModelType extends DocumentData = DocumentData>({ options, query: queryReference, queryConstraints, compositeFilter }: UseCountQueryOptions<AppModelType, DbModelType>) => UseQueryResult<number>;
+export {};

package/web/firestore/useCountQuery.js

@@ -0,0 +1,30 @@
+import { getCountFromServer, query } from "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, DbModelType>} options - Configuration options for the query.
+ * @param {AppModelType extends DocumentData = 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, query: queryReference, queryConstraints = [], compositeFilter }) => {
+    return useReactQuery({
+        ...options,
+        queryFn: async () => {
+            const queryToExecute = compositeFilter
+                ? query(queryReference, compositeFilter, ...queryConstraints)
+                : query(queryReference, ...queryConstraints);
+            const querySnapshot = await getCountFromServer(queryToExecute);
+            if (querySnapshot) {
+                return querySnapshot.data().count;
+            }
+            return 0;
+        }
+    });
+};

package/web/firestore/useCountQuery.ts

@@ -0,0 +1,65 @@
+import {
+    DocumentData,
+    getCountFromServer,
+    Query,
+    query,
+    QueryCompositeFilterConstraint,
+    QueryConstraint,
+    QueryNonFilterConstraint
+} from "firebase/firestore";
+
+import {
+    UseQueryResult,
+    useQuery as useReactQuery,
+    UseQueryOptions as UseReactQueryOptions
+} from "@tanstack/react-query";
+
+type UseCountQueryOptions<
+    AppModelType extends DocumentData = DocumentData,
+    DbModelType extends DocumentData = DocumentData
+> = {
+    options: Omit<UseReactQueryOptions<number, Error, number>, "queryFn"> &
+        Required<Pick<UseReactQueryOptions<number, Error, number>, "queryKey">>;
+    query: Query<AppModelType, DbModelType>;
+    queryConstraints?: QueryConstraint[] | QueryNonFilterConstraint[];
+    compositeFilter?: 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, DbModelType>} options - Configuration options for the query.
+ * @param {AppModelType extends DocumentData = 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 = <
+    AppModelType extends DocumentData = DocumentData,
+    DbModelType extends DocumentData = DocumentData
+>({
+    options,
+    query: queryReference,
+    queryConstraints = [],
+    compositeFilter
+}: UseCountQueryOptions<AppModelType, DbModelType>): UseQueryResult<number> => {
+    return useReactQuery({
+        ...options,
+        queryFn: async () => {
+            const queryToExecute = compositeFilter
+                ? query(queryReference, compositeFilter, ...(queryConstraints as QueryNonFilterConstraint[]))
+                : query(queryReference, ...queryConstraints);
+
+            const querySnapshot = await getCountFromServer(queryToExecute);
+            if (querySnapshot) {
+                return querySnapshot.data().count;
+            }
+            return 0;
+        }
+    });
+};

package/web/firestore/useDeleteDocMutation.d.ts

@@ -0,0 +1,18 @@
+import { UseMutationOptions } from "@tanstack/react-query";
+import { DocumentData, WithFieldValue, DocumentReference } from "firebase/firestore";
+import { FirebaseError } from "firebase/app";
+export type UseDeleteDocMutationValues<AppModelType> = {
+    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">;
+};
+/**
+ * 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 DocumentData = DocumentData, DbModelType extends DocumentData = DocumentData, TContext = unknown>({ reference, options }: UseDeleteDocMutationOptions<AppModelType, DbModelType, TContext>) => import("@tanstack/react-query").UseMutationResult<void, FirebaseError, void, TContext>;

package/web/firestore/useDeleteDocMutation.js

@@ -0,0 +1,23 @@
+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.
+ */
+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/web/firestore/useDeleteDocMutation.ts

@@ -0,0 +1,47 @@
+import { useMutation, UseMutationOptions } from "@tanstack/react-query";
+import { DocumentData, deleteDoc, WithFieldValue, DocumentReference } from "firebase/firestore";
+
+import { FirebaseError } from "firebase/app";
+import { useMemo } from "react";
+
+export type UseDeleteDocMutationValues<AppModelType> = {
+    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">;
+};
+
+/**
+ * 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 = <
+    AppModelType extends DocumentData = DocumentData,
+    DbModelType extends DocumentData = DocumentData,
+    TContext = unknown
+>({
+    reference,
+    options = {}
+}: UseDeleteDocMutationOptions<AppModelType, DbModelType, TContext>) => {
+    const mutationKey = useMemo(() => [reference?.path], [reference?.path]);
+
+    return useMutation({
+        ...options,
+        mutationFn: async () => {
+            if (!reference) {
+                throw new Error("Reference is undefined");
+            }
+            await deleteDoc<AppModelType, DbModelType>(reference);
+        },
+        mutationKey
+    });
+};

package/web/firestore/useDocReference.d.ts

@@ -0,0 +1,19 @@
+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[];
+};
+/**
+ * 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, 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, DbModelType> | null} The Firestore document reference corresponding to the provided path and options, or null if not initialized.
+ */
+export declare const useDocReference: <AppModelType, DbModelType extends DocumentData = DocumentData>({ path, reference, pathSegments }: UseDocReferenceOptions<AppModelType, DbModelType>) => DocumentReference<AppModelType, DbModelType> | null;

package/web/firestore/useDocReference.js

@@ -0,0 +1,45 @@
+import { doc } from "firebase/firestore";
+import { useEffect, useRef } 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, 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.
+ */
+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, 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, DbModelType> | 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();
+    const ref = useRef(getDocReference(db, { path, pathSegments, reference }));
+    useEffect(() => {
+        ref.current = getDocReference(db, { path, pathSegments, reference });
+    }, [path, reference, pathSegments]);
+    return ref.current;
+};

package/web/firestore/useDocReference.ts

@@ -0,0 +1,68 @@
+import { doc, CollectionReference, DocumentData, DocumentReference, Firestore } 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[];
+};
+
+/**
+ * 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.
+ */
+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>;
+};
+
+/**
+ * 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, 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, DbModelType> | null} The Firestore document reference corresponding to the provided path and options, or null if not initialized.
+ */
+export const useDocReference = <AppModelType, DbModelType extends DocumentData = DocumentData>({
+    path,
+    reference,
+    pathSegments
+}: UseDocReferenceOptions<AppModelType, DbModelType>) => {
+    const db = useFirestore();
+    const ref = useRef<DocumentReference<AppModelType, DbModelType> | null>(
+        getDocReference(db, { path, pathSegments, reference })
+    );
+
+    useEffect(() => {
+        ref.current = getDocReference(db, { path, pathSegments, reference });
+    }, [path, reference, pathSegments]);
+
+    return ref.current;
+};

package/web/firestore/useDocReferences.d.ts

@@ -0,0 +1,23 @@
+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[];
+};
+/**
+ * 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, 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.
+ */
+export declare const useDocReferences: <AppModelType, DbModelType extends DocumentData = DocumentData>(references: UseDocReferencesOptions<AppModelType, DbModelType>[]) => DocumentReference<AppModelType, DbModelType>[];