Firestore: Re-write API docs for COUNT API (#6632)

dconeybe · web-flow · commit 88d026653c3f · 2022-09-27T14:13:42.000-07:00
diff --git a/common/api-review/firestore-lite.api.md b/common/api-review/firestore-lite.api.md
@@ -19,19 +19,16 @@ export type AddPrefixToKeys<Prefix extends string, T extends Record<string, unkn
 
 // @public
 export class AggregateField<T> {
-    // (undocumented)
     type: string;
 }
 
 // @public
-export type AggregateFieldType = ReturnType<typeof count>;
+export type AggregateFieldType = AggregateField<number>;
 
 // @public
 export class AggregateQuerySnapshot<T extends AggregateSpec> {
     data(): AggregateSpecData<T>;
-    // (undocumented)
     readonly query: Query<unknown>;
-    // (undocumented)
     readonly type = "AggregateQuerySnapshot";
 }
 
@@ -95,9 +92,6 @@ export function connectFirestoreEmulator(firestore: Firestore, host: string, por
     mockUserToken?: EmulatorMockTokenOptions | string;
 }): void;
 
-// @public
-export function count(): AggregateField<number>;
-
 // @public
 export function deleteDoc(reference: DocumentReference<unknown>): Promise<void>;
 
diff --git a/common/api-review/firestore.api.md b/common/api-review/firestore.api.md
@@ -19,19 +19,16 @@ export type AddPrefixToKeys<Prefix extends string, T extends Record<string, unkn
 
 // @public
 export class AggregateField<T> {
-    // (undocumented)
     type: string;
 }
 
 // @public
-export type AggregateFieldType = ReturnType<typeof count>;
+export type AggregateFieldType = AggregateField<number>;
 
 // @public
 export class AggregateQuerySnapshot<T extends AggregateSpec> {
     data(): AggregateSpecData<T>;
-    // (undocumented)
     readonly query: Query<unknown>;
-    // (undocumented)
     readonly type = "AggregateQuerySnapshot";
 }
 
@@ -101,9 +98,6 @@ export function connectFirestoreEmulator(firestore: Firestore, host: string, por
     mockUserToken?: EmulatorMockTokenOptions | string;
 }): void;
 
-// @public
-export function count(): AggregateField<number>;
-
 // @public
 export function deleteDoc(reference: DocumentReference<unknown>): Promise<void>;
 
diff --git a/packages/firestore/lite/index.ts b/packages/firestore/lite/index.ts
@@ -37,8 +37,7 @@ export {
   AggregateFieldType,
   AggregateSpec,
   AggregateSpecData,
-  AggregateQuerySnapshot,
-  count
+  AggregateQuerySnapshot
 } from '../src/lite-api/aggregate_types';
 
 export { FirestoreSettings as Settings } from '../src/lite-api/settings';
diff --git a/packages/firestore/src/api.ts b/packages/firestore/src/api.ts
@@ -25,8 +25,7 @@ export {
   AggregateFieldType,
   AggregateSpec,
   AggregateSpecData,
-  AggregateQuerySnapshot,
-  count
+  AggregateQuerySnapshot
 } from './lite-api/aggregate_types';
 
 export { FieldPath, documentId } from './api/field_path';
diff --git a/packages/firestore/src/api/aggregate.ts b/packages/firestore/src/api/aggregate.ts
@@ -29,12 +29,25 @@ import { ExpUserDataWriter } from './reference_impl';
 export { aggregateQuerySnapshotEqual } from '../lite-api/aggregate';
 
 /**
- * Executes the query and returns the results as a `AggregateQuerySnapshot` from the
- * server. Returns an error if the network is not available.
+ * Calculates the number of documents in the result set of the given query,
+ * without actually downloading the documents.
  *
- * @param query - The `Query` to execute.
+ * Using this function to count the documents is efficient because only the
+ * final count, not the documents' data, is downloaded. This function can even
+ * count the documents if the result set would be prohibitively large to
+ * download entirely (e.g. thousands of documents).
  *
- * @returns A `Promise` that will be resolved with the results of the query.
+ * The result received from the server is presented, unaltered, without
+ * considering any local state. That is, documents in the local cache are not
+ * taken into consideration, neither are local modifications not yet
+ * synchronized with the server. Previously-downloaded results, if any, are not
+ * used: every request using this source necessarily involves a round trip to
+ * the server.
+ *
+ * @param query - The query whose result set size to calculate.
+ * @returns A Promise that will be resolved with the count; the count can be
+ * retrieved from `snapshot.data().count`, where `snapshot` is the
+ * `AggregateQuerySnapshot` to which the returned Promise resolves.
  */
 export function getCountFromServer(
   query: Query<unknown>
diff --git a/packages/firestore/src/lite-api/aggregate.ts b/packages/firestore/src/lite-api/aggregate.ts
@@ -31,14 +31,18 @@ import { Query, queryEqual } from './reference';
 import { LiteUserDataWriter } from './reference_impl';
 
 /**
- * Counts the number of documents in the result set of the given query, ignoring
- * any locally-cached data and any locally-pending writes and simply surfacing
- * whatever the server returns. If the server cannot be reached then the
- * returned promise will be rejected.
+ * Calculates the number of documents in the result set of the given query,
+ * without actually downloading the documents.
  *
- * @param query - The `Query` to execute.
+ * Using this function to count the documents is efficient because only the
+ * final count, not the documents' data, is downloaded. This function can even
+ * count the documents if the result set would be prohibitively large to
+ * download entirely (e.g. thousands of documents).
  *
- * @returns An `AggregateQuerySnapshot` that contains the number of documents.
+ * @param query - The query whose result set size to calculate.
+ * @returns A Promise that will be resolved with the count; the count can be
+ * retrieved from `snapshot.data().count`, where `snapshot` is the
+ * `AggregateQuerySnapshot` to which the returned Promise resolves.
  */
 export function getCount(
   query: Query<unknown>
@@ -51,13 +55,15 @@ export function getCount(
 
 /**
  * Compares two `AggregateQuerySnapshot` instances for equality.
+ *
  * Two `AggregateQuerySnapshot` instances are considered "equal" if they have
- * the same underlying query, and the same data.
+ * underlying queries that compare equal, and the same data.
  *
- * @param left - The `AggregateQuerySnapshot` to compare.
- * @param right - The `AggregateQuerySnapshot` to compare.
+ * @param left - The first `AggregateQuerySnapshot` to compare.
+ * @param right - The second `AggregateQuerySnapshot` to compare.
  *
- * @returns true if the AggregateQuerySnapshots are equal.
+ * @returns `true` if the objects are "equal", as defined above, or `false`
+ * otherwise.
  */
 export function aggregateQuerySnapshotEqual<T extends AggregateSpec>(
   left: AggregateQuerySnapshot<T>,
diff --git a/packages/firestore/src/lite-api/aggregate_types.ts b/packages/firestore/src/lite-api/aggregate_types.ts
@@ -18,64 +18,66 @@
 import { Query } from './reference';
 
 /**
- * An `AggregateField`that captures input type T.
+ * Represents an aggregation that can be performed by Firestore.
  */
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
 export class AggregateField<T> {
+  /** A type string to uniquely identify instances of this class. */
   type = 'AggregateField';
 }
 
 /**
- * Creates and returns an aggregation field that counts the documents in the result set.
- * @returns An `AggregateField` object with number input type.
+ * The union of all `AggregateField` types that are supported by Firestore.
  */
-export function count(): AggregateField<number> {
-  return new AggregateField<number>();
-}
+export type AggregateFieldType = AggregateField<number>;
 
 /**
- * The union of all `AggregateField` types that are returned from the factory
- * functions.
- */
-export type AggregateFieldType = ReturnType<typeof count>;
-
-/**
- * A type whose values are all `AggregateField` objects.
- * This is used as an argument to the "getter" functions, and the snapshot will
- * map the same names to the corresponding values.
+ * A type whose property values are all `AggregateField` objects.
  */
 export interface AggregateSpec {
   [field: string]: AggregateFieldType;
 }
 
 /**
- * A type whose keys are taken from an `AggregateSpec` type, and whose values
- * are the result of the aggregation performed by the corresponding
- * `AggregateField` from the input `AggregateSpec`.
+ * A type whose keys are taken from an `AggregateSpec`, and whose values are the
+ * result of the aggregation performed by the corresponding `AggregateField`
+ * from the input `AggregateSpec`.
  */
 export type AggregateSpecData<T extends AggregateSpec> = {
   [P in keyof T]: T[P] extends AggregateField<infer U> ? U : never;
 };
 
 /**
- * An `AggregateQuerySnapshot` contains the results of running an aggregate query.
+ * The results of executing an aggregation query.
  */
 export class AggregateQuerySnapshot<T extends AggregateSpec> {
+  /** A type string to uniquely identify instances of this class. */
   readonly type = 'AggregateQuerySnapshot';
 
+  /**
+   * The underlying query over which the aggregations recorded in this
+   * `AggregateQuerySnapshot` were performed.
+   */
+  readonly query: Query<unknown>;
+
   /** @hideconstructor */
   constructor(
-    readonly query: Query<unknown>,
+    query: Query<unknown>,
     private readonly _data: AggregateSpecData<T>
-  ) {}
+  ) {
+    this.query = query;
+  }
 
   /**
-   * The results of the requested aggregations. The keys of the returned object
-   * will be the same as those of the `AggregateSpec` object specified to the
-   * aggregation method, and the values will be the corresponding aggregation
-   * result.
+   * Returns the results of the aggregations performed over the underlying
+   * query.
+   *
+   * The keys of the returned object will be the same as those of the
+   * `AggregateSpec` object specified to the aggregation method, and the values
+   * will be the corresponding aggregation result.
    *
-   * @returns The aggregation statistics result of running a query.
+   * @returns The results of the aggregations performed over the underlying
+   * query.
    */
   data(): AggregateSpecData<T> {
     return this._data;
