react-query-firebase 2.3.3 → 2.4.1

package/web/firestore/utils/buildQueryConstraint.ts

@@ -0,0 +1,55 @@
+import {
+    QueryNonFilterConstraint,
+    orderBy,
+    startAt,
+    startAfter,
+    endAt,
+    endBefore,
+    limit,
+    limitToLast
+} 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 const buildQueryConstraint = <AppModelType extends AppModel = AppModel>(
+    constraint: NonFilterQueryConstraint<AppModelType>
+): QueryNonFilterConstraint => {
+    switch (constraint.type) {
+        case "orderBy":
+            return orderBy(constraint.fieldPath as string, constraint.directionStr);
+        case "startAt":
+            return startAt(...constraint.arguments);
+        case "startAfter":
+            return startAfter(...constraint.arguments);
+        case "endAt":
+            return endAt(constraint.value, constraint.key);
+        case "endBefore":
+            return endBefore(constraint.value, constraint.key);
+        case "limit":
+            return limit(constraint.limit);
+        case "limitToLast":
+            return limitToLast(constraint.limit);
+        default:
+            throw new Error(`Unsupported constaint ${JSON.stringify(constraint)}`);
+    }
+};

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

@@ -1,18 +1,20 @@
-import { DocumentData } from "firebase/firestore";
 import { GetDocSnapOptions } from "./getDocSnap";
-export type GetDocDataOptions<AppModelType extends DocumentData = DocumentData, DbModelType extends DocumentData = DocumentData> = GetDocSnapOptions<AppModelType, DbModelType>;
+import { AppModel } from "../../../types";
 /**
- * Asynchronously retrieves document data from a specified database and reference.
+ * @inline
+ */
+export type GetDocDataOptions<AppModelType extends AppModel = AppModel> = GetDocSnapOptions<AppModelType>;
+/**
+ * Asynchronously retrieves document data from a specified database reference.
  * Utilizes the helper function `getDocSnap` to fetch the document snapshot and
  * checks if the document exists before returning its data.
  *
- * @param {Object} options - The options for fetching document data.
- * @param {FirebaseFirestore} options.db - The Firestore database instance.
- * @param {DocumentReference=} options.reference - The document reference. This is an optional parameter.
- * @param {string=} options.path - The path to the document in the database. This is an optional parameter.
- * @param {Array<string>=} options.pathSegments - The path segments for the document's path. This is an optional parameter.
+ * @group Utility
+ *
+ * @param {GetDocDataOptions<AppModelType>} options - The options for fetching document data.
  *
- * @returns {Promise<AppModelType | null>} Returns a promise that resolves to the document data if it exists,
- * or null if the document does not exist.
+ * @returns {Promise<AppModelType | null>} Returns a promise that resolves to the document data if it exists, or null if the document does not exist.
  */
-export declare const getDocData: <AppModelType extends DocumentData = DocumentData, DbModelType extends DocumentData = DocumentData>({ db, reference, path, pathSegments }: GetDocDataOptions<AppModelType, DbModelType>) => Promise<AppModelType | null>;
+export declare const getDocData: <AppModelType extends AppModel = AppModel>({ db, reference, path, pathSegments }: GetDocDataOptions<AppModelType>) => Promise<(AppModelType & {
+    uid: string;
+}) | null>;

package/web/firestore/utils/getDocData.js

@@ -1,22 +1,19 @@
 import { getDocSnap } from "./getDocSnap";
 /**
- * Asynchronously retrieves document data from a specified database and reference.
+ * Asynchronously retrieves document data from a specified database reference.
  * Utilizes the helper function `getDocSnap` to fetch the document snapshot and
  * checks if the document exists before returning its data.
  *
- * @param {Object} options - The options for fetching document data.
- * @param {FirebaseFirestore} options.db - The Firestore database instance.
- * @param {DocumentReference=} options.reference - The document reference. This is an optional parameter.
- * @param {string=} options.path - The path to the document in the database. This is an optional parameter.
- * @param {Array<string>=} options.pathSegments - The path segments for the document's path. This is an optional parameter.
+ * @group Utility
  *
- * @returns {Promise<AppModelType | null>} Returns a promise that resolves to the document data if it exists,
- * or null if the document does not exist.
+ * @param {GetDocDataOptions<AppModelType>} options - The options for fetching document data.
+ *
+ * @returns {Promise<AppModelType | null>} Returns a promise that resolves to the document data if it exists, or null if the document does not exist.
  */
 export const getDocData = async ({ db, reference, path, pathSegments }) => {
     const docSnap = await getDocSnap({ db, reference, path, pathSegments });
     if (docSnap && docSnap.exists()) {
-        return docSnap.data();
+        return { ...docSnap.data(), uid: docSnap.id };
     }
     return null;
 };

package/web/firestore/utils/getDocData.ts

@@ -1,38 +1,32 @@
-import { DocumentData } from "firebase/firestore";
 import { getDocSnap, GetDocSnapOptions } from "./getDocSnap";
+import { AppModel } from "../../../types";
 
-export type GetDocDataOptions<
-    AppModelType extends DocumentData = DocumentData,
-    DbModelType extends DocumentData = DocumentData
-> = GetDocSnapOptions<AppModelType, DbModelType>;
+/**
+ * @inline
+ */
+export type GetDocDataOptions<AppModelType extends AppModel = AppModel> = GetDocSnapOptions<AppModelType>;
 
 /**
- * Asynchronously retrieves document data from a specified database and reference.
+ * Asynchronously retrieves document data from a specified database reference.
  * Utilizes the helper function `getDocSnap` to fetch the document snapshot and
  * checks if the document exists before returning its data.
  *
- * @param {Object} options - The options for fetching document data.
- * @param {FirebaseFirestore} options.db - The Firestore database instance.
- * @param {DocumentReference=} options.reference - The document reference. This is an optional parameter.
- * @param {string=} options.path - The path to the document in the database. This is an optional parameter.
- * @param {Array<string>=} options.pathSegments - The path segments for the document's path. This is an optional parameter.
+ * @group Utility
+ *
+ * @param {GetDocDataOptions<AppModelType>} options - The options for fetching document data.
  *
- * @returns {Promise<AppModelType | null>} Returns a promise that resolves to the document data if it exists,
- * or null if the document does not exist.
+ * @returns {Promise<AppModelType | null>} Returns a promise that resolves to the document data if it exists, or null if the document does not exist.
  */
-export const getDocData = async <
-    AppModelType extends DocumentData = DocumentData,
-    DbModelType extends DocumentData = DocumentData
->({
+export const getDocData = async <AppModelType extends AppModel = AppModel>({
     db,
     reference,
     path,
     pathSegments
-}: GetDocDataOptions<AppModelType, DbModelType>) => {
-    const docSnap = await getDocSnap<AppModelType, DbModelType>({ db, reference, path, pathSegments });
+}: GetDocDataOptions<AppModelType>) => {
+    const docSnap = await getDocSnap<AppModelType>({ db, reference, path, pathSegments });
 
     if (docSnap && docSnap.exists()) {
-        return docSnap.data();
+        return { ...docSnap.data(), uid: docSnap.id };
     }
 
     return null;

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

@@ -1,19 +1,22 @@
-import { CollectionReference, DocumentData, DocumentReference, Firestore } from "firebase/firestore";
-export type GetDocRefOptions<AppModelType extends DocumentData = DocumentData, DbModelType extends DocumentData = DocumentData> = {
+import { CollectionReference, DocumentReference, Firestore } from "firebase/firestore";
+import { AppModel } from "../../../types";
+/**
+ * @inline
+ */
+export type GetDocRefOptions<AppModelType extends AppModel = AppModel> = {
     db: Firestore;
-    reference?: CollectionReference<AppModelType, DbModelType> | DocumentReference<AppModelType, DbModelType>;
+    reference?: CollectionReference<AppModelType, AppModelType> | DocumentReference<AppModelType, AppModelType>;
     path?: string;
     pathSegments?: string[];
 };
 /**
  * Retrieves a document reference based on provided database options.
- * Either `reference` or `path` must be provided, not both.
+ * Either `reference` or `path`.
+ *
+ * @group Utility
+ *
+ * @param {GetDocRefOptions<AppModelType>} options - The options for building doc reference.
  *
- * @param {Object} options - The options for getting a document reference.
- * @param {Firestore} options.db - The Firestore database instance.
- * @param {DocumentReference | CollectionReference | null} [options.reference] - Reference to a document or collection.
- * @param {string | null} [options.path] - Path to the document.
- * @param {string[] | null} [options.pathSegments] - Additional path segments if any.
- * @returns {DocumentReference<AppModelType, DbModelType>} The document reference.
+ * @returns {DocumentReference<AppModelType, AppModelType>} Returns a document reference
  */
-export declare const getDocRef: <AppModelType extends DocumentData = DocumentData, DbModelType extends DocumentData = DocumentData>({ db, reference, path, pathSegments }: GetDocRefOptions<AppModelType, DbModelType>) => Promise<DocumentReference<AppModelType, DbModelType>>;
+export declare const getDocRef: <AppModelType extends AppModel = AppModel>({ db, reference, path, pathSegments }: GetDocRefOptions<AppModelType>) => DocumentReference<AppModelType, AppModelType> | null;

package/web/firestore/utils/getDocRef.js

@@ -1,18 +1,17 @@
 import { doc } from "firebase/firestore";
 /**
  * Retrieves a document reference based on provided database options.
- * Either `reference` or `path` must be provided, not both.
+ * Either `reference` or `path`.
  *
- * @param {Object} options - The options for getting a document reference.
- * @param {Firestore} options.db - The Firestore database instance.
- * @param {DocumentReference | CollectionReference | null} [options.reference] - Reference to a document or collection.
- * @param {string | null} [options.path] - Path to the document.
- * @param {string[] | null} [options.pathSegments] - Additional path segments if any.
- * @returns {DocumentReference<AppModelType, DbModelType>} The document reference.
+ * @group Utility
+ *
+ * @param {GetDocRefOptions<AppModelType>} options - The options for building doc reference.
+ *
+ * @returns {DocumentReference<AppModelType, AppModelType>} Returns a document reference
  */
-export const getDocRef = async ({ db, reference, path, pathSegments }) => {
-    if (!reference && !path) {
-        throw new Error("One of the options must be provided: path or reference.");
+export const getDocRef = ({ db, reference, path, pathSegments }) => {
+    if ((!reference && !path) || (reference && !path)) {
+        return null;
     }
     const docRef = !reference
         ? doc(db, path, ...(pathSegments || []))

package/web/firestore/utils/getDocRef.ts

@@ -1,46 +1,43 @@
-import { CollectionReference, doc, DocumentData, DocumentReference, Firestore } from "firebase/firestore";
+import { CollectionReference, doc, DocumentReference, Firestore } from "firebase/firestore";
+import { AppModel } from "../../../types";
 
-export type GetDocRefOptions<
-    AppModelType extends DocumentData = DocumentData,
-    DbModelType extends DocumentData = DocumentData
-> = {
+/**
+ * @inline
+ */
+export type GetDocRefOptions<AppModelType extends AppModel = AppModel> = {
     db: Firestore;
-    reference?: CollectionReference<AppModelType, DbModelType> | DocumentReference<AppModelType, DbModelType>;
+    reference?: CollectionReference<AppModelType, AppModelType> | DocumentReference<AppModelType, AppModelType>;
     path?: string;
     pathSegments?: string[];
 };
 
 /**
  * Retrieves a document reference based on provided database options.
- * Either `reference` or `path` must be provided, not both.
+ * Either `reference` or `path`.
+ *
+ * @group Utility
+ *
+ * @param {GetDocRefOptions<AppModelType>} options - The options for building doc reference.
  *
- * @param {Object} options - The options for getting a document reference.
- * @param {Firestore} options.db - The Firestore database instance.
- * @param {DocumentReference | CollectionReference | null} [options.reference] - Reference to a document or collection.
- * @param {string | null} [options.path] - Path to the document.
- * @param {string[] | null} [options.pathSegments] - Additional path segments if any.
- * @returns {DocumentReference<AppModelType, DbModelType>} The document reference.
+ * @returns {DocumentReference<AppModelType, AppModelType>} Returns a document reference
  */
-export const getDocRef = async <
-    AppModelType extends DocumentData = DocumentData,
-    DbModelType extends DocumentData = DocumentData
->({
+export const getDocRef = <AppModelType extends AppModel = AppModel>({
     db,
     reference,
     path,
     pathSegments
-}: GetDocRefOptions<AppModelType, DbModelType>) => {
-    if (!reference && !path) {
-        throw new Error("One of the options must be provided: path or reference.");
+}: GetDocRefOptions<AppModelType>) => {
+    if ((!reference && !path) || (reference && !path)) {
+        return null;
     }
 
     const docRef = !reference
-        ? doc(db, path as string, ...(pathSegments || []))
+        ? (doc(db, path as string, ...(pathSegments || [])) as DocumentReference<AppModelType, AppModelType>)
         : reference.type === "collection"
-          ? doc(reference, path, ...(pathSegments || []))
+          ? (doc(reference, path, ...(pathSegments || [])) as DocumentReference<AppModelType, AppModelType>)
           : reference.type === "document"
-            ? doc(reference, path as string, ...(pathSegments || []))
+            ? (doc(reference, path as string, ...(pathSegments || [])) as DocumentReference<AppModelType, AppModelType>)
             : null;
 
-    return docRef as DocumentReference<AppModelType, DbModelType>;
+    return docRef;
 };

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

@@ -1,20 +1,18 @@
-import { DocumentData } from "firebase/firestore";
 import { GetDocRefOptions } from "./getDocRef";
-export type GetDocSnapOptions<AppModelType extends DocumentData = DocumentData, DbModelType extends DocumentData = DocumentData> = GetDocRefOptions<AppModelType, DbModelType>;
+import { AppModel } from "../../../types";
+/**
+ * @inline
+ */
+export type GetDocSnapOptions<AppModelType extends AppModel = AppModel> = GetDocRefOptions<AppModelType>;
 /**
  * Asynchronously retrieves a document snapshot from Firestore using a specified document reference
  * or path information. This function handles getting the appropriate document reference based on
  * the parameters provided, and then fetches the document data from Firestore.
  *
- * @param {GetDocSnapOptions<AppModelType, DbModelType>} options - An object containing options
- *                                                                for retrieving the document
- *                                                                snapshot.
- * @param {DocumentData} options.db - The Firestore database instance to perform the operation on.
- * @param {string} options.reference - A string representing a direct Firestore document reference.
- * @param {string} options.path - A Firestore path string leading to the document.
- * @param {string[]} options.pathSegments - An array of path segments to build the Firestore path.
- * @returns {Promise<DocumentData | null>} A promise that resolves to the document data if the
- *                                         document exists, or `null` if the document does not exist
- *                                         or if the reference could not be obtained.
+ * @group Utility
+ *
+ * @param {GetDocSnapOptions<AppModelType>} options - The options for retrieving the document snapshot
+ *
+ * @returns {Promise<DocumentSnapshot<AppModelType, AppModelType> | null>} Returns a document reference
  */
-export declare const getDocSnap: <AppModelType extends DocumentData = DocumentData, DbModelType extends DocumentData = DocumentData>({ db, reference, path, pathSegments }: GetDocSnapOptions<AppModelType, DbModelType>) => Promise<import("@firebase/firestore").DocumentSnapshot<AppModelType, DbModelType> | null>;
+export declare const getDocSnap: <AppModelType extends AppModel = AppModel>({ db, reference, path, pathSegments }: GetDocSnapOptions<AppModelType>) => Promise<import("@firebase/firestore").DocumentSnapshot<AppModelType, AppModelType> | null>;

package/web/firestore/utils/getDocSnap.js

@@ -5,16 +5,11 @@ import { getDocRef } from "./getDocRef";
  * or path information. This function handles getting the appropriate document reference based on
  * the parameters provided, and then fetches the document data from Firestore.
  *
- * @param {GetDocSnapOptions<AppModelType, DbModelType>} options - An object containing options
- *                                                                for retrieving the document
- *                                                                snapshot.
- * @param {DocumentData} options.db - The Firestore database instance to perform the operation on.
- * @param {string} options.reference - A string representing a direct Firestore document reference.
- * @param {string} options.path - A Firestore path string leading to the document.
- * @param {string[]} options.pathSegments - An array of path segments to build the Firestore path.
- * @returns {Promise<DocumentData | null>} A promise that resolves to the document data if the
- *                                         document exists, or `null` if the document does not exist
- *                                         or if the reference could not be obtained.
+ * @group Utility
+ *
+ * @param {GetDocSnapOptions<AppModelType>} options - The options for retrieving the document snapshot
+ *
+ * @returns {Promise<DocumentSnapshot<AppModelType, AppModelType> | null>} Returns a document reference
  */
 export const getDocSnap = async ({ db, reference, path, pathSegments }) => {
     const docRef = await getDocRef({ db, reference, path, pathSegments });

package/web/firestore/utils/getDocSnap.ts

@@ -1,37 +1,30 @@
-import { DocumentData, getDoc as firestoreGetDoc } from "firebase/firestore";
+import { getDoc as firestoreGetDoc } from "firebase/firestore";
 import { getDocRef, GetDocRefOptions } from "./getDocRef";
+import { AppModel } from "../../../types";
 
-export type GetDocSnapOptions<
-    AppModelType extends DocumentData = DocumentData,
-    DbModelType extends DocumentData = DocumentData
-> = GetDocRefOptions<AppModelType, DbModelType>;
+/**
+ * @inline
+ */
+export type GetDocSnapOptions<AppModelType extends AppModel = AppModel> = GetDocRefOptions<AppModelType>;
 
 /**
  * Asynchronously retrieves a document snapshot from Firestore using a specified document reference
  * or path information. This function handles getting the appropriate document reference based on
  * the parameters provided, and then fetches the document data from Firestore.
  *
- * @param {GetDocSnapOptions<AppModelType, DbModelType>} options - An object containing options
- *                                                                for retrieving the document
- *                                                                snapshot.
- * @param {DocumentData} options.db - The Firestore database instance to perform the operation on.
- * @param {string} options.reference - A string representing a direct Firestore document reference.
- * @param {string} options.path - A Firestore path string leading to the document.
- * @param {string[]} options.pathSegments - An array of path segments to build the Firestore path.
- * @returns {Promise<DocumentData | null>} A promise that resolves to the document data if the
- *                                         document exists, or `null` if the document does not exist
- *                                         or if the reference could not be obtained.
+ * @group Utility
+ *
+ * @param {GetDocSnapOptions<AppModelType>} options - The options for retrieving the document snapshot
+ *
+ * @returns {Promise<DocumentSnapshot<AppModelType, AppModelType> | null>} Returns a document reference
  */
-export const getDocSnap = async <
-    AppModelType extends DocumentData = DocumentData,
-    DbModelType extends DocumentData = DocumentData
->({
+export const getDocSnap = async <AppModelType extends AppModel = AppModel>({
     db,
     reference,
     path,
     pathSegments
-}: GetDocSnapOptions<AppModelType, DbModelType>) => {
-    const docRef = await getDocRef<AppModelType, DbModelType>({ db, reference, path, pathSegments });
+}: GetDocSnapOptions<AppModelType>) => {
+    const docRef = await getDocRef<AppModelType>({ db, reference, path, pathSegments });
 
     if (docRef) {
         return await firestoreGetDoc(docRef);