· 6 years ago · Apr 05, 2019, 05:00 AM
1/**
2 * @fileoverview Firestore Server API.
3 *
4 * Copyright 2017 Google Inc. All Rights Reserved.
5 *
6 * Licensed under the Apache License, Version 2.0 (the "License");
7 * you may not use this file except in compliance with the License.
8 * You may obtain a copy of the License at
9 *
10 * http://www.apache.org/licenses/LICENSE-2.0
11 *
12 * Unless required by applicable law or agreed to in writing, software
13 * distributed under the License is distributed on an "AS IS" BASIS,
14 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15 * See the License for the specific language governing permissions and
16 * limitations under the License.
17 */
18
19// tslint:disable
20
21// Declare a global (ambient) namespace
22// (used when not using import statement, but just script include).
23declare namespace FirebaseFirestore {
24 /**
25 * Document data (for use with `DocumentReference.set()`) consists of fields
26 * mapped to values.
27 */
28 export type DocumentData = {[field: string]: any};
29
30 /**
31 * Update data (for use with `DocumentReference.update()`) consists of field
32 * paths (e.g. 'foo' or 'foo.baz') mapped to values. Fields that contain dots
33 * reference nested fields within the document.
34 */
35 export type UpdateData = {[fieldPath: string]: any};
36
37 /**
38 * Sets the log function for all active Firestore instances.
39 */
40 function setLogFunction(logger: (msg:string) => void): void;
41
42 /**
43 * Settings used to directly configure a `Firestore` instance.
44 */
45 export interface Settings {
46 /**
47 * The Firestore Project ID. Can be omitted in environments that support
48 * `Application Default Credentials` {@see https://cloud.google.com/docs/authentication}
49 */
50 projectId?: string;
51
52 /**
53 * Local file containing the Service Account credentials. Can be omitted
54 * in environments that support `Application Default Credentials`
55 * {@see https://cloud.google.com/docs/authentication}
56 */
57 keyFilename?: string;
58
59 /**
60 * Enables the use of `Timestamp`s for timestamp fields in
61 * `DocumentSnapshot`s.
62 *
63 * Currently, Firestore returns timestamp fields as `Date` but `Date` only
64 * supports millisecond precision, which leads to truncation and causes
65 * unexpected behavior when using a timestamp from a snapshot as a part
66 * of a subsequent query.
67 *
68 * Setting `timestampsInSnapshots` to true will cause Firestore to return
69 * `Timestamp` values instead of `Date` avoiding this kind of problem. To
70 * make this work you must also change any code that uses `Date` to use
71 * `Timestamp` instead.
72 *
73 * NOTE: in the future `timestampsInSnapshots: true` will become the
74 * default and this option will be removed so you should change your code to
75 * use `Timestamp` now and opt-in to this new behavior as soon as you can.
76 */
77 timestampsInSnapshots?: boolean;
78
79 [key: string]: any; // Accept other properties, such as GRPC settings.
80 }
81
82 /**
83 * `Firestore` represents a Firestore Database and is the entry point for all
84 * Firestore operations.
85 */
86 export class Firestore {
87 /**
88 * @param settings - Configuration object. See [Firestore Documentation]
89 * {@link https://firebase.google.com/docs/firestore/}
90 */
91 public constructor(settings?: Settings);
92
93 /**
94 * Specifies custom settings to be used to configure the `Firestore`
95 * instance. Can only be invoked once and before any other Firestore
96 * method.
97 *
98 * If settings are provided via both `settings()` and the `Firestore`
99 * constructor, both settings objects are merged and any settings provided
100 * via `settings()` take precedence.
101 *
102 * @param {object} settings The settings to use for all Firestore
103 * operations.
104 */
105 settings(settings: Settings): void;
106
107 /**
108 * Gets a `CollectionReference` instance that refers to the collection at
109 * the specified path.
110 *
111 * @param collectionPath A slash-separated path to a collection.
112 * @return The `CollectionReference` instance.
113 */
114 collection(collectionPath: string): CollectionReference;
115
116 /**
117 * Gets a `DocumentReference` instance that refers to the document at the
118 * specified path.
119 *
120 * @param documentPath A slash-separated path to a document.
121 * @return The `DocumentReference` instance.
122 */
123 doc(documentPath: string): DocumentReference;
124
125 /**
126 * Retrieves multiple documents from Firestore.
127 *
128 * @param documentRef The `DocumentReferences` to receive.
129 * @return A Promise that resolves with an array of resulting document
130 * snapshots.
131 */
132 getAll(...documentRef: DocumentReference[]): Promise<DocumentSnapshot[]>;
133
134 /**
135 * Fetches the root collections that are associated with this Firestore
136 * database.
137 *
138 * @returns A Promise that resolves with an array of CollectionReferences.
139 */
140 getCollections() : Promise<CollectionReference[]>;
141
142 /**
143 * Executes the given updateFunction and commits the changes applied within
144 * the transaction.
145 *
146 * You can use the transaction object passed to 'updateFunction' to read and
147 * modify Firestore documents under lock. Transactions are committed once
148 * 'updateFunction' resolves and attempted up to five times on failure.
149 *
150 * @param updateFunction The function to execute within the transaction
151 * context.
152 * @return If the transaction completed successfully or was explicitly
153 * aborted (by the updateFunction returning a failed Promise), the Promise
154 * returned by the updateFunction will be returned here. Else if the
155 * transaction failed, a rejected Promise with the corresponding failure
156 * error will be returned.
157 */
158 runTransaction<T>(
159 updateFunction: (transaction: Transaction) => Promise<T>
160 ): Promise<T>;
161
162 /**
163 * Creates a write batch, used for performing multiple writes as a single
164 * atomic operation.
165 */
166 batch(): WriteBatch;
167 }
168
169 /**
170 * An immutable object representing a geo point in Firestore. The geo point
171 * is represented as latitude/longitude pair.
172 *
173 * Latitude values are in the range of [-90, 90].
174 * Longitude values are in the range of [-180, 180].
175 */
176 export class GeoPoint {
177 /**
178 * Creates a new immutable GeoPoint object with the provided latitude and
179 * longitude values.
180 * @param latitude The latitude as number between -90 and 90.
181 * @param longitude The longitude as number between -180 and 180.
182 */
183 constructor(latitude: number, longitude: number);
184
185 readonly latitude: number;
186 readonly longitude: number;
187
188 /**
189 * Returns true if this `GeoPoint` is equal to the provided one.
190 *
191 * @param other The `GeoPoint` to compare against.
192 * @return true if this `GeoPoint` is equal to the provided one.
193 */
194 isEqual(other: GeoPoint): boolean;
195 }
196
197 /**
198 * A reference to a transaction.
199 * The `Transaction` object passed to a transaction's updateFunction provides
200 * the methods to read and write data within the transaction context. See
201 * `Firestore.runTransaction()`.
202 */
203 export class Transaction {
204 private constructor();
205
206
207 /**
208 * Retrieves a query result. Holds a pessimistic lock on all returned
209 * documents.
210 *
211 * @param query A query to execute.
212 * @return A QuerySnapshot for the retrieved data.
213 */
214 get(query: Query): Promise<QuerySnapshot>;
215
216 /**
217 * Reads the document referenced by the provided `DocumentReference.`
218 * Holds a pessimistic lock on the returned document.
219 *
220 * @param documentRef A reference to the document to be read.
221 * @return A DocumentSnapshot for the read data.
222 */
223 get(documentRef: DocumentReference): Promise<DocumentSnapshot>;
224
225 /**
226 * Retrieves multiple documents from Firestore. Holds a pessimistic lock on
227 * all returned documents.
228 *
229 * @param documentRef The `DocumentReferences` to receive.
230 * @return A Promise that resolves with an array of resulting document
231 * snapshots.
232 */
233 getAll(...documentRef: DocumentReference[]): Promise<DocumentSnapshot[]>;
234
235 /**
236 * Create the document referred to by the provided `DocumentReference`.
237 * The operation will fail the transaction if a document exists at the
238 * specified location.
239 *
240 * @param documentRef A reference to the document to be create.
241 * @param data The object data to serialize as the document.
242 * @return This `Transaction` instance. Used for chaining method calls.
243 */
244 create(documentRef: DocumentReference, data: DocumentData): Transaction;
245
246 /**
247 * Writes to the document referred to by the provided `DocumentReference`.
248 * If the document does not exist yet, it will be created. If you pass
249 * `SetOptions`, the provided data can be merged into the existing document.
250 *
251 * @param documentRef A reference to the document to be set.
252 * @param data An object of the fields and values for the document.
253 * @param options An object to configure the set behavior.
254 * @return This `Transaction` instance. Used for chaining method calls.
255 */
256 set(documentRef: DocumentReference, data: DocumentData,
257 options?: SetOptions): Transaction;
258
259 /**
260 * Updates fields in the document referred to by the provided
261 * `DocumentReference`. The update will fail if applied to a document that
262 * does not exist.
263 *
264 * Nested fields can be updated by providing dot-separated field path
265 * strings.
266 *
267 * @param documentRef A reference to the document to be updated.
268 * @param data An object containing the fields and values with which to
269 * update the document.
270 * @param precondition A Precondition to enforce on this update.
271 * @return This `Transaction` instance. Used for chaining method calls.
272 */
273 update(documentRef: DocumentReference, data: UpdateData,
274 precondition?: Precondition): Transaction;
275
276 /**
277 * Updates fields in the document referred to by the provided
278 * `DocumentReference`. The update will fail if applied to a document that
279 * does not exist.
280 *
281 * Nested fields can be updated by providing dot-separated field path
282 * strings or by providing FieldPath objects.
283 *
284 * A `Precondition` restricting this update can be specified as the last
285 * argument.
286 *
287 * @param documentRef A reference to the document to be updated.
288 * @param field The first field to update.
289 * @param value The first value
290 * @param fieldsOrPrecondition An alternating list of field paths and values
291 * to update, optionally followed by a `Precondition` to enforce on this
292 * update.
293 * @return This `Transaction` instance. Used for chaining method calls.
294 */
295 update(documentRef: DocumentReference, field: string|FieldPath, value:any,
296 ...fieldsOrPrecondition: any[]): Transaction;
297
298 /**
299 * Deletes the document referred to by the provided `DocumentReference`.
300 *
301 * @param documentRef A reference to the document to be deleted.
302 * @param precondition A Precondition to enforce for this delete.
303 * @return This `Transaction` instance. Used for chaining method calls.
304 */
305 delete(documentRef: DocumentReference,
306 precondition?: Precondition): Transaction;
307 }
308
309 /**
310 * A write batch, used to perform multiple writes as a single atomic unit.
311 *
312 * A `WriteBatch` object can be acquired by calling `Firestore.batch()`. It
313 * provides methods for adding writes to the write batch. None of the
314 * writes will be committed (or visible locally) until `WriteBatch.commit()`
315 * is called.
316 *
317 * Unlike transactions, write batches are persisted offline and therefore are
318 * preferable when you don't need to condition your writes on read data.
319 */
320 export class WriteBatch {
321 private constructor();
322
323 /**
324 * Create the document referred to by the provided `DocumentReference`. The
325 * operation will fail the batch if a document exists at the specified
326 * location.
327 *
328 * @param documentRef A reference to the document to be created.
329 * @param data The object data to serialize as the document.
330 * @return This `WriteBatch` instance. Used for chaining method calls.
331 */
332 create(documentRef: DocumentReference, data: DocumentData): WriteBatch;
333
334 /**
335 * Write to the document referred to by the provided `DocumentReference`.
336 * If the document does not exist yet, it will be created. If you pass
337 * `SetOptions`, the provided data can be merged into the existing document.
338 *
339 * @param documentRef A reference to the document to be set.
340 * @param data An object of the fields and values for the document.
341 * @param options An object to configure the set behavior.
342 * @return This `WriteBatch` instance. Used for chaining method calls.
343 */
344 set(documentRef: DocumentReference, data: DocumentData,
345 options?: SetOptions): WriteBatch;
346
347 /**
348 * Update fields of the document referred to by the provided
349 * `DocumentReference`. If the document doesn't yet exist, the update fails
350 * and the entire batch will be rejected.
351 *
352 * Nested fields can be updated by providing dot-separated field path
353 * strings.
354 *
355 * @param documentRef A reference to the document to be updated.
356 * @param data An object containing the fields and values with which to
357 * update the document.
358 * @param precondition A Precondition to enforce on this update.
359 * @return This `WriteBatch` instance. Used for chaining method calls.
360 */
361 update(documentRef: DocumentReference, data: UpdateData,
362 precondition?: Precondition): WriteBatch;
363
364 /**
365 * Updates fields in the document referred to by the provided
366 * `DocumentReference`. The update will fail if applied to a document that
367 * does not exist.
368 *
369 * Nested fields can be updated by providing dot-separated field path
370 * strings or by providing FieldPath objects.
371 *
372 * A `Precondition` restricting this update can be specified as the last
373 * argument.
374 *
375 * @param documentRef A reference to the document to be updated.
376 * @param field The first field to update.
377 * @param value The first value
378 * @param fieldsOrPrecondition An alternating list of field paths and values
379 * to update, optionally followed a `Precondition` to enforce on this update.
380 * @return This `WriteBatch` instance. Used for chaining method calls.
381 */
382 update(documentRef: DocumentReference, field: string|FieldPath, value:any,
383 ...fieldsOrPrecondition: any[]): WriteBatch;
384
385 /**
386 * Deletes the document referred to by the provided `DocumentReference`.
387 *
388 * @param documentRef A reference to the document to be deleted.
389 * @param precondition A Precondition to enforce for this delete.
390 * @return This `WriteBatch` instance. Used for chaining method calls.
391 */
392 delete(documentRef: DocumentReference,
393 precondition?: Precondition): WriteBatch;
394
395 /**
396 * Commits all of the writes in this write batch as a single atomic unit.
397 *
398 * @return A Promise resolved once all of the writes in the batch have been
399 * successfully written to the backend as an atomic unit.
400 */
401 commit(): Promise<WriteResult[]>;
402 }
403
404 /**
405 * An options object that configures conditional behavior of `update()` and
406 * `delete()` calls in `DocumentReference`, `WriteBatch`, and `Transaction`.
407 * Using Preconditions, these calls can be restricted to only apply to
408 * documents that match the specified restrictions.
409 */
410 export interface Precondition {
411 /**
412 * If set, the last update time to enforce.
413 */
414 readonly lastUpdateTime?: Timestamp;
415 }
416
417 /**
418 * An options object that configures the behavior of `set()` calls in
419 * `DocumentReference`, `WriteBatch` and `Transaction`. These calls can be
420 * configured to perform granular merges instead of overwriting the target
421 * documents in their entirety.
422 */
423 export interface SetOptions {
424 /**
425 * Changes the behavior of a set() call to only replace the values specified
426 * in its data argument. Fields omitted from the set() call remain
427 * untouched.
428 */
429 readonly merge?: boolean;
430
431 /**
432 * Changes the behavior of set() calls to only replace the specified field
433 * paths. Any field path that is not specified is ignored and remains
434 * untouched.
435 *
436 * It is an error to pass a SetOptions object to a set() call that is
437 * missing a value for any of the fields specified here.
438 */
439 readonly mergeFields?: (string|FieldPath)[];
440 }
441
442 /**
443 * A WriteResult wraps the write time set by the Firestore servers on `sets()`,
444 * `updates()`, and `creates()`.
445 */
446 export class WriteResult {
447 private constructor();
448
449 /**
450 * The write time as set by the Firestore servers.
451 */
452 readonly writeTime: Timestamp;
453
454 /**
455 * Returns true if this `WriteResult` is equal to the provided one.
456 *
457 * @param other The `WriteResult` to compare against.
458 * @return true if this `WriteResult` is equal to the provided one.
459 */
460 isEqual(other: WriteResult): boolean;
461 }
462
463 /**
464 * A `DocumentReference` refers to a document location in a Firestore database
465 * and can be used to write, read, or listen to the location. The document at
466 * the referenced location may or may not exist. A `DocumentReference` can
467 * also be used to create a `CollectionReference` to a subcollection.
468 */
469 export class DocumentReference {
470 private constructor();
471
472 /** The identifier of the document within its collection. */
473 readonly id: string;
474
475 /**
476 * The `Firestore` for the Firestore database (useful for performing
477 * transactions, etc.).
478 */
479 readonly firestore: Firestore;
480
481 /**
482 * A reference to the Collection to which this DocumentReference belongs.
483 */
484 readonly parent: CollectionReference;
485
486 /**
487 * A string representing the path of the referenced document (relative
488 * to the root of the database).
489 */
490 readonly path: string;
491
492 /**
493 * Gets a `CollectionReference` instance that refers to the collection at
494 * the specified path.
495 *
496 * @param collectionPath A slash-separated path to a collection.
497 * @return The `CollectionReference` instance.
498 */
499 collection(collectionPath: string): CollectionReference;
500
501 /**
502 * Fetches the subcollections that are direct children of this document.
503 *
504 * @returns A Promise that resolves with an array of CollectionReferences.
505 */
506 getCollections() : Promise<CollectionReference[]>;
507
508 /**
509 * Creates a document referred to by this `DocumentReference` with the
510 * provided object values. The write fails if the document already exists
511 *
512 * @param data The object data to serialize as the document.
513 * @return A Promise resolved with the write time of this create.
514 */
515 create(data: DocumentData): Promise<WriteResult>;
516
517 /**
518 * Writes to the document referred to by this `DocumentReference`. If the
519 * document does not yet exist, it will be created. If you pass
520 * `SetOptions`, the provided data can be merged into an existing document.
521 *
522 * @param data A map of the fields and values for the document.
523 * @param options An object to configure the set behavior.
524 * @return A Promise resolved with the write time of this set.
525 */
526 set(data: DocumentData, options?: SetOptions): Promise<WriteResult>;
527
528 /**
529 * Updates fields in the document referred to by this `DocumentReference`.
530 * The update will fail if applied to a document that does not exist.
531 *
532 * Nested fields can be updated by providing dot-separated field path
533 * strings.
534 *
535 * @param data An object containing the fields and values with which to
536 * update the document.
537 * @param precondition A Precondition to enforce on this update.
538 * @return A Promise resolved with the write time of this update.
539 */
540 update(data: UpdateData, precondition?: Precondition): Promise<WriteResult>;
541
542 /**
543 * Updates fields in the document referred to by this `DocumentReference`.
544 * The update will fail if applied to a document that does not exist.
545 *
546 * Nested fields can be updated by providing dot-separated field path
547 * strings or by providing FieldPath objects.
548 *
549 * A `Precondition` restricting this update can be specified as the last
550 * argument.
551 *
552 * @param field The first field to update.
553 * @param value The first value.
554 * @param moreFieldsOrPrecondition An alternating list of field paths and
555 * values to update, optionally followed by a `Precondition` to enforce on
556 * this update.
557 * @return A Promise resolved with the write time of this update.
558 */
559 update(field: string|FieldPath, value:any,
560 ...moreFieldsOrPrecondition: any[]): Promise<WriteResult>;
561
562 /**
563 * Deletes the document referred to by this `DocumentReference`.
564 *
565 * @param precondition A Precondition to enforce for this delete.
566 * @return A Promise resolved with the write time of this delete.
567 */
568 delete(precondition?:Precondition): Promise<WriteResult>;
569
570 /**
571 * Reads the document referred to by this `DocumentReference`.
572 *
573 * @return A Promise resolved with a DocumentSnapshot containing the
574 * current document contents.
575 */
576 get(): Promise<DocumentSnapshot>;
577
578 /**
579 * Attaches a listener for DocumentSnapshot events.
580 *
581 * @param onNext A callback to be called every time a new `DocumentSnapshot`
582 * is available.
583 * @param onError A callback to be called if the listen fails or is
584 * cancelled. No further callbacks will occur.
585 * @return An unsubscribe function that can be called to cancel
586 * the snapshot listener.
587 */
588 onSnapshot(onNext: (snapshot: DocumentSnapshot) => void,
589 onError?: (error: Error) => void): () => void;
590
591 /**
592 * Returns true if this `DocumentReference` is equal to the provided one.
593 *
594 * @param other The `DocumentReference` to compare against.
595 * @return true if this `DocumentReference` is equal to the provided one.
596 */
597 isEqual(other: DocumentReference): boolean;
598 }
599
600 /**
601 * A `DocumentSnapshot` contains data read from a document in your Firestore
602 * database. The data can be extracted with `.data()` or `.get(<field>)` to
603 * get a specific field.
604 *
605 * For a `DocumentSnapshot` that points to a non-existing document, any data
606 * access will return 'undefined'. You can use the `exists` property to
607 * explicitly verify a document's existence.
608 */
609 export class DocumentSnapshot {
610 protected constructor();
611
612 /** True if the document exists. */
613 readonly exists: boolean;
614
615 /** A `DocumentReference` to the document location. */
616 readonly ref: DocumentReference;
617
618 /**
619 * The ID of the document for which this `DocumentSnapshot` contains data.
620 */
621 readonly id: string;
622
623 /**
624 * The time the document was created. Not set for documents that don't
625 * exist.
626 */
627 readonly createTime?: Timestamp;
628
629 /**
630 * The time the document was last updated (at the time the snapshot was
631 * generated). Not set for documents that don't exist.
632 */
633 readonly updateTime?: Timestamp;
634
635 /**
636 * The time this snapshot was read.
637 */
638 readonly readTime: Timestamp;
639
640 /**
641 * Retrieves all fields in the document as an Object. Returns 'undefined' if
642 * the document doesn't exist.
643 *
644 * @return An Object containing all fields in the document.
645 */
646 data(): DocumentData | undefined;
647
648 /**
649 * Retrieves the field specified by `fieldPath`.
650 *
651 * @param fieldPath The path (e.g. 'foo' or 'foo.bar') to a specific field.
652 * @return The data at the specified field location or undefined if no such
653 * field exists in the document.
654 */
655 get(fieldPath: string|FieldPath): any;
656
657 /**
658 * Returns true if the document's data and path in this `DocumentSnapshot`
659 * is equal to the provided one.
660 *
661 * @param other The `DocumentSnapshot` to compare against.
662 * @return true if this `DocumentSnapshot` is equal to the provided one.
663 */
664 isEqual(other: DocumentSnapshot): boolean;
665 }
666
667 /**
668 * A `QueryDocumentSnapshot` contains data read from a document in your
669 * Firestore database as part of a query. The document is guaranteed to exist
670 * and its data can be extracted with `.data()` or `.get(<field>)` to get a
671 * specific field.
672 *
673 * A `QueryDocumentSnapshot` offers the same API surface as a
674 * `DocumentSnapshot`. Since query results contain only existing documents, the
675 * `exists` property will always be true and `data()` will never return
676 * 'undefined'.
677 */
678 export class QueryDocumentSnapshot extends DocumentSnapshot {
679 private constructor();
680
681 /**
682 * The time the document was created.
683 */
684 readonly createTime: Timestamp;
685
686 /**
687 * The time the document was last updated (at the time the snapshot was
688 * generated).
689 */
690 readonly updateTime: Timestamp;
691
692 /**
693 * Retrieves all fields in the document as an Object.
694 *
695 * @override
696 * @return An Object containing all fields in the document.
697 */
698 data(): DocumentData;
699 }
700
701 /**
702 * The direction of a `Query.orderBy()` clause is specified as 'desc' or 'asc'
703 * (descending or ascending).
704 */
705 export type OrderByDirection = 'desc' | 'asc';
706
707 /**
708 * Filter conditions in a `Query.where()` clause are specified using the
709 * strings '<', '<=', '==', '>=', '>', and 'array-contains'.
710 */
711 export type WhereFilterOp = '<' | '<=' | '==' | '>=' | '>' | 'array-contains';
712
713 /**
714 * A `Query` refers to a Query which you can read or listen to. You can also
715 * construct refined `Query` objects by adding filters and ordering.
716 */
717 export class Query {
718 protected constructor();
719
720 /**
721 * The `Firestore` for the Firestore database (useful for performing
722 * transactions, etc.).
723 */
724 readonly firestore: Firestore;
725
726 /**
727 * Creates and returns a new Query with the additional filter that documents
728 * must contain the specified field and that its value should satisfy the
729 * relation constraint provided.
730 *
731 * This function returns a new (immutable) instance of the Query (rather
732 * than modify the existing instance) to impose the filter.
733 *
734 * @param fieldPath The path to compare
735 * @param opStr The operation string (e.g "<", "<=", "==", ">", ">=").
736 * @param value The value for comparison
737 * @return The created Query.
738 */
739 where(fieldPath: string|FieldPath, opStr: WhereFilterOp, value: any): Query;
740
741 /**
742 * Creates and returns a new Query that's additionally sorted by the
743 * specified field, optionally in descending order instead of ascending.
744 *
745 * This function returns a new (immutable) instance of the Query (rather
746 * than modify the existing instance) to impose the order.
747 *
748 * @param fieldPath The field to sort by.
749 * @param directionStr Optional direction to sort by ('asc' or 'desc'). If
750 * not specified, order will be ascending.
751 * @return The created Query.
752 */
753 orderBy(
754 fieldPath: string|FieldPath, directionStr?: OrderByDirection
755 ): Query;
756
757 /**
758 * Creates and returns a new Query that's additionally limited to only
759 * return up to the specified number of documents.
760 *
761 * This function returns a new (immutable) instance of the Query (rather
762 * than modify the existing instance) to impose the limit.
763 *
764 * @param limit The maximum number of items to return.
765 * @return The created Query.
766 */
767 limit(limit: number): Query;
768
769 /**
770 * Specifies the offset of the returned results.
771 *
772 * This function returns a new (immutable) instance of the Query (rather
773 * than modify the existing instance) to impose the offset.
774 *
775 * @param offset The offset to apply to the Query results.
776 * @return The created Query.
777 */
778 offset(offset: number): Query;
779
780 /**
781 * Creates and returns a new Query instance that applies a field mask to
782 * the result and returns only the specified subset of fields. You can
783 * specify a list of field paths to return, or use an empty list to only
784 * return the references of matching documents.
785 *
786 * This function returns a new (immutable) instance of the Query (rather
787 * than modify the existing instance) to impose the field mask.
788 *
789 * @param field The field paths to return.
790 * @return The created Query.
791 */
792 select(...field: (string | FieldPath)[]): Query;
793
794 /**
795 * Creates and returns a new Query that starts at the provided document
796 * (inclusive). The starting position is relative to the order of the query.
797 * The document must contain all of the fields provided in the orderBy of
798 * this query.
799 *
800 * @param snapshot The snapshot of the document to start after.
801 * @return The created Query.
802 */
803 startAt(snapshot: DocumentSnapshot): Query;
804
805 /**
806 * Creates and returns a new Query that starts at the provided fields
807 * relative to the order of the query. The order of the field values
808 * must match the order of the order by clauses of the query.
809 *
810 * @param fieldValues The field values to start this query at, in order
811 * of the query's order by.
812 * @return The created Query.
813 */
814 startAt(...fieldValues: any[]): Query;
815
816 /**
817 * Creates and returns a new Query that starts after the provided document
818 * (exclusive). The starting position is relative to the order of the query.
819 * The document must contain all of the fields provided in the orderBy of
820 * this query.
821 *
822 * @param snapshot The snapshot of the document to start after.
823 * @return The created Query.
824 */
825 startAfter(snapshot: DocumentSnapshot): Query;
826
827 /**
828 * Creates and returns a new Query that starts after the provided fields
829 * relative to the order of the query. The order of the field values
830 * must match the order of the order by clauses of the query.
831 *
832 * @param fieldValues The field values to start this query after, in order
833 * of the query's order by.
834 * @return The created Query.
835 */
836 startAfter(...fieldValues: any[]): Query;
837
838 /**
839 * Creates and returns a new Query that ends before the provided document
840 * (exclusive). The end position is relative to the order of the query. The
841 * document must contain all of the fields provided in the orderBy of this
842 * query.
843 *
844 * @param snapshot The snapshot of the document to end before.
845 * @return The created Query.
846 */
847 endBefore(snapshot: DocumentSnapshot): Query;
848
849 /**
850 * Creates and returns a new Query that ends before the provided fields
851 * relative to the order of the query. The order of the field values
852 * must match the order of the order by clauses of the query.
853 *
854 * @param fieldValues The field values to end this query before, in order
855 * of the query's order by.
856 * @return The created Query.
857 */
858 endBefore(...fieldValues: any[]): Query;
859
860 /**
861 * Creates and returns a new Query that ends at the provided document
862 * (inclusive). The end position is relative to the order of the query. The
863 * document must contain all of the fields provided in the orderBy of this
864 * query.
865 *
866 * @param snapshot The snapshot of the document to end at.
867 * @return The created Query.
868 */
869 endAt(snapshot: DocumentSnapshot): Query;
870
871 /**
872 * Creates and returns a new Query that ends at the provided fields
873 * relative to the order of the query. The order of the field values
874 * must match the order of the order by clauses of the query.
875 *
876 * @param fieldValues The field values to end this query at, in order
877 * of the query's order by.
878 * @return The created Query.
879 */
880 endAt(...fieldValues: any[]): Query;
881
882 /**
883 * Executes the query and returns the results as a `QuerySnapshot`.
884 *
885 * @return A Promise that will be resolved with the results of the Query.
886 */
887 get(): Promise<QuerySnapshot>;
888
889 /*
890 * Executes the query and returns the results as Node Stream.
891 *
892 * @return A stream of QueryDocumentSnapshot.
893 */
894 stream(): NodeJS.ReadableStream;
895
896 /**
897 * Attaches a listener for `QuerySnapshot `events.
898 *
899 * @param onNext A callback to be called every time a new `QuerySnapshot`
900 * is available.
901 * @param onError A callback to be called if the listen fails or is
902 * cancelled. No further callbacks will occur.
903 * @return An unsubscribe function that can be called to cancel
904 * the snapshot listener.
905 */
906 onSnapshot(onNext: (snapshot: QuerySnapshot) => void,
907 onError?: (error: Error) => void) : () => void;
908
909 /**
910 * Returns true if this `Query` is equal to the provided one.
911 *
912 * @param other The `Query` to compare against.
913 * @return true if this `Query` is equal to the provided one.
914 */
915 isEqual(other: Query): boolean;
916 }
917
918 /**
919 * A `QuerySnapshot` contains zero or more `QueryDocumentSnapshot` objects
920 * representing the results of a query. The documents can be accessed as an
921 * array via the `docs` property or enumerated using the `forEach` method. The
922 * number of documents can be determined via the `empty` and `size`
923 * properties.
924 */
925 export class QuerySnapshot {
926 private constructor();
927
928 /**
929 * The query on which you called `get` or `onSnapshot` in order to get this
930 * `QuerySnapshot`.
931 */
932 readonly query: Query;
933
934 /**
935 * An array of the documents that changed since the last snapshot. If this
936 * is the first snapshot, all documents will be in the list as added
937 * changes.
938 */
939 readonly docChanges: DocumentChange[];
940
941 /** An array of all the documents in the QuerySnapshot. */
942 readonly docs: QueryDocumentSnapshot[];
943
944 /** The number of documents in the QuerySnapshot. */
945 readonly size: number;
946
947 /** True if there are no documents in the QuerySnapshot. */
948 readonly empty: boolean;
949
950 /** The time this query snapshot was obtained. */
951 readonly readTime: Timestamp;
952
953 /**
954 * Enumerates all of the documents in the QuerySnapshot.
955 *
956 * @param callback A callback to be called with a `DocumentSnapshot` for
957 * each document in the snapshot.
958 * @param thisArg The `this` binding for the callback.
959 */
960 forEach(
961 callback: (result: QueryDocumentSnapshot) => void, thisArg?: any
962 ): void;
963
964 /**
965 * Returns true if the document data in this `QuerySnapshot` is equal to the
966 * provided one.
967 *
968 * @param other The `QuerySnapshot` to compare against.
969 * @return true if this `QuerySnapshot` is equal to the provided one.
970 */
971 isEqual(other: QuerySnapshot): boolean;
972 }
973
974 /**
975 * The type of of a `DocumentChange` may be 'added', 'removed', or 'modified'.
976 */
977 export type DocumentChangeType = 'added' | 'removed' | 'modified';
978
979 /**
980 * A `DocumentChange` represents a change to the documents matching a query.
981 * It contains the document affected and the type of change that occurred.
982 */
983 export interface DocumentChange {
984 /** The type of change ('added', 'modified', or 'removed'). */
985 readonly type: DocumentChangeType;
986
987 /** The document affected by this change. */
988 readonly doc: QueryDocumentSnapshot;
989
990 /**
991 * The index of the changed document in the result set immediately prior to
992 * this DocumentChange (i.e. supposing that all prior DocumentChange objects
993 * have been applied). Is -1 for 'added' events.
994 */
995 readonly oldIndex: number;
996
997 /**
998 * The index of the changed document in the result set immediately after
999 * this DocumentChange (i.e. supposing that all prior DocumentChange
1000 * objects and the current DocumentChange object have been applied).
1001 * Is -1 for 'removed' events.
1002 */
1003 readonly newIndex: number;
1004
1005 /**
1006 * Returns true if the data in this `DocumentChange` is equal to the
1007 * provided one.
1008 *
1009 * @param other The `DocumentChange` to compare against.
1010 * @return true if this `DocumentChange` is equal to the provided one.
1011 */
1012 isEqual(other: DocumentChange): boolean;
1013 }
1014
1015 /**
1016 * A `CollectionReference` object can be used for adding documents, getting
1017 * document references, and querying for documents (using the methods
1018 * inherited from `Query`).
1019 */
1020 export class CollectionReference extends Query {
1021 private constructor();
1022
1023 /** The identifier of the collection. */
1024 readonly id: string;
1025
1026 /**
1027 * A reference to the containing Document if this is a subcollection, else
1028 * null.
1029 */
1030 readonly parent: DocumentReference|null;
1031
1032 /**
1033 * A string representing the path of the referenced collection (relative
1034 * to the root of the database).
1035 */
1036 readonly path: string;
1037
1038 /**
1039 * Get a `DocumentReference` for the document within the collection at the
1040 * specified path. If no path is specified, an automatically-generated
1041 * unique ID will be used for the returned DocumentReference.
1042 *
1043 * @param documentPath A slash-separated path to a document.
1044 * @return The `DocumentReference` instance.
1045 */
1046 doc(documentPath?: string): DocumentReference;
1047
1048 /**
1049 * Add a new document to this collection with the specified data, assigning
1050 * it a document ID automatically.
1051 *
1052 * @param data An Object containing the data for the new document.
1053 * @return A Promise resolved with a `DocumentReference` pointing to the
1054 * newly created document after it has been written to the backend.
1055 */
1056 add(data: DocumentData): Promise<DocumentReference>;
1057
1058 /**
1059 * Returns true if this `CollectionReference` is equal to the provided one.
1060 *
1061 * @param other The `CollectionReference` to compare against.
1062 * @return true if this `CollectionReference` is equal to the provided one.
1063 */
1064 isEqual(other: CollectionReference): boolean;
1065 }
1066
1067 /**
1068 * Sentinel values that can be used when writing document fields with set(),
1069 * create() or update().
1070 */
1071 export class FieldValue {
1072 private constructor();
1073
1074 /**
1075 * Returns a sentinel used with set(), create() or update() to include a
1076 * server-generated timestamp in the written data.
1077 *
1078 * @return The FieldValue sentinel for use in a call to set(), create() or
1079 * update().
1080 */
1081 static serverTimestamp(): FieldValue;
1082
1083 /**
1084 * Returns a sentinel for use with update() or set() with {merge:true} to
1085 * mark a field for deletion.
1086 *
1087 * @return The FieldValue sentinel for use in a call to set() or update().
1088 */
1089 static delete(): FieldValue;
1090
1091 /**
1092 * Returns a special value that can be used with set(), create() or update()
1093 * that tells the server to union the given elements with any array value
1094 * that already exists on the server. Each specified element that doesn't
1095 * already exist in the array will be added to the end. If the field being
1096 * modified is not already an array it will be overwritten with an array
1097 * containing exactly the specified elements.
1098 *
1099 * @param elements The elements to union into the array.
1100 * @return The FieldValue sentinel for use in a call to set(), create() or
1101 * update().
1102 */
1103 static arrayUnion(...elements: any[]): FieldValue;
1104
1105 /**
1106 * Returns a special value that can be used with set(), create() or update()
1107 * that tells the server to remove the given elements from any array value
1108 * that already exists on the server. All instances of each element
1109 * specified will be removed from the array. If the field being modified is
1110 * not already an array it will be overwritten with an empty array.
1111 *
1112 * @param elements The elements to remove from the array.
1113 * @return The FieldValue sentinel for use in a call to set(), create() or
1114 * update().
1115 */
1116 static arrayRemove(...elements: any[]): FieldValue;
1117
1118 /**
1119 * Returns true if this `FieldValue` is equal to the provided one.
1120 *
1121 * @param other The `FieldValue` to compare against.
1122 * @return true if this `FieldValue` is equal to the provided one.
1123 */
1124 isEqual(other: FieldValue): boolean;
1125 }
1126
1127 /**
1128 * A FieldPath refers to a field in a document. The path may consist of a
1129 * single field name (referring to a top-level field in the document), or a
1130 * list of field names (referring to a nested field in the document).
1131 */
1132 export class FieldPath {
1133 /**
1134 * Creates a FieldPath from the provided field names. If more than one field
1135 * name is provided, the path will point to a nested field in a document.
1136 *
1137 * @param fieldNames A list of field names.
1138 */
1139 constructor(...fieldNames: string[]);
1140
1141 /**
1142 * Returns a special sentinel FieldPath to refer to the ID of a document.
1143 * It can be used in queries to sort or filter by the document ID.
1144 */
1145 static documentId(): FieldPath;
1146
1147 /**
1148 * Returns true if this `FieldPath` is equal to the provided one.
1149 *
1150 * @param other The `FieldPath` to compare against.
1151 * @return true if this `FieldPath` is equal to the provided one.
1152 */
1153 isEqual(other: FieldPath): boolean;
1154 }
1155
1156 /**
1157 * A Timestamp represents a point in time independent of any time zone or
1158 * calendar, represented as seconds and fractions of seconds at nanosecond
1159 * resolution in UTC Epoch time. It is encoded using the Proleptic Gregorian
1160 * Calendar which extends the Gregorian calendar backwards to year one. It is
1161 * encoded assuming all minutes are 60 seconds long, i.e. leap seconds are
1162 * "smeared" so that no leap second table is needed for interpretation. Range
1163 * is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z.
1164 *
1165 * @see https://github.com/google/protobuf/blob/master/src/google/protobuf/timestamp.proto
1166 */
1167 export class Timestamp {
1168 /**
1169 * Creates a new timestamp with the current date, with millisecond precision.
1170 *
1171 * @return A new `Timestamp` representing the current date.
1172 */
1173 static now(): Timestamp;
1174
1175 /**
1176 * Creates a new timestamp from the given date.
1177 *
1178 * @param date The date to initialize the `Timestamp` from.
1179 * @return A new `Timestamp` representing the same point in time as the
1180 * given date.
1181 */
1182 static fromDate(date: Date): Timestamp;
1183
1184 /**
1185 * Creates a new timestamp from the given number of milliseconds.
1186 *
1187 * @param milliseconds Number of milliseconds since Unix epoch
1188 * 1970-01-01T00:00:00Z.
1189 * @return A new `Timestamp` representing the same point in time as the
1190 * given number of milliseconds.
1191 */
1192 static fromMillis(milliseconds: number): Timestamp;
1193
1194 /**
1195 * Creates a new timestamp.
1196 *
1197 * @param seconds The number of seconds of UTC time since Unix epoch
1198 * 1970-01-01T00:00:00Z. Must be from 0001-01-01T00:00:00Z to
1199 * 9999-12-31T23:59:59Z inclusive.
1200 * @param nanoseconds The non-negative fractions of a second at nanosecond
1201 * resolution. Negative second values with fractions must still have
1202 * non-negative nanoseconds values that count forward in time. Must be from
1203 * 0 to 999,999,999 inclusive.
1204 */
1205 constructor(seconds: number, nanoseconds: number);
1206
1207 /**
1208 * The number of seconds of UTC time since Unix epoch 1970-01-01T00:00:00Z.
1209 */
1210 readonly seconds: number;
1211
1212 /** The non-negative fractions of a second at nanosecond resolution. */
1213 readonly nanoseconds: number;
1214
1215 /**
1216 * Returns a new `Date` corresponding to this timestamp. This may lose
1217 * precision.
1218 *
1219 * @return JavaScript `Date` object representing the same point in time as
1220 * this `Timestamp`, with millisecond precision.
1221 */
1222 toDate(): Date;
1223
1224 /**
1225 * Returns the number of milliseconds since Unix epoch 1970-01-01T00:00:00Z.
1226 *
1227 * @return The point in time corresponding to this timestamp, represented as
1228 * the number of milliseconds since Unix epoch 1970-01-01T00:00:00Z.
1229 */
1230 toMillis(): number;
1231
1232 /**
1233 * Returns true if this `Timestamp` is equal to the provided one.
1234 *
1235 * @param other The `Timestamp` to compare against.
1236 * @return 'true' if this `Timestamp` is equal to the provided one.
1237 */
1238 isEqual(other: Timestamp): boolean;
1239 }
1240}
1241
1242declare module '@google-cloud/firestore' {
1243 export = FirebaseFirestore;
1244}