UNPKG

139 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';
9import { FirebaseError } from '@firebase/util';
10
11/**
12 * Add a new document to specified `CollectionReference` with the given data,
13 * assigning it a document ID automatically.
14 *
15 * @param reference - A reference to the collection to add this document to.
16 * @param data - An Object containing the data for the new document.
17 * @returns A `Promise` resolved with a `DocumentReference` pointing to the
18 * newly created document after it has been written to the backend (Note that it
19 * won't resolve while you're offline).
20 */
21export declare function addDoc<AppModelType, DbModelType extends DocumentData>(reference: CollectionReference<AppModelType, DbModelType>, data: WithFieldValue<AppModelType>): Promise<DocumentReference<AppModelType, DbModelType>>;
22/**
23 * Returns a new map where every key is prefixed with the outer key appended
24 * to a dot.
25 */
26export declare type AddPrefixToKeys<Prefix extends string, T extends Record<string, unknown>> = {
27 [K in keyof T & string as `${Prefix}.${K}`]+?: string extends K ? any : T[K];
28};
29/**
30 * Represents an aggregation that can be performed by Firestore.
31 */
32export declare class AggregateField<T> {
33 /** A type string to uniquely identify instances of this class. */
34 readonly type = "AggregateField";
35 /** Indicates the aggregation operation of this AggregateField. */
36 readonly aggregateType: AggregateType;
37}
38/**
39 * Compares two 'AggregateField` instances for equality.
40 *
41 * @param left Compare this AggregateField to the `right`.
42 * @param right Compare this AggregateField to the `left`.
43 */
44export declare function aggregateFieldEqual(left: AggregateField<unknown>, right: AggregateField<unknown>): boolean;
45/**
46 * The union of all `AggregateField` types that are supported by Firestore.
47 */
48export declare type AggregateFieldType = ReturnType<typeof sum> | ReturnType<typeof average> | ReturnType<typeof count>;
49/**
50 * The results of executing an aggregation query.
51 */
52export declare class AggregateQuerySnapshot<AggregateSpecType extends AggregateSpec, AppModelType = DocumentData, DbModelType extends DocumentData = DocumentData> {
53 /** A type string to uniquely identify instances of this class. */
54 readonly type = "AggregateQuerySnapshot";
55 /**
56 * The underlying query over which the aggregations recorded in this
57 * `AggregateQuerySnapshot` were performed.
58 */
59 readonly query: Query<AppModelType, DbModelType>;
60 private constructor();
61 /**
62 * Returns the results of the aggregations performed over the underlying
63 * query.
64 *
65 * The keys of the returned object will be the same as those of the
66 * `AggregateSpec` object specified to the aggregation method, and the values
67 * will be the corresponding aggregation result.
68 *
69 * @returns The results of the aggregations performed over the underlying
70 * query.
71 */
72 data(): AggregateSpecData<AggregateSpecType>;
73}
74/**
75 * Compares two `AggregateQuerySnapshot` instances for equality.
76 *
77 * Two `AggregateQuerySnapshot` instances are considered "equal" if they have
78 * underlying queries that compare equal, and the same data.
79 *
80 * @param left - The first `AggregateQuerySnapshot` to compare.
81 * @param right - The second `AggregateQuerySnapshot` to compare.
82 *
83 * @returns `true` if the objects are "equal", as defined above, or `false`
84 * otherwise.
85 */
86export declare function aggregateQuerySnapshotEqual<AggregateSpecType extends AggregateSpec, AppModelType, DbModelType extends DocumentData>(left: AggregateQuerySnapshot<AggregateSpecType, AppModelType, DbModelType>, right: AggregateQuerySnapshot<AggregateSpecType, AppModelType, DbModelType>): boolean;
87/**
88 * Specifies a set of aggregations and their aliases.
89 */
90export declare interface AggregateSpec {
91 [field: string]: AggregateFieldType;
92}
93/**
94 * A type whose keys are taken from an `AggregateSpec`, and whose values are the
95 * result of the aggregation performed by the corresponding `AggregateField`
96 * from the input `AggregateSpec`.
97 */
98export declare type AggregateSpecData<T extends AggregateSpec> = {
99 [P in keyof T]: T[P] extends AggregateField<infer U> ? U : never;
100};
101/**
102 * Union type representing the aggregate type to be performed.
103 */
104export declare type AggregateType = 'count' | 'avg' | 'sum';
105/**
106 * Creates a new {@link QueryCompositeFilterConstraint} that is a conjunction of
107 * the given filter constraints. A conjunction filter includes a document if it
108 * satisfies all of the given filters.
109 *
110 * @param queryConstraints - Optional. The list of
111 * {@link QueryFilterConstraint}s to perform a conjunction for. These must be
112 * created with calls to {@link where}, {@link or}, or {@link and}.
113 * @returns The newly created {@link QueryCompositeFilterConstraint}.
114 */
115export declare function and(...queryConstraints: QueryFilterConstraint[]): QueryCompositeFilterConstraint;
116/**
117 * Returns a special value that can be used with {@link (setDoc:1)} or {@link
118 * updateDoc:1} that tells the server to remove the given elements from any
119 * array value that already exists on the server. All instances of each element
120 * specified will be removed from the array. If the field being modified is not
121 * already an array it will be overwritten with an empty array.
122 *
123 * @param elements - The elements to remove from the array.
124 * @returns The `FieldValue` sentinel for use in a call to `setDoc()` or
125 * `updateDoc()`
126 */
127export declare function arrayRemove(...elements: unknown[]): FieldValue;
128/**
129 * Returns a special value that can be used with {@link @firebase/firestore/lite#(setDoc:1)} or {@link
130 * @firebase/firestore/lite#(updateDoc:1)} that tells the server to union the given elements with any array
131 * value that already exists on the server. Each specified element that doesn't
132 * already exist in the array will be added to the end. If the field being
133 * modified is not already an array it will be overwritten with an array
134 * containing exactly the specified elements.
135 *
136 * @param elements - The elements to union into the array.
137 * @returns The `FieldValue` sentinel for use in a call to `setDoc()` or
138 * `updateDoc()`.
139 */
140export declare function arrayUnion(...elements: unknown[]): FieldValue;
141/* Excluded from this release type: AuthTokenFactory */
142/* Excluded from this release type: _AutoId */
143/**
144 * Create an AggregateField object that can be used to compute the average of
145 * a specified field over a range of documents in the result set of a query.
146 * @param field Specifies the field to average across the result set.
147 */
148export declare function average(field: string | FieldPath): AggregateField<number | null>;
149/**
150 * An immutable object representing an array of bytes.
151 */
152export declare class Bytes {
153 private constructor();
154 /**
155 * Creates a new `Bytes` object from the given Base64 string, converting it to
156 * bytes.
157 *
158 * @param base64 - The Base64 string used to create the `Bytes` object.
159 */
160 static fromBase64String(base64: string): Bytes;
161 /**
162 * Creates a new `Bytes` object from the given Uint8Array.
163 *
164 * @param array - The Uint8Array used to create the `Bytes` object.
165 */
166 static fromUint8Array(array: Uint8Array): Bytes;
167 /**
168 * Returns the underlying bytes as a Base64-encoded string.
169 *
170 * @returns The Base64-encoded string created from the `Bytes` object.
171 */
172 toBase64(): string;
173 /**
174 * Returns the underlying bytes in a new `Uint8Array`.
175 *
176 * @returns The Uint8Array created from the `Bytes` object.
177 */
178 toUint8Array(): Uint8Array;
179 /**
180 * Returns a string representation of the `Bytes` object.
181 *
182 * @returns A string representation of the `Bytes` object.
183 */
184 toString(): string;
185 /**
186 * Returns true if this `Bytes` object is equal to the provided one.
187 *
188 * @param other - The `Bytes` object to compare against.
189 * @returns true if this `Bytes` object is equal to the provided one.
190 */
191 isEqual(other: Bytes): boolean;
192}
193/* Excluded from this release type: _ByteString */
194/**
195 * Constant used to indicate the LRU garbage collection should be disabled.
196 * Set this value as the `cacheSizeBytes` on the settings passed to the
197 * {@link Firestore} instance.
198 */
199export declare const CACHE_SIZE_UNLIMITED = -1;
200/**
201 * Helper for calculating the nested fields for a given type T1. This is needed
202 * to distribute union types such as `undefined | {...}` (happens for optional
203 * props) or `{a: A} | {b: B}`.
204 *
205 * In this use case, `V` is used to distribute the union types of `T[K]` on
206 * `Record`, since `T[K]` is evaluated as an expression and not distributed.
207 *
208 * See https://www.typescriptlang.org/docs/handbook/advanced-types.html#distributive-conditional-types
209 */
210export declare type ChildUpdateFields<K extends string, V> = V extends Record<string, unknown> ? AddPrefixToKeys<K, UpdateData<V>> : never;
211/**
212 * Clears the persistent storage. This includes pending writes and cached
213 * documents.
214 *
215 * Must be called while the {@link Firestore} instance is not started (after the app is
216 * terminated or when the app is first initialized). On startup, this function
217 * must be called before other functions (other than {@link
218 * initializeFirestore} or {@link (getFirestore:1)})). If the {@link Firestore}
219 * instance is still running, the promise will be rejected with the error code
220 * of `failed-precondition`.
221 *
222 * Note: `clearIndexedDbPersistence()` is primarily intended to help write
223 * reliable tests that use Cloud Firestore. It uses an efficient mechanism for
224 * dropping existing data but does not attempt to securely overwrite or
225 * otherwise make cached data unrecoverable. For applications that are sensitive
226 * to the disclosure of cached data in between user sessions, we strongly
227 * recommend not enabling persistence at all.
228 *
229 * @param firestore - The {@link Firestore} instance to clear persistence for.
230 * @returns A `Promise` that is resolved when the persistent storage is
231 * cleared. Otherwise, the promise is rejected with an error.
232 */
233export declare function clearIndexedDbPersistence(firestore: Firestore): Promise<void>;
234/**
235 * Gets a `CollectionReference` instance that refers to the collection at
236 * the specified absolute path.
237 *
238 * @param firestore - A reference to the root `Firestore` instance.
239 * @param path - A slash-separated path to a collection.
240 * @param pathSegments - Additional path segments to apply relative to the first
241 * argument.
242 * @throws If the final path has an even number of segments and does not point
243 * to a collection.
244 * @returns The `CollectionReference` instance.
245 */
246export declare function collection(firestore: Firestore, path: string, ...pathSegments: string[]): CollectionReference<DocumentData, DocumentData>;
247/**
248 * Gets a `CollectionReference` instance that refers to a subcollection of
249 * `reference` at the specified relative path.
250 *
251 * @param reference - A reference to a collection.
252 * @param path - A slash-separated path to a collection.
253 * @param pathSegments - Additional path segments to apply relative to the first
254 * argument.
255 * @throws If the final path has an even number of segments and does not point
256 * to a collection.
257 * @returns The `CollectionReference` instance.
258 */
259export declare function collection<AppModelType, DbModelType extends DocumentData>(reference: CollectionReference<AppModelType, DbModelType>, path: string, ...pathSegments: string[]): CollectionReference<DocumentData, DocumentData>;
260/**
261 * Gets a `CollectionReference` instance that refers to a subcollection of
262 * `reference` at the specified relative path.
263 *
264 * @param reference - A reference to a Firestore document.
265 * @param path - A slash-separated path to a collection.
266 * @param pathSegments - Additional path segments that will be applied relative
267 * to the first argument.
268 * @throws If the final path has an even number of segments and does not point
269 * to a collection.
270 * @returns The `CollectionReference` instance.
271 */
272export declare function collection<AppModelType, DbModelType extends DocumentData>(reference: DocumentReference<AppModelType, DbModelType>, path: string, ...pathSegments: string[]): CollectionReference<DocumentData, DocumentData>;
273/**
274 * Creates and returns a new `Query` instance that includes all documents in the
275 * database that are contained in a collection or subcollection with the
276 * given `collectionId`.
277 *
278 * @param firestore - A reference to the root `Firestore` instance.
279 * @param collectionId - Identifies the collections to query over. Every
280 * collection or subcollection with this ID as the last segment of its path
281 * will be included. Cannot contain a slash.
282 * @returns The created `Query`.
283 */
284export declare function collectionGroup(firestore: Firestore, collectionId: string): Query<DocumentData, DocumentData>;
285/**
286 * A `CollectionReference` object can be used for adding documents, getting
287 * document references, and querying for documents (using {@link (query:1)}).
288 */
289export declare class CollectionReference<AppModelType = DocumentData, DbModelType extends DocumentData = DocumentData> extends Query<AppModelType, DbModelType> {
290 /** The type of this Firestore reference. */
291 readonly type = "collection";
292 private constructor();
293 /** The collection's identifier. */
294 get id(): string;
295 /**
296 * A string representing the path of the referenced collection (relative
297 * to the root of the database).
298 */
299 get path(): string;
300 /**
301 * A reference to the containing `DocumentReference` if this is a
302 * subcollection. If this isn't a subcollection, the reference is null.
303 */
304 get parent(): DocumentReference<DocumentData, DocumentData> | null;
305 /**
306 * Applies a custom data converter to this `CollectionReference`, allowing you
307 * to use your own custom model objects with Firestore. When you call {@link
308 * addDoc} with the returned `CollectionReference` instance, the provided
309 * converter will convert between Firestore data of type `NewDbModelType` and
310 * your custom type `NewAppModelType`.
311 *
312 * @param converter - Converts objects to and from Firestore.
313 * @returns A `CollectionReference` that uses the provided converter.
314 */
315 withConverter<NewAppModelType, NewDbModelType extends DocumentData = DocumentData>(converter: FirestoreDataConverter<NewAppModelType, NewDbModelType>): CollectionReference<NewAppModelType, NewDbModelType>;
316 /**
317 * Removes the current converter.
318 *
319 * @param converter - `null` removes the current converter.
320 * @returns A `CollectionReference<DocumentData, DocumentData>` that does not
321 * use a converter.
322 */
323 withConverter(converter: null): CollectionReference<DocumentData, DocumentData>;
324}
325/**
326 * Modify this instance to communicate with the Cloud Firestore emulator.
327 *
328 * Note: This must be called before this instance has been used to do any
329 * operations.
330 *
331 * @param firestore - The `Firestore` instance to configure to connect to the
332 * emulator.
333 * @param host - the emulator host (ex: localhost).
334 * @param port - the emulator port (ex: 9000).
335 * @param options.mockUserToken - the mock auth token to use for unit testing
336 * Security Rules.
337 */
338export declare function connectFirestoreEmulator(firestore: Firestore, host: string, port: number, options?: {
339 mockUserToken?: EmulatorMockTokenOptions | string;
340}): void;
341/**
342 * Create an AggregateField object that can be used to compute the count of
343 * documents in the result set of a query.
344 */
345export declare function count(): AggregateField<number>;
346/**
347 * Removes all persistent cache indexes.
348 *
349 * Please note this function will also deletes indexes generated by
350 * `setIndexConfiguration()`, which is deprecated.
351 */
352export declare function deleteAllPersistentCacheIndexes(indexManager: PersistentCacheIndexManager): void;
353/**
354 * Deletes the document referred to by the specified `DocumentReference`.
355 *
356 * @param reference - A reference to the document to delete.
357 * @returns A Promise resolved once the document has been successfully
358 * deleted from the backend (note that it won't resolve while you're offline).
359 */
360export declare function deleteDoc<AppModelType, DbModelType extends DocumentData>(reference: DocumentReference<AppModelType, DbModelType>): Promise<void>;
361/**
362 * Returns a sentinel for use with {@link @firebase/firestore/lite#(updateDoc:1)} or
363 * {@link @firebase/firestore/lite#(setDoc:1)} with `{merge: true}` to mark a field for deletion.
364 */
365export declare function deleteField(): FieldValue;
366/**
367 * Disables network usage for this instance. It can be re-enabled via {@link
368 * enableNetwork}. While the network is disabled, any snapshot listeners,
369 * `getDoc()` or `getDocs()` calls will return results from cache, and any write
370 * operations will be queued until the network is restored.
371 *
372 * @returns A `Promise` that is resolved once the network has been disabled.
373 */
374export declare function disableNetwork(firestore: Firestore): Promise<void>;
375/**
376 * Stops creating persistent cache indexes automatically for local query
377 * execution. The indexes which have been created by calling
378 * `enablePersistentCacheIndexAutoCreation()` still take effect.
379 */
380export declare function disablePersistentCacheIndexAutoCreation(indexManager: PersistentCacheIndexManager): void;
381/**
382 * Gets a `DocumentReference` instance that refers to the document at the
383 * specified absolute path.
384 *
385 * @param firestore - A reference to the root `Firestore` instance.
386 * @param path - A slash-separated path to a document.
387 * @param pathSegments - Additional path segments that will be applied relative
388 * to the first argument.
389 * @throws If the final path has an odd number of segments and does not point to
390 * a document.
391 * @returns The `DocumentReference` instance.
392 */
393export declare function doc(firestore: Firestore, path: string, ...pathSegments: string[]): DocumentReference<DocumentData, DocumentData>;
394/**
395 * Gets a `DocumentReference` instance that refers to a document within
396 * `reference` at the specified relative path. If no path is specified, an
397 * automatically-generated unique ID will be used for the returned
398 * `DocumentReference`.
399 *
400 * @param reference - A reference to a collection.
401 * @param path - A slash-separated path to a document. Has to be omitted to use
402 * auto-generated IDs.
403 * @param pathSegments - Additional path segments that will be applied relative
404 * to the first argument.
405 * @throws If the final path has an odd number of segments and does not point to
406 * a document.
407 * @returns The `DocumentReference` instance.
408 */
409export declare function doc<AppModelType, DbModelType extends DocumentData>(reference: CollectionReference<AppModelType, DbModelType>, path?: string, ...pathSegments: string[]): DocumentReference<AppModelType, DbModelType>;
410/**
411 * Gets a `DocumentReference` instance that refers to a document within
412 * `reference` at the specified relative path.
413 *
414 * @param reference - A reference to a Firestore document.
415 * @param path - A slash-separated path to a document.
416 * @param pathSegments - Additional path segments that will be applied relative
417 * to the first argument.
418 * @throws If the final path has an odd number of segments and does not point to
419 * a document.
420 * @returns The `DocumentReference` instance.
421 */
422export declare function doc<AppModelType, DbModelType extends DocumentData>(reference: DocumentReference<AppModelType, DbModelType>, path: string, ...pathSegments: string[]): DocumentReference<DocumentData, DocumentData>;
423/**
424 * A `DocumentChange` represents a change to the documents matching a query.
425 * It contains the document affected and the type of change that occurred.
426 */
427export declare interface DocumentChange<AppModelType = DocumentData, DbModelType extends DocumentData = DocumentData> {
428 /** The type of change ('added', 'modified', or 'removed'). */
429 readonly type: DocumentChangeType;
430 /** The document affected by this change. */
431 readonly doc: QueryDocumentSnapshot<AppModelType, DbModelType>;
432 /**
433 * The index of the changed document in the result set immediately prior to
434 * this `DocumentChange` (i.e. supposing that all prior `DocumentChange` objects
435 * have been applied). Is `-1` for 'added' events.
436 */
437 readonly oldIndex: number;
438 /**
439 * The index of the changed document in the result set immediately after
440 * this `DocumentChange` (i.e. supposing that all prior `DocumentChange`
441 * objects and the current `DocumentChange` object have been applied).
442 * Is -1 for 'removed' events.
443 */
444 readonly newIndex: number;
445}
446/**
447 * The type of a `DocumentChange` may be 'added', 'removed', or 'modified'.
448 */
449export declare type DocumentChangeType = 'added' | 'removed' | 'modified';
450/**
451 * Document data (for use with {@link @firebase/firestore/lite#(setDoc:1)}) consists of fields mapped to
452 * values.
453 */
454export declare interface DocumentData {
455 /** A mapping between a field and its value. */
456 [field: string]: any;
457}
458/**
459 * Returns a special sentinel `FieldPath` to refer to the ID of a document.
460 * It can be used in queries to sort or filter by the document ID.
461 */
462export declare function documentId(): FieldPath;
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.
467 */
468export declare class DocumentReference<AppModelType = DocumentData, DbModelType extends DocumentData = DocumentData> {
469 /**
470 * If provided, the `FirestoreDataConverter` associated with this instance.
471 */
472 readonly converter: FirestoreDataConverter<AppModelType, DbModelType> | null;
473 /** The type of this Firestore reference. */
474 readonly type = "document";
475 /**
476 * The {@link Firestore} instance the document is in.
477 * This is useful for performing transactions, for example.
478 */
479 readonly firestore: Firestore;
480 private constructor();
481 /**
482 * The document's identifier within its collection.
483 */
484 get id(): string;
485 /**
486 * A string representing the path of the referenced document (relative
487 * to the root of the database).
488 */
489 get path(): string;
490 /**
491 * The collection this `DocumentReference` belongs to.
492 */
493 get parent(): CollectionReference<AppModelType, DbModelType>;
494 /**
495 * Applies a custom data converter to this `DocumentReference`, allowing you
496 * to use your own custom model objects with Firestore. When you call {@link
497 * @firebase/firestore/lite#(setDoc:1)}, {@link @firebase/firestore/lite#getDoc}, etc. with the returned `DocumentReference`
498 * instance, the provided converter will convert between Firestore data of
499 * type `NewDbModelType` and your custom type `NewAppModelType`.
500 *
501 * @param converter - Converts objects to and from Firestore.
502 * @returns A `DocumentReference` that uses the provided converter.
503 */
504 withConverter<NewAppModelType, NewDbModelType extends DocumentData = DocumentData>(converter: FirestoreDataConverter<NewAppModelType, NewDbModelType>): DocumentReference<NewAppModelType, NewDbModelType>;
505 /**
506 * Removes the current converter.
507 *
508 * @param converter - `null` removes the current converter.
509 * @returns A `DocumentReference<DocumentData, DocumentData>` that does not
510 * use a converter.
511 */
512 withConverter(converter: null): DocumentReference<DocumentData, DocumentData>;
513}
514/**
515 * A `DocumentSnapshot` contains data read from a document in your Firestore
516 * database. The data can be extracted with `.data()` or `.get(<field>)` to
517 * get a specific field.
518 *
519 * For a `DocumentSnapshot` that points to a non-existing document, any data
520 * access will return 'undefined'. You can use the `exists()` method to
521 * explicitly verify a document's existence.
522 */
523export declare class DocumentSnapshot<AppModelType = DocumentData, DbModelType extends DocumentData = DocumentData> {
524 /**
525 * Metadata about the `DocumentSnapshot`, including information about its
526 * source and local modifications.
527 */
528 readonly metadata: SnapshotMetadata;
529 protected constructor();
530 /**
531 * Returns whether or not the data exists. True if the document exists.
532 */
533 exists(): this is QueryDocumentSnapshot<AppModelType, DbModelType>;
534 /**
535 * Retrieves all fields in the document as an `Object`. Returns `undefined` if
536 * the document doesn't exist.
537 *
538 * By default, `serverTimestamp()` values that have not yet been
539 * set to their final value will be returned as `null`. You can override
540 * this by passing an options object.
541 *
542 * @param options - An options object to configure how data is retrieved from
543 * the snapshot (for example the desired behavior for server timestamps that
544 * have not yet been set to their final value).
545 * @returns An `Object` containing all fields in the document or `undefined` if
546 * the document doesn't exist.
547 */
548 data(options?: SnapshotOptions): AppModelType | undefined;
549 /**
550 * Retrieves the field specified by `fieldPath`. Returns `undefined` if the
551 * document or field doesn't exist.
552 *
553 * By default, a `serverTimestamp()` that has not yet been set to
554 * its final value will be returned as `null`. You can override this by
555 * passing an options object.
556 *
557 * @param fieldPath - The path (for example 'foo' or 'foo.bar') to a specific
558 * field.
559 * @param options - An options object to configure how the field is retrieved
560 * from the snapshot (for example the desired behavior for server timestamps
561 * that have not yet been set to their final value).
562 * @returns The data at the specified field location or undefined if no such
563 * field exists in the document.
564 */
565 get(fieldPath: string | FieldPath, options?: SnapshotOptions): any;
566 /**
567 * Property of the `DocumentSnapshot` that provides the document's ID.
568 */
569 get id(): string;
570 /**
571 * The `DocumentReference` for the document included in the `DocumentSnapshot`.
572 */
573 get ref(): DocumentReference<AppModelType, DbModelType>;
574}
575/* Excluded from this release type: _EmptyAppCheckTokenProvider */
576/* Excluded from this release type: _EmptyAuthCredentialsProvider */
577export { EmulatorMockTokenOptions };
578/**
579 * Attempts to enable persistent storage, if possible.
580 *
581 * On failure, `enableIndexedDbPersistence()` will reject the promise or
582 * throw an exception. There are several reasons why this can fail, which can be
583 * identified by the `code` on the error.
584 *
585 * * failed-precondition: The app is already open in another browser tab.
586 * * unimplemented: The browser is incompatible with the offline persistence
587 * implementation.
588 *
589 * Note that even after a failure, the {@link Firestore} instance will remain
590 * usable, however offline persistence will be disabled.
591 *
592 * Note: `enableIndexedDbPersistence()` must be called before any other functions
593 * (other than {@link initializeFirestore}, {@link (getFirestore:1)} or
594 * {@link clearIndexedDbPersistence}.
595 *
596 * Persistence cannot be used in a Node.js environment.
597 *
598 * @param firestore - The {@link Firestore} instance to enable persistence for.
599 * @param persistenceSettings - Optional settings object to configure
600 * persistence.
601 * @returns A `Promise` that represents successfully enabling persistent storage.
602 * @deprecated This function will be removed in a future major release. Instead, set
603 * `FirestoreSettings.localCache` to an instance of `PersistentLocalCache` to
604 * turn on IndexedDb cache. Calling this function when `FirestoreSettings.localCache`
605 * is already specified will throw an exception.
606 */
607export declare function enableIndexedDbPersistence(firestore: Firestore, persistenceSettings?: PersistenceSettings): Promise<void>;
608/**
609 * Attempts to enable multi-tab persistent storage, if possible. If enabled
610 * across all tabs, all operations share access to local persistence, including
611 * shared execution of queries and latency-compensated local document updates
612 * across all connected instances.
613 *
614 * On failure, `enableMultiTabIndexedDbPersistence()` will reject the promise or
615 * throw an exception. There are several reasons why this can fail, which can be
616 * identified by the `code` on the error.
617 *
618 * * failed-precondition: The app is already open in another browser tab and
619 * multi-tab is not enabled.
620 * * unimplemented: The browser is incompatible with the offline persistence
621 * implementation.
622 *
623 * Note that even after a failure, the {@link Firestore} instance will remain
624 * usable, however offline persistence will be disabled.
625 *
626 * @param firestore - The {@link Firestore} instance to enable persistence for.
627 * @returns A `Promise` that represents successfully enabling persistent
628 * storage.
629 * @deprecated This function will be removed in a future major release. Instead, set
630 * `FirestoreSettings.localCache` to an instance of `PersistentLocalCache` to
631 * turn on indexeddb cache. Calling this function when `FirestoreSettings.localCache`
632 * is already specified will throw an exception.
633 */
634export declare function enableMultiTabIndexedDbPersistence(firestore: Firestore): Promise<void>;
635/**
636 * Re-enables use of the network for this {@link Firestore} instance after a prior
637 * call to {@link disableNetwork}.
638 *
639 * @returns A `Promise` that is resolved once the network has been enabled.
640 */
641export declare function enableNetwork(firestore: Firestore): Promise<void>;
642/**
643 * Enables the SDK to create persistent cache indexes automatically for local
644 * query execution when the SDK believes cache indexes can help improve
645 * performance.
646 *
647 * This feature is disabled by default.
648 */
649export declare function enablePersistentCacheIndexAutoCreation(indexManager: PersistentCacheIndexManager): void;
650/**
651 * Creates a {@link QueryEndAtConstraint} that modifies the result set to end at
652 * the provided document (inclusive). The end position is relative to the order
653 * of the query. The document must contain all of the fields provided in the
654 * orderBy of the query.
655 *
656 * @param snapshot - The snapshot of the document to end at.
657 * @returns A {@link QueryEndAtConstraint} to pass to `query()`
658 */
659export declare function endAt<AppModelType, DbModelType extends DocumentData>(snapshot: DocumentSnapshot<AppModelType, DbModelType>): QueryEndAtConstraint;
660/**
661 * Creates a {@link QueryEndAtConstraint} that modifies the result set to end at
662 * the provided fields relative to the order of the query. The order of the field
663 * values must match the order of the order by clauses of the query.
664 *
665 * @param fieldValues - The field values to end this query at, in order
666 * of the query's order by.
667 * @returns A {@link QueryEndAtConstraint} to pass to `query()`
668 */
669export declare function endAt(...fieldValues: unknown[]): QueryEndAtConstraint;
670/**
671 * Creates a {@link QueryEndAtConstraint} that modifies the result set to end
672 * before the provided document (exclusive). The end position is relative to the
673 * order of the query. The document must contain all of the fields provided in
674 * the orderBy of the query.
675 *
676 * @param snapshot - The snapshot of the document to end before.
677 * @returns A {@link QueryEndAtConstraint} to pass to `query()`
678 */
679export declare function endBefore<AppModelType, DbModelType extends DocumentData>(snapshot: DocumentSnapshot<AppModelType, DbModelType>): QueryEndAtConstraint;
680/**
681 * Creates a {@link QueryEndAtConstraint} that modifies the result set to end
682 * before the provided fields relative to the order of the query. The order of
683 * the field values must match the order of the order by clauses of the query.
684 *
685 * @param fieldValues - The field values to end this query before, in order
686 * of the query's order by.
687 * @returns A {@link QueryEndAtConstraint} to pass to `query()`
688 */
689export declare function endBefore(...fieldValues: unknown[]): QueryEndAtConstraint;
690/* Excluded from this release type: executeWrite */
691/**
692 * @license
693 * Copyright 2023 Google LLC
694 *
695 * Licensed under the Apache License, Version 2.0 (the "License");
696 * you may not use this file except in compliance with the License.
697 * You may obtain a copy of the License at
698 *
699 * http://www.apache.org/licenses/LICENSE-2.0
700 *
701 * Unless required by applicable law or agreed to in writing, software
702 * distributed under the License is distributed on an "AS IS" BASIS,
703 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
704 * See the License for the specific language governing permissions and
705 * limitations under the License.
706 */
707/**
708 * Options that configure the SDK’s underlying network transport (WebChannel)
709 * when long-polling is used.
710 *
711 * Note: This interface is "experimental" and is subject to change.
712 *
713 * See `FirestoreSettings.experimentalAutoDetectLongPolling`,
714 * `FirestoreSettings.experimentalForceLongPolling`, and
715 * `FirestoreSettings.experimentalLongPollingOptions`.
716 */
717export declare interface ExperimentalLongPollingOptions {
718 /**
719 * The desired maximum timeout interval, in seconds, to complete a
720 * long-polling GET response. Valid values are between 5 and 30, inclusive.
721 * Floating point values are allowed and will be rounded to the nearest
722 * millisecond.
723 *
724 * By default, when long-polling is used the "hanging GET" request sent by
725 * the client times out after 30 seconds. To request a different timeout
726 * from the server, set this setting with the desired timeout.
727 *
728 * Changing the default timeout may be useful, for example, if the buffering
729 * proxy that necessitated enabling long-polling in the first place has a
730 * shorter timeout for hanging GET requests, in which case setting the
731 * long-polling timeout to a shorter value, such as 25 seconds, may fix
732 * prematurely-closed hanging GET requests.
733 * For example, see https://github.com/firebase/firebase-js-sdk/issues/6987.
734 */
735 timeoutSeconds?: number;
736}
737/**
738 * A `FieldPath` refers to a field in a document. The path may consist of a
739 * single field name (referring to a top-level field in the document), or a
740 * list of field names (referring to a nested field in the document).
741 *
742 * Create a `FieldPath` by providing field names. If more than one field
743 * name is provided, the path will point to a nested field in a document.
744 */
745export declare class FieldPath {
746 /**
747 * Creates a `FieldPath` from the provided field names. If more than one field
748 * name is provided, the path will point to a nested field in a document.
749 *
750 * @param fieldNames - A list of field names.
751 */
752 constructor(...fieldNames: string[]);
753 /**
754 * Returns true if this `FieldPath` is equal to the provided one.
755 *
756 * @param other - The `FieldPath` to compare against.
757 * @returns true if this `FieldPath` is equal to the provided one.
758 */
759 isEqual(other: FieldPath): boolean;
760}
761/**
762 * Sentinel values that can be used when writing document fields with `set()`
763 * or `update()`.
764 */
765export declare abstract class FieldValue {
766 private constructor();
767 /** Compares `FieldValue`s for equality. */
768 abstract isEqual(other: FieldValue): boolean;
769}
770/* Excluded from this release type: _FirebaseService */
771/**
772 * The Cloud Firestore service interface.
773 *
774 * Do not call this constructor directly. Instead, use {@link (getFirestore:1)}.
775 */
776export declare class Firestore {
777 /**
778 * Whether it's a {@link Firestore} or Firestore Lite instance.
779 */
780 type: 'firestore-lite' | 'firestore';
781 private constructor();
782 /**
783 * The {@link @firebase/app#FirebaseApp} associated with this `Firestore` service
784 * instance.
785 */
786 get app(): FirebaseApp;
787 /**
788 * Returns a JSON-serializable representation of this `Firestore` instance.
789 */
790 toJSON(): object;
791}
792/**
793 * Converter used by `withConverter()` to transform user objects of type
794 * `AppModelType` into Firestore data of type `DbModelType`.
795 *
796 * Using the converter allows you to specify generic type arguments when
797 * storing and retrieving objects from Firestore.
798 *
799 * In this context, an "AppModel" is a class that is used in an application to
800 * package together related information and functionality. Such a class could,
801 * for example, have properties with complex, nested data types, properties used
802 * for memoization, properties of types not supported by Firestore (such as
803 * `symbol` and `bigint`), and helper functions that perform compound
804 * operations. Such classes are not suitable and/or possible to store into a
805 * Firestore database. Instead, instances of such classes need to be converted
806 * to "plain old JavaScript objects" (POJOs) with exclusively primitive
807 * properties, potentially nested inside other POJOs or arrays of POJOs. In this
808 * context, this type is referred to as the "DbModel" and would be an object
809 * suitable for persisting into Firestore. For convenience, applications can
810 * implement `FirestoreDataConverter` and register the converter with Firestore
811 * objects, such as `DocumentReference` or `Query`, to automatically convert
812 * `AppModel` to `DbModel` when storing into Firestore, and convert `DbModel`
813 * to `AppModel` when retrieving from Firestore.
814 *
815 * @example
816 *
817 * Simple Example
818 *
819 * ```typescript
820 * const numberConverter = {
821 * toFirestore(value: WithFieldValue<number>) {
822 * return { value };
823 * },
824 * fromFirestore(snapshot: QueryDocumentSnapshot, options: SnapshotOptions) {
825 * return snapshot.data(options).value as number;
826 * }
827 * };
828 *
829 * async function simpleDemo(db: Firestore): Promise<void> {
830 * const documentRef = doc(db, 'values/value123').withConverter(numberConverter);
831 *
832 * // converters are used with `setDoc`, `addDoc`, and `getDoc`
833 * await setDoc(documentRef, 42);
834 * const snapshot1 = await getDoc(documentRef);
835 * assertEqual(snapshot1.data(), 42);
836 *
837 * // converters are not used when writing data with `updateDoc`
838 * await updateDoc(documentRef, { value: 999 });
839 * const snapshot2 = await getDoc(documentRef);
840 * assertEqual(snapshot2.data(), 999);
841 * }
842 * ```
843 *
844 * Advanced Example
845 *
846 * ```typescript
847 * // The Post class is a model that is used by our application.
848 * // This class may have properties and methods that are specific
849 * // to our application execution, which do not need to be persisted
850 * // to Firestore.
851 * class Post {
852 * constructor(
853 * readonly title: string,
854 * readonly author: string,
855 * readonly lastUpdatedMillis: number
856 * ) {}
857 * toString(): string {
858 * return `${this.title} by ${this.author}`;
859 * }
860 * }
861 *
862 * // The PostDbModel represents how we want our posts to be stored
863 * // in Firestore. This DbModel has different properties (`ttl`,
864 * // `aut`, and `lut`) from the Post class we use in our application.
865 * interface PostDbModel {
866 * ttl: string;
867 * aut: { firstName: string; lastName: string };
868 * lut: Timestamp;
869 * }
870 *
871 * // The `PostConverter` implements `FirestoreDataConverter` and specifies
872 * // how the Firestore SDK can convert `Post` objects to `PostDbModel`
873 * // objects and vice versa.
874 * class PostConverter implements FirestoreDataConverter<Post, PostDbModel> {
875 * toFirestore(post: WithFieldValue<Post>): WithFieldValue<PostDbModel> {
876 * return {
877 * ttl: post.title,
878 * aut: this._autFromAuthor(post.author),
879 * lut: this._lutFromLastUpdatedMillis(post.lastUpdatedMillis)
880 * };
881 * }
882 *
883 * fromFirestore(snapshot: QueryDocumentSnapshot, options: SnapshotOptions): Post {
884 * const data = snapshot.data(options) as PostDbModel;
885 * const author = `${data.aut.firstName} ${data.aut.lastName}`;
886 * return new Post(data.ttl, author, data.lut.toMillis());
887 * }
888 *
889 * _autFromAuthor(
890 * author: string | FieldValue
891 * ): { firstName: string; lastName: string } | FieldValue {
892 * if (typeof author !== 'string') {
893 * // `author` is a FieldValue, so just return it.
894 * return author;
895 * }
896 * const [firstName, lastName] = author.split(' ');
897 * return {firstName, lastName};
898 * }
899 *
900 * _lutFromLastUpdatedMillis(
901 * lastUpdatedMillis: number | FieldValue
902 * ): Timestamp | FieldValue {
903 * if (typeof lastUpdatedMillis !== 'number') {
904 * // `lastUpdatedMillis` must be a FieldValue, so just return it.
905 * return lastUpdatedMillis;
906 * }
907 * return Timestamp.fromMillis(lastUpdatedMillis);
908 * }
909 * }
910 *
911 * async function advancedDemo(db: Firestore): Promise<void> {
912 * // Create a `DocumentReference` with a `FirestoreDataConverter`.
913 * const documentRef = doc(db, 'posts/post123').withConverter(new PostConverter());
914 *
915 * // The `data` argument specified to `setDoc()` is type checked by the
916 * // TypeScript compiler to be compatible with `Post`. Since the `data`
917 * // argument is typed as `WithFieldValue<Post>` rather than just `Post`,
918 * // this allows properties of the `data` argument to also be special
919 * // Firestore values that perform server-side mutations, such as
920 * // `arrayRemove()`, `deleteField()`, and `serverTimestamp()`.
921 * await setDoc(documentRef, {
922 * title: 'My Life',
923 * author: 'Foo Bar',
924 * lastUpdatedMillis: serverTimestamp()
925 * });
926 *
927 * // The TypeScript compiler will fail to compile if the `data` argument to
928 * // `setDoc()` is _not_ compatible with `WithFieldValue<Post>`. This
929 * // type checking prevents the caller from specifying objects with incorrect
930 * // properties or property values.
931 * // @ts-expect-error "Argument of type { ttl: string; } is not assignable
932 * // to parameter of type WithFieldValue<Post>"
933 * await setDoc(documentRef, { ttl: 'The Title' });
934 *
935 * // When retrieving a document with `getDoc()` the `DocumentSnapshot`
936 * // object's `data()` method returns a `Post`, rather than a generic object,
937 * // which would have been returned if the `DocumentReference` did _not_ have a
938 * // `FirestoreDataConverter` attached to it.
939 * const snapshot1: DocumentSnapshot<Post> = await getDoc(documentRef);
940 * const post1: Post = snapshot1.data()!;
941 * if (post1) {
942 * assertEqual(post1.title, 'My Life');
943 * assertEqual(post1.author, 'Foo Bar');
944 * }
945 *
946 * // The `data` argument specified to `updateDoc()` is type checked by the
947 * // TypeScript compiler to be compatible with `PostDbModel`. Note that
948 * // unlike `setDoc()`, whose `data` argument must be compatible with `Post`,
949 * // the `data` argument to `updateDoc()` must be compatible with
950 * // `PostDbModel`. Similar to `setDoc()`, since the `data` argument is typed
951 * // as `WithFieldValue<PostDbModel>` rather than just `PostDbModel`, this
952 * // allows properties of the `data` argument to also be those special
953 * // Firestore values, like `arrayRemove()`, `deleteField()`, and
954 * // `serverTimestamp()`.
955 * await updateDoc(documentRef, {
956 * 'aut.firstName': 'NewFirstName',
957 * lut: serverTimestamp()
958 * });
959 *
960 * // The TypeScript compiler will fail to compile if the `data` argument to
961 * // `updateDoc()` is _not_ compatible with `WithFieldValue<PostDbModel>`.
962 * // This type checking prevents the caller from specifying objects with
963 * // incorrect properties or property values.
964 * // @ts-expect-error "Argument of type { title: string; } is not assignable
965 * // to parameter of type WithFieldValue<PostDbModel>"
966 * await updateDoc(documentRef, { title: 'New Title' });
967 * const snapshot2: DocumentSnapshot<Post> = await getDoc(documentRef);
968 * const post2: Post = snapshot2.data()!;
969 * if (post2) {
970 * assertEqual(post2.title, 'My Life');
971 * assertEqual(post2.author, 'NewFirstName Bar');
972 * }
973 * }
974 * ```
975 */
976export declare interface FirestoreDataConverter<AppModelType, DbModelType extends DocumentData = DocumentData> {
977 /**