@firebase/firestore

/** * @license * 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. */ import { Query as InternalQuery } from '../core/query'; import { DocumentKey } from '../model/document_key'; import { ResourcePath } from '../model/path'; import { FirebaseFirestore } from './database'; import { FieldPath } from './field_path'; import { FirestoreDataConverter } from './snapshot'; /** * Document data (for use with {@link @firebase/firestore/lite#(setDoc:1)}) consists of fields mapped to * values. */ export interface DocumentData { /** A mapping between a field and its value. */ [field: string]: any; } /** * Update data (for use with {@link @firebase/firestore/lite#(updateDoc:1)}) consists of field paths (e.g. * 'foo' or 'foo.baz') mapped to values. Fields that contain dots reference * nested fields within the document. */ export interface UpdateData { /** A mapping between a dot-separated field path and its value. */ [fieldPath: string]: any; } /** * 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>; }; /** * 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; readonly _key: DocumentKey; /** 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; /** @hideconstructor */ constructor(firestore: FirebaseFirestore, /** * If provided, the `FirestoreDataConverter` associated with this instance. */ converter: FirestoreDataConverter<T> | null, _key: DocumentKey); get _path(): ResourcePath; /** * 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` that uses the provided converter. */ withConverter(converter: FirestoreDataConverter): DocumentReference; /** * 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 `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; readonly _query: InternalQuery; /** The type of this Firestore reference. */ readonly type: 'query' | 'collection'; /** * The `FirebaseFirestore` for the Firestore database (useful for performing * transactions, etc.). */ readonly firestore: FirebaseFirestore; /** @hideconstructor protected */ constructor(firestore: FirebaseFirestore, /** * If provided, the `FirestoreDataConverter` associated with this instance. */ converter: FirestoreDataConverter<T> | null, _query: InternalQuery); /** * 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` that uses the provided converter. */ withConverter(converter: FirestoreDataConverter): Query; } /** * 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> { readonly _path: ResourcePath; /** The type of this Firestore reference. */ readonly type = "collection"; /** @hideconstructor */ constructor(firestore: FirebaseFirestore, converter: FirestoreDataConverter<T> | null, _path: ResourcePath); /** 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` that uses the provided converter. */ withConverter(converter: FirestoreDataConverter): CollectionReference; /** * 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>; } /** * 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>; /** * 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>; /** * 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; /** * 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;