react-query-firebase 1.0.2 → 1.0.4

package/dist/src/{FirebaseContextProvider.js → context/FirebaseContextProvider.js}

@@ -5,6 +5,29 @@ import { getAnalytics } from "firebase/analytics";
 import { getRemoteConfig } from "firebase/remote-config";
 import { connectFirestoreEmulator, getFirestore } from "firebase/firestore";
 import { initializeApp } from "firebase/app";
+/**
+ * FirebaseContextProvider component configures and provides Firebase services to its children.
+ * Initializes Firebase app and enables optional Firebase services such as Firestore, Auth, Analytics,
+ * and Remote Config based on the provided configuration and parameters.
+ *
+ * @group Component
+ *
+ * @param {FirebaseContextProviderProps} props
+ *
+ * @returns {FirebaseContextProvider<FirebaseContextProviderProps>}
+ *
+ * @example
+ * ```jsx
+ * const firebaseConfig = {};
+ * export const App = () => {
+ *  return (
+ *      <FirebaseContextProvider options={firebaseConfig}>
+ *          <ChildComponent />
+ *      </FirebaseContextProvider>
+ *  );
+ * };
+ * ```
+ */
 export const FirebaseContextProvider = ({ emulators, options, children, authEnabled = true, firestoreEnabled = true, analyticsEnabled = true, remoteConfigEnabled = true, remoteConfigSettings, remoteConfigDefaults = {} }) => {
     const firebase = useMemo(() => {
         return initializeApp(options);
@@ -42,5 +65,5 @@ export const FirebaseContextProvider = ({ emulators, options, children, authEnab
         }
         return { firebase, ...value };
     }, [firebase]);
-    return React.createElement(FirebaseContext.Provider, { value: contextValue }, children);
+    return (React.createElement(FirebaseContext.Provider, { value: contextValue }, children));
 };

package/dist/src/context/index.d.ts

@@ -0,0 +1 @@
+export * from "./FirebaseContextProvider";

package/dist/src/context/index.js

@@ -0,0 +1 @@
+export * from "./FirebaseContextProvider";

package/dist/src/firestore/index.d.ts

@@ -1,3 +1,4 @@
+export * from "./useFirestore";
 export * from "./useAddDocMutation";
 export * from "./useBatchWrite";
 export * from "./useCollectionReference";

package/dist/src/firestore/index.js

@@ -1,3 +1,4 @@
+export * from "./useFirestore";
 export * from "./useAddDocMutation";
 export * from "./useBatchWrite";
 export * from "./useCollectionReference";

package/dist/src/firestore/useAddDocMutation.d.ts

@@ -9,4 +9,15 @@ export type UseAddDocMutationOptions<AppModelType extends DocumentData = Documen
     converter?: FirestoreDataConverter<AppModelType, DbModelType>;
     options?: Omit<UseMutationOptions<AppModelType, FirebaseError, UseAddDocMutationValues<AppModelType>, TContext>, "mutationFn" | "mutationKey">;
 };
+/**
+ * Provides a mutation hook to add a document to a Firestore collection utilizing React Query's `useMutation`.
+ * It handles addition and optional conversion of the document data in Firestore.
+ *
+ * @param {Object} options - Options for the mutation hook
+ * @param {FirebaseFirestore.CollectionReference<AppModelType>} options.reference - Firestore collection reference where the document should be added.
+ * @param {FirebaseFirestore.FirestoreDataConverter<DbModelType>} [options.converter] - Optional data converter for reading and writing Firestore documents.
+ * @param {UseMutationOptions<AppModelType, Error, { data: DbModelType }, TContext>} [options.options={}] - Optional configuration for the mutation.
+ *
+ * @returns {UseMutationResult<AppModelType, Error, { data: DbModelType }, TContext>} The mutation hook result containing status, error, and data of the mutation process.
+ */
 export declare const useAddDocMutation: <AppModelType extends DocumentData = DocumentData, DbModelType extends DocumentData = DocumentData, TContext = unknown>({ reference, converter, options }: UseAddDocMutationOptions<AppModelType, DbModelType, TContext>) => import("@tanstack/react-query").UseMutationResult<AppModelType, FirebaseError, UseAddDocMutationValues<AppModelType>, TContext>;

package/dist/src/firestore/useAddDocMutation.js

@@ -1,6 +1,17 @@
 import { useMutation } from "@tanstack/react-query";
 import { addDoc, getDoc } from "firebase/firestore";
 import { useMemo } from "react";
+/**
+ * Provides a mutation hook to add a document to a Firestore collection utilizing React Query's `useMutation`.
+ * It handles addition and optional conversion of the document data in Firestore.
+ *
+ * @param {Object} options - Options for the mutation hook
+ * @param {FirebaseFirestore.CollectionReference<AppModelType>} options.reference - Firestore collection reference where the document should be added.
+ * @param {FirebaseFirestore.FirestoreDataConverter<DbModelType>} [options.converter] - Optional data converter for reading and writing Firestore documents.
+ * @param {UseMutationOptions<AppModelType, Error, { data: DbModelType }, TContext>} [options.options={}] - Optional configuration for the mutation.
+ *
+ * @returns {UseMutationResult<AppModelType, Error, { data: DbModelType }, TContext>} The mutation hook result containing status, error, and data of the mutation process.
+ */
 export const useAddDocMutation = ({ reference, converter, options = {} }) => {
     const mutationKey = useMemo(() => [reference.path], [reference.path]);
     return useMutation({

package/dist/src/firestore/useBatchWrite.d.ts

@@ -5,4 +5,11 @@ 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 declare const useBatchWrite: <TContext = unknown>({ options }?: UseBatchWriteOptions<TContext>) => import("@tanstack/react-query").UseMutationResult<void, FirebaseError, UseBatchWriteVariables, TContext>;

package/dist/src/firestore/useBatchWrite.js

@@ -1,6 +1,13 @@
 import { useMutation } from "@tanstack/react-query";
 import { writeBatch } from "firebase/firestore";
-import { useFirestore } from "../useFirestore";
+import { useFirestore } from "./useFirestore";
+/**
+ * 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 = ({ options = {} } = {}) => {
     const db = useFirestore();
     return useMutation({

package/dist/src/firestore/useCollectionReference.d.ts

@@ -4,4 +4,15 @@ export type UseCollectionReferenceOptions<AppModelType, DbModelType extends Docu
     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/dist/src/firestore/useCollectionReference.js

@@ -1,6 +1,17 @@
 import { collection } from "firebase/firestore";
 import { useMemo } from "react";
-import { useFirestore } from "../useFirestore";
+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(() => {

package/dist/src/firestore/useCompositeFilter.d.ts

@@ -16,5 +16,15 @@ export type CompositeFilter<DbModelType extends CompositeFilterDocumentData = Co
 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 = DocumentData>({ query }: UseCompositeFilter<DbModelType>) => QueryCompositeFilterConstraint | undefined;
 export {};

package/dist/src/firestore/useCompositeFilter.js

@@ -1,5 +1,12 @@
 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
@@ -15,6 +22,16 @@ const buildCompositeQuery = (query) => {
     }
     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) ?? [];

package/dist/src/firestore/useCountQuery.d.ts

@@ -6,5 +6,18 @@ type UseCountQueryOptions<AppModelType extends DocumentData = DocumentData, DbMo
     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/dist/src/firestore/useCountQuery.js

@@ -1,5 +1,18 @@
 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,

package/dist/src/firestore/useDeleteDocMutation.d.ts

@@ -8,4 +8,11 @@ export type UseDeleteDocMutationOptions<AppModelType extends DocumentData = Docu
     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/dist/src/firestore/useDeleteDocMutation.js

@@ -1,6 +1,13 @@
 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({

package/dist/src/firestore/useDocReference.d.ts

@@ -4,4 +4,16 @@ export type UseDocReferenceOptions<AppModelType, DbModelType extends DocumentDat
     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/dist/src/firestore/useDocReference.js

@@ -1,6 +1,18 @@
 import { doc } from "firebase/firestore";
 import { useEffect, useRef } from "react";
-import { useFirestore } from "../useFirestore";
+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;
@@ -11,6 +23,18 @@ const getDocReference = (db, { path, pathSegments, reference }) => {
             ? 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 }));

package/dist/src/firestore/useDocReferences.d.ts

@@ -4,4 +4,20 @@ export type UseDocReferencesOptions<AppModelType, DbModelType extends DocumentDa
     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>[];

package/dist/src/firestore/useDocReferences.js

@@ -1,6 +1,22 @@
 import { doc } from "firebase/firestore";
 import { useMemo } from "react";
-import { useFirestore } from "../useFirestore";
+import { useFirestore } from "./useFirestore";
+/**
+ * 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 const useDocReferences = (references) => {
     const db = useFirestore();
     return useMemo(() => {

package/dist/src/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/dist/src/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/dist/src/firestore/useGetDocData.d.ts

@@ -6,5 +6,13 @@ type UseGetDocOptions<AppModelType extends DocumentData = DocumentData, DbModelT
     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/dist/src/firestore/useGetDocData.js

@@ -1,6 +1,14 @@
-import { useFirestore } from "../useFirestore";
+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({

package/dist/src/firestore/useInfiniteQuery.d.ts

@@ -7,5 +7,12 @@ type UseInfiniteQueryOptions<AppModelType extends DocumentData = DocumentData, D
     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, query: queryReference, queryConstraints, compositeFilter, converter }: UseInfiniteQueryOptions<AppModelType, DbModelType>) => UseInfiniteQueryResult<InfiniteData<AppModelType[]>>;
 export {};

package/dist/src/firestore/useInfiniteQuery.js

@@ -1,5 +1,12 @@
 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, query: queryReference, queryConstraints = [], compositeFilter, converter }) => {
     return useInfiniteReactQuery({
         ...options,

package/dist/src/firestore/useQuery.d.ts

@@ -7,5 +7,19 @@ type UseQueryOptions<AppModelType extends DocumentData = DocumentData, DbModelTy
     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, query: queryReference, queryConstraints, compositeFilter, converter }: UseQueryOptions<AppModelType, DbModelType>) => UseQueryResult<AppModelType[]>;
 export {};

package/dist/src/firestore/useQuery.js

@@ -1,5 +1,19 @@
 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, query: queryReference, queryConstraints = [], compositeFilter, converter }) => {
     return useReactQuery({
         ...options,

package/dist/src/firestore/useRunTransaction.d.ts

@@ -5,4 +5,11 @@ export type UseRunTransactionValues = <AppModelType = unknown>(transaction: Tran
 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/dist/src/firestore/useRunTransaction.js

@@ -1,6 +1,13 @@
 import { useMutation } from "@tanstack/react-query";
 import { runTransaction } from "firebase/firestore";
-import { useFirestore } from "../useFirestore";
+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({

package/dist/src/firestore/useSetDocMutation.d.ts

@@ -8,4 +8,13 @@ export type UseSetDocMutationOptions<AppModelType = unknown, DbModelType extends
     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/dist/src/firestore/useSetDocMutation.js

@@ -1,6 +1,15 @@
 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({

package/dist/src/firestore/useUpdateDocMutation.d.ts

@@ -9,4 +9,23 @@ export type UseUpdateDocMutationOptions<AppModelType extends DocumentData = Docu
     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/dist/src/firestore/useUpdateDocMutation.js

@@ -1,6 +1,25 @@
 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({