andipaetzold · andipaetzold · Mar 14, 2024 · Mar 14, 2024
diff --git a/src/firestore/internal.ts b/src/firestore/internal.ts
@@ -14,9 +14,22 @@ import {
     queryEqual,
     QuerySnapshot,
     refEqual,
+    SnapshotListenOptions,
 } from "firebase/firestore";
 import type { Source } from "./types.js";
 
+/**
+ * @since 10.9.0
+ */
+export type ListenSource = "default" | "cache";
+
+/**
+ * This library currently supports [email protected] which is missing the `source` property in `SnapshotListenOptions`.
+ */
+export type SnapshotListenOptionsInternal = SnapshotListenOptions & {
+    readonly source?: "default" | "cache";
+};
+
 /**
  * @internal
  */

diff --git a/src/firestore/useDocument.spec.ts b/src/firestore/useDocument.spec.ts
@@ -0,0 +1,44 @@
+import { renderHook } from "@testing-library/react";
+import { expect, it, vi, describe, beforeEach } from "vitest";
+import { useDocument } from "./useDocument";
+import { newSymbol } from "../__testfixtures__";
+import { DocumentReference, onSnapshot } from "firebase/firestore";
+
+vi.mock("firebase/firestore", async () => ({
+    ...(await vi.importActual("firebase/firestore")),
+    onSnapshot: vi.fn().mockReturnValue(vi.fn()),
+}));
+
+beforeEach(() => {
+    vi.clearAllMocks();
+});
+
+const ref1 = newSymbol<DocumentReference>("Ref");
+
+describe("when re-rendered", () => {
+    it("with equal, but non-identical options object", () => {
+        const options1 = { snapshotListenOptions: { includeMetadataChanges: false } };
+        const options2 = { snapshotListenOptions: { includeMetadataChanges: false } };
+
+        const { rerender } = renderHook(({ options }) => useDocument(ref1, options), {
+            initialProps: { options: options1 },
+        });
+
+        expect(onSnapshot).toHaveBeenCalledTimes(1);
+        rerender({ options: options2 });
+        expect(onSnapshot).toHaveBeenCalledTimes(1);
+    });
+
+    it("with different options object", () => {
+        const options1 = { snapshotListenOptions: { includeMetadataChanges: false } };
+        const options2 = { snapshotListenOptions: { includeMetadataChanges: true } };
+
+        const { rerender } = renderHook(({ options }) => useDocument(ref1, options), {
+            initialProps: { options: options1 },
+        });
+
+        expect(onSnapshot).toHaveBeenCalledTimes(1);
+        rerender({ options: options2 });
+        expect(onSnapshot).toHaveBeenCalledTimes(2);
+    });
+});
diff --git a/src/firestore/useDocument.ts b/src/firestore/useDocument.ts
@@ -10,7 +10,7 @@ import { useCallback } from "react";
 import type { ValueHookResult } from "../common/types.js";
 import { useListen, UseListenOnChange } from "../internal/useListen.js";
 import { LoadingState } from "../internal/useLoadingValue.js";
-import { isDocRefEqual } from "./internal.js";
+import { isDocRefEqual, SnapshotListenOptionsInternal } from "./internal.js";
 
 export type UseDocumentResult<AppModelType = DocumentData> = ValueHookResult<DocumentSnapshot<AppModelType>, FirestoreError>;
 
@@ -37,7 +37,8 @@ export function useDocument<AppModelType = DocumentData, DbModelType extends Doc
     options?: UseDocumentOptions | undefined,
 ): UseDocumentResult<AppModelType> {
     const { snapshotListenOptions } = options ?? {};
-    const { includeMetadataChanges = false } = snapshotListenOptions ?? {};
+    const { includeMetadataChanges = false, source = "default" } = (snapshotListenOptions ??
+        {}) as SnapshotListenOptionsInternal;
 
     const onChange: UseListenOnChange<
         DocumentSnapshot<AppModelType, DbModelType>,
@@ -47,13 +48,16 @@ export function useDocument<AppModelType = DocumentData, DbModelType extends Doc
         (stableRef, next, error) =>
             onSnapshot(
                 stableRef,
-                { includeMetadataChanges },
+                {
+                    includeMetadataChanges,
+                    source,
+                } as SnapshotListenOptions,
                 {
                     next,
                     error,
                 },
             ),
-        [includeMetadataChanges],
+        [includeMetadataChanges, source],
     );
 
     return useListen(reference ?? undefined, onChange, isDocRefEqual, LoadingState);

diff --git a/src/firestore/useDocumentData.ts b/src/firestore/useDocumentData.ts
@@ -10,7 +10,7 @@ import { useCallback } from "react";
 import type { ValueHookResult } from "../common/types.js";
 import { useListen, UseListenOnChange } from "../internal/useListen.js";
 import { LoadingState } from "../internal/useLoadingValue.js";
-import { isDocRefEqual } from "./internal.js";
+import { isDocRefEqual, SnapshotListenOptionsInternal } from "./internal.js";
 
 export type UseDocumentDataResult<AppModelType = DocumentData> = ValueHookResult<AppModelType, FirestoreError>;
 
@@ -40,7 +40,8 @@ export function useDocumentData<AppModelType = DocumentData, DbModelType extends
     options?: UseDocumentDataOptions<AppModelType> | undefined,
 ): UseDocumentDataResult<AppModelType> {
     const { snapshotListenOptions, snapshotOptions } = options ?? {};
-    const { includeMetadataChanges = false } = snapshotListenOptions ?? {};
+    const { includeMetadataChanges = false, source = "default" } = (snapshotListenOptions ??
+        {}) as SnapshotListenOptionsInternal;
     const { serverTimestamps = "none" } = snapshotOptions ?? {};
 
     const onChange: UseListenOnChange<
@@ -51,13 +52,16 @@ export function useDocumentData<AppModelType = DocumentData, DbModelType extends
         (stableRef, next, error) =>
             onSnapshot(
                 stableRef,
-                { includeMetadataChanges },
+                {
+                    includeMetadataChanges,
+                    source,
+                } as SnapshotListenOptions,
                 {
                     next: (snap) => next(snap.data({ serverTimestamps })),
                     error,
                 },
             ),
-        [includeMetadataChanges, serverTimestamps],
+        [includeMetadataChanges, serverTimestamps, source],
     );
 
     return useListen(reference ?? undefined, onChange, isDocRefEqual, options?.initialValue ?? LoadingState);

diff --git a/src/firestore/useQueries.ts b/src/firestore/useQueries.ts
@@ -2,7 +2,7 @@ import { DocumentData, FirestoreError, onSnapshot, Query, QuerySnapshot, Snapsho
 import { useCallback } from "react";
 import { ValueHookResult } from "../common/types.js";
 import { useMultiListen, UseMultiListenChange } from "../internal/useMultiListen.js";
-import { isQueryEqual } from "./internal.js";
+import { isQueryEqual, SnapshotListenOptionsInternal } from "./internal.js";
 
 export type UseQueriesResult<AppModelTypes extends ReadonlyArray<unknown> = ReadonlyArray<DocumentData>> = {
     [Index in keyof AppModelTypes]: ValueHookResult<QuerySnapshot<AppModelTypes[Index]>, FirestoreError>;
@@ -34,7 +34,8 @@ export function useQueries<
     options?: UseQueriesOptions | undefined,
 ): UseQueriesResult<AppModelTypes> {
     const { snapshotListenOptions } = options ?? {};
-    const { includeMetadataChanges = false } = snapshotListenOptions ?? {};
+    const { includeMetadataChanges = false, source = "default" } = (snapshotListenOptions ??
+        {}) as SnapshotListenOptionsInternal;
 
     const onChange: UseMultiListenChange<
         QuerySnapshot<AppModelTypes[number], DbModelTypes[number]>,
@@ -44,13 +45,16 @@ export function useQueries<
         (query, next, error) =>
             onSnapshot(
                 query,
-                { includeMetadataChanges },
+                {
+                    includeMetadataChanges,
+                    source,
+                } as SnapshotListenOptions,
                 {
                     next,
                     error,
                 },
             ),
-        [includeMetadataChanges],
+        [includeMetadataChanges, source],
     );
 
     // @ts-expect-error `useMultiListen` assumes a single value type

diff --git a/src/firestore/useQueriesData.ts b/src/firestore/useQueriesData.ts
@@ -2,7 +2,7 @@ import { DocumentData, FirestoreError, onSnapshot, Query, SnapshotListenOptions,
 import { useCallback } from "react";
 import { ValueHookResult } from "../common/types.js";
 import { useMultiListen, UseMultiListenChange } from "../internal/useMultiListen.js";
-import { isQueryEqual } from "./internal.js";
+import { isQueryEqual, SnapshotListenOptionsInternal } from "./internal.js";
 
 export type UseQueriesDataResult<AppModelTypes extends ReadonlyArray<unknown> = ReadonlyArray<DocumentData>> = {
     [Index in keyof AppModelTypes]: ValueHookResult<AppModelTypes[Index], FirestoreError>;
@@ -35,7 +35,8 @@ export function useQueriesData<
     options?: UseQueriesDataOptions | undefined,
 ): UseQueriesDataResult<AppModelTypes> {
     const { snapshotListenOptions, snapshotOptions } = options ?? {};
-    const { includeMetadataChanges = false } = snapshotListenOptions ?? {};
+    const { includeMetadataChanges = false, source = "default" } = (snapshotListenOptions ??
+        {}) as SnapshotListenOptionsInternal;
     const { serverTimestamps = "none" } = snapshotOptions ?? {};
 
     const onChange: UseMultiListenChange<
@@ -46,13 +47,16 @@ export function useQueriesData<
         (query, next, error) =>
             onSnapshot(
                 query,
-                { includeMetadataChanges },
+                {
+                    includeMetadataChanges,
+                    source,
+                } as SnapshotListenOptions,
                 {
                     next: (snap) => next(snap.docs.map((doc) => doc.data({ serverTimestamps }))),
                     error,
                 },
             ),
-        [includeMetadataChanges, serverTimestamps],
+        [includeMetadataChanges, serverTimestamps, source],
     );
 
     // @ts-expect-error `useMultiListen` assumes a single value type

diff --git a/src/firestore/useQuery.ts b/src/firestore/useQuery.ts
@@ -3,7 +3,7 @@ import { useCallback } from "react";
 import { ValueHookResult } from "../common/types.js";
 import { useListen, UseListenOnChange } from "../internal/useListen.js";
 import { LoadingState } from "../internal/useLoadingValue.js";
-import { isQueryEqual } from "./internal.js";
+import { isQueryEqual, SnapshotListenOptionsInternal } from "./internal.js";
 
 export type UseQueryResult<AppModelType = DocumentData> = ValueHookResult<QuerySnapshot<AppModelType>, FirestoreError>;
 
@@ -30,7 +30,8 @@ export function useQuery<AppModelType = DocumentData, DbModelType extends Docume
     options?: UseQueryOptions | undefined,
 ): UseQueryResult<AppModelType> {
     const { snapshotListenOptions } = options ?? {};
-    const { includeMetadataChanges = false } = snapshotListenOptions ?? {};
+    const { includeMetadataChanges = false, source = "default" } = (snapshotListenOptions ??
+        {}) as SnapshotListenOptionsInternal;
 
     const onChange: UseListenOnChange<
         QuerySnapshot<AppModelType, DbModelType>,
@@ -40,13 +41,16 @@ export function useQuery<AppModelType = DocumentData, DbModelType extends Docume
         (stableQuery, next, error) =>
             onSnapshot(
                 stableQuery,
-                { includeMetadataChanges },
+                {
+                    includeMetadataChanges,
+                    source,
+                } as SnapshotListenOptions,
                 {
                     next,
                     error,
                 },
             ),
-        [includeMetadataChanges],
+        [includeMetadataChanges, source],
     );
 
     return useListen(query ?? undefined, onChange, isQueryEqual, LoadingState);

diff --git a/src/firestore/useQueryData.ts b/src/firestore/useQueryData.ts
@@ -3,7 +3,7 @@ import { useCallback } from "react";
 import { ValueHookResult } from "../common/types.js";
 import { useListen, UseListenOnChange } from "../internal/useListen.js";
 import { LoadingState } from "../internal/useLoadingValue.js";
-import { isQueryEqual } from "./internal.js";
+import { isQueryEqual, SnapshotListenOptionsInternal } from "./internal.js";
 
 export type UseQueryDataResult<AppModelType = DocumentData> = ValueHookResult<AppModelType[], FirestoreError>;
 
@@ -33,20 +33,24 @@ export function useQueryData<AppModelType = DocumentData, DbModelType extends Do
     options?: UseQueryDataOptions<AppModelType> | undefined,
 ): UseQueryDataResult<AppModelType> {
     const { snapshotListenOptions, snapshotOptions } = options ?? {};
-    const { includeMetadataChanges = false } = snapshotListenOptions ?? {};
+    const { includeMetadataChanges = false, source = "default" } = (snapshotListenOptions ??
+        {}) as SnapshotListenOptionsInternal;
     const { serverTimestamps = "none" } = snapshotOptions ?? {};
 
     const onChange: UseListenOnChange<AppModelType[], FirestoreError, Query<AppModelType, DbModelType>> = useCallback(
         (stableQuery, next, error) =>
             onSnapshot(
                 stableQuery,
-                { includeMetadataChanges },
+                {
+                    includeMetadataChanges,
+                    source,
+                } as SnapshotListenOptions,
                 {
                     next: (snap) => next(snap.docs.map((doc) => doc.data({ serverTimestamps }))),
                     error,
                 },
             ),
-        [includeMetadataChanges, serverTimestamps],
+        [includeMetadataChanges, serverTimestamps, source],
     );
 
     return useListen(query ?? undefined, onChange, isQueryEqual, options?.initialValue ?? LoadingState);