react-query-firebase 2.1.1 → 2.1.3

package/web/firestore/useFirestore.d.ts

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

package/web/firestore/useFirestore.js

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

package/web/firestore/useGetDocData.d.ts

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

package/web/firestore/useGetDocData.js

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

package/web/firestore/useGetRealtimeDocData.d.ts

@@ -0,0 +1,57 @@
+import { CollectionReference, DocumentData, DocumentReference } from "firebase/firestore";
+import { FirebaseError } from "firebase/app";
+/**
+ * @inline
+ */
+export type UseGetRealtimeDocDataOptions<AppModelType, DbModelType extends DocumentData = DocumentData> = {
+    /**
+     * A slash-separated path to a document. Has to be omitted to use
+     */
+    path?: string;
+    /**
+     * A reference to a collection.
+     */
+    reference?: CollectionReference<AppModelType, DbModelType> | DocumentReference<AppModelType, DbModelType>;
+    /**
+     * Additional path segments that will be applied relative
+     * to the first argument.
+     */
+    pathSegments?: string[];
+    /**
+     * A callback to be called if the listen fails or is
+     * cancelled. No further callbacks will occur.
+     */
+    onError?: (error: FirebaseError) => unknown;
+};
+/**
+ * @inline
+ */
+export type UseGetRealtimeDocDataResult<AppModelType> = {
+    data: AppModelType | null;
+    isError: boolean;
+    error: FirebaseError | null;
+    isFetching: boolean;
+};
+/**
+ * A hook to get realtime updates to a firestore document.
+ *
+ * @group Hook
+ *
+ * @param {UseGetRealtimeDocDataOptions<AppModelType, DbModelType>} options
+ *
+ * @returns {UseGetRealtimeDocDataResult<AppModelType>}
+ *
+ * @example
+ * ```jsx
+ * const firebaseConfig = {};
+ * export const MyComponent = () => {
+ *  const result = useGetRealtimeDocData('collection/documentId');
+ *  return (
+ *      <div>
+ *          {JSON.stringify(result)}
+ *      </div>
+ *  );
+ * };
+ * ```
+ */
+export declare const useGetRealtimeDocData: <AppModelType, DbModelType extends DocumentData = DocumentData>({ path, pathSegments, reference, onError }: UseGetRealtimeDocDataOptions<AppModelType, DbModelType>) => UseGetRealtimeDocDataResult<AppModelType>;

package/web/firestore/useGetRealtimeDocData.js

@@ -0,0 +1,56 @@
+import { onSnapshot } from "firebase/firestore";
+import { useEffect, useMemo, useState } from "react";
+import { useDocReference } from "./useDocReference";
+/**
+ * A hook to get realtime updates to a firestore document.
+ *
+ * @group Hook
+ *
+ * @param {UseGetRealtimeDocDataOptions<AppModelType, DbModelType>} options
+ *
+ * @returns {UseGetRealtimeDocDataResult<AppModelType>}
+ *
+ * @example
+ * ```jsx
+ * const firebaseConfig = {};
+ * export const MyComponent = () => {
+ *  const result = useGetRealtimeDocData('collection/documentId');
+ *  return (
+ *      <div>
+ *          {JSON.stringify(result)}
+ *      </div>
+ *  );
+ * };
+ * ```
+ */
+export const useGetRealtimeDocData = ({ path, pathSegments, reference, onError }) => {
+    const ref = useDocReference({ path, reference, pathSegments });
+    const [doc, setDoc] = useState(null);
+    const [isError, setIsError] = useState(false);
+    const [isFetching, setIsFetching] = useState(true);
+    const [error, setError] = useState(null);
+    useEffect(() => {
+        const unsubscribe = ref
+            ? onSnapshot(ref, {
+                next: async (snapshot) => {
+                    setIsFetching(false);
+                    setDoc(snapshot.data() || null);
+                    setError(null);
+                    setIsError(false);
+                },
+                error: (e) => {
+                    setIsError(true);
+                    setError(e);
+                    onError?.(e);
+                }
+            })
+            : () => { };
+        return () => unsubscribe();
+    }, [ref, doc, isError, onError, isFetching, error]);
+    return useMemo(() => ({
+        data: doc,
+        isError,
+        isFetching,
+        error
+    }), [doc, isError, error, isFetching]);
+};

package/web/firestore/useInfiniteQuery.d.ts

@@ -0,0 +1,18 @@
+import { CollectionReference, DocumentData, FirestoreDataConverter, QueryCompositeFilterConstraint, QueryConstraint, QueryNonFilterConstraint } from "firebase/firestore";
+import { UseInfiniteQueryOptions as UseReactInfiniteQueryOptions, QueryKey, UseInfiniteQueryResult, InfiniteData } from "@tanstack/react-query";
+type UseInfiniteQueryOptions<AppModelType extends DocumentData = DocumentData, DbModelType extends DocumentData = DocumentData, TQueryKey extends QueryKey = QueryKey> = {
+    options: Omit<UseReactInfiniteQueryOptions<AppModelType[], Error, InfiniteData<AppModelType[]>, AppModelType[], TQueryKey, QueryConstraint>, "queryFn"> & Required<Pick<UseReactInfiniteQueryOptions<AppModelType[], Error, InfiniteData<AppModelType[]>, AppModelType[], TQueryKey, QueryConstraint>, "queryKey">>;
+    collectionReference: CollectionReference<AppModelType, DbModelType>;
+    queryConstraints?: QueryConstraint[] | QueryNonFilterConstraint[];
+    compositeFilter?: QueryCompositeFilterConstraint;
+    converter?: FirestoreDataConverter<AppModelType, DbModelType>;
+};
+/**
+ * Custom hook that creates an infinite query using Firestore, allowing for query constraints, composite filters, and converters.
+ * It fetches data in pages and can load more as required.
+ *
+ * @param {UseInfiniteQueryOptions<AppModelType, DbModelType>} options - Configuration options for the infinite query, including Firestore query reference, query constraints, composite filter, and data converter.
+ * @returns {UseInfiniteQueryResult<InfiniteData<AppModelType[]>>} Result object containing the infinite data and methods for fetching more pages.
+ */
+export declare const useInfiniteQuery: <AppModelType extends DocumentData = DocumentData, DbModelType extends DocumentData = DocumentData>({ options, collectionReference, queryConstraints, compositeFilter, converter }: UseInfiniteQueryOptions<AppModelType, DbModelType>) => UseInfiniteQueryResult<InfiniteData<AppModelType[]>>;
+export {};

package/web/firestore/useInfiniteQuery.js

@@ -0,0 +1,28 @@
+import { getDocs, query } from "firebase/firestore";
+import { useInfiniteQuery as useInfiniteReactQuery } from "@tanstack/react-query";
+/**
+ * Custom hook that creates an infinite query using Firestore, allowing for query constraints, composite filters, and converters.
+ * It fetches data in pages and can load more as required.
+ *
+ * @param {UseInfiniteQueryOptions<AppModelType, DbModelType>} options - Configuration options for the infinite query, including Firestore query reference, query constraints, composite filter, and data converter.
+ * @returns {UseInfiniteQueryResult<InfiniteData<AppModelType[]>>} Result object containing the infinite data and methods for fetching more pages.
+ */
+export const useInfiniteQuery = ({ options, collectionReference, queryConstraints = [], compositeFilter, converter }) => {
+    return useInfiniteReactQuery({
+        ...options,
+        queryFn: async ({ pageParam }) => {
+            const allQueryConstraints = [...queryConstraints, ...(pageParam ? [pageParam] : [])];
+            const queryToExecute = compositeFilter
+                ? query(collectionReference, compositeFilter, ...allQueryConstraints)
+                : query(collectionReference, ...allQueryConstraints);
+            const querySnapshot = await getDocs(converter ? queryToExecute.withConverter(converter) : queryToExecute);
+            const docs = [];
+            if (querySnapshot) {
+                querySnapshot.forEach((doc) => {
+                    docs.push(doc.data());
+                });
+            }
+            return docs;
+        }
+    });
+};

package/web/firestore/useQuery.d.ts

@@ -0,0 +1,25 @@
+import { DocumentData, FirestoreDataConverter, CollectionReference, QueryCompositeFilterConstraint, QueryConstraint, QueryNonFilterConstraint } from "firebase/firestore";
+import { UseQueryResult, 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">>;
+    collectionReference: CollectionReference<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 declare const useQuery: <AppModelType extends DocumentData = DocumentData, DbModelType extends DocumentData = DocumentData>({ options, collectionReference, queryConstraints, compositeFilter, converter }: UseQueryOptions<AppModelType, DbModelType>) => UseQueryResult<AppModelType[]>;
+export {};

package/web/firestore/useQuery.js

@@ -0,0 +1,34 @@
+import { getDocs, query } from "firebase/firestore";
+import { useQuery as useReactQuery } from "@tanstack/react-query";
+/**
+ * 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 = ({ options, collectionReference, queryConstraints = [], compositeFilter, converter }) => {
+    return useReactQuery({
+        ...options,
+        queryFn: async () => {
+            const queryToExecute = compositeFilter
+                ? query(collectionReference, compositeFilter, ...queryConstraints)
+                : query(collectionReference, ...queryConstraints);
+            const querySnapshot = await getDocs(converter ? queryToExecute.withConverter(converter) : queryToExecute);
+            const docs = [];
+            if (querySnapshot) {
+                querySnapshot.forEach((doc) => {
+                    docs.push(doc.data());
+                });
+            }
+            return docs;
+        }
+    });
+};

package/web/firestore/useQueryConstraints.d.ts

@@ -0,0 +1,55 @@
+import { QueryNonFilterConstraint } from "firebase/firestore";
+import { AppModel } from "../../types/AppModel";
+import { NonFilterQueryConstraint } from "../../types/QueryConstraints";
+/**
+ * @inline
+ */
+export type UseQueryConstraints<AppModelType extends AppModel = AppModel> = {
+    /**
+     * A list of constraints such as limit, order, offset.
+     */
+    constraints: NonFilterQueryConstraint<AppModelType>[];
+};
+/**
+ * A generic mothod to build query constraints for firebase
+ *
+ * @group Utility
+ *
+ * @param {NonFilterQueryConstraint<AppModelType>} constraint
+ *
+ * @returns {QueryNonFilterConstraint}
+ *
+ * @example
+ * ```jsx
+ * const firebaseConfig = {};
+ * export const constraint = useMemo(() => {
+ *  return buildQueryConstraint({
+ *      type: 'limit',
+ *      limit: 1
+ *  });
+ * };
+ * ```
+ */
+export declare const buildQueryConstraint: <AppModelType extends AppModel = AppModel>(constraint: NonFilterQueryConstraint<AppModelType>) => QueryNonFilterConstraint;
+/**
+ * A hook to build a list of non-filter query constraints for firebase queries.
+ * It uses buildQueryConstraint method and useMemo hook.
+ *
+ * @group Hook
+ *
+ * @param {UseQueryConstraints<AppModelType>} constraints
+ *
+ * @returns {QueryNonFilterConstraint[]}
+ *
+ * @example
+ * ```jsx
+ * const firebaseConfig = {};
+ * export const constraint = useQueryConstraints([
+ *  {
+ *      type: 'limit',
+ *      limit: 1
+ *  }
+ * ]};
+ * ```
+ */
+export declare const useQueryConstraints: <AppModelType extends AppModel = AppModel>({ constraints }: UseQueryConstraints<AppModelType>) => QueryNonFilterConstraint[];

package/web/firestore/useQueryConstraints.js

@@ -0,0 +1,66 @@
+import { startAt, orderBy, limit, limitToLast, startAfter, endAt, endBefore } from "firebase/firestore";
+import { useMemo } from "react";
+/**
+ * A generic mothod to build query constraints for firebase
+ *
+ * @group Utility
+ *
+ * @param {NonFilterQueryConstraint<AppModelType>} constraint
+ *
+ * @returns {QueryNonFilterConstraint}
+ *
+ * @example
+ * ```jsx
+ * const firebaseConfig = {};
+ * export const constraint = useMemo(() => {
+ *  return buildQueryConstraint({
+ *      type: 'limit',
+ *      limit: 1
+ *  });
+ * };
+ * ```
+ */
+export const buildQueryConstraint = (constraint) => {
+    switch (constraint.type) {
+        case "orderBy":
+            return orderBy(constraint.fieldPath, constraint.directionStr);
+        case "startAt":
+            return startAt(...constraint.arguments);
+        case "startAfter":
+            return startAfter(...constraint.arguments);
+        case "endAt":
+            return endAt(constraint.value, constraint.key);
+        case "endBefore":
+            return endBefore(constraint.value, constraint.key);
+        case "limit":
+            return limit(constraint.limit);
+        case "limitToLast":
+            return limitToLast(constraint.limit);
+    }
+};
+/**
+ * A hook to build a list of non-filter query constraints for firebase queries.
+ * It uses buildQueryConstraint method and useMemo hook.
+ *
+ * @group Hook
+ *
+ * @param {UseQueryConstraints<AppModelType>} constraints
+ *
+ * @returns {QueryNonFilterConstraint[]}
+ *
+ * @example
+ * ```jsx
+ * const firebaseConfig = {};
+ * export const constraint = useQueryConstraints([
+ *  {
+ *      type: 'limit',
+ *      limit: 1
+ *  }
+ * ]};
+ * ```
+ */
+export const useQueryConstraints = ({ constraints }) => {
+    return useMemo(() => {
+        return constraints.map(buildQueryConstraint);
+    }, [constraints]);
+};

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/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/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/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/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>>;