@firebase/firestore
Version:
The Cloud Firestore component of the Firebase JS SDK.
200 lines (199 loc) • 8.32 kB
TypeScript
/**
* @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 { Compat } from '@firebase/util';
import { Document } from '../model/document';
import { DocumentKey } from '../model/document_key';
import { FieldPath as InternalFieldPath } from '../model/path';
import { FirebaseFirestore } from './database';
import { FieldPath } from './field_path';
import { DocumentData, DocumentReference, Query, SetOptions } from './reference';
import { UntypedFirestoreDataConverter } from './user_data_reader';
import { AbstractUserDataWriter } from './user_data_writer';
/**
* 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 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;
}
/**
* 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> {
_firestore: FirebaseFirestore;
_userDataWriter: AbstractUserDataWriter;
_key: DocumentKey;
_document: Document | null;
_converter: UntypedFirestoreDataConverter<T> | null;
/** @hideconstructor protected */
constructor(_firestore: FirebaseFirestore, _userDataWriter: AbstractUserDataWriter, _key: DocumentKey, _document: Document | null, _converter: UntypedFirestoreDataConverter<T> | null);
/** 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;
}
/**
* 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;
}
/**
* 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> {
readonly _docs: Array<QueryDocumentSnapshot<T>>;
/**
* The query on which you called {@link getDocs} in order to get this
* `QuerySnapshot`.
*/
readonly query: Query<T>;
/** @hideconstructor */
constructor(_query: Query<T>, _docs: Array<QueryDocumentSnapshot<T>>);
/** 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 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;
/**
* Helper that calls fromDotSeparatedString() but wraps any error thrown.
*/
export declare function fieldPathFromArgument(methodName: string, arg: string | FieldPath | Compat<FieldPath>): InternalFieldPath;