From e637c5f51a88079a4775486514c4475b930eebfc Mon Sep 17 00:00:00 2001 From: Sebastian Schmidt Date: Tue, 6 Apr 2021 12:32:25 -0600 Subject: [PATCH 1/2] Add database@exp API docs --- packages/database/src/core/view/Event.ts | 4 + packages/database/src/exp/Database.ts | 65 +- packages/database/src/exp/OnDisconnect.ts | 81 ++ packages/database/src/exp/Reference.ts | 91 ++ packages/database/src/exp/Reference_impl.ts | 1002 ++++++++++++++++++- packages/database/src/exp/ServerValue.ts | 12 + packages/database/src/exp/Transaction.ts | 44 + 7 files changed, 1247 insertions(+), 52 deletions(-) diff --git a/packages/database/src/core/view/Event.ts b/packages/database/src/core/view/Event.ts index 307510b27e6..ef18a9045a0 100644 --- a/packages/database/src/core/view/Event.ts +++ b/packages/database/src/core/view/Event.ts @@ -36,6 +36,10 @@ export interface Event { toString(): string; } +/** + * One of the following strings: "value", "child_added", "child_changed", + * "child_removed", or "child_moved." + */ export type EventType = | 'value' | 'child_added' diff --git a/packages/database/src/exp/Database.ts b/packages/database/src/exp/Database.ts index db01fe5bbb3..78aa81fae2e 100644 --- a/packages/database/src/exp/Database.ts +++ b/packages/database/src/exp/Database.ts @@ -262,6 +262,16 @@ export function getDatabase(app: FirebaseApp, url?: string): FirebaseDatabase { }) as FirebaseDatabase; } +/** + * Modify the provided instance to communicate with the Realtime Database + * emulator. + * + *

Note: This method must be called before performing any other operation. + * + * @param db - The instance to modify. + * @param host - The emulator host (ex: localhost) + * @param port - The emulator port (ex: 8080) + */ export function useDatabaseEmulator( db: FirebaseDatabase, host: string, @@ -278,20 +288,73 @@ export function useDatabaseEmulator( repoManagerApplyEmulatorSettings(db._repo, host, port); } +/** + * Disconnects from the server (all Database operations will be completed + * offline). + * + * The client automatically maintains a persistent connection to the Database + * server, which will remain active indefinitely and reconnect when + * disconnected. However, the `goOffline()` and `goOnline()` methods may be used + * to control the client connection in cases where a persistent connection is + * undesirable. + * + * While offline, the client will no longer receive data updates from the + * Database. However, all Database operations performed locally will continue to + * immediately fire events, allowing your application to continue behaving + * normally. Additionally, each operation performed locally will automatically + * be queued and retried upon reconnection to the Database server. + * + * To reconnect to the Database and begin receiving remote events, see + * `goOnline()`. + * + * @param db - The instance to disconnect. + */ export function goOffline(db: FirebaseDatabase): void { db = getModularInstance(db); db._checkNotDeleted('goOffline'); repoInterrupt(db._repo); } +/** + * Reconnects to the server and synchronizes the offline Database state + * with the server state. + * + * This method should be used after disabling the active connection with + * `goOffline()`. Once reconnected, the client will transmit the proper data + * and fire the appropriate events so that your client "catches up" + * automatically. + * + * @param db - The instance to reconnect. + */ export function goOnline(db: FirebaseDatabase): void { db = getModularInstance(db); db._checkNotDeleted('goOnline'); repoResume(db._repo); } +/** + * Logs debugging information to the console. + * + * @param enabled Enables logging if `true`, disables logging if `false`. + * @param persistent Remembers the logging state between page refreshes if + * `true`. + */ +export function enableLogging(enabled: boolean, persistent?: boolean); + +/** + * Logs debugging information to the console. + * + * @param logger A custom logger function to control how things get logged. + * @param persistent Remembers the logging state between page refreshes if + * `true`. + */ +export function enableLogging( + logger?: (message: string) => unknown, + persistent?: boolean +); + export function enableLogging( - logger?: boolean | ((message: string) => unknown), + logger: boolean | ((message: string) => unknown), persistent?: boolean ): void { enableLoggingImpl(logger, persistent); diff --git a/packages/database/src/exp/OnDisconnect.ts b/packages/database/src/exp/OnDisconnect.ts index efb57f9eda9..7312cde802a 100644 --- a/packages/database/src/exp/OnDisconnect.ts +++ b/packages/database/src/exp/OnDisconnect.ts @@ -33,9 +33,39 @@ import { validateWritablePath } from '../core/util/validation'; +/** + * The `onDisconnect` class allows you to write or clear data when your client + * disconnects from the Database server. These updates occur whether your + * client disconnects cleanly or not, so you can rely on them to clean up data + * even if a connection is dropped or a client crashes. + * + * The `onDisconnect` class is most commonly used to manage presence in + * applications where it is useful to detect how many clients are connected and + * when other clients disconnect. See {@link + * https://firebase.google.com/docs/database/web/offline-capabilities Enabling + * Offline Capabilities in JavaScript} for more information. + * + * To avoid problems when a connection is dropped before the requests can be + * transferred to the Database server, these functions should be called before + * writing any data. + * + * Note that `onDisconnect` operations are only triggered once. If you want an + * operation to occur each time a disconnect occurs, you'll need to re-establish + * the `onDisconnect` operations each time you reconnect. + */ export class OnDisconnect { constructor(private _repo: Repo, private _path: Path) {} + /** + * Cancels all previously queued `onDisconnect()` set or update events for this + * location and all children. + * + * If a write has been queued for this location via a `set()` or `update()` at a + * parent location, the write at this location will be canceled, though writes + * to sibling locations will still occur. + * + * @return Resolves when synchronization to the server is complete. + */ cancel(): Promise { const deferred = new Deferred(); repoOnDisconnectCancel( @@ -46,6 +76,12 @@ export class OnDisconnect { return deferred.promise; } + /** + * Ensures the data at this location is deleted when the client is disconnected + * (due to closing the browser, navigating to a new page, or network issues). + * + * @return Resolves when synchronization to the server is complete. + */ remove(): Promise { validateWritablePath('OnDisconnect.remove', this._path); const deferred = new Deferred(); @@ -58,6 +94,25 @@ export class OnDisconnect { return deferred.promise; } + /** + * Ensures the data at this location is set to the specified value when the + * client is disconnected (due to closing the browser, navigating to a new page, + * or network issues). + * + * `set()` is especially useful for implementing "presence" systems, where a + * value should be changed or cleared when a user disconnects so that they + * appear "offline" to other users. See {@link + * https://firebase.google.com/docs/database/web/offline-capabilities Enabling + * Offline Capabilities in JavaScript} for more information. + * + * Note that `onDisconnect` operations are only triggered once. If you want an + * operation to occur each time a disconnect occurs, you'll need to re-establish + * the `onDisconnect` operations each time. + * + * @param value - The value to be written to this location on disconnect (can + * be an object, array, string, number, boolean, or null). + * @return Resolves when synchronization to the Database is complete. + */ set(value: unknown): Promise { validateWritablePath('OnDisconnect.set', this._path); validateFirebaseDataArg('OnDisconnect.set', value, this._path, false); @@ -71,6 +126,16 @@ export class OnDisconnect { return deferred.promise; } + /** + * Ensures the data at this location is set to the specified value and priority + * when the client is disconnected (due to closing the browser, navigating to a + * new page, or network issues). + * + * @param value - The value to be written to this location on disconnect (can + * be an object, array, string, number, boolean, or null). + * @param priority - The priority to be written (string, number, or null). + * @return Resolves when synchronization to the Database is complete. + */ setWithPriority( value: unknown, priority: number | string | null @@ -95,6 +160,22 @@ export class OnDisconnect { return deferred.promise; } + /** + * Writes multiple values at this location when the client is disconnected (due + * to closing the browser, navigating to a new page, or network issues). + * + * The `values` argument contains multiple property-value pairs that will be + * written to the Database together. Each child property can either be a simple + * property (for example, "name") or a relative path (for example, "name/first") + * from the current location to the data to update. + * + * As opposed to the `set()` method, `update()` can be use to selectively update + * only the referenced properties at the current location (instead of replacing + * all the child properties at the current location). + * + * @param values Object containing multiple values. + * @return Resolves when synchronization to the Database is complete. + */ update(values: Indexable): Promise { validateWritablePath('OnDisconnect.update', this._path); validateFirebaseMergeDataArg( diff --git a/packages/database/src/exp/Reference.ts b/packages/database/src/exp/Reference.ts index 0335d5ff2c2..4c95bc3a4df 100644 --- a/packages/database/src/exp/Reference.ts +++ b/packages/database/src/exp/Reference.ts @@ -19,25 +19,116 @@ import { QueryContext } from '../core/view/EventRegistration'; * limitations under the License. */ +/** + * A `Query` sorts and filters the data at a Database location so only a subset + * of the child data is included. This can be used to order a collection of + * data by some attribute (for example, height of dinosaurs) as well as to + * restrict a large list of items (for example, chat messages) down to a number + * suitable for synchronizing to the client. Queries are created by chaining + * together one or more of the filter methods defined here. + * + * Just as with a `Reference`, you can receive data from a `Query` by using the + * `on*()` methods. You will only receive events and `DataSnapshot`s for the + * subset of the data that matches your query. + * + * Read our documentation on {@link + * https://firebase.google.com/docs/database/web/lists-of-data#sorting_and_filtering_data + * Sorting and filtering data} for more information. + */ export interface Query extends QueryContext { + /** The `Reference` for the `Query`'s location. */ readonly ref: Reference; + + /** + * Returns whether or not the current and provided queries represent the same + * location, have the same query parameters, and are from the same instance of + * `FirebaseApp`. + * + * Two `Reference` objects are equivalent if they represent the same location + * and are from the same instance of `FirebaseApp`. + * + * Two `Query` objects are equivalent if they represent the same location, + * have the same query parameters, and are from the same instance of + * `FirebaseApp`. Equivalent queries share the same sort order, limits, and + * starting and ending points. + * + * @param other - The query to compare against. + * @return Whether or not the current and provided queries are equivalent. + */ isEqual(other: Query | null): boolean; + + /** + * Returns a JSON-serializable representation of this object. + * + * @return A JSON-serializable representation of this object. + */ toJSON(): string; + + /** + * Gets the absolute URL for this location. + * + * The `toString()` method returns a URL that is ready to be put into a + * browser, curl command, or a `refFromURL()` call. Since all of those expect + * the URL to be url-encoded, `toString()` returns an encoded URL. + * + * Append '.json' to the returned URL when typed into a browser to download + * JSON-formatted data. If the location is secured (that is, not publicly + * readable), you will get a permission-denied error. + * + * @return The absolute URL for this location. + */ toString(): string; } +/** + * A `Reference` represents a specific location in your Database and can be used + * for reading or writing data to that Database location. + * + * You can reference the root or child location in your Database by calling + * `ref()` or `ref("child/path")`. + * + * Writing is done with the `set()` method and reading can be done with the + * `on*()` method. See {@link + * https://firebase.google.com/docs/database/web/read-and-write Read and Write + * Data on the Web} + */ export interface Reference extends Query { + /** + * The last part of the `Reference`'s path. + * + * For example, `"ada"` is the key for + * `https://.firebaseio.com/users/ada`. + * + * The key of a root `Reference` is `null`. + */ readonly key: string | null; + + /** + * The parent location of a `Reference`. + * + * The parent of a root `Reference` is `null`. + */ readonly parent: Reference | null; + + /** The root `Reference` of the Database. */ + readonly root: Reference; } +/** + * A `Promise` that can also act as a `Reference` when returned by + * {@link push}. The reference is available immediately and the Promise resolves + * as the write to the backend completes. + */ export interface ThenableReference extends Reference, Pick, 'then' | 'catch'> {} +/** A callback that can invoked to remove a listener. */ export type Unsubscribe = () => void; +/** An options objects that can be used to customize a listener. */ export interface ListenOptions { + /** Whether to remove the listener after its first invocation. */ readonly onlyOnce?: boolean; } diff --git a/packages/database/src/exp/Reference_impl.ts b/packages/database/src/exp/Reference_impl.ts index 948ad2e3cc7..1b0f8f9e85b 100644 --- a/packages/database/src/exp/Reference_impl.ts +++ b/packages/database/src/exp/Reference_impl.ts @@ -265,6 +265,20 @@ export class ReferenceImpl extends QueryImpl implements Reference { } } +/** + * A `DataSnapshot` contains data from a Database location. + * + * Any time you read data from the Database, you receive the data as a + * `DataSnapshot`. A `DataSnapshot` is passed to the event callbacks you attach + * with `on()` or `once()`. You can extract the contents of the snapshot as a + * JavaScript object by calling the `val()` method. Alternatively, you can + * traverse into the snapshot by calling `child()` to return child snapshots + * (which you could then call `val()` on). + * + * A `DataSnapshot` is an efficiently generated, immutable copy of the data at + * a Database location. It cannot be modified and will never change (to modify + * data, you always call the `set()` method on a `Reference` directly). + */ export class DataSnapshot { /** * @param _node A SnapshotNode to wrap. @@ -278,19 +292,50 @@ export class DataSnapshot { readonly _index: Index ) {} + /** + * Gets the priority value of the data in this `DataSnapshot`. + * + * Applications need not use priority but can order collections by + * ordinary properties (see + * {@link + * https://firebase.google.com/docs/database/web/lists-of-data#sorting_and_filtering_data + * Sorting and filtering data}). + */ get priority(): string | number | null { // typecast here because we never return deferred values or internal priorities (MAX_PRIORITY) return this._node.getPriority().val() as string | number | null; } + /** + * The key (last part of the path) of the location of this `DataSnapshot`. + * + * The last token in a Database location is considered its key. For example, + * "ada" is the key for the /users/ada/ node. Accessing the key on any + * `DataSnapshot` will return the key for the location that generated it. + * However, accessing the key on the root URL of a Database will return + * `null`. + */ get key(): string | null { return this.ref.key; } + /** Returns the number of child properties of this `DataSnapshot`. */ get size(): number { return this._node.numChildren(); } + /** + * Gets another `DataSnapshot` for the location at the specified relative path. + * + * Passing a relative path to the `child()` method of a DataSnapshot returns + * another `DataSnapshot` for the location at the specified relative path. The + * relative path can either be a simple child name (for example, "ada") or a + * deeper, slash-separated path (for example, "ada/name/first"). If the child + * location has no data, an empty `DataSnapshot` (that is, a `DataSnapshot` + * whose value is `null`) is returned. + * + * @param path - A relative path to the location of child data. + */ child(path: string): DataSnapshot { const childPath = new Path(path); const childRef = child(this.ref, path); @@ -300,16 +345,46 @@ export class DataSnapshot { PRIORITY_INDEX ); } - + /** + * Returns true if this `DataSnapshot` contains any data. It is slightly more + * efficient than using `snapshot.val() !== null`. + */ exists(): boolean { return !this._node.isEmpty(); } + /** + * Exports the entire contents of the DataSnapshot as a JavaScript object. + * + * The `exportVal()` method is similar to `val()`, except priority information + * is included (if available), making it suitable for backing up your data. + * + * @return The DataSnapshot's contents as a JavaScript value (Object, + * Array, string, number, boolean, or `null`). + */ // eslint-disable-next-line @typescript-eslint/no-explicit-any exportVal(): any { return this._node.val(true); } + /** + * Enumerates the top-level children in the `DataSnapshot`. + * + * Because of the way JavaScript objects work, the ordering of data in the + * JavaScript object returned by `val()` is not guaranteed to match the + * ordering on the server nor the ordering of `onChildAdded()` events. That is + * where `forEach()` comes in handy. It guarantees the children of a + * `DataSnapshot` will be iterated in their query order. + * + * If no explicit `orderBy*()` method is used, results are returned + * ordered by key (unless priorities are used, in which case, results are + * returned by priority). + * + * @param action - A function that will be called for each child DataSnapshot. + * The callback can return true to cancel further enumeration. + * @return true if enumeration was canceled due to your callback returning + * true. + */ forEach(action: (child: DataSnapshot) => boolean | void): boolean { if (this._node.isLeafNode()) { return false; @@ -324,11 +399,30 @@ export class DataSnapshot { }); } + /** + * Returns true if the specified child path has (non-null) data. + * + * @param path - A relative path to the location of a potential child. + * @return `true` if data exists at the specified child path; else + * `false`. + */ hasChild(path: string): boolean { const childPath = new Path(path); return !this._node.getChild(childPath).isEmpty(); } + /** + * Returns whether or not the `DataSnapshot` has any non-`null` child + * properties. + * + * You can use `hasChildren()` to determine if a `DataSnapshot` has any + * children. If it does, you can enumerate them using `forEach()`. If it + * doesn't, then either this snapshot contains a primitive value (which can be + * retrieved with `val()`) or it is empty (in which case, `val()` will return + * `null`). + * + * @return true if this snapshot has any children; else false. + */ hasChildren(): boolean { if (this._node.isLeafNode()) { return false; @@ -337,22 +431,65 @@ export class DataSnapshot { } } + /** + * Returns a JSON-serializable representation of this object. + */ toJSON(): object | null { return this.exportVal(); } + /** + * Extracts a JavaScript value from a `DataSnapshot`. + * + * Depending on the data in a `DataSnapshot`, the `val()` method may return a + * scalar type (string, number, or boolean), an array, or an object. It may + * also return null, indicating that the `DataSnapshot` is empty (contains no + * data). + * + * @return The DataSnapshot's contents as a JavaScript value (Object, + * Array, string, number, boolean, or `null`). + */ // eslint-disable-next-line @typescript-eslint/no-explicit-any val(): any { return this._node.val(); } } - +/** + * + * Returns a `Reference` representing the location in the Database + * corresponding to the provided path. If no path is provided, the `Reference` + * will point to the root of the Database. + * + * @param db - The database instance to obtain a reference for. + * @param path - Optional path representing the location the returned + * `Reference` will point. If not provided, the returned `Reference` will + * point to the root of the Database. + * @return If a path is provided, a `Reference` + * pointing to the provided path. Otherwise, a `Reference` pointing to the + * root of the Database. + */ export function ref(db: FirebaseDatabase, path?: string): ReferenceImpl { db = getModularInstance(db); db._checkNotDeleted('ref'); return path !== undefined ? child(db._root, path) : db._root; } +/** + * Returns a `Reference` representing the location in the Database + * corresponding to the provided Firebase URL. + * + * An exception is thrown if the URL is not a valid Firebase Database URL or it + * has a different domain than the current `Database` instance. + * + * Note that all query parameters (`orderBy`, `limitToLast`, etc.) are ignored + * and are not applied to the returned `Reference`. + * + * @param db - The database instance to obtain a reference for. + * @param url - The Firebase URL at which the returned `Reference` will + * point. + * @return A `Reference` pointing to the provided + * Firebase URL. + */ export function refFromURL(db: FirebaseDatabase, url: string): ReferenceImpl { db = getModularInstance(db); db._checkNotDeleted('refFromURL'); @@ -378,16 +515,35 @@ export function refFromURL(db: FirebaseDatabase, url: string): ReferenceImpl { return ref(db, parsedURL.path.toString()); } -export function child(ref: Reference, path: string): ReferenceImpl { - ref = getModularInstance(ref); - if (pathGetFront(ref._path) === null) { +/** + * Gets a `Reference` for the location at the specified relative path. + * + * The relative path can either be a simple child name (for example, "ada") or + * a deeper slash-separated path (for example, "ada/name/first"). + * + * @param parent - The parent location. + * @param path - A relative path from this location to the desired child + * location. + * @return The specified child location. + */ +export function child(parent: Reference, path: string): ReferenceImpl { + parent = getModularInstance(parent); + if (pathGetFront(parent._path) === null) { validateRootPathString('child', 'path', path, false); } else { validatePathString('child', 'path', path, false); } - return new ReferenceImpl(ref._repo, pathChild(ref._path, path)); + return new ReferenceImpl(parent._repo, pathChild(parent._path, path)); } +/** + * Returns an `OnDisconnect` object - see {@link + * https://firebase.google.com/docs/database/web/offline-capabilities + * Enabling Offline Capabilities in JavaScript} for more information on how + * to use it. + * + * @param ref - The reference to add OnDisconnect triggers for. + */ export function onDisconnect(ref: Reference): OnDisconnect { ref = getModularInstance(ref) as ReferenceImpl; return new OnDisconnect(ref._repo, ref._path); @@ -397,11 +553,41 @@ export interface ThenableReferenceImpl extends ReferenceImpl, Pick, 'then' | 'catch'> {} -export function push(ref: Reference, value?: unknown): ThenableReferenceImpl { - ref = getModularInstance(ref); - validateWritablePath('push', ref._path); - validateFirebaseDataArg('push', value, ref._path, true); - const now = repoServerTime(ref._repo); +/** + * Generates a new child location using a unique key and returns its + * `Reference`. + * + * This is the most common pattern for adding data to a collection of items. + * + * If you provide a value to `push()`, the value is written to the + * generated location. If you don't pass a value, nothing is written to the + * database and the child remains empty (but you can use the `Reference` + * elsewhere). + * + * The unique keys generated by `push()` are ordered by the current time, so the + * resulting list of items is chronologically sorted. The keys are also + * designed to be unguessable (they contain 72 random bits of entropy). + * + * See {@link + * https://firebase.google.com/docs/database/web/lists-of-data#append_to_a_list_of_data + * Append to a list of data} + *
See {@link + * https://firebase.googleblog.com/2015/02/the-2120-ways-to-ensure-unique_68.html + * The 2^120 Ways to Ensure Unique Identifiers} + * + * @param parent - The parent location. + * @param value - Optional value to be written at the generated location. + * @return Combined `Promise` and `Reference`; resolves when write is complete, + * but can be used immediately as the `Reference` to the child location. + */ +export function push( + parent: Reference, + value?: unknown +): ThenableReferenceImpl { + parent = getModularInstance(parent); + validateWritablePath('push', parent._path); + validateFirebaseDataArg('push', value, parent._path, true); + const now = repoServerTime(parent._repo); const name = nextPushId(now); // push() returns a ThennableReference whose promise is fulfilled with a @@ -410,8 +596,8 @@ export function push(ref: Reference, value?: unknown): ThenableReferenceImpl { // then() and catch() methods and is used as the return value of push(). The // second remains a regular Reference and is used as the fulfilled value of // the first ThennableReference. - const thennablePushRef: Partial = child(ref, name); - const pushRef = child(ref, name); + const thennablePushRef: Partial = child(parent, name); + const pushRef = child(parent, name); let promise: Promise; if (value != null) { @@ -425,11 +611,54 @@ export function push(ref: Reference, value?: unknown): ThenableReferenceImpl { return thennablePushRef as ThenableReferenceImpl; } +/** + * Removes the data at this Database location. + * + * Any data at child locations will also be deleted. + * + * The effect of the remove will be visible immediately and the corresponding + * event 'value' will be triggered. Synchronization of the remove to the + * Firebase servers will also be started, and the returned Promise will resolve + * when complete. If provided, the onComplete callback will be called + * asynchronously after synchronization has finished. + * + * @param ref - The location to remove. + * @return Resolves when remove on server is complete. + */ export function remove(ref: Reference): Promise { validateWritablePath('remove', ref._path); return set(ref, null); } +/** + * Writes data to this Database location. + * + * This will overwrite any data at this location and all child locations. + * + * The effect of the write will be visible immediately, and the corresponding + * events ("value", "child_added", etc.) will be triggered. Synchronization of + * the data to the Firebase servers will also be started, and the returned + * Promise will resolve when complete. If provided, the `onComplete` callback + * will be called asynchronously after synchronization has finished. + * + * Passing `null` for the new value is equivalent to calling `remove()`; namely, + * all data at this location and all child locations will be deleted. + * + * `set()` will remove any priority stored at this location, so if priority is + * meant to be preserved, you need to use `setWithPriority()` instead. + * + * Note that modifying data with `set()` will cancel any pending transactions + * at that location, so extreme care should be taken if mixing `set()` and + * `transaction()` to modify the same data. + * + * A single `set()` will generate a single "value" event at the location where + * the `set()` was performed. + * + * @param ref - The location to write to. + * @param value - The value to be written (string, number, boolean, object, + * array, or null). + * @return Resolves when write to server is complete. + */ export function set(ref: Reference, value: unknown): Promise { ref = getModularInstance(ref); validateWritablePath('set', ref._path); @@ -445,6 +674,18 @@ export function set(ref: Reference, value: unknown): Promise { return deferred.promise; } +/** + * Sets a priority for the data at this Database location. + * + * Applications need not use priority but can order collections by + * ordinary properties (see {@link + * https://firebase.google.com/docs/database/web/lists-of-data#sorting_and_filtering_data + * Sorting and filtering data}). + * + * @param ref - The location to write to. + * @param priority - The priority to be written (string, number, or null). + * @return Resolves when write to server is complete. + */ export function setPriority( ref: Reference, priority: string | number | null @@ -463,6 +704,21 @@ export function setPriority( return deferred.promise; } +/** + * Writes data the Database location. Like `set()` but also specifies the + * priority for that data. + * + * Applications need not use priority but can order collections by + * ordinary properties (see {@link + * https://firebase.google.com/docs/database/web/lists-of-data#sorting_and_filtering_data + * Sorting and filtering data}). + * + * @param ref - The location to write to. + * @param value - The value to be written (string, number, boolean, object, + * array, or null). + * @param priority - The priority to be written (string, number, or null). + * @return Resolves when write to server is complete. + */ export function setWithPriority( ref: Reference, value: unknown, @@ -486,6 +742,42 @@ export function setWithPriority( return deferred.promise; } +/** + * Writes multiple values to the Database at once. + * + * The `values` argument contains multiple property-value pairs that will be + * written to the Database together. Each child property can either be a simple + * property (for example, "name") or a relative path (for example, + * "name/first") from the current location to the data to update. + * + * As opposed to the `set()` method, `update()` can be use to selectively update + * only the referenced properties at the current location (instead of replacing + * all the child properties at the current location). + * + * The effect of the write will be visible immediately, and the corresponding + * events ('value', 'child_added', etc.) will be triggered. Synchronization of + * the data to the Firebase servers will also be started, and the returned + * Promise will resolve when complete. If provided, the `onComplete` callback + * will be called asynchronously after synchronization has finished. + * + * A single `update()` will generate a single "value" event at the location + * where the `update()` was performed, regardless of how many children were + * modified. + * + * Note that modifying data with `update()` will cancel any pending + * transactions at that location, so extreme care should be taken if mixing + * `update()` and `transaction()` to modify the same data. + * + * Passing `null` to `update()` will remove the data at this location. + * + * See {@link + * https://firebase.googleblog.com/2015/09/introducing-multi-location-updates-and_86.html + * Introducing multi-location updates and more}. + * + * @param ref - The location to write to. + * @param values - Object containing multiple values. + * @return Resolves when update on server is complete. + */ export function update(ref: Reference, values: object): Promise { validateFirebaseMergeDataArg('update', values, ref._path, false); const deferred = new Deferred(); @@ -498,6 +790,14 @@ export function update(ref: Reference, values: object): Promise { return deferred.promise; } +/** + * Gets the most up-to-date result for this query. + * + * @param query - The query to run. + * @return A promise which resolves to the resulting DataSnapshot if a value is + * available, or rejects if the client is unable to return a value (e.g., if the + * server is unreachable and there is nothing cached). + */ export function get(query: Query): Promise { const queryImpl = getModularInstance(query) as QueryImpl; return repoGetValue(query._repo, queryImpl).then(node => { @@ -515,16 +815,10 @@ export function get(query: Query): Promise { export class ValueEventRegistration implements EventRegistration { constructor(private callbackContext: CallbackContext) {} - /** - * @inheritDoc - */ respondsTo(eventType: string): boolean { return eventType === 'value'; } - /** - * @inheritDoc - */ createEvent(change: Change, query: QueryContext): DataEvent { const index = query._queryParams.getIndex(); return new DataEvent( @@ -538,9 +832,6 @@ export class ValueEventRegistration implements EventRegistration { ); } - /** - * @inheritDoc - */ getEventRunner(eventData: CancelEvent | DataEvent): () => void { if (eventData.getEventType() === 'cancel') { return () => @@ -551,9 +842,6 @@ export class ValueEventRegistration implements EventRegistration { } } - /** - * @inheritDoc - */ createCancelEvent(error: Error, path: Path): CancelEvent | null { if (this.callbackContext.hasCancelCallback) { return new CancelEvent(this, error, path); @@ -562,9 +850,6 @@ export class ValueEventRegistration implements EventRegistration { } } - /** - * @inheritDoc - */ matches(other: EventRegistration): boolean { if (!(other instanceof ValueEventRegistration)) { return false; @@ -576,9 +861,6 @@ export class ValueEventRegistration implements EventRegistration { } } - /** - * @inheritDoc - */ hasAnyCallback(): boolean { return this.callbackContext !== null; } @@ -587,8 +869,8 @@ export class ValueEventRegistration implements EventRegistration { /** * Represents the registration of 1 or more child_xxx events. * - * Currently, it is always exactly 1 child_xxx event, but the idea is we might let you - * register a group of callbacks together in the future. + * Currently, it is always exactly 1 child_xxx event, but the idea is we might + * let you register a group of callbacks together in the future. */ export class ChildEventRegistration implements EventRegistration { constructor( @@ -597,9 +879,6 @@ export class ChildEventRegistration implements EventRegistration { } | null ) {} - /** - * @inheritDoc - */ respondsTo(eventType: string): boolean { let eventToCheck = eventType === 'children_added' ? 'child_added' : eventType; @@ -608,9 +887,6 @@ export class ChildEventRegistration implements EventRegistration { return contains(this.callbacks, eventToCheck); } - /** - * @inheritDoc - */ createCancelEvent(error: Error, path: Path): CancelEvent | null { if (this.callbacks['cancel'].hasCancelCallback) { return new CancelEvent(this, error, path); @@ -619,9 +895,6 @@ export class ChildEventRegistration implements EventRegistration { } } - /** - * @inheritDoc - */ createEvent(change: Change, query: QueryContext): DataEvent { assert(change.childName != null, 'Child events should have a childName.'); const childRef = child( @@ -637,9 +910,6 @@ export class ChildEventRegistration implements EventRegistration { ); } - /** - * @inheritDoc - */ getEventRunner(eventData: CancelEvent | DataEvent): () => void { if (eventData.getEventType() === 'cancel') { const cancelCB = this.callbacks['cancel']; @@ -654,9 +924,6 @@ export class ChildEventRegistration implements EventRegistration { } } - /** - * @inheritDoc - */ matches(other: EventRegistration): boolean { if (other instanceof ChildEventRegistration) { if (!this.callbacks || !other.callbacks) { @@ -693,9 +960,6 @@ export class ChildEventRegistration implements EventRegistration { return false; } - /** - * @inheritDoc - */ hasAnyCallback(): boolean { return this.callbacks !== null; } @@ -742,22 +1006,102 @@ function addEventListener( return () => repoRemoveEventCallbackForQuery(query._repo, query, container); } +/** + * Listens for data changes at a particular location. + * + * This is the primary way to read data from a Database. Your callback + * will be triggered for the initial data and again whenever the data changes. + * Invoke the returned unsubscribe callback to stop receiving updates. See + * {@link https://firebase.google.com/docs/database/web/retrieve-data Retrieve + * Data on the Web} for more details. + * + * An `onValue` event will trigger once with the initial data stored at this + * location, and then trigger again each time the data changes. The + * `DataSnapshot` passed to the callback will be for the location at which + * `on()` was called. It won't trigger until the entire contents has been + * synchronized. If the location has no data, it will be triggered with an empty + * `DataSnapshot` (`val()` will return `null`). + * + * @param query - The query to run. + * @param callback - A callback that fires when the specified event occurs. The + * callback will be passed a DataSnapshot. + * @param cancelCallback - An optional callback that will be notified if your + * event subscription is ever canceled because your client does not have + * permission to read this data (or it had permission but has now lost it). + * This callback will be passed an `Error` object indicating why the failure + * occurred. + * @return A function that can be invoked to remove the listener. + */ export function onValue( query: Query, callback: (snapshot: DataSnapshot) => unknown, cancelCallback?: (error: Error) => unknown ): Unsubscribe; + +/** + * Listens for data changes at a particular location. + * + * This is the primary way to read data from a Database. Your callback + * will be triggered for the initial data and again whenever the data changes. + * Invoke the returned unsubscribe callback to stop receiving updates. See + * {@link https://firebase.google.com/docs/database/web/retrieve-data Retrieve + * Data on the Web} for more details. + * + * An `onValue` event will trigger once with the initial data stored at this + * location, and then trigger again each time the data changes. The + * `DataSnapshot` passed to the callback will be for the location at which + * `on()` was called. It won't trigger until the entire contents has been + * synchronized. If the location has no data, it will be triggered with an empty + * `DataSnapshot` (`val()` will return `null`). + * + * @param query - The query to run. + * @param callback - A callback that fires when the specified event occurs. The + * callback will be passed a DataSnapshot. + * @param options - An object that can be used to configure `onlyOnce`, which + * then removes the listener after its first invocation. + * @return A function that can be invoked to remove the listener. + */ export function onValue( query: Query, callback: (snapshot: DataSnapshot) => unknown, options: ListenOptions ): Unsubscribe; + +/** + * Listens for data changes at a particular location. + * + * This is the primary way to read data from a Database. Your callback + * will be triggered for the initial data and again whenever the data changes. + * Invoke the returned unsubscribe callback to stop receiving updates. See + * {@link https://firebase.google.com/docs/database/web/retrieve-data Retrieve + * Data on the Web} for more details. + * + * An `onValue` event will trigger once with the initial data stored at this + * location, and then trigger again each time the data changes. The + * `DataSnapshot` passed to the callback will be for the location at which + * `on()` was called. It won't trigger until the entire contents has been + * synchronized. If the location has no data, it will be triggered with an empty + * `DataSnapshot` (`val()` will return `null`). + * + * @param query - The query to run. + * @param callback - A callback that fires when the specified event occurs. The + * callback will be passed a DataSnapshot. + * @param cancelCallback - An optional callback that will be notified if your + * event subscription is ever canceled because your client does not have + * permission to read this data (or it had permission but has now lost it). + * This callback will be passed an `Error` object indicating why the failure + * occurred. + * @param options - An object that can be used to configure `onlyOnce`, which + * then removes the listener after its first invocation. + * @return A function that can be invoked to remove the listener. + */ export function onValue( query: Query, callback: (snapshot: DataSnapshot) => unknown, cancelCallback: (error: Error) => unknown, options: ListenOptions ): Unsubscribe; + export function onValue( query: Query, callback: (snapshot: DataSnapshot) => unknown, @@ -773,6 +1117,33 @@ export function onValue( ); } +/** + * Listens for data changes at a particular location. + * + * This is the primary way to read data from a Database. Your callback + * will be triggered for the initial data and again whenever the data changes. + * Invoke the returned unsubscribe callback to stop receiving updates. See + * {@link https://firebase.google.com/docs/database/web/retrieve-data Retrieve + * Data on the Web} for more details. + * + * An `onChildAdded` event will be triggered once for each initial child at this + * location, and it will be triggered again every time a new child is added. The + * `DataSnapshot` passed into the callback will reflect the data for the + * relevant child. For ordering purposes, it is passed a second argument which + * is a string containing the key of the previous sibling child by sort order, + * or `null` if it is the first child. + * + * @param query - The query to run. + * @param callback - A callback that fires when the specified event occurs. + * The callback will be passed a DataSnapshot and a string containing the key of + * the previous child, by sort order, or `null` if it is the first child. + * @param cancelCallback - An optional callback that will be notified if your + * event subscription is ever canceled because your client does not have + * permission to read this data (or it had permission but has now lost it). + * This callback will be passed an `Error` object indicating why the failure + * occurred. + * @return A function that can be invoked to remove the listener. + */ export function onChildAdded( query: Query, callback: ( @@ -781,6 +1152,31 @@ export function onChildAdded( ) => unknown, cancelCallback?: (error: Error) => unknown ): Unsubscribe; + +/** + * Listens for data changes at a particular location. + * + * This is the primary way to read data from a Database. Your callback + * will be triggered for the initial data and again whenever the data changes. + * Invoke the returned unsubscribe callback to stop receiving updates. See + * {@link https://firebase.google.com/docs/database/web/retrieve-data Retrieve + * Data on the Web} for more details. + * + * An `onChildAdded` event will be triggered once for each initial child at this + * location, and it will be triggered again every time a new child is added. The + * `DataSnapshot` passed into the callback will reflect the data for the + * relevant child. For ordering purposes, it is passed a second argument which + * is a string containing the key of the previous sibling child by sort order, + * or `null` if it is the first child. + * + * @param query - The query to run. + * @param callback - A callback that fires when the specified event occurs. + * The callback will be passed a DataSnapshot and a string containing the key of + * the previous child, by sort order, or `null` if it is the first child. + * @param options - An object that can be used to configure `onlyOnce`, which + * then removes the listener after its first invocation. + * @return A function that can be invoked to remove the listener. + */ export function onChildAdded( query: Query, callback: ( @@ -789,6 +1185,36 @@ export function onChildAdded( ) => unknown, options: ListenOptions ): Unsubscribe; + +/** + * Listens for data changes at a particular location. + * + * This is the primary way to read data from a Database. Your callback + * will be triggered for the initial data and again whenever the data changes. + * Invoke the returned unsubscribe callback to stop receiving updates. See + * {@link https://firebase.google.com/docs/database/web/retrieve-data Retrieve + * Data on the Web} for more details. + * + * An `onChildAdded` event will be triggered once for each initial child at this + * location, and it will be triggered again every time a new child is added. The + * `DataSnapshot` passed into the callback will reflect the data for the + * relevant child. For ordering purposes, it is passed a second argument which + * is a string containing the key of the previous sibling child by sort order, + * or `null` if it is the first child. + * + * @param query - The query to run. + * @param callback - A callback that fires when the specified event occurs. + * The callback will be passed a DataSnapshot and a string containing the key of + * the previous child, by sort order, or `null` if it is the first child. + * @param cancelCallback - An optional callback that will be notified if your + * event subscription is ever canceled because your client does not have + * permission to read this data (or it had permission but has now lost it). + * This callback will be passed an `Error` object indicating why the failure + * occurred. + * @param options - An object that can be used to configure `onlyOnce`, which + * then removes the listener after its first invocation. + * @return A function that can be invoked to remove the listener. + */ export function onChildAdded( query: Query, callback: ( @@ -798,6 +1224,7 @@ export function onChildAdded( cancelCallback: (error: Error) => unknown, options: ListenOptions ): Unsubscribe; + export function onChildAdded( query: Query, callback: ( @@ -816,6 +1243,34 @@ export function onChildAdded( ); } +/** + * Listens for data changes at a particular location. + * + * This is the primary way to read data from a Database. Your callback + * will be triggered for the initial data and again whenever the data changes. + * Invoke the returned unsubscribe callback to stop receiving updates. See + * {@link https://firebase.google.com/docs/database/web/retrieve-data Retrieve + * Data on the Web} for more details. + * + * An `onChildChanged` event will be triggered when the data stored in a child + * (or any of its descendants) changes. Note that a single `child_changed` event + * may represent multiple changes to the child. The `DataSnapshot` passed to the + * callback will contain the new child contents. For ordering purposes, the + * callback is also passed a second argument which is a string containing the + * key of the previous sibling child by sort order, or `null` if it is the first + * child. + * + * @param query - The query to run. + * @param callback - A callback that fires when the specified event occurs. + * The callback will be passed a DataSnapshot and a string containing the key of + * the previous child, by sort order, or `null` if it is the first child. + * @param cancelCallback - An optional callback that will be notified if your + * event subscription is ever canceled because your client does not have + * permission to read this data (or it had permission but has now lost it). + * This callback will be passed an `Error` object indicating why the failure + * occurred. + * @return A function that can be invoked to remove the listener. + */ export function onChildChanged( query: Query, callback: ( @@ -824,6 +1279,32 @@ export function onChildChanged( ) => unknown, cancelCallback?: (error: Error) => unknown ): Unsubscribe; + +/** + * Listens for data changes at a particular location. + * + * This is the primary way to read data from a Database. Your callback + * will be triggered for the initial data and again whenever the data changes. + * Invoke the returned unsubscribe callback to stop receiving updates. See + * {@link https://firebase.google.com/docs/database/web/retrieve-data Retrieve + * Data on the Web} for more details. + * + * An `onChildChanged` event will be triggered when the data stored in a child + * (or any of its descendants) changes. Note that a single `child_changed` event + * may represent multiple changes to the child. The `DataSnapshot` passed to the + * callback will contain the new child contents. For ordering purposes, the + * callback is also passed a second argument which is a string containing the + * key of the previous sibling child by sort order, or `null` if it is the first + * child. + * + * @param query - The query to run. + * @param callback - A callback that fires when the specified event occurs. + * The callback will be passed a DataSnapshot and a string containing the key of + * the previous child, by sort order, or `null` if it is the first child. + * @param options - An object that can be used to configure `onlyOnce`, which + * then removes the listener after its first invocation. + * @return A function that can be invoked to remove the listener. + */ export function onChildChanged( query: Query, callback: ( @@ -832,6 +1313,37 @@ export function onChildChanged( ) => unknown, options: ListenOptions ): Unsubscribe; + +/** + * Listens for data changes at a particular location. + * + * This is the primary way to read data from a Database. Your callback + * will be triggered for the initial data and again whenever the data changes. + * Invoke the returned unsubscribe callback to stop receiving updates. See + * {@link https://firebase.google.com/docs/database/web/retrieve-data Retrieve + * Data on the Web} for more details. + * + * An `onChildChanged` event will be triggered when the data stored in a child + * (or any of its descendants) changes. Note that a single `child_changed` event + * may represent multiple changes to the child. The `DataSnapshot` passed to the + * callback will contain the new child contents. For ordering purposes, the + * callback is also passed a second argument which is a string containing the + * key of the previous sibling child by sort order, or `null` if it is the first + * child. + * + * @param query - The query to run. + * @param callback - A callback that fires when the specified event occurs. + * The callback will be passed a DataSnapshot and a string containing the key of + * the previous child, by sort order, or `null` if it is the first child. + * @param cancelCallback - An optional callback that will be notified if your + * event subscription is ever canceled because your client does not have + * permission to read this data (or it had permission but has now lost it). + * This callback will be passed an `Error` object indicating why the failure + * occurred. + * @param options - An object that can be used to configure `onlyOnce`, which + * then removes the listener after its first invocation. + * @return A function that can be invoked to remove the listener. + */ export function onChildChanged( query: Query, callback: ( @@ -841,6 +1353,7 @@ export function onChildChanged( cancelCallback: (error: Error) => unknown, options: ListenOptions ): Unsubscribe; + export function onChildChanged( query: Query, callback: ( @@ -859,6 +1372,32 @@ export function onChildChanged( ); } +/** + * Listens for data changes at a particular location. + * + * This is the primary way to read data from a Database. Your callback + * will be triggered for the initial data and again whenever the data changes. + * Invoke the returned unsubscribe callback to stop receiving updates. See + * {@link https://firebase.google.com/docs/database/web/retrieve-data Retrieve + * Data on the Web} for more details. + * + * An `onChildMoved` event will be triggered when a child's sort order changes + * such that its position relative to its siblings changes. The `DataSnapshot` + * passed to the callback will be for the data of the child that has moved. It + * is also passed a second argument which is a string containing the key of the + * previous sibling child by sort order, or `null` if it is the first child. + * + * @param query - The query to run. + * @param callback - A callback that fires when the specified event occurs. + * The callback will be passed a DataSnapshot and a string containing the key of + * the previous child, by sort order, or `null` if it is the first child. + * @param cancelCallback - An optional callback that will be notified if your + * event subscription is ever canceled because your client does not have + * permission to read this data (or it had permission but has now lost it). + * This callback will be passed an `Error` object indicating why the failure + * occurred. + * @return A function that can be invoked to remove the listener. + */ export function onChildMoved( query: Query, callback: ( @@ -867,6 +1406,30 @@ export function onChildMoved( ) => unknown, cancelCallback?: (error: Error) => unknown ): Unsubscribe; + +/** + * Listens for data changes at a particular location. + * + * This is the primary way to read data from a Database. Your callback + * will be triggered for the initial data and again whenever the data changes. + * Invoke the returned unsubscribe callback to stop receiving updates. See + * {@link https://firebase.google.com/docs/database/web/retrieve-data Retrieve + * Data on the Web} for more details. + * + * An `onChildMoved` event will be triggered when a child's sort order changes + * such that its position relative to its siblings changes. The `DataSnapshot` + * passed to the callback will be for the data of the child that has moved. It + * is also passed a second argument which is a string containing the key of the + * previous sibling child by sort order, or `null` if it is the first child. + * + * @param query - The query to run. + * @param callback - A callback that fires when the specified event occurs. + * The callback will be passed a DataSnapshot and a string containing the key of + * the previous child, by sort order, or `null` if it is the first child. + * @param options - An object that can be used to configure `onlyOnce`, which + * then removes the listener after its first invocation. + * @return A function that can be invoked to remove the listener. + */ export function onChildMoved( query: Query, callback: ( @@ -875,6 +1438,35 @@ export function onChildMoved( ) => unknown, options: ListenOptions ): Unsubscribe; + +/** + * Listens for data changes at a particular location. + * + * This is the primary way to read data from a Database. Your callback + * will be triggered for the initial data and again whenever the data changes. + * Invoke the returned unsubscribe callback to stop receiving updates. See + * {@link https://firebase.google.com/docs/database/web/retrieve-data Retrieve + * Data on the Web} for more details. + * + * An `onChildMoved` event will be triggered when a child's sort order changes + * such that its position relative to its siblings changes. The `DataSnapshot` + * passed to the callback will be for the data of the child that has moved. It + * is also passed a second argument which is a string containing the key of the + * previous sibling child by sort order, or `null` if it is the first child. + * + * @param query - The query to run. + * @param callback - A callback that fires when the specified event occurs. + * The callback will be passed a DataSnapshot and a string containing the key of + * the previous child, by sort order, or `null` if it is the first child. + * @param cancelCallback - An optional callback that will be notified if your + * event subscription is ever canceled because your client does not have + * permission to read this data (or it had permission but has now lost it). + * This callback will be passed an `Error` object indicating why the failure + * occurred. + * @param options - An object that can be used to configure `onlyOnce`, which + * then removes the listener after its first invocation. + * @return A function that can be invoked to remove the listener. + */ export function onChildMoved( query: Query, callback: ( @@ -884,6 +1476,7 @@ export function onChildMoved( cancelCallback: (error: Error) => unknown, options: ListenOptions ): Unsubscribe; + export function onChildMoved( query: Query, callback: ( @@ -902,22 +1495,114 @@ export function onChildMoved( ); } +/** + * Listens for data changes at a particular location. + * + * This is the primary way to read data from a Database. Your callback + * will be triggered for the initial data and again whenever the data changes. + * Invoke the returned unsubscribe callback to stop receiving updates. See + * {@link https://firebase.google.com/docs/database/web/retrieve-data Retrieve + * Data on the Web} for more details. + * + * An `onChildRemoved` event will be triggered once every time a child is + * removed. The `DataSnapshot` passed into the callback will be the old data for + * the child that was removed. A child will get removed when either: + * + * - a client explicitly calls `remove()` on that child or one of its ancestors + * - a client calls `set(null)` on that child or one of its ancestors + * - that child has all of its children removed + * - there is a query in effect which now filters out the child (because it's + * sort order changed or the max limit was hit) + * + * @param query - The query to run. + * @param callback - A callback that fires when the specified event occurs. + * The callback will be passed a DataSnapshot and a string containing the key of + * the previous child, by sort order, or `null` if it is the first child. + * @param cancelCallback - An optional callback that will be notified if your + * event subscription is ever canceled because your client does not have + * permission to read this data (or it had permission but has now lost it). + * This callback will be passed an `Error` object indicating why the failure + * occurred. + * @return A function that can be invoked to remove the listener. + */ export function onChildRemoved( query: Query, callback: (snapshot: DataSnapshot) => unknown, cancelCallback?: (error: Error) => unknown ): Unsubscribe; + +/** + * Listens for data changes at a particular location. + * + * This is the primary way to read data from a Database. Your callback + * will be triggered for the initial data and again whenever the data changes. + * Invoke the returned unsubscribe callback to stop receiving updates. See + * {@link https://firebase.google.com/docs/database/web/retrieve-data Retrieve + * Data on the Web} for more details. + * + * An `onChildRemoved` event will be triggered once every time a child is + * removed. The `DataSnapshot` passed into the callback will be the old data for + * the child that was removed. A child will get removed when either: + * + * - a client explicitly calls `remove()` on that child or one of its ancestors + * - a client calls `set(null)` on that child or one of its ancestors + * - that child has all of its children removed + * - there is a query in effect which now filters out the child (because it's + * sort order changed or the max limit was hit) + * + * @param query - The query to run. + * @param callback - A callback that fires when the specified event occurs. + * The callback will be passed a DataSnapshot and a string containing the key of + * the previous child, by sort order, or `null` if it is the first child. + * @param options - An object that can be used to configure `onlyOnce`, which + * then removes the listener after its first invocation. + * @return A function that can be invoked to remove the listener. + */ export function onChildRemoved( query: Query, callback: (snapshot: DataSnapshot) => unknown, options: ListenOptions ): Unsubscribe; + +/** + * Listens for data changes at a particular location. + * + * This is the primary way to read data from a Database. Your callback + * will be triggered for the initial data and again whenever the data changes. + * Invoke the returned unsubscribe callback to stop receiving updates. See + * {@link https://firebase.google.com/docs/database/web/retrieve-data Retrieve + * Data on the Web} for more details. + * + * An `onChildRemoved` event will be triggered once every time a child is + * removed. The `DataSnapshot` passed into the callback will be the old data for + * the child that was removed. A child will get removed when either: + * + * - a client explicitly calls `remove()` on that child or one of its ancestors + * - a client calls `set(null)` on that child or one of its ancestors + * - that child has all of its children removed + * - there is a query in effect which now filters out the child (because it's + * sort order changed or the max limit was hit) + * + * @param query - The query to run. + * @param callback - A callback that fires when the specified event occurs. + * The callback will be passed a DataSnapshot and a string containing the key of + * the previous child, by sort order, or `null` if it is the first child. + * @param cancelCallback - An optional callback that will be notified if your + * event subscription is ever canceled because your client does not have + * permission to read this data (or it had permission but has now lost it). + * This callback will be passed an `Error` object indicating why the failure + * occurred. + * @param options - An object that can be used to configure `onlyOnce`, which + * then removes the listener after its first invocation. + * @return A function that can be invoked to remove the listener. + */ export function onChildRemoved( query: Query, callback: (snapshot: DataSnapshot) => unknown, cancelCallback: (error: Error) => unknown, options: ListenOptions ): Unsubscribe; + export function onChildRemoved( query: Query, callback: (snapshot: DataSnapshot) => unknown, @@ -935,6 +1620,30 @@ export function onChildRemoved( export { EventType }; +/** + * Detaches a callback previously attached with `on()`. + * + * Detach a callback previously attached with `on()`. Note that if `on()` was + * called multiple times with the same eventType and callback, the callback + * will be called multiple times for each event, and `off()` must be called + * multiple times to remove the callback. Calling `off()` on a parent listener + * will not automatically remove listeners registered on child nodes, `off()` + * must also be called on any child listeners to remove the callback. + * + * If a callback is not specified, all callbacks for the specified eventType + * will be removed. Similarly, if no eventType is specified, all callbacks + * for the `Reference` will be removed. + * + * Individual listeners can also be removed by invoking their unsubscribe + * callbacks. + * + * @param query - The query that the listener was registered with. + * @param eventType One of the following strings: "value", "child_added", + * "child_changed", "child_removed", or "child_moved." If omitted, all callbacks + * for the `Reference` will be removed. + * @param callback The callback function that was passed to `on()` or + * `undefined` to remove all callbacks. + */ export function off( query: Query, eventType?: EventType, @@ -1027,6 +1736,30 @@ class QueryEndAtConstraint extends QueryConstraint { } } +/** + * Creates a `QueryConstraint` with the specified ending point. + * + * Using `startAt()`, `startAfter()`, `endBefore()`, `endAt()` and `equalTo()` + * allows you to choose arbitrary starting and ending points for your queries. + * + * The ending point is inclusive, so children with exactly the specified value + * will be included in the query. The optional key argument can be used to + * further limit the range of the query. If it is specified, then children that + * have exactly the specified value must also have a key name less than or equal + * to the specified key. + * + * You can read more about `endAt()` in{@link + * https://firebase.google.com/docs/database/web/lists-of-data#filtering_data + * Filtering data}. + * + * @param value - The value to end at. The argument type depends on which + * `orderBy*()` function was used in this query. Specify a value that matches + * the `orderBy*()` type. When used in combination with `orderByKey()`, the + * value must be a string. + * @param key - The child key to end at, among the children with the previously + * specified priority. This argument is only allowed if ordering by child, + * value, or priority. + */ export function endAt( value: number | string | boolean | null, key?: string @@ -1069,6 +1802,25 @@ class QueryEndBeforeConstraint extends QueryConstraint { } } +/** + * Creates a `QueryConstraint` with the specified ending point (exclusive). + * + * Using `startAt()`, `startAfter()`, `endBefore()`, `endAt()` and `equalTo()` + * allows you to choose arbitrary starting and ending points for your queries. + * + * The ending point is exclusive. If only a value is provided, children + * with a value less than the specified value will be included in the query. + * If a key is specified, then children must have a value lesss than or equal + * to the specified value and a a key name less than the specified key. + * + * @param value - The value to end before. The argument type depends on which + * `orderBy*()` function was used in this query. Specify a value that matches + * the `orderBy*()` type. When used in combination with `orderByKey()`, the + * value must be a string. + * @param key - The child key to end before, among the children with the + * previously specified priority. This argument is only allowed if ordering by + * child, value, or priority. + */ export function endBefore( value: number | string | boolean | null, key?: string @@ -1111,6 +1863,29 @@ class QueryStartAtConstraint extends QueryConstraint { } } +/** + * Creates a `QueryConstraint` with the specified starting point. + * + * Using `startAt()`, `startAfter()`, `endBefore()`, `endAt()` and `equalTo()` + * allows you to choose arbitrary starting and ending points for your queries. + * + * The starting point is inclusive, so children with exactly the specified value + * will be included in the query. The optional key argument can be used to + * further limit the range of the query. If it is specified, then children that + * have exactly the specified value must also have a key name greater than or + * equal to the specified key. + * + * You can read more about `startAt()` in {@link + * https://firebase.google.com/docs/database/web/lists-of-data#filtering_data + * Filtering data}. + * + * @param value - The value to start at. The argument type depends on which + * `orderBy*()` function was used in this query. Specify a value that matches + * the `orderBy*()` type. When used in combination with `orderByKey()`, the + * value must be a string. + * @param key - The child key to start at. This argument is only allowed if + * ordering by child, value, or priority. + */ export function startAt( value: number | string | boolean | null = null, key?: string @@ -1153,6 +1928,24 @@ class QueryStartAfterConstraint extends QueryConstraint { } } +/** + * Creates a `QueryConstraint` with the specified starting point (exclusive). + * + * Using `startAt()`, `startAfter()`, `endBefore()`, `endAt()` and `equalTo()` + * allows you to choose arbitrary starting and ending points for your queries. + * + * The starting point is exclusive. If only a value is provided, children + * with a value greater than the specified value will be included in the query. + * If a key is specified, then children must have a value greater than or equal + * to the specified value and a a key name greater than the specified key. + * + * @param value The value to start after. The argument type depends on which + * `orderBy*()` function was used in this query. Specify a value that matches + * the `orderBy*()` type. When used in combination with `orderByKey()`, the + * value must be a string. + * @param key - The child key to start after. This argument is only allowed if + * ordering by child, value, or priority. + */ export function startAfter( value: number | string | boolean | null, key?: string @@ -1184,6 +1977,25 @@ class QueryLimitToFirstConstraint extends QueryConstraint { } } +/** + * Creates a new `QueryConstraint` that if limited to the first specific number + * of children. + * + * The `limitToFirst()` method is used to set a maximum number of children to be + * synced for a given callback. If we set a limit of 100, we will initially only + * receive up to 100 `child_added` events. If we have fewer than 100 messages + * stored in our Database, a `child_added` event will fire for each message. + * However, if we have over 100 messages, we will only receive a `child_added` + * event for the first 100 ordered messages. As items change, we will receive + * `child_removed` events for each item that drops out of the active list so + * that the total number stays at 100. + * + * You can read more about `limitToFirst()` in {@link + * https://firebase.google.com/docs/database/web/lists-of-data#filtering_data + * Filtering data}. + * + * @param limit - The maximum number of nodes to include in this query. + */ export function limitToFirst(limit: number): QueryConstraint { if (typeof limit !== 'number' || Math.floor(limit) !== limit || limit <= 0) { throw new Error('limitToFirst: First argument must be a positive integer.'); @@ -1214,6 +2026,25 @@ class QueryLimitToLastConstraint extends QueryConstraint { } } +/** + * Creates a new `QueryConstraint` that is limited to return only the last + * specified number of children. + * + * The `limitToLast()` method is used to set a maximum number of children to be + * synced for a given callback. If we set a limit of 100, we will initially only + * receive up to 100 `child_added` events. If we have fewer than 100 messages + * stored in our Database, a `child_added` event will fire for each message. + * However, if we have over 100 messages, we will only receive a `child_added` + * event for the last 100 ordered messages. As items change, we will receive + * `child_removed` events for each item that drops out of the active list so + * that the total number stays at 100. + * + * You can read more about `limitToLast()` in {@link + * https://firebase.google.com/docs/database/web/lists-of-data#filtering_data + * Filtering data}. + * + * @param limit - The maximum number of nodes to include in this query. + */ export function limitToLast(limit: number): QueryConstraint { if (typeof limit !== 'number' || Math.floor(limit) !== limit || limit <= 0) { throw new Error('limitToLast: First argument must be a positive integer.'); @@ -1250,6 +2081,24 @@ class QueryOrderByChildConstraint extends QueryConstraint { } } +/** + * Creates a new `QueryConstraint` that orders by the specified child key. + * + * Queries can only order by one key at a time. Calling `orderByChild()` + * multiple times on the same query is an error. + * + * Firebase queries allow you to order your data by any child key on the fly. + * However, if you know in advance what your indexes will be, you can define + * them via the .indexOn rule in your Security Rules for better performance. See + * the {@link https://firebase.google.com/docs/database/security/indexing-data + * .indexOn} rule for more information. + * + * You can read more about `orderByChild()` in {@link + * https://firebase.google.com/docs/database/web/lists-of-data#sort_data + * Sort data}. + * + * @param path - The path to order by. + */ export function orderByChild(path: string): QueryConstraint { if (path === '$key') { throw new Error( @@ -1284,6 +2133,15 @@ class QueryOrderByKeyConstraint extends QueryConstraint { } } +/** + * Creates a new `QueryConstraint` that orders by the key. + * + * Sorts the results of a query by their (ascending) key values. + * + * You can read more about `orderByKey()` in {@link + * https://firebase.google.com/docs/database/web/lists-of-data#sort_data + * Sort data}. + */ export function orderByKey(): QueryConstraint { return new QueryOrderByKeyConstraint(); } @@ -1304,6 +2162,14 @@ class QueryOrderByPriorityConstraint extends QueryConstraint { } } +/** + * Creates a new `QueryConstraint` that orders by priority. + * + * Applications need not use priority but can order collections by + * ordinary properties (see {@link + * https://firebase.google.com/docs/database/web/lists-of-data#sort_data + * Sort data} for alternatives to priority. + */ export function orderByPriority(): QueryConstraint { return new QueryOrderByPriorityConstraint(); } @@ -1324,6 +2190,16 @@ class QueryOrderByValueConstraint extends QueryConstraint { } } +/** + * Creates a new `QueryConstraint` that orders by value. + * + * If the children of a query are all scalar values (string, number, or + * boolean), you can order the results by their (ascending) values. + * + * You can read more about `orderByValue()` in {@link + * https://firebase.google.com/docs/database/web/lists-of-data#sort_data + * Sort data}. + */ export function orderByValue(): QueryConstraint { return new QueryOrderByValueConstraint(); } @@ -1358,6 +2234,30 @@ class QueryEqualToValueConstraint extends QueryConstraint { } } +/** + * Creates a `QueryConstraint` that includes children that match the specified + * value. + * + * Using `startAt()`, `startAfter()`, `endBefore()`, `endAt()` and `equalTo()` + * allows you to choose arbitrary starting and ending points for your queries. + * + * The optional key argument can be used to further limit the range of the + * query. If it is specified, then children that have exactly the specified + * value must also have exactly the specified key as their key name. This can be + * used to filter result sets with many matches for the same value. + * + * You can read more about `equalTo()` in {@link + * https://firebase.google.com/docs/database/web/lists-of-data#filtering_data + * Filtering data}. + * + * @param value - The value to match for. The argument type depends on which + * `orderBy*()` function was used in this query. Specify a value that matches + * the `orderBy*()` type. When used in combination with `orderByKey()`, the + * value must be a string. + * @param key - The child key to start at, among the children with the + * previously specified priority. This argument is only allowed if ordering by + * child, value, or priority. + */ export function equalTo( value: number | string | boolean | null, key?: string diff --git a/packages/database/src/exp/ServerValue.ts b/packages/database/src/exp/ServerValue.ts index 6fdecee1b2a..3ea7889a388 100644 --- a/packages/database/src/exp/ServerValue.ts +++ b/packages/database/src/exp/ServerValue.ts @@ -19,10 +19,22 @@ const SERVER_TIMESTAMP = { '.sv': 'timestamp' }; +/** + * Returns a placeholder value for auto-populating the current timestamp (time + * since the Unix epoch, in milliseconds) as determined by the Firebase + * servers. + */ export function serverTimestamp(): object { return SERVER_TIMESTAMP; } +/** + * Returns a placeholder value that can be used to atomically increment the + * current database value by the provided delta. + * + * @param delta the amount to modify the current value atomically. + * @return A placeholder value for modifying data atomically server-side. + */ export function increment(delta: number): object { return { '.sv': { diff --git a/packages/database/src/exp/Transaction.ts b/packages/database/src/exp/Transaction.ts index d20723cdec8..39ed8ea0497 100644 --- a/packages/database/src/exp/Transaction.ts +++ b/packages/database/src/exp/Transaction.ts @@ -25,7 +25,14 @@ import { validateWritablePath } from '../core/util/validation'; import { Reference } from './Reference'; import { DataSnapshot, onValue, ReferenceImpl } from './Reference_impl'; +/** An options object to configure transactions. */ export interface TransactionOptions { + /** + * By default, events are raised each time the transaction update function + * runs. So if it is run multiple times, you may see intermediate states. You + * can set this to false to suppress these intermediate states and instead + * wait until the transaction has completed before events are raised. + */ readonly applyLocally?: boolean; } @@ -40,6 +47,43 @@ export class TransactionResult { } } +/** + * Atomically modifies the data at this location. + * + * Atomically modify the data at this location. Unlike a normal `set()`, which + * just overwrites the data regardless of its previous value, `transaction()` is + * used to modify the existing value to a new value, ensuring there are no + * conflicts with other clients writing to the same location at the same time. + * + * To accomplish this, you pass `runTransaction()` an update function which is + * used to transform the current value into a new value. If another client + * writes to the location before your new value is successfully written, your + * update function will be called again with the new current value, and the + * write will be retried. This will happen repeatedly until your write succeeds + * without conflict or you abort the transaction by not returning a value from + * your update function. + * + * Note: Modifying data with `set()` will cancel any pending transactions at + * that location, so extreme care should be taken if mixing `set()` and + * `transaction()` to update the same data. + * + * Note: When using transactions with Security and Firebase Rules in place, be + * aware that a client needs `.read` access in addition to `.write` access in + * order to perform a transaction. This is because the client-side nature of + * transactions requires the client to read the data in order to transactionally + * update it. + * + * @param ref - The location to atomically modify. + * @param transactionUpdate - A developer-supplied function which will be passed + * the current data stored at this location (as a JavaScript object). The + * function should return the new value it would like written (as a JavaScript + * object). If `undefined` is returned (i.e. you return with no arguments) the + * transaction will be aborted and the data at this location will not be + * modified. + * @param options - An options object to configure transactions. + * @return A Promise that can optionally be used instead of the onComplete + * callback to handle success and failure. + */ export function runTransaction( ref: Reference, // eslint-disable-next-line @typescript-eslint/no-explicit-any From 73c0ca19e8d7e82c39d306c9253af8b717e474af Mon Sep 17 00:00:00 2001 From: Sebastian Schmidt Date: Tue, 6 Apr 2021 12:53:58 -0600 Subject: [PATCH 2/2] return -> returns --- packages/database/src/api/Database.ts | 4 +- packages/database/src/api/Reference.ts | 28 +++---- packages/database/src/core/CompoundWrite.ts | 12 +-- packages/database/src/core/Repo.ts | 10 +-- .../database/src/core/SparseSnapshotTree.ts | 4 +- packages/database/src/core/SyncPoint.ts | 8 +- packages/database/src/core/SyncTree.ts | 26 +++---- packages/database/src/core/WriteTree.ts | 2 +- packages/database/src/core/snap/LeafNode.ts | 2 +- packages/database/src/core/snap/Node.ts | 32 ++++---- .../database/src/core/snap/indexes/Index.ts | 10 +-- .../src/core/snap/indexes/KeyIndex.ts | 2 +- .../src/core/snap/indexes/PriorityIndex.ts | 2 +- .../src/core/snap/indexes/ValueIndex.ts | 2 +- .../src/core/storage/DOMStorageWrapper.ts | 2 +- packages/database/src/core/storage/storage.ts | 2 +- .../database/src/core/util/EventEmitter.ts | 2 +- .../database/src/core/util/ImmutableTree.ts | 10 +-- packages/database/src/core/util/Path.ts | 12 +-- packages/database/src/core/util/SortedMap.ts | 76 +++++++++---------- packages/database/src/core/util/Tree.ts | 12 +-- .../database/src/core/util/libs/parser.ts | 2 +- packages/database/src/core/util/util.ts | 10 +-- .../database/src/core/view/QueryParams.ts | 6 +- packages/database/src/core/view/View.ts | 2 +- packages/database/src/exp/Database.ts | 2 +- packages/database/src/exp/OnDisconnect.ts | 10 +-- packages/database/src/exp/Reference.ts | 6 +- packages/database/src/exp/Reference_impl.ts | 60 +++++++-------- packages/database/src/exp/ServerValue.ts | 2 +- packages/database/src/exp/Transaction.ts | 2 +- .../database/src/realtime/TransportManager.ts | 4 +- .../src/realtime/WebSocketConnection.ts | 4 +- packages/database/test/datasnapshot.test.ts | 2 +- 34 files changed, 186 insertions(+), 186 deletions(-) diff --git a/packages/database/src/api/Database.ts b/packages/database/src/api/Database.ts index 468bf9153b1..2649cad1b47 100644 --- a/packages/database/src/api/Database.ts +++ b/packages/database/src/api/Database.ts @@ -69,7 +69,7 @@ export class Database implements FirebaseService, Compat { * location. * @throws If a Reference is provided, throws if it does not belong to the * same project. - * @return Firebase reference. + * @returns Firebase reference. */ ref(path?: string): Reference; ref(path?: Reference): Reference; @@ -88,7 +88,7 @@ export class Database implements FirebaseService, Compat { * Returns a reference to the root or the path specified in url. * We throw a exception if the url is not in the same domain as the * current repo. - * @return Firebase reference. + * @returns Firebase reference. */ refFromURL(url: string): Reference { const apiName = 'database.refFromURL'; diff --git a/packages/database/src/api/Reference.ts b/packages/database/src/api/Reference.ts index e918b3020f9..1d1dd3ba1b6 100644 --- a/packages/database/src/api/Reference.ts +++ b/packages/database/src/api/Reference.ts @@ -85,7 +85,7 @@ export class DataSnapshot implements Compat { * Retrieves the snapshot contents as JSON. Returns null if the snapshot is * empty. * - * @return JSON representation of the DataSnapshot contents, or null if empty. + * @returns JSON representation of the DataSnapshot contents, or null if empty. */ val(): unknown { validateArgCount('DataSnapshot.val', 0, 0, arguments.length); @@ -95,7 +95,7 @@ export class DataSnapshot implements Compat { /** * Returns the snapshot contents as JSON, including priorities of node. Suitable for exporting * the entire node contents. - * @return JSON representation of the DataSnapshot contents, or null if empty. + * @returns JSON representation of the DataSnapshot contents, or null if empty. */ exportVal(): unknown { validateArgCount('DataSnapshot.exportVal', 0, 0, arguments.length); @@ -113,7 +113,7 @@ export class DataSnapshot implements Compat { /** * Returns whether the snapshot contains a non-null value. * - * @return Whether the snapshot contains a non-null value, or is empty. + * @returns Whether the snapshot contains a non-null value, or is empty. */ exists(): boolean { validateArgCount('DataSnapshot.exists', 0, 0, arguments.length); @@ -124,7 +124,7 @@ export class DataSnapshot implements Compat { * Returns a DataSnapshot of the specified child node's contents. * * @param path Path to a child. - * @return DataSnapshot for child node. + * @returns DataSnapshot for child node. */ child(path: string): DataSnapshot { validateArgCount('DataSnapshot.child', 0, 1, arguments.length); @@ -138,7 +138,7 @@ export class DataSnapshot implements Compat { * Returns whether the snapshot contains a child at the specified path. * * @param path Path to a child. - * @return Whether the child exists. + * @returns Whether the child exists. */ hasChild(path: string): boolean { validateArgCount('DataSnapshot.hasChild', 1, 1, arguments.length); @@ -149,7 +149,7 @@ export class DataSnapshot implements Compat { /** * Returns the priority of the object, or null if no priority was set. * - * @return The priority. + * @returns The priority. */ getPriority(): string | number | null { validateArgCount('DataSnapshot.getPriority', 0, 0, arguments.length); @@ -161,7 +161,7 @@ export class DataSnapshot implements Compat { * * @param action Callback function to be called * for each child. - * @return True if forEach was canceled by action returning true for + * @returns True if forEach was canceled by action returning true for * one of the child nodes. */ forEach(action: (snapshot: DataSnapshot) => boolean | void): boolean { @@ -174,7 +174,7 @@ export class DataSnapshot implements Compat { /** * Returns whether this DataSnapshot has children. - * @return True if the DataSnapshot contains 1 or more child nodes. + * @returns True if the DataSnapshot contains 1 or more child nodes. */ hasChildren(): boolean { validateArgCount('DataSnapshot.hasChildren', 0, 0, arguments.length); @@ -187,7 +187,7 @@ export class DataSnapshot implements Compat { /** * Returns the number of children for this DataSnapshot. - * @return The number of children that this DataSnapshot contains. + * @returns The number of children that this DataSnapshot contains. */ numChildren(): number { validateArgCount('DataSnapshot.numChildren', 0, 0, arguments.length); @@ -195,7 +195,7 @@ export class DataSnapshot implements Compat { } /** - * @return The Firebase reference for the location this snapshot's data came + * @returns The Firebase reference for the location this snapshot's data came * from. */ getRef(): Reference { @@ -472,7 +472,7 @@ export class Query implements Compat { } /** - * @return URL for this location. + * @returns URL for this location. */ toString(): string { validateArgCount('Query.toString', 0, 0, arguments.length); @@ -563,7 +563,7 @@ export class Reference extends Query implements Compat { ); } - /** @return {?string} */ + /** @returns {?string} */ getKey(): string | null { validateArgCount('Reference.key', 0, 0, arguments.length); return this._delegate.key; @@ -577,14 +577,14 @@ export class Reference extends Query implements Compat { return new Reference(this.database, child(this._delegate, pathString)); } - /** @return {?Reference} */ + /** @returns {?Reference} */ getParent(): Reference | null { validateArgCount('Reference.parent', 0, 0, arguments.length); const parent = this._delegate.parent; return parent ? new Reference(this.database, parent) : null; } - /** @return {!Reference} */ + /** @returns {!Reference} */ getRoot(): Reference { validateArgCount('Reference.root', 0, 0, arguments.length); return new Reference(this.database, this._delegate.root); diff --git a/packages/database/src/core/CompoundWrite.ts b/packages/database/src/core/CompoundWrite.ts index dffc92a98f6..f19577bd6e0 100644 --- a/packages/database/src/core/CompoundWrite.ts +++ b/packages/database/src/core/CompoundWrite.ts @@ -87,7 +87,7 @@ export function compoundWriteAddWrites( * * @param compoundWrite The CompoundWrite to remove. * @param path The path at which a write and all deeper writes should be removed - * @return The new CompoundWrite with the removed path + * @returns The new CompoundWrite with the removed path */ export function compoundWriteRemoveWrite( compoundWrite: CompoundWrite, @@ -110,7 +110,7 @@ export function compoundWriteRemoveWrite( * * @param compoundWrite The CompoundWrite to check. * @param path The path to check for - * @return Whether there is a complete write at that path + * @returns Whether there is a complete write at that path */ export function compoundWriteHasCompleteWrite( compoundWrite: CompoundWrite, @@ -125,7 +125,7 @@ export function compoundWriteHasCompleteWrite( * * @param compoundWrite The CompoundWrite to get the node from. * @param path The path to get a complete write - * @return The node if complete at that path, or null otherwise. + * @returns The node if complete at that path, or null otherwise. */ export function compoundWriteGetCompleteNode( compoundWrite: CompoundWrite, @@ -145,7 +145,7 @@ export function compoundWriteGetCompleteNode( * Returns all children that are guaranteed to be a complete overwrite. * * @param compoundWrite The CompoundWrite to get children from. - * @return A list of all complete children. + * @returns A list of all complete children. */ export function compoundWriteGetCompleteChildren( compoundWrite: CompoundWrite @@ -192,7 +192,7 @@ export function compoundWriteChildCompoundWrite( /** * Returns true if this CompoundWrite is empty and therefore does not modify any nodes. - * @return Whether this CompoundWrite is empty + * @returns Whether this CompoundWrite is empty */ export function compoundWriteIsEmpty(compoundWrite: CompoundWrite): boolean { return compoundWrite.writeTree_.isEmpty(); @@ -202,7 +202,7 @@ export function compoundWriteIsEmpty(compoundWrite: CompoundWrite): boolean { * Applies this CompoundWrite to a node. The node is returned with all writes from this CompoundWrite applied to the * node * @param node The node to apply this CompoundWrite to - * @return The node with all writes applied + * @returns The node with all writes applied */ export function compoundWriteApply( compoundWrite: CompoundWrite, diff --git a/packages/database/src/core/Repo.ts b/packages/database/src/core/Repo.ts index ab5ff3f5933..13f3d1db196 100644 --- a/packages/database/src/core/Repo.ts +++ b/packages/database/src/core/Repo.ts @@ -193,7 +193,7 @@ export class Repo { } /** - * @return The URL corresponding to the root of this Firebase. + * @returns The URL corresponding to the root of this Firebase. */ toString(): string { return ( @@ -319,7 +319,7 @@ export function repoStart( } /** - * @return The time in milliseconds, taking the server offset into account if we have one. + * @returns The time in milliseconds, taking the server offset into account if we have one. */ export function repoServerTime(repo: Repo): number { const offsetNode = repo.infoData_.getNode(new Path('.info/serverTimeOffset')); @@ -1147,7 +1147,7 @@ function repoSendTransactionQueue( * is the path at which events need to be raised for. * * @param changedPath The path in mergedData that changed. - * @return The rootmost path that was affected by rerunning transactions. + * @returns The rootmost path that was affected by rerunning transactions. */ function repoRerunTransactions(repo: Repo, changedPath: Path): Path { const rootMostTransactionNode = repoGetAncestorTransactionNode( @@ -1329,7 +1329,7 @@ function repoRerunTransactionQueue( * no pending transactions on any ancestor. * * @param path The location to start at. - * @return The rootmost node with a transaction. + * @returns The rootmost node with a transaction. */ function repoGetAncestorTransactionNode( repo: Repo, @@ -1355,7 +1355,7 @@ function repoGetAncestorTransactionNode( * transactionNode. * * @param transactionNode - * @return The generated queue. + * @returns The generated queue. */ function repoBuildTransactionQueue( repo: Repo, diff --git a/packages/database/src/core/SparseSnapshotTree.ts b/packages/database/src/core/SparseSnapshotTree.ts index 6286ff512cb..27a9be9a85a 100644 --- a/packages/database/src/core/SparseSnapshotTree.ts +++ b/packages/database/src/core/SparseSnapshotTree.ts @@ -39,7 +39,7 @@ export function newSparseSnapshotTree(): SparseSnapshotTree { * Only seems to be used in tests. * * @param path Path to look up snapshot for. - * @return The retrieved node, or null. + * @returns The retrieved node, or null. */ export function sparseSnapshotTreeFind( sparseSnapshotTree: SparseSnapshotTree, @@ -94,7 +94,7 @@ export function sparseSnapshotTreeRemember( * Purge the data at path from the cache. * * @param path Path to look up snapshot for. - * @return True if this node should now be removed. + * @returns True if this node should now be removed. */ export function sparseSnapshotTreeForget( sparseSnapshotTree: SparseSnapshotTree, diff --git a/packages/database/src/core/SyncPoint.ts b/packages/database/src/core/SyncPoint.ts index b001865084f..99c0efc5dd4 100644 --- a/packages/database/src/core/SyncPoint.ts +++ b/packages/database/src/core/SyncPoint.ts @@ -119,7 +119,7 @@ export function syncPointApplyOperation( * @param writesCache * @param serverCache * @param serverCacheComplete - * @return Events to raise. + * @returns Events to raise. */ export function syncPointGetView( syncPoint: SyncPoint, @@ -166,7 +166,7 @@ export function syncPointGetView( * @param writesCache * @param serverCache Complete server cache, if we have it. * @param serverCacheComplete - * @return Events to raise. + * @returns Events to raise. */ export function syncPointAddEventRegistration( syncPoint: SyncPoint, @@ -199,7 +199,7 @@ export function syncPointAddEventRegistration( * * @param eventRegistration If null, remove all callbacks. * @param cancelError If a cancelError is provided, appropriate cancel events will be returned. - * @return removed queries and any cancel events + * @returns removed queries and any cancel events */ export function syncPointRemoveEventRegistration( syncPoint: SyncPoint, @@ -266,7 +266,7 @@ export function syncPointGetQueryViews(syncPoint: SyncPoint): View[] { /** * @param path The path to the desired complete snapshot - * @return A complete cache, if it exists + * @returns A complete cache, if it exists */ export function syncPointGetCompleteServerCache( syncPoint: SyncPoint, diff --git a/packages/database/src/core/SyncTree.ts b/packages/database/src/core/SyncTree.ts index 6d7c0da8526..700a6fe126c 100644 --- a/packages/database/src/core/SyncTree.ts +++ b/packages/database/src/core/SyncTree.ts @@ -160,7 +160,7 @@ export class SyncTree { /** * Apply the data changes for a user-generated set() or transaction() call. * - * @return Events to raise. + * @returns Events to raise. */ export function syncTreeApplyUserOverwrite( syncTree: SyncTree, @@ -191,7 +191,7 @@ export function syncTreeApplyUserOverwrite( /** * Apply the data from a user-generated update() call * - * @return Events to raise. + * @returns Events to raise. */ export function syncTreeApplyUserMerge( syncTree: SyncTree, @@ -214,7 +214,7 @@ export function syncTreeApplyUserMerge( * Acknowledge a pending user write that was previously registered with applyUserOverwrite() or applyUserMerge(). * * @param revert True if the given write failed and needs to be reverted - * @return Events to raise. + * @returns Events to raise. */ export function syncTreeAckUserWrite( syncTree: SyncTree, @@ -248,7 +248,7 @@ export function syncTreeAckUserWrite( /** * Apply new server data for the specified path.. * - * @return Events to raise. + * @returns Events to raise. */ export function syncTreeApplyServerOverwrite( syncTree: SyncTree, @@ -264,7 +264,7 @@ export function syncTreeApplyServerOverwrite( /** * Apply new server data to be merged in at the specified path. * - * @return Events to raise. + * @returns Events to raise. */ export function syncTreeApplyServerMerge( syncTree: SyncTree, @@ -282,7 +282,7 @@ export function syncTreeApplyServerMerge( /** * Apply a listen complete for a query * - * @return Events to raise. + * @returns Events to raise. */ export function syncTreeApplyListenComplete( syncTree: SyncTree, @@ -297,7 +297,7 @@ export function syncTreeApplyListenComplete( /** * Apply a listen complete for a tagged query * - * @return Events to raise. + * @returns Events to raise. */ export function syncTreeApplyTaggedListenComplete( syncTree: SyncTree, @@ -329,7 +329,7 @@ export function syncTreeApplyTaggedListenComplete( * * @param eventRegistration If null, all callbacks are removed. * @param cancelError If a cancelError is provided, appropriate cancel events will be returned. - * @return Cancel events, if cancelError was provided. + * @returns Cancel events, if cancelError was provided. */ export function syncTreeRemoveEventRegistration( syncTree: SyncTree, @@ -437,7 +437,7 @@ export function syncTreeRemoveEventRegistration( /** * Apply new server data for the specified tagged query. * - * @return Events to raise. + * @returns Events to raise. */ export function syncTreeApplyTaggedQueryOverwrite( syncTree: SyncTree, @@ -466,7 +466,7 @@ export function syncTreeApplyTaggedQueryOverwrite( /** * Apply server data to be merged in for the specified tagged query. * - * @return Events to raise. + * @returns Events to raise. */ export function syncTreeApplyTaggedQueryMerge( syncTree: SyncTree, @@ -496,7 +496,7 @@ export function syncTreeApplyTaggedQueryMerge( /** * Add an event callback for the specified query. * - * @return Events to raise. + * @returns Events to raise. */ export function syncTreeAddEventRegistration( syncTree: SyncTree, @@ -901,7 +901,7 @@ function syncTreeCollectDistinctViewsForSubTree_( /** * Normalizes a query to a query we send the server for listening * - * @return The normalized query + * @returns The normalized query */ function syncTreeQueryForListening_(query: QueryContext): QueryContext { if (query._queryParams.loadsAllData() && !query._queryParams.isDefault()) { @@ -937,7 +937,7 @@ function syncTreeGetNextQueryTag_(): number { /** * For a given new listen, manage the de-duplication of outstanding subscriptions. * - * @return This method can return events to support synchronous data sources + * @returns This method can return events to support synchronous data sources */ function syncTreeSetupListener_( syncTree: SyncTree, diff --git a/packages/database/src/core/WriteTree.ts b/packages/database/src/core/WriteTree.ts index b6e9972aba4..5003dad68a9 100644 --- a/packages/database/src/core/WriteTree.ts +++ b/packages/database/src/core/WriteTree.ts @@ -150,7 +150,7 @@ export function writeTreeGetWrite( * Remove a write (either an overwrite or merge) that has been successfully acknowledge by the server. Recalculates * the tree if necessary. We return true if it may have been visible, meaning views need to reevaluate. * - * @return true if the write may have been visible (meaning we'll need to reevaluate / raise + * @returns true if the write may have been visible (meaning we'll need to reevaluate / raise * events as a result). */ export function writeTreeRemoveWrite( diff --git a/packages/database/src/core/snap/LeafNode.ts b/packages/database/src/core/snap/LeafNode.ts index 9e244e28fd6..e280de54cf7 100644 --- a/packages/database/src/core/snap/LeafNode.ts +++ b/packages/database/src/core/snap/LeafNode.ts @@ -212,7 +212,7 @@ export class LeafNode implements Node { /** * Returns the value of the leaf node. - * @return The value of the node. + * @returns The value of the node. */ getValue(): Indexable | string | number | boolean { return this.value_; diff --git a/packages/database/src/core/snap/Node.ts b/packages/database/src/core/snap/Node.ts index eeaa38b5e0d..0bf423e8af6 100644 --- a/packages/database/src/core/snap/Node.ts +++ b/packages/database/src/core/snap/Node.ts @@ -28,34 +28,34 @@ import { Index } from './indexes/Index'; export interface Node { /** * Whether this node is a leaf node. - * @return Whether this is a leaf node. + * @returns Whether this is a leaf node. */ isLeafNode(): boolean; /** * Gets the priority of the node. - * @return The priority of the node. + * @returns The priority of the node. */ getPriority(): Node; /** * Returns a duplicate node with the new priority. * @param newPriorityNode New priority to set for the node. - * @return Node with new priority. + * @returns Node with new priority. */ updatePriority(newPriorityNode: Node): Node; /** * Returns the specified immediate child, or null if it doesn't exist. * @param childName The name of the child to retrieve. - * @return The retrieved child, or an empty node. + * @returns The retrieved child, or an empty node. */ getImmediateChild(childName: string): Node; /** * Returns a child by path, or null if it doesn't exist. * @param path The path of the child to retrieve. - * @return The retrieved child or an empty node. + * @returns The retrieved child or an empty node. */ getChild(path: Path): Node; @@ -64,7 +64,7 @@ export interface Node { * @param childName The name of the child to find the predecessor of. * @param childNode The node to find the predecessor of. * @param index The index to use to determine the predecessor - * @return The name of the predecessor child, or null if childNode is the first child. + * @returns The name of the predecessor child, or null if childNode is the first child. */ getPredecessorChildName( childName: string, @@ -77,7 +77,7 @@ export interface Node { * Any value in the node will be removed. * @param childName The name of the child to update. * @param newChildNode The new child node - * @return The updated node. + * @returns The updated node. */ updateImmediateChild(childName: string, newChildNode: Node): Node; @@ -86,7 +86,7 @@ export interface Node { * be removed. * @param path The path of the child to update. * @param newChildNode The new child node, which may be an empty node - * @return The updated node. + * @returns The updated node. */ updateChild(path: Path, newChildNode: Node): Node; @@ -96,12 +96,12 @@ export interface Node { hasChild(childName: string): boolean; /** - * @return True if this node has no value or children. + * @returns True if this node has no value or children. */ isEmpty(): boolean; /** - * @return The number of children of this node. + * @returns The number of children of this node. */ numChildren(): number; @@ -109,34 +109,34 @@ export interface Node { * Calls action for each child. * @param action Action to be called for * each child. It's passed the child name and the child node. - * @return The first truthy value return by action, or the last falsey one + * @returns The first truthy value return by action, or the last falsey one */ forEachChild(index: Index, action: (a: string, b: Node) => void): unknown; /** * @param exportFormat True for export format (also wire protocol format). - * @return Value of this node as JSON. + * @returns Value of this node as JSON. */ val(exportFormat?: boolean): unknown; /** - * @return hash representing the node contents. + * @returns hash representing the node contents. */ hash(): string; /** * @param other Another node - * @return -1 for less than, 0 for equal, 1 for greater than other + * @returns -1 for less than, 0 for equal, 1 for greater than other */ compareTo(other: Node): number; /** - * @return Whether or not this snapshot equals other + * @returns Whether or not this snapshot equals other */ equals(other: Node): boolean; /** - * @return This node, with the specified index now available + * @returns This node, with the specified index now available */ withIndex(indexDefinition: Index): Node; diff --git a/packages/database/src/core/snap/indexes/Index.ts b/packages/database/src/core/snap/indexes/Index.ts index 8c768b64926..ee4f796582f 100644 --- a/packages/database/src/core/snap/indexes/Index.ts +++ b/packages/database/src/core/snap/indexes/Index.ts @@ -25,7 +25,7 @@ export abstract class Index { abstract isDefinedOn(node: Node): boolean; /** - * @return A standalone comparison function for + * @returns A standalone comparison function for * this index */ getCompare(): Comparator { @@ -37,7 +37,7 @@ export abstract class Index { * it's possible that the changes are isolated to parts of the snapshot that are not indexed. * * - * @return True if the portion of the snapshot being indexed changed between oldNode and newNode + * @returns True if the portion of the snapshot being indexed changed between oldNode and newNode */ indexedValueChanged(oldNode: Node, newNode: Node): boolean { const oldWrapped = new NamedNode(MIN_NAME, oldNode); @@ -46,7 +46,7 @@ export abstract class Index { } /** - * @return a node wrapper that will sort equal to or less than + * @returns a node wrapper that will sort equal to or less than * any other node wrapper, using this index */ minPost(): NamedNode { @@ -55,7 +55,7 @@ export abstract class Index { } /** - * @return a node wrapper that will sort greater than or equal to + * @returns a node wrapper that will sort greater than or equal to * any other node wrapper, using this index */ abstract maxPost(): NamedNode; @@ -63,7 +63,7 @@ export abstract class Index { abstract makePost(indexValue: unknown, name: string): NamedNode; /** - * @return String representation for inclusion in a query spec + * @returns String representation for inclusion in a query spec */ abstract toString(): string; } diff --git a/packages/database/src/core/snap/indexes/KeyIndex.ts b/packages/database/src/core/snap/indexes/KeyIndex.ts index c3c47aa6cc4..05d4e7e79ac 100644 --- a/packages/database/src/core/snap/indexes/KeyIndex.ts +++ b/packages/database/src/core/snap/indexes/KeyIndex.ts @@ -84,7 +84,7 @@ export class KeyIndex extends Index { } /** - * @return String representation for inclusion in a query spec + * @returns String representation for inclusion in a query spec */ toString(): string { return '.key'; diff --git a/packages/database/src/core/snap/indexes/PriorityIndex.ts b/packages/database/src/core/snap/indexes/PriorityIndex.ts index 5b9e7d3d76c..117abd2e60d 100644 --- a/packages/database/src/core/snap/indexes/PriorityIndex.ts +++ b/packages/database/src/core/snap/indexes/PriorityIndex.ts @@ -82,7 +82,7 @@ export class PriorityIndex extends Index { } /** - * @return String representation for inclusion in a query spec + * @returns String representation for inclusion in a query spec */ toString(): string { return '.priority'; diff --git a/packages/database/src/core/snap/indexes/ValueIndex.ts b/packages/database/src/core/snap/indexes/ValueIndex.ts index 8f87aa10101..576bc84f961 100644 --- a/packages/database/src/core/snap/indexes/ValueIndex.ts +++ b/packages/database/src/core/snap/indexes/ValueIndex.ts @@ -70,7 +70,7 @@ export class ValueIndex extends Index { } /** - * @return String representation for inclusion in a query spec + * @returns String representation for inclusion in a query spec */ toString(): string { return '.value'; diff --git a/packages/database/src/core/storage/DOMStorageWrapper.ts b/packages/database/src/core/storage/DOMStorageWrapper.ts index 5f3fe008fa8..8d31ba5df53 100644 --- a/packages/database/src/core/storage/DOMStorageWrapper.ts +++ b/packages/database/src/core/storage/DOMStorageWrapper.ts @@ -48,7 +48,7 @@ export class DOMStorageWrapper { } /** - * @return The value that was stored under this key, or null + * @returns The value that was stored under this key, or null */ get(key: string): unknown { const storedVal = this.domStorage_.getItem(this.prefixedName_(key)); diff --git a/packages/database/src/core/storage/storage.ts b/packages/database/src/core/storage/storage.ts index d590146948e..99d62a82f95 100644 --- a/packages/database/src/core/storage/storage.ts +++ b/packages/database/src/core/storage/storage.ts @@ -27,7 +27,7 @@ declare const window: Window; * * @param domStorageName Name of the underlying storage object * (e.g. 'localStorage' or 'sessionStorage'). - * @return Turning off type information until a common interface is defined. + * @returns Turning off type information until a common interface is defined. */ const createStoragefor = function ( domStorageName: string diff --git a/packages/database/src/core/util/EventEmitter.ts b/packages/database/src/core/util/EventEmitter.ts index 8be5e6cab55..0c87df607b4 100644 --- a/packages/database/src/core/util/EventEmitter.ts +++ b/packages/database/src/core/util/EventEmitter.ts @@ -40,7 +40,7 @@ export abstract class EventEmitter { * To be overridden by derived classes in order to fire an initial event when * somebody subscribes for data. * - * @return {Array.<*>} Array of parameters to trigger initial event with. + * @returns {Array.<*>} Array of parameters to trigger initial event with. */ abstract getInitialEvent(eventType: string): unknown[]; diff --git a/packages/database/src/core/util/ImmutableTree.ts b/packages/database/src/core/util/ImmutableTree.ts index 435549293c2..5191150588d 100644 --- a/packages/database/src/core/util/ImmutableTree.ts +++ b/packages/database/src/core/util/ImmutableTree.ts @@ -122,7 +122,7 @@ export class ImmutableTree { } /** - * @return The subtree at the given path + * @returns The subtree at the given path */ subtree(relativePath: Path): ImmutableTree { if (pathIsEmpty(relativePath)) { @@ -143,7 +143,7 @@ export class ImmutableTree { * * @param relativePath Path to set value at. * @param toSet Value to set. - * @return Resulting tree. + * @returns Resulting tree. */ set(relativePath: Path, toSet: T | null): ImmutableTree { if (pathIsEmpty(relativePath)) { @@ -161,7 +161,7 @@ export class ImmutableTree { * Removes the value at the specified path. * * @param relativePath Path to value to remove. - * @return Resulting tree. + * @returns Resulting tree. */ remove(relativePath: Path): ImmutableTree { if (pathIsEmpty(relativePath)) { @@ -196,7 +196,7 @@ export class ImmutableTree { * Gets a value from the tree. * * @param relativePath Path to get value for. - * @return Value at path, or null. + * @returns Value at path, or null. */ get(relativePath: Path): T | null { if (pathIsEmpty(relativePath)) { @@ -217,7 +217,7 @@ export class ImmutableTree { * * @param relativePath Path to replace subtree for. * @param newTree New tree. - * @return Resulting tree. + * @returns Resulting tree. */ setTree(relativePath: Path, newTree: ImmutableTree): ImmutableTree { if (pathIsEmpty(relativePath)) { diff --git a/packages/database/src/core/util/Path.ts b/packages/database/src/core/util/Path.ts index f4d1d3f25c2..b409f9783bd 100644 --- a/packages/database/src/core/util/Path.ts +++ b/packages/database/src/core/util/Path.ts @@ -85,7 +85,7 @@ export function pathGetFront(path: Path): string | null { } /** - * @return The number of segments in this path + * @returns The number of segments in this path */ export function pathGetLength(path: Path): number { return path.pieces_.length - path.pieceNum_; @@ -162,14 +162,14 @@ export function pathChild(path: Path, childPathObj: string | Path): Path { } /** - * @return True if there are no segments in this path + * @returns True if there are no segments in this path */ export function pathIsEmpty(path: Path): boolean { return path.pieceNum_ >= path.pieces_.length; } /** - * @return The path from outerPath to innerPath + * @returns The path from outerPath to innerPath */ export function newRelativePath(outerPath: Path, innerPath: Path): Path { const outer = pathGetFront(outerPath), @@ -191,7 +191,7 @@ export function newRelativePath(outerPath: Path, innerPath: Path): Path { } /** - * @return -1, 0, 1 if left is less, equal, or greater than the right. + * @returns -1, 0, 1 if left is less, equal, or greater than the right. */ export function pathCompare(left: Path, right: Path): number { const leftKeys = pathSlice(left, 0); @@ -209,7 +209,7 @@ export function pathCompare(left: Path, right: Path): number { } /** - * @return true if paths are the same. + * @returns true if paths are the same. */ export function pathEquals(path: Path, other: Path): boolean { if (pathGetLength(path) !== pathGetLength(other)) { @@ -230,7 +230,7 @@ export function pathEquals(path: Path, other: Path): boolean { } /** - * @return True if this path is a parent (or the same as) other + * @returns True if this path is a parent (or the same as) other */ export function pathContains(path: Path, other: Path): boolean { let i = path.pieceNum_; diff --git a/packages/database/src/core/util/SortedMap.ts b/packages/database/src/core/util/SortedMap.ts index 6b8bf0aeb02..38328d2b043 100644 --- a/packages/database/src/core/util/SortedMap.ts +++ b/packages/database/src/core/util/SortedMap.ts @@ -175,7 +175,7 @@ export class LLRBNode { * @param color New color for the node, or null. * @param left New left child for the node, or null. * @param right New right child for the node, or null. - * @return The node copy. + * @returns The node copy. */ copy( key: K | null, @@ -194,14 +194,14 @@ export class LLRBNode { } /** - * @return The total number of nodes in the tree. + * @returns The total number of nodes in the tree. */ count(): number { return this.left.count() + 1 + this.right.count(); } /** - * @return True if the tree is empty. + * @returns True if the tree is empty. */ isEmpty(): boolean { return false; @@ -213,7 +213,7 @@ export class LLRBNode { * * @param action Callback function to be called for each * node. If it returns true, traversal is aborted. - * @return The first truthy value returned by action, or the last falsey + * @returns The first truthy value returned by action, or the last falsey * value returned by action */ inorderTraversal(action: (k: K, v: V) => unknown): boolean { @@ -230,7 +230,7 @@ export class LLRBNode { * * @param action Callback function to be called for each * node. If it returns true, traversal is aborted. - * @return True if traversal was aborted. + * @returns True if traversal was aborted. */ reverseTraversal(action: (k: K, v: V) => void): boolean { return ( @@ -241,7 +241,7 @@ export class LLRBNode { } /** - * @return The minimum node in the tree. + * @returns The minimum node in the tree. */ private min_(): LLRBNode { if (this.left.isEmpty()) { @@ -252,14 +252,14 @@ export class LLRBNode { } /** - * @return The maximum key in the tree. + * @returns The maximum key in the tree. */ minKey(): K { return this.min_().key; } /** - * @return The maximum key in the tree. + * @returns The maximum key in the tree. */ maxKey(): K { if (this.right.isEmpty()) { @@ -273,7 +273,7 @@ export class LLRBNode { * @param key Key to insert. * @param value Value to insert. * @param comparator Comparator. - * @return New tree, with the key/value added. + * @returns New tree, with the key/value added. */ insert(key: K, value: V, comparator: Comparator): LLRBNode { let n: LLRBNode = this; @@ -295,7 +295,7 @@ export class LLRBNode { } /** - * @return New tree, with the minimum key removed. + * @returns New tree, with the minimum key removed. */ private removeMin_(): LLRBNode | LLRBEmptyNode { if (this.left.isEmpty()) { @@ -312,7 +312,7 @@ export class LLRBNode { /** * @param key The key of the item to remove. * @param comparator Comparator. - * @return New tree, with the specified item removed. + * @returns New tree, with the specified item removed. */ remove( key: K, @@ -352,14 +352,14 @@ export class LLRBNode { } /** - * @return Whether this is a RED node. + * @returns Whether this is a RED node. */ isRed_(): boolean { return this.color; } /** - * @return New tree after performing any needed rotations. + * @returns New tree after performing any needed rotations. */ private fixUp_(): LLRBNode { let n: LLRBNode = this; @@ -376,7 +376,7 @@ export class LLRBNode { } /** - * @return New tree, after moveRedLeft. + * @returns New tree, after moveRedLeft. */ private moveRedLeft_(): LLRBNode { let n = this.colorFlip_(); @@ -395,7 +395,7 @@ export class LLRBNode { } /** - * @return New tree, after moveRedRight. + * @returns New tree, after moveRedRight. */ private moveRedRight_(): LLRBNode { let n = this.colorFlip_(); @@ -407,7 +407,7 @@ export class LLRBNode { } /** - * @return New tree, after rotateLeft. + * @returns New tree, after rotateLeft. */ private rotateLeft_(): LLRBNode { const nl = this.copy(null, null, LLRBNode.RED, null, this.right.left); @@ -415,7 +415,7 @@ export class LLRBNode { } /** - * @return New tree, after rotateRight. + * @returns New tree, after rotateRight. */ private rotateRight_(): LLRBNode { const nr = this.copy(null, null, LLRBNode.RED, this.left.right, null); @@ -423,7 +423,7 @@ export class LLRBNode { } /** - * @return Newt ree, after colorFlip. + * @returns Newt ree, after colorFlip. */ private colorFlip_(): LLRBNode { const left = this.left.copy(null, null, !this.left.color, null, null); @@ -434,7 +434,7 @@ export class LLRBNode { /** * For testing. * - * @return True if all is well. + * @returns True if all is well. */ private checkMaxDepth_(): boolean { const blackDepth = this.check_(); @@ -474,7 +474,7 @@ export class LLRBEmptyNode { /** * Returns a copy of the current node. * - * @return The node copy. + * @returns The node copy. */ copy( key: K | null, @@ -492,7 +492,7 @@ export class LLRBEmptyNode { * @param key Key to be added. * @param value Value to be added. * @param comparator Comparator. - * @return New tree, with item added. + * @returns New tree, with item added. */ insert(key: K, value: V, comparator: Comparator): LLRBNode { return new LLRBNode(key, value, null); @@ -503,21 +503,21 @@ export class LLRBEmptyNode { * * @param key The key to remove. * @param comparator Comparator. - * @return New tree, with item removed. + * @returns New tree, with item removed. */ remove(key: K, comparator: Comparator): LLRBEmptyNode { return this; } /** - * @return The total number of nodes in the tree. + * @returns The total number of nodes in the tree. */ count(): number { return 0; } /** - * @return True if the tree is empty. + * @returns True if the tree is empty. */ isEmpty(): boolean { return true; @@ -529,7 +529,7 @@ export class LLRBEmptyNode { * * @param action Callback function to be called for each * node. If it returns true, traversal is aborted. - * @return True if traversal was aborted. + * @returns True if traversal was aborted. */ inorderTraversal(action: (k: K, v: V) => unknown): boolean { return false; @@ -541,7 +541,7 @@ export class LLRBEmptyNode { * * @param action Callback function to be called for each * node. If it returns true, traversal is aborted. - * @return True if traversal was aborted. + * @returns True if traversal was aborted. */ reverseTraversal(action: (k: K, v: V) => void): boolean { return false; @@ -560,7 +560,7 @@ export class LLRBEmptyNode { } /** - * @return Whether this node is red. + * @returns Whether this node is red. */ isRed_() { return false; @@ -594,7 +594,7 @@ export class SortedMap { * * @param key Key to be added. * @param value Value to be added. - * @return New map, with item added. + * @returns New map, with item added. */ insert(key: K, value: V): SortedMap { return new SortedMap( @@ -609,7 +609,7 @@ export class SortedMap { * Returns a copy of the map, with the specified key removed. * * @param key The key to remove. - * @return New map, with item removed. + * @returns New map, with item removed. */ remove(key: K): SortedMap { return new SortedMap( @@ -624,7 +624,7 @@ export class SortedMap { * Returns the value of the node with the given key, or null. * * @param key The key to look up. - * @return The value of the node with the given key, or null if the + * @returns The value of the node with the given key, or null if the * key doesn't exist. */ get(key: K): V | null { @@ -646,7 +646,7 @@ export class SortedMap { /** * Returns the key of the item *before* the specified key, or null if key is the first item. * @param key The key to find the predecessor of - * @return The predecessor key. + * @returns The predecessor key. */ getPredecessorKey(key: K): K | null { let cmp, @@ -680,28 +680,28 @@ export class SortedMap { } /** - * @return True if the map is empty. + * @returns True if the map is empty. */ isEmpty(): boolean { return this.root_.isEmpty(); } /** - * @return The total number of nodes in the map. + * @returns The total number of nodes in the map. */ count(): number { return this.root_.count(); } /** - * @return The minimum key in the map. + * @returns The minimum key in the map. */ minKey(): K | null { return this.root_.minKey(); } /** - * @return The maximum key in the map. + * @returns The maximum key in the map. */ maxKey(): K | null { return this.root_.maxKey(); @@ -713,7 +713,7 @@ export class SortedMap { * * @param action Callback function to be called * for each key/value pair. If action returns true, traversal is aborted. - * @return The first truthy value returned by action, or the last falsey + * @returns The first truthy value returned by action, or the last falsey * value returned by action */ inorderTraversal(action: (k: K, v: V) => unknown): boolean { @@ -726,7 +726,7 @@ export class SortedMap { * * @param action Callback function to be called * for each key/value pair. If action returns true, traversal is aborted. - * @return True if the traversal was aborted. + * @returns True if the traversal was aborted. */ reverseTraversal(action: (k: K, v: V) => void): boolean { return this.root_.reverseTraversal(action); @@ -734,7 +734,7 @@ export class SortedMap { /** * Returns an iterator over the SortedMap. - * @return The iterator. + * @returns The iterator. */ getIterator( resultGenerator?: (k: K, v: V) => T diff --git a/packages/database/src/core/util/Tree.ts b/packages/database/src/core/util/Tree.ts index 4b1ba798341..fd8f8ebcb52 100644 --- a/packages/database/src/core/util/Tree.ts +++ b/packages/database/src/core/util/Tree.ts @@ -53,7 +53,7 @@ export class Tree { * Returns a sub-Tree for the given path. * * @param pathObj Path to look up. - * @return Tree for path. + * @returns Tree for path. */ export function treeSubTree(tree: Tree, pathObj: string | Path): Tree { // TODO: Require pathObj to be Path? @@ -76,7 +76,7 @@ export function treeSubTree(tree: Tree, pathObj: string | Path): Tree { /** * Returns the data associated with this tree node. * - * @return The data or null if no data exists. + * @returns The data or null if no data exists. */ export function treeGetValue(tree: Tree): T | undefined { return tree.node.value; @@ -93,14 +93,14 @@ export function treeSetValue(tree: Tree, value: T | undefined): void { } /** - * @return Whether the tree has any children. + * @returns Whether the tree has any children. */ export function treeHasChildren(tree: Tree): boolean { return tree.node.childCount > 0; } /** - * @return Whethe rthe tree is empty (no value or children). + * @returns Whethe rthe tree is empty (no value or children). */ export function treeIsEmpty(tree: Tree): boolean { return treeGetValue(tree) === undefined && !treeHasChildren(tree); @@ -154,7 +154,7 @@ export function treeForEachDescendant( * @param action Action to be called on each parent; return * true to abort. * @param includeSelf Whether to call action on this node as well. - * @return true if the action callback returned true. + * @returns true if the action callback returned true. */ export function treeForEachAncestor( tree: Tree, @@ -192,7 +192,7 @@ export function treeForEachImmediateDescendantWithValue( } /** - * @return The path of this tree node, as a Path. + * @returns The path of this tree node, as a Path. */ export function treeGetPath(tree: Tree) { return new Path( diff --git a/packages/database/src/core/util/libs/parser.ts b/packages/database/src/core/util/libs/parser.ts index 69c3b4e1db7..e4f006a635a 100644 --- a/packages/database/src/core/util/libs/parser.ts +++ b/packages/database/src/core/util/libs/parser.ts @@ -35,7 +35,7 @@ function decodePath(pathString: string): string { } /** - * @return key value hash + * @returns key value hash */ function decodeQuery(queryString: string): { [key: string]: string } { const results = {}; diff --git a/packages/database/src/core/util/util.ts b/packages/database/src/core/util/util.ts index 4208b0529d9..c63010d15b8 100644 --- a/packages/database/src/core/util/util.ts +++ b/packages/database/src/core/util/util.ts @@ -47,7 +47,7 @@ export const LUIDGenerator: () => number = (function () { /** * Sha1 hash of the input string * @param str The string to hash - * @return {!string} The resulting hash + * @returns {!string} The resulting hash */ export const sha1 = function (str: string): string { const utf8Bytes = stringToByteArray(str); @@ -277,7 +277,7 @@ export const nameCompare = function (a: string, b: string): number { }; /** - * @return {!number} comparison result. + * @returns {!number} comparison result. */ export const stringCompare = function (a: string, b: string): number { if (a === b) { @@ -333,7 +333,7 @@ export const ObjectToUniqueKey = function (obj: unknown): string { * Splits a string into a number of smaller segments of maximum size * @param str The string * @param segsize The maximum number of chars in the string. - * @return The string, split into appropriately-sized chunks + * @returns The string, split into appropriately-sized chunks */ export const splitStringBySize = function ( str: string, @@ -573,7 +573,7 @@ export const callUserCallback = function ( }; /** - * @return {boolean} true if we think we're currently being crawled. + * @returns {boolean} true if we think we're currently being crawled. */ export const beingCrawled = function (): boolean { const userAgent = @@ -611,7 +611,7 @@ export const exportPropGetter = function ( * * @param fn Function to run. * @param time Milliseconds to wait before running. - * @return The setTimeout() return value. + * @returns The setTimeout() return value. */ export const setTimeoutNonBlocking = function ( fn: () => void, diff --git a/packages/database/src/core/view/QueryParams.ts b/packages/database/src/core/view/QueryParams.ts index 33477032fb0..a8443e90521 100644 --- a/packages/database/src/core/view/QueryParams.ts +++ b/packages/database/src/core/view/QueryParams.ts @@ -93,7 +93,7 @@ export class QueryParams { } /** - * @return True if it would return from left. + * @returns True if it would return from left. */ isViewFromLeft(): boolean { if (this.viewFrom_ === '') { @@ -158,7 +158,7 @@ export class QueryParams { } /** - * @return True if a limit has been set and it has been explicitly anchored + * @returns True if a limit has been set and it has been explicitly anchored */ hasAnchoredLimit(): boolean { return this.limitSet_ && this.viewFrom_ !== ''; @@ -347,7 +347,7 @@ export function queryParamsOrderBy( /** * Returns a set of REST query string parameters representing this query. * - * @return query string parameters + * @returns query string parameters */ export function queryParamsToRestQueryStringParameters( queryParams: QueryParams diff --git a/packages/database/src/core/view/View.ts b/packages/database/src/core/view/View.ts index 1c5804a0eb1..032fd1daaa4 100644 --- a/packages/database/src/core/view/View.ts +++ b/packages/database/src/core/view/View.ts @@ -145,7 +145,7 @@ export function viewAddEventRegistration( /** * @param eventRegistration If null, remove all callbacks. * @param cancelError If a cancelError is provided, appropriate cancel events will be returned. - * @return Cancel events, if cancelError was provided. + * @returns Cancel events, if cancelError was provided. */ export function viewRemoveEventRegistration( view: View, diff --git a/packages/database/src/exp/Database.ts b/packages/database/src/exp/Database.ts index 78aa81fae2e..557840cc004 100644 --- a/packages/database/src/exp/Database.ts +++ b/packages/database/src/exp/Database.ts @@ -163,7 +163,7 @@ function repoManagerDeleteRepo(repo: Repo, appName: string): void { * provided app. * * @param repoInfo The metadata about the Repo - * @return The Repo object for the specified server / repoName. + * @returns The Repo object for the specified server / repoName. */ function repoManagerCreateRepo( repoInfo: RepoInfo, diff --git a/packages/database/src/exp/OnDisconnect.ts b/packages/database/src/exp/OnDisconnect.ts index 7312cde802a..cf7998cc2bd 100644 --- a/packages/database/src/exp/OnDisconnect.ts +++ b/packages/database/src/exp/OnDisconnect.ts @@ -64,7 +64,7 @@ export class OnDisconnect { * parent location, the write at this location will be canceled, though writes * to sibling locations will still occur. * - * @return Resolves when synchronization to the server is complete. + * @returns Resolves when synchronization to the server is complete. */ cancel(): Promise { const deferred = new Deferred(); @@ -80,7 +80,7 @@ export class OnDisconnect { * Ensures the data at this location is deleted when the client is disconnected * (due to closing the browser, navigating to a new page, or network issues). * - * @return Resolves when synchronization to the server is complete. + * @returns Resolves when synchronization to the server is complete. */ remove(): Promise { validateWritablePath('OnDisconnect.remove', this._path); @@ -111,7 +111,7 @@ export class OnDisconnect { * * @param value - The value to be written to this location on disconnect (can * be an object, array, string, number, boolean, or null). - * @return Resolves when synchronization to the Database is complete. + * @returns Resolves when synchronization to the Database is complete. */ set(value: unknown): Promise { validateWritablePath('OnDisconnect.set', this._path); @@ -134,7 +134,7 @@ export class OnDisconnect { * @param value - The value to be written to this location on disconnect (can * be an object, array, string, number, boolean, or null). * @param priority - The priority to be written (string, number, or null). - * @return Resolves when synchronization to the Database is complete. + * @returns Resolves when synchronization to the Database is complete. */ setWithPriority( value: unknown, @@ -174,7 +174,7 @@ export class OnDisconnect { * all the child properties at the current location). * * @param values Object containing multiple values. - * @return Resolves when synchronization to the Database is complete. + * @returns Resolves when synchronization to the Database is complete. */ update(values: Indexable): Promise { validateWritablePath('OnDisconnect.update', this._path); diff --git a/packages/database/src/exp/Reference.ts b/packages/database/src/exp/Reference.ts index 4c95bc3a4df..6598f983c74 100644 --- a/packages/database/src/exp/Reference.ts +++ b/packages/database/src/exp/Reference.ts @@ -53,14 +53,14 @@ export interface Query extends QueryContext { * starting and ending points. * * @param other - The query to compare against. - * @return Whether or not the current and provided queries are equivalent. + * @returns Whether or not the current and provided queries are equivalent. */ isEqual(other: Query | null): boolean; /** * Returns a JSON-serializable representation of this object. * - * @return A JSON-serializable representation of this object. + * @returns A JSON-serializable representation of this object. */ toJSON(): string; @@ -75,7 +75,7 @@ export interface Query extends QueryContext { * JSON-formatted data. If the location is secured (that is, not publicly * readable), you will get a permission-denied error. * - * @return The absolute URL for this location. + * @returns The absolute URL for this location. */ toString(): string; } diff --git a/packages/database/src/exp/Reference_impl.ts b/packages/database/src/exp/Reference_impl.ts index 1b0f8f9e85b..d29628bd5e4 100644 --- a/packages/database/src/exp/Reference_impl.ts +++ b/packages/database/src/exp/Reference_impl.ts @@ -359,7 +359,7 @@ export class DataSnapshot { * The `exportVal()` method is similar to `val()`, except priority information * is included (if available), making it suitable for backing up your data. * - * @return The DataSnapshot's contents as a JavaScript value (Object, + * @returns The DataSnapshot's contents as a JavaScript value (Object, * Array, string, number, boolean, or `null`). */ // eslint-disable-next-line @typescript-eslint/no-explicit-any @@ -382,7 +382,7 @@ export class DataSnapshot { * * @param action - A function that will be called for each child DataSnapshot. * The callback can return true to cancel further enumeration. - * @return true if enumeration was canceled due to your callback returning + * @returns true if enumeration was canceled due to your callback returning * true. */ forEach(action: (child: DataSnapshot) => boolean | void): boolean { @@ -403,7 +403,7 @@ export class DataSnapshot { * Returns true if the specified child path has (non-null) data. * * @param path - A relative path to the location of a potential child. - * @return `true` if data exists at the specified child path; else + * @returns `true` if data exists at the specified child path; else * `false`. */ hasChild(path: string): boolean { @@ -421,7 +421,7 @@ export class DataSnapshot { * retrieved with `val()`) or it is empty (in which case, `val()` will return * `null`). * - * @return true if this snapshot has any children; else false. + * @returns true if this snapshot has any children; else false. */ hasChildren(): boolean { if (this._node.isLeafNode()) { @@ -446,7 +446,7 @@ export class DataSnapshot { * also return null, indicating that the `DataSnapshot` is empty (contains no * data). * - * @return The DataSnapshot's contents as a JavaScript value (Object, + * @returns The DataSnapshot's contents as a JavaScript value (Object, * Array, string, number, boolean, or `null`). */ // eslint-disable-next-line @typescript-eslint/no-explicit-any @@ -464,7 +464,7 @@ export class DataSnapshot { * @param path - Optional path representing the location the returned * `Reference` will point. If not provided, the returned `Reference` will * point to the root of the Database. - * @return If a path is provided, a `Reference` + * @returns If a path is provided, a `Reference` * pointing to the provided path. Otherwise, a `Reference` pointing to the * root of the Database. */ @@ -487,7 +487,7 @@ export function ref(db: FirebaseDatabase, path?: string): ReferenceImpl { * @param db - The database instance to obtain a reference for. * @param url - The Firebase URL at which the returned `Reference` will * point. - * @return A `Reference` pointing to the provided + * @returns A `Reference` pointing to the provided * Firebase URL. */ export function refFromURL(db: FirebaseDatabase, url: string): ReferenceImpl { @@ -524,7 +524,7 @@ export function refFromURL(db: FirebaseDatabase, url: string): ReferenceImpl { * @param parent - The parent location. * @param path - A relative path from this location to the desired child * location. - * @return The specified child location. + * @returns The specified child location. */ export function child(parent: Reference, path: string): ReferenceImpl { parent = getModularInstance(parent); @@ -577,7 +577,7 @@ export interface ThenableReferenceImpl * * @param parent - The parent location. * @param value - Optional value to be written at the generated location. - * @return Combined `Promise` and `Reference`; resolves when write is complete, + * @returns Combined `Promise` and `Reference`; resolves when write is complete, * but can be used immediately as the `Reference` to the child location. */ export function push( @@ -623,7 +623,7 @@ export function push( * asynchronously after synchronization has finished. * * @param ref - The location to remove. - * @return Resolves when remove on server is complete. + * @returns Resolves when remove on server is complete. */ export function remove(ref: Reference): Promise { validateWritablePath('remove', ref._path); @@ -657,7 +657,7 @@ export function remove(ref: Reference): Promise { * @param ref - The location to write to. * @param value - The value to be written (string, number, boolean, object, * array, or null). - * @return Resolves when write to server is complete. + * @returns Resolves when write to server is complete. */ export function set(ref: Reference, value: unknown): Promise { ref = getModularInstance(ref); @@ -684,7 +684,7 @@ export function set(ref: Reference, value: unknown): Promise { * * @param ref - The location to write to. * @param priority - The priority to be written (string, number, or null). - * @return Resolves when write to server is complete. + * @returns Resolves when write to server is complete. */ export function setPriority( ref: Reference, @@ -717,7 +717,7 @@ export function setPriority( * @param value - The value to be written (string, number, boolean, object, * array, or null). * @param priority - The priority to be written (string, number, or null). - * @return Resolves when write to server is complete. + * @returns Resolves when write to server is complete. */ export function setWithPriority( ref: Reference, @@ -776,7 +776,7 @@ export function setWithPriority( * * @param ref - The location to write to. * @param values - Object containing multiple values. - * @return Resolves when update on server is complete. + * @returns Resolves when update on server is complete. */ export function update(ref: Reference, values: object): Promise { validateFirebaseMergeDataArg('update', values, ref._path, false); @@ -794,7 +794,7 @@ export function update(ref: Reference, values: object): Promise { * Gets the most up-to-date result for this query. * * @param query - The query to run. - * @return A promise which resolves to the resulting DataSnapshot if a value is + * @returns A promise which resolves to the resulting DataSnapshot if a value is * available, or rejects if the client is unable to return a value (e.g., if the * server is unreachable and there is nothing cached). */ @@ -1030,7 +1030,7 @@ function addEventListener( * permission to read this data (or it had permission but has now lost it). * This callback will be passed an `Error` object indicating why the failure * occurred. - * @return A function that can be invoked to remove the listener. + * @returns A function that can be invoked to remove the listener. */ export function onValue( query: Query, @@ -1059,7 +1059,7 @@ export function onValue( * callback will be passed a DataSnapshot. * @param options - An object that can be used to configure `onlyOnce`, which * then removes the listener after its first invocation. - * @return A function that can be invoked to remove the listener. + * @returns A function that can be invoked to remove the listener. */ export function onValue( query: Query, @@ -1093,7 +1093,7 @@ export function onValue( * occurred. * @param options - An object that can be used to configure `onlyOnce`, which * then removes the listener after its first invocation. - * @return A function that can be invoked to remove the listener. + * @returns A function that can be invoked to remove the listener. */ export function onValue( query: Query, @@ -1142,7 +1142,7 @@ export function onValue( * permission to read this data (or it had permission but has now lost it). * This callback will be passed an `Error` object indicating why the failure * occurred. - * @return A function that can be invoked to remove the listener. + * @returns A function that can be invoked to remove the listener. */ export function onChildAdded( query: Query, @@ -1175,7 +1175,7 @@ export function onChildAdded( * the previous child, by sort order, or `null` if it is the first child. * @param options - An object that can be used to configure `onlyOnce`, which * then removes the listener after its first invocation. - * @return A function that can be invoked to remove the listener. + * @returns A function that can be invoked to remove the listener. */ export function onChildAdded( query: Query, @@ -1213,7 +1213,7 @@ export function onChildAdded( * occurred. * @param options - An object that can be used to configure `onlyOnce`, which * then removes the listener after its first invocation. - * @return A function that can be invoked to remove the listener. + * @returns A function that can be invoked to remove the listener. */ export function onChildAdded( query: Query, @@ -1269,7 +1269,7 @@ export function onChildAdded( * permission to read this data (or it had permission but has now lost it). * This callback will be passed an `Error` object indicating why the failure * occurred. - * @return A function that can be invoked to remove the listener. + * @returns A function that can be invoked to remove the listener. */ export function onChildChanged( query: Query, @@ -1303,7 +1303,7 @@ export function onChildChanged( * the previous child, by sort order, or `null` if it is the first child. * @param options - An object that can be used to configure `onlyOnce`, which * then removes the listener after its first invocation. - * @return A function that can be invoked to remove the listener. + * @returns A function that can be invoked to remove the listener. */ export function onChildChanged( query: Query, @@ -1342,7 +1342,7 @@ export function onChildChanged( * occurred. * @param options - An object that can be used to configure `onlyOnce`, which * then removes the listener after its first invocation. - * @return A function that can be invoked to remove the listener. + * @returns A function that can be invoked to remove the listener. */ export function onChildChanged( query: Query, @@ -1396,7 +1396,7 @@ export function onChildChanged( * permission to read this data (or it had permission but has now lost it). * This callback will be passed an `Error` object indicating why the failure * occurred. - * @return A function that can be invoked to remove the listener. + * @returns A function that can be invoked to remove the listener. */ export function onChildMoved( query: Query, @@ -1428,7 +1428,7 @@ export function onChildMoved( * the previous child, by sort order, or `null` if it is the first child. * @param options - An object that can be used to configure `onlyOnce`, which * then removes the listener after its first invocation. - * @return A function that can be invoked to remove the listener. + * @returns A function that can be invoked to remove the listener. */ export function onChildMoved( query: Query, @@ -1465,7 +1465,7 @@ export function onChildMoved( * occurred. * @param options - An object that can be used to configure `onlyOnce`, which * then removes the listener after its first invocation. - * @return A function that can be invoked to remove the listener. + * @returns A function that can be invoked to remove the listener. */ export function onChildMoved( query: Query, @@ -1523,7 +1523,7 @@ export function onChildMoved( * permission to read this data (or it had permission but has now lost it). * This callback will be passed an `Error` object indicating why the failure * occurred. - * @return A function that can be invoked to remove the listener. + * @returns A function that can be invoked to remove the listener. */ export function onChildRemoved( query: Query, @@ -1556,7 +1556,7 @@ export function onChildRemoved( * the previous child, by sort order, or `null` if it is the first child. * @param options - An object that can be used to configure `onlyOnce`, which * then removes the listener after its first invocation. - * @return A function that can be invoked to remove the listener. + * @returns A function that can be invoked to remove the listener. */ export function onChildRemoved( query: Query, @@ -1594,7 +1594,7 @@ export function onChildRemoved( * occurred. * @param options - An object that can be used to configure `onlyOnce`, which * then removes the listener after its first invocation. - * @return A function that can be invoked to remove the listener. + * @returns A function that can be invoked to remove the listener. */ export function onChildRemoved( query: Query, diff --git a/packages/database/src/exp/ServerValue.ts b/packages/database/src/exp/ServerValue.ts index 3ea7889a388..30cdffdd509 100644 --- a/packages/database/src/exp/ServerValue.ts +++ b/packages/database/src/exp/ServerValue.ts @@ -33,7 +33,7 @@ export function serverTimestamp(): object { * current database value by the provided delta. * * @param delta the amount to modify the current value atomically. - * @return A placeholder value for modifying data atomically server-side. + * @returns A placeholder value for modifying data atomically server-side. */ export function increment(delta: number): object { return { diff --git a/packages/database/src/exp/Transaction.ts b/packages/database/src/exp/Transaction.ts index 39ed8ea0497..a7555ec3f99 100644 --- a/packages/database/src/exp/Transaction.ts +++ b/packages/database/src/exp/Transaction.ts @@ -81,7 +81,7 @@ export class TransactionResult { * transaction will be aborted and the data at this location will not be * modified. * @param options - An options object to configure transactions. - * @return A Promise that can optionally be used instead of the onComplete + * @returns A Promise that can optionally be used instead of the onComplete * callback to handle success and failure. */ export function runTransaction( diff --git a/packages/database/src/realtime/TransportManager.ts b/packages/database/src/realtime/TransportManager.ts index 787761c34fd..19ec62dc2e4 100644 --- a/packages/database/src/realtime/TransportManager.ts +++ b/packages/database/src/realtime/TransportManager.ts @@ -72,7 +72,7 @@ export class TransportManager { } /** - * @return The constructor for the initial transport to use + * @returns The constructor for the initial transport to use */ initialTransport(): TransportConstructor { if (this.transports_.length > 0) { @@ -83,7 +83,7 @@ export class TransportManager { } /** - * @return The constructor for the next transport, or null + * @returns The constructor for the next transport, or null */ upgradeTransport(): TransportConstructor | null { if (this.transports_.length > 1) { diff --git a/packages/database/src/realtime/WebSocketConnection.ts b/packages/database/src/realtime/WebSocketConnection.ts index 707c7c5f940..929f2f799d1 100644 --- a/packages/database/src/realtime/WebSocketConnection.ts +++ b/packages/database/src/realtime/WebSocketConnection.ts @@ -102,7 +102,7 @@ export class WebSocketConnection implements Transport { * @param transportSessionId Optional transportSessionId if this is connecting to an existing transport * session * @param lastSessionId Optional lastSessionId if there was a previous connection - * @return connection url + * @returns connection url */ private static connectionURL_( repoInfo: RepoInfo, @@ -288,7 +288,7 @@ export class WebSocketConnection implements Transport { /** * Attempts to parse a frame count out of some text. If it can't, assumes a value of 1 - * @return Any remaining data to be process, or null if there is none + * @returns Any remaining data to be process, or null if there is none */ private extractFrameCount_(data: string): string | null { assert(this.frames === null, 'We already have a frame buffer'); diff --git a/packages/database/test/datasnapshot.test.ts b/packages/database/test/datasnapshot.test.ts index 3afdfde8ddf..d6114b39ff1 100644 --- a/packages/database/test/datasnapshot.test.ts +++ b/packages/database/test/datasnapshot.test.ts @@ -25,7 +25,7 @@ import { DataSnapshot as ExpDataSnapshot } from '../src/exp/Reference_impl'; import { getRandomNode } from './helpers/util'; describe('DataSnapshot Tests', () => { - /** @return {!DataSnapshot} */ + /** @returns {!DataSnapshot} */ const snapshotForJSON = function (json) { const dummyRef = getRandomNode() as Reference; return new DataSnapshot(