UNPKG

91.4 kBTypeScriptView Raw
1/**
2 * Cloud Firestore
3 *
4 * @packageDocumentation
5 */
6import { FirebaseApp } from '@firebase/app';
7import { LogLevelString as LogLevel } from '@firebase/logger';
8import { EmulatorMockTokenOptions } from '@firebase/util';
9
10/**
11 * Add a new document to specified `CollectionReference` with the given data,
12 * assigning it a document ID automatically.
13 *
14 * @param reference - A reference to the collection to add this document to.
15 * @param data - An Object containing the data for the new document.
16 * @returns A `Promise` resolved with a `DocumentReference` pointing to the
17 * newly created document after it has been written to the backend (Note that it
18 * won't resolve while you're offline).
19 */
20export declare function addDoc<T>(reference: CollectionReference<T>, data: WithFieldValue<T>): Promise<DocumentReference<T>>;
21/**
22 * Returns a new map where every key is prefixed with the outer key appended
23 * to a dot.
24 */
25export declare type AddPrefixToKeys<Prefix extends string, T extends Record<string, unknown>> = {
26 [K in keyof T & string as `${Prefix}.${K}`]+?: T[K];
27};
28/**
29 * Returns a special value that can be used with {@link (setDoc:1)} or {@link
30 * updateDoc:1} that tells the server to remove the given elements from any
31 * array value that already exists on the server. All instances of each element
32 * specified will be removed from the array. If the field being modified is not
33 * already an array it will be overwritten with an empty array.
34 *
35 * @param elements - The elements to remove from the array.
36 * @returns The `FieldValue` sentinel for use in a call to `setDoc()` or
37 * `updateDoc()`
38 */
39export declare function arrayRemove(...elements: unknown[]): FieldValue;
40/**
41 * Returns a special value that can be used with {@link @firebase/firestore/lite#(setDoc:1)} or {@link
42 * @firebase/firestore/lite#(updateDoc:1)} that tells the server to union the given elements with any array
43 * value that already exists on the server. Each specified element that doesn't
44 * already exist in the array will be added to the end. If the field being
45 * modified is not already an array it will be overwritten with an array
46 * containing exactly the specified elements.
47 *
48 * @param elements - The elements to union into the array.
49 * @returns The `FieldValue` sentinel for use in a call to `setDoc()` or
50 * `updateDoc()`.
51 */
52export declare function arrayUnion(...elements: unknown[]): FieldValue;
53/**
54 * An immutable object representing an array of bytes.
55 */
56export declare class Bytes {
57 private constructor();
58 /**
59 * Creates a new `Bytes` object from the given Base64 string, converting it to
60 * bytes.
61 *
62 * @param base64 - The Base64 string used to create the `Bytes` object.
63 */
64 static fromBase64String(base64: string): Bytes;
65 /**
66 * Creates a new `Bytes` object from the given Uint8Array.
67 *
68 * @param array - The Uint8Array used to create the `Bytes` object.
69 */
70 static fromUint8Array(array: Uint8Array): Bytes;
71 /**
72 * Returns the underlying bytes as a Base64-encoded string.
73 *
74 * @returns The Base64-encoded string created from the `Bytes` object.
75 */
76 toBase64(): string;
77 /**
78 * Returns the underlying bytes in a new `Uint8Array`.
79 *
80 * @returns The Uint8Array created from the `Bytes` object.
81 */
82 toUint8Array(): Uint8Array;
83 /**
84 * Returns a string representation of the `Bytes` object.
85 *
86 * @returns A string representation of the `Bytes` object.
87 */
88 toString(): string;
89 /**
90 * Returns true if this `Bytes` object is equal to the provided one.
91 *
92 * @param other - The `Bytes` object to compare against.
93 * @returns true if this `Bytes` object is equal to the provided one.
94 */
95 isEqual(other: Bytes): boolean;
96}
97/* Excluded from this release type: _ByteString */
98/**
99 * Constant used to indicate the LRU garbage collection should be disabled.
100 * Set this value as the `cacheSizeBytes` on the settings passed to the
101 * {@link Firestore} instance.
102 */
103export declare const CACHE_SIZE_UNLIMITED = -1;
104/**
105 * Helper for calculating the nested fields for a given type T1. This is needed
106 * to distribute union types such as `undefined | {...}` (happens for optional
107 * props) or `{a: A} | {b: B}`.
108 *
109 * In this use case, `V` is used to distribute the union types of `T[K]` on
110 * `Record`, since `T[K]` is evaluated as an expression and not distributed.
111 *
112 * See https://www.typescriptlang.org/docs/handbook/advanced-types.html#distributive-conditional-types
113 */
114export declare type ChildUpdateFields<K extends string, V> = V extends Record<string, unknown> ? AddPrefixToKeys<K, UpdateData<V>> : never;
115/**
116 * Clears the persistent storage. This includes pending writes and cached
117 * documents.
118 *
119 * Must be called while the {@link Firestore} instance is not started (after the app is
120 * terminated or when the app is first initialized). On startup, this function
121 * must be called before other functions (other than {@link
122 * initializeFirestore} or {@link getFirestore})). If the {@link Firestore}
123 * instance is still running, the promise will be rejected with the error code
124 * of `failed-precondition`.
125 *
126 * Note: `clearIndexedDbPersistence()` is primarily intended to help write
127 * reliable tests that use Cloud Firestore. It uses an efficient mechanism for
128 * dropping existing data but does not attempt to securely overwrite or
129 * otherwise make cached data unrecoverable. For applications that are sensitive
130 * to the disclosure of cached data in between user sessions, we strongly
131 * recommend not enabling persistence at all.
132 *
133 * @param firestore - The {@link Firestore} instance to clear persistence for.
134 * @returns A `Promise` that is resolved when the persistent storage is
135 * cleared. Otherwise, the promise is rejected with an error.
136 */
137export declare function clearIndexedDbPersistence(firestore: Firestore): Promise<void>;
138/**
139 * Gets a `CollectionReference` instance that refers to the collection at
140 * the specified absolute path.
141 *
142 * @param firestore - A reference to the root `Firestore` instance.
143 * @param path - A slash-separated path to a collection.
144 * @param pathSegments - Additional path segments to apply relative to the first
145 * argument.
146 * @throws If the final path has an even number of segments and does not point
147 * to a collection.
148 * @returns The `CollectionReference` instance.
149 */
150export declare function collection(firestore: Firestore, path: string, ...pathSegments: string[]): CollectionReference<DocumentData>;
151/**
152 * Gets a `CollectionReference` instance that refers to a subcollection of
153 * `reference` at the the specified relative path.
154 *
155 * @param reference - A reference to a collection.
156 * @param path - A slash-separated path to a collection.
157 * @param pathSegments - Additional path segments to apply relative to the first
158 * argument.
159 * @throws If the final path has an even number of segments and does not point
160 * to a collection.
161 * @returns The `CollectionReference` instance.
162 */
163export declare function collection(reference: CollectionReference<unknown>, path: string, ...pathSegments: string[]): CollectionReference<DocumentData>;
164/**
165 * Gets a `CollectionReference` instance that refers to a subcollection of
166 * `reference` at the the specified relative path.
167 *
168 * @param reference - A reference to a Firestore document.
169 * @param path - A slash-separated path to a collection.
170 * @param pathSegments - Additional path segments that will be applied relative
171 * to the first argument.
172 * @throws If the final path has an even number of segments and does not point
173 * to a collection.
174 * @returns The `CollectionReference` instance.
175 */
176export declare function collection(reference: DocumentReference, path: string, ...pathSegments: string[]): CollectionReference<DocumentData>;
177/**
178 * Creates and returns a new `Query` instance that includes all documents in the
179 * database that are contained in a collection or subcollection with the
180 * given `collectionId`.
181 *
182 * @param firestore - A reference to the root `Firestore` instance.
183 * @param collectionId - Identifies the collections to query over. Every
184 * collection or subcollection with this ID as the last segment of its path
185 * will be included. Cannot contain a slash.
186 * @returns The created `Query`.
187 */
188export declare function collectionGroup(firestore: Firestore, collectionId: string): Query<DocumentData>;
189/**
190 * A `CollectionReference` object can be used for adding documents, getting
191 * document references, and querying for documents (using {@link query}).
192 */
193export declare class CollectionReference<T = DocumentData> extends Query<T> {
194 /** The type of this Firestore reference. */
195 readonly type = "collection";
196 private constructor();
197 /** The collection's identifier. */
198 get id(): string;
199 /**
200 * A string representing the path of the referenced collection (relative
201 * to the root of the database).
202 */
203 get path(): string;
204 /**
205 * A reference to the containing `DocumentReference` if this is a
206 * subcollection. If this isn't a subcollection, the reference is null.
207 */
208 get parent(): DocumentReference<DocumentData> | null;
209 /**
210 * Applies a custom data converter to this `CollectionReference`, allowing you
211 * to use your own custom model objects with Firestore. When you call {@link
212 * addDoc} with the returned `CollectionReference` instance, the provided
213 * converter will convert between Firestore data and your custom type `U`.
214 *
215 * @param converter - Converts objects to and from Firestore.
216 * @returns A `CollectionReference<U>` that uses the provided converter.
217 */
218 withConverter<U>(converter: FirestoreDataConverter<U>): CollectionReference<U>;
219 /**
220 * Removes the current converter.
221 *
222 * @param converter - `null` removes the current converter.
223 * @returns A `CollectionReference<DocumentData>` that does not use a
224 * converter.
225 */
226 withConverter(converter: null): CollectionReference<DocumentData>;
227}
228/**
229 * Modify this instance to communicate with the Cloud Firestore emulator.
230 *
231 * Note: This must be called before this instance has been used to do any
232 * operations.
233 *
234 * @param firestore - The `Firestore` instance to configure to connect to the
235 * emulator.
236 * @param host - the emulator host (ex: localhost).
237 * @param port - the emulator port (ex: 9000).
238 * @param options.mockUserToken - the mock auth token to use for unit testing
239 * Security Rules.
240 */
241export declare function connectFirestoreEmulator(firestore: Firestore, host: string, port: number, options?: {
242 mockUserToken?: EmulatorMockTokenOptions | string;
243}): void;
244/**
245 * Deletes the document referred to by the specified `DocumentReference`.
246 *
247 * @param reference - A reference to the document to delete.
248 * @returns A Promise resolved once the document has been successfully
249 * deleted from the backend (note that it won't resolve while you're offline).
250 */
251export declare function deleteDoc(reference: DocumentReference<unknown>): Promise<void>;
252/**
253 * Returns a sentinel for use with {@link @firebase/firestore/lite#(updateDoc:1)} or
254 * {@link @firebase/firestore/lite#(setDoc:1)} with `{merge: true}` to mark a field for deletion.
255 */
256export declare function deleteField(): FieldValue;
257/**
258 * Disables network usage for this instance. It can be re-enabled via {@link
259 * enableNetwork}. While the network is disabled, any snapshot listeners,
260 * `getDoc()` or `getDocs()` calls will return results from cache, and any write
261 * operations will be queued until the network is restored.
262 *
263 * @returns A `Promise` that is resolved once the network has been disabled.
264 */
265export declare function disableNetwork(firestore: Firestore): Promise<void>;
266/**
267 * Gets a `DocumentReference` instance that refers to the document at the
268 * specified absolute path.
269 *
270 * @param firestore - A reference to the root `Firestore` instance.
271 * @param path - A slash-separated path to a document.
272 * @param pathSegments - Additional path segments that will be applied relative
273 * to the first argument.
274 * @throws If the final path has an odd number of segments and does not point to
275 * a document.
276 * @returns The `DocumentReference` instance.
277 */
278export declare function doc(firestore: Firestore, path: string, ...pathSegments: string[]): DocumentReference<DocumentData>;
279/**
280 * Gets a `DocumentReference` instance that refers to a document within
281 * `reference` at the specified relative path. If no path is specified, an
282 * automatically-generated unique ID will be used for the returned
283 * `DocumentReference`.
284 *
285 * @param reference - A reference to a collection.
286 * @param path - A slash-separated path to a document. Has to be omitted to use
287 * auto-genrated IDs.
288 * @param pathSegments - Additional path segments that will be applied relative
289 * to the first argument.
290 * @throws If the final path has an odd number of segments and does not point to
291 * a document.
292 * @returns The `DocumentReference` instance.
293 */
294export declare function doc<T>(reference: CollectionReference<T>, path?: string, ...pathSegments: string[]): DocumentReference<T>;
295/**
296 * Gets a `DocumentReference` instance that refers to a document within
297 * `reference` at the specified relative path.
298 *
299 * @param reference - A reference to a Firestore document.
300 * @param path - A slash-separated path to a document.
301 * @param pathSegments - Additional path segments that will be applied relative
302 * to the first argument.
303 * @throws If the final path has an odd number of segments and does not point to
304 * a document.
305 * @returns The `DocumentReference` instance.
306 */
307export declare function doc(reference: DocumentReference<unknown>, path: string, ...pathSegments: string[]): DocumentReference<DocumentData>;
308/**
309 * A `DocumentChange` represents a change to the documents matching a query.
310 * It contains the document affected and the type of change that occurred.
311 */
312export declare interface DocumentChange<T = DocumentData> {
313 /** The type of change ('added', 'modified', or 'removed'). */
314 readonly type: DocumentChangeType;
315 /** The document affected by this change. */
316 readonly doc: QueryDocumentSnapshot<T>;
317 /**
318 * The index of the changed document in the result set immediately prior to
319 * this `DocumentChange` (i.e. supposing that all prior `DocumentChange` objects
320 * have been applied). Is `-1` for 'added' events.
321 */
322 readonly oldIndex: number;
323 /**
324 * The index of the changed document in the result set immediately after
325 * this `DocumentChange` (i.e. supposing that all prior `DocumentChange`
326 * objects and the current `DocumentChange` object have been applied).
327 * Is -1 for 'removed' events.
328 */
329 readonly newIndex: number;
330}
331/**
332 * The type of a `DocumentChange` may be 'added', 'removed', or 'modified'.
333 */
334export declare type DocumentChangeType = 'added' | 'removed' | 'modified';
335/**
336 * Document data (for use with {@link @firebase/firestore/lite#(setDoc:1)}) consists of fields mapped to
337 * values.
338 */
339export declare interface DocumentData {
340 /** A mapping between a field and its value. */
341 [field: string]: any;
342}
343/**
344 * Returns a special sentinel `FieldPath` to refer to the ID of a document.
345 * It can be used in queries to sort or filter by the document ID.
346 */
347export declare function documentId(): FieldPath;
348/**
349 * A `DocumentReference` refers to a document location in a Firestore database
350 * and can be used to write, read, or listen to the location. The document at
351 * the referenced location may or may not exist.
352 */
353export declare class DocumentReference<T = DocumentData> {
354 /**
355 * If provided, the `FirestoreDataConverter` associated with this instance.
356 */
357 readonly converter: FirestoreDataConverter<T> | null;
358 /** The type of this Firestore reference. */
359 readonly type = "document";
360 /**
361 * The {@link Firestore} instance the document is in.
362 * This is useful for performing transactions, for example.
363 */
364 readonly firestore: Firestore;
365 private constructor();
366 /**
367 * The document's identifier within its collection.
368 */
369 get id(): string;
370 /**
371 * A string representing the path of the referenced document (relative
372 * to the root of the database).
373 */
374 get path(): string;
375 /**
376 * The collection this `DocumentReference` belongs to.
377 */
378 get parent(): CollectionReference<T>;
379 /**
380 * Applies a custom data converter to this `DocumentReference`, allowing you
381 * to use your own custom model objects with Firestore. When you call {@link
382 * @firebase/firestore/lite#(setDoc:1)}, {@link @firebase/firestore/lite#getDoc}, etc. with the returned `DocumentReference`
383 * instance, the provided converter will convert between Firestore data and
384 * your custom type `U`.
385 *
386 * @param converter - Converts objects to and from Firestore.
387 * @returns A `DocumentReference<U>` that uses the provided converter.
388 */
389 withConverter<U>(converter: FirestoreDataConverter<U>): DocumentReference<U>;
390 /**
391 * Removes the current converter.
392 *
393 * @param converter - `null` removes the current converter.
394 * @returns A `DocumentReference<DocumentData>` that does not use a converter.
395 */
396 withConverter(converter: null): DocumentReference<DocumentData>;
397}
398/**
399 * A `DocumentSnapshot` contains data read from a document in your Firestore
400 * database. The data can be extracted with `.data()` or `.get(<field>)` to
401 * get a specific field.
402 *
403 * For a `DocumentSnapshot` that points to a non-existing document, any data
404 * access will return 'undefined'. You can use the `exists()` method to
405 * explicitly verify a document's existence.
406 */
407export declare class DocumentSnapshot<T = DocumentData> {
408 /**
409 * Metadata about the `DocumentSnapshot`, including information about its
410 * source and local modifications.
411 */
412 readonly metadata: SnapshotMetadata;
413 protected constructor();
414 /**
415 * Property of the `DocumentSnapshot` that signals whether or not the data
416 * exists. True if the document exists.
417 */
418 exists(): this is QueryDocumentSnapshot<T>;
419 /**
420 * Retrieves all fields in the document as an `Object`. Returns `undefined` if
421 * the document doesn't exist.
422 *
423 * By default, `FieldValue.serverTimestamp()` values that have not yet been
424 * set to their final value will be returned as `null`. You can override
425 * this by passing an options object.
426 *
427 * @param options - An options object to configure how data is retrieved from
428 * the snapshot (for example the desired behavior for server timestamps that
429 * have not yet been set to their final value).
430 * @returns An `Object` containing all fields in the document or `undefined` if
431 * the document doesn't exist.
432 */
433 data(options?: SnapshotOptions): T | undefined;
434 /**
435 * Retrieves the field specified by `fieldPath`. Returns `undefined` if the
436 * document or field doesn't exist.
437 *
438 * By default, a `FieldValue.serverTimestamp()` that has not yet been set to
439 * its final value will be returned as `null`. You can override this by
440 * passing an options object.
441 *
442 * @param fieldPath - The path (for example 'foo' or 'foo.bar') to a specific
443 * field.
444 * @param options - An options object to configure how the field is retrieved
445 * from the snapshot (for example the desired behavior for server timestamps
446 * that have not yet been set to their final value).
447 * @returns The data at the specified field location or undefined if no such
448 * field exists in the document.
449 */
450 get(fieldPath: string | FieldPath, options?: SnapshotOptions): any;
451 /**
452 * Property of the `DocumentSnapshot` that provides the document's ID.
453 */
454 get id(): string;
455 /**
456 * The `DocumentReference` for the document included in the `DocumentSnapshot`.
457 */
458 get ref(): DocumentReference<T>;
459}
460/* Excluded from this release type: _EmptyCredentialsProvider */
461export { EmulatorMockTokenOptions };
462/**
463 * Attempts to enable persistent storage, if possible.
464 *
465 * Must be called before any other functions (other than
466 * {@link initializeFirestore}, {@link getFirestore} or
467 * {@link clearIndexedDbPersistence}.
468 *
469 * If this fails, `enableIndexedDbPersistence()` will reject the promise it
470 * returns. Note that even after this failure, the {@link Firestore} instance will
471 * remain usable, however offline persistence will be disabled.
472 *
473 * There are several reasons why this can fail, which can be identified by
474 * the `code` on the error.
475 *
476 * * failed-precondition: The app is already open in another browser tab.
477 * * unimplemented: The browser is incompatible with the offline
478 * persistence implementation.
479 *
480 * @param firestore - The {@link Firestore} instance to enable persistence for.
481 * @param persistenceSettings - Optional settings object to configure
482 * persistence.
483 * @returns A `Promise` that represents successfully enabling persistent storage.
484 */
485export declare function enableIndexedDbPersistence(firestore: Firestore, persistenceSettings?: PersistenceSettings): Promise<void>;
486/**
487 * Attempts to enable multi-tab persistent storage, if possible. If enabled
488 * across all tabs, all operations share access to local persistence, including
489 * shared execution of queries and latency-compensated local document updates
490 * across all connected instances.
491 *
492 * If this fails, `enableMultiTabIndexedDbPersistence()` will reject the promise
493 * it returns. Note that even after this failure, the {@link Firestore} instance will
494 * remain usable, however offline persistence will be disabled.
495 *
496 * There are several reasons why this can fail, which can be identified by
497 * the `code` on the error.
498 *
499 * * failed-precondition: The app is already open in another browser tab and
500 * multi-tab is not enabled.
501 * * unimplemented: The browser is incompatible with the offline
502 * persistence implementation.
503 *
504 * @param firestore - The {@link Firestore} instance to enable persistence for.
505 * @returns A `Promise` that represents successfully enabling persistent
506 * storage.
507 */
508export declare function enableMultiTabIndexedDbPersistence(firestore: Firestore): Promise<void>;
509/**
510 * Re-enables use of the network for this {@link Firestore} instance after a prior
511 * call to {@link disableNetwork}.
512 *
513 * @returns A `Promise` that is resolved once the network has been enabled.
514 */
515export declare function enableNetwork(firestore: Firestore): Promise<void>;
516/**
517 * Creates a {@link QueryConstraint} that modifies the result set to end at the
518 * provided document (inclusive). The end position is relative to the order of
519 * the query. The document must contain all of the fields provided in the
520 * orderBy of the query.
521 *
522 * @param snapshot - The snapshot of the document to end at.
523 * @returns A {@link QueryConstraint} to pass to `query()`
524 */
525export declare function endAt(snapshot: DocumentSnapshot<unknown>): QueryConstraint;
526/**
527 * Creates a {@link QueryConstraint} that modifies the result set to end at the
528 * provided fields relative to the order of the query. The order of the field
529 * values must match the order of the order by clauses of the query.
530 *
531 * @param fieldValues - The field values to end this query at, in order
532 * of the query's order by.
533 * @returns A {@link QueryConstraint} to pass to `query()`
534 */
535export declare function endAt(...fieldValues: unknown[]): QueryConstraint;
536/**
537 * Creates a {@link QueryConstraint} that modifies the result set to end before the
538 * provided document (exclusive). The end position is relative to the order of
539 * the query. The document must contain all of the fields provided in the
540 * orderBy of the query.
541 *
542 * @param snapshot - The snapshot of the document to end before.
543 * @returns A {@link QueryConstraint} to pass to `query()`
544 */
545export declare function endBefore(snapshot: DocumentSnapshot<unknown>): QueryConstraint;
546/**
547 * Creates a {@link QueryConstraint} that modifies the result set to end before the
548 * provided fields relative to the order of the query. The order of the field
549 * values must match the order of the order by clauses of the query.
550 *
551 * @param fieldValues - The field values to end this query before, in order
552 * of the query's order by.
553 * @returns A {@link QueryConstraint} to pass to `query()`
554 */
555export declare function endBefore(...fieldValues: unknown[]): QueryConstraint;
556/**
557 * A `FieldPath` refers to a field in a document. The path may consist of a
558 * single field name (referring to a top-level field in the document), or a
559 * list of field names (referring to a nested field in the document).
560 *
561 * Create a `FieldPath` by providing field names. If more than one field
562 * name is provided, the path will point to a nested field in a document.
563 */
564export declare class FieldPath {
565 /**
566 * Creates a `FieldPath` from the provided field names. If more than one field
567 * name is provided, the path will point to a nested field in a document.
568 *
569 * @param fieldNames - A list of field names.
570 */
571 constructor(...fieldNames: string[]);
572 /**
573 * Returns true if this `FieldPath` is equal to the provided one.
574 *
575 * @param other - The `FieldPath` to compare against.
576 * @returns true if this `FieldPath` is equal to the provided one.
577 */
578 isEqual(other: FieldPath): boolean;
579}
580/**
581 * Sentinel values that can be used when writing document fields with `set()`
582 * or `update()`.
583 */
584export declare abstract class FieldValue {
585 private constructor();
586 /** Compares `FieldValue`s for equality. */
587 abstract isEqual(other: FieldValue): boolean;
588}
589/* Excluded from this release type: _FirebaseService */
590/**
591 * The Cloud Firestore service interface.
592 *
593 * Do not call this constructor directly. Instead, use {@link getFirestore}.
594 */
595export declare class Firestore {
596 /**
597 * Whether it's a {@link Firestore} or Firestore Lite instance.
598 */
599 type: 'firestore-lite' | 'firestore';
600 private constructor();
601 /**
602 * The {@link @firebase/app#FirebaseApp} associated with this `Firestore` service
603 * instance.
604 */
605 get app(): FirebaseApp;
606 /**
607 * Returns a JSON-serializable representation of this `Firestore` instance.
608 */
609 toJSON(): object;
610}
611/**
612 * Converter used by `withConverter()` to transform user objects of type `T`
613 * into Firestore data.
614 *
615 * Using the converter allows you to specify generic type arguments when
616 * storing and retrieving objects from Firestore.
617 *
618 * @example
619 * ```typescript
620 * class Post {
621 * constructor(readonly title: string, readonly author: string) {}
622 *
623 * toString(): string {
624 * return this.title + ', by ' + this.author;
625 * }
626 * }
627 *
628 * const postConverter = {
629 * toFirestore(post: WithFieldValue<Post>): firebase.firestore.DocumentData {
630 * return {title: post.title, author: post.author};
631 * },
632 * fromFirestore(
633 * snapshot: firebase.firestore.QueryDocumentSnapshot,
634 * options: firebase.firestore.SnapshotOptions
635 * ): Post {
636 * const data = snapshot.data(options)!;
637 * return new Post(data.title, data.author);
638 * }
639 * };
640 *
641 * const postSnap = await firebase.firestore()
642 * .collection('posts')
643 * .withConverter(postConverter)
644 * .doc().get();
645 * const post = postSnap.data();
646 * if (post !== undefined) {
647 * post.title; // string
648 * post.toString(); // Should be defined
649 * post.someNonExistentProperty; // TS error
650 * }
651 * ```
652 */
653export declare interface FirestoreDataConverter<T> {
654 /**
655 * Called by the Firestore SDK to convert a custom model object of type `T`
656 * into a plain JavaScript object (suitable for writing directly to the
657 * Firestore database). To use `set()` with `merge` and `mergeFields`,
658 * `toFirestore()` must be defined with `PartialWithFieldValue<T>`.
659 *
660 * The `WithFieldValue<T>` type extends `T` to also allow FieldValues such as
661 * {@link (deleteField:1)} to be used as property values.
662 */
663 toFirestore(modelObject: WithFieldValue<T>): DocumentData;
664 /**
665 * Called by the Firestore SDK to convert a custom model object of type `T`
666 * into a plain JavaScript object (suitable for writing directly to the
667 * Firestore database). Used with {@link (setDoc:1)}, {@link (WriteBatch.set:1)}
668 * and {@link (Transaction.set:1)} with `merge:true` or `mergeFields`.
669 *
670 * The `PartialWithFieldValue<T>` type extends `Partial<T>` to allow
671 * FieldValues such as {@link (arrayUnion:1)} to be used as property values.
672 * It also supports nested `Partial` by allowing nested fields to be
673 * omitted.
674 */
675 toFirestore(modelObject: PartialWithFieldValue<T>, options: SetOptions): DocumentData;
676 /**
677 * Called by the Firestore SDK to convert Firestore data into an object of
678 * type T. You can access your data by calling: `snapshot.data(options)`.
679 *
680 * @param snapshot - A `QueryDocumentSnapshot` containing your data and metadata.
681 * @param options - The `SnapshotOptions` from the initial call to `data()`.
682 */
683 fromFirestore(snapshot: QueryDocumentSnapshot<DocumentData>, options?: SnapshotOptions): T;
684}
685/** An error returned by a Firestore operation. */
686export declare class FirestoreError extends Error {
687 /**
688 * The backend error code associated with this error.
689 */
690 readonly code: FirestoreErrorCode;
691 /**
692 * A custom error description.
693 */
694 readonly message: string;
695 /** The custom name for all FirestoreErrors. */
696 readonly name: string;
697 /** The stack of the error. */
698 readonly stack?: string;
699 private constructor();
700}
701/**
702 * @license
703 * Copyright 2017 Google LLC
704 *
705 * Licensed under the Apache License, Version 2.0 (the "License");
706 * you may not use this file except in compliance with the License.
707 * You may obtain a copy of the License at
708 *
709 * http://www.apache.org/licenses/LICENSE-2.0
710 *
711 * Unless required by applicable law or agreed to in writing, software
712 * distributed under the License is distributed on an "AS IS" BASIS,
713 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
714 * See the License for the specific language governing permissions and
715 * limitations under the License.
716 */
717/**
718 * The set of Firestore status codes. The codes are the same at the ones
719 * exposed by gRPC here:
720 * https://github.com/grpc/grpc/blob/master/doc/statuscodes.md
721 *
722 * Possible values:
723 * - 'cancelled': The operation was cancelled (typically by the caller).
724 * - 'unknown': Unknown error or an error from a different error domain.
725 * - 'invalid-argument': Client specified an invalid argument. Note that this
726 * differs from 'failed-precondition'. 'invalid-argument' indicates
727 * arguments that are problematic regardless of the state of the system
728 * (e.g. an invalid field name).
729 * - 'deadline-exceeded': Deadline expired before operation could complete.
730 * For operations that change the state of the system, this error may be
731 * returned even if the operation has completed successfully. For example,
732 * a successful response from a server could have been delayed long enough
733 * for the deadline to expire.
734 * - 'not-found': Some requested document was not found.
735 * - 'already-exists': Some document that we attempted to create already
736 * exists.
737 * - 'permission-denied': The caller does not have permission to execute the
738 * specified operation.
739 * - 'resource-exhausted': Some resource has been exhausted, perhaps a
740 * per-user quota, or perhaps the entire file system is out of space.
741 * - 'failed-precondition': Operation was rejected because the system is not
742 * in a state required for the operation's execution.
743 * - 'aborted': The operation was aborted, typically due to a concurrency
744 * issue like transaction aborts, etc.
745 * - 'out-of-range': Operation was attempted past the valid range.
746 * - 'unimplemented': Operation is not implemented or not supported/enabled.
747 * - 'internal': Internal errors. Means some invariants expected by
748 * underlying system has been broken. If you see one of these errors,
749 * something is very broken.
750 * - 'unavailable': The service is currently unavailable. This is most likely
751 * a transient condition and may be corrected by retrying with a backoff.
752 * - 'data-loss': Unrecoverable data loss or corruption.
753 * - 'unauthenticated': The request does not have valid authentication
754 * credentials for the operation.
755 */
756export 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';
757/**
758 * Specifies custom configurations for your Cloud Firestore instance.
759 * You must set these before invoking any other methods.
760 */
761export declare interface FirestoreSettings {
762 /**
763 * An approximate cache size threshold for the on-disk data. If the cache
764 * grows beyond this size, Firestore will start removing data that hasn't been
765 * recently used. The size is not a guarantee that the cache will stay below
766 * that size, only that if the cache exceeds the given size, cleanup will be
767 * attempted.
768 *
769 * The default value is 40 MB. The threshold must be set to at least 1 MB, and
770 * can be set to `CACHE_SIZE_UNLIMITED` to disable garbage collection.
771 */
772 cacheSizeBytes?: number;
773 /**
774 * Forces the SDK’s underlying network transport (WebChannel) to use
775 * long-polling. Each response from the backend will be closed immediately
776 * after the backend sends data (by default responses are kept open in
777 * case the backend has more data to send). This avoids incompatibility
778 * issues with certain proxies, antivirus software, etc. that incorrectly
779 * buffer traffic indefinitely. Use of this option will cause some
780 * performance degradation though.
781 *
782 * This setting cannot be used with `experimentalAutoDetectLongPolling` and
783 * may be removed in a future release. If you find yourself using it to
784 * work around a specific network reliability issue, please tell us about
785 * it in https://github.com/firebase/firebase-js-sdk/issues/1674.
786 */
787 experimentalForceLongPolling?: boolean;
788 /**
789 * Configures the SDK's underlying transport (WebChannel) to automatically
790 * detect if long-polling should be used. This is very similar to
791 * `experimentalForceLongPolling`, but only uses long-polling if required.
792 *
793 * This setting will likely be enabled by default in future releases and
794 * cannot be combined with `experimentalForceLongPolling`.
795 */
796 experimentalAutoDetectLongPolling?: boolean;
797 /**
798 * The hostname to connect to.
799 */
800 host?: string;
801 /**
802 * Whether to use SSL when connecting.
803 */
804 ssl?: boolean;
805 /**
806 * Whether to skip nested properties that are set to `undefined` during
807 * object serialization. If set to `true`, these properties are skipped
808 * and not written to Firestore. If set to `false` or omitted, the SDK
809 * throws an exception when it encounters properties of type `undefined`.
810 */
811 ignoreUndefinedProperties?: boolean;
812}
813/**
814 * @license
815 * Copyright 2017 Google LLC
816 *
817 * Licensed under the Apache License, Version 2.0 (the "License");
818 * you may not use this file except in compliance with the License.
819 * You may obtain a copy of the License at
820 *
821 * http://www.apache.org/licenses/LICENSE-2.0
822 *
823 * Unless required by applicable law or agreed to in writing, software
824 * distributed under the License is distributed on an "AS IS" BASIS,
825 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
826 * See the License for the specific language governing permissions and
827 * limitations under the License.
828 */
829/**
830 * An immutable object representing a geographic location in Firestore. The
831 * location is represented as latitude/longitude pair.
832 *
833 * Latitude values are in the range of [-90, 90].
834 * Longitude values are in the range of [-180, 180].
835 */
836export declare class GeoPoint {
837 /**
838 * Creates a new immutable `GeoPoint` object with the provided latitude and
839 * longitude values.
840 * @param latitude - The latitude as number between -90 and 90.
841 * @param longitude - The longitude as number between -180 and 180.
842 */
843 constructor(latitude: number, longitude: number);
844 /**
845 * The latitude of this `GeoPoint` instance.
846 */
847 get latitude(): number;
848 /**
849 * The longitude of this `GeoPoint` instance.
850 */
851 get longitude(): number;
852 /**
853 * Returns true if this `GeoPoint` is equal to the provided one.
854 *
855 * @param other - The `GeoPoint` to compare against.
856 * @returns true if this `GeoPoint` is equal to the provided one.
857 */
858 isEqual(other: GeoPoint): boolean;
859 /** Returns a JSON-serializable representation of this GeoPoint. */
860 toJSON(): {
861 latitude: number;
862 longitude: number;
863 };
864}
865/**
866 * Reads the document referred to by this `DocumentReference`.
867 *
868 * Note: `getDoc()` attempts to provide up-to-date data when possible by waiting
869 * for data from the server, but it may return cached data or fail if you are
870 * offline and the server cannot be reached. To specify this behavior, invoke
871 * {@link getDocFromCache} or {@link getDocFromServer}.
872 *
873 * @param reference - The reference of the document to fetch.
874 * @returns A Promise resolved with a `DocumentSnapshot` containing the
875 * current document contents.
876 */
877export declare function getDoc<T>(reference: DocumentReference<T>): Promise<DocumentSnapshot<T>>;
878/**
879 * Reads the document referred to by this `DocumentReference` from cache.
880 * Returns an error if the document is not currently cached.
881 *
882 * @returns A `Promise` resolved with a `DocumentSnapshot` containing the
883 * current document contents.
884 */
885export declare function getDocFromCache<T>(reference: DocumentReference<T>): Promise<DocumentSnapshot<T>>;
886/**
887 * Reads the document referred to by this `DocumentReference` from the server.
888 * Returns an error if the network is not available.
889 *
890 * @returns A `Promise` resolved with a `DocumentSnapshot` containing the
891 * current document contents.
892 */
893export declare function getDocFromServer<T>(reference: DocumentReference<T>): Promise<DocumentSnapshot<T>>;
894/**
895 * Executes the query and returns the results as a `QuerySnapshot`.
896 *
897 * Note: `getDocs()` attempts to provide up-to-date data when possible by
898 * waiting for data from the server, but it may return cached data or fail if
899 * you are offline and the server cannot be reached. To specify this behavior,
900 * invoke {@link getDocsFromCache} or {@link getDocsFromServer}.
901 *
902 * @returns A `Promise` that will be resolved with the results of the query.
903 */
904export declare function getDocs<T>(query: Query<T>): Promise<QuerySnapshot<T>>;
905/**
906 * Executes the query and returns the results as a `QuerySnapshot` from cache.
907 * Returns an error if the document is not currently cached.
908 *
909 * @returns A `Promise` that will be resolved with the results of the query.
910 */
911export declare function getDocsFromCache<T>(query: Query<T>): Promise<QuerySnapshot<T>>;
912/**
913 * Executes the query and returns the results as a `QuerySnapshot` from the
914 * server. Returns an error if the network is not available.
915 *
916 * @returns A `Promise` that will be resolved with the results of the query.
917 */
918export declare function getDocsFromServer<T>(query: Query<T>): Promise<QuerySnapshot<T>>;
919/**
920 * Returns the existing {@link Firestore} instance that is associated with the
921 * provided {@link @firebase/app#FirebaseApp}. If no instance exists, initializes a new
922 * instance with default settings.
923 *
924 * @param app - The {@link @firebase/app#FirebaseApp} instance that the returned {@link Firestore}
925 * instance is associated with.
926 * @returns The {@link Firestore} instance of the provided app.
927 */
928export declare function getFirestore(app?: FirebaseApp): Firestore;
929/**
930 * Returns a special value that can be used with {@link @firebase/firestore/lite#(setDoc:1)} or {@link
931 * @firebase/firestore/lite#(updateDoc:1)} that tells the server to increment the field's current value by
932 * the given value.
933 *
934 * If either the operand or the current field value uses floating point
935 * precision, all arithmetic follows IEEE 754 semantics. If both values are
936 * integers, values outside of JavaScript's safe number range
937 * (`Number.MIN_SAFE_INTEGER` to `Number.MAX_SAFE_INTEGER`) are also subject to
938 * precision loss. Furthermore, once processed by the Firestore backend, all
939 * integer operations are capped between -2^63 and 2^63-1.
940 *
941 * If the current field value is not of type `number`, or if the field does not
942 * yet exist, the transformation sets the field to the given value.
943 *
944 * @param n - The value to increment by.
945 * @returns The `FieldValue` sentinel for use in a call to `setDoc()` or
946 * `updateDoc()`
947 */
948export declare function increment(n: number): FieldValue;
949/**
950 * Initializes a new instance of {@link Firestore} with the provided settings.
951 * Can only be called before any other function, including
952 * {@link getFirestore}. If the custom settings are empty, this function is
953 * equivalent to calling {@link getFirestore}.
954 *
955 * @param app - The {@link @firebase/app#FirebaseApp} with which the {@link Firestore} instance will
956 * be associated.
957 * @param settings - A settings object to configure the {@link Firestore} instance.
958 * @returns A newly initialized {@link Firestore} instance.
959 */
960export declare function initializeFirestore(app: FirebaseApp, settings: FirestoreSettings): Firestore;
961/* Excluded from this release type: _isBase64Available */
962/**
963 * Creates a {@link QueryConstraint} that only returns the first matching documents.
964 *
965 * @param limit - The maximum number of items to return.
966 * @returns The created {@link Query}.
967 */
968export declare function limit(limit: number): QueryConstraint;
969/**
970 * Creates a {@link QueryConstraint} that only returns the last matching documents.
971 *
972 * You must specify at least one `orderBy` clause for `limitToLast` queries,
973 * otherwise an exception will be thrown during execution.
974 *
975 * @param limit - The maximum number of items to return.
976 * @returns The created {@link Query}.
977 */
978export declare function limitToLast(limit: number): QueryConstraint;
979/**
980 * Loads a Firestore bundle into the local cache.
981 *
982 * @param firestore - The {@link Firestore} instance to load bundles for for.
983 * @param bundleData - An object representing the bundle to be loaded. Valid objects are
984 * `ArrayBuffer`, `ReadableStream<Uint8Array>` or `string`.
985 *
986 * @returns
987 * A `LoadBundleTask` object, which notifies callers with progress updates, and completion
988 * or error events. It can be used as a `Promise<LoadBundleTaskProgress>`.
989 */
990export declare function loadBundle(firestore: Firestore, bundleData: ReadableStream<Uint8Array> | ArrayBuffer | string): LoadBundleTask;
991/**
992 * Represents the task of loading a Firestore bundle. It provides progress of bundle
993 * loading, as well as task completion and error events.
994 *
995 * The API is compatible with `Promise<LoadBundleTaskProgress>`.
996 */
997export declare class LoadBundleTask implements PromiseLike<LoadBundleTaskProgress> {
998 /**
999 * Registers functions to listen to bundle loading progress events.
1000 * @param next - Called when there is a progress update from bundle loading. Typically `next` calls occur
1001 * each time a Firestore document is loaded from the bundle.
1002 * @param error - Called when an error occurs during bundle loading. The task aborts after reporting the
1003 * error, and there should be no more updates after this.
1004 * @param complete - Called when the loading task is complete.
1005 */
1006 onProgress(next?: (progress: LoadBundleTaskProgress) => unknown, error?: (err: Error) => unknown, complete?: () => void): void;
1007 /**
1008 * Implements the `Promise<LoadBundleTaskProgress>.catch` interface.
1009 *
1010 * @param onRejected - Called when an error occurs during bundle loading.
1011 */
1012 catch<R>(onRejected: (a: Error) => R | PromiseLike<R>): Promise<R | LoadBundleTaskProgress>;
1013 /**
1014 * Implements the `Promise<LoadBundleTaskProgress>.then` interface.
1015 *
1016 * @param onFulfilled - Called on the completion of the loading task with a final `LoadBundleTaskProgress` update.
1017 * The update will always have its `taskState` set to `"Success"`.
1018 * @param onRejected - Called when an error occurs during bundle loading.
1019 */
1020 then<T, R>(onFulfilled?: (a: LoadBundleTaskProgress) => T | PromiseLike<T>, onRejected?: (a: Error) => R | PromiseLike<R>): Promise<T | R>;
1021}
1022/**
1023 * Represents a progress update or a final state from loading bundles.
1024 */
1025export declare interface LoadBundleTaskProgress {
1026 /** How many documents have been loaded. */
1027 documentsLoaded: number;
1028 /** How many documents are in the bundle being loaded. */
1029 totalDocuments: number;
1030 /** How many bytes have been loaded. */
1031 bytesLoaded: number;
1032 /** How many bytes are in the bundle being loaded. */
1033 totalBytes: number;
1034 /** Current task state. */
1035 taskState: TaskState;
1036}
1037export { LogLevel };
1038/**
1039 * Reads a Firestore {@link Query} from local cache, identified by the given name.
1040 *
1041 * The named queries are packaged into bundles on the server side (along
1042 * with resulting documents), and loaded to local cache using `loadBundle`. Once in local
1043 * cache, use this method to extract a {@link Query} by name.
1044 */
1045export declare function namedQuery(firestore: Firestore, name: string): Promise<Query | null>;
1046/**
1047 * For each field (e.g. 'bar'), find all nested keys (e.g. {'bar.baz': T1,
1048 * 'bar.qux': T2}). Intersect them together to make a single map containing
1049 * all possible keys that are all marked as optional
1050 */
1051export declare type NestedUpdateFields<T extends Record<string, unknown>> = UnionToIntersection<{
1052 [K in keyof T & string]: ChildUpdateFields<K, T[K]>;
1053}[keyof T & string]>;
1054/**
1055 * Attaches a listener for `DocumentSnapshot` events. You may either pass
1056 * individual `onNext` and `onError` callbacks or pass a single observer
1057 * object with `next` and `error` callbacks.
1058 *
1059 * NOTE: Although an `onCompletion` callback can be provided, it will
1060 * never be called because the snapshot stream is never-ending.
1061 *
1062 * @param reference - A reference to the document to listen to.
1063 * @param observer - A single object containing `next` and `error` callbacks.
1064 * @returns An unsubscribe function that can be called to cancel
1065 * the snapshot listener.
1066 */
1067export declare function onSnapshot<T>(reference: DocumentReference<T>, observer: {
1068 next?: (snapshot: DocumentSnapshot<T>) => void;
1069 error?: (error: FirestoreError) => void;
1070 complete?: () => void;
1071}): Unsubscribe;
1072/**
1073 * Attaches a listener for `DocumentSnapshot` events. You may either pass
1074 * individual `onNext` and `onError` callbacks or pass a single observer
1075 * object with `next` and `error` callbacks.
1076 *
1077 * NOTE: Although an `onCompletion` callback can be provided, it will
1078 * never be called because the snapshot stream is never-ending.
1079 *
1080 * @param reference - A reference to the document to listen to.
1081 * @param options - Options controlling the listen behavior.
1082 * @param observer - A single object containing `next` and `error` callbacks.
1083 * @returns An unsubscribe function that can be called to cancel
1084 * the snapshot listener.
1085 */
1086export declare function onSnapshot<T>(reference: DocumentReference<T>, options: SnapshotListenOptions, observer: {
1087 next?: (snapshot: DocumentSnapshot<T>) => void;
1088 error?: (error: FirestoreError) => void;
1089 complete?: () => void;
1090}): Unsubscribe;
1091/**
1092 * Attaches a listener for `DocumentSnapshot` events. You may either pass
1093 * individual `onNext` and `onError` callbacks or pass a single observer
1094 * object with `next` and `error` callbacks.
1095 *
1096 * NOTE: Although an `onCompletion` callback can be provided, it will
1097 * never be called because the snapshot stream is never-ending.
1098 *
1099 * @param reference - A reference to the document to listen to.
1100 * @param onNext - A callback to be called every time a new `DocumentSnapshot`
1101 * is available.
1102 * @param onError - A callback to be called if the listen fails or is
1103 * cancelled. No further callbacks will occur.
1104 * @param onCompletion - Can be provided, but will not be called since streams are
1105 * never ending.
1106 * @returns An unsubscribe function that can be called to cancel
1107 * the snapshot listener.
1108 */
1109export declare function onSnapshot<T>(reference: DocumentReference<T>, onNext: (snapshot: DocumentSnapshot<T>) => void, onError?: (error: FirestoreError) => void, onCompletion?: () => void): Unsubscribe;
1110/**
1111 * Attaches a listener for `DocumentSnapshot` events. You may either pass
1112 * individual `onNext` and `onError` callbacks or pass a single observer
1113 * object with `next` and `error` callbacks.
1114 *
1115 * NOTE: Although an `onCompletion` callback can be provided, it will
1116 * never be called because the snapshot stream is never-ending.
1117 *
1118 * @param reference - A reference to the document to listen to.
1119 * @param options - Options controlling the listen behavior.
1120 * @param onNext - A callback to be called every time a new `DocumentSnapshot`
1121 * is available.
1122 * @param onError - A callback to be called if the listen fails or is
1123 * cancelled. No further callbacks will occur.
1124 * @param onCompletion - Can be provided, but will not be called since streams are
1125 * never ending.
1126 * @returns An unsubscribe function that can be called to cancel
1127 * the snapshot listener.
1128 */
1129export declare function onSnapshot<T>(reference: DocumentReference<T>, options: SnapshotListenOptions, onNext: (snapshot: DocumentSnapshot<T>) => void, onError?: (error: FirestoreError) => void, onCompletion?: () => void): Unsubscribe;
1130/**
1131 * Attaches a listener for `QuerySnapshot` events. You may either pass
1132 * individual `onNext` and `onError` callbacks or pass a single observer
1133 * object with `next` and `error` callbacks. The listener can be cancelled by
1134 * calling the function that is returned when `onSnapshot` is called.
1135 *
1136 * NOTE: Although an `onCompletion` callback can be provided, it will
1137 * never be called because the snapshot stream is never-ending.
1138 *
1139 * @param query - The query to listen to.
1140 * @param observer - A single object containing `next` and `error` callbacks.
1141 * @returns An unsubscribe function that can be called to cancel
1142 * the snapshot listener.
1143 */
1144export declare function onSnapshot<T>(query: Query<T>, observer: {
1145 next?: (snapshot: QuerySnapshot<T>) => void;
1146 error?: (error: FirestoreError) => void;
1147 complete?: () => void;
1148}): Unsubscribe;
1149/**
1150 * Attaches a listener for `QuerySnapshot` events. You may either pass
1151 * individual `onNext` and `onError` callbacks or pass a single observer
1152 * object with `next` and `error` callbacks. The listener can be cancelled by
1153 * calling the function that is returned when `onSnapshot` is called.
1154 *
1155 * NOTE: Although an `onCompletion` callback can be provided, it will
1156 * never be called because the snapshot stream is never-ending.
1157 *
1158 * @param query - The query to listen to.
1159 * @param options - Options controlling the listen behavior.
1160 * @param observer - A single object containing `next` and `error` callbacks.
1161 * @returns An unsubscribe function that can be called to cancel
1162 * the snapshot listener.
1163 */
1164export declare function onSnapshot<T>(query: Query<T>, options: SnapshotListenOptions, observer: {
1165 next?: (snapshot: QuerySnapshot<T>) => void;
1166 error?: (error: FirestoreError) => void;
1167 complete?: () => void;
1168}): Unsubscribe;
1169/**
1170 * Attaches a listener for `QuerySnapshot` events. You may either pass
1171 * individual `onNext` and `onError` callbacks or pass a single observer
1172 * object with `next` and `error` callbacks. The listener can be cancelled by
1173 * calling the function that is returned when `onSnapshot` is called.
1174 *
1175 * NOTE: Although an `onCompletion` callback can be provided, it will
1176 * never be called because the snapshot stream is never-ending.
1177 *
1178 * @param query - The query to listen to.
1179 * @param onNext - A callback to be called every time a new `QuerySnapshot`
1180 * is available.
1181 * @param onCompletion - Can be provided, but will not be called since streams are
1182 * never ending.
1183 * @param onError - A callback to be called if the listen fails or is
1184 * cancelled. No further callbacks will occur.
1185 * @returns An unsubscribe function that can be called to cancel
1186 * the snapshot listener.
1187 */
1188export declare function onSnapshot<T>(query: Query<T>, onNext: (snapshot: QuerySnapshot<T>) => void, onError?: (error: FirestoreError) => void, onCompletion?: () => void): Unsubscribe;
1189/**
1190 * Attaches a listener for `QuerySnapshot` events. You may either pass
1191 * individual `onNext` and `onError` callbacks or pass a single observer
1192 * object with `next` and `error` callbacks. The listener can be cancelled by
1193 * calling the function that is returned when `onSnapshot` is called.
1194 *
1195 * NOTE: Although an `onCompletion` callback can be provided, it will
1196 * never be called because the snapshot stream is never-ending.
1197 *
1198 * @param query - The query to listen to.
1199 * @param options - Options controlling the listen behavior.
1200 * @param onNext - A callback to be called every time a new `QuerySnapshot`
1201 * is available.
1202 * @param onCompletion - Can be provided, but will not be called since streams are
1203 * never ending.
1204 * @param onError - A callback to be called if the listen fails or is
1205 * cancelled. No further callbacks will occur.
1206 * @returns An unsubscribe function that can be called to cancel
1207 * the snapshot listener.
1208 */
1209export declare function onSnapshot<T>(query: Query<T>, options: SnapshotListenOptions, onNext: (snapshot: QuerySnapshot<T>) => void, onError?: (error: FirestoreError) => void, onCompletion?: () => void): Unsubscribe;
1210/**
1211 * Attaches a listener for a snapshots-in-sync event. The snapshots-in-sync
1212 * event indicates that all listeners affected by a given change have fired,
1213 * even if a single server-generated change affects multiple listeners.
1214 *
1215 * NOTE: The snapshots-in-sync event only indicates that listeners are in sync
1216 * with each other, but does not relate to whether those snapshots are in sync
1217 * with the server. Use SnapshotMetadata in the individual listeners to
1218 * determine if a snapshot is from the cache or the server.
1219 *
1220 * @param firestore - The instance of Firestore for synchronizing snapshots.
1221 * @param observer - A single object containing `next` and `error` callbacks.
1222 * @returns An unsubscribe function that can be called to cancel the snapshot
1223 * listener.
1224 */
1225export declare function onSnapshotsInSync(firestore: Firestore, observer: {
1226 next?: (value: void) => void;
1227 error?: (error: FirestoreError) => void;
1228 complete?: () => void;
1229}): Unsubscribe;
1230/**
1231 * Attaches a listener for a snapshots-in-sync event. The snapshots-in-sync
1232 * event indicates that all listeners affected by a given change have fired,
1233 * even if a single server-generated change affects multiple listeners.
1234 *
1235 * NOTE: The snapshots-in-sync event only indicates that listeners are in sync
1236 * with each other, but does not relate to whether those snapshots are in sync
1237 * with the server. Use `SnapshotMetadata` in the individual listeners to
1238 * determine if a snapshot is from the cache or the server.
1239 *
1240 * @param firestore - The `Firestore` instance for synchronizing snapshots.
1241 * @param onSync - A callback to be called every time all snapshot listeners are
1242 * in sync with each other.
1243 * @returns An unsubscribe function that can be called to cancel the snapshot
1244 * listener.
1245 */
1246export declare function onSnapshotsInSync(firestore: Firestore, onSync: () => void): Unsubscribe;
1247/**
1248 * Creates a {@link QueryConstraint} that sorts the query result by the
1249 * specified field, optionally in descending order instead of ascending.
1250 *
1251 * @param fieldPath - The field to sort by.
1252 * @param directionStr - Optional direction to sort by ('asc' or 'desc'). If
1253 * not specified, order will be ascending.
1254 * @returns The created {@link Query}.
1255 */
1256export declare function orderBy(fieldPath: string | FieldPath, directionStr?: OrderByDirection): QueryConstraint;
1257/**
1258 * The direction of a {@link orderBy} clause is specified as 'desc' or 'asc'
1259 * (descending or ascending).
1260 */
1261export declare type OrderByDirection = 'desc' | 'asc';
1262/**
1263 * Similar to Typescript's `Partial<T>`, but allows nested fields to be
1264 * omitted and FieldValues to be passed in as property values.
1265 */
1266export declare type PartialWithFieldValue<T> = T extends Primitive ? T : T extends {} ? {
1267 [K in keyof T]?: PartialWithFieldValue<T[K]> | FieldValue;
1268} : Partial<T>;
1269/**
1270 * Settings that can be passed to `enableIndexedDbPersistence()` to configure
1271 * Firestore persistence.
1272 */
1273export declare interface PersistenceSettings {
1274 /**
1275 * Whether to force enable persistence for the client. This cannot be used
1276 * with multi-tab synchronization and is primarily intended for use with Web
1277 * Workers. Setting this to `true` will enable persistence, but cause other
1278 * tabs using persistence to fail.
1279 */
1280 forceOwnership?: boolean;
1281}
1282/**
1283 * These types primarily exist to support the `UpdateData`,
1284 * `WithFieldValue`, and `PartialWithFieldValue` types and are not consumed
1285 * directly by the end developer.
1286 */
1287/** Primitive types. */
1288export declare type Primitive = string | number | boolean | undefined | null;
1289/**
1290 * A `Query` refers to a query which you can read or listen to. You can also
1291 * construct refined `Query` objects by adding filters and ordering.
1292 */
1293export declare class Query<T = DocumentData> {
1294 /**
1295 * If provided, the `FirestoreDataConverter` associated with this instance.
1296 */
1297 readonly converter: FirestoreDataConverter<T> | null;
1298 /** The type of this Firestore reference. */
1299 readonly type: 'query' | 'collection';
1300 /**
1301 * The `Firestore` instance for the Firestore database (useful for performing
1302 * transactions, etc.).
1303 */
1304 readonly firestore: Firestore;
1305 protected constructor();
1306 /**
1307 * Removes the current converter.
1308 *
1309 * @param converter - `null` removes the current converter.
1310 * @returns A `Query<DocumentData>` that does not use a converter.
1311 */
1312 withConverter(converter: null): Query<DocumentData>;
1313 /**
1314 * Applies a custom data converter to this query, allowing you to use your own
1315 * custom model objects with Firestore. When you call {@link getDocs} with
1316 * the returned query, the provided converter will convert between Firestore
1317 * data and your custom type `U`.
1318 *
1319 * @param converter - Converts objects to and from Firestore.
1320 * @returns A `Query<U>` that uses the provided converter.
1321 */
1322 withConverter<U>(converter: FirestoreDataConverter<U>): Query<U>;
1323}
1324/**
1325 * Creates a new immutable instance of {@link Query} that is extended to also include
1326 * additional query constraints.
1327 *
1328 * @param query - The {@link Query} instance to use as a base for the new constraints.
1329 * @param queryConstraints - The list of {@link QueryConstraint}s to apply.
1330 * @throws if any of the provided query constraints cannot be combined with the
1331 * existing or new constraints.
1332 */
1333export declare function query<T>(query: Query<T>, ...queryConstraints: QueryConstraint[]): Query<T>;
1334/**
1335 * A `QueryConstraint` is used to narrow the set of documents returned by a
1336 * Firestore query. `QueryConstraint`s are created by invoking {@link where},
1337 * {@link orderBy}, {@link (startAt:1)}, {@link (startAfter:1)}, {@link
1338 * endBefore:1}, {@link (endAt:1)}, {@link limit} or {@link limitToLast} and
1339 * can then be passed to {@link query} to create a new query instance that
1340 * also contains this `QueryConstraint`.
1341 */
1342export declare abstract class QueryConstraint {
1343 /** The type of this query constraints */
1344 abstract readonly type: QueryConstraintType;
1345}
1346/** Describes the different query constraints available in this SDK. */
1347export declare type QueryConstraintType = 'where' | 'orderBy' | 'limit' | 'limitToLast' | 'startAt' | 'startAfter' | 'endAt' | 'endBefore';
1348/**
1349 * A `QueryDocumentSnapshot` contains data read from a document in your
1350 * Firestore database as part of a query. The document is guaranteed to exist
1351 * and its data can be extracted with `.data()` or `.get(<field>)` to get a
1352 * specific field.
1353 *
1354 * A `QueryDocumentSnapshot` offers the same API surface as a
1355 * `DocumentSnapshot`. Since query results contain only existing documents, the
1356 * `exists` property will always be true and `data()` will never return
1357 * 'undefined'.
1358 */
1359export declare class QueryDocumentSnapshot<T = DocumentData> extends DocumentSnapshot<T> {
1360 /**
1361 * Retrieves all fields in the document as an `Object`.
1362 *
1363 * By default, `FieldValue.serverTimestamp()` values that have not yet been
1364 * set to their final value will be returned as `null`. You can override
1365 * this by passing an options object.
1366 *
1367 * @override
1368 * @param options - An options object to configure how data is retrieved from
1369 * the snapshot (for example the desired behavior for server timestamps that
1370 * have not yet been set to their final value).
1371 * @returns An `Object` containing all fields in the document.
1372 */
1373 data(options?: SnapshotOptions): T;
1374}
1375/**
1376 * Returns true if the provided queries point to the same collection and apply
1377 * the same constraints.
1378 *
1379 * @param left - A `Query` to compare.
1380 * @param right - A `Query` to compare.
1381 * @returns true if the references point to the same location in the same
1382 * Firestore database.
1383 */
1384export declare function queryEqual<T>(left: Query<T>, right: Query<T>): boolean;
1385/**
1386 * A `QuerySnapshot` contains zero or more `DocumentSnapshot` objects
1387 * representing the results of a query. The documents can be accessed as an
1388 * array via the `docs` property or enumerated using the `forEach` method. The
1389 * number of documents can be determined via the `empty` and `size`
1390 * properties.
1391 */
1392export declare class QuerySnapshot<T = DocumentData> {
1393 /**
1394 * Metadata about this snapshot, concerning its source and if it has local
1395 * modifications.
1396 */
1397 readonly metadata: SnapshotMetadata;
1398 /**
1399 * The query on which you called `get` or `onSnapshot` in order to get this
1400 * `QuerySnapshot`.
1401 */
1402 readonly query: Query<T>;
1403 private constructor();
1404 /** An array of all the documents in the `QuerySnapshot`. */
1405 get docs(): Array<QueryDocumentSnapshot<T>>;
1406 /** The number of documents in the `QuerySnapshot`. */
1407 get size(): number;
1408 /** True if there are no documents in the `QuerySnapshot`. */
1409 get empty(): boolean;
1410 /**
1411 * Enumerates all of the documents in the `QuerySnapshot`.
1412 *
1413 * @param callback - A callback to be called with a `QueryDocumentSnapshot` for
1414 * each document in the snapshot.
1415 * @param thisArg - The `this` binding for the callback.
1416 */
1417 forEach(callback: (result: QueryDocumentSnapshot<T>) => void, thisArg?: unknown): void;
1418 /**
1419 * Returns an array of the documents changes since the last snapshot. If this
1420 * is the first snapshot, all documents will be in the list as 'added'
1421 * changes.
1422 *
1423 * @param options - `SnapshotListenOptions` that control whether metadata-only
1424 * changes (i.e. only `DocumentSnapshot.metadata` changed) should trigger
1425 * snapshot events.
1426 */
1427 docChanges(options?: SnapshotListenOptions): Array<DocumentChange<T>>;
1428}
1429/**
1430 * Returns true if the provided references are equal.
1431 *
1432 * @param left - A reference to compare.
1433 * @param right - A reference to compare.
1434 * @returns true if the references point to the same location in the same
1435 * Firestore database.
1436 */
1437export declare function refEqual<T>(left: DocumentReference<T> | CollectionReference<T>, right: DocumentReference<T> | CollectionReference<T>): boolean;
1438/* Excluded from this release type: _ResourcePath */
1439/**
1440 * Executes the given `updateFunction` and then attempts to commit the changes
1441 * applied within the transaction. If any document read within the transaction
1442 * has changed, Cloud Firestore retries the `updateFunction`. If it fails to
1443 * commit after 5 attempts, the transaction fails.
1444 *
1445 * The maximum number of writes allowed in a single transaction is 500.
1446 *
1447 * @param firestore - A reference to the Firestore database to run this
1448 * transaction against.
1449 * @param updateFunction - The function to execute within the transaction
1450 * context.
1451 * @returns If the transaction completed successfully or was explicitly aborted
1452 * (the `updateFunction` returned a failed promise), the promise returned by the
1453 * `updateFunction `is returned here. Otherwise, if the transaction failed, a
1454 * rejected promise with the corresponding failure error is returned.
1455 */
1456export declare function runTransaction<T>(firestore: Firestore, updateFunction: (transaction: Transaction) => Promise<T>): Promise<T>;
1457/**
1458 * Returns a sentinel used with {@link @firebase/firestore/lite#(setDoc:1)} or {@link @firebase/firestore/lite#(updateDoc:1)} to
1459 * include a server-generated timestamp in the written data.
1460 */
1461export declare function serverTimestamp(): FieldValue;
1462/**
1463 * Writes to the document referred to by this `DocumentReference`. If the
1464 * document does not yet exist, it will be created.
1465 *
1466 * @param reference - A reference to the document to write.
1467 * @param data - A map of the fields and values for the document.
1468 * @returns A `Promise` resolved once the data has been successfully written
1469 * to the backend (note that it won't resolve while you're offline).
1470 */
1471export declare function setDoc<T>(reference: DocumentReference<T>, data: WithFieldValue<T>): Promise<void>;
1472/**
1473 * Writes to the document referred to by the specified `DocumentReference`. If
1474 * the document does not yet exist, it will be created. If you provide `merge`
1475 * or `mergeFields`, the provided data can be merged into an existing document.
1476 *
1477 * @param reference - A reference to the document to write.
1478 * @param data - A map of the fields and values for the document.
1479 * @param options - An object to configure the set behavior.
1480 * @returns A Promise resolved once the data has been successfully written
1481 * to the backend (note that it won't resolve while you're offline).
1482 */
1483export declare function setDoc<T>(reference: DocumentReference<T>, data: PartialWithFieldValue<T>, options: SetOptions): Promise<void>;
1484/**
1485 * Sets the verbosity of Cloud Firestore logs (debug, error, or silent).
1486 *
1487 * @param logLevel - The verbosity you set for activity and error logging. Can
1488 * be any of the following values:
1489 *
1490 * <ul>
1491 * <li>`debug` for the most verbose logging level, primarily for
1492 * debugging.</li>
1493 * <li>`error` to log errors only.</li>
1494 * <li><code>`silent` to turn off logging.</li>
1495 * </ul>
1496 */
1497export declare function setLogLevel(logLevel: LogLevel): void;
1498/**
1499 * An options object that configures the behavior of {@link @firebase/firestore/lite#(setDoc:1)}, {@link
1500 * @firebase/firestore/lite#(WriteBatch.set:1)} and {@link @firebase/firestore/lite#(Transaction.set:1)} calls. These calls can be
1501 * configured to perform granular merges instead of overwriting the target
1502 * documents in their entirety by providing a `SetOptions` with `merge: true`.
1503 *
1504 * @param merge - Changes the behavior of a `setDoc()` call to only replace the
1505 * values specified in its data argument. Fields omitted from the `setDoc()`
1506 * call remain untouched.
1507 * @param mergeFields - Changes the behavior of `setDoc()` calls to only replace
1508 * the specified field paths. Any field path that is not specified is ignored
1509 * and remains untouched.
1510 */
1511export declare type SetOptions = {
1512 readonly merge?: boolean;
1513} | {
1514 readonly mergeFields?: Array<string | FieldPath>;
1515};
1516/**
1517 * Returns true if the provided snapshots are equal.
1518 *
1519 * @param left - A snapshot to compare.
1520 * @param right - A snapshot to compare.
1521 * @returns true if the snapshots are equal.
1522 */
1523export declare function snapshotEqual<T>(left: DocumentSnapshot<T> | QuerySnapshot<T>, right: DocumentSnapshot<T> | QuerySnapshot<T>): boolean;
1524/**
1525 * An options object that can be passed to {@link (onSnapshot:1)} and {@link
1526 * QuerySnapshot.docChanges} to control which types of changes to include in the
1527 * result set.
1528 */
1529export declare interface SnapshotListenOptions {
1530 /**
1531 * Include a change even if only the metadata of the query or of a document
1532 * changed. Default is false.
1533 */
1534 readonly includeMetadataChanges?: boolean;
1535}
1536/**
1537 * Metadata about a snapshot, describing the state of the snapshot.
1538 */
1539export declare class SnapshotMetadata {
1540 /**
1541 * True if the snapshot contains the result of local writes (for example
1542 * `set()` or `update()` calls) that have not yet been committed to the
1543 * backend. If your listener has opted into metadata updates (via
1544 * `SnapshotListenOptions`) you will receive another snapshot with
1545 * `hasPendingWrites` equal to false once the writes have been committed to
1546 * the backend.
1547 */
1548 readonly hasPendingWrites: boolean;
1549 /**
1550 * True if the snapshot was created from cached data rather than guaranteed
1551 * up-to-date server data. If your listener has opted into metadata updates
1552 * (via `SnapshotListenOptions`) you will receive another snapshot with
1553 * `fromCache` set to false once the client has received up-to-date data from
1554 * the backend.
1555 */
1556 readonly fromCache: boolean;
1557 private constructor();
1558 /**
1559 * Returns true if this `SnapshotMetadata` is equal to the provided one.
1560 *
1561 * @param other - The `SnapshotMetadata` to compare against.
1562 * @returns true if this `SnapshotMetadata` is equal to the provided one.
1563 */
1564 isEqual(other: SnapshotMetadata): boolean;
1565}
1566/**
1567 * Options that configure how data is retrieved from a `DocumentSnapshot` (for
1568 * example the desired behavior for server timestamps that have not yet been set
1569 * to their final value).
1570 */
1571export declare interface SnapshotOptions {
1572 /**
1573 * If set, controls the return value for server timestamps that have not yet
1574 * been set to their final value.
1575 *
1576 * By specifying 'estimate', pending server timestamps return an estimate
1577 * based on the local clock. This estimate will differ from the final value
1578 * and cause these values to change once the server result becomes available.
1579 *
1580 * By specifying 'previous', pending timestamps will be ignored and return
1581 * their previous value instead.
1582 *
1583 * If omitted or set to 'none', `null` will be returned by default until the
1584 * server value becomes available.
1585 */
1586 readonly serverTimestamps?: 'estimate' | 'previous' | 'none';
1587}
1588/**
1589 * Creates a {@link QueryConstraint} that modifies the result set to start after the
1590 * provided document (exclusive). The starting position is relative to the order
1591 * of the query. The document must contain all of the fields provided in the
1592 * orderBy of the query.
1593 *
1594 * @param snapshot - The snapshot of the document to start after.
1595 * @returns A {@link QueryConstraint} to pass to `query()`
1596 */
1597export declare function startAfter(snapshot: DocumentSnapshot<unknown>): QueryConstraint;
1598/**
1599 * Creates a {@link QueryConstraint} that modifies the result set to start after the
1600 * provided fields relative to the order of the query. The order of the field
1601 * values must match the order of the order by clauses of the query.
1602 *
1603 * @param fieldValues - The field values to start this query after, in order
1604 * of the query's order by.
1605 * @returns A {@link QueryConstraint} to pass to `query()`
1606 */
1607export declare function startAfter(...fieldValues: unknown[]): QueryConstraint;
1608/**
1609 * Creates a {@link QueryConstraint} that modifies the result set to start at the
1610 * provided document (inclusive). The starting position is relative to the order
1611 * of the query. The document must contain all of the fields provided in the
1612 * `orderBy` of this query.
1613 *
1614 * @param snapshot - The snapshot of the document to start at.
1615 * @returns A {@link QueryConstraint} to pass to `query()`.
1616 */
1617export declare function startAt(snapshot: DocumentSnapshot<unknown>): QueryConstraint;
1618/**
1619 * Creates a {@link QueryConstraint} that modifies the result set to start at the
1620 * provided fields relative to the order of the query. The order of the field
1621 * values must match the order of the order by clauses of the query.
1622 *
1623 * @param fieldValues - The field values to start this query at, in order
1624 * of the query's order by.
1625 * @returns A {@link QueryConstraint} to pass to `query()`.
1626 */
1627export declare function startAt(...fieldValues: unknown[]): QueryConstraint;
1628/**
1629 * Represents the state of bundle loading tasks.
1630 *
1631 * Both 'Error' and 'Success' are sinking state: task will abort or complete and there will
1632 * be no more updates after they are reported.
1633 */
1634export declare type TaskState = 'Error' | 'Running' | 'Success';
1635/**
1636 * Terminates the provided {@link Firestore} instance.
1637 *
1638 * After calling `terminate()` only the `clearIndexedDbPersistence()` function
1639 * may be used. Any other function will throw a `FirestoreError`.
1640 *
1641 * To restart after termination, create a new instance of FirebaseFirestore with
1642 * {@link getFirestore}.
1643 *
1644 * Termination does not cancel any pending writes, and any promises that are
1645 * awaiting a response from the server will not be resolved. If you have
1646 * persistence enabled, the next time you start this instance, it will resume
1647 * sending these writes to the server.
1648 *
1649 * Note: Under normal circumstances, calling `terminate()` is not required. This
1650 * function is useful only when you want to force this instance to release all
1651 * of its resources or in combination with `clearIndexedDbPersistence()` to
1652 * ensure that all local state is destroyed between test runs.
1653 *
1654 * @returns A `Promise` that is resolved when the instance has been successfully
1655 * terminated.
1656 */
1657export declare function terminate(firestore: Firestore): Promise<void>;
1658/**
1659 * @license
1660 * Copyright 2017 Google LLC
1661 *
1662 * Licensed under the Apache License, Version 2.0 (the "License");
1663 * you may not use this file except in compliance with the License.
1664 * You may obtain a copy of the License at
1665 *
1666 * http://www.apache.org/licenses/LICENSE-2.0
1667 *
1668 * Unless required by applicable law or agreed to in writing, software
1669 * distributed under the License is distributed on an "AS IS" BASIS,
1670 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
1671 * See the License for the specific language governing permissions and
1672 * limitations under the License.
1673 */
1674/**
1675 * A `Timestamp` represents a point in time independent of any time zone or
1676 * calendar, represented as seconds and fractions of seconds at nanosecond
1677 * resolution in UTC Epoch time.
1678 *
1679 * It is encoded using the Proleptic Gregorian Calendar which extends the
1680 * Gregorian calendar backwards to year one. It is encoded assuming all minutes
1681 * are 60 seconds long, i.e. leap seconds are "smeared" so that no leap second
1682 * table is needed for interpretation. Range is from 0001-01-01T00:00:00Z to
1683 * 9999-12-31T23:59:59.999999999Z.
1684 *
1685 * For examples and further specifications, refer to the
1686 * {@link https://github.com/google/protobuf/blob/master/src/google/protobuf/timestamp.proto | Timestamp definition}.
1687 */
1688export declare class Timestamp {
1689 /**
1690 * The number of seconds of UTC time since Unix epoch 1970-01-01T00:00:00Z.
1691 */
1692 readonly seconds: number;
1693 /**
1694 * The fractions of a second at nanosecond resolution.*
1695 */
1696 readonly nanoseconds: number;
1697 /**
1698 * Creates