react-query-firebase 2.1.4 → 2.3.0

package/react-native/firestore/useInfiniteQuery.js

@@ -1,11 +1,26 @@
 import { getDocs, query } from "@react-native-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.
+ * Executes an infinite query on a Firestore data source and returns the resulting documents as an array.
  *
- * @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.
+ * @group Hook
+ *
+ * @param {UseInfiniteQueryOptions<AppModelType, TQueryKey>} options - Configuration options for the query.
+ *
+ * @returns {UseInfiniteQueryResult<InfiniteData<AppModelType[]>>} An object containing documents that match the query.
+ *
+ * @example
+ * ```jsx
+ * export const MyComponent = () => {
+ *  const docs = useInfiniteQuery({
+ *      options: {
+ *          queryKey: ['key']
+ *      },
+ *      collectionReference: collection(),
+ *  });
+ *  console.log(docs);
+ * };
+ * ```
  */
 export const useInfiniteQuery = ({ options, collectionReference, queryConstraints = [], compositeFilter }) => {
     return useInfiniteReactQuery({

package/react-native/firestore/useInfiniteQuery.ts

@@ -13,12 +13,20 @@ import {
     UseInfiniteQueryResult,
     InfiniteData
 } from "@tanstack/react-query";
+import { QueryFilterConstraint } from "./useCompositeFilter";
+import { AppModel } from "../../types";
 
+/**
+ * @inline
+ */
 type UseInfiniteQueryOptions<
-    AppModelType extends FirebaseFirestoreTypes.DocumentData = FirebaseFirestoreTypes.DocumentData,
+    AppModelType extends AppModel = AppModel,
     TQueryKey extends QueryKey = QueryKey,
     TPageParam = unknown
 > = {
+    /**
+     * Reqct-query options that must include queryKey and shall not define queryFn
+     */
     options: Omit<
         UseReactInfiniteQueryOptions<
             AppModelType[],
@@ -43,26 +51,57 @@ type UseInfiniteQueryOptions<
                 "queryKey"
             >
         >;
+
+    /**
+     * Reference to a Firestore collection
+     */
     collectionReference: FirebaseFirestoreTypes.CollectionReference<AppModelType>;
+
+    /**
+     * Non composite filter constraints such as limit, order, where
+     */
     queryConstraints?: QueryConstraint[] | QueryNonFilterConstraint[];
-    compositeFilter?: FirebaseFirestoreTypes.QueryCompositeFilterConstraint;
+
+    /**
+     * Composite filter
+     */
+    compositeFilter?: QueryFilterConstraint;
 };
 
 /**
- * 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.
+ * Executes an infinite query on a Firestore data source and returns the resulting documents as an array.
  *
- * @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.
+ * @group Hook
+ *
+ * @param {UseInfiniteQueryOptions<AppModelType, TQueryKey>} options - Configuration options for the query.
+ *
+ * @returns {UseInfiniteQueryResult<InfiniteData<AppModelType[]>>} An object containing documents that match the query.
+ *
+ * @example
+ * ```jsx
+ * export const MyComponent = () => {
+ *  const docs = useInfiniteQuery({
+ *      options: {
+ *          queryKey: ['key']
+ *      },
+ *      collectionReference: collection(),
+ *  });
+ *  console.log(docs);
+ * };
+ * ```
  */
 export const useInfiniteQuery = <
-    AppModelType extends FirebaseFirestoreTypes.DocumentData = FirebaseFirestoreTypes.DocumentData
+    AppModelType extends AppModel = AppModel,
+    TQueryKey extends QueryKey = QueryKey,
+    TPageParam = unknown
 >({
     options,
     collectionReference,
     queryConstraints = [],
     compositeFilter
-}: UseInfiniteQueryOptions<AppModelType>): UseInfiniteQueryResult<InfiniteData<AppModelType[]>> => {
+}: UseInfiniteQueryOptions<AppModelType, TQueryKey, TPageParam>): UseInfiniteQueryResult<
+    InfiniteData<AppModelType[]>
+> => {
     return useInfiniteReactQuery({
         ...options,
         queryFn: async ({ pageParam }) => {

package/react-native/firestore/useQuery.d.ts

@@ -1,24 +1,49 @@
 import { FirebaseFirestoreTypes, QueryConstraint, QueryNonFilterConstraint } from "@react-native-firebase/firestore";
 import { UseQueryResult, UseQueryOptions as UseReactQueryOptions } from "@tanstack/react-query";
-type UseQueryOptions<AppModelType extends FirebaseFirestoreTypes.DocumentData> = {
+import { QueryFilterConstraint } from "./useCompositeFilter";
+import { AppModel } from "../../types";
+/**
+ * @inline
+ */
+type UseQueryOptions<AppModelType extends AppModel = AppModel> = {
+    /**
+     * Reqct-query options that must include queryKey and shall not define queryFn
+     */
     options: Omit<UseReactQueryOptions<AppModelType[], Error, AppModelType[]>, "queryFn"> & Required<Pick<UseReactQueryOptions<AppModelType[], Error, AppModelType[]>, "queryKey">>;
+    /**
+     * Reference to a Firestore collection
+     */
     collectionReference: FirebaseFirestoreTypes.CollectionReference<AppModelType>;
+    /**
+     * Non composite filter constraints such as limit, order, where
+     */
     queryConstraints?: QueryConstraint[] | QueryNonFilterConstraint[];
-    compositeFilter?: FirebaseFirestoreTypes.QueryCompositeFilterConstraint;
+    /**
+     * Composite filter
+     */
+    compositeFilter?: QueryFilterConstraint;
 };
 /**
- * Executes a query on a Firestore-like data source and returns the resulting documents as an array.
+ * Executes a query on a Firestore data source and returns the resulting documents as an array.
+ *
+ * @group Hook
  *
- * 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>} options - Configuration options for the query.
  *
- * @param {UseQueryOptions<AppModelType>}  options - Configuration options for the query.
- * @param {FirebaseFirestoreTypes.DocumentReference<AppModelType>}  collectionReference - 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[]>} An object containing documents that match the query.
  *
- * @returns {UseQueryResult<AppModelType[]>} Result containing an array of documents that match the query criteria.
+ * @example
+ * ```jsx
+ * export const MyComponent = () => {
+ *  const docs = useQuery({
+ *      options: {
+ *          queryKey: ['key']
+ *      },
+ *      collectionReference: collection(),
+ *  });
+ *  console.log(docs);
+ * };
+ * ```
  */
-export declare const useQuery: <AppModelType extends FirebaseFirestoreTypes.DocumentData = FirebaseFirestoreTypes.DocumentData>({ options, collectionReference, queryConstraints, compositeFilter }: UseQueryOptions<AppModelType>) => UseQueryResult<AppModelType[]>;
+export declare const useQuery: <AppModelType extends AppModel = AppModel>({ options, collectionReference, queryConstraints, compositeFilter }: UseQueryOptions<AppModelType>) => UseQueryResult<AppModelType[]>;
 export {};

package/react-native/firestore/useQuery.js

@@ -1,18 +1,26 @@
 import { getDocs, query } from "@react-native-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.
+ * Executes a query on a Firestore 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.
+ * @group Hook
  *
- * @param {UseQueryOptions<AppModelType>}  options - Configuration options for the query.
- * @param {FirebaseFirestoreTypes.DocumentReference<AppModelType>}  collectionReference - 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.
+ * @param {UseQueryOptions<AppModelType>} options - Configuration options for the query.
  *
- * @returns {UseQueryResult<AppModelType[]>} Result containing an array of documents that match the query criteria.
+ * @returns {UseQueryResult<AppModelType[]>} An object containing documents that match the query.
+ *
+ * @example
+ * ```jsx
+ * export const MyComponent = () => {
+ *  const docs = useQuery({
+ *      options: {
+ *          queryKey: ['key']
+ *      },
+ *      collectionReference: collection(),
+ *  });
+ *  console.log(docs);
+ * };
+ * ```
  */
 export const useQuery = ({ options, collectionReference, queryConstraints = [], compositeFilter }) => {
     return useReactQuery({

package/react-native/firestore/useQuery.ts

@@ -11,32 +11,58 @@ import {
     useQuery as useReactQuery,
     UseQueryOptions as UseReactQueryOptions
 } from "@tanstack/react-query";
+import { QueryFilterConstraint } from "./useCompositeFilter";
+import { AppModel } from "../../types";
 
-type UseQueryOptions<AppModelType extends FirebaseFirestoreTypes.DocumentData> = {
+/**
+ * @inline
+ */
+type UseQueryOptions<AppModelType extends AppModel = AppModel> = {
+    /**
+     * Reqct-query options that must include queryKey and shall not define queryFn
+     */
     options: Omit<UseReactQueryOptions<AppModelType[], Error, AppModelType[]>, "queryFn"> &
         Required<Pick<UseReactQueryOptions<AppModelType[], Error, AppModelType[]>, "queryKey">>;
+
+    /**
+     * Reference to a Firestore collection
+     */
     collectionReference: FirebaseFirestoreTypes.CollectionReference<AppModelType>;
+
+    /**
+     * Non composite filter constraints such as limit, order, where
+     */
     queryConstraints?: QueryConstraint[] | QueryNonFilterConstraint[];
-    compositeFilter?: FirebaseFirestoreTypes.QueryCompositeFilterConstraint;
+
+    /**
+     * Composite filter
+     */
+    compositeFilter?: QueryFilterConstraint;
 };
 
 /**
- * Executes a query on a Firestore-like data source and returns the resulting documents as an array.
+ * Executes a query on a Firestore data source and returns the resulting documents as an array.
+ *
+ * @group Hook
  *
- * 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>} options - Configuration options for the query.
  *
- * @param {UseQueryOptions<AppModelType>}  options - Configuration options for the query.
- * @param {FirebaseFirestoreTypes.DocumentReference<AppModelType>}  collectionReference - 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[]>} An object containing documents that match the query.
  *
- * @returns {UseQueryResult<AppModelType[]>} Result containing an array of documents that match the query criteria.
+ * @example
+ * ```jsx
+ * export const MyComponent = () => {
+ *  const docs = useQuery({
+ *      options: {
+ *          queryKey: ['key']
+ *      },
+ *      collectionReference: collection(),
+ *  });
+ *  console.log(docs);
+ * };
+ * ```
  */
-export const useQuery = <
-    AppModelType extends FirebaseFirestoreTypes.DocumentData = FirebaseFirestoreTypes.DocumentData
->({
+export const useQuery = <AppModelType extends AppModel = AppModel>({
     options,
     collectionReference,
     queryConstraints = [],

package/types/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./AppModel";
+export * from "./QueryConstraints";

package/types/index.js

@@ -0,0 +1,2 @@
+export * from "./AppModel";
+export * from "./QueryConstraints";

package/web/auth/useAuthStateReady.d.ts

@@ -1,6 +1,17 @@
 /**
  * A custom hook that determines if the Firebase authentication state is ready.
  * It uses Firebase authentication to check if the auth state is ready and updates the state accordingly.
- * @returns {boolean} Indicates whether the authentication state is ready.
+ *
+ * @group Hook
+ *
+ * @returns {boolean}
+ *
+ * @example
+ * ```jsx
+ * export const MyComponent = () => {
+ *  const isAuthStateReady = useAuthStateReady();
+ *  console.log(isAuthStateReady);
+ * };
+ * ```
  */
 export declare const useAuthStateReady: () => boolean;

package/web/auth/useAuthStateReady.js

@@ -3,7 +3,18 @@ import { useCallback, useEffect, useState } from "react";
 /**
  * A custom hook that determines if the Firebase authentication state is ready.
  * It uses Firebase authentication to check if the auth state is ready and updates the state accordingly.
- * @returns {boolean} Indicates whether the authentication state is ready.
+ *
+ * @group Hook
+ *
+ * @returns {boolean}
+ *
+ * @example
+ * ```jsx
+ * export const MyComponent = () => {
+ *  const isAuthStateReady = useAuthStateReady();
+ *  console.log(isAuthStateReady);
+ * };
+ * ```
  */
 export const useAuthStateReady = () => {
     const firebaseAuth = useAuth();

package/web/auth/useAuthStateReady.ts

@@ -4,7 +4,18 @@ import { useCallback, useEffect, useState } from "react";
 /**
  * A custom hook that determines if the Firebase authentication state is ready.
  * It uses Firebase authentication to check if the auth state is ready and updates the state accordingly.
- * @returns {boolean} Indicates whether the authentication state is ready.
+ *
+ * @group Hook
+ *
+ * @returns {boolean}
+ *
+ * @example
+ * ```jsx
+ * export const MyComponent = () => {
+ *  const isAuthStateReady = useAuthStateReady();
+ *  console.log(isAuthStateReady);
+ * };
+ * ```
  */
 export const useAuthStateReady = () => {
     const firebaseAuth = useAuth();

package/web/firestore/useCompositeFilter.d.ts

@@ -1,40 +1,82 @@
-import { DocumentData, QueryFilterConstraint, WhereFilterOp } from "firebase/firestore";
-type CompositeFilterDocumentData = DocumentData;
-export type QueryElement<DbModelType extends CompositeFilterDocumentData = CompositeFilterDocumentData> = {
+import { QueryFilterConstraint as FBQueryFilterConstraint, QueryCompositeFilterConstraint as FBQueryCompositeFilterConstraint, WhereFilterOp } from "firebase/firestore";
+import { AppModel } from "../../types";
+export type QueryFilterConstraint = FBQueryFilterConstraint | FBQueryCompositeFilterConstraint;
+export type QueryElement<AppModelType extends AppModel = AppModel> = {
     operator?: "OR" | "AND";
     children?: QueryElement[];
-    field?: keyof (DbModelType & {
+    field?: keyof (AppModelType & {
         documentId?: string[];
     });
-    value?: DbModelType[keyof DbModelType];
+    value?: AppModelType[keyof AppModelType];
     op?: WhereFilterOp;
 };
-export type CompositeFilter<DbModelType extends CompositeFilterDocumentData = CompositeFilterDocumentData> = {
+export type CompositeFilter<AppModelType extends AppModel = AppModel> = {
     operator: "OR" | "AND";
-    children: QueryElement<DbModelType & {
+    children: QueryElement<AppModelType & {
         documentId?: string[];
     }>[];
 };
-export type UseCompositeFilter<DbModelType extends CompositeFilterDocumentData = CompositeFilterDocumentData> = {
-    query?: CompositeFilter<DbModelType>;
+/**
+ * @inline
+ */
+export type UseCompositeFilter<AppModelType extends AppModel = AppModel> = {
+    query?: CompositeFilter<AppModelType>;
 };
 /**
- * Constructs a composite query filter based on the provided query structure.
+ * Constructs a composite or where 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 {QueryFieldFilterConstraint | null} A constructed query filter constraint based on the input query, or null if no valid constraints can be derived.
+ * @group Utility
+ *
+ * @param {QueryElement<AppModelType>} query
+ *
+ * @returns {QueryFilterConstraint | null}
+ *
+ * @example
+ * ```jsx
+ * export const MyComponent = () => {
+ *  const filter = buildCompositeFilter({
+ *      operator: "AND",
+ *      children: [
+ *          {
+ *              field: "field",
+ *              value: "value",
+ *              op: "=="
+ *          },
+ *          ...(query ? [query] : [])
+ *      ]
+ *  });
+ *  console.log(filter);
+ * };
+ * ```
  */
-export declare const buildCompositeFilter: <DbModelType extends CompositeFilterDocumentData = CompositeFilterDocumentData>(query: QueryElement<DbModelType>) => QueryFilterConstraint | null;
+export declare const buildCompositeFilter: <AppModelType extends AppModel = AppModel>(query: QueryElement<AppModelType>) => QueryFilterConstraint | 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.
+ * A custom hook that constructs a composite or where query filter based on the provided query structure.
+ * It recursively builds query constraints using logical "or" or "and" operators.
+ *
+ * @group Hook
+ *
+ * @param {QueryElement<AppModelType>} 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 {QueryFilterConstraint | null}
  *
- * @returns {(Function|undefined)} A composite query filter constraint function formed by combining subqueries or undefined if there are no valid constraints.
+ * @example
+ * ```jsx
+ * export const MyComponent = () => {
+ *  const filter = useCompositeFilter({
+ *      operator: "AND",
+ *      children: [
+ *          {
+ *              field: "field",
+ *              value: "value",
+ *              op: "=="
+ *          },
+ *          ...(query ? [query] : [])
+ *      ]
+ *  });
+ *  console.log(filter);
+ * };
+ * ```
  */
-export declare const useCompositeFilter: <DbModelType extends CompositeFilterDocumentData = CompositeFilterDocumentData>({ query }: UseCompositeFilter<DbModelType>) => import("@firebase/firestore").QueryCompositeFilterConstraint | undefined;
-export {};
+export declare const useCompositeFilter: <AppModelType extends AppModel = AppModel>({ query }: UseCompositeFilter<AppModelType>) => FBQueryCompositeFilterConstraint | undefined;

package/web/firestore/useCompositeFilter.js

@@ -1,11 +1,32 @@
 import { documentId, and, or, where } from "firebase/firestore";
 import { useMemo } from "react";
 /**
- * Constructs a composite query filter based on the provided query structure.
+ * Constructs a composite or where 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 {QueryFieldFilterConstraint | null} A constructed query filter constraint based on the input query, or null if no valid constraints can be derived.
+ * @group Utility
+ *
+ * @param {QueryElement<AppModelType>} query
+ *
+ * @returns {QueryFilterConstraint | null}
+ *
+ * @example
+ * ```jsx
+ * export const MyComponent = () => {
+ *  const filter = buildCompositeFilter({
+ *      operator: "AND",
+ *      children: [
+ *          {
+ *              field: "field",
+ *              value: "value",
+ *              op: "=="
+ *          },
+ *          ...(query ? [query] : [])
+ *      ]
+ *  });
+ *  console.log(filter);
+ * };
+ * ```
  */
 export const buildCompositeFilter = (query) => {
     if (query.children) {
@@ -21,14 +42,32 @@ export const buildCompositeFilter = (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.
+ * A custom hook that constructs a composite or where query filter based on the provided query structure.
+ * It recursively builds query constraints using logical "or" or "and" operators.
+ *
+ * @group Hook
+ *
+ * @param {QueryElement<AppModelType>} 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 {QueryFilterConstraint | null}
  *
- * @returns {(Function|undefined)} A composite query filter constraint function formed by combining subqueries or undefined if there are no valid constraints.
+ * @example
+ * ```jsx
+ * export const MyComponent = () => {
+ *  const filter = useCompositeFilter({
+ *      operator: "AND",
+ *      children: [
+ *          {
+ *              field: "field",
+ *              value: "value",
+ *              op: "=="
+ *          },
+ *          ...(query ? [query] : [])
+ *      ]
+ *  });
+ *  console.log(filter);
+ * };
+ * ```
  */
 export const useCompositeFilter = ({ query }) => {
     return useMemo(() => {