UNPKG

70.4 kBTypeScriptView Raw
1/**
2 * Firebase Realtime Database
3 *
4 * @packageDocumentation
5 */
6import { FirebaseApp } from '@firebase/app';
7import { EmulatorMockTokenOptions } from '@firebase/util';
8
9/**
10 * Gets a `Reference` for the location at the specified relative path.
11 *
12 * The relative path can either be a simple child name (for example, "ada") or
13 * a deeper slash-separated path (for example, "ada/name/first").
14 *
15 * @param parent - The parent location.
16 * @param path - A relative path from this location to the desired child
17 * location.
18 * @returns The specified child location.
19 */
20export declare function child(parent: DatabaseReference, path: string): DatabaseReference;
21/**
22 * Modify the provided instance to communicate with the Realtime Database
23 * emulator.
24 *
25 * <p>Note: This method must be called before performing any other operation.
26 *
27 * @param db - The instance to modify.
28 * @param host - The emulator host (ex: localhost)
29 * @param port - The emulator port (ex: 8080)
30 * @param options.mockUserToken - the mock auth token to use for unit testing Security Rules
31 */
32export declare function connectDatabaseEmulator(db: Database, host: string, port: number, options?: {
33 mockUserToken?: EmulatorMockTokenOptions | string;
34}): void;
35/**
36 * Class representing a Firebase Realtime Database.
37 */
38export declare class Database {
39 /** The {@link @firebase/app#FirebaseApp} associated with this Realtime Database instance. */
40 readonly app: FirebaseApp;
41 /** Represents a `Database` instance. */
42 readonly 'type' = "database";
43 private constructor();
44}
45/**
46 * A `DatabaseReference` represents a specific location in your Database and can be used
47 * for reading or writing data to that Database location.
48 *
49 * You can reference the root or child location in your Database by calling
50 * `ref()` or `ref("child/path")`.
51 *
52 * Writing is done with the `set()` method and reading can be done with the
53 * `on*()` method. See {@link
54 * https://firebase.google.com/docs/database/web/read-and-write}
55 */
56export declare interface DatabaseReference extends Query {
57 /**
58 * The last part of the `DatabaseReference`'s path.
59 *
60 * For example, `"ada"` is the key for
61 * `https://<DATABASE_NAME>.firebaseio.com/users/ada`.
62 *
63 * The key of a root `DatabaseReference` is `null`.
64 */
65 readonly key: string | null;
66 /**
67 * The parent location of a `DatabaseReference`.
68 *
69 * The parent of a root `DatabaseReference` is `null`.
70 */
71 readonly parent: DatabaseReference | null;
72 /** The root `DatabaseReference` of the Database. */
73 readonly root: DatabaseReference;
74}
75/**
76 * A `DataSnapshot` contains data from a Database location.
77 *
78 * Any time you read data from the Database, you receive the data as a
79 * `DataSnapshot`. A `DataSnapshot` is passed to the event callbacks you attach
80 * with `on()` or `once()`. You can extract the contents of the snapshot as a
81 * JavaScript object by calling the `val()` method. Alternatively, you can
82 * traverse into the snapshot by calling `child()` to return child snapshots
83 * (which you could then call `val()` on).
84 *
85 * A `DataSnapshot` is an efficiently generated, immutable copy of the data at
86 * a Database location. It cannot be modified and will never change (to modify
87 * data, you always call the `set()` method on a `Reference` directly).
88 */
89export declare class DataSnapshot {
90 /**
91 * The location of this DataSnapshot.
92 */
93 readonly ref: DatabaseReference;
94 private constructor();
95 /**
96 * Gets the priority value of the data in this `DataSnapshot`.
97 *
98 * Applications need not use priority but can order collections by
99 * ordinary properties (see
100 * {@link https://firebase.google.com/docs/database/web/lists-of-data#sorting_and_filtering_data |Sorting and filtering data}
101 * ).
102 */
103 get priority(): string | number | null;
104 /**
105 * The key (last part of the path) of the location of this `DataSnapshot`.
106 *
107 * The last token in a Database location is considered its key. For example,
108 * "ada" is the key for the /users/ada/ node. Accessing the key on any
109 * `DataSnapshot` will return the key for the location that generated it.
110 * However, accessing the key on the root URL of a Database will return
111 * `null`.
112 */
113 get key(): string | null;
114 /** Returns the number of child properties of this `DataSnapshot`. */
115 get size(): number;
116 /**
117 * Gets another `DataSnapshot` for the location at the specified relative path.
118 *
119 * Passing a relative path to the `child()` method of a DataSnapshot returns
120 * another `DataSnapshot` for the location at the specified relative path. The
121 * relative path can either be a simple child name (for example, "ada") or a
122 * deeper, slash-separated path (for example, "ada/name/first"). If the child
123 * location has no data, an empty `DataSnapshot` (that is, a `DataSnapshot`
124 * whose value is `null`) is returned.
125 *
126 * @param path - A relative path to the location of child data.
127 */
128 child(path: string): DataSnapshot;
129 /**
130 * Returns true if this `DataSnapshot` contains any data. It is slightly more
131 * efficient than using `snapshot.val() !== null`.
132 */
133 exists(): boolean;
134 /**
135 * Exports the entire contents of the DataSnapshot as a JavaScript object.
136 *
137 * The `exportVal()` method is similar to `val()`, except priority information
138 * is included (if available), making it suitable for backing up your data.
139 *
140 * @returns The DataSnapshot's contents as a JavaScript value (Object,
141 * Array, string, number, boolean, or `null`).
142 */
143 exportVal(): any;
144 /**
145 * Enumerates the top-level children in the `DataSnapshot`.
146 *
147 * Because of the way JavaScript objects work, the ordering of data in the
148 * JavaScript object returned by `val()` is not guaranteed to match the
149 * ordering on the server nor the ordering of `onChildAdded()` events. That is
150 * where `forEach()` comes in handy. It guarantees the children of a
151 * `DataSnapshot` will be iterated in their query order.
152 *
153 * If no explicit `orderBy*()` method is used, results are returned
154 * ordered by key (unless priorities are used, in which case, results are
155 * returned by priority).
156 *
157 * @param action - A function that will be called for each child DataSnapshot.
158 * The callback can return true to cancel further enumeration.
159 * @returns true if enumeration was canceled due to your callback returning
160 * true.
161 */
162 forEach(action: (child: DataSnapshot) => boolean | void): boolean;
163 /**
164 * Returns true if the specified child path has (non-null) data.
165 *
166 * @param path - A relative path to the location of a potential child.
167 * @returns `true` if data exists at the specified child path; else
168 * `false`.
169 */
170 hasChild(path: string): boolean;
171 /**
172 * Returns whether or not the `DataSnapshot` has any non-`null` child
173 * properties.
174 *
175 * You can use `hasChildren()` to determine if a `DataSnapshot` has any
176 * children. If it does, you can enumerate them using `forEach()`. If it
177 * doesn't, then either this snapshot contains a primitive value (which can be
178 * retrieved with `val()`) or it is empty (in which case, `val()` will return
179 * `null`).
180 *
181 * @returns true if this snapshot has any children; else false.
182 */
183 hasChildren(): boolean;
184 /**
185 * Returns a JSON-serializable representation of this object.
186 */
187 toJSON(): object | null;
188 /**
189 * Extracts a JavaScript value from a `DataSnapshot`.
190 *
191 * Depending on the data in a `DataSnapshot`, the `val()` method may return a
192 * scalar type (string, number, or boolean), an array, or an object. It may
193 * also return null, indicating that the `DataSnapshot` is empty (contains no
194 * data).
195 *
196 * @returns The DataSnapshot's contents as a JavaScript value (Object,
197 * Array, string, number, boolean, or `null`).
198 */
199 val(): any;
200}
201export { EmulatorMockTokenOptions };
202/**
203 * Logs debugging information to the console.
204 *
205 * @param enabled - Enables logging if `true`, disables logging if `false`.
206 * @param persistent - Remembers the logging state between page refreshes if
207 * `true`.
208 */
209export declare function enableLogging(enabled: boolean, persistent?: boolean): any;
210/**
211 * Logs debugging information to the console.
212 *
213 * @param logger - A custom logger function to control how things get logged.
214 */
215export declare function enableLogging(logger: (message: string) => unknown): any;
216/**
217 * Creates a `QueryConstraint` with the specified ending point.
218 *
219 * Using `startAt()`, `startAfter()`, `endBefore()`, `endAt()` and `equalTo()`
220 * allows you to choose arbitrary starting and ending points for your queries.
221 *
222 * The ending point is inclusive, so children with exactly the specified value
223 * will be included in the query. The optional key argument can be used to
224 * further limit the range of the query. If it is specified, then children that
225 * have exactly the specified value must also have a key name less than or equal
226 * to the specified key.
227 *
228 * You can read more about `endAt()` in
229 * {@link https://firebase.google.com/docs/database/web/lists-of-data#filtering_data | Filtering data}.
230 *
231 * @param value - The value to end at. The argument type depends on which
232 * `orderBy*()` function was used in this query. Specify a value that matches
233 * the `orderBy*()` type. When used in combination with `orderByKey()`, the
234 * value must be a string.
235 * @param key - The child key to end at, among the children with the previously
236 * specified priority. This argument is only allowed if ordering by child,
237 * value, or priority.
238 */
239export declare function endAt(value: number | string | boolean | null, key?: string): QueryConstraint;
240/**
241 * Creates a `QueryConstraint` with the specified ending point (exclusive).
242 *
243 * Using `startAt()`, `startAfter()`, `endBefore()`, `endAt()` and `equalTo()`
244 * allows you to choose arbitrary starting and ending points for your queries.
245 *
246 * The ending point is exclusive. If only a value is provided, children
247 * with a value less than the specified value will be included in the query.
248 * If a key is specified, then children must have a value lesss than or equal
249 * to the specified value and a a key name less than the specified key.
250 *
251 * @param value - The value to end before. The argument type depends on which
252 * `orderBy*()` function was used in this query. Specify a value that matches
253 * the `orderBy*()` type. When used in combination with `orderByKey()`, the
254 * value must be a string.
255 * @param key - The child key to end before, among the children with the
256 * previously specified priority. This argument is only allowed if ordering by
257 * child, value, or priority.
258 */
259export declare function endBefore(value: number | string | boolean | null, key?: string): QueryConstraint;
260/**
261 * Creates a `QueryConstraint` that includes children that match the specified
262 * value.
263 *
264 * Using `startAt()`, `startAfter()`, `endBefore()`, `endAt()` and `equalTo()`
265 * allows you to choose arbitrary starting and ending points for your queries.
266 *
267 * The optional key argument can be used to further limit the range of the
268 * query. If it is specified, then children that have exactly the specified
269 * value must also have exactly the specified key as their key name. This can be
270 * used to filter result sets with many matches for the same value.
271 *
272 * You can read more about `equalTo()` in
273 * {@link https://firebase.google.com/docs/database/web/lists-of-data#filtering_data | Filtering data}.
274 *
275 * @param value - The value to match for. The argument type depends on which
276 * `orderBy*()` function was used in this query. Specify a value that matches
277 * the `orderBy*()` type. When used in combination with `orderByKey()`, the
278 * value must be a string.
279 * @param key - The child key to start at, among the children with the
280 * previously specified priority. This argument is only allowed if ordering by
281 * child, value, or priority.
282 */
283export declare function equalTo(value: number | string | boolean | null, key?: string): QueryConstraint;
284/**
285 * One of the following strings: "value", "child_added", "child_changed",
286 * "child_removed", or "child_moved."
287 */
288export declare type EventType = 'value' | 'child_added' | 'child_changed' | 'child_moved' | 'child_removed';
289/* Excluded from this release type: _FirebaseService */
290/**
291 * Force the use of longPolling instead of websockets. This will be ignored if websocket protocol is used in databaseURL.
292 */
293export declare function forceLongPolling(): void;
294/**
295 * Force the use of websockets instead of longPolling.
296 */
297export declare function forceWebSockets(): void;
298/**
299 * Gets the most up-to-date result for this query.
300 *
301 * @param query - The query to run.
302 * @returns A `Promise` which resolves to the resulting DataSnapshot if a value is
303 * available, or rejects if the client is unable to return a value (e.g., if the
304 * server is unreachable and there is nothing cached).
305 */
306export declare function get(query: Query): Promise<DataSnapshot>;
307/**
308 * Returns the instance of the Realtime Database SDK that is associated
309 * with the provided {@link @firebase/app#FirebaseApp}. Initializes a new instance with
310 * with default settings if no instance exists or if the existing instance uses
311 * a custom database URL.
312 *
313 * @param app - The {@link @firebase/app#FirebaseApp} instance that the returned Realtime
314 * Database instance is associated with.
315 * @param url - The URL of the Realtime Database instance to connect to. If not
316 * provided, the SDK connects to the default instance of the Firebase App.
317 * @returns The `Database` instance of the provided app.
318 */
319export declare function getDatabase(app?: FirebaseApp, url?: string): Database;
320/**
321 * Disconnects from the server (all Database operations will be completed
322 * offline).
323 *
324 * The client automatically maintains a persistent connection to the Database
325 * server, which will remain active indefinitely and reconnect when
326 * disconnected. However, the `goOffline()` and `goOnline()` methods may be used
327 * to control the client connection in cases where a persistent connection is
328 * undesirable.
329 *
330 * While offline, the client will no longer receive data updates from the
331 * Database. However, all Database operations performed locally will continue to
332 * immediately fire events, allowing your application to continue behaving
333 * normally. Additionally, each operation performed locally will automatically
334 * be queued and retried upon reconnection to the Database server.
335 *
336 * To reconnect to the Database and begin receiving remote events, see
337 * `goOnline()`.
338 *
339 * @param db - The instance to disconnect.
340 */
341export declare function goOffline(db: Database): void;
342/**
343 * Reconnects to the server and synchronizes the offline Database state
344 * with the server state.
345 *
346 * This method should be used after disabling the active connection with
347 * `goOffline()`. Once reconnected, the client will transmit the proper data
348 * and fire the appropriate events so that your client "catches up"
349 * automatically.
350 *
351 * @param db - The instance to reconnect.
352 */
353export declare function goOnline(db: Database): void;
354/**
355 * Returns a placeholder value that can be used to atomically increment the
356 * current database value by the provided delta.
357 *
358 * @param delta - the amount to modify the current value atomically.
359 * @returns A placeholder value for modifying data atomically server-side.
360 */
361export declare function increment(delta: number): object;
362/**
363 * Creates a new `QueryConstraint` that if limited to the first specific number
364 * of children.
365 *
366 * The `limitToFirst()` method is used to set a maximum number of children to be
367 * synced for a given callback. If we set a limit of 100, we will initially only
368 * receive up to 100 `child_added` events. If we have fewer than 100 messages
369 * stored in our Database, a `child_added` event will fire for each message.
370 * However, if we have over 100 messages, we will only receive a `child_added`
371 * event for the first 100 ordered messages. As items change, we will receive
372 * `child_removed` events for each item that drops out of the active list so
373 * that the total number stays at 100.
374 *
375 * You can read more about `limitToFirst()` in
376 * {@link https://firebase.google.com/docs/database/web/lists-of-data#filtering_data | Filtering data}.
377 *
378 * @param limit - The maximum number of nodes to include in this query.
379 */
380export declare function limitToFirst(limit: number): QueryConstraint;
381/**
382 * Creates a new `QueryConstraint` that is limited to return only the last
383 * specified number of children.
384 *
385 * The `limitToLast()` method is used to set a maximum number of children to be
386 * synced for a given callback. If we set a limit of 100, we will initially only
387 * receive up to 100 `child_added` events. If we have fewer than 100 messages
388 * stored in our Database, a `child_added` event will fire for each message.
389 * However, if we have over 100 messages, we will only receive a `child_added`
390 * event for the last 100 ordered messages. As items change, we will receive
391 * `child_removed` events for each item that drops out of the active list so
392 * that the total number stays at 100.
393 *
394 * You can read more about `limitToLast()` in
395 * {@link https://firebase.google.com/docs/database/web/lists-of-data#filtering_data | Filtering data}.
396 *
397 * @param limit - The maximum number of nodes to include in this query.
398 */
399export declare function limitToLast(limit: number): QueryConstraint;
400/** An options objects that can be used to customize a listener. */
401export declare interface ListenOptions {
402 /** Whether to remove the listener after its first invocation. */
403 readonly onlyOnce?: boolean;
404}
405/**
406 * Detaches a callback previously attached with `on()`.
407 *
408 * Detach a callback previously attached with `on()`. Note that if `on()` was
409 * called multiple times with the same eventType and callback, the callback
410 * will be called multiple times for each event, and `off()` must be called
411 * multiple times to remove the callback. Calling `off()` on a parent listener
412 * will not automatically remove listeners registered on child nodes, `off()`
413 * must also be called on any child listeners to remove the callback.
414 *
415 * If a callback is not specified, all callbacks for the specified eventType
416 * will be removed. Similarly, if no eventType is specified, all callbacks
417 * for the `Reference` will be removed.
418 *
419 * Individual listeners can also be removed by invoking their unsubscribe
420 * callbacks.
421 *
422 * @param query - The query that the listener was registered with.
423 * @param eventType - One of the following strings: "value", "child_added",
424 * "child_changed", "child_removed", or "child_moved." If omitted, all callbacks
425 * for the `Reference` will be removed.
426 * @param callback - The callback function that was passed to `on()` or
427 * `undefined` to remove all callbacks.
428 */
429export declare function off(query: Query, eventType?: EventType, callback?: (snapshot: DataSnapshot, previousChildName?: string | null) => unknown): void;
430/**
431 * Listens for data changes at a particular location.
432 *
433 * This is the primary way to read data from a Database. Your callback
434 * will be triggered for the initial data and again whenever the data changes.
435 * Invoke the returned unsubscribe callback to stop receiving updates. See
436 * {@link https://firebase.google.com/docs/database/web/retrieve-data | Retrieve Data on the Web}
437 * for more details.
438 *
439 * An `onChildAdded` event will be triggered once for each initial child at this
440 * location, and it will be triggered again every time a new child is added. The
441 * `DataSnapshot` passed into the callback will reflect the data for the
442 * relevant child. For ordering purposes, it is passed a second argument which
443 * is a string containing the key of the previous sibling child by sort order,
444 * or `null` if it is the first child.
445 *
446 * @param query - The query to run.
447 * @param callback - A callback that fires when the specified event occurs.
448 * The callback will be passed a DataSnapshot and a string containing the key of
449 * the previous child, by sort order, or `null` if it is the first child.
450 * @param cancelCallback - An optional callback that will be notified if your
451 * event subscription is ever canceled because your client does not have
452 * permission to read this data (or it had permission but has now lost it).
453 * This callback will be passed an `Error` object indicating why the failure
454 * occurred.
455 * @returns A function that can be invoked to remove the listener.
456 */
457export declare function onChildAdded(query: Query, callback: (snapshot: DataSnapshot, previousChildName?: string | null) => unknown, cancelCallback?: (error: Error) => unknown): Unsubscribe;
458/**
459 * Listens for data changes at a particular location.
460 *
461 * This is the primary way to read data from a Database. Your callback
462 * will be triggered for the initial data and again whenever the data changes.
463 * Invoke the returned unsubscribe callback to stop receiving updates. See
464 * {@link https://firebase.google.com/docs/database/web/retrieve-data | Retrieve Data on the Web}
465 * for more details.
466 *
467 * An `onChildAdded` event will be triggered once for each initial child at this
468 * location, and it will be triggered again every time a new child is added. The
469 * `DataSnapshot` passed into the callback will reflect the data for the
470 * relevant child. For ordering purposes, it is passed a second argument which
471 * is a string containing the key of the previous sibling child by sort order,
472 * or `null` if it is the first child.
473 *
474 * @param query - The query to run.
475 * @param callback - A callback that fires when the specified event occurs.
476 * The callback will be passed a DataSnapshot and a string containing the key of
477 * the previous child, by sort order, or `null` if it is the first child.
478 * @param options - An object that can be used to configure `onlyOnce`, which
479 * then removes the listener after its first invocation.
480 * @returns A function that can be invoked to remove the listener.
481 */
482export declare function onChildAdded(query: Query, callback: (snapshot: DataSnapshot, previousChildName: string | null) => unknown, options: ListenOptions): Unsubscribe;
483/**
484 * Listens for data changes at a particular location.
485 *
486 * This is the primary way to read data from a Database. Your callback
487 * will be triggered for the initial data and again whenever the data changes.
488 * Invoke the returned unsubscribe callback to stop receiving updates. See
489 * {@link https://firebase.google.com/docs/database/web/retrieve-data | Retrieve Data on the Web}
490 * for more details.
491 *
492 * An `onChildAdded` event will be triggered once for each initial child at this
493 * location, and it will be triggered again every time a new child is added. The
494 * `DataSnapshot` passed into the callback will reflect the data for the
495 * relevant child. For ordering purposes, it is passed a second argument which
496 * is a string containing the key of the previous sibling child by sort order,
497 * or `null` if it is the first child.
498 *
499 * @param query - The query to run.
500 * @param callback - A callback that fires when the specified event occurs.
501 * The callback will be passed a DataSnapshot and a string containing the key of
502 * the previous child, by sort order, or `null` if it is the first child.
503 * @param cancelCallback - An optional callback that will be notified if your
504 * event subscription is ever canceled because your client does not have
505 * permission to read this data (or it had permission but has now lost it).
506 * This callback will be passed an `Error` object indicating why the failure
507 * occurred.
508 * @param options - An object that can be used to configure `onlyOnce`, which
509 * then removes the listener after its first invocation.
510 * @returns A function that can be invoked to remove the listener.
511 */
512export declare function onChildAdded(query: Query, callback: (snapshot: DataSnapshot, previousChildName: string | null) => unknown, cancelCallback: (error: Error) => unknown, options: ListenOptions): Unsubscribe;
513/**
514 * Listens for data changes at a particular location.
515 *
516 * This is the primary way to read data from a Database. Your callback
517 * will be triggered for the initial data and again whenever the data changes.
518 * Invoke the returned unsubscribe callback to stop receiving updates. See
519 * {@link https://firebase.google.com/docs/database/web/retrieve-data | Retrieve Data on the Web}
520 * for more details.
521 *
522 * An `onChildChanged` event will be triggered when the data stored in a child
523 * (or any of its descendants) changes. Note that a single `child_changed` event
524 * may represent multiple changes to the child. The `DataSnapshot` passed to the
525 * callback will contain the new child contents. For ordering purposes, the
526 * callback is also passed a second argument which is a string containing the
527 * key of the previous sibling child by sort order, or `null` if it is the first
528 * child.
529 *
530 * @param query - The query to run.
531 * @param callback - A callback that fires when the specified event occurs.
532 * The callback will be passed a DataSnapshot and a string containing the key of
533 * the previous child, by sort order, or `null` if it is the first child.
534 * @param cancelCallback - An optional callback that will be notified if your
535 * event subscription is ever canceled because your client does not have
536 * permission to read this data (or it had permission but has now lost it).
537 * This callback will be passed an `Error` object indicating why the failure
538 * occurred.
539 * @returns A function that can be invoked to remove the listener.
540 */
541export declare function onChildChanged(query: Query, callback: (snapshot: DataSnapshot, previousChildName: string | null) => unknown, cancelCallback?: (error: Error) => unknown): Unsubscribe;
542/**
543 * Listens for data changes at a particular location.
544 *
545 * This is the primary way to read data from a Database. Your callback
546 * will be triggered for the initial data and again whenever the data changes.
547 * Invoke the returned unsubscribe callback to stop receiving updates. See
548 * {@link https://firebase.google.com/docs/database/web/retrieve-data | Retrieve Data on the Web}
549 * for more details.
550 *
551 * An `onChildChanged` event will be triggered when the data stored in a child
552 * (or any of its descendants) changes. Note that a single `child_changed` event
553 * may represent multiple changes to the child. The `DataSnapshot` passed to the
554 * callback will contain the new child contents. For ordering purposes, the
555 * callback is also passed a second argument which is a string containing the
556 * key of the previous sibling child by sort order, or `null` if it is the first
557 * child.
558 *
559 * @param query - The query to run.
560 * @param callback - A callback that fires when the specified event occurs.
561 * The callback will be passed a DataSnapshot and a string containing the key of
562 * the previous child, by sort order, or `null` if it is the first child.
563 * @param options - An object that can be used to configure `onlyOnce`, which
564 * then removes the listener after its first invocation.
565 * @returns A function that can be invoked to remove the listener.
566 */
567export declare function onChildChanged(query: Query, callback: (snapshot: DataSnapshot, previousChildName: string | null) => unknown, options: ListenOptions): Unsubscribe;
568/**
569 * Listens for data changes at a particular location.
570 *
571 * This is the primary way to read data from a Database. Your callback
572 * will be triggered for the initial data and again whenever the data changes.
573 * Invoke the returned unsubscribe callback to stop receiving updates. See
574 * {@link https://firebase.google.com/docs/database/web/retrieve-data | Retrieve Data on the Web}
575 * for more details.
576 *
577 * An `onChildChanged` event will be triggered when the data stored in a child
578 * (or any of its descendants) changes. Note that a single `child_changed` event
579 * may represent multiple changes to the child. The `DataSnapshot` passed to the
580 * callback will contain the new child contents. For ordering purposes, the
581 * callback is also passed a second argument which is a string containing the
582 * key of the previous sibling child by sort order, or `null` if it is the first
583 * child.
584 *
585 * @param query - The query to run.
586 * @param callback - A callback that fires when the specified event occurs.
587 * The callback will be passed a DataSnapshot and a string containing the key of
588 * the previous child, by sort order, or `null` if it is the first child.
589 * @param cancelCallback - An optional callback that will be notified if your
590 * event subscription is ever canceled because your client does not have
591 * permission to read this data (or it had permission but has now lost it).
592 * This callback will be passed an `Error` object indicating why the failure
593 * occurred.
594 * @param options - An object that can be used to configure `onlyOnce`, which
595 * then removes the listener after its first invocation.
596 * @returns A function that can be invoked to remove the listener.
597 */
598export declare function onChildChanged(query: Query, callback: (snapshot: DataSnapshot, previousChildName: string | null) => unknown, cancelCallback: (error: Error) => unknown, options: ListenOptions): Unsubscribe;
599/**
600 * Listens for data changes at a particular location.
601 *
602 * This is the primary way to read data from a Database. Your callback
603 * will be triggered for the initial data and again whenever the data changes.
604 * Invoke the returned unsubscribe callback to stop receiving updates. See
605 * {@link https://firebase.google.com/docs/database/web/retrieve-data | Retrieve Data on the Web}
606 * for more details.
607 *
608 * An `onChildMoved` event will be triggered when a child's sort order changes
609 * such that its position relative to its siblings changes. The `DataSnapshot`
610 * passed to the callback will be for the data of the child that has moved. It
611 * is also passed a second argument which is a string containing the key of the
612 * previous sibling child by sort order, or `null` if it is the first child.
613 *
614 * @param query - The query to run.
615 * @param callback - A callback that fires when the specified event occurs.
616 * The callback will be passed a DataSnapshot and a string containing the key of
617 * the previous child, by sort order, or `null` if it is the first child.
618 * @param cancelCallback - An optional callback that will be notified if your
619 * event subscription is ever canceled because your client does not have
620 * permission to read this data (or it had permission but has now lost it).
621 * This callback will be passed an `Error` object indicating why the failure
622 * occurred.
623 * @returns A function that can be invoked to remove the listener.
624 */
625export declare function onChildMoved(query: Query, callback: (snapshot: DataSnapshot, previousChildName: string | null) => unknown, cancelCallback?: (error: Error) => unknown): Unsubscribe;
626/**
627 * Listens for data changes at a particular location.
628 *
629 * This is the primary way to read data from a Database. Your callback
630 * will be triggered for the initial data and again whenever the data changes.
631 * Invoke the returned unsubscribe callback to stop receiving updates. See
632 * {@link https://firebase.google.com/docs/database/web/retrieve-data | Retrieve Data on the Web}
633 * for more details.
634 *
635 * An `onChildMoved` event will be triggered when a child's sort order changes
636 * such that its position relative to its siblings changes. The `DataSnapshot`
637 * passed to the callback will be for the data of the child that has moved. It
638 * is also passed a second argument which is a string containing the key of the
639 * previous sibling child by sort order, or `null` if it is the first child.
640 *
641 * @param query - The query to run.
642 * @param callback - A callback that fires when the specified event occurs.
643 * The callback will be passed a DataSnapshot and a string containing the key of
644 * the previous child, by sort order, or `null` if it is the first child.
645 * @param options - An object that can be used to configure `onlyOnce`, which
646 * then removes the listener after its first invocation.
647 * @returns A function that can be invoked to remove the listener.
648 */
649export declare function onChildMoved(query: Query, callback: (snapshot: DataSnapshot, previousChildName: string | null) => unknown, options: ListenOptions): Unsubscribe;
650/**
651 * Listens for data changes at a particular location.
652 *
653 * This is the primary way to read data from a Database. Your callback
654 * will be triggered for the initial data and again whenever the data changes.
655 * Invoke the returned unsubscribe callback to stop receiving updates. See
656 * {@link https://firebase.google.com/docs/database/web/retrieve-data | Retrieve Data on the Web}
657 * for more details.
658 *
659 * An `onChildMoved` event will be triggered when a child's sort order changes
660 * such that its position relative to its siblings changes. The `DataSnapshot`
661 * passed to the callback will be for the data of the child that has moved. It
662 * is also passed a second argument which is a string containing the key of the
663 * previous sibling child by sort order, or `null` if it is the first child.
664 *
665 * @param query - The query to run.
666 * @param callback - A callback that fires when the specified event occurs.
667 * The callback will be passed a DataSnapshot and a string containing the key of
668 * the previous child, by sort order, or `null` if it is the first child.
669 * @param cancelCallback - An optional callback that will be notified if your
670 * event subscription is ever canceled because your client does not have
671 * permission to read this data (or it had permission but has now lost it).
672 * This callback will be passed an `Error` object indicating why the failure
673 * occurred.
674 * @param options - An object that can be used to configure `onlyOnce`, which
675 * then removes the listener after its first invocation.
676 * @returns A function that can be invoked to remove the listener.
677 */
678export declare function onChildMoved(query: Query, callback: (snapshot: DataSnapshot, previousChildName: string | null) => unknown, cancelCallback: (error: Error) => unknown, options: ListenOptions): Unsubscribe;
679/**
680 * Listens for data changes at a particular location.
681 *
682 * This is the primary way to read data from a Database. Your callback
683 * will be triggered for the initial data and again whenever the data changes.
684 * Invoke the returned unsubscribe callback to stop receiving updates. See
685 * {@link https://firebase.google.com/docs/database/web/retrieve-data | Retrieve Data on the Web}
686 * for more details.
687 *
688 * An `onChildRemoved` event will be triggered once every time a child is
689 * removed. The `DataSnapshot` passed into the callback will be the old data for
690 * the child that was removed. A child will get removed when either:
691 *
692 * - a client explicitly calls `remove()` on that child or one of its ancestors
693 * - a client calls `set(null)` on that child or one of its ancestors
694 * - that child has all of its children removed
695 * - there is a query in effect which now filters out the child (because it's
696 * sort order changed or the max limit was hit)
697 *
698 * @param query - The query to run.
699 * @param callback - A callback that fires when the specified event occurs.
700 * The callback will be passed a DataSnapshot and a string containing the key of
701 * the previous child, by sort order, or `null` if it is the first child.
702 * @param cancelCallback - An optional callback that will be notified if your
703 * event subscription is ever canceled because your client does not have
704 * permission to read this data (or it had permission but has now lost it).
705 * This callback will be passed an `Error` object indicating why the failure
706 * occurred.
707 * @returns A function that can be invoked to remove the listener.
708 */
709export declare function onChildRemoved(query: Query, callback: (snapshot: DataSnapshot) => unknown, cancelCallback?: (error: Error) => unknown): Unsubscribe;
710/**
711 * Listens for data changes at a particular location.
712 *
713 * This is the primary way to read data from a Database. Your callback
714 * will be triggered for the initial data and again whenever the data changes.
715 * Invoke the returned unsubscribe callback to stop receiving updates. See
716 * {@link https://firebase.google.com/docs/database/web/retrieve-data | Retrieve Data on the Web}
717 * for more details.
718 *
719 * An `onChildRemoved` event will be triggered once every time a child is
720 * removed. The `DataSnapshot` passed into the callback will be the old data for
721 * the child that was removed. A child will get removed when either:
722 *
723 * - a client explicitly calls `remove()` on that child or one of its ancestors
724 * - a client calls `set(null)` on that child or one of its ancestors
725 * - that child has all of its children removed
726 * - there is a query in effect which now filters out the child (because it's
727 * sort order changed or the max limit was hit)
728 *
729 * @param query - The query to run.
730 * @param callback - A callback that fires when the specified event occurs.
731 * The callback will be passed a DataSnapshot and a string containing the key of
732 * the previous child, by sort order, or `null` if it is the first child.
733 * @param options - An object that can be used to configure `onlyOnce`, which
734 * then removes the listener after its first invocation.
735 * @returns A function that can be invoked to remove the listener.
736 */
737export declare function onChildRemoved(query: Query, callback: (snapshot: DataSnapshot) => unknown, options: ListenOptions): Unsubscribe;
738/**
739 * Listens for data changes at a particular location.
740 *
741 * This is the primary way to read data from a Database. Your callback
742 * will be triggered for the initial data and again whenever the data changes.
743 * Invoke the returned unsubscribe callback to stop receiving updates. See
744 * {@link https://firebase.google.com/docs/database/web/retrieve-data | Retrieve Data on the Web}
745 * for more details.
746 *
747 * An `onChildRemoved` event will be triggered once every time a child is
748 * removed. The `DataSnapshot` passed into the callback will be the old data for
749 * the child that was removed. A child will get removed when either:
750 *
751 * - a client explicitly calls `remove()` on that child or one of its ancestors
752 * - a client calls `set(null)` on that child or one of its ancestors
753 * - that child has all of its children removed
754 * - there is a query in effect which now filters out the child (because it's
755 * sort order changed or the max limit was hit)
756 *
757 * @param query - The query to run.
758 * @param callback - A callback that fires when the specified event occurs.
759 * The callback will be passed a DataSnapshot and a string containing the key of
760 * the previous child, by sort order, or `null` if it is the first child.
761 * @param cancelCallback - An optional callback that will be notified if your
762 * event subscription is ever canceled because your client does not have
763 * permission to read this data (or it had permission but has now lost it).
764 * This callback will be passed an `Error` object indicating why the failure
765 * occurred.
766 * @param options - An object that can be used to configure `onlyOnce`, which
767 * then removes the listener after its first invocation.
768 * @returns A function that can be invoked to remove the listener.
769 */
770export declare function onChildRemoved(query: Query, callback: (snapshot: DataSnapshot) => unknown, cancelCallback: (error: Error) => unknown, options: ListenOptions): Unsubscribe;
771/**
772 * The `onDisconnect` class allows you to write or clear data when your client
773 * disconnects from the Database server. These updates occur whether your
774 * client disconnects cleanly or not, so you can rely on them to clean up data
775 * even if a connection is dropped or a client crashes.
776 *
777 * The `onDisconnect` class is most commonly used to manage presence in
778 * applications where it is useful to detect how many clients are connected and
779 * when other clients disconnect. See
780 * {@link https://firebase.google.com/docs/database/web/offline-capabilities | Enabling Offline Capabilities in JavaScript}
781 * for more information.
782 *
783 * To avoid problems when a connection is dropped before the requests can be
784 * transferred to the Database server, these functions should be called before
785 * writing any data.
786 *
787 * Note that `onDisconnect` operations are only triggered once. If you want an
788 * operation to occur each time a disconnect occurs, you'll need to re-establish
789 * the `onDisconnect` operations each time you reconnect.
790 */
791export declare class OnDisconnect {
792 private constructor();
793 /**
794 * Cancels all previously queued `onDisconnect()` set or update events for this
795 * location and all children.
796 *
797 * If a write has been queued for this location via a `set()` or `update()` at a
798 * parent location, the write at this location will be canceled, though writes
799 * to sibling locations will still occur.
800 *
801 * @returns Resolves when synchronization to the server is complete.
802 */
803 cancel(): Promise<void>;
804 /**
805 * Ensures the data at this location is deleted when the client is disconnected
806 * (due to closing the browser, navigating to a new page, or network issues).
807 *
808 * @returns Resolves when synchronization to the server is complete.
809 */
810 remove(): Promise<void>;
811 /**
812 * Ensures the data at this location is set to the specified value when the
813 * client is disconnected (due to closing the browser, navigating to a new page,
814 * or network issues).
815 *
816 * `set()` is especially useful for implementing "presence" systems, where a
817 * value should be changed or cleared when a user disconnects so that they
818 * appear "offline" to other users. See
819 * {@link https://firebase.google.com/docs/database/web/offline-capabilities | Enabling Offline Capabilities in JavaScript}
820 * for more information.
821 *
822 * Note that `onDisconnect` operations are only triggered once. If you want an
823 * operation to occur each time a disconnect occurs, you'll need to re-establish
824 * the `onDisconnect` operations each time.
825 *
826 * @param value - The value to be written to this location on disconnect (can
827 * be an object, array, string, number, boolean, or null).
828 * @returns Resolves when synchronization to the Database is complete.
829 */
830 set(value: unknown): Promise<void>;
831 /**
832 * Ensures the data at this location is set to the specified value and priority
833 * when the client is disconnected (due to closing the browser, navigating to a
834 * new page, or network issues).
835 *
836 * @param value - The value to be written to this location on disconnect (can
837 * be an object, array, string, number, boolean, or null).
838 * @param priority - The priority to be written (string, number, or null).
839 * @returns Resolves when synchronization to the Database is complete.
840 */
841 setWithPriority(value: unknown, priority: number | string | null): Promise<void>;
842 /**
843 * Writes multiple values at this location when the client is disconnected (due
844 * to closing the browser, navigating to a new page, or network issues).
845 *
846 * The `values` argument contains multiple property-value pairs that will be
847 * written to the Database together. Each child property can either be a simple
848 * property (for example, "name") or a relative path (for example, "name/first")
849 * from the current location to the data to update.
850 *
851 * As opposed to the `set()` method, `update()` can be use to selectively update
852 * only the referenced properties at the current location (instead of replacing
853 * all the child properties at the current location).
854 *
855 * @param values - Object containing multiple values.
856 * @returns Resolves when synchronization to the Database is complete.
857 */
858 update(values: object): Promise<void>;
859}
860/**
861 * Returns an `OnDisconnect` object - see
862 * {@link https://firebase.google.com/docs/database/web/offline-capabilities | Enabling Offline Capabilities in JavaScript}
863 * for more information on how to use it.
864 *
865 * @param ref - The reference to add OnDisconnect triggers for.
866 */
867export declare function onDisconnect(ref: DatabaseReference): OnDisconnect;
868/**
869 * Listens for data changes at a particular location.
870 *
871 * This is the primary way to read data from a Database. Your callback
872 * will be triggered for the initial data and again whenever the data changes.
873 * Invoke the returned unsubscribe callback to stop receiving updates. See
874 * {@link https://firebase.google.com/docs/database/web/retrieve-data | Retrieve Data on the Web}
875 * for more details.
876 *
877 * An `onValue` event will trigger once with the initial data stored at this
878 * location, and then trigger again each time the data changes. The
879 * `DataSnapshot` passed to the callback will be for the location at which
880 * `on()` was called. It won't trigger until the entire contents has been
881 * synchronized. If the location has no data, it will be triggered with an empty
882 * `DataSnapshot` (`val()` will return `null`).
883 *
884 * @param query - The query to run.
885 * @param callback - A callback that fires when the specified event occurs. The
886 * callback will be passed a DataSnapshot.
887 * @param cancelCallback - An optional callback that will be notified if your
888 * event subscription is ever canceled because your client does not have
889 * permission to read this data (or it had permission but has now lost it).
890 * This callback will be passed an `Error` object indicating why the failure
891 * occurred.
892 * @returns A function that can be invoked to remove the listener.
893 */
894export declare function onValue(query: Query, callback: (snapshot: DataSnapshot) => unknown, cancelCallback?: (error: Error) => unknown): Unsubscribe;
895/**
896 * Listens for data changes at a particular location.
897 *
898 * This is the primary way to read data from a Database. Your callback
899 * will be triggered for the initial data and again whenever the data changes.
900 * Invoke the returned unsubscribe callback to stop receiving updates. See
901 * {@link https://firebase.google.com/docs/database/web/retrieve-data | Retrieve Data on the Web}
902 * for more details.
903 *
904 * An `onValue` event will trigger once with the initial data stored at this
905 * location, and then trigger again each time the data changes. The
906 * `DataSnapshot` passed to the callback will be for the location at which
907 * `on()` was called. It won't trigger until the entire contents has been
908 * synchronized. If the location has no data, it will be triggered with an empty
909 * `DataSnapshot` (`val()` will return `null`).
910 *
911 * @param query - The query to run.
912 * @param callback - A callback that fires when the specified event occurs. The
913 * callback will be passed a DataSnapshot.
914 * @param options - An object that can be used to configure `onlyOnce`, which
915 * then removes the listener after its first invocation.
916 * @returns A function that can be invoked to remove the listener.
917 */
918export declare function onValue(query: Query, callback: (snapshot: DataSnapshot) => unknown, options: ListenOptions): Unsubscribe;
919/**
920 * Listens for data changes at a particular location.
921 *
922 * This is the primary way to read data from a Database. Your callback
923 * will be triggered for the initial data and again whenever the data changes.
924 * Invoke the returned unsubscribe callback to stop receiving updates. See
925 * {@link https://firebase.google.com/docs/database/web/retrieve-data | Retrieve Data on the Web}
926 * for more details.
927 *
928 * An `onValue` event will trigger once with the initial data stored at this
929 * location, and then trigger again each time the data changes. The
930 * `DataSnapshot` passed to the callback will be for the location at which
931 * `on()` was called. It won't trigger until the entire contents has been
932 * synchronized. If the location has no data, it will be triggered with an empty
933 * `DataSnapshot` (`val()` will return `null`).
934 *
935 * @param query - The query to run.
936 * @param callback - A callback that fires when the specified event occurs. The
937 * callback will be passed a DataSnapshot.
938 * @param cancelCallback - An optional callback that will be notified if your
939 * event subscription is ever canceled because your client does not have
940 * permission to read this data (or it had permission but has now lost it).
941 * This callback will be passed an `Error` object indicating why the failure
942 * occurred.
943 * @param options - An object that can be used to configure `onlyOnce`, which
944 * then removes the listener after its first invocation.
945 * @returns A function that can be invoked to remove the listener.
946 */
947export declare function onValue(query: Query, callback: (snapshot: DataSnapshot) => unknown, cancelCallback: (error: Error) => unknown, options: ListenOptions): Unsubscribe;
948/**
949 * Creates a new `QueryConstraint` that orders by the specified child key.
950 *
951 * Queries can only order by one key at a time. Calling `orderByChild()`
952 * multiple times on the same query is an error.
953 *
954 * Firebase queries allow you to order your data by any child key on the fly.
955 * However, if you know in advance what your indexes will be, you can define
956 * them via the .indexOn rule in your Security Rules for better performance. See
957 * the{@link https://firebase.google.com/docs/database/security/indexing-data}
958 * rule for more information.
959 *
960 * You can read more about `orderByChild()` in
961 * {@link https://firebase.google.com/docs/database/web/lists-of-data#sort_data | Sort data}.
962 *
963 * @param path - The path to order by.
964 */
965export declare function orderByChild(path: string): QueryConstraint;
966/**
967 * Creates a new `QueryConstraint` that orders by the key.
968 *
969 * Sorts the results of a query by their (ascending) key values.
970 *
971 * You can read more about `orderByKey()` in
972 * {@link https://firebase.google.com/docs/database/web/lists-of-data#sort_data | Sort data}.
973 */
974export declare function orderByKey(): QueryConstraint;
975/**
976 * Creates a new `QueryConstraint` that orders by priority.
977 *
978 * Applications need not use priority but can order collections by
979 * ordinary properties (see
980 * {@link https://firebase.google.com/docs/database/web/lists-of-data#sort_data | Sort data}
981 * for alternatives to priority.
982 */
983export declare function orderByPriority(): QueryConstraint;
984/**
985 * Creates a new `QueryConstraint` that orders by value.
986 *
987 * If the children of a query are all scalar values (string, number, or
988 * boolean), you can order the results by their (ascending) values.
989 *
990 * You can read more about `orderByValue()` in
991 * {@link https://firebase.google.com/docs/database/web/lists-of-data#sort_data | Sort data}.
992 */
993export declare function orderByValue(): QueryConstraint;
994/**
995 * Generates a new child location using a unique key and returns its
996 * `Reference`.
997 *
998 * This is the most common pattern for adding data to a collection of items.
999 *
1000 * If you provide a value to `push()`, the value is written to the
1001 * generated location. If you don't pass a value, nothing is written to the
1002 * database and the child remains empty (but you can use the `Reference`
1003 * elsewhere).
1004 *
1005 * The unique keys generated by `push()` are ordered by the current time, so the
1006 * resulting list of items is chronologically sorted. The keys are also
1007 * designed to be unguessable (they contain 72 random bits of entropy).
1008 *
1009 * See {@link https://firebase.google.com/docs/database/web/lists-of-data#append_to_a_list_of_data | Append to a list of data}
1010 * </br>See {@link ttps://firebase.googleblog.com/2015/02/the-2120-ways-to-ensure-unique_68.html | The 2^120 Ways to Ensure Unique Identifiers}
1011 *
1012 * @param parent - The parent location.
1013 * @param value - Optional value to be written at the generated location.
1014 * @returns Combined `Promise` and `Reference`; resolves when write is complete,
1015 * but can be used immediately as the `Reference` to the child location.
1016 */
1017export declare function push(parent: DatabaseReference, value?: unknown): ThenableReference;
1018/**
1019 * @license
1020 * Copyright 2021 Google LLC
1021 *
1022 * Licensed under the Apache License, Version 2.0 (the "License");
1023 * you may not use this file except in compliance with the License.
1024 * You may obtain a copy of the License at
1025 *
1026 * http://www.apache.org/licenses/LICENSE-2.0
1027 *
1028 * Unless required by applicable law or agreed to in writing, software
1029 * distributed under the License is distributed on an "AS IS" BASIS,
1030 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
1031 * See the License for the specific language governing permissions and
1032 * limitations under the License.
1033 */
1034/**
1035 * A `Query` sorts and filters the data at a Database location so only a subset
1036 * of the child data is included. This can be used to order a collection of
1037 * data by some attribute (for example, height of dinosaurs) as well as to
1038 * restrict a large list of items (for example, chat messages) down to a number
1039 * suitable for synchronizing to the client. Queries are created by chaining
1040 * together one or more of the filter methods defined here.
1041 *
1042 * Just as with a `DatabaseReference`, you can receive data from a `Query` by using the
1043 * `on*()` methods. You will only receive events and `DataSnapshot`s for the
1044 * subset of the data that matches your query.
1045 *
1046 * See {@link https://firebase.google.com/docs/database/web/lists-of-data#sorting_and_filtering_data}
1047 * for more information.
1048 */
1049export declare interface Query {
1050 /** The `DatabaseReference` for the `Query`'s location. */
1051 readonly ref: DatabaseReference;
1052 /**
1053 * Returns whether or not the current and provided queries represent the same
1054 * location, have the same query parameters, and are from the same instance of
1055 * `FirebaseApp`.
1056 *
1057 * Two `DatabaseReference` objects are equivalent if they represent the same location
1058 * and are from the same instance of `FirebaseApp`.
1059 *
1060 * Two `Query` objects are equivalent if they represent the same location,
1061 * have the same query parameters, and are from the same instance of
1062 * `FirebaseApp`. Equivalent queries share the same sort order, limits, and
1063 * starting and ending points.
1064 *
1065 * @param other - The query to compare against.
1066 * @returns Whether or not the current and provided queries are equivalent.
1067 */
1068 isEqual(other: Query | null): boolean;
1069 /**
1070 * Returns a JSON-serializable representation of this object.
1071 *
1072 * @returns A JSON-serializable representation of this object.
1073 */
1074 toJSON(): string;
1075 /**
1076 * Gets the absolute URL for this location.
1077 *
1078 * The `toString()` method returns a URL that is ready to be put into a
1079 * browser, curl command, or a `refFromURL()` call. Since all of those expect
1080 * the URL to be url-encoded, `toString()` returns an encoded URL.
1081 *
1082 * Append '.json' to the returned URL when typed into a browser to download
1083 * JSON-formatted data. If the location is secured (that is, not publicly
1084 * readable), you will get a permission-denied error.
1085 *
1086 * @returns The absolute URL for this location.
1087 */
1088 toString(): string;
1089}
1090/**
1091 * Creates a new immutable instance of `Query` that is extended to also include
1092 * additional query constraints.
1093 *
1094 * @param query - The Query instance to use as a base for the new constraints.
1095 * @param queryConstraints - The list of `QueryConstraint`s to apply.
1096 * @throws if any of the provided query constraints cannot be combined with the
1097 * existing or new constraints.
1098 */
1099export declare function query(query: Query, ...queryConstraints: QueryConstraint[]): Query;
1100/**
1101 * A `QueryConstraint` is used to narrow the set of documents returned by a
1102 * Database query. `QueryConstraint`s are created by invoking {@link endAt},
1103 * {@link endBefore}, {@link startAt}, {@link startAfter}, {@link
1104 * limitToFirst}, {@link limitToLast}, {@link orderByChild},
1105 * {@link orderByChild}, {@link orderByKey} , {@link orderByPriority} ,
1106 * {@link orderByValue} or {@link equalTo} and
1107 * can then be passed to {@link query} to create a new query instance that
1108 * also contains this `QueryConstraint`.
1109 */
1110export declare abstract class QueryConstraint {
1111 /** The type of this query constraints */
1112 abstract readonly type: QueryConstraintType;
1113}
1114/** Describes the different query constraints available in this SDK. */
1115export declare type QueryConstraintType = 'endAt' | 'endBefore' | 'startAt' | 'startAfter' | 'limitToFirst' | 'limitToLast' | 'orderByChild' | 'orderByKey' | 'orderByPriority' | 'orderByValue' | 'equalTo';
1116/* Excluded from this release type: _QueryImpl */
1117/* Excluded from this release type: _QueryParams */
1118/**
1119 *
1120 * Returns a `Reference` representing the location in the Database
1121 * corresponding to the provided path. If no path is provided, the `Reference`
1122 * will point to the root of the Database.
1123 *
1124 * @param db - The database instance to obtain a reference for.
1125 * @param path - Optional path representing the location the returned
1126 * `Reference` will point. If not provided, the returned `Reference` will
1127 * point to the root of the Database.
1128 * @returns If a path is provided, a `Reference`
1129 * pointing to the provided path. Otherwise, a `Reference` pointing to the
1130 * root of the Database.
1131 */
1132export declare function ref(db: Database, path?: string): DatabaseReference;
1133/* Excluded from this release type: _ReferenceImpl */
1134/**
1135 * Returns a `Reference` representing the location in the Database
1136 * corresponding to the provided Firebase URL.
1137 *
1138 * An exception is thrown if the URL is not a valid Firebase Database URL or it
1139 * has a different domain than the current `Database` instance.
1140 *
1141 * Note that all query parameters (`orderBy`, `limitToLast`, etc.) are ignored
1142 * and are not applied to the returned `Reference`.
1143 *
1144 * @param db - The database instance to obtain a reference for.
1145 * @param url - The Firebase URL at which the returned `Reference` will
1146 * point.
1147 * @returns A `Reference` pointing to the provided
1148 * Firebase URL.
1149 */
1150export declare function refFromURL(db: Database, url: string): DatabaseReference;
1151/**
1152 * Removes the data at this Database location.
1153 *
1154 * Any data at child locations will also be deleted.
1155 *
1156 * The effect of the remove will be visible immediately and the corresponding
1157 * event 'value' will be triggered. Synchronization of the remove to the
1158 * Firebase servers will also be started, and the returned Promise will resolve
1159 * when complete. If provided, the onComplete callback will be called
1160 * asynchronously after synchronization has finished.
1161 *
1162 * @param ref - The location to remove.
1163 * @returns Resolves when remove on server is complete.
1164 */
1165export declare function remove(ref: DatabaseReference): Promise<void>;
1166/* Excluded from this release type: _repoManagerDatabaseFromApp */
1167/**
1168 * Atomically modifies the data at this location.
1169 *
1170 * Atomically modify the data at this location. Unlike a normal `set()`, which
1171 * just overwrites the data regardless of its previous value, `runTransaction()` is
1172 * used to modify the existing value to a new value, ensuring there are no
1173 * conflicts with other clients writing to the same location at the same time.
1174 *
1175 * To accomplish this, you pass `runTransaction()` an update function which is
1176 * used to transform the current value into a new value. If another client
1177 * writes to the location before your new value is successfully written, your
1178 * update function will be called again with the new current value, and the
1179 * write will be retried. This will happen repeatedly until your write succeeds
1180 * without conflict or you abort the transaction by not returning a value from
1181 * your update function.
1182 *
1183 * Note: Modifying data with `set()` will cancel any pending transactions at
1184 * that location, so extreme care should be taken if mixing `set()` and
1185 * `runTransaction()` to update the same data.
1186 *
1187 * Note: When using transactions with Security and Firebase Rules in place, be
1188 * aware that a client needs `.read` access in addition to `.write` access in
1189 * order to perform a transaction. This is because the client-side nature of
1190 * transactions requires the client to read the data in order to transactionally
1191 * update it.
1192 *
1193 * @param ref - The location to atomically modify.
1194 * @param transactionUpdate - A developer-supplied function which will be passed
1195 * the current data stored at this location (as a JavaScript object). The
1196 * function should return the new value it would like written (as a JavaScript
1197 * object). If `undefined` is returned (i.e. you return with no arguments) the
1198 * transaction will be aborted and the data at this location will not be
1199 * modified.
1200 * @param options - An options object to configure transactions.
1201 * @returns A `Promise` that can optionally be used instead of the `onComplete`
1202 * callback to handle success and failure.
1203 */
1204export declare function runTransaction(ref: DatabaseReference, transactionUpdate: (currentData: any) => unknown, options?: TransactionOptions): Promise<TransactionResult>;
1205/**
1206 * @license
1207 * Copyright 2020 Google LLC
1208 *
1209 * Licensed under the Apache License, Version 2.0 (the "License");
1210 * you may not use this file except in compliance with the License.
1211 * You may obtain a copy of the License at
1212 *
1213 * http://www.apache.org/licenses/LICENSE-2.0
1214 *
1215 * Unless required by applicable law or agreed to in writing, software
1216 * distributed under the License is distributed on an "AS IS" BASIS,
1217 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
1218 * See the License for the specific language governing permissions and
1219 * limitations under the License.
1220 */
1221/**
1222 * Returns a placeholder value for auto-populating the current timestamp (time
1223 * since the Unix epoch, in milliseconds) as determined by the Firebase
1224 * servers.
1225 */
1226export declare function serverTimestamp(): object;
1227/**
1228 * Writes data to this Database location.
1229 *
1230 * This will overwrite any data at this location and all child locations.
1231 *
1232 * The effect of the write will be visible immediately, and the corresponding
1233 * events ("value", "child_added", etc.) will be triggered. Synchronization of
1234 * the data to the Firebase servers will also be started, and the returned
1235 * Promise will resolve when complete. If provided, the `onComplete` callback
1236 * will be called asynchronously after synchronization has finished.
1237 *
1238 * Passing `null` for the new value is equivalent to calling `remove()`; namely,
1239 * all data at this location and all child locations will be deleted.
1240 *
1241 * `set()` will remove any priority stored at this location, so if priority is
1242 * meant to be preserved, you need to use `setWithPriority()` instead.
1243 *
1244 * Note that modifying data with `set()` will cancel any pending transactions
1245 * at that location, so extreme care should be taken if mixing `set()` and
1246 * `transaction()` to modify the same data.
1247 *
1248 * A single `set()` will generate a single "value" event at the location where
1249 * the `set()` was performed.
1250 *
1251 * @param ref - The location to write to.
1252 * @param value - The value to be written (string, number, boolean, object,
1253 * array, or null).
1254 * @returns Resolves when write to server is complete.
1255 */
1256export declare function set(ref: DatabaseReference, value: unknown): Promise<void>;
1257/**
1258 * Sets a priority for the data at this Database location.
1259 *
1260 * Applications need not use priority but can order collections by
1261 * ordinary properties (see
1262 * {@link https://firebase.google.com/docs/database/web/lists-of-data#sorting_and_filtering_data | Sorting and filtering data}
1263 * ).
1264 *
1265 * @param ref - The location to write to.
1266 * @param priority - The priority to be written (string, number, or null).
1267 * @returns Resolves when write to server is complete.
1268 */
1269export declare function setPriority(ref: DatabaseReference, priority: string | number | null): Promise<void>;
1270/* Excluded from this release type: _setSDKVersion */
1271/**
1272 * Writes data the Database location. Like `set()` but also specifies the
1273 * priority for that data.
1274 *
1275 * Applications need not use priority but can order collections by
1276 * ordinary properties (see
1277 * {@link https://firebase.google.com/docs/database/web/lists-of-data#sorting_and_filtering_data | Sorting and filtering data}
1278 * ).
1279 *
1280 * @param ref - The location to write to.
1281 * @param value - The value to be written (string, number, boolean, object,
1282 * array, or null).
1283 * @param priority - The priority to be written (string, number, or null).
1284 * @returns Resolves when write to server is complete.
1285 */
1286export declare function setWithPriority(ref: DatabaseReference, value: unknown, priority: string | number | null): Promise<void>;
1287/**
1288 * Creates a `QueryConstraint` with the specified starting point (exclusive).
1289 *
1290 * Using `startAt()`, `startAfter()`, `endBefore()`, `endAt()` and `equalTo()`
1291 * allows you to choose arbitrary starting and ending points for your queries.
1292 *
1293 * The starting point is exclusive. If only a value is provided, children
1294 * with a value greater than the specified value will be included in the query.
1295 * If a key is specified, then children must have a value greater than or equal
1296 * to the specified value and a a key name greater than the specified key.
1297 *
1298 * @param value - The value to start after. The argument type depends on which
1299 * `orderBy*()` function was used in this query. Specify a value that matches
1300 * the `orderBy*()` type. When used in combination with `orderByKey()`, the
1301 * value must be a string.
1302 * @param key - The child key to start after. This argument is only allowed if
1303 * ordering by child, value, or priority.
1304 */
1305export declare function startAfter(value: number | string | boolean | null, key?: string): QueryConstraint;
1306/**
1307 * Creates a `QueryConstraint` with the specified starting point.
1308 *
1309 * Using `startAt()`, `startAfter()`, `endBefore()`, `endAt()` and `equalTo()`
1310 * allows you to choose arbitrary starting and ending points for your queries.
1311 *
1312 * The starting point is inclusive, so children with exactly the specified value
1313 * will be included in the query. The optional key argument can be used to
1314 * further limit the range of the query. If it is specified, then children that
1315 * have exactly the specified value must also have a key name greater than or
1316 * equal to the specified key.
1317 *
1318 * You can read more about `startAt()` in
1319 * {@link https://firebase.google.com/docs/database/web/lists-of-data#filtering_data | Filtering data}.
1320 *
1321 * @param value - The value to start at. The argument type depends on which
1322 * `orderBy*()` function was used in this query. Specify a value that matches
1323 * the `orderBy*()` type. When used in combination with `orderByKey()`, the
1324 * value must be a string.
1325 * @param key - The child key to start at. This argument is only allowed if
1326 * ordering by child, value, or priority.
1327 */
1328export declare function startAt(value?: number | string | boolean | null, key?: string): QueryConstraint;
1329/* Excluded from this release type: _TEST_ACCESS_forceRestClient */
1330/* Excluded from this release type: _TEST_ACCESS_hijackHash */
1331/**
1332 * A `Promise` that can also act as a `DatabaseReference` when returned by
1333 * {@link push}. The reference is available immediately and the `Promise` resolves
1334 * as the write to the backend completes.
1335 */
1336export declare interface ThenableReference extends DatabaseReference, Pick<Promise<DatabaseReference>, 'then' | 'catch'> {
1337}
1338/** An options object to configure transactions. */
1339export declare interface TransactionOptions {
1340 /**
1341 * By default, events are raised each time the transaction update function
1342 * runs. So if it is run multiple times, you may see intermediate states. You
1343 * can set this to false to suppress these intermediate states and instead
1344 * wait until the transaction has completed before events are raised.
1345 */
1346 readonly applyLocally?: boolean;
1347}
1348/**
1349 * A type for the resolve value of {@link runTransaction}.
1350 */
1351export declare class TransactionResult {
1352 /** Whether the transaction was successfully committed. */
1353 readonly committed: boolean;
1354 /** The resulting data snapshot. */
1355 readonly snapshot: DataSnapshot;
1356 private constructor();
1357 /** Returns a JSON-serializable representation of this object. */
1358 toJSON(): object;
1359}
1360/** A callback that can invoked to remove a listener. */
1361export declare type Unsubscribe = () => void;
1362/**
1363 * Writes multiple values to the Database at once.
1364 *
1365 * The `values` argument contains multiple property-value pairs that will be
1366 * written to the Database together. Each child property can either be a simple
1367 * property (for example, "name") or a relative path (for example,
1368 * "name/first") from the current location to the data to update.
1369 *
1370 * As opposed to the `set()` method, `update()` can be use to selectively update
1371 * only the referenced properties at the current location (instead of replacing
1372 * all the child properties at the current location).
1373 *
1374 * The effect of the write will be visible immediately, and the corresponding
1375 * events ('value', 'child_added', etc.) will be triggered. Synchronization of
1376 * the data to the Firebase servers will also be started, and the returned
1377 * Promise will resolve when complete. If provided, the `onComplete` callback
1378 * will be called asynchronously after synchronization has finished.
1379 *
1380 * A single `update()` will generate a single "value" event at the location
1381 * where the `update()` was performed, regardless of how many children were
1382 * modified.
1383 *
1384 * Note that modifying data with `update()` will cancel any pending
1385 * transactions at that location, so extreme care should be taken if mixing
1386 * `update()` and `transaction()` to modify the same data.
1387 *
1388 * Passing `null` to `update()` will remove the data at this location.
1389 *
1390 * See
1391 * {@link https://firebase.googleblog.com/2015/09/introducing-multi-location-updates-and_86.html | Introducing multi-location updates and more}.
1392 *
1393 * @param ref - The location to write to.
1394 * @param values - Object containing multiple values.
1395 * @returns Resolves when update on server is complete.
1396 */
1397export declare function update(ref: DatabaseReference, values: object): Promise<void>;
1398export {};