Make Parameters for Firestore Hooks Positional (#73)

* convert parameters to positional for useDocument hook * add and impl UseDocumentOptions.listenToMetadataChanges * fix useDocument declaration * convert parameters into positional for useCollection hook * add UseCollectionOptions.listenToMetadataChanges * convert into positional parameters for useAddDocument hook * convert parameters into positional for useDeleteDocument * convert parameters into positional for useSetDocument hook
erayerdin · Feb 10, 2024 · 4d5e507 · 4d5e507
1 parent d17e041
commit 4d5e507
Show file tree

Hide file tree

Showing 13 changed files with 74 additions and 104 deletions.
diff --git a/docs/hooks/useCollection.md b/docs/hooks/useCollection.md
@@ -33,15 +33,13 @@ Input parameters for `useCollection` hook is as follows:
 | Name | Type | Description | Required | Default Value |
 |---|---|---|---|---|
 | `reference` | [`firebase/firestore/CollectionRefference`][CollectionReferenceRefDoc] or [`firebase/firestore/Query`][QueryRefDoc] | Reference to a collection in Firestore or a query. | ✅ | - |
-| `options` | Object | Options for the hook. | ❌ | `{ listen: false }` |
+| `options` | Object | Options for the hook. | ❌ | See below. |
 | `options.listen` | `boolean` | Whether to listen to realtime changes of the document or not. | ❌ | `false` |
+| `options.listenToMetadataChanges` | `boolean` | Whether to listen to realtime changes of the document or not as well as its metadata. See [this][EventsForMetadataChangesDoc]. | ❌ | `false` |
 
 !!! note
     `options.listen` is `false` by default to prevent unnecessary READ queries from Firestore.
 
-!!! warning
-    When `options.listen` is `true`, the change is reflected including the metadata changes on the document. See [this page](https://firebase.google.com/docs/firestore/query-data/listen#events-metadata-changes) to understand `includeMetadataChanges` option in Firestore.
-
 ## Return Type
 
 `useCollection` hook returns an object with properties as below:
@@ -58,4 +56,5 @@ Input parameters for `useCollection` hook is as follows:
 [CollectionReferenceRefDoc]: https://firebase.google.com/docs/reference/node/firebase.firestore.CollectionReference
 [QueryRefDoc]: https://firebase.google.com/docs/reference/node/firebase.database.Query
 [QuerySnapshotRefDoc]: https://firebase.google.com/docs/reference/node/firebase.firestore.QuerySnapshot
-[FirebaseErrorRefDoc]: https://firebase.google.com/docs/reference/node/firebase.FirebaseError
+[FirebaseErrorRefDoc]: https://firebase.google.com/docs/reference/node/firebase.FirebaseError
+[EventsForMetadataChangesDoc]: https://firebase.google.com/docs/firestore/query-data/listen#events-metadata-changes
diff --git a/docs/hooks/useDocument.md b/docs/hooks/useDocument.md
@@ -25,15 +25,13 @@ Input parameters for `useDocument` hook is as follows:
 | Name | Type | Description | Required | Default Value |
 |---|---|---|---|---|
 | `reference` | [`firebase/firestore/DocumentReference`][DocumentReferenceRefDoc] | Reference to a document in Firestore. | ✅ | - |
-| `options` | Object | Options for the hook. | ❌ | `{ listen: false }` |
+| `options` | Object | Options for the hook. | ❌ | See the following parameters. |
 | `options.listen` | `boolean` | Whether to listen to realtime changes of the document or not. | ❌ | `false` |
+| `options.listenToMetadataChanges` | `boolean` | Whether to listen to realtime changes of the document as well its metadata. See [here][EventsForMetadataChangesDoc] | ❌ | `false` |
 
 !!! note
     `options.listen` is `false` by default to prevent unnecessary READ queries from Firestore.
 
-!!! warning
-    When `options.listen` is `true`, the change is reflected including the metadata changes on the document. See [this page](https://firebase.google.com/docs/firestore/query-data/listen#events-metadata-changes) to understand `includeMetadataChanges` option in Firestore.
-
 ## Return Type
 
 `useDocument` hook returns an object with properties as below:
@@ -49,4 +47,5 @@ Input parameters for `useDocument` hook is as follows:
 
 [DocumentReferenceRefDoc]: https://firebase.google.com/docs/reference/node/firebase.firestore.DocumentReference
 [DocumentSnapshotRefDoc]: https://firebase.google.com/docs/reference/node/firebase.firestore.DocumentSnapshot
-[FirebaseErrorRefDoc]: https://firebase.google.com/docs/reference/node/firebase.FirebaseError
+[FirebaseErrorRefDoc]: https://firebase.google.com/docs/reference/node/firebase.FirebaseError
+[EventsForMetadataChangesDoc]: https://firebase.google.com/docs/firestore/query-data/listen#events-metadata-changes
diff --git a/src/firestore/FirestoreDocument.tsx b/src/firestore/FirestoreDocument.tsx
@@ -28,7 +28,7 @@ export const FirestoreDocument = ({
     loading: processing,
     snapshot,
     error: err,
-  } = useDocument({ reference, options: { listen } });
+  } = useDocument(reference, { listen });
 
   return processing ? onLoading() : err ? onError(err) : onDone(snapshot!);
 };
diff --git a/src/firestore/useAddDocument.test.ts b/src/firestore/useAddDocument.test.ts
@@ -19,7 +19,7 @@ describe("initially useAddDocument hook", () => {
     await deleteDoc(docRef);
 
     // test
-    const { result } = renderHook(() => useAddDocument({ reference: colRef }));
+    const { result } = renderHook(() => useAddDocument(colRef));
     const { state } = result.current;
     expect(state).toBe("ready");
 
@@ -32,7 +32,7 @@ describe("initially useAddDocument hook", () => {
     await deleteDoc(docRef);
 
     // test
-    const { result } = renderHook(() => useAddDocument({ reference: colRef }));
+    const { result } = renderHook(() => useAddDocument(colRef));
     const { reference } = result.current;
     expect(reference).toBeUndefined();
 
@@ -45,7 +45,7 @@ describe("initially useAddDocument hook", () => {
     await deleteDoc(docRef);
 
     // test
-    const { result } = renderHook(() => useAddDocument({ reference: colRef }));
+    const { result } = renderHook(() => useAddDocument(colRef));
     const { error } = result.current;
     expect(error).toBeUndefined();
 
@@ -61,7 +61,7 @@ describe("as soon as dispatched, useAddDocument hook", () => {
     await deleteDoc(docRef);
 
     // test
-    const { result } = renderHook(() => useAddDocument({ reference: colRef }));
+    const { result } = renderHook(() => useAddDocument(colRef));
     const { dispatch } = result.current;
     dispatch(docData);
     await sleep(30);
@@ -80,7 +80,7 @@ describe("after dispatched, useAddDocument hook", () => {
     await deleteDoc(docRef);
 
     // test
-    const { result } = renderHook(() => useAddDocument({ reference: colRef }));
+    const { result } = renderHook(() => useAddDocument(colRef));
     const { dispatch } = result.current;
     await dispatch(docData);
     await sleep(250);
@@ -97,7 +97,7 @@ describe("after dispatched, useAddDocument hook", () => {
     await deleteDoc(docRef);
 
     // test
-    const { result } = renderHook(() => useAddDocument({ reference: colRef }));
+    const { result } = renderHook(() => useAddDocument(colRef));
     const { dispatch } = result.current;
     await dispatch(docData);
     await sleep(250);
@@ -114,7 +114,7 @@ describe("after dispatched, useAddDocument hook", () => {
     await deleteDoc(docRef);
 
     // test
-    const { result } = renderHook(() => useAddDocument({ reference: colRef }));
+    const { result } = renderHook(() => useAddDocument(colRef));
     const { dispatch } = result.current;
     await dispatch(docData);
     await sleep(250);

diff --git a/src/firestore/useAddDocument.ts b/src/firestore/useAddDocument.ts
@@ -12,10 +12,6 @@ import {
 } from "firebase/firestore";
 import { useState } from "react";
 
-type UseAddDocumentParams = {
-  reference: CollectionReference;
-};
-
 type UseAddDocumentState = "ready" | "loading" | "done";
 type UseAddDocumentDispatcher = (
   data: DocumentData,
@@ -28,9 +24,9 @@ type UseAddDocument = {
   error?: FirebaseError;
 };
 
-export const useAddDocument = ({
-  reference,
-}: UseAddDocumentParams): UseAddDocument => {
+export const useAddDocument = (
+  reference: CollectionReference,
+): UseAddDocument => {
   const [state, setState] = useState<UseAddDocumentState>("ready");
   const [refer, setRefer] = useState<DocumentReference | undefined>();
   const [error, setError] = useState<FirebaseError | undefined>();

diff --git a/src/firestore/useCollection.test.ts b/src/firestore/useCollection.test.ts
@@ -20,7 +20,7 @@ describe("initially useCollection hook", () => {
     await setDoc(docRef, docData);
 
     // test
-    const { result } = renderHook(() => useCollection({ query: colRef }));
+    const { result } = renderHook(() => useCollection(colRef));
     const { loading } = result.current;
     expect(loading).toBe(true);
 
@@ -34,7 +34,7 @@ describe("initially useCollection hook", () => {
     await setDoc(docRef, docData);
 
     // test
-    const { result } = renderHook(() => useCollection({ query: colRef }));
+    const { result } = renderHook(() => useCollection(colRef));
     const { snapshot } = result.current;
     expect(snapshot).toBeUndefined();
 
@@ -48,7 +48,7 @@ describe("initially useCollection hook", () => {
     await setDoc(docRef, docData);
 
     // test
-    const { result } = renderHook(() => useCollection({ query: colRef }));
+    const { result } = renderHook(() => useCollection(colRef));
     const { error } = result.current;
     expect(error).toBeUndefined();
 
@@ -64,7 +64,7 @@ describe("later useCollection hook", () => {
     await setDoc(docRef, docData);
 
     // test
-    const { result } = renderHook(() => useCollection({ query: colRef }));
+    const { result } = renderHook(() => useCollection(colRef));
     await sleep(250);
     const { loading } = result.current;
     expect(loading).toBe(false);
@@ -79,7 +79,7 @@ describe("later useCollection hook", () => {
     await setDoc(docRef, docData);
 
     // test
-    const { result } = renderHook(() => useCollection({ query: colRef }));
+    const { result } = renderHook(() => useCollection(colRef));
     await sleep(250);
     const { snapshot } = result.current;
     expect(snapshot?.size).toBeGreaterThan(0);
@@ -94,7 +94,7 @@ describe("later useCollection hook", () => {
     await setDoc(docRef, docData);
 
     // test
-    const { result } = renderHook(() => useCollection({ query: colRef }));
+    const { result } = renderHook(() => useCollection(colRef));
     await sleep(250);
     const { error } = result.current;
     expect(error).toBeUndefined();

diff --git a/src/firestore/useCollection.ts b/src/firestore/useCollection.ts
@@ -7,11 +7,9 @@ import { FirebaseError } from "firebase/app";
 import { Query, QuerySnapshot, getDocs, onSnapshot } from "firebase/firestore";
 import { useEffect, useState } from "react";
 
-type UseCollectionParams = {
-  query: Query;
-  options?: {
-    listen: boolean;
-  };
+type UseCollectionOptions = {
+  listen?: boolean;
+  listenToMetadataChanges?: boolean;
 };
 
 type UseCollection = {
@@ -20,12 +18,13 @@ type UseCollection = {
   error?: FirebaseError;
 };
 
-export const useCollection = ({
-  query,
-  options = { listen: false },
-}: UseCollectionParams): UseCollection => {
-  const { listen } = options;
-
+export const useCollection = (
+  query: Query,
+  { listen, listenToMetadataChanges }: UseCollectionOptions = {
+    listen: false,
+    listenToMetadataChanges: false,
+  },
+): UseCollection => {
   const [loading, setLoading] = useState<boolean>(true);
   const [snapshot, setSnapshot] = useState<QuerySnapshot | undefined>();
   const [error, setError] = useState<FirebaseError | undefined>();
@@ -36,7 +35,7 @@ export const useCollection = ({
     if (listen) {
       const unsub = onSnapshot(
         query,
-        { includeMetadataChanges: true },
+        { includeMetadataChanges: listenToMetadataChanges },
         (snap) => {
           setSnapshot(snap);
           setLoading(false);
@@ -62,7 +61,7 @@ export const useCollection = ({
         })
         .finally(() => setLoading(false));
     }
-  }, [listen, query]);
+  }, [query, listen, listenToMetadataChanges]);
 
   return { loading, snapshot, error };
 };
diff --git a/src/firestore/useDeleteDocument.test.ts b/src/firestore/useDeleteDocument.test.ts
@@ -17,9 +17,7 @@ describe("initially useDeleteDocument hook", () => {
     await deleteDoc(docRef);
 
     // test
-    const { result } = renderHook(() =>
-      useDeleteDocument({ reference: docRef }),
-    );
+    const { result } = renderHook(() => useDeleteDocument(docRef));
     const { state } = result.current;
     expect(state).toBe("ready");
 
@@ -32,9 +30,7 @@ describe("initially useDeleteDocument hook", () => {
     await deleteDoc(docRef);
 
     // test
-    const { result } = renderHook(() =>
-      useDeleteDocument({ reference: docRef }),
-    );
+    const { result } = renderHook(() => useDeleteDocument(docRef));
     const { error } = result.current;
     expect(error).toBeUndefined();
 
@@ -50,9 +46,7 @@ describe("as soon as dispatched, useDeleteDocument hook", () => {
     await deleteDoc(docRef);
 
     // test
-    const { result } = renderHook(() =>
-      useDeleteDocument({ reference: docRef }),
-    );
+    const { result } = renderHook(() => useDeleteDocument(docRef));
     const { dispatch } = result.current;
     dispatch();
     await sleep(30);
@@ -71,9 +65,7 @@ describe("after dispatched, useDeleteDocument hook", () => {
     await deleteDoc(docRef);
 
     // test
-    const { result } = renderHook(() =>
-      useDeleteDocument({ reference: docRef }),
-    );
+    const { result } = renderHook(() => useDeleteDocument(docRef));
     const { dispatch } = result.current;
     await dispatch();
     await sleep(250);
@@ -90,9 +82,7 @@ describe("after dispatched, useDeleteDocument hook", () => {
     await setDoc(docRef, { displayName: "Use Delete Document" });
 
     // test
-    const { result } = renderHook(() =>
-      useDeleteDocument({ reference: docRef }),
-    );
+    const { result } = renderHook(() => useDeleteDocument(docRef));
     const { dispatch } = result.current;
     await dispatch();
     await sleep(250);

diff --git a/src/firestore/useDeleteDocument.ts b/src/firestore/useDeleteDocument.ts
@@ -7,10 +7,6 @@ import { FirebaseError } from "firebase/app";
 import { DocumentReference, deleteDoc } from "firebase/firestore";
 import { useState } from "react";
 
-type UseSetDocumentParams = {
-  reference: DocumentReference;
-};
-
 type UseSetDocumentState = "ready" | "loading" | "done";
 type UseSetDocumentDispatcher = () => Promise<void>;
 
@@ -20,9 +16,9 @@ type UseSetDocument = {
   error?: FirebaseError;
 };
 
-export const useDeleteDocument = ({
-  reference,
-}: UseSetDocumentParams): UseSetDocument => {
+export const useDeleteDocument = (
+  reference: DocumentReference,
+): UseSetDocument => {
   const [state, setState] = useState<UseSetDocumentState>("ready");
   const [error, setError] = useState<FirebaseError | undefined>();