@firebase/firestore 3.5.0 → 3.6.0

package/dist/private.d.ts

@@ -39,6 +39,77 @@ export declare type AddPrefixToKeys<Prefix extends string, T extends Record<stri
     [K in keyof T & string as `${Prefix}.${K}`]+?: T[K];
 };
 
+/**
+ * Represents an aggregation that can be performed by Firestore.
+ */
+export declare class AggregateField<T> {
+    /** A type string to uniquely identify instances of this class. */
+    type: string;
+}
+
+/**
+ * The union of all `AggregateField` types that are supported by Firestore.
+ */
+export declare type AggregateFieldType = AggregateField<number>;
+
+/**
+ * The results of executing an aggregation query.
+ */
+export declare class AggregateQuerySnapshot<T extends AggregateSpec> {
+    private readonly _data;
+    /** 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(query: Query<unknown>, _data: AggregateSpecData<T>);
+    /**
+     * 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 results of the aggregations performed over the underlying
+     * query.
+     */
+    data(): AggregateSpecData<T>;
+}
+
+/**
+ * Compares two `AggregateQuerySnapshot` instances for equality.
+ *
+ * Two `AggregateQuerySnapshot` instances are considered "equal" if they have
+ * underlying queries that compare equal, and the same data.
+ *
+ * @param left - The first `AggregateQuerySnapshot` to compare.
+ * @param right - The second `AggregateQuerySnapshot` to compare.
+ *
+ * @returns `true` if the objects are "equal", as defined above, or `false`
+ * otherwise.
+ */
+export declare function aggregateQuerySnapshotEqual<T extends AggregateSpec>(left: AggregateQuerySnapshot<T>, right: AggregateQuerySnapshot<T>): boolean;
+
+/**
+ * A type whose property values are all `AggregateField` objects.
+ */
+export declare interface AggregateSpec {
+    [field: string]: AggregateFieldType;
+}
+
+/**
+ * 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 declare type AggregateSpecData<T extends AggregateSpec> = {
+    [P in keyof T]: T[P] extends AggregateField<infer U> ? U : never;
+};
+
 declare interface ApiClientObjectMap<T> {
     [k: string]: T;
 }
@@ -354,7 +425,7 @@ export declare type ChildUpdateFields<K extends string, V> = V extends Record<st
  * Must be called while the {@link Firestore} instance is not started (after the app is
  * terminated or when the app is first initialized). On startup, this function
  * must be called before other functions (other than {@link
- * initializeFirestore} or {@link getFirestore})). If the {@link Firestore}
+ * initializeFirestore} or {@link (getFirestore:1)})). If the {@link Firestore}
  * instance is still running, the promise will be rejected with the error code
  * of `failed-precondition`.
  *
@@ -1128,7 +1199,7 @@ export { EmulatorMockTokenOptions }
  * Attempts to enable persistent storage, if possible.
  *
  * Must be called before any other functions (other than
- * {@link initializeFirestore}, {@link getFirestore} or
+ * {@link initializeFirestore}, {@link (getFirestore:1)} or
  * {@link clearIndexedDbPersistence}.
  *
  * If this fails, `enableIndexedDbPersistence()` will reject the promise it
@@ -1381,7 +1452,7 @@ declare abstract class Filter {
 /**
  * The Cloud Firestore service interface.
  *
- * Do not call this constructor directly. Instead, use {@link getFirestore}.
+ * Do not call this constructor directly. Instead, use {@link (getFirestore:1)}.
  */
 export declare class Firestore extends Firestore_2 {
     /**
@@ -1399,7 +1470,7 @@ export declare class Firestore extends Firestore_2 {
 /**
  * The Cloud Firestore service interface.
  *
- * Do not call this constructor directly. Instead, use {@link getFirestore}.
+ * Do not call this constructor directly. Instead, use {@link (getFirestore:1)}.
  */
 declare class Firestore_2 implements FirestoreService {
     _authCredentials: CredentialsProvider<User>;
@@ -1982,6 +2053,32 @@ declare namespace firestoreV1ApiClientInterfaces {
         readTime?: string;
         skippedResults?: number;
     }
+    interface RunAggregationQueryRequest {
+        parent?: string;
+        structuredAggregationQuery?: StructuredAggregationQuery;
+        transaction?: string;
+        newTransaction?: TransactionOptions;
+        readTime?: string;
+    }
+    interface RunAggregationQueryResponse {
+        result?: AggregationResult;
+        transaction?: string;
+        readTime?: string;
+    }
+    interface AggregationResult {
+        aggregateFields?: ApiClientObjectMap<Value>;
+    }
+    interface StructuredAggregationQuery {
+        structuredQuery?: StructuredQuery;
+        aggregations?: Aggregation[];
+    }
+    interface Aggregation {
+        count?: Count;
+        alias?: string;
+    }
+    interface Count {
+        upTo?: number;
+    }
     interface Status {
         code?: number;
         message?: string;
@@ -2148,6 +2245,31 @@ export declare class GeoPoint {
     _compareTo(other: GeoPoint): number;
 }
 
+/**
+ * Calculates the number of documents in the result set of the given query,
+ * without actually downloading the documents.
+ *
+ * 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).
+ *
+ * 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 declare function getCountFromServer(query: Query<unknown>): Promise<AggregateQuerySnapshot<{
+    count: AggregateField<number>;
+}>>;
+
 /**
  * Reads the document referred to by this `DocumentReference`.
  *
@@ -2210,25 +2332,25 @@ export declare function getDocsFromServer<T>(query: Query<T>): Promise<QuerySnap
 
 /**
  * Returns the existing default {@link Firestore} instance that is associated with the
- * default {@link @firebase/app#FirebaseApp}. If no instance exists, initializes a new
+ * provided {@link @firebase/app#FirebaseApp}. If no instance exists, initializes a new
  * instance with default settings.
  *
+ * @param app - The {@link @firebase/app#FirebaseApp} instance that the returned {@link Firestore}
+ * instance is associated with.
  * @returns The {@link Firestore} instance of the provided app.
  */
-export declare function getFirestore(): Firestore;
+export declare function getFirestore(app: FirebaseApp): Firestore;
+
+/* Excluded declaration from this release type: getFirestore */
 
 /**
  * Returns the existing default {@link Firestore} instance that is associated with the
- * provided {@link @firebase/app#FirebaseApp}. If no instance exists, initializes a new
+ * default {@link @firebase/app#FirebaseApp}. If no instance exists, initializes a new
  * instance with default settings.
  *
- * @param app - The {@link @firebase/app#FirebaseApp} instance that the returned {@link Firestore}
- * instance is associated with.
  * @returns The {@link Firestore} instance of the provided app.
  */
-export declare function getFirestore(app: FirebaseApp): Firestore;
-
-/* Excluded declaration from this release type: getFirestore */
+export declare function getFirestore(): Firestore;
 
 /* Excluded declaration from this release type: getFirestore */
 
@@ -2253,11 +2375,54 @@ export declare function getFirestore(app: FirebaseApp): Firestore;
  */
 export declare function increment(n: number): FieldValue;
 
-/* Excluded from this release type: Index */
+/**
+ * The SDK definition of a Firestore index.
+ * @beta
+ */
+export declare interface Index {
+    /** The ID of the collection to index. */
+    readonly collectionGroup: string;
+    /** A list of fields to index. */
+    readonly fields?: IndexField[];
+    [key: string]: unknown;
+}
 
-/* Excluded from this release type: IndexConfiguration */
+/**
+ * A list of Firestore indexes to speed up local query execution.
+ *
+ * See {@link https://firebase.google.com/docs/reference/firestore/indexes/#json_format | JSON Format}
+ * for a description of the format of the index definition.
+ * @beta
+ */
+export declare interface IndexConfiguration {
+    /** A list of all Firestore indexes. */
+    readonly indexes?: Index[];
+    [key: string]: unknown;
+}
 
-/* Excluded from this release type: IndexField */
+/**
+ * A single field element in an index configuration.
+ * @beta
+ */
+export declare interface IndexField {
+    /** The field path to index. */
+    readonly fieldPath: string;
+    /**
+     * What type of array index to create. Set to `CONTAINS` for `array-contains`
+     * and `array-contains-any` indexes.
+     *
+     * Only one of `arrayConfig` or `order` should be set;
+     */
+    readonly arrayConfig?: 'CONTAINS';
+    /**
+     * What type of array index to create. Set to `ASCENDING` or 'DESCENDING` for
+     * `==`, `!=`, `<=`, `<=`, `in` and `not-in` filters.
+     *
+     * Only one of `arrayConfig` or `order` should be set.
+     */
+    readonly order?: 'ASCENDING' | 'DESCENDING';
+    [key: string]: unknown;
+}
 
 declare type IndexFieldMode = 'MODE_UNSPECIFIED' | 'ASCENDING' | 'DESCENDING';
 
@@ -2446,8 +2611,8 @@ declare const enum IndexType {
 /**
  * Initializes a new instance of {@link Firestore} with the provided settings.
  * Can only be called before any other function, including
- * {@link getFirestore}. If the custom settings are empty, this function is
- * equivalent to calling {@link getFirestore}.
+ * {@link (getFirestore:1)}. If the custom settings are empty, this function is
+ * equivalent to calling {@link (getFirestore:1)}.
  *
  * @param app - The {@link @firebase/app#FirebaseApp} with which the {@link Firestore} instance will
  * be associated.
@@ -4502,7 +4667,57 @@ export declare function setDoc<T>(reference: DocumentReference<T>, data: WithFie
  */
 export declare function setDoc<T>(reference: DocumentReference<T>, data: PartialWithFieldValue<T>, options: SetOptions): Promise<void>;
 
-/* Excluded from this release type: setIndexConfiguration */
+/**
+ * Configures indexing for local query execution. Any previous index
+ * configuration is overridden. The `Promise` resolves once the index
+ * configuration has been persisted.
+ *
+ * The index entries themselves are created asynchronously. You can continue to
+ * use queries that require indexing even if the indices are not yet available.
+ * Query execution will automatically start using the index once the index
+ * entries have been written.
+ *
+ * Indexes are only supported with IndexedDb persistence. Invoke either
+ * `enableIndexedDbPersistence()` or `enableMultiTabIndexedDbPersistence()`
+ * before setting an index configuration. If IndexedDb is not enabled, any
+ * index configuration is ignored.
+ *
+ * @param firestore - The {@link Firestore} instance to configure indexes for.
+ * @param configuration -The index definition.
+ * @throws FirestoreError if the JSON format is invalid.
+ * @returns A `Promise` that resolves once all indices are successfully
+ * configured.
+ * @beta
+ */
+export declare function setIndexConfiguration(firestore: Firestore, configuration: IndexConfiguration): Promise<void>;
+
+/**
+ * Configures indexing for local query execution. Any previous index
+ * configuration is overridden. The `Promise` resolves once the index
+ * configuration has been persisted.
+ *
+ * The index entries themselves are created asynchronously. You can continue to
+ * use queries that require indexing even if the indices are not yet available.
+ * Query execution will automatically start using the index once the index
+ * entries have been written.
+ *
+ * Indexes are only supported with IndexedDb persistence. Invoke either
+ * `enableIndexedDbPersistence()` or `enableMultiTabIndexedDbPersistence()`
+ * before setting an index configuration. If IndexedDb is not enabled, any
+ * index configuration is ignored.
+ *
+ * The method accepts the JSON format exported by the Firebase CLI (`firebase
+ * firestore:indexes`). If the JSON format is invalid, this method throws an
+ * error.
+ *
+ * @param firestore - The {@link Firestore} instance to configure indexes for.
+ * @param json -The JSON format exported by the Firebase CLI.
+ * @throws FirestoreError if the JSON format is invalid.
+ * @returns A `Promise` that resolves once all indices are successfully
+ * configured.
+ * @beta
+ */
+export declare function setIndexConfiguration(firestore: Firestore, json: string): Promise<void>;
 
 /**
  * Sets the verbosity of Cloud Firestore logs (debug, error, or silent).
@@ -5198,7 +5413,7 @@ export declare type TaskState = 'Error' | 'Running' | 'Success';
  * may be used. Any other function will throw a `FirestoreError`.
  *
  * To restart after termination, create a new instance of FirebaseFirestore with
- * {@link getFirestore}.
+ * {@link (getFirestore:1)}.
  *
  * Termination does not cancel any pending writes, and any promises that are
  * awaiting a response from the server will not be resolved. If you have

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@firebase/firestore",
-  "version": "3.5.0",
+  "version": "3.6.0",
   "engines": {
     "node": ">=10.10.0"
   },
@@ -80,9 +80,9 @@
     "lite/package.json"
   ],
   "dependencies": {
-    "@firebase/component": "0.5.17",
+    "@firebase/component": "0.5.18",
     "@firebase/logger": "0.3.3",
-    "@firebase/util": "1.6.3",
+    "@firebase/util": "1.7.0",
     "@firebase/webchannel-wrapper": "0.7.0",
     "@grpc/grpc-js": "^1.3.2",
     "@grpc/proto-loader": "^0.6.13",
@@ -93,9 +93,9 @@
     "@firebase/app": "0.x"
   },
   "devDependencies": {
-    "@firebase/app": "0.7.33",
-    "@firebase/app-compat": "0.1.34",
-    "@firebase/auth": "0.20.7",
+    "@firebase/app": "0.8.0",
+    "@firebase/app-compat": "0.1.35",
+    "@firebase/auth": "0.20.8",
     "@rollup/plugin-alias": "3.1.9",
     "@rollup/plugin-json": "4.1.0",
     "@types/eslint": "7.29.0",