sum avg (#7502)

* Support sum and average aggregations.
firebase · Oct 10, 2023 · 02e2518 · 02e2518
1 parent cbfd14c
commit 02e2518
Show file tree

Hide file tree

Showing 14 changed files with 556 additions and 249 deletions.
diff --git a/.changeset/beige-oranges-eat.md b/.changeset/beige-oranges-eat.md
@@ -0,0 +1,6 @@
+---
+"@firebase/firestore": minor
+"firebase": minor
+---
+
+Support sum and average aggregations.
diff --git a/common/api-review/firestore-lite.api.md b/common/api-review/firestore-lite.api.md
@@ -19,11 +19,15 @@ export type AddPrefixToKeys<Prefix extends string, T extends Record<string, unkn
 
 // @public
 export class AggregateField<T> {
+    readonly aggregateType: AggregateType;
     readonly type = "AggregateField";
 }
 
 // @public
-export type AggregateFieldType = AggregateField<number | null>;
+export function aggregateFieldEqual(left: AggregateField<unknown>, right: AggregateField<unknown>): boolean;
+
+// @public
+export type AggregateFieldType = ReturnType<typeof sum> | ReturnType<typeof average> | ReturnType<typeof count>;
 
 // @public
 export class AggregateQuerySnapshot<AggregateSpecType extends AggregateSpec, AppModelType = DocumentData, DbModelType extends DocumentData = DocumentData> {
@@ -46,6 +50,9 @@ export type AggregateSpecData<T extends AggregateSpec> = {
     [P in keyof T]: T[P] extends AggregateField<infer U> ? U : never;
 };
 
+// @public
+export type AggregateType = 'count' | 'avg' | 'sum';
+
 // @public
 export function and(...queryConstraints: QueryFilterConstraint[]): QueryCompositeFilterConstraint;
 
@@ -55,6 +62,9 @@ export function arrayRemove(...elements: unknown[]): FieldValue;
 // @public
 export function arrayUnion(...elements: unknown[]): FieldValue;
 
+// @public
+export function average(field: string | FieldPath): AggregateField<number | null>;
+
 // @public
 export class Bytes {
     static fromBase64String(base64: string): Bytes;
@@ -95,6 +105,9 @@ export function connectFirestoreEmulator(firestore: Firestore, host: string, por
     mockUserToken?: EmulatorMockTokenOptions | string;
 }): void;
 
+// @public
+export function count(): AggregateField<number>;
+
 // @public
 export function deleteDoc<AppModelType, DbModelType extends DocumentData>(reference: DocumentReference<AppModelType, DbModelType>): Promise<void>;
 
@@ -201,6 +214,9 @@ export class GeoPoint {
     };
 }
 
+// @public
+export function getAggregate<AggregateSpecType extends AggregateSpec, AppModelType, DbModelType extends DocumentData>(query: Query<AppModelType, DbModelType>, aggregateSpec: AggregateSpecType): Promise<AggregateQuerySnapshot<AggregateSpecType, AppModelType, DbModelType>>;
+
 // @public
 export function getCount<AppModelType, DbModelType extends DocumentData>(query: Query<AppModelType, DbModelType>): Promise<AggregateQuerySnapshot<{
     count: AggregateField<number>;
@@ -388,6 +404,9 @@ export function startAt<AppModelType, DbModelType extends DocumentData>(snapshot
 // @public
 export function startAt(...fieldValues: unknown[]): QueryStartAtConstraint;
 
+// @public
+export function sum(field: string | FieldPath): AggregateField<number>;
+
 // @public
 export function terminate(firestore: Firestore): Promise<void>;
 

diff --git a/common/api-review/firestore.api.md b/common/api-review/firestore.api.md
@@ -19,11 +19,15 @@ export type AddPrefixToKeys<Prefix extends string, T extends Record<string, unkn
 
 // @public
 export class AggregateField<T> {
+    readonly aggregateType: AggregateType;
     readonly type = "AggregateField";
 }
 
 // @public
-export type AggregateFieldType = AggregateField<number | null>;
+export function aggregateFieldEqual(left: AggregateField<unknown>, right: AggregateField<unknown>): boolean;
+
+// @public
+export type AggregateFieldType = ReturnType<typeof sum> | ReturnType<typeof average> | ReturnType<typeof count>;
 
 // @public
 export class AggregateQuerySnapshot<AggregateSpecType extends AggregateSpec, AppModelType = DocumentData, DbModelType extends DocumentData = DocumentData> {
@@ -46,6 +50,9 @@ export type AggregateSpecData<T extends AggregateSpec> = {
     [P in keyof T]: T[P] extends AggregateField<infer U> ? U : never;
 };
 
+// @public
+export type AggregateType = 'count' | 'avg' | 'sum';
+
 // @public
 export function and(...queryConstraints: QueryFilterConstraint[]): QueryCompositeFilterConstraint;
 
@@ -55,6 +62,9 @@ export function arrayRemove(...elements: unknown[]): FieldValue;
 // @public
 export function arrayUnion(...elements: unknown[]): FieldValue;
 
+// @public
+export function average(field: string | FieldPath): AggregateField<number | null>;
+
 // @public
 export class Bytes {
     static fromBase64String(base64: string): Bytes;
@@ -101,6 +111,9 @@ export function connectFirestoreEmulator(firestore: Firestore, host: string, por
     mockUserToken?: EmulatorMockTokenOptions | string;
 }): void;
 
+// @public
+export function count(): AggregateField<number>;
+
 // @public
 export function deleteAllPersistentCacheIndexes(indexManager: PersistentCacheIndexManager): void;
 
@@ -260,6 +273,9 @@ export class GeoPoint {
     };
 }
 
+// @public
+export function getAggregateFromServer<AggregateSpecType extends AggregateSpec, AppModelType, DbModelType extends DocumentData>(query: Query<AppModelType, DbModelType>, aggregateSpec: AggregateSpecType): Promise<AggregateQuerySnapshot<AggregateSpecType, AppModelType, DbModelType>>;
+
 // @public
 export function getCountFromServer<AppModelType, DbModelType extends DocumentData>(query: Query<AppModelType, DbModelType>): Promise<AggregateQuerySnapshot<{
     count: AggregateField<number>;
@@ -661,6 +677,9 @@ export function startAt<AppModelType, DbModelType extends DocumentData>(snapshot
 // @public
 export function startAt(...fieldValues: unknown[]): QueryStartAtConstraint;
 
+// @public
+export function sum(field: string | FieldPath): AggregateField<number>;
+
 // @public
 export type TaskState = 'Error' | 'Running' | 'Success';
 

diff --git a/docs-devsite/firestore_.aggregatefield.md b/docs-devsite/firestore_.aggregatefield.md
@@ -22,8 +22,19 @@ export declare class AggregateField<T>
 
 |  Property | Modifiers | Type | Description |
 |  --- | --- | --- | --- |
+|  [aggregateType](./firestore_.aggregatefield.md#aggregatefieldaggregatetype) |  | [AggregateType](./firestore_.md#aggregatetype) | Indicates the aggregation operation of this AggregateField. |
 |  [type](./firestore_.aggregatefield.md#aggregatefieldtype) |  | (not declared) | A type string to uniquely identify instances of this class. |
 
+## AggregateField.aggregateType
+
+Indicates the aggregation operation of this AggregateField.
+
+<b>Signature:</b>
+
+```typescript
+readonly aggregateType: AggregateType;
+```
+
 ## AggregateField.type
 
 A type string to uniquely identify instances of this class.