<NME> firestore.d.ts <BEF> /*! * Copyright 2020 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. */ // We deliberately use `any` in the external API to not impose type-checking // on end users. /* eslint-disable @typescript-eslint/no-explicit-any */ // Declare a global (ambient) namespace // (used when not using import statement, but just script include). declare namespace FirebaseFirestore { /** Alias for `any` but used where a Firestore field value would be provided. */ export type DocumentFieldValue = any; /** * Document data (for use with `DocumentReference.set()`) consists of fields * mapped to values. */ export type DocumentData = {[field: string]: DocumentFieldValue}; /** * Similar to Typescript's `Partial<T>`, but allows nested fields to be * omitted and FieldValues to be passed in as property values. */ export type PartialWithFieldValue<T> = | Partial<T> | (T extends Primitive ? T : T extends {} ? {[K in keyof T]?: PartialWithFieldValue<T[K]> | FieldValue} : never); /** * Allows FieldValues to be passed in as a property value while maintaining * type safety. */ export type WithFieldValue<T> = | T | (T extends Primitive ? T : T extends {} ? {[K in keyof T]: WithFieldValue<T[K]> | FieldValue} : never); /** * Update data (for use with [update]{@link DocumentReference#update}) * that contains paths mapped to values. Fields that contain dots reference * nested fields within the document. FieldValues can be passed in * as property values. * * You can update a top-level field in your document by using the field name * as a key (e.g. `foo`). The provided value completely replaces the contents * for this field. * * You can also update a nested field directly by using its field path as a * key (e.g. `foo.bar`). This nested field update replaces the contents at * `bar` but does not modify other data under `foo`. */ export type UpdateData<T> = T extends Primitive ? T : T extends {} ? {[K in keyof T]?: UpdateData<T[K]> | FieldValue} & NestedUpdateFields<T> : Partial<T>; /** Primitive types. */ export type Primitive = string | number | boolean | undefined | null; /** * For each field (e.g. 'bar'), find all nested keys (e.g. {'bar.baz': T1, * 'bar.qux': T2}). Intersect them together to make a single map containing * all possible keys that are all marked as optional */ export type NestedUpdateFields<T extends Record<string, unknown>> = UnionToIntersection< { [K in keyof T & string]: ChildUpdateFields<K, T[K]>; }[keyof T & string] // Also include the generated prefix-string keys. >; /** * Helper for calculating the nested fields for a given type T1. This is needed * to distribute union types such as `undefined | {...}` (happens for optional * props) or `{a: A} | {b: B}`. * * In this use case, `V` is used to distribute the union types of `T[K]` on * `Record`, since `T[K]` is evaluated as an expression and not distributed. * * See https://www.typescriptlang.org/docs/handbook/advanced-types.html#distributive-conditional-types */ export type ChildUpdateFields<K extends string, V> = // Only allow nesting for map values V extends Record<string, unknown> ? // Recurse into the map and add the prefix in front of each key // (e.g. Prefix 'bar.' to create: 'bar.baz' and 'bar.qux'. AddPrefixToKeys<K, UpdateData<V>> : // UpdateData is always a map of values. never; /** * Returns a new map where every key is prefixed with the outer key appended * to a dot. */ export type AddPrefixToKeys< Prefix extends string, T extends Record<string, unknown> > = // Remap K => Prefix.K. See https://www.typescriptlang.org/docs/handbook/2/mapped-types.html#key-remapping-via-as {[K in keyof T & string as `${Prefix}.${K}`]+?: T[K]}; /** * Given a union type `U = T1 | T2 | ...`, returns an intersected type * `(T1 & T2 & ...)`. * * Uses distributive conditional types and inference from conditional types. * This works because multiple candidates for the same type variable in * contra-variant positions causes an intersection type to be inferred. * https://www.typescriptlang.org/docs/handbook/advanced-types.html#type-inference-in-conditional-types * https://stackoverflow.com/questions/50374908/transform-union-type-to-intersection-type */ export type UnionToIntersection<U> = ( U extends unknown ? (k: U) => void : never ) extends (k: infer I) => void ? I : never; /** * Sets or disables the log function for all active Firestore instances. * * @param logger A log function that takes a message (such as `console.log`) or * `null` to turn off logging. */ function setLogFunction(logger: ((msg: string) => void) | null): void; /** * Converter used by `withConverter()` to transform user objects of type T * into Firestore data. * * Using the converter allows you to specify generic type arguments when * storing and retrieving objects from Firestore. * * @example * class Post { * constructor(readonly title: string, readonly author: string) {} * * toString(): string { * return this.title + ', by ' + this.author; * } * } * * const postConverter = { * toFirestore(post: Post): FirebaseFirestore.DocumentData { * return {title: post.title, author: post.author}; * }, * fromFirestore( * snapshot: FirebaseFirestore.QueryDocumentSnapshot * ): Post { * const data = snapshot.data(); * return new Post(data.title, data.author); * } * }; * * const postSnap = await Firestore() * .collection('posts') * .withConverter(postConverter) * .doc().get(); * const post = postSnap.data(); * if (post !== undefined) { * post.title; // string * post.toString(); // Should be defined * post.someNonExistentProperty; // TS error * } */ export interface FirestoreDataConverter<T> { /** * Called by the Firestore SDK to convert a custom model object of type T * into a plain Javascript object (suitable for writing directly to the * Firestore database). To use set() with `merge` and `mergeFields`, * toFirestore() must be defined with `Partial<T>`. * * The `WithFieldValue<T>` type extends `T` to also allow FieldValues such * as `FieldValue.delete()` to be used as property values. */ toFirestore(modelObject: WithFieldValue<T>): DocumentData; /** * Called by the Firestore SDK to convert a custom model object of type T * into a plain Javascript object (suitable for writing directly to the * Firestore database). To use set() with `merge` and `mergeFields`, * toFirestore() must be defined with `Partial<T>`. * * The `PartialWithFieldValue<T>` type extends `Partial<T>` to allow * FieldValues such as `FieldValue.delete()` to be used as property values. * It also supports nested `Partial` by allowing nested fields to be * omitted. */ toFirestore( modelObject: PartialWithFieldValue<T>, options: SetOptions ): DocumentData; /** * Called by the Firestore SDK to convert Firestore data into an object of * type T. */ fromFirestore(snapshot: QueryDocumentSnapshot): T; } /** * Settings used to directly configure a `Firestore` instance. */ export interface Settings { /** * The project ID from the Google Developer's Console, e.g. * 'grape-spaceship-123'. We will also check the environment variable * GCLOUD_PROJECT for your project ID. Can be omitted in environments that * support {@link https://cloud.google.com/docs/authentication Application * Default Credentials} */ projectId?: string; /** * The database name. If omitted, the default database will be used. * * @internal */ databaseId?: string; /** The hostname to connect to. */ host?: string; /** The port to connect to. */ port?: number; /** * Local file containing the Service Account credentials as downloaded from * the Google Developers Console. Can be omitted in environments that * support {@link https://cloud.google.com/docs/authentication Application * Default Credentials}. To configure Firestore with custom credentials, use * the `credentials` property to provide the `client_email` and * `private_key` of your service account. */ keyFilename?: string; /** * The 'client_email' and 'private_key' properties of the service account * to use with your Firestore project. Can be omitted in environments that * support {@link https://cloud.google.com/docs/authentication Application * Default Credentials}. If your credentials are stored in a JSON file, you * can specify a `keyFilename` instead. */ credentials?: {client_email?: string; private_key?: string}; /** Whether to use SSL when connecting. */ ssl?: boolean; /** * The maximum number of idle GRPC channels to keep. A smaller number of idle * channels reduces memory usage but increases request latency for clients * with fluctuating request rates. If set to 0, shuts down all GRPC channels * when the client becomes idle. Defaults to 1. */ maxIdleChannels?: number; /** * Whether to use `BigInt` for integer types when deserializing Firestore * Documents. Regardless of magnitude, all integer values are returned as * `BigInt` to match the precision of the Firestore backend. Floating point * numbers continue to use JavaScript's `number` type. */ useBigInt?: boolean; /** * Whether to skip nested properties that are set to `undefined` during * object serialization. If set to `true`, these properties are skipped * and not written to Firestore. If set `false` or omitted, the SDK throws * an exception when it encounters properties of type `undefined`. */ ignoreUndefinedProperties?: boolean; /** * Use HTTP for requests that can be served over HTTP and JSON. This reduces * the amount of networking code that is loaded to serve requests within * Firestore. * * This setting does not apply to `onSnapshot` APIs as they cannot be served * over native HTTP. */ preferRest?: boolean; [key: string]: any; // Accept other properties, such as GRPC settings. } /** Options to configure a read-only transaction. */ export interface ReadOnlyTransactionOptions { /** Set to true to indicate a read-only transaction. */ readOnly: true; /** * If specified, documents are read at the given time. This may not be more * than 60 seconds in the past from when the request is processed by the * server. */ readTime?: Timestamp; } /** Options to configure a read-write transaction. */ export interface ReadWriteTransactionOptions { /** Set to false or omit to indicate a read-write transaction. */ readOnly?: false; /** * The maximum number of attempts for this transaction. Defaults to 5. */ maxAttempts?: number; } /** * `Firestore` represents a Firestore Database and is the entry point for all * Firestore operations. */ export class Firestore { /** * @param settings Configuration object. See [Firestore Documentation] * {@link https://firebase.google.com/docs/firestore/} */ public constructor(settings?: Settings); /** * Specifies custom settings to be used to configure the `Firestore` * instance. Can only be invoked once and before any other Firestore * method. * * If settings are provided via both `settings()` and the `Firestore` * constructor, both settings objects are merged and any settings provided * via `settings()` take precedence. * * @param {object} settings The settings to use for all Firestore * operations. */ settings(settings: Settings): void; /** * Gets a `CollectionReference` instance that refers to the collection at * the specified path. * * @param collectionPath A slash-separated path to a collection. * @return The `CollectionReference` instance. */ collection(collectionPath: string): CollectionReference<DocumentData>; /** * Gets a `DocumentReference` instance that refers to the document at the * specified path. * * @param documentPath A slash-separated path to a document. * @return The `DocumentReference` instance. */ doc(documentPath: string): DocumentReference<DocumentData>; /** * Creates and returns a new Query that includes all documents in the * database that are contained in a collection or subcollection with the * given collectionId. * * @param collectionId Identifies the collections to query over. Every * collection or subcollection with this ID as the last segment of its path * will be included. Cannot contain a slash. * @return The created `CollectionGroup`. */ collectionGroup(collectionId: string): CollectionGroup<DocumentData>; /** * Retrieves multiple documents from Firestore. * * The first argument is required and must be of type `DocumentReference` * followed by any additional `DocumentReference` documents. If used, the * optional `ReadOptions` must be the last argument. * * @param {Array.<DocumentReference|ReadOptions>} documentRefsOrReadOptions * The `DocumentReferences` to receive, followed by an optional field * mask. * @return A Promise that resolves with an array of resulting document * snapshots. */ getAll( ...documentRefsOrReadOptions: Array< DocumentReference<DocumentData> | ReadOptions > ): Promise<Array<DocumentSnapshot<DocumentData>>>; /** * Recursively deletes all documents and subcollections at and under the * specified level. * * If any delete fails, the promise is rejected with an error message * containing the number of failed deletes and the stack trace of the last * failed delete. The provided reference is deleted regardless of whether * all deletes succeeded. * * `recursiveDelete()` uses a BulkWriter instance with default settings to * perform the deletes. To customize throttling rates or add success/error * callbacks, pass in a custom BulkWriter instance. * * @param ref The reference of a document or collection to delete. * @param bulkWriter A custom BulkWriter instance used to perform the * deletes. * @return A promise that resolves when all deletes have been performed. * The promise is rejected if any of the deletes fail. * * @example * // Recursively delete a reference and log the references of failures. * const bulkWriter = firestore.bulkWriter(); * bulkWriter * .onWriteError((error) => { * if ( * error.failedAttempts < MAX_RETRY_ATTEMPTS * ) { * return true; * } else { * console.log('Failed write at document: ', error.documentRef.path); * return false; * } * }); * await firestore.recursiveDelete(docRef, bulkWriter); */ recursiveDelete( ref: CollectionReference<unknown> | DocumentReference<unknown>, bulkWriter?: BulkWriter ): Promise<void>; /** * Terminates the Firestore client and closes all open streams. * * @return A Promise that resolves when the client is terminated. */ terminate(): Promise<void>; /** * Fetches the root collections that are associated with this Firestore * database. * * @returns A Promise that resolves with an array of CollectionReferences. */ listCollections(): Promise<Array<CollectionReference<DocumentData>>>; /** * Executes the given updateFunction and commits the changes applied within * the transaction. * * You can use the transaction object passed to 'updateFunction' to read and * modify Firestore documents under lock. You have to perform all reads * before you perform any write. * * Transactions can be performed as read-only or read-write transactions. By * default, transactions are executed in read-write mode. * * A read-write transaction obtains a pessimistic lock on all documents that * are read during the transaction. These locks block other transactions, * batched writes, and other non-transactional writes from changing that * document. Any writes in a read-write transactions are committed once * 'updateFunction' resolves, which also releases all locks. * * If a read-write transaction fails with contention, the transaction is * retried up to five times. The `updateFunction` is invoked once for each * attempt. * * Read-only transactions do not lock documents. They can be used to read * documents at a consistent snapshot in time, which may be up to 60 seconds * in the past. Read-only transactions are not retried. * * Transactions time out after 60 seconds if no documents are read. * Transactions that are not committed within than 270 seconds are also * aborted. Any remaining locks are released when a transaction times out. * * @param updateFunction The function to execute within the transaction * context. * @param transactionOptions Transaction options. * @return If the transaction completed successfully or was explicitly * aborted (by the updateFunction returning a failed Promise), the Promise * returned by the updateFunction will be returned here. Else if the * transaction failed, a rejected Promise with the corresponding failure * error will be returned. */ runTransaction<T>( updateFunction: (transaction: Transaction) => Promise<T>, transactionOptions?: | ReadWriteTransactionOptions | ReadOnlyTransactionOptions ): Promise<T>; /** * Creates a write batch, used for performing multiple writes as a single * atomic operation. */ batch(): WriteBatch; /** * Creates a [BulkWriter]{@link BulkWriter}, used for performing * multiple writes in parallel. Gradually ramps up writes as specified * by the 500/50/5 rule. * * @see https://firebase.google.com/docs/firestore/best-practices#ramping_up_traffic * * @param options An options object used to configure the throttling * behavior for the underlying BulkWriter. */ bulkWriter(options?: BulkWriterOptions): BulkWriter; /** * Creates a new `BundleBuilder` instance to package selected Firestore data into * a bundle. * * @param bundleId The ID of the bundle. When loaded on clients, client SDKs use this ID * and the timestamp associated with the bundle to tell if it has been loaded already. * If not specified, a random identifier will be used. * * * @example * const bundle = firestore.bundle('data-bundle'); * const docSnapshot = await firestore.doc('abc/123').get(); * const querySnapshot = await firestore.collection('coll').get(); * * const bundleBuffer = bundle.add(docSnapshot); // Add a document * .add('coll-query', querySnapshot) // Add a named query. * .build() * // Save `bundleBuffer` to CDN or stream it to clients. */ bundle(bundleId?: string): BundleBuilder; } /** * An immutable object representing a geo point in Firestore. The geo point * is represented as latitude/longitude pair. * * Latitude values are in the range of [-90, 90]. * Longitude values are in the range of [-180, 180]. */ export class GeoPoint { /** * Creates a new immutable GeoPoint object with the provided latitude and * longitude values. * @param latitude The latitude as number between -90 and 90. * @param longitude The longitude as number between -180 and 180. */ constructor(latitude: number, longitude: number); readonly latitude: number; readonly longitude: number; /** * Returns true if this `GeoPoint` is equal to the provided one. * * @param other The `GeoPoint` to compare against. * @return true if this `GeoPoint` is equal to the provided one. */ isEqual(other: GeoPoint): boolean; } /** * A reference to a transaction. * The `Transaction` object passed to a transaction's updateFunction provides * the methods to read and write data within the transaction context. See * `Firestore.runTransaction()`. */ export class Transaction { private constructor(); /** * Retrieves a query result. Holds a pessimistic lock on all returned * documents. * * @param query A query to execute. * @return A QuerySnapshot for the retrieved data. */ get<T>(query: Query<T>): Promise<QuerySnapshot<T>>; /** * Reads the document referenced by the provided `DocumentReference.` * Holds a pessimistic lock on the returned document. * * @param documentRef A reference to the document to be read. * @return A DocumentSnapshot for the read data. */ get<T>(documentRef: DocumentReference<T>): Promise<DocumentSnapshot<T>>; /** * Retrieves an aggregate query result. Holds a pessimistic lock on all * documents that were matched by the underlying query. * * @param aggregateQuery An aggregate query to execute. * @return An AggregateQuerySnapshot for the retrieved data. */ get<T extends AggregateSpec>( aggregateQuery: AggregateQuery<T> ): Promise<AggregateQuerySnapshot<T>>; /** * Retrieves multiple documents from Firestore. Holds a pessimistic lock on * all returned documents. * * The first argument is required and must be of type `DocumentReference` * followed by any additional `DocumentReference` documents. If used, the * optional `ReadOptions` must be the last argument. * * @param {Array.<DocumentReference|ReadOptions>} documentRefsOrReadOptions * The `DocumentReferences` to receive, followed by an optional field * mask. * @return A Promise that resolves with an array of resulting document * snapshots. */ getAll<T>( ...documentRefsOrReadOptions: Array<DocumentReference<T> | ReadOptions> ): Promise<Array<DocumentSnapshot<T>>>; /** * Create the document referred to by the provided `DocumentReference`. * The operation will fail the transaction if a document exists at the * specified location. * * @param documentRef A reference to the document to be create. * @param data The object data to serialize as the document. * @throws Error If the provided input is not a valid Firestore document. * @return This `Transaction` instance. Used for chaining method calls. */ create<T>( documentRef: DocumentReference<T>, data: WithFieldValue<T> ): Transaction; /** * Writes to the document referred to by the provided `DocumentReference`. * If the document does not exist yet, it will be created. If you pass * `SetOptions`, the provided data can be merged into the existing document. * * @param documentRef A reference to the document to be set. * @param data An object of the fields and values for the document. * @param options An object to configure the set behavior. * @param options.merge - If true, set() merges the values specified in its * data argument. Fields omitted from this set() call remain untouched. If * your input sets any field to an empty map, all nested fields are * overwritten. * @param options.mergeFields - If provided, set() only replaces the * specified field paths. Any field path that is not specified is ignored * and remains untouched. If your input sets any field to an empty map, all * nested fields are overwritten. * @throws Error If the provided input is not a valid Firestore document. * @return This `Transaction` instance. Used for chaining method calls. */ set<T>( documentRef: DocumentReference<T>, data: PartialWithFieldValue<T>, options: SetOptions ): Transaction; set<T>( documentRef: DocumentReference<T>, data: WithFieldValue<T> ): Transaction; /** * Updates fields in the document referred to by the provided * `DocumentReference`. The update will fail if applied to a document that * does not exist. * * Nested fields can be updated by providing dot-separated field path * strings. * * @param documentRef A reference to the document to be updated. * @param data An object containing the fields and values with which to * update the document. * @param precondition A Precondition to enforce on this update. * @throws Error If the provided input is not valid Firestore data. * @return This `Transaction` instance. Used for chaining method calls. */ update<T>( documentRef: DocumentReference<T>, data: UpdateData<T>, precondition?: Precondition ): Transaction; /** * Updates fields in the document referred to by the provided * `DocumentReference`. The update will fail if applied to a document that * does not exist. * * Nested fields can be updated by providing dot-separated field path * strings or by providing FieldPath objects. * * A `Precondition` restricting this update can be specified as the last * argument. * * @param documentRef A reference to the document to be updated. * @param field The first field to update. * @param value The first value * @param fieldsOrPrecondition An alternating list of field paths and values * to update, optionally followed by a `Precondition` to enforce on this * update. * @throws Error If the provided input is not valid Firestore data. * @return This `Transaction` instance. Used for chaining method calls. */ update( documentRef: DocumentReference<any>, field: string | FieldPath, value: any, ...fieldsOrPrecondition: any[] ): Transaction; /** * Deletes the document referred to by the provided `DocumentReference`. * * @param documentRef A reference to the document to be deleted. * @param precondition A Precondition to enforce for this delete. * @return This `Transaction` instance. Used for chaining method calls. */ delete( documentRef: DocumentReference<any>, precondition?: Precondition ): Transaction; } /** * A Firestore BulkWriter than can be used to perform a large number of writes * in parallel. Writes to the same document will be executed sequentially. * * @class */ export class BulkWriter { private constructor(); /** * Create a document with the provided data. This single operation will fail * if a document exists at its location. * * @param documentRef A reference to the document to be * created. * @param data The object to serialize as the document. * @throws Error If the provided input is not a valid Firestore document. * @returns A promise that resolves with the result of the write. If the * write fails, the promise is rejected with a * [BulkWriterError]{@link BulkWriterError}. */ create<T>( documentRef: DocumentReference<T>, data: WithFieldValue<T> ): Promise<WriteResult>; /** * Delete a document from the database. * * @param documentRef A reference to the document to be * deleted. * @param precondition A precondition to enforce for this * delete. * @param precondition.lastUpdateTime If set, enforces that the * document was last updated at lastUpdateTime. Fails the batch if the * document doesn't exist or was last updated at a different time. * @param precondition.exists If set, enforces that the target document * must or must not exist. * @returns A promise that resolves with the result of the delete. If the * delete fails, the promise is rejected with a * [BulkWriterError]{@link BulkWriterError}. */ delete( documentRef: DocumentReference<any>, precondition?: Precondition ): Promise<WriteResult>; /** * Write to the document referred to by the provided * [DocumentReference]{@link DocumentReference}. If the document does not * exist yet, it will be created. If you pass * [SetOptions]{@link SetOptions}., the provided data can be merged into the * existing document. * * @param documentRef A reference to the document to be * set. * @param data The object to serialize as the document. * @param options An object to configure the set behavior. * @param options.merge - If true, set() merges the values specified in its * data argument. Fields omitted from this set() call remain untouched. If * your input sets any field to an empty map, all nested fields are * overwritten. * @param options.mergeFields - If provided, set() only replaces the * specified field paths. Any field path that is not specified is ignored * and remains untouched. If your input sets any field to an empty map, all * nested fields are overwritten. * @throws Error If the provided input is not a valid Firestore document. * @returns A promise that resolves with the result of the write. If the * write fails, the promise is rejected with a * [BulkWriterError]{@link BulkWriterError}. */ set<T>( documentRef: DocumentReference<T>, data: PartialWithFieldValue<T>, options: SetOptions ): Promise<WriteResult>; set<T>( documentRef: DocumentReference<T>, data: WithFieldValue<T> ): Promise<WriteResult>; /** * Update fields of the document referred to by the provided * [DocumentReference]{@link DocumentReference}. If the document doesn't yet * exist, the update fails and the entire batch will be rejected. * * The update() method accepts either an object with field paths encoded as * keys and field values encoded as values, or a variable number of * arguments that alternate between field paths and field values. Nested * fields can be updated by providing dot-separated field path strings or by * providing FieldPath objects. * * * A Precondition restricting this update can be specified as the last * argument. * * @param documentRef A reference to the document to be updated. * @param data An object containing the fields and values with which to * update the document. * @param precondition A Precondition to enforce on this update. * @throws Error If the provided input is not valid Firestore data. * @returns A promise that resolves with the result of the write. If the * write fails, the promise is rejected with a * [BulkWriterError]{@link BulkWriterError}. */ update<T>( documentRef: DocumentReference<T>, data: UpdateData<T>, precondition?: Precondition ): Promise<WriteResult>; /** * Update fields of the document referred to by the provided * [DocumentReference]{@link DocumentReference}. If the document doesn't yet * exist, the update fails and the entire batch will be rejected. * * The update() method accepts either an object with field paths encoded as * keys and field values encoded as values, or a variable number of * arguments that alternate between field paths and field values. Nested * fields can be updated by providing dot-separated field path strings or by * providing FieldPath objects. * * * A Precondition restricting this update can be specified as the last * argument. * * @param documentRef A reference to the document to be updated. * @param field The first field to update. * @param value The first value * @param fieldsOrPrecondition An alternating list of field paths and values * to update, optionally followed a `Precondition` to enforce on this * update. * @throws Error If the provided input is not valid Firestore data; * @returns A promise that resolves with the result of the write. If the * write fails, the promise is rejected with a * [BulkWriterError]{@link BulkWriterError}. */ update( documentRef: DocumentReference<any>, field: string | FieldPath, value: any, ...fieldsOrPrecondition: any[] ): Promise<WriteResult>; /** * Attaches a listener that is run every time a BulkWriter operation * successfully completes. * * @param callback A callback to be called every time a BulkWriter operation * successfully completes. */ onWriteResult( callback: ( documentRef: DocumentReference<any>, result: WriteResult ) => void ): void; /** * Attaches an error handler listener that is run every time a BulkWriter * operation fails. * * BulkWriter has a default error handler that retries UNAVAILABLE and * ABORTED errors up to a maximum of 10 failed attempts. When an error * handler is specified, the default error handler will be overwritten. * * @param shouldRetryCallback A callback to be called every time a BulkWriter * operation fails. Returning `true` will retry the operation. Returning * `false` will stop the retry loop. */ onWriteError( shouldRetryCallback: (error: BulkWriterError) => boolean ): void; /** * Commits all writes that have been enqueued up to this point in parallel. * * Returns a Promise that resolves when all currently queued operations have * been committed. The Promise will never be rejected since the results for * each individual operation are conveyed via their individual Promises. * * The Promise resolves immediately if there are no pending writes. * Otherwise, the Promise waits for all previously issued writes, but it * does not wait for writes that were added after the method is called. If * you want to wait for additional writes, call `flush()` again. * * @return A promise that resolves when all enqueued writes * up to this point have been committed. */ flush(): Promise<void>; /** * Commits all enqueued writes and marks the BulkWriter instance as closed. * * After calling `close()`, calling any method will throw an error. Any * retries scheduled as part of an `onWriteError()` handler will be run * before the `close()` promise resolves. * * Returns a Promise that resolves when all writes have been committed. The * Promise will never be rejected. Calling this method will send all * requests. The promise resolves immediately if there are no pending * writes. * * @return A promise that resolves when all enqueued writes * up to this point have been committed. */ close(): Promise<void>; } /** * An options object to configure throttling on BulkWriter. */ export interface BulkWriterOptions { /** * Whether to disable or configure throttling. By default, throttling is * enabled. This field can be set to either a boolean or a config * object. Setting it to `true` will use default values. You can override * the defaults by setting it to `false` to disable throttling, or by * setting the config values to enable throttling with the provided values. * * @see https://firebase.google.com/docs/firestore/best-practices#ramping_up_traffic * * @param initialOpsPerSecond The initial maximum number of operations per * second allowed by the throttler. If this field is not set, the default * is 500 operations per second. * @param maxOpsPerSecond The maximum number of operations per second * allowed by the throttler. If this field is set, the throttler's allowed * operations per second does not ramp up past the specified operations per * second. */ readonly throttling?: | boolean | {initialOpsPerSecond?: number; maxOpsPerSecond?: number}; } /** * The error thrown when a BulkWriter operation fails. */ export class BulkWriterError extends Error { /** The status code of the error. */ readonly code: GrpcStatus; /** The error message of the error. */ readonly message: string; /** The document reference the operation was performed on. */ readonly documentRef: DocumentReference<any>; /** The type of operation performed. */ readonly operationType: 'create' | 'set' | 'update' | 'delete'; /** How many times this operation has been attempted unsuccessfully. */ readonly failedAttempts: number; } /** * A write batch, used to perform multiple writes as a single atomic unit. * * A `WriteBatch` object can be acquired by calling `Firestore.batch()`. It * provides methods for adding writes to the write batch. None of the * writes will be committed (or visible locally) until `WriteBatch.commit()` * is called. * * Unlike transactions, write batches are persisted offline and therefore are * preferable when you don't need to condition your writes on read data. */ export class WriteBatch { private constructor(); /** * Create the document referred to by the provided `DocumentReference`. The * operation will fail the batch if a document exists at the specified * location. * * @param documentRef A reference to the document to be created. * @param data The object data to serialize as the document. * @throws Error If the provided input is not a valid Firestore document. * @return This `WriteBatch` instance. Used for chaining method calls. */ create<T>( documentRef: DocumentReference<T>, data: WithFieldValue<T> ): WriteBatch; /** * Write to the document referred to by the provided `DocumentReference`. * If the document does not exist yet, it will be created. If you pass * `SetOptions`, the provided data can be merged into the existing document. * * @param documentRef A reference to the document to be set. * @param data An object of the fields and values for the document. * @param options An object to configure the set behavior. * @param options.merge - If true, set() merges the values specified in its * data argument. Fields omitted from this set() call remain untouched. If * your input sets any field to an empty map, all nested fields are * overwritten. * @param options.mergeFields - If provided, set() only replaces the * specified field paths. Any field path that is not specified is ignored * and remains untouched. If your input sets any field to an empty map, all * nested fields are overwritten. * @throws Error If the provided input is not a valid Firestore document. * @return This `WriteBatch` instance. Used for chaining method calls. */ set<T>( documentRef: DocumentReference<T>, data: PartialWithFieldValue<T>, options: SetOptions ): WriteBatch; set<T>( documentRef: DocumentReference<T>, data: WithFieldValue<T> ): WriteBatch; /** * Update fields of the document referred to by the provided * `DocumentReference`. If the document doesn't yet exist, the update fails * and the entire batch will be rejected. * * Nested fields can be updated by providing dot-separated field path * strings. * * @param documentRef A reference to the document to be updated. * @param data An object containing the fields and values with which to * update the document. */ readonly path: string; /** * Get a `DocumentReference` for the document within the collection at the * specified path. If no path is specified, an automatically-generated * * @param documentRef A reference to the document to be updated. * @param field The first field to update. * @param value The first value * @param fieldsOrPrecondition An alternating list of field paths and values * to update, optionally followed a `Precondition` to enforce on this * update. * @throws Error If the provided input is not valid Firestore data. * @return This `WriteBatch` instance. Used for chaining method calls. */ update( documentRef: DocumentReference<any>, field: string | FieldPath, value: any, ...fieldsOrPrecondition: any[] ): WriteBatch; /** * Deletes the document referred to by the provided `DocumentReference`. * * @param documentRef A reference to the document to be deleted. * @param precondition A Precondition to enforce for this delete. * @return This `WriteBatch` instance. Used for chaining method calls. */ delete( documentRef: DocumentReference<any>, precondition?: Precondition ): WriteBatch; /** * Commits all of the writes in this write batch as a single atomic unit. * * @return A Promise resolved once all of the writes in the batch have been * successfully written to the backend as an atomic unit. */ commit(): Promise<WriteResult[]>; } /** * An options object that configures conditional behavior of `update()` and * `delete()` calls in `DocumentReference`, `WriteBatch`, and `Transaction`. * Using Preconditions, these calls can be restricted to only apply to * documents that match the specified restrictions. */ export interface Precondition { /** * If set, the last update time to enforce. */ readonly lastUpdateTime?: Timestamp; /** * If set, enforces that the target document must or must not exist. */ readonly exists?: boolean; } /** * An options object that configures the behavior of `set()` calls in * `DocumentReference`, `WriteBatch` and `Transaction`. These calls can be * configured to perform granular merges instead of overwriting the target * documents in their entirety. * * @param merge Changes the behavior of a set() call to only replace the * values specified in its data argument. Fields omitted from the set() call * remain untouched. If your input sets any field to an empty map, all nested * fields are overwritten. * * @param mergeFields Changes the behavior of set() calls to only replace * the specified field paths. Any field path that is not specified is ignored * and remains untouched. If your input sets any field to an empty map, all * nested fields are overwritten. */ export type SetOptions = | { readonly merge?: boolean; } | { readonly mergeFields?: Array<string | FieldPath>; }; /** * An options object that can be used to configure the behavior of `getAll()` * calls. By providing a `fieldMask`, these calls can be configured to only * return a subset of fields. */ export interface ReadOptions { /** * Specifies the set of fields to return and reduces the amount of data * transmitted by the backend. * * Adding a field mask does not filter results. Documents do not need to * contain values for all the fields in the mask to be part of the result * set. */ readonly fieldMask?: (string | FieldPath)[]; } /** * A WriteResult wraps the write time set by the Firestore servers on `sets()`, * `updates()`, and `creates()`. */ export class WriteResult { private constructor(); /** * The write time as set by the Firestore servers. */ readonly writeTime: Timestamp; /** * Returns true if this `WriteResult` is equal to the provided one. * * @param other The `WriteResult` to compare against. * @return true if this `WriteResult` is equal to the provided one. */ isEqual(other: WriteResult): boolean; } /** * A `DocumentReference` refers to a document location in a Firestore database * and can be used to write, read, or listen to the location. The document at * the referenced location may or may not exist. A `DocumentReference` can * also be used to create a `CollectionReference` to a subcollection. */ export class DocumentReference<T = DocumentData> { private constructor(); /** The identifier of the document within its collection. */ readonly id: string; /** * The `Firestore` for the Firestore database (useful for performing * transactions, etc.). */ readonly firestore: Firestore; /** * A reference to the Collection to which this DocumentReference belongs. */ readonly parent: CollectionReference<T>; /** * A string representing the path of the referenced document (relative * to the root of the database). */ readonly path: string; /** * Gets a `CollectionReference` instance that refers to the collection at * the specified path. * * @param collectionPath A slash-separated path to a collection. * @return The `CollectionReference` instance. */ collection(collectionPath: string): CollectionReference<DocumentData>; /** * Fetches the subcollections that are direct children of this document. * * @returns A Promise that resolves with an array of CollectionReferences. */ listCollections(): Promise<Array<CollectionReference<DocumentData>>>; /** * Creates a document referred to by this `DocumentReference` with the * provided object values. The write fails if the document already exists * * @param data The object data to serialize as the document. * @throws Error If the provided input is not a valid Firestore document. * @return A Promise resolved with the write time of this create. */ create(data: WithFieldValue<T>): Promise<WriteResult>; /** * Writes to the document referred to by this `DocumentReference`. If the * document does not yet exist, it will be created. If you pass * `SetOptions`, the provided data can be merged into an existing document. * * @param data A map of the fields and values for the document. * @param options An object to configure the set behavior. * @param options.merge - If true, set() merges the values specified in its * data argument. Fields omitted from this set() call remain untouched. If * your input sets any field to an empty map, all nested fields are * overwritten. * @param options.mergeFields - If provided, set() only replaces the * specified field paths. Any field path that is not specified is ignored * and remains untouched. If your input sets any field to an empty map, all * nested fields are overwritten. * @throws Error If the provided input is not a valid Firestore document. * @return A Promise resolved with the write time of this set. */ set( data: PartialWithFieldValue<T>, options: SetOptions ): Promise<WriteResult>; set(data: WithFieldValue<T>): Promise<WriteResult>; /** * Updates fields in the document referred to by this `DocumentReference`. * The update will fail if applied to a document that does not exist. * * Nested fields can be updated by providing dot-separated field path * strings. * * @param data An object containing the fields and values with which to * update the document. * @param precondition A Precondition to enforce on this update. * @throws Error If the provided input is not valid Firestore data. * @return A Promise resolved with the write time of this update. */ update( data: UpdateData<T>, precondition?: Precondition ): Promise<WriteResult>; /** * Updates fields in the document referred to by this `DocumentReference`. * The update will fail if applied to a document that does not exist. * * Nested fields can be updated by providing dot-separated field path * strings or by providing FieldPath objects. * * A `Precondition` restricting this update can be specified as the last * argument. * * @param field The first field to update. * @param value The first value. * @param moreFieldsOrPrecondition An alternating list of field paths and * values to update, optionally followed by a `Precondition` to enforce on * this update. * @throws Error If the provided input is not valid Firestore data. * @return A Promise resolved with the write time of this update. */ update( field: string | FieldPath, value: any, ...moreFieldsOrPrecondition: any[] ): Promise<WriteResult>; /** * Deletes the document referred to by this `DocumentReference`. * * @param precondition A Precondition to enforce for this delete. * @return A Promise resolved with the write time of this delete. */ delete(precondition?: Precondition): Promise<WriteResult>; /** * Reads the document referred to by this `DocumentReference`. * * @return A Promise resolved with a DocumentSnapshot containing the * current document contents. */ get(): Promise<DocumentSnapshot<T>>; /** * Attaches a listener for DocumentSnapshot events. * * @param onNext A callback to be called every time a new `DocumentSnapshot` * is available. * @param onError A callback to be called if the listen fails or is * cancelled. No further callbacks will occur. * @return An unsubscribe function that can be called to cancel * the snapshot listener. */ onSnapshot( onNext: (snapshot: DocumentSnapshot<T>) => void, onError?: (error: Error) => void ): () => void; /** * Returns true if this `DocumentReference` is equal to the provided one. * * @param other The `DocumentReference` to compare against. * @return true if this `DocumentReference` is equal to the provided one. */ isEqual(other: DocumentReference<T>): boolean; /** * Applies a custom data converter to this DocumentReference, allowing you * to use your own custom model objects with Firestore. When you call * set(), get(), etc. on the returned DocumentReference instance, the * provided converter will convert between Firestore data and your custom * type U. * * @param converter Converts objects to and from Firestore. Passing in * `null` removes the current converter. * @return A DocumentReference<U> that uses the provided converter. */ withConverter<U>( converter: FirestoreDataConverter<U> ): DocumentReference<U>; withConverter(converter: null): DocumentReference<DocumentData>; } /** * A `DocumentSnapshot` contains data read from a document in your Firestore * database. The data can be extracted with `.data()` or `.get(<field>)` to * get a specific field. * * For a `DocumentSnapshot` that points to a non-existing document, any data * access will return 'undefined'. You can use the `exists` property to * explicitly verify a document's existence. */ export class DocumentSnapshot<T = DocumentData> { protected constructor(); /** True if the document exists. */ readonly exists: boolean; /** A `DocumentReference` to the document location. */ readonly ref: DocumentReference<T>; /** * The ID of the document for which this `DocumentSnapshot` contains data. */ readonly id: string; /** * The time the document was created. Not set for documents that don't * exist. */ readonly createTime?: Timestamp; /** * The time the document was last updated (at the time the snapshot was * generated). Not set for documents that don't exist. */ readonly updateTime?: Timestamp; /** * The time this snapshot was read. */ readonly readTime: Timestamp; /** * Retrieves all fields in the document as an Object. Returns 'undefined' if * the document doesn't exist. * * @return An Object containing all fields in the document. */ data(): T | undefined; /** * Retrieves the field specified by `fieldPath`. * * @param fieldPath The path (e.g. 'foo' or 'foo.bar') to a specific field. * @return The data at the specified field location or undefined if no such * field exists in the document. */ get(fieldPath: string | FieldPath): any; /** * Returns true if the document's data and path in this `DocumentSnapshot` * is equal to the provided one. * * @param other The `DocumentSnapshot` to compare against. * @return true if this `DocumentSnapshot` is equal to the provided one. */ isEqual(other: DocumentSnapshot<T>): boolean; } /** * A `QueryDocumentSnapshot` contains data read from a document in your * Firestore database as part of a query. The document is guaranteed to exist * and its data can be extracted with `.data()` or `.get(<field>)` to get a * specific field. * * A `QueryDocumentSnapshot` offers the same API surface as a * `DocumentSnapshot`. Since query results contain only existing documents, the * `exists` property will always be true and `data()` will never return * 'undefined'. */ export class QueryDocumentSnapshot< T = DocumentData > extends DocumentSnapshot<T> { private constructor(); /** * The time the document was created. */ readonly createTime: Timestamp; /** * The time the document was last updated (at the time the snapshot was * generated). */ readonly updateTime: Timestamp; /** * Retrieves all fields in the document as an Object. * * @override * @return An Object containing all fields in the document. */ data(): T; } /** * The direction of a `Query.orderBy()` clause is specified as 'desc' or 'asc' * (descending or ascending). */ export type OrderByDirection = 'desc' | 'asc'; /** * Filter conditions in a `Query.where()` clause are specified using the * strings '<', '<=', '==', '!=', '>=', '>', 'array-contains', 'in', 'not-in', * and 'array-contains-any'. */ export type WhereFilterOp = | '<' | '<=' | '==' | '!=' | '>=' | '>' | 'array-contains' | 'in' | 'not-in' | 'array-contains-any'; /** * A `Query` refers to a Query which you can read or listen to. You can also * construct refined `Query` objects by adding filters and ordering. */ export class Query<T = DocumentData> { protected constructor(); /** * The `Firestore` for the Firestore database (useful for performing * transactions, etc.). */ readonly firestore: Firestore; /** * Creates and returns a new Query with the additional filter that documents * must contain the specified field and that its value should satisfy the * relation constraint provided. * * This function returns a new (immutable) instance of the Query (rather * than modify the existing instance) to impose the filter. * * @param fieldPath The path to compare * @param opStr The operation string (e.g "<", "<=", "==", ">", ">="). * @param value The value for comparison * @return The created Query. */ where( fieldPath: string | FieldPath, opStr: WhereFilterOp, value: any ): Query<T>; /** * Creates and returns a new Query that's additionally sorted by the * specified field, optionally in descending order instead of ascending. * * This function returns a new (immutable) instance of the Query (rather * than modify the existing instance) to impose the order. * * @param fieldPath The field to sort by. * @param directionStr Optional direction to sort by ('asc' or 'desc'). If * not specified, order will be ascending. * @return The created Query. */ orderBy( fieldPath: string | FieldPath, directionStr?: OrderByDirection ): Query<T>; /** * Creates and returns a new Query that only returns the first matching * documents. * * This function returns a new (immutable) instance of the Query (rather * than modify the existing instance) to impose the limit. * * @param limit The maximum number of items to return. * @return The created Query. */ limit(limit: number): Query<T>; /** * Creates and returns a new Query that only returns the last matching * documents. * * You must specify at least one orderBy clause for limitToLast queries, * otherwise an exception will be thrown during execution. * * Results for limitToLast queries cannot be streamed via the `stream()` * API. * * @param limit The maximum number of items to return. * @return The created Query. */ limitToLast(limit: number): Query<T>; /** * Specifies the offset of the returned results. * * This function returns a new (immutable) instance of the Query (rather * than modify the existing instance) to impose the offset. * * @param offset The offset to apply to the Query results. * @return The created Query. */ offset(offset: number): Query<T>; /** * Creates and returns a new Query instance that applies a field mask to * the result and returns only the specified subset of fields. You can * specify a list of field paths to return, or use an empty
{'addition_count': 14, 'commit_subject': ' Add List() API (#368)', 'deletion_count': 0, 'file_extension': '.ts', 'lang': 'd', 'license': 'apache-2.0', 'repo_name': 'googleapis/nodejs-firestore'}