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

package/web/firestore/useQuery.ts

@@ -0,0 +1,72 @@
+import {
+    DocumentData,
+    FirestoreDataConverter,
+    getDocs,
+    Query,
+    query,
+    QueryCompositeFilterConstraint,
+    QueryConstraint,
+    QueryNonFilterConstraint
+} from "firebase/firestore";
+
+import {
+    UseQueryResult,
+    useQuery as useReactQuery,
+    UseQueryOptions as UseReactQueryOptions
+} from "@tanstack/react-query";
+
+type UseQueryOptions<
+    AppModelType extends DocumentData = DocumentData,
+    DbModelType extends DocumentData = DocumentData
+> = {
+    options: Omit<UseReactQueryOptions<AppModelType[], Error, AppModelType[]>, "queryFn"> &
+        Required<Pick<UseReactQueryOptions<AppModelType[], Error, AppModelType[]>, "queryKey">>;
+    query: Query<AppModelType, DbModelType>;
+    queryConstraints?: QueryConstraint[] | QueryNonFilterConstraint[];
+    compositeFilter?: QueryCompositeFilterConstraint;
+    converter?: FirestoreDataConverter<AppModelType, DbModelType>;
+};
+
+/**
+ * Executes a query on a Firestore-like data source and returns the resulting documents as an array.
+ *
+ * This hook utilizes an abstraction over React Query to asynchronously fetch data based on the provided query
+ * reference and constraints. It supports optional filtering, conversion, and additional query constraints.
+ *
+ * @param {UseQueryOptions<AppModelType, DbModelType>}  options - Configuration options for the query.
+ * @param {DocumentReference<AppModelType>}  queryReference - The reference to the query to be executed.
+ * @param {QueryConstraint[]}  queryConstraints - Additional constraints to fine-tune the query.
+ * @param {QueryConstraint}  compositeFilter - Optional composite filter to apply to the query.
+ * @param {FirestoreDataConverter<AppModelType>}  converter - Optional data converter for transforming snapshots.
+ *
+ * @returns {UseQueryResult<AppModelType[]>} Result containing an array of documents that match the query criteria.
+ */
+export const useQuery = <
+    AppModelType extends DocumentData = DocumentData,
+    DbModelType extends DocumentData = DocumentData
+>({
+    options,
+    query: queryReference,
+    queryConstraints = [],
+    compositeFilter,
+    converter
+}: UseQueryOptions<AppModelType, DbModelType>): UseQueryResult<AppModelType[]> => {
+    return useReactQuery({
+        ...options,
+        queryFn: async () => {
+            const queryToExecute = compositeFilter
+                ? query(queryReference, compositeFilter, ...(queryConstraints as QueryNonFilterConstraint[]))
+                : query(queryReference, ...queryConstraints);
+
+            const querySnapshot = await getDocs(converter ? queryToExecute.withConverter(converter) : queryToExecute);
+            const docs: AppModelType[] = [];
+
+            if (querySnapshot) {
+                querySnapshot.forEach((doc) => {
+                    docs.push(doc.data());
+                });
+            }
+            return docs;
+        }
+    });
+};

package/web/firestore/useRunTransaction.d.ts

@@ -0,0 +1,15 @@
+import { UseMutationOptions } from "@tanstack/react-query";
+import { Transaction } from "firebase/firestore";
+import { FirebaseError } from "firebase/app";
+export type UseRunTransactionValues = <AppModelType = unknown>(transaction: Transaction) => AppModelType;
+export type UseRunTransactionOptions<AppModelType = unknown, TContext = unknown> = {
+    options?: Omit<UseMutationOptions<AppModelType, FirebaseError, UseRunTransactionValues, TContext>, "mutationFn">;
+};
+/**
+ * Custom hook to execute a Firestore transaction using the useMutation hook.
+ *
+ * @param {UseRunTransactionOptions<AppModelType, TContext>} options - Configuration options for running the transaction.
+ * @param {Object} options.options - Options to customize the behavior of useMutation and runTransaction.
+ * @returns {UseMutationResult} The result object from the useMutation hook, allowing to track the transaction state and outcome.
+ */
+export declare const useRunTransaction: <AppModelType = unknown, TContext = unknown>({ options }: UseRunTransactionOptions<AppModelType, TContext>) => import("@tanstack/react-query").UseMutationResult<AppModelType, FirebaseError, UseRunTransactionValues, TContext>;

package/web/firestore/useRunTransaction.js

@@ -0,0 +1,19 @@
+import { useMutation } from "@tanstack/react-query";
+import { runTransaction } from "firebase/firestore";
+import { useFirestore } from "./useFirestore";
+/**
+ * Custom hook to execute a Firestore transaction using the useMutation hook.
+ *
+ * @param {UseRunTransactionOptions<AppModelType, TContext>} options - Configuration options for running the transaction.
+ * @param {Object} options.options - Options to customize the behavior of useMutation and runTransaction.
+ * @returns {UseMutationResult} The result object from the useMutation hook, allowing to track the transaction state and outcome.
+ */
+export const useRunTransaction = ({ options = {} }) => {
+    const db = useFirestore();
+    return useMutation({
+        ...options,
+        mutationFn: async (transactionFn) => {
+            return runTransaction(db, transactionFn);
+        }
+    });
+};

package/web/firestore/useRunTransaction.ts

@@ -0,0 +1,31 @@
+import { useMutation, UseMutationOptions } from "@tanstack/react-query";
+import { runTransaction, Transaction } from "firebase/firestore";
+
+import { FirebaseError } from "firebase/app";
+import { useFirestore } from "./useFirestore";
+
+export type UseRunTransactionValues = <AppModelType = unknown>(transaction: Transaction) => AppModelType;
+
+export type UseRunTransactionOptions<AppModelType = unknown, TContext = unknown> = {
+    options?: Omit<UseMutationOptions<AppModelType, FirebaseError, UseRunTransactionValues, TContext>, "mutationFn">;
+};
+
+/**
+ * Custom hook to execute a Firestore transaction using the useMutation hook.
+ *
+ * @param {UseRunTransactionOptions<AppModelType, TContext>} options - Configuration options for running the transaction.
+ * @param {Object} options.options - Options to customize the behavior of useMutation and runTransaction.
+ * @returns {UseMutationResult} The result object from the useMutation hook, allowing to track the transaction state and outcome.
+ */
+export const useRunTransaction = <AppModelType = unknown, TContext = unknown>({
+    options = {}
+}: UseRunTransactionOptions<AppModelType, TContext>) => {
+    const db = useFirestore();
+
+    return useMutation({
+        ...options,
+        mutationFn: async (transactionFn) => {
+            return runTransaction<AppModelType>(db, transactionFn);
+        }
+    });
+};

package/web/firestore/useSetDocMutation.d.ts

@@ -0,0 +1,20 @@
+import { UseMutationOptions } from "@tanstack/react-query";
+import { DocumentData, DocumentReference, WithFieldValue } from "firebase/firestore";
+import { FirebaseError } from "firebase/app";
+export type UseSetDocMutationValues<AppModelType> = {
+    data: WithFieldValue<AppModelType>;
+};
+export type UseSetDocMutationOptions<AppModelType = unknown, DbModelType extends DocumentData = DocumentData, TContext = unknown> = {
+    reference: DocumentReference<AppModelType, DbModelType> | null;
+    options?: Omit<UseMutationOptions<void, FirebaseError, UseSetDocMutationValues<AppModelType>, TContext>, "mutationFn" | "mutationKey">;
+};
+/**
+ * Custom hook to create a mutation for setting a document in a Firestore-like database.
+ * The mutation can be configured with options and reference to specific document path.
+ *
+ * @param {UseSetDocMutationOptions<AppModelType, DbModelType, TContext>} param0 - The options for configuring the mutation, including the document reference and additional mutation options.
+ * @param {Object} param0.reference - The reference object that contains the path to the document.
+ * @param {Object} param0.options - Additional options for the mutation, can configure aspects like onSuccess or onError callbacks.
+ * @returns {MutationResult} The result of the mutation operation, which includes states like isLoading, isSuccess, isError, and methods to control the mutation process.
+ */
+export declare const useSetDocMutation: <AppModelType = unknown, DbModelType extends DocumentData = DocumentData, TContext = unknown>({ reference, options }: UseSetDocMutationOptions<AppModelType, DbModelType, TContext>) => import("@tanstack/react-query").UseMutationResult<void, FirebaseError, UseSetDocMutationValues<AppModelType>, TContext>;

package/web/firestore/useSetDocMutation.js

@@ -0,0 +1,25 @@
+import { useMutation } from "@tanstack/react-query";
+import { setDoc } from "firebase/firestore";
+import { useMemo } from "react";
+/**
+ * Custom hook to create a mutation for setting a document in a Firestore-like database.
+ * The mutation can be configured with options and reference to specific document path.
+ *
+ * @param {UseSetDocMutationOptions<AppModelType, DbModelType, TContext>} param0 - The options for configuring the mutation, including the document reference and additional mutation options.
+ * @param {Object} param0.reference - The reference object that contains the path to the document.
+ * @param {Object} param0.options - Additional options for the mutation, can configure aspects like onSuccess or onError callbacks.
+ * @returns {MutationResult} The result of the mutation operation, which includes states like isLoading, isSuccess, isError, and methods to control the mutation process.
+ */
+export const useSetDocMutation = ({ reference, options }) => {
+    const mutationKey = useMemo(() => [reference?.path], [reference?.path]);
+    return useMutation({
+        ...options,
+        mutationFn: ({ data }) => {
+            if (!reference) {
+                throw new Error("Reference is undefined");
+            }
+            return setDoc(reference, data);
+        },
+        mutationKey
+    });
+};

package/web/firestore/useSetDocMutation.ts

@@ -0,0 +1,52 @@
+import { useMutation, UseMutationOptions } from "@tanstack/react-query";
+import { DocumentData, DocumentReference, setDoc, WithFieldValue } from "firebase/firestore";
+
+import { FirebaseError } from "firebase/app";
+import { useMemo } from "react";
+
+export type UseSetDocMutationValues<AppModelType> = {
+    data: WithFieldValue<AppModelType>;
+};
+
+export type UseSetDocMutationOptions<
+    AppModelType = unknown,
+    DbModelType extends DocumentData = DocumentData,
+    TContext = unknown
+> = {
+    reference: DocumentReference<AppModelType, DbModelType> | null;
+    options?: Omit<
+        UseMutationOptions<void, FirebaseError, UseSetDocMutationValues<AppModelType>, TContext>,
+        "mutationFn" | "mutationKey"
+    >;
+};
+
+/**
+ * Custom hook to create a mutation for setting a document in a Firestore-like database.
+ * The mutation can be configured with options and reference to specific document path.
+ *
+ * @param {UseSetDocMutationOptions<AppModelType, DbModelType, TContext>} param0 - The options for configuring the mutation, including the document reference and additional mutation options.
+ * @param {Object} param0.reference - The reference object that contains the path to the document.
+ * @param {Object} param0.options - Additional options for the mutation, can configure aspects like onSuccess or onError callbacks.
+ * @returns {MutationResult} The result of the mutation operation, which includes states like isLoading, isSuccess, isError, and methods to control the mutation process.
+ */
+export const useSetDocMutation = <
+    AppModelType = unknown,
+    DbModelType extends DocumentData = DocumentData,
+    TContext = unknown
+>({
+    reference,
+    options
+}: UseSetDocMutationOptions<AppModelType, DbModelType, TContext>) => {
+    const mutationKey = useMemo(() => [reference?.path], [reference?.path]);
+
+    return useMutation({
+        ...options,
+        mutationFn: ({ data }) => {
+            if (!reference) {
+                throw new Error("Reference is undefined");
+            }
+            return setDoc<AppModelType, DbModelType>(reference, data);
+        },
+        mutationKey
+    });
+};

package/web/firestore/useUpdateDocMutation.d.ts

@@ -0,0 +1,31 @@
+import { UseMutationOptions } from "@tanstack/react-query";
+import { DocumentData, FirestoreDataConverter, DocumentReference, UpdateData } from "firebase/firestore";
+import { FirebaseError } from "firebase/app";
+export type UseUpdateDocMutationValues<DbModelType> = {
+    data: UpdateData<DbModelType>;
+};
+export type UseUpdateDocMutationOptions<AppModelType extends DocumentData = DocumentData, DbModelType extends DocumentData = DocumentData, TContext = unknown> = {
+    reference: DocumentReference<AppModelType, DbModelType> | null;
+    converter?: FirestoreDataConverter<AppModelType, DbModelType>;
+    options?: Omit<UseMutationOptions<AppModelType, FirebaseError, UseUpdateDocMutationValues<DbModelType>, TContext>, "mutationFn" | "mutationKey">;
+};
+/**
+ * Custom hook that sets up a mutation for updating a document in a Firestore database.
+ *
+ * This hook utilizes `useMutation` for performing asynchronous operations to update the document
+ * and retrieve the latest data snapshot. The update functionality can be configured with a custom
+ * converter if needed.
+ *
+ * @param {UseUpdateDocMutationOptions<AppModelType, DbModelType, TContext>} options - Configuration options for the mutation,
+ * including Firestore reference, an optional Firestore data converter, and additional mutation options.
+ *
+ * `reference` - The Firestore document reference that identifies the document to be updated.
+ *
+ * `converter` - An optional Firestore converter for transforming the database response into a custom type.
+ *
+ * `options` - Additional options that customize the mutation's behavior.
+ *
+ * @returns {UseMutationResult<AppModelType, Error, {data: AppModelType}, TContext>} An object returned by `useMutation`
+ * which includes functions to start the mutation and properties that represent the different states of the mutation.
+ */
+export declare const useUpdateDocMutation: <AppModelType extends DocumentData = DocumentData, DbModelType extends DocumentData = DocumentData, TContext = unknown>({ reference, converter, options }: UseUpdateDocMutationOptions<AppModelType, DbModelType, TContext>) => import("@tanstack/react-query").UseMutationResult<AppModelType, FirebaseError, UseUpdateDocMutationValues<DbModelType>, TContext>;

package/web/firestore/useUpdateDocMutation.js

@@ -0,0 +1,37 @@
+import { useMutation } from "@tanstack/react-query";
+import { updateDoc, getDoc } from "firebase/firestore";
+import { useMemo } from "react";
+/**
+ * Custom hook that sets up a mutation for updating a document in a Firestore database.
+ *
+ * This hook utilizes `useMutation` for performing asynchronous operations to update the document
+ * and retrieve the latest data snapshot. The update functionality can be configured with a custom
+ * converter if needed.
+ *
+ * @param {UseUpdateDocMutationOptions<AppModelType, DbModelType, TContext>} options - Configuration options for the mutation,
+ * including Firestore reference, an optional Firestore data converter, and additional mutation options.
+ *
+ * `reference` - The Firestore document reference that identifies the document to be updated.
+ *
+ * `converter` - An optional Firestore converter for transforming the database response into a custom type.
+ *
+ * `options` - Additional options that customize the mutation's behavior.
+ *
+ * @returns {UseMutationResult<AppModelType, Error, {data: AppModelType}, TContext>} An object returned by `useMutation`
+ * which includes functions to start the mutation and properties that represent the different states of the mutation.
+ */
+export const useUpdateDocMutation = ({ reference, converter, options = {} }) => {
+    const mutationKey = useMemo(() => [reference?.path], [reference?.path]);
+    return useMutation({
+        ...options,
+        mutationFn: async ({ data }) => {
+            if (!reference) {
+                throw new Error("Reference is undefined");
+            }
+            await updateDoc(reference, data);
+            const docSnap = await getDoc(converter ? reference.withConverter(converter) : reference);
+            return docSnap.data();
+        },
+        mutationKey
+    });
+};

package/web/firestore/useUpdateDocMutation.ts

@@ -0,0 +1,74 @@
+import { useMutation, UseMutationOptions } from "@tanstack/react-query";
+import {
+    DocumentData,
+    updateDoc,
+    getDoc,
+    FirestoreDataConverter,
+    DocumentReference,
+    UpdateData
+} from "firebase/firestore";
+
+import { FirebaseError } from "firebase/app";
+import { useMemo } from "react";
+
+export type UseUpdateDocMutationValues<DbModelType> = {
+    data: UpdateData<DbModelType>;
+};
+
+export type UseUpdateDocMutationOptions<
+    AppModelType extends DocumentData = DocumentData,
+    DbModelType extends DocumentData = DocumentData,
+    TContext = unknown
+> = {
+    reference: DocumentReference<AppModelType, DbModelType> | null;
+    converter?: FirestoreDataConverter<AppModelType, DbModelType>;
+    options?: Omit<
+        UseMutationOptions<AppModelType, FirebaseError, UseUpdateDocMutationValues<DbModelType>, TContext>,
+        "mutationFn" | "mutationKey"
+    >;
+};
+
+/**
+ * Custom hook that sets up a mutation for updating a document in a Firestore database.
+ *
+ * This hook utilizes `useMutation` for performing asynchronous operations to update the document
+ * and retrieve the latest data snapshot. The update functionality can be configured with a custom
+ * converter if needed.
+ *
+ * @param {UseUpdateDocMutationOptions<AppModelType, DbModelType, TContext>} options - Configuration options for the mutation,
+ * including Firestore reference, an optional Firestore data converter, and additional mutation options.
+ *
+ * `reference` - The Firestore document reference that identifies the document to be updated.
+ *
+ * `converter` - An optional Firestore converter for transforming the database response into a custom type.
+ *
+ * `options` - Additional options that customize the mutation's behavior.
+ *
+ * @returns {UseMutationResult<AppModelType, Error, {data: AppModelType}, TContext>} An object returned by `useMutation`
+ * which includes functions to start the mutation and properties that represent the different states of the mutation.
+ */
+export const useUpdateDocMutation = <
+    AppModelType extends DocumentData = DocumentData,
+    DbModelType extends DocumentData = DocumentData,
+    TContext = unknown
+>({
+    reference,
+    converter,
+    options = {}
+}: UseUpdateDocMutationOptions<AppModelType, DbModelType, TContext>) => {
+    const mutationKey = useMemo(() => [reference?.path], [reference?.path]);
+
+    return useMutation({
+        ...options,
+        mutationFn: async ({ data }) => {
+            if (!reference) {
+                throw new Error("Reference is undefined");
+            }
+
+            await updateDoc<AppModelType, DbModelType>(reference, data);
+            const docSnap = await getDoc(converter ? reference.withConverter(converter) : reference);
+            return docSnap.data() as AppModelType;
+        },
+        mutationKey
+    });
+};

package/web/firestore/utils/getDocData.d.ts

@@ -0,0 +1,18 @@
+import { DocumentData } from "firebase/firestore";
+import { GetDocSnapOptions } from "./getDocSnap";
+export type GetDocDataOptions<AppModelType extends DocumentData = DocumentData, DbModelType extends DocumentData = DocumentData> = GetDocSnapOptions<AppModelType, DbModelType>;
+/**
+ * Asynchronously retrieves document data from a specified database and reference.
+ * Utilizes the helper function `getDocSnap` to fetch the document snapshot and
+ * checks if the document exists before returning its data.
+ *
+ * @param {Object} options - The options for fetching document data.
+ * @param {FirebaseFirestore} options.db - The Firestore database instance.
+ * @param {DocumentReference=} options.reference - The document reference. This is an optional parameter.
+ * @param {string=} options.path - The path to the document in the database. This is an optional parameter.
+ * @param {Array<string>=} options.pathSegments - The path segments for the document's path. This is an optional parameter.
+ *
+ * @returns {Promise<AppModelType | null>} Returns a promise that resolves to the document data if it exists,
+ * or null if the document does not exist.
+ */
+export declare const getDocData: <AppModelType extends DocumentData = DocumentData, DbModelType extends DocumentData = DocumentData>({ db, reference, path, pathSegments }: GetDocDataOptions<AppModelType, DbModelType>) => Promise<AppModelType | null>;

package/web/firestore/utils/getDocData.js

@@ -0,0 +1,22 @@
+import { getDocSnap } from "./getDocSnap";
+/**
+ * Asynchronously retrieves document data from a specified database and reference.
+ * Utilizes the helper function `getDocSnap` to fetch the document snapshot and
+ * checks if the document exists before returning its data.
+ *
+ * @param {Object} options - The options for fetching document data.
+ * @param {FirebaseFirestore} options.db - The Firestore database instance.
+ * @param {DocumentReference=} options.reference - The document reference. This is an optional parameter.
+ * @param {string=} options.path - The path to the document in the database. This is an optional parameter.
+ * @param {Array<string>=} options.pathSegments - The path segments for the document's path. This is an optional parameter.
+ *
+ * @returns {Promise<AppModelType | null>} Returns a promise that resolves to the document data if it exists,
+ * or null if the document does not exist.
+ */
+export const getDocData = async ({ db, reference, path, pathSegments }) => {
+    const docSnap = await getDocSnap({ db, reference, path, pathSegments });
+    if (docSnap && docSnap.exists()) {
+        return docSnap.data();
+    }
+    return null;
+};

package/web/firestore/utils/getDocData.ts

@@ -0,0 +1,39 @@
+import { DocumentData } from "firebase/firestore";
+import { getDocSnap, GetDocSnapOptions } from "./getDocSnap";
+
+export type GetDocDataOptions<
+    AppModelType extends DocumentData = DocumentData,
+    DbModelType extends DocumentData = DocumentData
+> = GetDocSnapOptions<AppModelType, DbModelType>;
+
+/**
+ * Asynchronously retrieves document data from a specified database and reference.
+ * Utilizes the helper function `getDocSnap` to fetch the document snapshot and
+ * checks if the document exists before returning its data.
+ *
+ * @param {Object} options - The options for fetching document data.
+ * @param {FirebaseFirestore} options.db - The Firestore database instance.
+ * @param {DocumentReference=} options.reference - The document reference. This is an optional parameter.
+ * @param {string=} options.path - The path to the document in the database. This is an optional parameter.
+ * @param {Array<string>=} options.pathSegments - The path segments for the document's path. This is an optional parameter.
+ *
+ * @returns {Promise<AppModelType | null>} Returns a promise that resolves to the document data if it exists,
+ * or null if the document does not exist.
+ */
+export const getDocData = async <
+    AppModelType extends DocumentData = DocumentData,
+    DbModelType extends DocumentData = DocumentData
+>({
+    db,
+    reference,
+    path,
+    pathSegments
+}: GetDocDataOptions<AppModelType, DbModelType>) => {
+    const docSnap = await getDocSnap<AppModelType, DbModelType>({ db, reference, path, pathSegments });
+
+    if (docSnap && docSnap.exists()) {
+        return docSnap.data();
+    }
+
+    return null;
+};

package/web/firestore/utils/getDocRef.d.ts

@@ -0,0 +1,19 @@
+import { CollectionReference, DocumentData, DocumentReference, Firestore } from "firebase/firestore";
+export type GetDocRefOptions<AppModelType extends DocumentData = DocumentData, DbModelType extends DocumentData = DocumentData> = {
+    db: Firestore;
+    reference?: CollectionReference<AppModelType, DbModelType> | DocumentReference<AppModelType, DbModelType>;
+    path?: string;
+    pathSegments?: string[];
+};
+/**
+ * Retrieves a document reference based on provided database options.
+ * Either `reference` or `path` must be provided, not both.
+ *
+ * @param {Object} options - The options for getting a document reference.
+ * @param {Firestore} options.db - The Firestore database instance.
+ * @param {DocumentReference | CollectionReference | null} [options.reference] - Reference to a document or collection.
+ * @param {string | null} [options.path] - Path to the document.
+ * @param {string[] | null} [options.pathSegments] - Additional path segments if any.
+ * @returns {DocumentReference<AppModelType, DbModelType>} The document reference.
+ */
+export declare const getDocRef: <AppModelType extends DocumentData = DocumentData, DbModelType extends DocumentData = DocumentData>({ db, reference, path, pathSegments }: GetDocRefOptions<AppModelType, DbModelType>) => Promise<DocumentReference<AppModelType, DbModelType>>;

package/web/firestore/utils/getDocRef.js

@@ -0,0 +1,25 @@
+import { doc } from "firebase/firestore";
+/**
+ * Retrieves a document reference based on provided database options.
+ * Either `reference` or `path` must be provided, not both.
+ *
+ * @param {Object} options - The options for getting a document reference.
+ * @param {Firestore} options.db - The Firestore database instance.
+ * @param {DocumentReference | CollectionReference | null} [options.reference] - Reference to a document or collection.
+ * @param {string | null} [options.path] - Path to the document.
+ * @param {string[] | null} [options.pathSegments] - Additional path segments if any.
+ * @returns {DocumentReference<AppModelType, DbModelType>} The document reference.
+ */
+export const getDocRef = async ({ db, reference, path, pathSegments }) => {
+    if (!reference && !path) {
+        throw new Error("One of the options must be provided: path or reference.");
+    }
+    const docRef = !reference
+        ? doc(db, path, ...(pathSegments || []))
+        : reference.type === "collection"
+            ? doc(reference, path, ...(pathSegments || []))
+            : reference.type === "document"
+                ? doc(reference, path, ...(pathSegments || []))
+                : null;
+    return docRef;
+};

package/web/firestore/utils/getDocRef.ts

@@ -0,0 +1,46 @@
+import { CollectionReference, doc, DocumentData, DocumentReference, Firestore } from "firebase/firestore";
+
+export type GetDocRefOptions<
+    AppModelType extends DocumentData = DocumentData,
+    DbModelType extends DocumentData = DocumentData
+> = {
+    db: Firestore;
+    reference?: CollectionReference<AppModelType, DbModelType> | DocumentReference<AppModelType, DbModelType>;
+    path?: string;
+    pathSegments?: string[];
+};
+
+/**
+ * Retrieves a document reference based on provided database options.
+ * Either `reference` or `path` must be provided, not both.
+ *
+ * @param {Object} options - The options for getting a document reference.
+ * @param {Firestore} options.db - The Firestore database instance.
+ * @param {DocumentReference | CollectionReference | null} [options.reference] - Reference to a document or collection.
+ * @param {string | null} [options.path] - Path to the document.
+ * @param {string[] | null} [options.pathSegments] - Additional path segments if any.
+ * @returns {DocumentReference<AppModelType, DbModelType>} The document reference.
+ */
+export const getDocRef = async <
+    AppModelType extends DocumentData = DocumentData,
+    DbModelType extends DocumentData = DocumentData
+>({
+    db,
+    reference,
+    path,
+    pathSegments
+}: GetDocRefOptions<AppModelType, DbModelType>) => {
+    if (!reference && !path) {
+        throw new Error("One of the options must be provided: path or reference.");
+    }
+
+    const docRef = !reference
+        ? doc(db, path as string, ...(pathSegments || []))
+        : reference.type === "collection"
+          ? doc(reference, path, ...(pathSegments || []))
+          : reference.type === "document"
+            ? doc(reference, path as string, ...(pathSegments || []))
+            : null;
+
+    return docRef as DocumentReference<AppModelType, DbModelType>;
+};

package/web/firestore/utils/getDocSnap.d.ts

@@ -0,0 +1,20 @@
+import { DocumentData } from "firebase/firestore";
+import { GetDocRefOptions } from "./getDocRef";
+export type GetDocSnapOptions<AppModelType extends DocumentData = DocumentData, DbModelType extends DocumentData = DocumentData> = GetDocRefOptions<AppModelType, DbModelType>;
+/**
+ * Asynchronously retrieves a document snapshot from Firestore using a specified document reference
+ * or path information. This function handles getting the appropriate document reference based on
+ * the parameters provided, and then fetches the document data from Firestore.
+ *
+ * @param {GetDocSnapOptions<AppModelType, DbModelType>} options - An object containing options
+ *                                                                for retrieving the document
+ *                                                                snapshot.
+ * @param {DocumentData} options.db - The Firestore database instance to perform the operation on.
+ * @param {string} options.reference - A string representing a direct Firestore document reference.
+ * @param {string} options.path - A Firestore path string leading to the document.
+ * @param {string[]} options.pathSegments - An array of path segments to build the Firestore path.
+ * @returns {Promise<DocumentData | null>} A promise that resolves to the document data if the
+ *                                         document exists, or `null` if the document does not exist
+ *                                         or if the reference could not be obtained.
+ */
+export declare const getDocSnap: <AppModelType extends DocumentData = DocumentData, DbModelType extends DocumentData = DocumentData>({ db, reference, path, pathSegments }: GetDocSnapOptions<AppModelType, DbModelType>) => Promise<import("@firebase/firestore").DocumentSnapshot<AppModelType, DbModelType> | null>;

package/web/firestore/utils/getDocSnap.js

@@ -0,0 +1,25 @@
+import { getDoc as firestoreGetDoc } from "firebase/firestore";
+import { getDocRef } from "./getDocRef";
+/**
+ * Asynchronously retrieves a document snapshot from Firestore using a specified document reference
+ * or path information. This function handles getting the appropriate document reference based on
+ * the parameters provided, and then fetches the document data from Firestore.
+ *
+ * @param {GetDocSnapOptions<AppModelType, DbModelType>} options - An object containing options
+ *                                                                for retrieving the document
+ *                                                                snapshot.
+ * @param {DocumentData} options.db - The Firestore database instance to perform the operation on.
+ * @param {string} options.reference - A string representing a direct Firestore document reference.
+ * @param {string} options.path - A Firestore path string leading to the document.
+ * @param {string[]} options.pathSegments - An array of path segments to build the Firestore path.
+ * @returns {Promise<DocumentData | null>} A promise that resolves to the document data if the
+ *                                         document exists, or `null` if the document does not exist
+ *                                         or if the reference could not be obtained.
+ */
+export const getDocSnap = async ({ db, reference, path, pathSegments }) => {
+    const docRef = await getDocRef({ db, reference, path, pathSegments });
+    if (docRef) {
+        return await firestoreGetDoc(docRef);
+    }
+    return null;
+};

package/web/firestore/utils/getDocSnap.ts

@@ -0,0 +1,41 @@
+import { DocumentData, getDoc as firestoreGetDoc } from "firebase/firestore";
+import { getDocRef, GetDocRefOptions } from "./getDocRef";
+
+export type GetDocSnapOptions<
+    AppModelType extends DocumentData = DocumentData,
+    DbModelType extends DocumentData = DocumentData
+> = GetDocRefOptions<AppModelType, DbModelType>;
+
+/**
+ * Asynchronously retrieves a document snapshot from Firestore using a specified document reference
+ * or path information. This function handles getting the appropriate document reference based on
+ * the parameters provided, and then fetches the document data from Firestore.
+ *
+ * @param {GetDocSnapOptions<AppModelType, DbModelType>} options - An object containing options
+ *                                                                for retrieving the document
+ *                                                                snapshot.
+ * @param {DocumentData} options.db - The Firestore database instance to perform the operation on.
+ * @param {string} options.reference - A string representing a direct Firestore document reference.
+ * @param {string} options.path - A Firestore path string leading to the document.
+ * @param {string[]} options.pathSegments - An array of path segments to build the Firestore path.
+ * @returns {Promise<DocumentData | null>} A promise that resolves to the document data if the
+ *                                         document exists, or `null` if the document does not exist
+ *                                         or if the reference could not be obtained.
+ */
+export const getDocSnap = async <
+    AppModelType extends DocumentData = DocumentData,
+    DbModelType extends DocumentData = DocumentData
+>({
+    db,
+    reference,
+    path,
+    pathSegments
+}: GetDocSnapOptions<AppModelType, DbModelType>) => {
+    const docRef = await getDocRef<AppModelType, DbModelType>({ db, reference, path, pathSegments });
+
+    if (docRef) {
+        return await firestoreGetDoc(docRef);
+    }
+
+    return null;
+};