@firebase/firestore
Version:
The Cloud Firestore component of the Firebase JS SDK.
1,166 lines (1,165 loc) • 61.1 kB
TypeScript
/**
* Firestore Lite
*
* @remarks Firestore Lite is a small online-only SDK that allows read
* and write access to your Firestore database. All operations connect
* directly to the backend, and `onSnapshot()` APIs are not supported.
* @packageDocumentation
*/
import { FirebaseApp } from '@firebase/app-exp';
import { LogLevelString as LogLevel } from '@firebase/logger';
import { EmulatorMockTokenOptions } from '@firebase/util';
/* Excluded from this release type: AbstractUserDataWriter */
/**
* Add a new document to specified `CollectionReference` with the given data,
* assigning it a document ID automatically.
*
* The result of this write will only be reflected in document reads that occur
* after the returned Promise resolves. If the client is offline, the
* write fails. If you would like to see local modifications or buffer writes
* until the client is online, use the full Firestore SDK.
*
* @param reference - A reference to the collection to add this document to.
* @param data - An Object containing the data for the new document.
* @returns A Promise resolved with a `DocumentReference` pointing to the
* newly created document after it has been written to the backend.
*/
export declare function addDoc<T>(reference: CollectionReference<T>, data: T): Promise<DocumentReference<T>>;
/**
* Returns a special value that can be used with {@link (setDoc:1)} or {@link
* updateDoc:1} that tells the server to remove the given elements from any
* array value that already exists on the server. All instances of each element
* specified will be removed from the array. If the field being modified is not
* already an array it will be overwritten with an empty array.
*
* @param elements - The elements to remove from the array.
* @returns The `FieldValue` sentinel for use in a call to `setDoc()` or
* `updateDoc()`
*/
export declare function arrayRemove(...elements: unknown[]): FieldValue;
/**
* Returns a special value that can be used with {@link @firebase/firestore/lite#(setDoc:1)} or {@link
* @firebase/firestore/lite#(updateDoc:1)} that tells the server to union the given elements with any array
* value that already exists on the server. Each specified element that doesn't
* already exist in the array will be added to the end. If the field being
* modified is not already an array it will be overwritten with an array
* containing exactly the specified elements.
*
* @param elements - The elements to union into the array.
* @returns The `FieldValue` sentinel for use in a call to `setDoc()` or
* `updateDoc()`.
*/
export declare function arrayUnion(...elements: unknown[]): FieldValue;
/**
* An immutable object representing an array of bytes.
*/
export declare class Bytes {
private constructor();
/**
* Creates a new `Bytes` object from the given Base64 string, converting it to
* bytes.
*
* @param base64 - The Base64 string used to create the `Bytes` object.
*/
static fromBase64String(base64: string): Bytes;
/**
* Creates a new `Bytes` object from the given Uint8Array.
*
* @param array - The Uint8Array used to create the `Bytes` object.
*/
static fromUint8Array(array: Uint8Array): Bytes;
/**
* Returns the underlying bytes as a Base64-encoded string.
*
* @returns The Base64-encoded string created from the `Bytes` object.
*/
toBase64(): string;
/**
* Returns the underlying bytes in a new `Uint8Array`.
*
* @returns The Uint8Array created from the `Bytes` object.
*/
toUint8Array(): Uint8Array;
/**
* Returns a string representation of the `Bytes` object.
*
* @returns A string representation of the `Bytes` object.
*/
toString(): string;
/**
* Returns true if this `Bytes` object is equal to the provided one.
*
* @param other - The `Bytes` object to compare against.
* @returns true if this `Bytes` object is equal to the provided one.
*/
isEqual(other: Bytes): boolean;
}
/**
* Gets a `CollectionReference` instance that refers to the collection at
* the specified absolute path.
*
* @param firestore - A reference to the root Firestore instance.
* @param path - A slash-separated path to a collection.
* @param pathSegments - Additional path segments to apply relative to the first
* argument.
* @throws If the final path has an even number of segments and does not point
* to a collection.
* @returns The `CollectionReference` instance.
*/
export declare function collection(firestore: FirebaseFirestore, path: string, ...pathSegments: string[]): CollectionReference<DocumentData>;
/**
* Gets a `CollectionReference` instance that refers to a subcollection of
* `reference` at the the specified relative path.
*
* @param reference - A reference to a collection.
* @param path - A slash-separated path to a collection.
* @param pathSegments - Additional path segments to apply relative to the first
* argument.
* @throws If the final path has an even number of segments and does not point
* to a collection.
* @returns The `CollectionReference` instance.
*/
export declare function collection(reference: CollectionReference<unknown>, path: string, ...pathSegments: string[]): CollectionReference<DocumentData>;
/**
* Gets a `CollectionReference` instance that refers to a subcollection of
* `reference` at the the specified relative path.
*
* @param reference - A reference to a Firestore document.
* @param path - A slash-separated path to a collection.
* @param pathSegments - Additional path segments that will be applied relative
* to the first argument.
* @throws If the final path has an even number of segments and does not point
* to a collection.
* @returns The `CollectionReference` instance.
*/
export declare function collection(reference: DocumentReference, path: string, ...pathSegments: string[]): CollectionReference<DocumentData>;
/**
* Creates and returns a new `Query` instance that includes all documents in the
* database that are contained in a collection or subcollection with the
* given `collectionId`.
*
* @param firestore - A reference to the root Firestore instance.
* @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.
* @returns The created `Query`.
*/
export declare function collectionGroup(firestore: FirebaseFirestore, collectionId: string): Query<DocumentData>;
/**
* A `CollectionReference` object can be used for adding documents, getting
* document references, and querying for documents (using {@link query}).
*/
export declare class CollectionReference<T = DocumentData> extends Query<T> {
/** The type of this Firestore reference. */
readonly type = "collection";
private constructor();
/** The collection's identifier. */
get id(): string;
/**
* A string representing the path of the referenced collection (relative
* to the root of the database).
*/
get path(): string;
/**
* A reference to the containing `DocumentReference` if this is a
* subcollection. If this isn't a subcollection, the reference is null.
*/
get parent(): DocumentReference<DocumentData> | null;
/**
* Applies a custom data converter to this CollectionReference, allowing you
* to use your own custom model objects with Firestore. When you call {@link
* addDoc} with the returned `CollectionReference` instance, the provided
* converter will convert between Firestore data and your custom type `U`.
*
* @param converter - Converts objects to and from Firestore.
* @returns A `CollectionReference<U>` that uses the provided converter.
*/
withConverter<U>(converter: FirestoreDataConverter<U>): CollectionReference<U>;
/**
* Removes the current converter.
*
* @param converter - `null` removes the current converter.
* @returns A `CollectionReference<DocumentData>` that does not use a
* converter.
*/
withConverter(converter: null): CollectionReference<DocumentData>;
}
/**
* Deletes the document referred to by the specified `DocumentReference`.
*
* The deletion will only be reflected in document reads that occur after the
* returned Promise resolves. If the client is offline, the
* delete fails. If you would like to see local modifications or buffer writes
* until the client is online, use the full Firestore SDK.
*
* @param reference - A reference to the document to delete.
* @returns A Promise resolved once the document has been successfully
* deleted from the backend.
*/
export declare function deleteDoc(reference: DocumentReference<unknown>): Promise<void>;
/**
* Returns a sentinel for use with {@link @firebase/firestore/lite#(updateDoc:1)} or
* {@link @firebase/firestore/lite#(setDoc:1)} with `{merge: true}` to mark a field for deletion.
*/
export declare function deleteField(): FieldValue;
/**
* Gets a `DocumentReference` instance that refers to the document at the
* specified abosulute path.
*
* @param firestore - A reference to the root Firestore instance.
* @param path - A slash-separated path to a document.
* @param pathSegments - Additional path segments that will be applied relative
* to the first argument.
* @throws If the final path has an odd number of segments and does not point to
* a document.
* @returns The `DocumentReference` instance.
*/
export declare function doc(firestore: FirebaseFirestore, path: string, ...pathSegments: string[]): DocumentReference<DocumentData>;
/**
* Gets a `DocumentReference` instance that refers to a document within
* `reference` at the specified relative path. If no path is specified, an
* automatically-generated unique ID will be used for the returned
* `DocumentReference`.
*
* @param reference - A reference to a collection.
* @param path - A slash-separated path to a document. Has to be omitted to use
* auto-genrated IDs.
* @param pathSegments - Additional path segments that will be applied relative
* to the first argument.
* @throws If the final path has an odd number of segments and does not point to
* a document.
* @returns The `DocumentReference` instance.
*/
export declare function doc<T>(reference: CollectionReference<T>, path?: string, ...pathSegments: string[]): DocumentReference<T>;
/**
* Gets a `DocumentReference` instance that refers to a document within
* `reference` at the specified relative path.
*
* @param reference - A reference to a Firestore document.
* @param path - A slash-separated path to a document.
* @param pathSegments - Additional path segments that will be applied relative
* to the first argument.
* @throws If the final path has an odd number of segments and does not point to
* a document.
* @returns The `DocumentReference` instance.
*/
export declare function doc(reference: DocumentReference<unknown>, path: string, ...pathSegments: string[]): DocumentReference<DocumentData>;
/**
* Document data (for use with {@link @firebase/firestore/lite#(setDoc:1)}) consists of fields mapped to
* values.
*/
export declare interface DocumentData {
/** A mapping between a field and its value. */
[field: string]: any;
}
/**
* Returns a special sentinel `FieldPath` to refer to the ID of a document.
* It can be used in queries to sort or filter by the document ID.
*/
export declare function documentId(): FieldPath;
/**
* 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.
*/
export declare class DocumentReference<T = DocumentData> {
/**
* If provided, the `FirestoreDataConverter` associated with this instance.
*/
readonly converter: FirestoreDataConverter<T> | null;
/** The type of this Firestore reference. */
readonly type = "document";
/**
* The {@link FirebaseFirestore} the document is in.
* This is useful for performing transactions, for example.
*/
readonly firestore: FirebaseFirestore;
private constructor();
/**
* The document's identifier within its collection.
*/
get id(): string;
/**
* A string representing the path of the referenced document (relative
* to the root of the database).
*/
get path(): string;
/**
* The collection this `DocumentReference` belongs to.
*/
get parent(): CollectionReference<T>;
/**
* Applies a custom data converter to this `DocumentReference`, allowing you
* to use your own custom model objects with Firestore. When you call {@link
* @firebase/firestore/lite#(setDoc:1)}, {@link @firebase/firestore/lite#getDoc}, etc. with 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.
* @returns A `DocumentReference<U>` that uses the provided converter.
*/
withConverter<U>(converter: FirestoreDataConverter<U>): DocumentReference<U>;
/**
* Removes the current converter.
*
* @param converter - `null` removes the current converter.
* @returns A `DocumentReference<DocumentData>` that does not use a converter.
*/
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()` method to
* explicitly verify a document's existence.
*/
export declare class DocumentSnapshot<T = DocumentData> {
protected constructor();
/** Property of the `DocumentSnapshot` that provides the document's ID. */
get id(): string;
/**
* The `DocumentReference` for the document included in the `DocumentSnapshot`.
*/
get ref(): DocumentReference<T>;
/**
* Signals whether or not the document at the snapshot's location exists.
*
* @returns true if the document exists.
*/
exists(): this is QueryDocumentSnapshot<T>;
/**
* Retrieves all fields in the document as an `Object`. Returns `undefined` if
* the document doesn't exist.
*
* @returns An `Object` containing all fields in the document or `undefined`
* if the document doesn't exist.
*/
data(): T | undefined;
/**
* Retrieves the field specified by `fieldPath`. Returns `undefined` if the
* document or field doesn't exist.
*
* @param fieldPath - The path (for example 'foo' or 'foo.bar') to a specific
* field.
* @returns The data at the specified field location or undefined if no such
* field exists in the document.
*/
get(fieldPath: string | FieldPath): any;
}
/**
* Creates a `QueryConstraint` that modifies the result set to end at the
* provided document (inclusive). The end position is relative to the order of
* the query. The document must contain all of the fields provided in the
* orderBy of the query.
*
* @param snapshot - The snapshot of the document to end at.
* @returns A `QueryConstraint` to pass to `query()`
*/
export declare function endAt(snapshot: DocumentSnapshot<unknown>): QueryConstraint;
/**
* Creates a `QueryConstraint` that modifies the result set to end at the
* provided fields relative to the order of the query. The order of the field
* values must match the order of the order by clauses of the query.
*
* @param fieldValues - The field values to end this query at, in order
* of the query's order by.
* @returns A `QueryConstraint` to pass to `query()`
*/
export declare function endAt(...fieldValues: unknown[]): QueryConstraint;
/**
* Creates a `QueryConstraint` that modifies the result set to end before the
* provided document (exclusive). The end position is relative to the order of
* the query. The document must contain all of the fields provided in the
* orderBy of the query.
*
* @param snapshot - The snapshot of the document to end before.
* @returns A `QueryConstraint` to pass to `query()`
*/
export declare function endBefore(snapshot: DocumentSnapshot<unknown>): QueryConstraint;
/**
* Creates a `QueryConstraint` that modifies the result set to end before the
* provided fields relative to the order of the query. The order of the field
* values must match the order of the order by clauses of the query.
*
* @param fieldValues - The field values to end this query before, in order
* of the query's order by.
* @returns A `QueryConstraint` to pass to `query()`
*/
export declare function endBefore(...fieldValues: unknown[]): QueryConstraint;
/**
* A `FieldPath` refers to a field in a document. The path may consist of a
* single field name (referring to a top-level field in the document), or a
* list of field names (referring to a nested field in the document).
*
* Create a `FieldPath` by providing field names. If more than one field
* name is provided, the path will point to a nested field in a document.
*/
export declare class FieldPath {
/**
* Creates a FieldPath from the provided field names. If more than one field
* name is provided, the path will point to a nested field in a document.
*
* @param fieldNames - A list of field names.
*/
constructor(...fieldNames: string[]);
/**
* Returns true if this `FieldPath` is equal to the provided one.
*
* @param other - The `FieldPath` to compare against.
* @returns true if this `FieldPath` is equal to the provided one.
*/
isEqual(other: FieldPath): boolean;
}
/**
* Sentinel values that can be used when writing document fields with `set()`
* or `update()`.
*/
export declare abstract class FieldValue {
private constructor();
/** Compares `FieldValue`s for equality. */
abstract isEqual(other: FieldValue): boolean;
}
/**
* The Cloud Firestore service interface.
*
* Do not call this constructor directly. Instead, use {@link getFirestore}.
*/
export declare class FirebaseFirestore {
type: 'firestore-lite' | 'firestore';
private constructor();
/**
* The {@link @firebase/app#FirebaseApp} associated with this `Firestore` service
* instance.
*/
get app(): FirebaseApp;
/** Returns a JSON-serializable representation of this Firestore instance. */
toJSON(): object;
}
/* Excluded from this release type: _FirebaseService */
/**
* 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
* ```typescript
* class Post {
* constructor(readonly title: string, readonly author: string) {}
*
* toString(): string {
* return this.title + ', by ' + this.author;
* }
* }
*
* const postConverter = {
* toFirestore(post: Post): firebase.firestore.DocumentData {
* return {title: post.title, author: post.author};
* },
* fromFirestore(snapshot: firebase.firestore.QueryDocumentSnapshot): Post {
* const data = snapshot.data(options)!;
* return new Post(data.title, data.author);
* }
* };
*
* const postSnap = await firebase.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 declare 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). Used with {@link @firebase/firestore/lite#(setDoc:1)}, {@link @firebase/firestore/lite#(WriteBatch.set:1)}
* and {@link @firebase/firestore/lite#(Transaction.set:1)}.
*/
toFirestore(modelObject: 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). Used with {@link @firebase/firestore/lite#(setDoc:1)}, {@link @firebase/firestore/lite#(WriteBatch.set:1)}
* and {@link @firebase/firestore/lite#(Transaction.set:1)} with `merge:true` or `mergeFields`.
*/
toFirestore(modelObject: Partial<T>, options: SetOptions): DocumentData;
/**
* Called by the Firestore SDK to convert Firestore data into an object of
* type T. You can access your data by calling: `snapshot.data()`.
*
* @param snapshot - A `QueryDocumentSnapshot` containing your data and
* metadata.
*/
fromFirestore(snapshot: QueryDocumentSnapshot<DocumentData>): T;
}
/** An error returned by a Firestore operation. */
export declare class FirestoreError extends Error {
/**
* The backend error code associated with this error.
*/
readonly code: FirestoreErrorCode;
/**
* A custom error description.
*/
readonly message: string;
/** The custom name for all FirestoreErrors. */
readonly name: string;
/** The stack of the error. */
readonly stack?: string;
private constructor();
}
/**
* @license
* Copyright 2017 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.
*/
/**
* The set of Firestore status codes. The codes are the same at the ones
* exposed by gRPC here:
* https://github.com/grpc/grpc/blob/master/doc/statuscodes.md
*
* Possible values:
* - 'cancelled': The operation was cancelled (typically by the caller).
* - 'unknown': Unknown error or an error from a different error domain.
* - 'invalid-argument': Client specified an invalid argument. Note that this
* differs from 'failed-precondition'. 'invalid-argument' indicates
* arguments that are problematic regardless of the state of the system
* (e.g. an invalid field name).
* - 'deadline-exceeded': Deadline expired before operation could complete.
* For operations that change the state of the system, this error may be
* returned even if the operation has completed successfully. For example,
* a successful response from a server could have been delayed long enough
* for the deadline to expire.
* - 'not-found': Some requested document was not found.
* - 'already-exists': Some document that we attempted to create already
* exists.
* - 'permission-denied': The caller does not have permission to execute the
* specified operation.
* - 'resource-exhausted': Some resource has been exhausted, perhaps a
* per-user quota, or perhaps the entire file system is out of space.
* - 'failed-precondition': Operation was rejected because the system is not
* in a state required for the operation's execution.
* - 'aborted': The operation was aborted, typically due to a concurrency
* issue like transaction aborts, etc.
* - 'out-of-range': Operation was attempted past the valid range.
* - 'unimplemented': Operation is not implemented or not supported/enabled.
* - 'internal': Internal errors. Means some invariants expected by
* underlying system has been broken. If you see one of these errors,
* something is very broken.
* - 'unavailable': The service is currently unavailable. This is most likely
* a transient condition and may be corrected by retrying with a backoff.
* - 'data-loss': Unrecoverable data loss or corruption.
* - 'unauthenticated': The request does not have valid authentication
* credentials for the operation.
*/
export declare type FirestoreErrorCode = 'cancelled' | 'unknown' | 'invalid-argument' | 'deadline-exceeded' | 'not-found' | 'already-exists' | 'permission-denied' | 'resource-exhausted' | 'failed-precondition' | 'aborted' | 'out-of-range' | 'unimplemented' | 'internal' | 'unavailable' | 'data-loss' | 'unauthenticated';
/**
* @license
* Copyright 2017 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.
*/
/**
* An immutable object representing a geographic location in Firestore. The
* location 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 declare 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);
/**
* The latitude of this `GeoPoint` instance.
*/
get latitude(): number;
/**
* The longitude of this `GeoPoint` instance.
*/
get longitude(): number;
/**
* Returns true if this `GeoPoint` is equal to the provided one.
*
* @param other - The `GeoPoint` to compare against.
* @returns true if this `GeoPoint` is equal to the provided one.
*/
isEqual(other: GeoPoint): boolean;
/** Returns a JSON-serializable representation of this GeoPoint. */
toJSON(): {
latitude: number;
longitude: number;
};
}
/**
* Reads the document referred to by the specified document reference.
*
* All documents are directly fetched from the server, even if the document was
* previously read or modified. Recent modifications are only reflected in the
* retrieved `DocumentSnapshot` if they have already been applied by the
* backend. If the client is offline, the read fails. If you like to use
* caching or see local modifications, please use the full Firestore SDK.
*
* @param reference - The reference of the document to fetch.
* @returns A Promise resolved with a `DocumentSnapshot` containing the current
* document contents.
*/
export declare function getDoc<T>(reference: DocumentReference<T>): Promise<DocumentSnapshot<T>>;
/**
* Executes the query and returns the results as a {@link QuerySnapshot}.
*
* All queries are executed directly by the server, even if the the query was
* previously executed. Recent modifications are only reflected in the retrieved
* results if they have already been applied by the backend. If the client is
* offline, the operation fails. To see previously cached result and local
* modifications, use the full Firestore SDK.
*
* @param query - The `Query` to execute.
* @returns A Promise that will be resolved with the results of the query.
*/
export declare function getDocs<T>(query: Query<T>): Promise<QuerySnapshot<T>>;
/**
* Returns the existing instance of Firestore that is associated with the
* 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 Firestore
* instance is associated with.
* @returns The `Firestore` instance of the provided app.
*/
export declare function getFirestore(app?: FirebaseApp): FirebaseFirestore;
/**
* Returns a special value that can be used with {@link @firebase/firestore/lite#(setDoc:1)} or {@link
* @firebase/firestore/lite#(updateDoc:1)} that tells the server to increment the field's current value by
* the given value.
*
* If either the operand or the current field value uses floating point
* precision, all arithmetic follows IEEE 754 semantics. If both values are
* integers, values outside of JavaScript's safe number range
* (`Number.MIN_SAFE_INTEGER` to `Number.MAX_SAFE_INTEGER`) are also subject to
* precision loss. Furthermore, once processed by the Firestore backend, all
* integer operations are capped between -2^63 and 2^63-1.
*
* If the current field value is not of type `number`, or if the field does not
* yet exist, the transformation sets the field to the given value.
*
* @param n - The value to increment by.
* @returns The `FieldValue` sentinel for use in a call to `setDoc()` or
* `updateDoc()`
*/
export declare function increment(n: number): FieldValue;
/**
* Initializes a new instance of Cloud Firestore with the provided settings.
* Can only be called before any other functions, including
* {@link getFirestore}. If the custom settings are empty, this function is
* equivalent to calling {@link getFirestore}.
*
* @param app - The {@link @firebase/app#FirebaseApp} with which the `Firestore` instance will
* be associated.
* @param settings - A settings object to configure the `Firestore` instance.
* @returns A newly initialized Firestore instance.
*/
export declare function initializeFirestore(app: FirebaseApp, settings: Settings): FirebaseFirestore;
/**
* Creates a `QueryConstraint` that only returns the first matching documents.
*
* @param limit - The maximum number of items to return.
* @returns The created `Query`.
*/
export declare function limit(limit: number): QueryConstraint;
/**
* Creates a `QueryConstraint` 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.
*
* @param limit - The maximum number of items to return.
* @returns The created `Query`.
*/
export declare function limitToLast(limit: number): QueryConstraint;
export { LogLevel };
/**
* Creates a `QueryConstraint` that sorts the query result by the
* specified field, optionally in descending order instead of ascending.
*
* @param fieldPath - The field to sort by.
* @param directionStr - Optional direction to sort by ('asc' or 'desc'). If
* not specified, order will be ascending.
* @returns The created `Query`.
*/
export declare function orderBy(fieldPath: string | FieldPath, directionStr?: OrderByDirection): QueryConstraint;
/**
* The direction of a {@link orderBy} clause is specified as 'desc' or 'asc'
* (descending or ascending).
*/
export declare type OrderByDirection = 'desc' | 'asc';
/**
* 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 declare class Query<T = DocumentData> {
/**
* If provided, the `FirestoreDataConverter` associated with this instance.
*/
readonly converter: FirestoreDataConverter<T> | null;
/** The type of this Firestore reference. */
readonly type: 'query' | 'collection';
/**
* The `FirebaseFirestore` for the Firestore database (useful for performing
* transactions, etc.).
*/
readonly firestore: FirebaseFirestore;
protected constructor();
/**
* Removes the current converter.
*
* @param converter - `null` removes the current converter.
* @returns A `Query<DocumentData>` that does not use a converter.
*/
withConverter(converter: null): Query<DocumentData>;
/**
* Applies a custom data converter to this query, allowing you to use your own
* custom model objects with Firestore. When you call {@link getDocs} with
* the returned query, the provided converter will convert between Firestore
* data and your custom type `U`.
*
* @param converter - Converts objects to and from Firestore.
* @returns A `Query<U>` that uses the provided converter.
*/
withConverter<U>(converter: FirestoreDataConverter<U>): Query<U>;
}
/**
* Creates a new immutable instance of `Query` that is extended to also include
* additional query constraints.
*
* @param query - The Query instance to use as a base for the new constraints.
* @param queryConstraints - The list of `QueryConstraint`s to apply.
* @throws if any of the provided query constraints cannot be combined with the
* existing or new constraints.
*/
export declare function query<T>(query: Query<T>, ...queryConstraints: QueryConstraint[]): Query<T>;
/**
* A `QueryConstraint` is used to narrow the set of documents returned by a
* Firestore query. `QueryConstraint`s are created by invoking {@link where},
* {@link orderBy}, {@link (startAt:1)}, {@link (startAfter:1)}, {@link
* endBefore:1}, {@link (endAt:1)}, {@link limit} or {@link limitToLast} and
* can then be passed to {@link query} to create a new query instance that
* also contains this `QueryConstraint`.
*/
export declare abstract class QueryConstraint {
/** The type of this query constraints */
abstract readonly type: QueryConstraintType;
}
/** Describes the different query constraints available in this SDK. */
export declare type QueryConstraintType = 'where' | 'orderBy' | 'limit' | 'limitToLast' | 'startAt' | 'startAfter' | 'endAt' | 'endBefore';
/**
* 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 declare class QueryDocumentSnapshot<T = DocumentData> extends DocumentSnapshot<T> {
/**
* Retrieves all fields in the document as an `Object`.
*
* @override
* @returns An `Object` containing all fields in the document.
*/
data(): T;
}
/**
* Returns true if the provided queries point to the same collection and apply
* the same constraints.
*
* @param left - A `Query` to compare.
* @param right - A `Query` to compare.
* @returns true if the references point to the same location in the same
* Firestore database.
*/
export declare function queryEqual<T>(left: Query<T>, right: Query<T>): boolean;
/**
* A `QuerySnapshot` contains zero or more `DocumentSnapshot` objects
* representing the results of a query. The documents can be accessed as an
* array via the `docs` property or enumerated using the `forEach` method. The
* number of documents can be determined via the `empty` and `size`
* properties.
*/
export declare class QuerySnapshot<T = DocumentData> {
/**
* The query on which you called {@link getDocs} in order to get this
* `QuerySnapshot`.
*/
readonly query: Query<T>;
private constructor();
/** An array of all the documents in the `QuerySnapshot`. */
get docs(): Array<QueryDocumentSnapshot<T>>;
/** The number of documents in the `QuerySnapshot`. */
get size(): number;
/** True if there are no documents in the `QuerySnapshot`. */
get empty(): boolean;
/**
* Enumerates all of the documents in the `QuerySnapshot`.
*
* @param callback - A callback to be called with a `QueryDocumentSnapshot` for
* each document in the snapshot.
* @param thisArg - The `this` binding for the callback.
*/
forEach(callback: (result: QueryDocumentSnapshot<T>) => void, thisArg?: unknown): void;
}
/**
* Returns true if the provided references are equal.
*
* @param left - A reference to compare.
* @param right - A reference to compare.
* @returns true if the references point to the same location in the same
* Firestore database.
*/
export declare function refEqual<T>(left: DocumentReference<T> | CollectionReference<T>, right: DocumentReference<T> | CollectionReference<T>): boolean;
/**
* Executes the given `updateFunction` and then attempts to commit the changes
* applied within the transaction. If any document read within the transaction
* has changed, Cloud Firestore retries the `updateFunction`. If it fails to
* commit after 5 attempts, the transaction fails.
*
* The maximum number of writes allowed in a single transaction is 500.
*
* @param firestore - A reference to the Firestore database to run this
* transaction against.
* @param updateFunction - The function to execute within the transaction
* context.
* @returns If the transaction completed successfully or was explicitly aborted
* (the `updateFunction` returned a failed promise), the promise returned by the
* `updateFunction `is returned here. Otherwise, if the transaction failed, a
* rejected promise with the corresponding failure error is returned.
*/
export declare function runTransaction<T>(firestore: FirebaseFirestore, updateFunction: (transaction: Transaction) => Promise<T>): Promise<T>;
/**
* Returns a sentinel used with {@link @firebase/firestore/lite#(setDoc:1)} or {@link @firebase/firestore/lite#(updateDoc:1)} to
* include a server-generated timestamp in the written data.
*/
export declare function serverTimestamp(): FieldValue;
/**
* Writes to the document referred to by the specified `DocumentReference`. If
* the document does not yet exist, it will be created.
*
* The result of this write will only be reflected in document reads that occur
* after the returned Promise resolves. If the client is offline, the
* write fails. If you would like to see local modifications or buffer writes
* until the client is online, use the full Firestore SDK.
*
* @param reference - A reference to the document to write.
* @param data - A map of the fields and values for the document.
* @returns A Promise resolved once the data has been successfully written
* to the backend.
*/
export declare function setDoc<T>(reference: DocumentReference<T>, data: T): Promise<void>;
/**
* Writes to the document referred to by the specified `DocumentReference`. If
* the document does not yet exist, it will be created. If you provide `merge`
* or `mergeFields`, the provided data can be merged into an existing document.
*
* The result of this write will only be reflected in document reads that occur
* after the returned Promise resolves. If the client is offline, the
* write fails. If you would like to see local modifications or buffer writes
* until the client is online, use the full Firestore SDK.
*
* @param reference - A reference to the document to write.
* @param data - A map of the fields and values for the document.
* @param options - An object to configure the set behavior.
* @returns A Promise resolved once the data has been successfully written
* to the backend.
*/
export declare function setDoc<T>(reference: DocumentReference<T>, data: Partial<T>, options: SetOptions): Promise<void>;
/**
* Sets the verbosity of Cloud Firestore logs (debug, error, or silent).
*
* @param logLevel - The verbosity you set for activity and error logging. Can
* be any of the following values:
*
* <ul>
* <li>`debug` for the most verbose logging level, primarily for
* debugging.</li>
* <li>`error` to log errors only.</li>
* <li><code>`silent` to turn off logging.</li>
* </ul>
*/
export declare function setLogLevel(logLevel: LogLevel): void;
/**
* An options object that configures the behavior of {@link @firebase/firestore/lite#(setDoc:1)}, {@link
* @firebase/firestore/lite#(WriteBatch.set:1)} and {@link @firebase/firestore/lite#(Transaction.set:1)} calls. These calls can be
* configured to perform granular merges instead of overwriting the target
* documents in their entirety by providing a `SetOptions` with `merge: true`.
*
* @param merge - Changes the behavior of a `setDoc()` call to only replace the
* values specified in its data argument. Fields omitted from the `setDoc()`
* call remain untouched.
* @param mergeFields - Changes the behavior of `setDoc()` calls to only replace
* the specified field paths. Any field path that is not specified is ignored
* and remains untouched.
*/
export declare type SetOptions = {
readonly merge?: boolean;
} | {
readonly mergeFields?: Array<string | FieldPath>;
};
/**
* Specifies custom configurations for your Cloud Firestore instance.
* You must set these before invoking any other methods.
*/
export declare interface Settings {
/** The hostname to connect to. */
host?: string;
/** Whether to use SSL when connecting. */
ssl?: 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 to `false` or omitted, the SDK
* throws an exception when it encounters properties of type `undefined`.
*/
ignoreUndefinedProperties?: boolean;
}
/**
* Returns true if the provided snapshots are equal.
*
* @param left - A snapshot to compare.
* @param right - A snapshot to compare.
* @returns true if the snapshots are equal.
*/
export declare function snapshotEqual<T>(left: DocumentSnapshot<T> | QuerySnapshot<T>, right: DocumentSnapshot<T> | QuerySnapshot<T>): boolean;
/**
* Creates a `QueryConstraint` that modifies the result set to start after the
* provided document (exclusive). The starting position is relative to the order
* of the query. The document must contain all of the fields provided in the
* orderBy of the query.
*
* @param snapshot - The snapshot of the document to start after.
* @returns A `QueryConstraint` to pass to `query()`
*/
export declare function startAfter(snapshot: DocumentSnapshot<unknown>): QueryConstraint;
/**
* Creates a `QueryConstraint` that modifies the result set to start after the
* provided fields relative to the order of the query. The order of the field
* values must match the order of the order by clauses of the query.
*
* @param fieldValues - The field values to start this query after, in order
* of the query's order by.
* @returns A `QueryConstraint` to pass to `query()`
*/
export declare function startAfter(...fieldValues: unknown[]): QueryConstraint;
/**
* Creates a `QueryConstraint` that modifies the result set to start at the
* provided document (inclusive). The starting position is relative to the order
* of the query. The document must contain all of the fields provided in the
* `orderBy` of this query.
*
* @param snapshot - The snapshot of the document to start at.
* @returns A `QueryConstraint` to pass to `query()`.
*/
export declare function startAt(snapshot: DocumentSnapshot<unknown>): QueryConstraint;
/**
* Creates a `QueryConstraint` that modifies the result set to start at the
* provided fields relative to the order of the query. The order of the field
* values must match the order of the order by clauses of the query.
*
* @param fieldValues - The field values to start this query at, in order
* of the query's order by.
* @returns A `QueryConstraint` to pass to `query()`.
*/
export declare function startAt(...fieldValues: unknown[]): QueryConstraint;
/**
* Terminates the provided Firestore instance.
*
* After calling `terminate()` only the `clearIndexedDbPersistence()` functions
* may be used. Any other function will throw a `FirestoreError`. Termination
* does not cancel any pending writes, and any promises that are awaiting a
* response from the server will not be resolved.
*
* To restart after termination, create a new instance of FirebaseFirestore with
* {@link getFirestore}.
*
* Note: Under normal circumstances, calling `terminate()` is not required. This
* function is useful only when you want to force this instance to release all of
* its resources or in combination with {@link clearIndexedDbPersistence} to
* ensure that all local state is destroyed between test runs.
*
* @param firestore - The Firestore instance to terminate.
* @returns A promise that is resolved when the instance has been successfully
* terminated.
*/
export declare function terminate(firestore: FirebaseFirestore): Promise<void>;
/**
* @license
* Copyright 2017 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.
*/
/**
* A `Timestamp` represents a point in time independent of any time zone or
* calendar, represented as seconds and fractions of seconds at nanosecond
* resolution in UTC Epoch time.
*
* It is encoded using the Proleptic Gregorian Calendar which extends the
* Gregorian calendar backwards to year one. It is encoded assuming all minutes
* are 60 seconds long, i.e. leap seconds are "smeared" so that no leap second
* table is needed for interpretation. Range is from 0001-01-01T00:00:00Z to
* 9999-12-31T23:59:59.999999999Z.
*
* For examples and further specifications, refer to the
* {@link https://github.com/google/protobuf/blob/master/src/google/protobuf/timestamp.proto | Timestamp definition}.
*/
export declare class Timestamp {
/**
* The number of seconds of UTC time since Unix epoch 1970-01-01T00:00:00Z.
*/
readonly seconds: number;
/**
* The fractions of a second at nanosecond resolution.*
*/
readonly nanoseconds: number;
/**
* Creates a new timestamp with the current date, with millisecond precision.
*
* @returns a new timestamp representing the current date.
*/
static now(): Timestamp;
/**
* Creates a new timestamp from the given date.
*
* @param date - The date to initialize the `Timestamp` from.
* @returns A new `Timestamp` representing the same point in time as the given
* date.
*/
static fromDate(date: Date): Timestamp;
/**
* Creates a new timestamp from the given number of milliseconds.
*
* @param milliseconds - Number of milliseconds since Unix epoch
* 1970-01-01T00:00:00Z.
* @returns A new `Timestamp` representing the same point in time as the given
* number of milliseconds.
*/
static fromMillis(milliseconds: number): Timestamp;
/**
* Creates a new timestamp.
*
* @param seconds - The number of seconds of UTC time since Unix epoch
* 1970-01-01T00:00:00Z. Must be from 0001-01-01T00:00:00Z to
* 9999-12-31T23:59:59Z inclusive.
* @param nanoseconds - The non-negative fractions of a second at nanosecond
* resolution. Negative second values with fractions must still have
* non-negative nanoseconds values that count forward in time. Must be
* from 0 to 999,999,999 inclusive.
*/
constructor(
/**
* The number of seconds of UTC time since Unix epoch 1970-01-01T00:00:00Z.
*/
seconds: number,
/**
* The fractions of a second at nanosecond resolution.*
*/
nanoseconds: number);
/**
* Converts a `Timestamp` to a JavaScript `Date` object. This conversion
* causes a loss of precision since `Date` objects only support millisecond
* precision.
*
* @returns JavaScript `Date` object representing the same point in time as
* this `Timestamp`, with millisecond precision.
*/
toDate(): Date;
/**
* Converts a `Timestamp` to a numeric timestamp (in milliseconds since
* epoch). This operation causes a loss of precision.
*
* @returns The point in time corresponding to this timestamp, represented as
* the number of milliseconds since Unix epoch 1970-01-01T00:00:00Z.
*/
toMillis(): number;
/**
* Returns true if this `Timestamp` is equal to the provided one.
*
* @param other - The `Timestamp` to compare against.
* @returns true if this `Timestamp` is equal to the provided one.
*/
isEqual(other: Timestamp): boolean;
/** Returns a textual representation of this Timestamp. */
toString(): string;
/** Returns a JSON-serializable representation of this Timestamp. */
toJSON(): {
seconds: number;
nanoseconds: number;
};
/**
* Converts this object to a primitive string, which allows Timestamp objects
* to be compared using the `>`, `<=`, `>=` and `>` operators.
*/
valueOf(): string;
}
/**
* 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
* {@link runTransaction}.
*/
export declare class Transaction {
private constructor();
/**
* Reads the document referenced by the provided {@link DocumentReference}.
*
* @param documentRef - A reference to the document to be read.
* @returns A `DocumentSnapshot` with the read data.
*/
g