feat(firestore): add useCountFromServer (#147)

README.md

@@ -54,6 +54,7 @@ This library consists of 4 modules with many hooks:
     -   [`useCollectionData`](#useCollectionData)
     -   [`useCollectionDataOnce`](#useCollectionDataOnce)
     -   [`useCollectionOnce`](#useCollectionOnce)
+    -   [`useCountFromServer`](#useCountFromServer)
     -   [`useDocument`](#useDocument)
     -   [`useDocumentData`](#useDocumentData)
     -   [`useDocumentDataOnce`](#useDocumentataOnce)
@@ -317,6 +318,26 @@ Returns:
 -   `loading`: `true` while fetching the query; `false` if the query was fetched successfully or an error occurred
 -   `error`: `undefined` if no error occurred
 
+#### useCountFromServer
+
+Returns the number of documents in the result set of of a Firestore Query. Does not update the count once initially calculated.
+
+Requires firebase 9.11.0 or later.
+
+```javascript
+const [count, loading, error] = useCountFromServer(query);
+```
+
+Params:
+
+-   `query`: Firestore query whose result set size is calculated
+
+Returns:
+
+-   `value`: Size of the result set; `undefined` if the result set size is currently being calculated, or an error occurred
+-   `loading`: `true` while calculating the result size set; `false` if the result size set was calculated successfully or an error occurred
+-   `error`: `undefined` if no error occurred
+
 #### useDocument
 
 Returns and updates a DocumentSnapshot of a Firestore DocumentReference

src/firestore/index.ts

@@ -3,6 +3,7 @@ export * from "./useCollection.js";
 export * from "./useCollectionData.js";
 export * from "./useCollectionDataOnce.js";
 export * from "./useCollectionOnce.js";
+export * from "./useCountFromServer.js";
 export * from "./useDocument.js";
 export * from "./useDocumentData.js";
 export * from "./useDocumentDataOnce.js";

src/firestore/useCountFromServer.ts

@@ -0,0 +1,31 @@
+import type { FirestoreError, Query } from "firebase/firestore";
+import type { ValueHookResult } from "../common/types.js";
+import { useOnce } from "../internal/useOnce.js";
+import { isQueryEqual } from "./internal.js";
+
+export type UseCountFromServerResult = ValueHookResult<number, FirestoreError>;
+
+async function getData(stableQuery: Query<unknown>) {
+    const firestoreModule = await import("firebase/firestore");
+
+    // @ts-expect-error `getCountFromServer` is only available from 9.11.0
+    const { getCountFromServer } = firestoreModule;
+
+    const snap = await getCountFromServer(stableQuery);
+    return snap.data().count;
+}
+
+/**
+ * Returns the number of documents in the result set of of a Firestore Query. Does not update the count once initially calculated.
+ *
+ * Requires firebase 9.11.0 or later
+ *
+ * @param {Query<unknown> | undefined | null} query Firestore query whose result set size is calculated
+ * @returns {UseCountFromServerResult} Size of the result set, loading state, and error
+ * * value: Size of the result set; `undefined` if the result set size is currently being calculated, or an error occurred
+ * * loading: `true` while calculating the result size set; `false` if the result size set was calculated successfully or an error occurred
+ * * error: `undefined` if no error occurred
+ */
+export function useCountFromServer(query: Query<unknown> | undefined | null): UseCountFromServerResult {
+    return useOnce(query ?? undefined, getData, isQueryEqual);
+}