DO NOT MERGE: Firestore COUNT API proposal

common/api-review/firestore.api.md

@@ -17,6 +17,30 @@ export type AddPrefixToKeys<Prefix extends string, T extends Record<string, unkn
     [K in keyof T & string as `${Prefix}.${K}`]+?: T[K];
 };
 
+// @public (undocumented)
+export class AggregateQuery {
+    // (undocumented)
+    readonly query: Query<unknown>;
+    // (undocumented)
+    readonly type = "AggregateQuery";
+}
+
+// @public (undocumented)
+export function aggregateQueryEqual(left: AggregateQuery, right: AggregateQuery): boolean;
+
+// @public (undocumented)
+export class AggregateQuerySnapshot {
+    // (undocumented)
+    getCount(): number | null;
+    // (undocumented)
+    readonly query: AggregateQuery;
+    // (undocumented)
+    readonly type = "AggregateQuerySnapshot";
+}
+
+// @public (undocumented)
+export function aggregateQuerySnapshotEqual(left: AggregateQuerySnapshot, right: AggregateQuerySnapshot): boolean;
+
 // @public
 export function arrayRemove(...elements: unknown[]): FieldValue;
 
@@ -69,6 +93,9 @@ export function connectFirestoreEmulator(firestore: Firestore, host: string, por
     mockUserToken?: EmulatorMockTokenOptions | string;
 }): void;
 
+// @public (undocumented)
+export function countQuery(query: Query<unknown>): AggregateQuery;
+
 // @public
 export function deleteDoc(reference: DocumentReference<unknown>): Promise<void>;
 
@@ -209,6 +236,9 @@ export class GeoPoint {
     };
 }
 
+// @public (undocumented)
+export function getAggregateFromServerDirect(query: AggregateQuery): Promise<AggregateQuerySnapshot>;
+
 // @public
 export function getDoc<T>(reference: DocumentReference<T>): Promise<DocumentSnapshot<T>>;
 

packages/firestore/src/api.ts

@@ -119,6 +119,15 @@ export {
   deleteField
 } from './api/field_value_impl';
 
+export {
+  AggregateQuery,
+  AggregateQuerySnapshot,
+  aggregateQueryEqual,
+  aggregateQuerySnapshotEqual,
+  countQuery,
+  getAggregateFromServerDirect
+} from './api/aggregate';
+
 export { setLogLevel, LogLevelString as LogLevel } from './util/log';
 
 export { Bytes } from './api/bytes';

packages/firestore/src/api/aggregate.ts

@@ -0,0 +1,25 @@
+/**
+ * @license
+ * Copyright 2022 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+export {
+  AggregateQuery,
+  AggregateQuerySnapshot,
+  aggregateQueryEqual,
+  aggregateQuerySnapshotEqual,
+  countQuery,
+  getAggregateFromServerDirect
+} from '../lite-api/aggregate';

packages/firestore/src/lite-api/aggregate.ts

@@ -0,0 +1,62 @@
+/**
+ * @license
+ * Copyright 2022 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import {Query, queryEqual} from './reference';
+
+export class AggregateQuery {
+
+  /** @hideconstructor */
+  constructor(query: Query<unknown>) {
+    this.query = query;
+  }
+
+  readonly type = "AggregateQuery";
+
+  readonly query: Query<unknown>;
+}
+
+export class AggregateQuerySnapshot {
+
+  /** @hideconstructor */
+  constructor(query: AggregateQuery, readonly _count: number) {
+    this.query = query;
+  }
+
+  readonly type = "AggregateQuerySnapshot";
+
+  readonly query: AggregateQuery;
+
+  getCount(): number | null {
+    return this._count;
+  }
+}
+
+export function countQuery(query: Query<unknown>): AggregateQuery {
+  return new AggregateQuery(query);
+}
+
+export function getAggregateFromServerDirect(query: AggregateQuery): Promise<AggregateQuerySnapshot> {
+  return Promise.resolve(new AggregateQuerySnapshot(query, 42));
+}
+
+export function aggregateQueryEqual(left: AggregateQuery, right: AggregateQuery): boolean {
+  return queryEqual(left.query, right.query);
+}
+
+export function aggregateQuerySnapshotEqual(left: AggregateQuerySnapshot, right: AggregateQuerySnapshot): boolean {
+  return aggregateQueryEqual(left.query, right.query) && left.getCount() === right.getCount();
+}

packages/firestore/test/integration/api/aggregate.demo.ts

@@ -0,0 +1,69 @@
+/**
+ * @license
+ * Copyright 2022 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { expect } from 'chai';
+
+import {
+  AggregateQuery,
+  AggregateQuerySnapshot,
+  CollectionReference,
+  DocumentReference,
+  Firestore,
+  aggregateQueryEqual,
+  aggregateQuerySnapshotEqual,
+  collection,
+  countQuery,
+  disableNetwork,
+  doc,
+  enableNetwork,
+  getAggregateFromServerDirect,
+  query,
+  setDoc,
+  getDocs,
+  waitForPendingWrites,
+  limit,
+  where
+} from '../util/firebase_export';
+
+import {Deferred} from '../../util/promise';
+
+async function Demo0_NormalQuery(db: Firestore) {
+  const query_ = collection(db, "games/halo/players");
+  const snapshot = await getDocs(query_);
+  expect(snapshot.size).to.equal(5000000);
+}
+
+async function Demo1_CountOfDocumentsInACollection(db: Firestore) {
+  const countQuery_ = countQuery(collection(db, "games/halo/players"));
+  const snapshot = await getAggregateFromServerDirect(countQuery_);
+  expect(snapshot.getCount()).to.equal(5000000);
+}
+
+async function Demo2_CountOfDocumentsInACollectionWithFilter(db: Firestore) {
+  const query_ = query(collection(db, "games/halo/players"), where("online", "==", true));
+  const countQuery_ = countQuery(query_);
+  const snapshot = await getAggregateFromServerDirect(countQuery_);
+  expect(snapshot.getCount()).to.equal(2000);
+}
+
+async function Demo2_CountOfDocumentsInACollectionWithLimit(db: Firestore) {
+  const query_ = query(collection(db, "games/halo/players"), limit(9000));
+  const countQuery_ = countQuery(query_);
+  const snapshot = await getAggregateFromServerDirect(countQuery_);
+  expect(snapshot.getCount()).to.equal(9000);
+}
+