1 | /**
|
2 | * Cloud Firestore
|
3 | *
|
4 | * @packageDocumentation
|
5 | */
|
6 | import { FirebaseApp } from '@firebase/app';
|
7 | import { LogLevelString as LogLevel } from '@firebase/logger';
|
8 | import { EmulatorMockTokenOptions } from '@firebase/util';
|
9 | import { 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 | */
|
21 | export 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 | */
|
26 | export 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 | */
|
32 | export 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 | */
|
44 | export declare function aggregateFieldEqual(left: AggregateField<unknown>, right: AggregateField<unknown>): boolean;
|
45 | /**
|
46 | * The union of all `AggregateField` types that are supported by Firestore.
|
47 | */
|
48 | export declare type AggregateFieldType = ReturnType<typeof sum> | ReturnType<typeof average> | ReturnType<typeof count>;
|
49 | /**
|
50 | * The results of executing an aggregation query.
|
51 | */
|
52 | export 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 | */
|
86 | export 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 | */
|
90 | export 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 | */
|
98 | export 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 | */
|
104 | export 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 | */
|
115 | export 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 | */
|
127 | export 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 | */
|
140 | export 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 | */
|
148 | export declare function average(field: string | FieldPath): AggregateField<number | null>;
|
149 | /**
|
150 | * An immutable object representing an array of bytes.
|
151 | */
|
152 | export 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 | * { Firestore} instance.
|
198 | */
|
199 | export 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 | */
|
210 | export 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 | */
|
233 | export 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 | */
|
246 | export 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 | */
|
259 | export 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 | */
|
272 | export 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 | */
|
284 | export 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 | */
|
289 | export 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 {
|
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 | * from Firestore.
converter - Converts objects to and |
313 | * `CollectionReference` that uses the provided converter.
A |
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 | */
|
338 | export 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 | */
|
345 | export 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 | */
|
352 | export 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 | */
|
360 | export 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 | */
|
365 | export 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 | */
|
374 | export 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 | */
|
380 | export 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 | */
|
393 | export 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 | */
|
409 | export 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 | */
|
422 | export 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 | */
|
427 | export 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 | */
|
449 | export 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 | */
|
454 | export 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 | */
|
462 | export 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 | */
|
468 | export 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 {
|
497 | * 1)}, { /firestore/lite#getDoc}, etc. with the returned `DocumentReference`
/firestore/lite#(setDoc: |
498 | * instance, the provided converter will convert between Firestore data of
|
499 | * type `NewDbModelType` and your custom type `NewAppModelType`.
|
500 | *
|
501 | * from Firestore.
converter - Converts objects to and |
502 | * `DocumentReference` that uses the provided converter.
A |
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 | */
|
523 | export 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 */
|
577 | export { 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 | */
|
607 | export 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 | */
|
634 | export 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 | */
|
641 | export 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 | */
|
649 | export 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 | */
|
659 | export 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 | */
|
669 | export 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 | */
|
679 | export 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 | */
|
689 | export 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 | */
|
717 | export 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 | */
|
745 | export 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 | */
|
765 | export 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 | */
|
776 | export 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 {with this `Firestore` service
/app#FirebaseApp} associated |
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 | */
|
976 | export declare interface FirestoreDataConverter<AppModelType, DbModelType extends DocumentData = DocumentData> {
|
977 | /**
|