react-query-firebase 2.3.2 → 2.4.0

package/web/firestore/useSetDocMutation.d.ts

@@ -1,20 +1,53 @@
 import { UseMutationOptions } from "@tanstack/react-query";
-import { DocumentData, DocumentReference, WithFieldValue } from "firebase/firestore";
+import { DocumentReference, WithFieldValue } from "firebase/firestore";
 import { FirebaseError } from "firebase/app";
-export type UseSetDocMutationValues<AppModelType> = {
+import { AppModel } from "../../types";
+/**
+ * @inline
+ */
+export type UseSetDocMutationValues<AppModelType extends AppModel = AppModel> = {
+    /**
+     * Data to write
+     */
     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">;
+/**
+ * @inline
+ */
+export type UseSetDocMutationOptions<AppModelType extends AppModel = AppModel, TContext = unknown> = {
+    /**
+     * Reference to a document that must be written
+     */
+    reference: DocumentReference<AppModelType, AppModelType> | null;
+    /**
+     * Options for useMutation hook excluding mutationFn.
+     */
+    options?: Omit<UseMutationOptions<AppModelType, FirebaseError, UseSetDocMutationValues<AppModelType>, TContext>, "mutationFn">;
 };
 /**
- * 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.
+ * Executes a mutation and returns added document
+ *
+ * @group Hook
+ *
+ * @param {UseSetDocMutationOptions<AppModelType>} options - Configuration options for mutation.
+ *
+ * @returns {UseMutationResult<AppModelType, Error, UseAddDocMutationValues<AppModelType>, TContext>}  A mutation result
+ *
+ * @example
+ * ```jsx
+ * export const MyComponent = () => {
+ *  const {mutate} = useSetDocMutation({
+ *      options: {
+ *      },
+ *      reference: collection().doc(),
+ *  });
  *
- * @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.
+ *  // ....
+ *  mutate({data: {test: 'value'}});
+ *  // ....
+ * };
+ * ```
  */
-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>;
+export declare const useSetDocMutation: <AppModelType extends AppModel = AppModel, TContext = unknown>({ reference, options }: UseSetDocMutationOptions<AppModelType, TContext>) => import("@tanstack/react-query").UseMutationResult<AppModelType & {
+    uid: string;
+}, FirebaseError, UseSetDocMutationValues<AppModelType>, TContext>;

package/web/firestore/useSetDocMutation.js

@@ -1,25 +1,42 @@
 import { useMutation } from "@tanstack/react-query";
-import { setDoc } from "firebase/firestore";
+import { getDoc, 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.
+ * Executes a mutation and returns added document
  *
- * @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.
+ * @group Hook
+ *
+ * @param {UseSetDocMutationOptions<AppModelType>} options - Configuration options for mutation.
+ *
+ * @returns {UseMutationResult<AppModelType, Error, UseAddDocMutationValues<AppModelType>, TContext>}  A mutation result
+ *
+ * @example
+ * ```jsx
+ * export const MyComponent = () => {
+ *  const {mutate} = useSetDocMutation({
+ *      options: {
+ *      },
+ *      reference: collection().doc(),
+ *  });
+ *
+ *  // ....
+ *  mutate({data: {test: 'value'}});
+ *  // ....
+ * };
+ * ```
  */
 export const useSetDocMutation = ({ reference, options }) => {
     const mutationKey = useMemo(() => [reference?.path], [reference?.path]);
     return useMutation({
         ...options,
-        mutationFn: ({ data }) => {
+        mutationKey,
+        mutationFn: async ({ data }) => {
             if (!reference) {
                 throw new Error("Reference is undefined");
             }
-            return setDoc(reference, data);
-        },
-        mutationKey
+            await setDoc(reference, data);
+            const docSnap = await getDoc(reference);
+            return { ...docSnap.data(), uid: docSnap.id };
+        }
     });
 };

package/web/firestore/useSetDocMutation.ts

@@ -1,52 +1,77 @@
 import { useMutation, UseMutationOptions } from "@tanstack/react-query";
-import { DocumentData, DocumentReference, setDoc, WithFieldValue } from "firebase/firestore";
+import { DocumentReference, getDoc, setDoc, WithFieldValue } from "firebase/firestore";
 
 import { FirebaseError } from "firebase/app";
 import { useMemo } from "react";
+import { AppModel } from "../../types";
 
-export type UseSetDocMutationValues<AppModelType> = {
+/**
+ * @inline
+ */
+export type UseSetDocMutationValues<AppModelType extends AppModel = AppModel> = {
+    /**
+     * Data to write
+     */
     data: WithFieldValue<AppModelType>;
 };
 
-export type UseSetDocMutationOptions<
-    AppModelType = unknown,
-    DbModelType extends DocumentData = DocumentData,
-    TContext = unknown
-> = {
-    reference: DocumentReference<AppModelType, DbModelType> | null;
+/**
+ * @inline
+ */
+export type UseSetDocMutationOptions<AppModelType extends AppModel = AppModel, TContext = unknown> = {
+    /**
+     * Reference to a document that must be written
+     */
+    reference: DocumentReference<AppModelType, AppModelType> | null;
+    /**
+     * Options for useMutation hook excluding mutationFn.
+     */
     options?: Omit<
-        UseMutationOptions<void, FirebaseError, UseSetDocMutationValues<AppModelType>, TContext>,
-        "mutationFn" | "mutationKey"
+        UseMutationOptions<AppModelType, FirebaseError, UseSetDocMutationValues<AppModelType>, TContext>,
+        "mutationFn"
     >;
 };
 
 /**
- * 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.
+ * Executes a mutation and returns added document
+ *
+ * @group Hook
+ *
+ * @param {UseSetDocMutationOptions<AppModelType>} options - Configuration options for mutation.
+ *
+ * @returns {UseMutationResult<AppModelType, Error, UseAddDocMutationValues<AppModelType>, TContext>}  A mutation result
+ *
+ * @example
+ * ```jsx
+ * export const MyComponent = () => {
+ *  const {mutate} = useSetDocMutation({
+ *      options: {
+ *      },
+ *      reference: collection().doc(),
+ *  });
  *
- * @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.
+ *  // ....
+ *  mutate({data: {test: 'value'}});
+ *  // ....
+ * };
+ * ```
  */
-export const useSetDocMutation = <
-    AppModelType = unknown,
-    DbModelType extends DocumentData = DocumentData,
-    TContext = unknown
->({
+export const useSetDocMutation = <AppModelType extends AppModel = AppModel, TContext = unknown>({
     reference,
     options
-}: UseSetDocMutationOptions<AppModelType, DbModelType, TContext>) => {
+}: UseSetDocMutationOptions<AppModelType, TContext>) => {
     const mutationKey = useMemo(() => [reference?.path], [reference?.path]);
 
     return useMutation({
         ...options,
-        mutationFn: ({ data }) => {
+        mutationKey,
+        mutationFn: async ({ data }) => {
             if (!reference) {
                 throw new Error("Reference is undefined");
             }
-            return setDoc<AppModelType, DbModelType>(reference, data);
-        },
-        mutationKey
+            await setDoc<AppModelType, AppModelType>(reference, data);
+            const docSnap = await getDoc(reference);
+            return { ...(docSnap.data() as AppModelType), uid: docSnap.id };
+        }
     });
 };

package/web/firestore/useUpdateDocMutation.d.ts

@@ -1,31 +1,53 @@
 import { UseMutationOptions } from "@tanstack/react-query";
-import { DocumentData, FirestoreDataConverter, DocumentReference, UpdateData } from "firebase/firestore";
+import { DocumentReference, UpdateData } from "firebase/firestore";
 import { FirebaseError } from "firebase/app";
-export type UseUpdateDocMutationValues<DbModelType> = {
-    data: UpdateData<DbModelType>;
+import { AppModel } from "../../types";
+/**
+ * @inline
+ */
+export type UseUpdateDocMutationValues<AppModelType extends AppModel = AppModel> = {
+    /**
+     * Data to write
+     */
+    data: UpdateData<AppModelType>;
 };
-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">;
+/**
+ * @inline
+ */
+export type UseUpdateDocMutationOptions<AppModelType extends AppModel = AppModel, TContext = unknown> = {
+    /**
+     * Reference to a document that must be updated
+     */
+    reference: DocumentReference<AppModelType, AppModelType> | null;
+    /**
+     * Options for useMutation hook excluding mutationFn.
+     */
+    options?: Omit<UseMutationOptions<AppModelType, FirebaseError, UseUpdateDocMutationValues<AppModelType>, TContext>, "mutationFn">;
 };
 /**
- * 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.
+ * Executes a mutation and returns updated document
  *
- * @param {UseUpdateDocMutationOptions<AppModelType, DbModelType, TContext>} options - Configuration options for the mutation,
- * including Firestore reference, an optional Firestore data converter, and additional mutation options.
+ * @group Hook
  *
- * `reference` - The Firestore document reference that identifies the document to be updated.
+ * @param {UseUpdateDocMutationOptions<AppModelType>} options - Configuration options for mutation.
  *
- * `converter` - An optional Firestore converter for transforming the database response into a custom type.
+ * @returns {UseMutationResult<AppModelType, Error, UseAddDocMutationValues<AppModelType>, TContext>}  A mutation result
  *
- * `options` - Additional options that customize the mutation's behavior.
+ * @example
+ * ```jsx
+ * export const MyComponent = () => {
+ *  const {mutate} = useUpdateDocMutation({
+ *      options: {
+ *      },
+ *      reference: collection().doc(),
+ *  });
  *
- * @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.
+ *  // ....
+ *  mutate({data: {test: 'value'}});
+ *  // ....
+ * };
+ * ```
  */
-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>;
+export declare const useUpdateDocMutation: <AppModelType extends AppModel = AppModel, TContext = unknown>({ reference, options }: UseUpdateDocMutationOptions<AppModelType, TContext>) => import("@tanstack/react-query").UseMutationResult<AppModelType & {
+    uid: string;
+}, FirebaseError, UseUpdateDocMutationValues<AppModelType>, TContext>;

package/web/firestore/useUpdateDocMutation.js

@@ -2,25 +2,30 @@ 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.
+ * Executes a mutation and returns updated document
  *
- * 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.
+ * @group Hook
  *
- * @param {UseUpdateDocMutationOptions<AppModelType, DbModelType, TContext>} options - Configuration options for the mutation,
- * including Firestore reference, an optional Firestore data converter, and additional mutation options.
+ * @param {UseUpdateDocMutationOptions<AppModelType>} options - Configuration options for mutation.
  *
- * `reference` - The Firestore document reference that identifies the document to be updated.
+ * @returns {UseMutationResult<AppModelType, Error, UseAddDocMutationValues<AppModelType>, TContext>}  A mutation result
  *
- * `converter` - An optional Firestore converter for transforming the database response into a custom type.
+ * @example
+ * ```jsx
+ * export const MyComponent = () => {
+ *  const {mutate} = useUpdateDocMutation({
+ *      options: {
+ *      },
+ *      reference: collection().doc(),
+ *  });
  *
- * `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.
+ *  // ....
+ *  mutate({data: {test: 'value'}});
+ *  // ....
+ * };
+ * ```
  */
-export const useUpdateDocMutation = ({ reference, converter, options = {} }) => {
+export const useUpdateDocMutation = ({ reference, options = {} }) => {
     const mutationKey = useMemo(() => [reference?.path], [reference?.path]);
     return useMutation({
         ...options,
@@ -29,8 +34,8 @@ export const useUpdateDocMutation = ({ reference, converter, options = {} }) =>
                 throw new Error("Reference is undefined");
             }
             await updateDoc(reference, data);
-            const docSnap = await getDoc(converter ? reference.withConverter(converter) : reference);
-            return docSnap.data();
+            const docSnap = await getDoc(reference);
+            return { ...docSnap.data(), uid: docSnap.id };
         },
         mutationKey
     });

package/web/firestore/useUpdateDocMutation.ts

@@ -1,61 +1,65 @@
 import { useMutation, UseMutationOptions } from "@tanstack/react-query";
-import {
-    DocumentData,
-    updateDoc,
-    getDoc,
-    FirestoreDataConverter,
-    DocumentReference,
-    UpdateData
-} from "firebase/firestore";
+import { updateDoc, getDoc, DocumentReference, UpdateData } from "firebase/firestore";
 
 import { FirebaseError } from "firebase/app";
 import { useMemo } from "react";
+import { AppModel } from "../../types";
 
-export type UseUpdateDocMutationValues<DbModelType> = {
-    data: UpdateData<DbModelType>;
+/**
+ * @inline
+ */
+export type UseUpdateDocMutationValues<AppModelType extends AppModel = AppModel> = {
+    /**
+     * Data to write
+     */
+    data: UpdateData<AppModelType>;
 };
 
-export type UseUpdateDocMutationOptions<
-    AppModelType extends DocumentData = DocumentData,
-    DbModelType extends DocumentData = DocumentData,
-    TContext = unknown
-> = {
-    reference: DocumentReference<AppModelType, DbModelType> | null;
-    converter?: FirestoreDataConverter<AppModelType, DbModelType>;
+/**
+ * @inline
+ */
+export type UseUpdateDocMutationOptions<AppModelType extends AppModel = AppModel, TContext = unknown> = {
+    /**
+     * Reference to a document that must be updated
+     */
+    reference: DocumentReference<AppModelType, AppModelType> | null;
+    /**
+     * Options for useMutation hook excluding mutationFn.
+     */
     options?: Omit<
-        UseMutationOptions<AppModelType, FirebaseError, UseUpdateDocMutationValues<DbModelType>, TContext>,
-        "mutationFn" | "mutationKey"
+        UseMutationOptions<AppModelType, FirebaseError, UseUpdateDocMutationValues<AppModelType>, TContext>,
+        "mutationFn"
     >;
 };
 
 /**
- * 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.
+ * Executes a mutation and returns updated document
  *
- * @param {UseUpdateDocMutationOptions<AppModelType, DbModelType, TContext>} options - Configuration options for the mutation,
- * including Firestore reference, an optional Firestore data converter, and additional mutation options.
+ * @group Hook
  *
- * `reference` - The Firestore document reference that identifies the document to be updated.
+ * @param {UseUpdateDocMutationOptions<AppModelType>} options - Configuration options for mutation.
  *
- * `converter` - An optional Firestore converter for transforming the database response into a custom type.
+ * @returns {UseMutationResult<AppModelType, Error, UseAddDocMutationValues<AppModelType>, TContext>}  A mutation result
  *
- * `options` - Additional options that customize the mutation's behavior.
+ * @example
+ * ```jsx
+ * export const MyComponent = () => {
+ *  const {mutate} = useUpdateDocMutation({
+ *      options: {
+ *      },
+ *      reference: collection().doc(),
+ *  });
  *
- * @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.
+ *  // ....
+ *  mutate({data: {test: 'value'}});
+ *  // ....
+ * };
+ * ```
  */
-export const useUpdateDocMutation = <
-    AppModelType extends DocumentData = DocumentData,
-    DbModelType extends DocumentData = DocumentData,
-    TContext = unknown
->({
+export const useUpdateDocMutation = <AppModelType extends AppModel = AppModel, TContext = unknown>({
     reference,
-    converter,
     options = {}
-}: UseUpdateDocMutationOptions<AppModelType, DbModelType, TContext>) => {
+}: UseUpdateDocMutationOptions<AppModelType, TContext>) => {
     const mutationKey = useMemo(() => [reference?.path], [reference?.path]);
 
     return useMutation({
@@ -65,9 +69,9 @@ export const useUpdateDocMutation = <
                 throw new Error("Reference is undefined");
             }
 
-            await updateDoc<AppModelType, DbModelType>(reference, data);
-            const docSnap = await getDoc(converter ? reference.withConverter(converter) : reference);
-            return docSnap.data() as AppModelType;
+            await updateDoc<AppModelType, AppModelType>(reference, data);
+            const docSnap = await getDoc(reference);
+            return { ...(docSnap.data() as AppModelType), uid: docSnap.id };
         },
         mutationKey
     });

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

@@ -0,0 +1,47 @@
+import { QueryFilterConstraint as FBQueryFilterConstraint, QueryCompositeFilterConstraint as FBQueryCompositeFilterConstraint, WhereFilterOp } from "firebase/firestore";
+import { AppModel } from "../../../types/AppModel";
+export type QueryFilterConstraint = FBQueryFilterConstraint | FBQueryCompositeFilterConstraint;
+export type QueryElement<AppModelType extends AppModel = AppModel> = {
+    operator?: "OR" | "AND";
+    children?: QueryElement[];
+    field?: keyof (AppModelType & {
+        documentId?: string[];
+    });
+    value?: AppModelType[keyof AppModelType];
+    op?: WhereFilterOp;
+};
+export type CompositeFilter<AppModelType extends AppModel = AppModel> = {
+    operator: "OR" | "AND";
+    children: QueryElement<AppModelType & {
+        documentId?: string[];
+    }>[];
+};
+/**
+ * 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 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: <AppModelType extends AppModel = AppModel>(query: QueryElement<AppModelType>) => QueryFilterConstraint | null;

package/web/firestore/utils/buildCompositeFilter.js

@@ -0,0 +1,42 @@
+import { or, and, where, documentId } from "firebase/firestore";
+/**
+ * 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 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) {
+        const queryConstraints = query.children.map(buildCompositeFilter).filter((constraint) => !!constraint);
+        if (queryConstraints.length <= 0) {
+            return null;
+        }
+        return query.operator === "OR" ? or(...queryConstraints) : and(...queryConstraints);
+    }
+    if (query.field && query.op) {
+        return where(query.field === "documentId" ? documentId() : query.field, query.op, query.value);
+    }
+    return null;
+};

package/web/firestore/utils/buildCompositeFilter.ts

@@ -0,0 +1,73 @@
+import {
+    QueryFilterConstraint as FBQueryFilterConstraint,
+    QueryCompositeFilterConstraint as FBQueryCompositeFilterConstraint,
+    WhereFilterOp,
+    or,
+    and,
+    where,
+    documentId
+} from "firebase/firestore";
+import { AppModel } from "../../../types/AppModel";
+
+export type QueryFilterConstraint = FBQueryFilterConstraint | FBQueryCompositeFilterConstraint;
+
+export type QueryElement<AppModelType extends AppModel = AppModel> = {
+    operator?: "OR" | "AND";
+    children?: QueryElement[];
+    field?: keyof (AppModelType & { documentId?: string[] });
+    value?: AppModelType[keyof AppModelType];
+    op?: WhereFilterOp;
+};
+
+export type CompositeFilter<AppModelType extends AppModel = AppModel> = {
+    operator: "OR" | "AND";
+    children: QueryElement<AppModelType & { documentId?: string[] }>[];
+};
+/**
+ * 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 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 = <AppModelType extends AppModel = AppModel>(
+    query: QueryElement<AppModelType>
+): QueryFilterConstraint | null => {
+    if (query.children) {
+        const queryConstraints = query.children.map(buildCompositeFilter).filter((constraint) => !!constraint);
+
+        if (queryConstraints.length <= 0) {
+            return null;
+        }
+
+        return (query as CompositeFilter).operator === "OR" ? or(...queryConstraints) : and(...queryConstraints);
+    }
+
+    if (query.field && query.op) {
+        return where(query.field === "documentId" ? documentId() : (query.field as string), query.op, query.value);
+    }
+
+    return null;
+};

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

@@ -0,0 +1,23 @@
+import { QueryNonFilterConstraint } from "firebase/firestore";
+import { AppModel, NonFilterQueryConstraint } from "../../../types";
+/**
+ * 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;