react-query-firebase 2.13.2 → 2.13.4

package/web/firestore/useCollectionReference.ts

@@ -1,58 +0,0 @@
-import { collection, CollectionReference, DocumentReference } from "firebase/firestore";
-
-import { useMemo } from "react";
-import { useFirestore } from "./useFirestore";
-import { AppModel } from "../../types";
-
-/**
- * @inline
- */
-export type UseCollectionReferenceOptions<AppModelType extends AppModel = AppModel> = {
-    /**
-     * CollectionReference or DocumentReference that is used as a root to lookup a sub-collection
-     */
-    reference?: CollectionReference<AppModelType, AppModelType> | DocumentReference<AppModelType, AppModelType>;
-    /**
-     * A slash-separated path to a collection.
-     */
-    path: string;
-    /**
-     * Additional path segments that will be applied relative
-     */
-    pathSegments?: string[];
-};
-
-/**
- * Gets a `CollectionReference` instance that refers to a subcollection of
- * `reference` at the specified relative path.
- *
- * @group Hook
- *
- * @param {UseCollectionReferenceOptions<AppModelType>} options - Options
- *
- * @returns {CollectionReference<AppModelType, AppModelType>} A reference to a Firestore collection
- *
- * @example
- * ```jsx
- * export const MyComponent = () => {
- *  const ref = useCollectionReference({
- *      path: 'todos'
- *  });
- * };
- * ```
- */
-export const useCollectionReference = <AppModelType extends AppModel = AppModel>({
-    path,
-    reference,
-    pathSegments
-}: UseCollectionReferenceOptions<AppModelType>) => {
-    const db = useFirestore();
-
-    return useMemo(() => {
-        return !reference
-            ? collection(db, path || "", ...(pathSegments || []))
-            : reference.type === "collection"
-              ? collection(reference, path, ...(pathSegments || []))
-              : collection(reference, path, ...(pathSegments || []));
-    }, [path, reference, pathSegments, db]) as CollectionReference<AppModelType, AppModelType>;
-};

package/web/firestore/useCompositeFilter.ts

@@ -1,55 +0,0 @@
-import { and, or } from "firebase/firestore";
-import { useMemo } from "react";
-import { AppModel } from "../../types";
-import { CompositeFilter, buildCompositeFilter, QueryFilterConstraint } from "./utils/buildCompositeFilter";
-
-/**
- * @inline
- */
-export type UseCompositeFilter<AppModelType extends AppModel = AppModel> = {
-    query?: CompositeFilter<AppModelType>;
-};
-
-/**
- * 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
- *
- * @returns {QueryFilterConstraint | null}
- *
- * @example
- * ```jsx
- * export const MyComponent = () => {
- *  const filter = useCompositeFilter({
- *      operator: "AND",
- *      children: [
- *          {
- *              field: "field",
- *              value: "value",
- *              op: "=="
- *          },
- *          ...(query ? [query] : [])
- *      ]
- *  });
- *  console.log(filter);
- * };
- * ```
- */
-export const useCompositeFilter = <AppModelType extends AppModel = AppModel>({
-    query
-}: UseCompositeFilter<AppModelType>) => {
-    return useMemo(() => {
-        const queryConstraints =
-            query?.children?.map?.((subQuery) => buildCompositeFilter(subQuery))?.filter<QueryFilterConstraint>?.(
-                (constraint) => !!constraint
-            ) ?? [];
-
-        if (queryConstraints.length <= 0) {
-            return undefined;
-        }
-        return query?.operator === "OR" ? or(...queryConstraints) : and(...queryConstraints);
-    }, [query]);
-};

package/web/firestore/useCountQuery.ts

@@ -1,90 +0,0 @@
-import {
-    getCountFromServer,
-    CollectionReference,
-    query,
-    QueryCompositeFilterConstraint,
-    QueryConstraint,
-    QueryNonFilterConstraint
-} from "firebase/firestore";
-
-import {
-    UseQueryResult,
-    useQuery as useReactQuery,
-    UseQueryOptions as UseReactQueryOptions
-} from "@tanstack/react-query";
-import { QueryFilterConstraint } from "./utils/buildCompositeFilter";
-import { AppModel } from "../../types";
-
-/**
- * @inline
- */
-type UseCountQueryOptions<AppModelType extends AppModel = AppModel> = {
-    /**
-     * Reqct-query options that must include queryKey and shall not define queryFn
-     */
-    options: Omit<UseReactQueryOptions<number, Error, number>, "queryFn"> &
-        Required<Pick<UseReactQueryOptions<number, Error, number>, "queryKey">>;
-
-    /**
-     * Reference to a Firestore collection
-     */
-    collectionReference: CollectionReference<AppModelType, AppModelType>;
-
-    /**
-     * Non composite filter constraints such as limit, order, where
-     */
-    queryConstraints?: QueryConstraint[] | QueryNonFilterConstraint[];
-
-    /**
-     * Composite filter
-     */
-    compositeFilter?: QueryFilterConstraint;
-};
-
-/**
- * Executes a query with specified constraints and returns the count of matched documents.
- *
- * @group Hook
- *
- * @param {UseCountQueryOptions<AppModelType>} options - Configuration options for the query.
- *
- * @returns {UseQueryResult<number>} An object containing the number of documents that match the query.
- *
- * @example
- * ```jsx
- * export const MyComponent = () => {
- *  const count = useCountQuery({
- *      options: {
- *          queryKey: ['key']
- *      },
- *      collectionReference: collection(),
- *  });
- *  console.log(count);
- * };
- * ```
- */
-export const useCountQuery = <AppModelType extends AppModel = AppModel>({
-    options,
-    collectionReference,
-    queryConstraints = [],
-    compositeFilter
-}: UseCountQueryOptions<AppModelType>): UseQueryResult<number> => {
-    return useReactQuery({
-        ...options,
-        queryFn: async () => {
-            const queryToExecute = compositeFilter
-                ? query(
-                      collectionReference,
-                      compositeFilter as QueryCompositeFilterConstraint,
-                      ...(queryConstraints as QueryNonFilterConstraint[])
-                  )
-                : query(collectionReference, ...queryConstraints);
-
-            const querySnapshot = await getCountFromServer(queryToExecute);
-            if (querySnapshot) {
-                return querySnapshot.data().count;
-            }
-            return 0;
-        }
-    });
-};

package/web/firestore/useDeleteDocMutation.ts

@@ -1,69 +0,0 @@
-import { useMutation, UseMutationOptions } from "@tanstack/react-query";
-import { deleteDoc, WithFieldValue, DocumentReference } from "firebase/firestore";
-
-import { FirebaseError } from "firebase/app";
-import { useMemo } from "react";
-import { AppModel } from "../../types";
-
-/**
- * @inline
- */
-export type UseDeleteDocMutationValues<AppModelType extends AppModel = AppModel> = {
-    data: WithFieldValue<AppModelType>;
-};
-
-/**
- * @inline
- */
-export type UseDeleteDocMutationOptions<AppModelType extends AppModel = AppModel, TContext = unknown> = {
-    /**
-     * A reference to a firestore document
-     */
-    reference: DocumentReference<AppModelType, AppModelType> | null;
-    /**
-     * Options for useMutation hook excluding mutationFn. MutationKey will be equal to reference.path by default.
-     */
-    options?: Omit<UseMutationOptions<void, FirebaseError, void, TContext>, "mutationFn">;
-};
-
-/**
- * Executes a query with specified constraints and returns the count of matched documents.
- *
- * @group Hook
- *
- * @param {UseDeleteDocMutationOptions<AppModelType>} options - Configuration options for the query.
- *
- * @returns {UseMutationResult<void, Error, UseDeleteDocMutationValues<AppModelType>, TContext>}  A mutation result
- *
- * @example
- * ```jsx
- * export const MyComponent = () => {
- *  const {mutate} = useDeleteDocMutation({
- *      options: {
- *      },
- *      reference: document(),
- *  });
- *
- *  // ....
- *  mutate();
- *  // ....
- * };
- * ```
- */
-export const useDeleteDocMutation = <AppModelType extends AppModel = AppModel, TContext = unknown>({
-    reference,
-    options = {}
-}: UseDeleteDocMutationOptions<AppModelType, TContext>) => {
-    const mutationKey = useMemo(() => [reference?.path], [reference?.path]);
-
-    return useMutation({
-        mutationKey,
-        ...options,
-        mutationFn: async () => {
-            if (!reference) {
-                throw new Error("Reference is undefined");
-            }
-            await deleteDoc<AppModelType, AppModelType>(reference);
-        }
-    });
-};

package/web/firestore/useDocReference.ts

@@ -1,50 +0,0 @@
-import { DocumentReference } from "firebase/firestore";
-
-import { useEffect, useRef } from "react";
-import { useFirestore } from "./useFirestore";
-import { AppModel } from "../../types";
-import { getDocRef, GetDocRefOptions } from "./utils/getDocRef";
-
-/**
- * @inline
- */
-export type UseDocReferenceOptions<AppModelType extends AppModel = AppModel> = Omit<
-    GetDocRefOptions<AppModelType>,
-    "db"
->;
-
-/**
- * Gets a `CollectionReference` instance
- *
- * @group Hook
- *
- * @param {UseDocReferenceOptions<AppModelType>} options - Options
- *
- * @returns {DocumentReference<AppModelType, AppModelType> | null} A reference to a Firestore document
- *
- * @example
- * ```jsx
- * export const MyComponent = () => {
- *  const ref = useDocReference({
- *      reference: collection('todos')
- *      path: 'first'
- *  });
- * };
- * ```
- */
-export const useDocReference = <AppModelType extends AppModel = AppModel>({
-    path,
-    reference,
-    pathSegments
-}: UseDocReferenceOptions<AppModelType>) => {
-    const db = useFirestore();
-    const ref = useRef<DocumentReference<AppModelType, AppModelType> | null>(
-        getDocRef({ db, path, pathSegments, reference })
-    );
-
-    useEffect(() => {
-        ref.current = getDocRef({ db, path, pathSegments, reference });
-    }, [path, reference, pathSegments, db]);
-
-    return ref.current;
-};

package/web/firestore/useDocReferences.ts

@@ -1,40 +0,0 @@
-import { useMemo } from "react";
-import { useFirestore } from "./useFirestore";
-import { AppModel } from "../../types";
-import { getDocRef, GetDocRefOptions } from "./utils/getDocRef";
-
-/**
- * @inline
- */
-export type UseDocReferencesOptions<AppModelType extends AppModel = AppModel> = {
-    references: Omit<GetDocRefOptions<AppModelType>, "db">[];
-};
-
-/**
- * Gets `CollectionReference` instances
- *
- * @group Hook
- *
- * @param {UseDocReferencesOptions<AppModelType>} options - Options
- *
- * @returns {Array<DocumentReference<AppModelType, AppModelType> | null>} A reference to a Firestore document
- *
- * @example
- * ```jsx
- * export const MyComponent = () => {
- *  const ref = useDocReference({
- *      reference: collection('todos')
- *      path: 'first'
- *  });
- * };
- * ```
- */
-export const useDocReferences = <AppModelType extends AppModel = AppModel>({
-    references
-}: UseDocReferencesOptions<AppModelType>) => {
-    const db = useFirestore();
-
-    return useMemo(() => {
-        return references.map(({ path, reference, pathSegments }) => getDocRef({ db, reference, path, pathSegments }));
-    }, [references, db]);
-};

package/web/firestore/useEnsureDoc.ts

@@ -1,92 +0,0 @@
-import { useQuery, UseQueryOptions } from "@tanstack/react-query";
-import { FirestoreError, getDoc, setDoc } from "firebase/firestore";
-
-import { AppModel } from "../../types";
-import { GetDocDataOptions } from "./utils/getDocData";
-import { getDocRef } from "./utils/getDocRef";
-import { getDocSnap } from "./utils/getDocSnap";
-import { useFirestore } from "./useFirestore";
-
-/**
- * @inline
- */
-export type UseEnsureDocOptions<AppModelType extends AppModel = AppModel> = {
-    /**
-     * Reference to a document that must be written
-     */
-    defaults: AppModelType;
-
-    /**
-     * Options for useMutation hook excluding mutationFn.
-     */
-    options: Omit<UseQueryOptions<AppModelType, Error, AppModelType>, "queryFn"> &
-        Required<Pick<UseQueryOptions<AppModelType, Error, AppModelType>, "queryKey">>;
-} & Omit<GetDocDataOptions<AppModelType>, "db">;
-
-/**
- * This hook checks if a doc with a requested reference exists.
- * It creates a document with requested data if it does not exist.
- *
- * @group Hook
- *
- * @param {UseEnsureDocOptions<AppModelType>} options - Configuration options for mutation.
- *
- * @returns {UseQueryResult<AppModelType, Error>}  A mutation result
- *
- * @example
- * ```jsx
- * export const MyComponent = () => {
- *  const {data} = useEnsureDocQuery({
- *      options: {
- *      },
- *      reference: collection().doc(),
- *      defaults: {prop1: 'value1'}
- *  });
- *
- * };
- * ```
- */
-export const useEnsureDoc = <AppModelType extends AppModel = AppModel>({
-    reference,
-    path,
-    pathSegments,
-    defaults,
-    options
-}: UseEnsureDocOptions<AppModelType>) => {
-    const db = useFirestore();
-
-    return useQuery({
-        ...options,
-        queryFn: async () => {
-            const createDoc = async () => {
-                const docRef = getDocRef({ db, reference, path, pathSegments });
-                if (!docRef) {
-                    throw new Error(
-                        `Cannot fetch document reference using data: ${reference?.path}, ${path}, ${pathSegments?.join("/")}`
-                    );
-                }
-
-                await setDoc<AppModelType, AppModelType>(docRef, defaults);
-                const docSnap = await getDoc(docRef);
-                return { ...(docSnap.data() as AppModelType), uid: docSnap.id };
-            };
-
-            try {
-                const existingDocSnap = await getDocSnap({ db, path, pathSegments, reference });
-
-                if (existingDocSnap?.exists()) {
-                    return { ...(existingDocSnap.data() as AppModelType), uid: existingDocSnap.id };
-                }
-
-                return createDoc();
-            } catch (e) {
-                // permission denied error may arise because of a security rule
-                if ((e as FirestoreError).code === "permission-denied") {
-                    return createDoc();
-                }
-
-                throw e;
-            }
-        }
-    });
-};

package/web/firestore/useFirestore.js

@@ -1,13 +0,0 @@
-import { useContext } from "react";
-import { FirebaseContext } from "../context/FirebaseContext";
-/**
- * Returns an instance of firestore bound to the closest context.
- *
- * @group Hook
- *
- * @returns {Firestore}
- */
-export const useFirestore = () => {
-    const { firestore } = useContext(FirebaseContext);
-    return firestore;
-};

package/web/firestore/useGetDocData.ts

@@ -1,52 +0,0 @@
-import { useFirestore } from "./useFirestore";
-import { getDocData, GetDocDataOptions } from "./utils/getDocData";
-import { useQuery, UseQueryOptions } from "@tanstack/react-query";
-import { AppModel } from "../../types";
-
-/**
- * @inline
- */
-type UseGetDocOptions<AppModelType extends AppModel = AppModel> = {
-    /**
-     * Reqct-query options that must include queryKey and shall not define queryFn
-     */
-    options: Omit<UseQueryOptions<AppModelType | null, Error, AppModelType>, "queryFn"> &
-        Required<Pick<UseQueryOptions<AppModelType, Error, AppModelType>, "queryKey">>;
-} & Omit<GetDocDataOptions<AppModelType>, "db">;
-
-/**
- * Executes a query on a Firestore data source and returns the resulting document.
- *
- * @group Hook
- *
- * @param {UseGetDocOptions<AppModelType>} options - Configuration options for the query.
- *
- * @returns {UseQueryResult<AppModelType, Error>} An object containing document's data
- *
- * @example
- * ```jsx
- * export const MyComponent = () => {
- *  const doc = useGetDocData({
- *      options: {
- *          queryKey: ['key']
- *      },
- *      reference: collection(),
- *      path: 'id'
- *  });
- *  console.log(doc);
- * };
- * ```
- */
-export const useGetDocData = <AppModelType extends AppModel = AppModel>({
-    options,
-    reference,
-    path,
-    pathSegments
-}: UseGetDocOptions<AppModelType>) => {
-    const db = useFirestore();
-
-    return useQuery({
-        ...options,
-        queryFn: () => getDocData<AppModelType>({ db, reference, path, pathSegments })
-    });
-};

package/web/firestore/useGetRealtimeDocData.ts

@@ -1,105 +0,0 @@
-import { DocumentReference, onSnapshot } from "firebase/firestore";
-
-import { useEffect, useMemo, useState } from "react";
-import { FirebaseError } from "firebase/app";
-import { useDocReference } from "./useDocReference";
-import { AppModel } from "../../types";
-
-/**
- * @inline
- */
-export type UseGetRealtimeDocDataOptions<AppModelType extends AppModel = AppModel> = {
-    /**
-     * A slash-separated path to a document. Has to be omitted to use
-     */
-    path?: string;
-    /**
-     * A reference to a collection.
-     */
-    reference?: DocumentReference<AppModelType, AppModelType>;
-    /**
-     * 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>} 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 = <AppModelType extends AppModel = AppModel>({
-    path,
-    pathSegments,
-    reference,
-    onError
-}: UseGetRealtimeDocDataOptions<AppModelType>): UseGetRealtimeDocDataResult<AppModelType> => {
-    const ref = useDocReference({ path, reference, pathSegments });
-    const [doc, setDoc] = useState<AppModelType | null>(null);
-    const [isError, setIsError] = useState(false);
-    const [isFetching, setIsFetching] = useState(true);
-    const [error, setError] = useState<FirebaseError | null>(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 || {}), uid: ref?.id ?? "" } as AppModelType,
-            isError,
-            isFetching,
-            error
-        }),
-        [doc, isError, error, ref, isFetching]
-    );
-};