From ba9b1623be9f82127a530ee1c9bf593046601707 Mon Sep 17 00:00:00 2001 From: Sebastian Schmidt Date: Tue, 6 Apr 2021 15:25:12 -0600 Subject: [PATCH 1/4] Add Support for API report Pruned DTS file: https://gist.github.com/schmidt-sebastian/2401be010ce057988495823ffe446a1d --- packages/database/exp/index.ts | 15 +- packages/database/exp/package.json | 2 +- packages/database/index.node.ts | 8 +- packages/database/package.json | 5 +- packages/database/scripts/api-report.ts | 178 ++++++++++++++++++ packages/database/src/api/Database.ts | 6 +- packages/database/src/api/Reference.ts | 13 +- packages/database/src/api/internal.ts | 8 +- packages/database/src/core/CompoundWrite.ts | 16 +- .../database/src/core/PersistentConnection.ts | 43 +---- .../database/src/core/ReadonlyRestClient.ts | 4 +- packages/database/src/core/Repo.ts | 33 ++-- packages/database/src/core/RepoInfo.ts | 12 +- packages/database/src/core/ServerActions.ts | 2 +- .../database/src/core/SparseSnapshotTree.ts | 14 +- packages/database/src/core/SyncPoint.ts | 10 +- packages/database/src/core/SyncTree.ts | 27 +-- packages/database/src/core/WriteTree.ts | 10 +- .../src/core/operation/AckUserWrite.ts | 6 +- packages/database/src/core/operation/Merge.ts | 8 - .../database/src/core/snap/ChildrenNode.ts | 24 +-- packages/database/src/core/snap/LeafNode.ts | 31 +-- packages/database/src/core/snap/Node.ts | 26 +-- packages/database/src/core/snap/childSet.ts | 8 +- .../src/core/snap/indexes/KeyIndex.ts | 20 -- .../src/core/snap/indexes/PathIndex.ts | 20 -- .../src/core/snap/indexes/PriorityIndex.ts | 19 -- .../src/core/snap/indexes/ValueIndex.ts | 19 -- .../database/src/core/snap/nodeFromJSON.ts | 4 +- .../database/src/core/stats/StatsListener.ts | 2 +- .../database/src/core/stats/StatsReporter.ts | 4 - .../src/core/storage/DOMStorageWrapper.ts | 6 +- packages/database/src/core/storage/storage.ts | 2 +- .../database/src/core/util/ImmutableTree.ts | 22 +-- packages/database/src/core/util/Path.ts | 6 +- .../database/src/core/util/ServerValues.ts | 6 +- packages/database/src/core/util/SortedMap.ts | 73 ++++--- packages/database/src/core/util/Tree.ts | 28 +-- packages/database/src/core/util/util.ts | 30 +-- packages/database/src/core/view/Change.ts | 10 +- .../src/core/view/CompleteChildSource.ts | 15 -- packages/database/src/core/view/Event.ts | 40 +--- packages/database/src/core/view/EventQueue.ts | 10 +- .../database/src/core/view/QueryParams.ts | 4 +- packages/database/src/core/view/View.ts | 4 +- .../src/core/view/filter/IndexedFilter.ts | 20 -- .../src/core/view/filter/LimitedFilter.ts | 24 --- .../src/core/view/filter/RangedFilter.ts | 24 --- packages/database/src/exp/Database.ts | 11 +- packages/database/src/exp/OnDisconnect.ts | 20 +- packages/database/src/exp/Reference.ts | 8 +- packages/database/src/exp/Reference_impl.ts | 167 ++++++++-------- packages/database/src/exp/ServerValue.ts | 2 +- .../src/realtime/BrowserPollConnection.ts | 16 +- packages/database/src/realtime/Connection.ts | 6 +- packages/database/src/realtime/Transport.ts | 14 +- .../database/src/realtime/TransportManager.ts | 2 +- .../src/realtime/WebSocketConnection.ts | 28 +-- packages/database/test/helpers/events.ts | 2 +- repo-scripts/prune-dts/prune-dts.ts | 2 +- 60 files changed, 533 insertions(+), 666 deletions(-) create mode 100644 packages/database/scripts/api-report.ts diff --git a/packages/database/exp/index.ts b/packages/database/exp/index.ts index 074202a22de..05f704e3149 100644 --- a/packages/database/exp/index.ts +++ b/packages/database/exp/index.ts @@ -26,6 +26,7 @@ import { } from '../src/exp/Database'; export { + FirebaseDatabase, enableLogging, getDatabase, goOffline, @@ -41,9 +42,10 @@ export { } from '../src/exp/Reference'; export { OnDisconnect } from '../src/exp/OnDisconnect'; export { - QueryConstraint, DataSnapshot, EventType, + QueryConstraint, + QueryConstraintType, endAt, endBefore, equalTo, @@ -55,16 +57,23 @@ export { onChildChanged, onChildMoved, onChildRemoved, + onDisconnect, onValue, orderByChild, orderByKey, orderByPriority, orderByValue, + push, query, + ref, + refFromURL, + remove, + set, + setPriority, + setWithPriority, startAfter, startAt, - ref, - refFromURL + update } from '../src/exp/Reference_impl'; export { increment, serverTimestamp } from '../src/exp/ServerValue'; export { diff --git a/packages/database/exp/package.json b/packages/database/exp/package.json index b6cf2b6b028..916f8918e64 100644 --- a/packages/database/exp/package.json +++ b/packages/database/exp/package.json @@ -5,5 +5,5 @@ "browser": "../dist/exp/index.esm.js", "module": "../dist/exp/index.esm.js", "esm2017": "../dist/exp/index.esm2017.js", - "typings": "../exp-types/index.d.ts" + "typings": "../dist/exp/index.d.ts" } diff --git a/packages/database/index.node.ts b/packages/database/index.node.ts index 30a8a7bb0e5..277365da490 100644 --- a/packages/database/index.node.ts +++ b/packages/database/index.node.ts @@ -40,10 +40,10 @@ const ServerValue = Database.ServerValue; * A one off register function which returns a database based on the app and * passed database URL. (Used by the Admin SDK) * - * @param app A valid FirebaseApp-like object - * @param url A valid Firebase databaseURL - * @param version custom version e.g. firebase-admin version - * @param nodeAdmin true if the SDK is being initialized from Firebase Admin. + * @param app - A valid FirebaseApp-like object + * @param url - A valid Firebase databaseURL + * @param version - custom version e.g. firebase-admin version + * @param nodeAdmin - true if the SDK is being initialized from Firebase Admin. */ export function initStandalone( app: FirebaseApp, diff --git a/packages/database/package.json b/packages/database/package.json index c57504a49f5..4893e8ef2bd 100644 --- a/packages/database/package.json +++ b/packages/database/package.json @@ -14,7 +14,7 @@ "lint": "eslint -c .eslintrc.js '**/*.ts' --ignore-path '../../.gitignore'", "lint:fix": "eslint --fix -c .eslintrc.js '**/*.ts' --ignore-path '../../.gitignore'", "prettier": "prettier --write '*.js' '*.ts' '@(exp|src|test)/**/*.ts'", - "build": "run-p build:classic build:exp && yarn api-report", + "build": "run-p build:classic build:exp", "build:classic": "rollup -c rollup.config.js", "build:exp": "rollup -c rollup.config.exp.js && yarn api-report", "build:deps": "lerna run --scope @firebase/'{app,database}' --include-dependencies build", @@ -25,7 +25,8 @@ "test:browser": "karma start --single-run", "test:node": "TS_NODE_FILES=true TS_NODE_CACHE=NO TS_NODE_COMPILER_OPTIONS='{\"module\":\"commonjs\"}' nyc --reporter lcovonly -- mocha 'test/{,!(browser)/**/}*.test.ts' --file index.node.ts --config ../../config/mocharc.node.js", "test:emulator": "ts-node --compiler-options='{\"module\":\"commonjs\"}' ../../scripts/emulator-testing/database-test-runner.ts", - "api-report": "api-extractor run --local --verbose", + "api-report": "TS_NODE_COMPILER_OPTIONS='{\"module\":\"commonjs\"}' ts-node ./scripts/api-report.ts && yarn api-report:api-json", + "api-report:api-json": "rm -rf temp && api-extractor run --local --verbose", "predoc": "node ../../scripts/exp/remove-exp.js temp", "doc": "api-documenter markdown --input temp --output docs" }, diff --git a/packages/database/scripts/api-report.ts b/packages/database/scripts/api-report.ts new file mode 100644 index 00000000000..873721b4df8 --- /dev/null +++ b/packages/database/scripts/api-report.ts @@ -0,0 +1,178 @@ +/** + * @license + * Copyright 2020 Google LLC + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +import * as fs from 'fs'; +import * as path from 'path'; + +import { Extractor, ExtractorConfig } from 'api-extractor-me'; +import * as tmp from 'tmp'; + +import { + pruneDts, + removeUnusedImports +} from '../../../repo-scripts/prune-dts/prune-dts'; + +// TODOD(mrschmidt): Combine this script with the Firestore version. + +/* eslint-disable no-console */ + +// This script takes the output of the API Extractor, post-processes it using +// the pruned-dts script and then invokes API report to generate a report +// that only includes exported symbols. This is all done in temporary folders, +// all configuration is auto-generated for each run. + +const baseApiExtractorConfigFile: string = path.resolve( + __dirname, + '../../../config/api-extractor.json' +); +const reportFolder = path.resolve(__dirname, '../../../common/api-review'); +const tmpDir = tmp.dirSync().name; + +function writeTypescriptConfig(): void { + const tsConfigJson = { + extends: path.resolve(__dirname, '../tsconfig.json'), + include: [path.resolve(__dirname, '../src')], + compilerOptions: { + downlevelIteration: true // Needed for FirebaseApp + } + }; + fs.writeFileSync( + path.resolve(tmpDir, 'tsconfig.json'), + JSON.stringify(tsConfigJson), + { encoding: 'utf-8' } + ); +} + +function writePackageJson(): void { + const packageJson = { + 'name': `@firebase/database-exp` + }; + const packageJsonPath = path.resolve(tmpDir, 'package.json'); + fs.writeFileSync(packageJsonPath, JSON.stringify(packageJson), { + encoding: 'utf-8' + }); +} + +function loadApiExtractorConfig( + typescriptDtsPath: string, + rollupDtsPath: string, + untrimmedRollupDtsPath: string, + dtsRollupEnabled: boolean, + apiReportEnabled: boolean +): ExtractorConfig { + const apiExtractorJsonPath = path.resolve(tmpDir, 'api-extractor.json'); + const apiExtractorJson = { + extends: baseApiExtractorConfigFile, + mainEntryPointFilePath: typescriptDtsPath, + 'dtsRollup': { + 'enabled': dtsRollupEnabled, + publicTrimmedFilePath: rollupDtsPath, + untrimmedFilePath: untrimmedRollupDtsPath + }, + 'tsdocMetadata': { + 'enabled': false + }, + 'apiReport': { + 'enabled': apiReportEnabled, + reportFolder + }, + 'messages': { + 'extractorMessageReporting': { + 'ae-missing-release-tag': { + 'logLevel': 'none' + }, + 'ae-unresolved-link': { + 'logLevel': 'none' + }, + 'ae-forgotten-export': { + 'logLevel': apiReportEnabled ? 'error' : 'none' + } + }, + 'tsdocMessageReporting': { + 'tsdoc-undefined-tag': { + 'logLevel': 'none' + } + } + } + }; + fs.writeFileSync(apiExtractorJsonPath, JSON.stringify(apiExtractorJson), { + encoding: 'utf-8' + }); + return ExtractorConfig.loadFileAndPrepare(apiExtractorJsonPath); +} + +export async function generateApi(): Promise { + // The .d.ts file generated by the Typescript compiler as we transpile our + // sources + const typescriptDtsPath: string = path.resolve( + __dirname, + `../dist/exp/packages/database/exp/index.d.ts` + ); + // A "bundled" version of our d.ts files that includes all public and private + // types + const rollupDtsPath: string = path.resolve( + __dirname, + `../dist/exp/private.d.ts` + ); + + // A "bundled" version of our d.ts files that includes all public and private + // types, but also include exports marked as @internal + // This file is used by @firebase/database-compat to use internal exports + const untrimmedRollupDtsPath: string = path.resolve( + __dirname, + `../dist/exp/internal.d.ts` + ); + + // A customer-facing d.ts file that only include the public APIs + const publicDtsPath: string = path.resolve( + __dirname, + `../dist/exp/index.d.ts` + ); + + console.log(`Running API Extractor configuration for RTDB...`); + writeTypescriptConfig(); + writePackageJson(); + + let extractorConfig = loadApiExtractorConfig( + typescriptDtsPath, + rollupDtsPath, + untrimmedRollupDtsPath, + /* dtsRollupEnabled= */ true, + /* apiReportEnabled= */ false + ); + Extractor.invoke(extractorConfig, { + localBuild: true + }); + + console.log('Generated rollup DTS'); + pruneDts(rollupDtsPath, publicDtsPath); + console.log('Pruned DTS file'); + await removeUnusedImports(publicDtsPath); + console.log('Removed unused imports'); + + extractorConfig = loadApiExtractorConfig( + publicDtsPath, + rollupDtsPath, + untrimmedRollupDtsPath, + /* dtsRollupEnabled= */ false, + /* apiReportEnabled= */ true + ); + Extractor.invoke(extractorConfig, { localBuild: true }); + console.log(`API report for RTDB written to ${reportFolder}`); +} + +void generateApi(); diff --git a/packages/database/src/api/Database.ts b/packages/database/src/api/Database.ts index 2649cad1b47..43766045bce 100644 --- a/packages/database/src/api/Database.ts +++ b/packages/database/src/api/Database.ts @@ -54,8 +54,8 @@ export class Database implements FirebaseService, Compat { * *

Note: This method must be called before performing any other operation. * - * @param host the emulator host (ex: localhost) - * @param port the emulator port (ex: 8080) + * @param host - the emulator host (ex: localhost) + * @param port - the emulator port (ex: 8080) */ useEmulator(host: string, port: number): void { useDatabaseEmulator(this._delegate, host, port); @@ -65,7 +65,7 @@ export class Database implements FirebaseService, Compat { * Returns a reference to the root or to the path specified in the provided * argument. * - * @param path The relative string path or an existing Reference to a database + * @param path - The relative string path or an existing Reference to a database * location. * @throws If a Reference is provided, throws if it does not belong to the * same project. diff --git a/packages/database/src/api/Reference.ts b/packages/database/src/api/Reference.ts index 1d1dd3ba1b6..98315eb1370 100644 --- a/packages/database/src/api/Reference.ts +++ b/packages/database/src/api/Reference.ts @@ -64,7 +64,8 @@ import { setWithPriority, remove, setPriority, - push + push, + ThenableReferenceImpl } from '../exp/Reference_impl'; import { runTransaction } from '../exp/Transaction'; @@ -123,7 +124,7 @@ export class DataSnapshot implements Compat { /** * Returns a DataSnapshot of the specified child node's contents. * - * @param path Path to a child. + * @param path - Path to a child. * @returns DataSnapshot for child node. */ child(path: string): DataSnapshot { @@ -137,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. + * @param path - Path to a child. * @returns Whether the child exists. */ hasChild(path: string): boolean { @@ -159,7 +160,7 @@ export class DataSnapshot implements Compat { /** * Iterates through child nodes and calls the specified action for each one. * - * @param action Callback function to be called + * @param action - Callback function to be called * for each child. * @returns True if forEach was canceled by action returning true for * one of the child nodes. @@ -502,7 +503,7 @@ export class Query implements Compat { /** * Helper used by .on and .once to extract the context and or cancel arguments. - * @param fnName The function name (on or once) + * @param fnName - The function name (on or once) * */ private static getCancelAndContextArgs_( @@ -743,7 +744,7 @@ export class Reference extends Query implements Compat { validateArgCount('Reference.push', 0, 2, arguments.length); validateCallback('Reference.push', 'onComplete', onComplete, true); - const expPromise = push(this._delegate, value); + const expPromise = push(this._delegate, value) as ThenableReferenceImpl; const promise = expPromise.then( expRef => new Reference(this.database, expRef) ); diff --git a/packages/database/src/api/internal.ts b/packages/database/src/api/internal.ts index 773bf0fd0a2..aad24d65cff 100644 --- a/packages/database/src/api/internal.ts +++ b/packages/database/src/api/internal.ts @@ -93,10 +93,10 @@ export const interceptServerData = function ( * Used by console to create a database based on the app, * passed database URL and a custom auth implementation. * - * @param app A valid FirebaseApp-like object - * @param url A valid Firebase databaseURL - * @param version custom version e.g. firebase-admin version - * @param customAuthImpl custom auth implementation + * @param app - A valid FirebaseApp-like object + * @param url - A valid Firebase databaseURL + * @param version - custom version e.g. firebase-admin version + * @param customAuthImpl - custom auth implementation */ export function initStandalone({ app, diff --git a/packages/database/src/core/CompoundWrite.ts b/packages/database/src/core/CompoundWrite.ts index f19577bd6e0..1ebee8a4e18 100644 --- a/packages/database/src/core/CompoundWrite.ts +++ b/packages/database/src/core/CompoundWrite.ts @@ -85,8 +85,8 @@ export function compoundWriteAddWrites( * Will remove a write at the given path and deeper paths. This will not modify a write at a higher * location, which must be removed by calling this method with that path. * - * @param compoundWrite The CompoundWrite to remove. - * @param path The path at which a write and all deeper writes should be removed + * @param compoundWrite - The CompoundWrite to remove. + * @param path - The path at which a write and all deeper writes should be removed * @returns The new CompoundWrite with the removed path */ export function compoundWriteRemoveWrite( @@ -108,8 +108,8 @@ export function compoundWriteRemoveWrite( * Returns whether this CompoundWrite will fully overwrite a node at a given location and can therefore be * considered "complete". * - * @param compoundWrite The CompoundWrite to check. - * @param path The path to check for + * @param compoundWrite - The CompoundWrite to check. + * @param path - The path to check for * @returns Whether there is a complete write at that path */ export function compoundWriteHasCompleteWrite( @@ -123,8 +123,8 @@ export function compoundWriteHasCompleteWrite( * Returns a node for a path if and only if the node is a "complete" overwrite at that path. This will not aggregate * writes from deeper paths, but will return child nodes from a more shallow path. * - * @param compoundWrite The CompoundWrite to get the node from. - * @param path The path to get a complete write + * @param compoundWrite - The CompoundWrite to get the node from. + * @param path - The path to get a complete write * @returns The node if complete at that path, or null otherwise. */ export function compoundWriteGetCompleteNode( @@ -144,7 +144,7 @@ export function compoundWriteGetCompleteNode( /** * Returns all children that are guaranteed to be a complete overwrite. * - * @param compoundWrite The CompoundWrite to get children from. + * @param compoundWrite - The CompoundWrite to get children from. * @returns A list of all complete children. */ export function compoundWriteGetCompleteChildren( @@ -201,7 +201,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 + * @param node - The node to apply this CompoundWrite to * @returns The node with all writes applied */ export function compoundWriteApply( diff --git a/packages/database/src/core/PersistentConnection.ts b/packages/database/src/core/PersistentConnection.ts index 2cae60fcfec..e3cfa4c5322 100644 --- a/packages/database/src/core/PersistentConnection.ts +++ b/packages/database/src/core/PersistentConnection.ts @@ -92,7 +92,6 @@ export class PersistentConnection extends ServerActions { private log_ = logWrapper('p:' + this.id + ':'); private interruptReasons_: { [reason: string]: boolean } = {}; - /** Map> */ private readonly listens: Map< /* path */ string, Map @@ -137,9 +136,9 @@ export class PersistentConnection extends ServerActions { private static nextConnectionId_ = 0; /** - * @param repoInfo_ Data about the namespace we are connecting to - * @param applicationId_ The Firebase App ID for this project - * @param onDataUpdate_ A callback for new data from the server + * @param repoInfo_ - Data about the namespace we are connecting to + * @param applicationId_ - The Firebase App ID for this project + * @param onDataUpdate_ - A callback for new data from the server */ constructor( private repoInfo_: RepoInfo, @@ -240,10 +239,6 @@ export class PersistentConnection extends ServerActions { return deferred.promise; } - - /** - * @inheritDoc - */ listen( query: QueryContext, currentHashFn: () => string, @@ -349,10 +344,6 @@ export class PersistentConnection extends ServerActions { } } } - - /** - * @inheritDoc - */ refreshAuthToken(token: string) { this.authToken_ = token; this.log_('Auth token refreshed'); @@ -414,10 +405,6 @@ export class PersistentConnection extends ServerActions { ); } } - - /** - * @inheritDoc - */ unlisten(query: QueryContext, tag: number | null) { const pathString = query._path.toString(); const queryId = query._queryIdentifier; @@ -452,10 +439,6 @@ export class PersistentConnection extends ServerActions { this.sendRequest(action, req); } - - /** - * @inheritDoc - */ onDisconnectPut( pathString: string, data: unknown, @@ -472,10 +455,6 @@ export class PersistentConnection extends ServerActions { }); } } - - /** - * @inheritDoc - */ onDisconnectMerge( pathString: string, data: unknown, @@ -492,10 +471,6 @@ export class PersistentConnection extends ServerActions { }); } } - - /** - * @inheritDoc - */ onDisconnectCancel( pathString: string, onComplete?: (a: string, b: string) => void @@ -531,10 +506,6 @@ export class PersistentConnection extends ServerActions { } }); } - - /** - * @inheritDoc - */ put( pathString: string, data: unknown, @@ -543,10 +514,6 @@ export class PersistentConnection extends ServerActions { ) { this.putInternal('p', pathString, data, onComplete, hash); } - - /** - * @inheritDoc - */ merge( pathString: string, data: unknown, @@ -614,10 +581,6 @@ export class PersistentConnection extends ServerActions { } }); } - - /** - * @inheritDoc - */ reportStats(stats: { [k: string]: unknown }) { // If we're not connected, we just drop the stats. if (this.connected_) { diff --git a/packages/database/src/core/ReadonlyRestClient.ts b/packages/database/src/core/ReadonlyRestClient.ts index d9cfceac113..63615b6b003 100644 --- a/packages/database/src/core/ReadonlyRestClient.ts +++ b/packages/database/src/core/ReadonlyRestClient.ts @@ -62,8 +62,8 @@ export class ReadonlyRestClient extends ServerActions { } /** - * @param repoInfo_ Data about the namespace we are connecting to - * @param onDataUpdate_ A callback for new data from the server + * @param repoInfo_ - Data about the namespace we are connecting to + * @param onDataUpdate_ - A callback for new data from the server */ constructor( private repoInfo_: RepoInfo, diff --git a/packages/database/src/core/Repo.ts b/packages/database/src/core/Repo.ts index 13f3d1db196..005c663f74c 100644 --- a/packages/database/src/core/Repo.ts +++ b/packages/database/src/core/Repo.ts @@ -35,6 +35,7 @@ import { nodeFromJSON } from './snap/nodeFromJSON'; import { SnapshotHolder } from './SnapshotHolder'; import { newSparseSnapshotTree, + SparseSnapshotTree, sparseSnapshotTreeForEachTree, sparseSnapshotTreeForget, sparseSnapshotTreeRemember @@ -175,7 +176,7 @@ export class Repo { interceptServerDataCallback_: ((a: string, b: unknown) => void) | null = null; /** A list of data pieces and paths to be set when this client disconnects. */ - onDisconnect_ = newSparseSnapshotTree(); + onDisconnect_: SparseSnapshotTree = newSparseSnapshotTree(); /** Stores queues of outstanding transactions for Firebase locations. */ transactionQueueTree_ = new Tree(); @@ -857,12 +858,12 @@ export function repoCallOnCompleteCallback( * Creates a new transaction, adds it to the transactions we're tracking, and * sends it to the server if possible. * - * @param path Path at which to do transaction. - * @param transactionUpdate Update callback. - * @param onComplete Completion callback. - * @param unwatcher Function that will be called when the transaction no longer + * @param path - Path at which to do transaction. + * @param transactionUpdate - Update callback. + * @param onComplete - Completion callback. + * @param unwatcher - Function that will be called when the transaction no longer * need data updates for `path`. - * @param applyLocally Whether or not to make intermediate results visible + * @param applyLocally - Whether or not to make intermediate results visible */ export function repoStartTransaction( repo: Repo, @@ -974,7 +975,7 @@ export function repoStartTransaction( } /** - * @param excludeSets A specific set to exclude + * @param excludeSets - A specific set to exclude */ function repoGetLatestState( repo: Repo, @@ -994,7 +995,7 @@ function repoGetLatestState( * Externally it's called with no arguments, but it calls itself recursively * with a particular transactionQueueTree node to recurse through the tree. * - * @param node transactionQueueTree node to start at. + * @param node - transactionQueueTree node to start at. */ function repoSendReadyTransactions( repo: Repo, @@ -1028,8 +1029,8 @@ function repoSendReadyTransactions( * Given a list of run transactions, send them to the server and then handle * the result (success or failure). * - * @param path The location of the queue. - * @param queue Queue of transactions under the specified location. + * @param path - The location of the queue. + * @param queue - Queue of transactions under the specified location. */ function repoSendTransactionQueue( repo: Repo, @@ -1146,7 +1147,7 @@ function repoSendTransactionQueue( * Return the highest path that was affected by rerunning transactions. This * is the path at which events need to be raised for. * - * @param changedPath The path in mergedData that changed. + * @param changedPath - The path in mergedData that changed. * @returns The rootmost path that was affected by rerunning transactions. */ function repoRerunTransactions(repo: Repo, changedPath: Path): Path { @@ -1166,8 +1167,8 @@ function repoRerunTransactions(repo: Repo, changedPath: Path): Path { * Does all the work of rerunning transactions (as well as cleans up aborted * transactions and whatnot). * - * @param queue The queue of transactions to run. - * @param path The path the queue is for. + * @param queue - The queue of transactions to run. + * @param path - The path the queue is for. */ function repoRerunTransactionQueue( repo: Repo, @@ -1328,7 +1329,7 @@ function repoRerunTransactionQueue( * transaction on it, or just returns the node for the given path if there are * no pending transactions on any ancestor. * - * @param path The location to start at. + * @param path - The location to start at. * @returns The rootmost node with a transaction. */ function repoGetAncestorTransactionNode( @@ -1422,7 +1423,7 @@ function repoPruneCompletedTransactionsBelowNode( * Called when doing a set() or update() since we consider them incompatible * with transactions. * - * @param path Path for which we want to abort related transactions. + * @param path - Path for which we want to abort related transactions. */ function repoAbortTransactions(repo: Repo, path: Path): Path { const affectedPath = treeGetPath(repoGetAncestorTransactionNode(repo, path)); @@ -1445,7 +1446,7 @@ function repoAbortTransactions(repo: Repo, path: Path): Path { /** * Abort transactions stored in this transaction queue node. * - * @param node Node to abort transactions for. + * @param node - Node to abort transactions for. */ function repoAbortTransactionsOnNode( repo: Repo, diff --git a/packages/database/src/core/RepoInfo.ts b/packages/database/src/core/RepoInfo.ts index 4302ea86581..de0e4603be1 100644 --- a/packages/database/src/core/RepoInfo.ts +++ b/packages/database/src/core/RepoInfo.ts @@ -31,12 +31,12 @@ export class RepoInfo { internalHost: string; /** - * @param host Hostname portion of the url for the repo - * @param secure Whether or not this repo is accessed over ssl - * @param namespace The namespace represented by the repo - * @param webSocketOnly Whether to prefer websockets over all other transports (used by Nest). - * @param nodeAdmin Whether this instance uses Admin SDK credentials - * @param persistenceKey Override the default session persistence storage key + * @param host - Hostname portion of the url for the repo + * @param secure - Whether or not this repo is accessed over ssl + * @param namespace - The namespace represented by the repo + * @param webSocketOnly - Whether to prefer websockets over all other transports (used by Nest). + * @param nodeAdmin - Whether this instance uses Admin SDK credentials + * @param persistenceKey - Override the default session persistence storage key */ constructor( host: string, diff --git a/packages/database/src/core/ServerActions.ts b/packages/database/src/core/ServerActions.ts index 7a8d3fa1225..ee5b3f32ff9 100644 --- a/packages/database/src/core/ServerActions.ts +++ b/packages/database/src/core/ServerActions.ts @@ -57,7 +57,7 @@ export abstract class ServerActions { /** * Refreshes the auth token for the current connection. - * @param token The authentication token + * @param token - The authentication token */ refreshAuthToken(token: string) {} diff --git a/packages/database/src/core/SparseSnapshotTree.ts b/packages/database/src/core/SparseSnapshotTree.ts index 27a9be9a85a..e578cd2d11d 100644 --- a/packages/database/src/core/SparseSnapshotTree.ts +++ b/packages/database/src/core/SparseSnapshotTree.ts @@ -38,7 +38,7 @@ export function newSparseSnapshotTree(): SparseSnapshotTree { * Gets the node stored at the given path if one exists. * Only seems to be used in tests. * - * @param path Path to look up snapshot for. + * @param path - Path to look up snapshot for. * @returns The retrieved node, or null. */ export function sparseSnapshotTreeFind( @@ -65,8 +65,8 @@ export function sparseSnapshotTreeFind( * Stores the given node at the specified path. If there is already a node * at a shallower path, it merges the new data into that snapshot node. * - * @param path Path to look up snapshot for. - * @param data The new data, or null. + * @param path - Path to look up snapshot for. + * @param data - The new data, or null. */ export function sparseSnapshotTreeRemember( sparseSnapshotTree: SparseSnapshotTree, @@ -93,7 +93,7 @@ export function sparseSnapshotTreeRemember( /** * Purge the data at path from the cache. * - * @param path Path to look up snapshot for. + * @param path - Path to look up snapshot for. * @returns True if this node should now be removed. */ export function sparseSnapshotTreeForget( @@ -143,8 +143,8 @@ export function sparseSnapshotTreeForget( * Recursively iterates through all of the stored tree and calls the * callback on each one. * - * @param prefixPath Path to look up node for. - * @param func The function to invoke for each tree. + * @param prefixPath - Path to look up node for. + * @param func - The function to invoke for each tree. */ export function sparseSnapshotTreeForEachTree( sparseSnapshotTree: SparseSnapshotTree, @@ -165,7 +165,7 @@ export function sparseSnapshotTreeForEachTree( * Iterates through each immediate child and triggers the callback. * Only seems to be used in tests. * - * @param func The function to invoke for each child. + * @param func - The function to invoke for each child. */ export function sparseSnapshotTreeForEachChild( sparseSnapshotTree: SparseSnapshotTree, diff --git a/packages/database/src/core/SyncPoint.ts b/packages/database/src/core/SyncPoint.ts index 99c0efc5dd4..6751b2242a8 100644 --- a/packages/database/src/core/SyncPoint.ts +++ b/packages/database/src/core/SyncPoint.ts @@ -115,7 +115,7 @@ export function syncPointApplyOperation( /** * Get a view for the specified query. * - * @param query The query to return a view for + * @param query - The query to return a view for * @param writesCache * @param serverCache * @param serverCacheComplete @@ -164,7 +164,7 @@ export function syncPointGetView( * @param query * @param eventRegistration * @param writesCache - * @param serverCache Complete server cache, if we have it. + * @param serverCache - Complete server cache, if we have it. * @param serverCacheComplete * @returns Events to raise. */ @@ -197,8 +197,8 @@ export function syncPointAddEventRegistration( * If query is the default query, we'll check all views for the specified eventRegistration. * If eventRegistration is null, we'll remove all callbacks for the specified view(s). * - * @param eventRegistration If null, remove all callbacks. - * @param cancelError If a cancelError is provided, appropriate cancel events will be returned. + * @param eventRegistration - If null, remove all callbacks. + * @param cancelError - If a cancelError is provided, appropriate cancel events will be returned. * @returns removed queries and any cancel events */ export function syncPointRemoveEventRegistration( @@ -265,7 +265,7 @@ export function syncPointGetQueryViews(syncPoint: SyncPoint): View[] { } /** - * @param path The path to the desired complete snapshot + * @param path - The path to the desired complete snapshot * @returns A complete cache, if it exists */ export function syncPointGetCompleteServerCache( diff --git a/packages/database/src/core/SyncTree.ts b/packages/database/src/core/SyncTree.ts index 700a6fe126c..0fad43f5976 100644 --- a/packages/database/src/core/SyncTree.ts +++ b/packages/database/src/core/SyncTree.ts @@ -60,6 +60,7 @@ import { EventRegistration, QueryContext } from './view/EventRegistration'; import { View, viewGetCompleteNode, viewGetServerCache } from './view/View'; import { newWriteTree, + WriteTree, writeTreeAddMerge, writeTreeAddOverwrite, writeTreeCalcCompleteEventCache, @@ -87,18 +88,6 @@ function syncTreeGetReferenceConstructor(): ReferenceConstructor { return referenceConstructor; } -/** - * @typedef {{ - * startListening: function( - * !Query, - * ?number, - * function():string, - * function(!string, *):!Array. - * ):!Array., - * - * stopListening: function(!Query, ?number) - * }} - */ export interface ListenProvider { startListening( query: QueryContext, @@ -145,13 +134,13 @@ export class SyncTree { /** * A tree of all pending user writes (user-initiated set()'s, transaction()'s, update()'s, etc.). */ - pendingWriteTree_ = newWriteTree(); + pendingWriteTree_: WriteTree = newWriteTree(); readonly tagToQueryMap: Map = new Map(); readonly queryToTagMap: Map = new Map(); /** - * @param listenProvider_ Used by SyncTree to start / stop listening + * @param listenProvider_ - Used by SyncTree to start / stop listening * to server data. */ constructor(public listenProvider_: ListenProvider) {} @@ -213,7 +202,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 + * @param revert - True if the given write failed and needs to be reverted * @returns Events to raise. */ export function syncTreeAckUserWrite( @@ -327,8 +316,8 @@ export function syncTreeApplyTaggedListenComplete( * If query is the default query, we'll check all queries for the specified eventRegistration. * If eventRegistration is null, we'll remove all callbacks for the specified query/queries. * - * @param eventRegistration If null, all callbacks are removed. - * @param cancelError If a cancelError is provided, appropriate cancel events will be returned. + * @param eventRegistration - If null, all callbacks are removed. + * @param cancelError - If a cancelError is provided, appropriate cancel events will be returned. * @returns Cancel events, if cancelError was provided. */ export function syncTreeRemoveEventRegistration( @@ -584,8 +573,8 @@ export function syncTreeAddEventRegistration( * * Note: this method will *include* hidden writes from transaction with applyLocally set to false. * - * @param path The path to the data we want - * @param writeIdsToExclude A specific set to be excluded + * @param path - The path to the data we want + * @param writeIdsToExclude - A specific set to be excluded */ export function syncTreeCalcCompleteEventCache( syncTree: SyncTree, diff --git a/packages/database/src/core/WriteTree.ts b/packages/database/src/core/WriteTree.ts index 5003dad68a9..f586f194441 100644 --- a/packages/database/src/core/WriteTree.ts +++ b/packages/database/src/core/WriteTree.ts @@ -72,7 +72,7 @@ export function writeTreeChildWrites( /** * Record a new overwrite from user code. * - * @param visible This is set to false by some transactions. It should be excluded from event caches + * @param visible - This is set to false by some transactions. It should be excluded from event caches */ export function writeTreeAddOverwrite( writeTree: WriteTree, @@ -351,8 +351,8 @@ export function writeTreeGetCompleteWriteData( * Given optional, underlying server data, and an optional set of constraints (exclude some sets, include hidden * writes), attempt to calculate a complete snapshot for the given path * - * @param writeIdsToExclude An optional set to be excluded - * @param includeHiddenWrites Defaults to false, whether or not to layer on writes with visible set to false + * @param writeIdsToExclude - An optional set to be excluded + * @param includeHiddenWrites - Defaults to false, whether or not to layer on writes with visible set to false */ export function writeTreeCalcCompleteEventCache( writeTree: WriteTree, @@ -674,8 +674,8 @@ export interface WriteTree { * to get a cache that includes hidden writes, and excludes arbitrary writes. Note that customizing the returned node * can lead to a more expensive calculation. * - * @param writeIdsToExclude Optional writes to exclude. - * @param includeHiddenWrites Defaults to false, whether or not to layer on writes with visible set to false + * @param writeIdsToExclude - Optional writes to exclude. + * @param includeHiddenWrites - Defaults to false, whether or not to layer on writes with visible set to false */ export function writeTreeRefCalcCompleteEventCache( writeTreeRef: WriteTreeRef, diff --git a/packages/database/src/core/operation/AckUserWrite.ts b/packages/database/src/core/operation/AckUserWrite.ts index 41f0067526f..8bd98ae6745 100644 --- a/packages/database/src/core/operation/AckUserWrite.ts +++ b/packages/database/src/core/operation/AckUserWrite.ts @@ -36,17 +36,13 @@ export class AckUserWrite implements Operation { source = newOperationSourceUser(); /** - * @param affectedTree A tree containing true for each affected path. Affected paths can't overlap. + * @param affectedTree - A tree containing true for each affected path. Affected paths can't overlap. */ constructor( /** @inheritDoc */ public path: Path, /** @inheritDoc */ public affectedTree: ImmutableTree, /** @inheritDoc */ public revert: boolean ) {} - - /** - * @inheritDoc - */ operationForChild(childName: string): AckUserWrite { if (!pathIsEmpty(this.path)) { assert( diff --git a/packages/database/src/core/operation/Merge.ts b/packages/database/src/core/operation/Merge.ts index c72587a84c8..eeded9d96c6 100644 --- a/packages/database/src/core/operation/Merge.ts +++ b/packages/database/src/core/operation/Merge.ts @@ -39,10 +39,6 @@ export class Merge implements Operation { /** @inheritDoc */ public path: Path, /** @inheritDoc */ public children: ImmutableTree ) {} - - /** - * @inheritDoc - */ operationForChild(childName: string): Operation { if (pathIsEmpty(this.path)) { const childTree = this.children.subtree(new Path(childName)); @@ -64,10 +60,6 @@ export class Merge implements Operation { return new Merge(this.source, pathPopFront(this.path), this.children); } } - - /** - * @inheritDoc - */ toString(): string { return ( 'Operation(' + diff --git a/packages/database/src/core/snap/ChildrenNode.ts b/packages/database/src/core/snap/ChildrenNode.ts index 0989925f65c..fce34e484c3 100644 --- a/packages/database/src/core/snap/ChildrenNode.ts +++ b/packages/database/src/core/snap/ChildrenNode.ts @@ -66,8 +66,8 @@ export class ChildrenNode implements Node { } /** - * @param children_ List of children of this node.. - * @param priorityNode_ The priority of this node (as a snapshot node). + * @param children_ - List of children of this node.. + * @param priorityNode_ - The priority of this node (as a snapshot node). */ constructor( private readonly children_: SortedMap, @@ -311,10 +311,6 @@ export class ChildrenNode implements Node { return null; } } - - /** - * @inheritDoc - */ forEachChild( index: Index, action: (key: string, node: Node) => boolean | void @@ -387,10 +383,6 @@ export class ChildrenNode implements Node { return iterator; } } - - /** - * @inheritDoc - */ compareTo(other: ChildrenNode): number { if (this.isEmpty()) { if (other.isEmpty()) { @@ -407,10 +399,6 @@ export class ChildrenNode implements Node { return 0; } } - - /** - * @inheritDoc - */ withIndex(indexDefinition: Index): Node { if ( indexDefinition === KEY_INDEX || @@ -425,17 +413,9 @@ export class ChildrenNode implements Node { return new ChildrenNode(this.children_, this.priorityNode_, newIndexMap); } } - - /** - * @inheritDoc - */ isIndexed(index: Index): boolean { return index === KEY_INDEX || this.indexMap_.hasIndex(index); } - - /** - * @inheritDoc - */ equals(other: Node): boolean { if (other === this) { return true; diff --git a/packages/database/src/core/snap/LeafNode.ts b/packages/database/src/core/snap/LeafNode.ts index e280de54cf7..3b3316326a7 100644 --- a/packages/database/src/core/snap/LeafNode.ts +++ b/packages/database/src/core/snap/LeafNode.ts @@ -57,9 +57,9 @@ export class LeafNode implements Node { private lazyHash_: string | null = null; /** - * @param value_ The value to store in this leaf node. The object type is + * @param value_ - The value to store in this leaf node. The object type is * possible in the event of a deferred value - * @param priorityNode_ The priority of this node. + * @param priorityNode_ - The priority of this node. */ constructor( private readonly value_: string | number | boolean | Indexable, @@ -108,10 +108,6 @@ export class LeafNode implements Node { return LeafNode.__childrenNodeConstructor.EMPTY_NODE; } } - - /** - * @inheritDoc - */ hasChild(): boolean { return false; } @@ -172,10 +168,6 @@ export class LeafNode implements Node { forEachChild(index: Index, action: (s: string, n: Node) => void): boolean { return false; } - - /** - * @inheritDoc - */ val(exportFormat?: boolean): {} { if (exportFormat && !this.getPriority().isEmpty()) { return { @@ -217,10 +209,6 @@ export class LeafNode implements Node { getValue(): Indexable | string | number | boolean { return this.value_; } - - /** - * @inheritDoc - */ compareTo(other: Node): number { if (other === LeafNode.__childrenNodeConstructor.EMPTY_NODE) { return 1; @@ -261,28 +249,13 @@ export class LeafNode implements Node { return thisIndex - otherIndex; } } - - /** - * @inheritDoc - */ withIndex(): Node { return this; } - - /** - * @inheritDoc - */ isIndexed(): boolean { return true; } - - /** - * @inheritDoc - */ equals(other: Node): boolean { - /** - * @inheritDoc - */ if (other === this) { return true; } else if (other.isLeafNode()) { diff --git a/packages/database/src/core/snap/Node.ts b/packages/database/src/core/snap/Node.ts index 0bf423e8af6..9d4afca79dc 100644 --- a/packages/database/src/core/snap/Node.ts +++ b/packages/database/src/core/snap/Node.ts @@ -40,30 +40,30 @@ export interface Node { /** * Returns a duplicate node with the new priority. - * @param newPriorityNode New priority to set for the node. + * @param newPriorityNode - New priority to set for the node. * @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. + * @param childName - The name of the child to retrieve. * @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. + * @param path - The path of the child to retrieve. * @returns The retrieved child or an empty node. */ getChild(path: Path): Node; /** * Returns the name of the child immediately prior to the specified childNode, or null. - * @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 + * @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 * @returns The name of the predecessor child, or null if childNode is the first child. */ getPredecessorChildName( @@ -75,8 +75,8 @@ export interface Node { /** * Returns a duplicate node, with the specified immediate child updated. * Any value in the node will be removed. - * @param childName The name of the child to update. - * @param newChildNode The new child node + * @param childName - The name of the child to update. + * @param newChildNode - The new child node * @returns The updated node. */ updateImmediateChild(childName: string, newChildNode: Node): Node; @@ -84,8 +84,8 @@ export interface Node { /** * Returns a duplicate node, with the specified child updated. Any value will * be removed. - * @param path The path of the child to update. - * @param newChildNode The new child node, which may be an empty node + * @param path - The path of the child to update. + * @param newChildNode - The new child node, which may be an empty node * @returns The updated node. */ updateChild(path: Path, newChildNode: Node): Node; @@ -107,14 +107,14 @@ export interface Node { /** * Calls action for each child. - * @param action Action to be called for + * @param action - Action to be called for * each child. It's passed the child name and the child node. * @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). + * @param exportFormat - True for export format (also wire protocol format). * @returns Value of this node as JSON. */ val(exportFormat?: boolean): unknown; @@ -125,7 +125,7 @@ export interface Node { hash(): string; /** - * @param other Another node + * @param other - Another node * @returns -1 for less than, 0 for equal, 1 for greater than other */ compareTo(other: Node): number; diff --git a/packages/database/src/core/snap/childSet.ts b/packages/database/src/core/snap/childSet.ts index de4f01569be..bef2b193f1f 100644 --- a/packages/database/src/core/snap/childSet.ts +++ b/packages/database/src/core/snap/childSet.ts @@ -52,11 +52,11 @@ class Base12Num { * Uses the algorithm described in the paper linked here: * http://citeseerx.ist.psu.edu/viewdoc/summary?doi=10.1.1.46.1458 * - * @param childList Unsorted list of children - * @param cmp The comparison method to be used - * @param keyFn An optional function to extract K from a node wrapper, if K's + * @param childList - Unsorted list of children + * @param cmp - The comparison method to be used + * @param keyFn - An optional function to extract K from a node wrapper, if K's * type is not NamedNode - * @param mapSortFn An optional override for comparator used by the generated sorted map + * @param mapSortFn - An optional override for comparator used by the generated sorted map */ export const buildChildSet = function ( childList: NamedNode[], diff --git a/packages/database/src/core/snap/indexes/KeyIndex.ts b/packages/database/src/core/snap/indexes/KeyIndex.ts index 05d4e7e79ac..b2678c39d5a 100644 --- a/packages/database/src/core/snap/indexes/KeyIndex.ts +++ b/packages/database/src/core/snap/indexes/KeyIndex.ts @@ -33,41 +33,21 @@ export class KeyIndex extends Index { static set __EMPTY_NODE(val) { __EMPTY_NODE = val; } - - /** - * @inheritDoc - */ compare(a: NamedNode, b: NamedNode): number { return nameCompare(a.name, b.name); } - - /** - * @inheritDoc - */ isDefinedOn(node: Node): boolean { // We could probably return true here (since every node has a key), but it's never called // so just leaving unimplemented for now. throw assertionError('KeyIndex.isDefinedOn not expected to be called.'); } - - /** - * @inheritDoc - */ indexedValueChanged(oldNode: Node, newNode: Node): boolean { return false; // The key for a node never changes. } - - /** - * @inheritDoc - */ minPost() { // eslint-disable-next-line @typescript-eslint/no-explicit-any return (NamedNode as any).MIN; } - - /** - * @inheritDoc - */ maxPost(): NamedNode { // TODO: This should really be created once and cached in a static property, but // NamedNode isn't defined yet, so I can't use it in a static. Bleh. diff --git a/packages/database/src/core/snap/indexes/PathIndex.ts b/packages/database/src/core/snap/indexes/PathIndex.ts index e7808864d80..dfe3ef1bdc5 100644 --- a/packages/database/src/core/snap/indexes/PathIndex.ts +++ b/packages/database/src/core/snap/indexes/PathIndex.ts @@ -38,17 +38,9 @@ export class PathIndex extends Index { protected extractChild(snap: Node): Node { return snap.getChild(this.indexPath_); } - - /** - * @inheritDoc - */ isDefinedOn(node: Node): boolean { return !node.getChild(this.indexPath_).isEmpty(); } - - /** - * @inheritDoc - */ compare(a: NamedNode, b: NamedNode): number { const aChild = this.extractChild(a.node); const bChild = this.extractChild(b.node); @@ -59,10 +51,6 @@ export class PathIndex extends Index { return indexCmp; } } - - /** - * @inheritDoc - */ makePost(indexValue: object, name: string): NamedNode { const valueNode = nodeFromJSON(indexValue); const node = ChildrenNode.EMPTY_NODE.updateChild( @@ -71,18 +59,10 @@ export class PathIndex extends Index { ); return new NamedNode(name, node); } - - /** - * @inheritDoc - */ maxPost(): NamedNode { const node = ChildrenNode.EMPTY_NODE.updateChild(this.indexPath_, MAX_NODE); return new NamedNode(MAX_NAME, node); } - - /** - * @inheritDoc - */ toString(): string { return pathSlice(this.indexPath_, 0).join('/'); } diff --git a/packages/database/src/core/snap/indexes/PriorityIndex.ts b/packages/database/src/core/snap/indexes/PriorityIndex.ts index 117abd2e60d..9eda74bbc29 100644 --- a/packages/database/src/core/snap/indexes/PriorityIndex.ts +++ b/packages/database/src/core/snap/indexes/PriorityIndex.ts @@ -33,9 +33,6 @@ export function setMaxNode(val: Node) { } export class PriorityIndex extends Index { - /** - * @inheritDoc - */ compare(a: NamedNode, b: NamedNode): number { const aPriority = a.node.getPriority(); const bPriority = b.node.getPriority(); @@ -46,32 +43,16 @@ export class PriorityIndex extends Index { return indexCmp; } } - - /** - * @inheritDoc - */ isDefinedOn(node: Node): boolean { return !node.getPriority().isEmpty(); } - - /** - * @inheritDoc - */ indexedValueChanged(oldNode: Node, newNode: Node): boolean { return !oldNode.getPriority().equals(newNode.getPriority()); } - - /** - * @inheritDoc - */ minPost(): NamedNode { // eslint-disable-next-line @typescript-eslint/no-explicit-any return (NamedNode as any).MIN; } - - /** - * @inheritDoc - */ maxPost(): NamedNode { return new NamedNode(MAX_NAME, new LeafNode('[PRIORITY-POST]', MAX_NODE)); } diff --git a/packages/database/src/core/snap/indexes/ValueIndex.ts b/packages/database/src/core/snap/indexes/ValueIndex.ts index 576bc84f961..855b31c0e9e 100644 --- a/packages/database/src/core/snap/indexes/ValueIndex.ts +++ b/packages/database/src/core/snap/indexes/ValueIndex.ts @@ -22,9 +22,6 @@ import { nodeFromJSON } from '../nodeFromJSON'; import { Index } from './Index'; export class ValueIndex extends Index { - /** - * @inheritDoc - */ compare(a: NamedNode, b: NamedNode): number { const indexCmp = a.node.compareTo(b.node); if (indexCmp === 0) { @@ -33,32 +30,16 @@ export class ValueIndex extends Index { return indexCmp; } } - - /** - * @inheritDoc - */ isDefinedOn(node: Node): boolean { return true; } - - /** - * @inheritDoc - */ indexedValueChanged(oldNode: Node, newNode: Node): boolean { return !oldNode.equals(newNode); } - - /** - * @inheritDoc - */ minPost(): NamedNode { // eslint-disable-next-line @typescript-eslint/no-explicit-any return (NamedNode as any).MIN; } - - /** - * @inheritDoc - */ maxPost(): NamedNode { // eslint-disable-next-line @typescript-eslint/no-explicit-any return (NamedNode as any).MAX; diff --git a/packages/database/src/core/snap/nodeFromJSON.ts b/packages/database/src/core/snap/nodeFromJSON.ts index a497ed57377..b6df6bb4ed0 100644 --- a/packages/database/src/core/snap/nodeFromJSON.ts +++ b/packages/database/src/core/snap/nodeFromJSON.ts @@ -33,8 +33,8 @@ const USE_HINZE = true; /** * Constructs a snapshot node representing the passed JSON and returns it. - * @param json JSON to create a node for. - * @param priority Optional priority to use. This will be ignored if the + * @param json - JSON to create a node for. + * @param priority - Optional priority to use. This will be ignored if the * passed JSON contains a .priority property. */ export function nodeFromJSON( diff --git a/packages/database/src/core/stats/StatsListener.ts b/packages/database/src/core/stats/StatsListener.ts index 4e30c6ca9fa..969ce4f3cb2 100644 --- a/packages/database/src/core/stats/StatsListener.ts +++ b/packages/database/src/core/stats/StatsListener.ts @@ -22,7 +22,7 @@ import { StatsCollection } from './StatsCollection'; /** * Returns the delta from the previous call to get stats. * - * @param collection_ The collection to "listen" to. + * @param collection_ - The collection to "listen" to. */ export class StatsListener { private last_: { [k: string]: number } | null = null; diff --git a/packages/database/src/core/stats/StatsReporter.ts b/packages/database/src/core/stats/StatsReporter.ts index 2f5dd06ff77..f10db738111 100644 --- a/packages/database/src/core/stats/StatsReporter.ts +++ b/packages/database/src/core/stats/StatsReporter.ts @@ -36,10 +36,6 @@ export class StatsReporter { private statsListener_: StatsListener; statsToReport_: { [k: string]: boolean } = {}; - /** - * @param collection - * @param server_ - */ constructor(collection: StatsCollection, private server_: ServerActions) { this.statsListener_ = new StatsListener(collection); diff --git a/packages/database/src/core/storage/DOMStorageWrapper.ts b/packages/database/src/core/storage/DOMStorageWrapper.ts index 8d31ba5df53..f4255f50a23 100644 --- a/packages/database/src/core/storage/DOMStorageWrapper.ts +++ b/packages/database/src/core/storage/DOMStorageWrapper.ts @@ -31,13 +31,13 @@ export class DOMStorageWrapper { private prefix_ = 'firebase:'; /** - * @param domStorage_ The underlying storage object (e.g. localStorage or sessionStorage) + * @param domStorage_ - The underlying storage object (e.g. localStorage or sessionStorage) */ constructor(private domStorage_: Storage) {} /** - * @param key The key to save the value under - * @param value The value being stored, or null to remove the key. + * @param key - The key to save the value under + * @param value - The value being stored, or null to remove the key. */ set(key: string, value: unknown | null) { if (value == null) { diff --git a/packages/database/src/core/storage/storage.ts b/packages/database/src/core/storage/storage.ts index 99d62a82f95..c47ad1c482c 100644 --- a/packages/database/src/core/storage/storage.ts +++ b/packages/database/src/core/storage/storage.ts @@ -25,7 +25,7 @@ declare const window: Window; * TODO: Once MemoryStorage and DOMStorageWrapper have a shared interface this method annotation should change * to reflect this type * - * @param domStorageName Name of the underlying storage object + * @param domStorageName - Name of the underlying storage object * (e.g. 'localStorage' or 'sessionStorage'). * @returns Turning off type information until a common interface is defined. */ diff --git a/packages/database/src/core/util/ImmutableTree.ts b/packages/database/src/core/util/ImmutableTree.ts index 5191150588d..a6449878dad 100644 --- a/packages/database/src/core/util/ImmutableTree.ts +++ b/packages/database/src/core/util/ImmutableTree.ts @@ -72,11 +72,11 @@ export class ImmutableTree { * Given a path and predicate, return the first node and the path to that node * where the predicate returns true. * - * TODO Do a perf test -- If we're creating a bunch of {path: value:} objects - * on the way back out, it may be better to pass down a pathSoFar obj. + * TODO Do a perf test -- If we're creating a bunch of `{path: value:}` + * objects on the way back out, it may be better to pass down a pathSoFar obj. * - * @param relativePath The remainder of the path - * @param predicate The predicate to satisfy to return a node + * @param relativePath - The remainder of the path + * @param predicate - The predicate to satisfy to return a node */ findRootMostMatchingPathAndValue( relativePath: Path, @@ -141,8 +141,8 @@ export class ImmutableTree { /** * Sets a value at the specified path. * - * @param relativePath Path to set value at. - * @param toSet Value to set. + * @param relativePath - Path to set value at. + * @param toSet - Value to set. * @returns Resulting tree. */ set(relativePath: Path, toSet: T | null): ImmutableTree { @@ -160,7 +160,7 @@ export class ImmutableTree { /** * Removes the value at the specified path. * - * @param relativePath Path to value to remove. + * @param relativePath - Path to value to remove. * @returns Resulting tree. */ remove(relativePath: Path): ImmutableTree { @@ -195,7 +195,7 @@ export class ImmutableTree { /** * Gets a value from the tree. * - * @param relativePath Path to get value for. + * @param relativePath - Path to get value for. * @returns Value at path, or null. */ get(relativePath: Path): T | null { @@ -215,8 +215,8 @@ export class ImmutableTree { /** * Replace the subtree at the specified path with the given new tree. * - * @param relativePath Path to replace subtree for. - * @param newTree New tree. + * @param relativePath - Path to replace subtree for. + * @param newTree - New tree. * @returns Resulting tree. */ setTree(relativePath: Path, newTree: ImmutableTree): ImmutableTree { @@ -330,7 +330,7 @@ export class ImmutableTree { /** * Calls the given function for each node in the tree that has a value. * - * @param f A function to be called with the path from the root of the tree to + * @param f - A function to be called with the path from the root of the tree to * a node, and the value at that node. Called in depth-first order. */ foreach(f: (path: Path, value: T) => void) { diff --git a/packages/database/src/core/util/Path.ts b/packages/database/src/core/util/Path.ts index b409f9783bd..c0ddcf5061b 100644 --- a/packages/database/src/core/util/Path.ts +++ b/packages/database/src/core/util/Path.ts @@ -36,7 +36,7 @@ export class Path { pieceNum_: number; /** - * @param pathOrString Path string to parse, or another path, or the raw + * @param pathOrString - Path string to parse, or another path, or the raw * tokens array */ constructor(pathOrString: string | string[], pieceNum?: number) { @@ -264,8 +264,8 @@ export class ValidationPath { byteLength_: number; /** - * @param path Initial Path. - * @param errorPrefix_ Prefix for any error messages. + * @param path - Initial Path. + * @param errorPrefix_ - Prefix for any error messages. */ constructor(path: Path, public errorPrefix_: string) { this.parts_ = pathSlice(path, 0); diff --git a/packages/database/src/core/util/ServerValues.ts b/packages/database/src/core/util/ServerValues.ts index 8995e24bbae..e3b8cbb7b19 100644 --- a/packages/database/src/core/util/ServerValues.ts +++ b/packages/database/src/core/util/ServerValues.ts @@ -157,9 +157,9 @@ const resolveComplexDeferredValue = function ( /** * Recursively replace all deferred values and priorities in the tree with the * specified generated replacement values. - * @param path path to which write is relative - * @param node new data written at path - * @param syncTree current data + * @param path - path to which write is relative + * @param node - new data written at path + * @param syncTree - current data */ export const resolveDeferredValueTree = function ( path: Path, diff --git a/packages/database/src/core/util/SortedMap.ts b/packages/database/src/core/util/SortedMap.ts index 38328d2b043..c27cd7d5226 100644 --- a/packages/database/src/core/util/SortedMap.ts +++ b/packages/database/src/core/util/SortedMap.ts @@ -19,7 +19,7 @@ * @fileoverview Implementation of an immutable SortedMap using a Left-leaning * Red-Black Tree, adapted from the implementation in Mugs * (http://mads379.github.com/mugs/) by Mads Hartmann Jensen - * (mads379@gmail.com). + * (mads379\@gmail.com). * * Original paper on Left-leaning Red-Black Trees: * http://www.cs.princeton.edu/~rs/talks/LLRB/LLRB.pdf @@ -44,9 +44,8 @@ export class SortedMapIterator { private nodeStack_: Array | LLRBEmptyNode> = []; /** - * @param node Node to iterate. - * @param isReverse_ Whether or not to iterate in reverse - * @param resultGenerator_ + * @param node - Node to iterate. + * @param isReverse_ - Whether or not to iterate in reverse */ constructor( node: LLRBNode | LLRBEmptyNode, @@ -144,11 +143,11 @@ export class LLRBNode { right: LLRBNode | LLRBEmptyNode; /** - * @param key Key associated with this node. - * @param value Value associated with this node. - * @param color Whether this node is red. - * @param left Left child. - * @param right Right child. + * @param key - Key associated with this node. + * @param value - Value associated with this node. + * @param color - Whether this node is red. + * @param left - Left child. + * @param right - Right child. */ constructor( public key: K, @@ -170,11 +169,11 @@ export class LLRBNode { /** * Returns a copy of the current node, optionally replacing pieces of it. * - * @param key New key for the node, or null. - * @param value New value for the node, or null. - * @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. + * @param key - New key for the node, or null. + * @param value - New value for the node, or null. + * @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. * @returns The node copy. */ copy( @@ -211,7 +210,7 @@ export class LLRBNode { * Traverses the tree in key order and calls the specified action function * for each node. * - * @param action Callback function to be called for each + * @param action - Callback function to be called for each * node. If it returns true, traversal is aborted. * @returns The first truthy value returned by action, or the last falsey * value returned by action @@ -228,7 +227,7 @@ export class LLRBNode { * Traverses the tree in reverse key order and calls the specified action function * for each node. * - * @param action Callback function to be called for each + * @param action - Callback function to be called for each * node. If it returns true, traversal is aborted. * @returns True if traversal was aborted. */ @@ -270,9 +269,9 @@ export class LLRBNode { } /** - * @param key Key to insert. - * @param value Value to insert. - * @param comparator Comparator. + * @param key - Key to insert. + * @param value - Value to insert. + * @param comparator - Comparator. * @returns New tree, with the key/value added. */ insert(key: K, value: V, comparator: Comparator): LLRBNode { @@ -310,8 +309,8 @@ export class LLRBNode { } /** - * @param key The key of the item to remove. - * @param comparator Comparator. + * @param key - The key of the item to remove. + * @param comparator - Comparator. * @returns New tree, with the specified item removed. */ remove( @@ -489,9 +488,9 @@ export class LLRBEmptyNode { /** * Returns a copy of the tree, with the specified key/value added. * - * @param key Key to be added. - * @param value Value to be added. - * @param comparator Comparator. + * @param key - Key to be added. + * @param value - Value to be added. + * @param comparator - Comparator. * @returns New tree, with item added. */ insert(key: K, value: V, comparator: Comparator): LLRBNode { @@ -501,8 +500,8 @@ export class LLRBEmptyNode { /** * Returns a copy of the tree, with the specified key removed. * - * @param key The key to remove. - * @param comparator Comparator. + * @param key - The key to remove. + * @param comparator - Comparator. * @returns New tree, with item removed. */ remove(key: K, comparator: Comparator): LLRBEmptyNode { @@ -527,7 +526,7 @@ export class LLRBEmptyNode { * Traverses the tree in key order and calls the specified action function * for each node. * - * @param action Callback function to be called for each + * @param action - Callback function to be called for each * node. If it returns true, traversal is aborted. * @returns True if traversal was aborted. */ @@ -539,7 +538,7 @@ export class LLRBEmptyNode { * Traverses the tree in reverse key order and calls the specified action function * for each node. * - * @param action Callback function to be called for each + * @param action - Callback function to be called for each * node. If it returns true, traversal is aborted. * @returns True if traversal was aborted. */ @@ -578,8 +577,8 @@ export class SortedMap { static EMPTY_NODE = new LLRBEmptyNode(); /** - * @param comparator_ Key comparator. - * @param root_ (Optional) Root node for the map. + * @param comparator_ - Key comparator. + * @param root_ - Optional root node for the map. */ constructor( private comparator_: Comparator, @@ -592,8 +591,8 @@ export class SortedMap { * Returns a copy of the map, with the specified key/value added or replaced. * (TODO: We should perhaps rename this method to 'put') * - * @param key Key to be added. - * @param value Value to be added. + * @param key - Key to be added. + * @param value - Value to be added. * @returns New map, with item added. */ insert(key: K, value: V): SortedMap { @@ -608,7 +607,7 @@ export class SortedMap { /** * Returns a copy of the map, with the specified key removed. * - * @param key The key to remove. + * @param key - The key to remove. * @returns New map, with item removed. */ remove(key: K): SortedMap { @@ -623,7 +622,7 @@ export class SortedMap { /** * Returns the value of the node with the given key, or null. * - * @param key The key to look up. + * @param key - The key to look up. * @returns The value of the node with the given key, or null if the * key doesn't exist. */ @@ -645,7 +644,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 + * @param key - The key to find the predecessor of * @returns The predecessor key. */ getPredecessorKey(key: K): K | null { @@ -711,7 +710,7 @@ export class SortedMap { * Traverses the map in key order and calls the specified action function * for each key/value pair. * - * @param action Callback function to be called + * @param action - Callback function to be called * for each key/value pair. If action returns true, traversal is aborted. * @returns The first truthy value returned by action, or the last falsey * value returned by action @@ -724,7 +723,7 @@ export class SortedMap { * Traverses the map in reverse key order and calls the specified action function * for each key/value pair. * - * @param action Callback function to be called + * @param action - Callback function to be called * for each key/value pair. If action returns true, traversal is aborted. * @returns True if the traversal was aborted. */ diff --git a/packages/database/src/core/util/Tree.ts b/packages/database/src/core/util/Tree.ts index fd8f8ebcb52..7233b9ed948 100644 --- a/packages/database/src/core/util/Tree.ts +++ b/packages/database/src/core/util/Tree.ts @@ -38,9 +38,9 @@ export interface TreeNode { */ export class Tree { /** - * @param name Optional name of the node. - * @param parent Optional parent node. - * @param node Optional node to wrap. + * @param name - Optional name of the node. + * @param parent - Optional parent node. + * @param node - Optional node to wrap. */ constructor( readonly name: string = '', @@ -52,7 +52,7 @@ export class Tree { /** * Returns a sub-Tree for the given path. * - * @param pathObj Path to look up. + * @param pathObj - Path to look up. * @returns Tree for path. */ export function treeSubTree(tree: Tree, pathObj: string | Path): Tree { @@ -85,7 +85,7 @@ export function treeGetValue(tree: Tree): T | undefined { /** * Sets data to this tree node. * - * @param value Value to set. + * @param value - Value to set. */ export function treeSetValue(tree: Tree, value: T | undefined): void { tree.node.value = value; @@ -109,7 +109,7 @@ export function treeIsEmpty(tree: Tree): boolean { /** * Calls action for each child of this tree node. * - * @param action Action to be called for each child. + * @param action - Action to be called for each child. */ export function treeForEachChild( tree: Tree, @@ -123,10 +123,10 @@ export function treeForEachChild( /** * Does a depth-first traversal of this node's descendants, calling action for each one. * - * @param action Action to be called for each child. - * @param includeSelf Whether to call action on this node as well. Defaults to + * @param action - Action to be called for each child. + * @param includeSelf - Whether to call action on this node as well. Defaults to * false. - * @param childrenFirst Whether to call action on children before calling it on + * @param childrenFirst - Whether to call action on children before calling it on * parent. */ export function treeForEachDescendant( @@ -151,9 +151,9 @@ export function treeForEachDescendant( /** * Calls action on each ancestor node. * - * @param action Action to be called on each parent; return + * @param action - Action to be called on each parent; return * true to abort. - * @param includeSelf Whether to call action on this node as well. + * @param includeSelf - Whether to call action on this node as well. * @returns true if the action callback returned true. */ export function treeForEachAncestor( @@ -176,7 +176,7 @@ export function treeForEachAncestor( * is found, action is called on it and traversal does not continue inside the node. * Action is *not* called on this node. * - * @param action Action to be called for each child. + * @param action - Action to be called for each child. */ export function treeForEachImmediateDescendantWithValue( tree: Tree, @@ -214,8 +214,8 @@ function treeUpdateParents(tree: Tree) { /** * Adds or removes the passed child to this tree node, depending on whether it's empty. * - * @param childName The name of the child to update. - * @param child The child to update. + * @param childName - The name of the child to update. + * @param child - The child to update. */ function treeUpdateChild(tree: Tree, childName: string, child: Tree) { const childEmpty = treeIsEmpty(child); diff --git a/packages/database/src/core/util/util.ts b/packages/database/src/core/util/util.ts index c63010d15b8..4ce187b755c 100644 --- a/packages/database/src/core/util/util.ts +++ b/packages/database/src/core/util/util.ts @@ -46,7 +46,7 @@ export const LUIDGenerator: () => number = (function () { /** * Sha1 hash of the input string - * @param str The string to hash + * @param str - The string to hash * @returns {!string} The resulting hash */ export const sha1 = function (str: string): string { @@ -92,8 +92,8 @@ let firstLog_ = true; /** * The implementation of Firebase.enableLogging (defined here to break dependencies) - * @param logger_ A flag to turn on logging, or a custom logger - * @param persistent Whether or not to persist logging settings across refreshes + * @param logger_ - A flag to turn on logging, or a custom logger + * @param persistent - Whether or not to persist logging settings across refreshes */ export const enableLogging = function ( logger_?: boolean | ((a: string) => void) | null, @@ -331,8 +331,8 @@ 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. + * @param str - The string + * @param segsize - The maximum number of chars in the string. * @returns The string, split into appropriately-sized chunks */ export const splitStringBySize = function ( @@ -359,8 +359,8 @@ export const splitStringBySize = function ( /** * Apply a function to each (key, value) pair in an object or * apply a function to each (index, value) pair in an array - * @param obj The object or array to iterate over - * @param fn The function to apply + * @param obj - The object or array to iterate over + * @param fn - The function to apply */ export function each(obj: object, fn: (k: string, v: unknown) => void) { for (const key in obj) { @@ -372,8 +372,8 @@ export function each(obj: object, fn: (k: string, v: unknown) => void) { /** * Like goog.bind, but doesn't bother to create a closure if opt_context is null/undefined. - * @param callback Callback function. - * @param context Optional context to bind to. + * @param callback - Callback function. + * @param context - Optional context to bind to. * */ export const bindCallback = function ( @@ -387,7 +387,7 @@ export const bindCallback = function ( * Borrowed from http://hg.secondlife.com/llsd/src/tip/js/typedarray.js (MIT License) * I made one modification at the end and removed the NaN / Infinity * handling (since it seemed broken [caused an overflow] and we don't need it). See MJL comments. - * @param v A double + * @param v - A double * */ export const doubleToIEEE754String = function (v: number): string { @@ -533,7 +533,7 @@ export const tryParseInt = function (str: string): number | null { * * If you're only pausing on uncaught exceptions, the debugger will only pause * on us re-throwing it. * - * @param fn The code to guard. + * @param fn - The code to guard. */ export const exceptionGuard = function (fn: () => void) { try { @@ -557,8 +557,8 @@ export const exceptionGuard = function (fn: () => void) { * 1. Turns into a no-op if opt_callback is null or undefined. * 2. Wraps the call inside exceptionGuard to prevent exceptions from breaking our state. * - * @param callback Optional onComplete callback. - * @param varArgs Arbitrary args to be passed to opt_onComplete + * @param callback - Optional onComplete callback. + * @param varArgs - Arbitrary args to be passed to opt_onComplete */ export const callUserCallback = function ( // eslint-disable-next-line @typescript-eslint/ban-types @@ -609,8 +609,8 @@ export const exportPropGetter = function ( * * It is removed with clearTimeout() as normal. * - * @param fn Function to run. - * @param time Milliseconds to wait before running. + * @param fn - Function to run. + * @param time - Milliseconds to wait before running. * @returns The setTimeout() return value. */ export const setTimeoutNonBlocking = function ( diff --git a/packages/database/src/core/view/Change.ts b/packages/database/src/core/view/Change.ts index c2a57e556ec..30ffaa53649 100644 --- a/packages/database/src/core/view/Change.ts +++ b/packages/database/src/core/view/Change.ts @@ -31,15 +31,15 @@ export const enum ChangeType { } export interface Change { - /** @param type The event type */ + /** @param type - The event type */ type: ChangeType; - /** @param snapshotNode The data */ + /** @param snapshotNode - The data */ snapshotNode: Node; - /** @param childName The name for this child, if it's a child even */ + /** @param childName - The name for this child, if it's a child even */ childName?: string; - /** @param oldSnap Used for intermediate processing of child changed events */ + /** @param oldSnap - Used for intermediate processing of child changed events */ oldSnap?: Node; - /** * @param prevName The name for the previous child, if applicable */ + /** * @param prevName - The name for the previous child, if applicable */ prevName?: string | null; } diff --git a/packages/database/src/core/view/CompleteChildSource.ts b/packages/database/src/core/view/CompleteChildSource.ts index 36f2e6239df..6887ebbe442 100644 --- a/packages/database/src/core/view/CompleteChildSource.ts +++ b/packages/database/src/core/view/CompleteChildSource.ts @@ -49,16 +49,9 @@ export interface CompleteChildSource { */ // eslint-disable-next-line @typescript-eslint/naming-convention export class NoCompleteChildSource_ implements CompleteChildSource { - /** - * @inheritDoc - */ getCompleteChild(childKey?: string): Node | null { return null; } - - /** - * @inheritDoc - */ getChildAfterChild( index?: Index, child?: NamedNode, @@ -83,10 +76,6 @@ export class WriteTreeCompleteChildSource implements CompleteChildSource { private viewCache_: ViewCache, private optCompleteServerCache_: Node | null = null ) {} - - /** - * @inheritDoc - */ getCompleteChild(childKey: string): Node | null { const node = this.viewCache_.eventCache; if (node.isCompleteForChild(childKey)) { @@ -99,10 +88,6 @@ export class WriteTreeCompleteChildSource implements CompleteChildSource { return writeTreeRefCalcCompleteChild(this.writes_, childKey, serverNode); } } - - /** - * @inheritDoc - */ getChildAfterChild( index: Index, child: NamedNode, diff --git a/packages/database/src/core/view/Event.ts b/packages/database/src/core/view/Event.ts index ef18a9045a0..81d5d3b5d2e 100644 --- a/packages/database/src/core/view/Event.ts +++ b/packages/database/src/core/view/Event.ts @@ -52,10 +52,10 @@ export type EventType = */ export class DataEvent implements Event { /** - * @param eventType One of: value, child_added, child_changed, child_moved, child_removed - * @param eventRegistration The function to call to with the event data. User provided - * @param snapshot The data backing the event - * @param prevName Optional, the name of the previous child for child_* events. + * @param eventType - One of: value, child_added, child_changed, child_moved, child_removed + * @param eventRegistration - The function to call to with the event data. User provided + * @param snapshot - The data backing the event + * @param prevName - Optional, the name of the previous child for child_* events. */ constructor( public eventType: EventType, @@ -63,10 +63,6 @@ export class DataEvent implements Event { public snapshot: ExpDataSnapshot, public prevName?: string | null ) {} - - /** - * @inheritDoc - */ getPath(): Path { const ref = this.snapshot.ref; if (this.eventType === 'value') { @@ -75,24 +71,12 @@ export class DataEvent implements Event { return ref.parent._path; } } - - /** - * @inheritDoc - */ getEventType(): string { return this.eventType; } - - /** - * @inheritDoc - */ getEventRunner(): () => void { return this.eventRegistration.getEventRunner(this); } - - /** - * @inheritDoc - */ toString(): string { return ( this.getPath().toString() + @@ -110,31 +94,15 @@ export class CancelEvent implements Event { public error: Error, public path: Path ) {} - - /** - * @inheritDoc - */ getPath(): Path { return this.path; } - - /** - * @inheritDoc - */ getEventType(): string { return 'cancel'; } - - /** - * @inheritDoc - */ getEventRunner(): () => void { return this.eventRegistration.getEventRunner(this); } - - /** - * @inheritDoc - */ toString(): string { return this.path.toString() + ':cancel'; } diff --git a/packages/database/src/core/view/EventQueue.ts b/packages/database/src/core/view/EventQueue.ts index 9b5ba573843..dc62b5d1c51 100644 --- a/packages/database/src/core/view/EventQueue.ts +++ b/packages/database/src/core/view/EventQueue.ts @@ -43,7 +43,7 @@ export class EventQueue { } /** - * @param eventDataList The new events to queue. + * @param eventDataList - The new events to queue. */ export function eventQueueQueueEvents( eventQueue: EventQueue, @@ -76,8 +76,8 @@ export function eventQueueQueueEvents( * * It is assumed that the new events are all for the specified path. * - * @param path The path to raise events for. - * @param eventDataList The new events to raise. + * @param path - The path to raise events for. + * @param eventDataList - The new events to raise. */ export function eventQueueRaiseEventsAtPath( eventQueue: EventQueue, @@ -96,8 +96,8 @@ export function eventQueueRaiseEventsAtPath( * * It is assumed that the new events are all related (ancestor or descendant) to the specified path. * - * @param changedPath The path to raise events for. - * @param eventDataList The events to raise + * @param changedPath - The path to raise events for. + * @param eventDataList - The events to raise */ export function eventQueueRaiseEventsForChangedPath( eventQueue: EventQueue, diff --git a/packages/database/src/core/view/QueryParams.ts b/packages/database/src/core/view/QueryParams.ts index a8443e90521..577970fb255 100644 --- a/packages/database/src/core/view/QueryParams.ts +++ b/packages/database/src/core/view/QueryParams.ts @@ -20,7 +20,7 @@ import { assert, stringify } from '@firebase/util'; import { Index } from '../snap/indexes/Index'; import { KEY_INDEX } from '../snap/indexes/KeyIndex'; import { PathIndex } from '../snap/indexes/PathIndex'; -import { PRIORITY_INDEX } from '../snap/indexes/PriorityIndex'; +import { PRIORITY_INDEX, PriorityIndex } from '../snap/indexes/PriorityIndex'; import { VALUE_INDEX } from '../snap/indexes/ValueIndex'; import { predecessor, successor } from '../util/NextPushId'; import { MAX_NAME, MIN_NAME } from '../util/util'; @@ -78,7 +78,7 @@ export class QueryParams { indexStartName_ = ''; indexEndValue_: unknown | null = null; indexEndName_ = ''; - index_ = PRIORITY_INDEX; + index_: PriorityIndex = PRIORITY_INDEX; hasStart(): boolean { return this.startSet_; diff --git a/packages/database/src/core/view/View.ts b/packages/database/src/core/view/View.ts index 032fd1daaa4..2bb9e1d52e1 100644 --- a/packages/database/src/core/view/View.ts +++ b/packages/database/src/core/view/View.ts @@ -143,8 +143,8 @@ export function viewAddEventRegistration( } /** - * @param eventRegistration If null, remove all callbacks. - * @param cancelError If a cancelError is provided, appropriate cancel events will be returned. + * @param eventRegistration - If null, remove all callbacks. + * @param cancelError - If a cancelError is provided, appropriate cancel events will be returned. * @returns Cancel events, if cancelError was provided. */ export function viewRemoveEventRegistration( diff --git a/packages/database/src/core/view/filter/IndexedFilter.ts b/packages/database/src/core/view/filter/IndexedFilter.ts index f31c6607d62..3db8560d28e 100644 --- a/packages/database/src/core/view/filter/IndexedFilter.ts +++ b/packages/database/src/core/view/filter/IndexedFilter.ts @@ -94,10 +94,6 @@ export class IndexedFilter implements NodeFilter { return snap.updateImmediateChild(key, newChild).withIndex(this.index_); } } - - /** - * @inheritDoc - */ updateFullNode( oldSnap: Node, newSnap: Node, @@ -132,10 +128,6 @@ export class IndexedFilter implements NodeFilter { } return newSnap.withIndex(this.index_); } - - /** - * @inheritDoc - */ updatePriority(oldSnap: Node, newPriority: Node): Node { if (oldSnap.isEmpty()) { return ChildrenNode.EMPTY_NODE; @@ -143,24 +135,12 @@ export class IndexedFilter implements NodeFilter { return oldSnap.updatePriority(newPriority); } } - - /** - * @inheritDoc - */ filtersNodes(): boolean { return false; } - - /** - * @inheritDoc - */ getIndexedFilter(): IndexedFilter { return this; } - - /** - * @inheritDoc - */ getIndex(): Index { return this.index_; } diff --git a/packages/database/src/core/view/filter/LimitedFilter.ts b/packages/database/src/core/view/filter/LimitedFilter.ts index 40e003072cc..9fb74b4027d 100644 --- a/packages/database/src/core/view/filter/LimitedFilter.ts +++ b/packages/database/src/core/view/filter/LimitedFilter.ts @@ -52,10 +52,6 @@ export class LimitedFilter implements NodeFilter { this.limit_ = params.getLimit(); this.reverse_ = !params.isViewFromLeft(); } - - /** - * @inheritDoc - */ updateChild( snap: Node, key: string, @@ -91,10 +87,6 @@ export class LimitedFilter implements NodeFilter { ); } } - - /** - * @inheritDoc - */ updateFullNode( oldSnap: Node, newSnap: Node, @@ -192,32 +184,16 @@ export class LimitedFilter implements NodeFilter { .getIndexedFilter() .updateFullNode(oldSnap, filtered, optChangeAccumulator); } - - /** - * @inheritDoc - */ updatePriority(oldSnap: Node, newPriority: Node): Node { // Don't support priorities on queries return oldSnap; } - - /** - * @inheritDoc - */ filtersNodes(): boolean { return true; } - - /** - * @inheritDoc - */ getIndexedFilter(): IndexedFilter { return this.rangedFilter_.getIndexedFilter(); } - - /** - * @inheritDoc - */ getIndex(): Index { return this.index_; } diff --git a/packages/database/src/core/view/filter/RangedFilter.ts b/packages/database/src/core/view/filter/RangedFilter.ts index 3c86be93ba4..7311f1cc826 100644 --- a/packages/database/src/core/view/filter/RangedFilter.ts +++ b/packages/database/src/core/view/filter/RangedFilter.ts @@ -60,10 +60,6 @@ export class RangedFilter implements NodeFilter { this.index_.compare(node, this.getEndPost()) <= 0 ); } - - /** - * @inheritDoc - */ updateChild( snap: Node, key: string, @@ -84,10 +80,6 @@ export class RangedFilter implements NodeFilter { optChangeAccumulator ); } - - /** - * @inheritDoc - */ updateFullNode( oldSnap: Node, newSnap: Node, @@ -112,32 +104,16 @@ export class RangedFilter implements NodeFilter { optChangeAccumulator ); } - - /** - * @inheritDoc - */ updatePriority(oldSnap: Node, newPriority: Node): Node { // Don't support priorities on queries return oldSnap; } - - /** - * @inheritDoc - */ filtersNodes(): boolean { return true; } - - /** - * @inheritDoc - */ getIndexedFilter(): IndexedFilter { return this.indexedFilter_; } - - /** - * @inheritDoc - */ getIndex(): Index { return this.index_; } diff --git a/packages/database/src/exp/Database.ts b/packages/database/src/exp/Database.ts index 557840cc004..0d9981beb1d 100644 --- a/packages/database/src/exp/Database.ts +++ b/packages/database/src/exp/Database.ts @@ -162,7 +162,7 @@ function repoManagerDeleteRepo(repo: Repo, appName: string): void { * Ensures a repo doesn't already exist and then creates one using the * provided app. * - * @param repoInfo The metadata about the Repo + * @param repoInfo - The metadata about the Repo * @returns The Repo object for the specified server / repoName. */ function repoManagerCreateRepo( @@ -208,6 +208,7 @@ export class FirebaseDatabase implements _FirebaseService { /** Backing state for root_ */ private _rootInternal?: ReferenceImpl; + /** @hideconstructor */ constructor(private _repoInternal: Repo, readonly app: FirebaseApp) {} get _repo(): Repo { @@ -335,8 +336,8 @@ export function goOnline(db: FirebaseDatabase): void { /** * 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 + * @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); @@ -344,8 +345,8 @@ 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 + * @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( diff --git a/packages/database/src/exp/OnDisconnect.ts b/packages/database/src/exp/OnDisconnect.ts index cf7998cc2bd..f3b9507ab91 100644 --- a/packages/database/src/exp/OnDisconnect.ts +++ b/packages/database/src/exp/OnDisconnect.ts @@ -24,7 +24,6 @@ import { repoOnDisconnectSetWithPriority, repoOnDisconnectUpdate } from '../core/Repo'; -import { Indexable } from '../core/util/misc'; import { Path } from '../core/util/Path'; import { validateFirebaseDataArg, @@ -41,9 +40,9 @@ import { * * 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. + * 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 @@ -54,6 +53,7 @@ import { * the `onDisconnect` operations each time you reconnect. */ export class OnDisconnect { + /** @hideconstructor */ constructor(private _repo: Repo, private _path: Path) {} /** @@ -101,9 +101,9 @@ export class OnDisconnect { * * `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. + * 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 @@ -173,10 +173,10 @@ export class OnDisconnect { * 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. + * @param values - Object containing multiple values. * @returns Resolves when synchronization to the Database is complete. */ - update(values: Indexable): Promise { + update(values: object): Promise { validateWritablePath('OnDisconnect.update', this._path); validateFirebaseMergeDataArg( 'OnDisconnect.update', @@ -188,7 +188,7 @@ export class OnDisconnect { repoOnDisconnectUpdate( this._repo, this._path, - values, + values as Record, deferred.wrapCallback(() => {}) ); return deferred.promise; diff --git a/packages/database/src/exp/Reference.ts b/packages/database/src/exp/Reference.ts index 6598f983c74..0934e8e183d 100644 --- a/packages/database/src/exp/Reference.ts +++ b/packages/database/src/exp/Reference.ts @@ -31,9 +31,8 @@ import { QueryContext } from '../core/view/EventRegistration'; * `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. + * See {@link https://firebase.google.com/docs/database/web/lists-of-data#sorting_and_filtering_data} + * for more information. */ export interface Query extends QueryContext { /** The `Reference` for the `Query`'s location. */ @@ -89,8 +88,7 @@ export interface Query extends QueryContext { * * 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} + * https://firebase.google.com/docs/database/web/read-and-write} */ export interface Reference extends Query { /** diff --git a/packages/database/src/exp/Reference_impl.ts b/packages/database/src/exp/Reference_impl.ts index d29628bd5e4..599b32c8bd5 100644 --- a/packages/database/src/exp/Reference_impl.ts +++ b/packages/database/src/exp/Reference_impl.ts @@ -90,7 +90,8 @@ import { ListenOptions, Query as Query, Reference as Reference, - Unsubscribe + Unsubscribe, + ThenableReference } from './Reference'; export class QueryImpl implements Query, QueryContext { @@ -281,9 +282,9 @@ export class ReferenceImpl extends QueryImpl implements Reference { */ export class DataSnapshot { /** - * @param _node A SnapshotNode to wrap. - * @param ref The location this snapshot came from. - * @param _index The iteration order for this snapshot + * @param _node - A SnapshotNode to wrap. + * @param ref - The location this snapshot came from. + * @param _index - The iteration order for this snapshot * @hideconstructor */ constructor( @@ -297,9 +298,8 @@ export class 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}). + * {@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) @@ -537,10 +537,9 @@ export function child(parent: Reference, path: string): ReferenceImpl { } /** - * 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. + * 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. */ @@ -568,22 +567,15 @@ export interface ThenableReferenceImpl * 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} + * 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 ttps://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. * @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( - parent: Reference, - value?: unknown -): ThenableReferenceImpl { +export function push(parent: Reference, value?: unknown): ThenableReference { parent = getModularInstance(parent); validateWritablePath('push', parent._path); validateFirebaseDataArg('push', value, parent._path, true); @@ -678,9 +670,9 @@ export function set(ref: Reference, value: unknown): 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}). + * 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). @@ -709,9 +701,9 @@ export function setPriority( * 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}). + * 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, @@ -770,9 +762,8 @@ export function setWithPriority( * * 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}. + * 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. @@ -1012,8 +1003,8 @@ function addEventListener( * 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. + * {@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 @@ -1044,8 +1035,8 @@ export function onValue( * 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. + * {@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 @@ -1073,8 +1064,8 @@ export function onValue( * 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. + * {@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 @@ -1123,8 +1114,8 @@ export function onValue( * 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. + * {@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 @@ -1159,8 +1150,8 @@ export function onChildAdded( * 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. + * {@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 @@ -1192,8 +1183,8 @@ export function onChildAdded( * 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. + * {@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 @@ -1249,8 +1240,8 @@ export function onChildAdded( * 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. + * {@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 @@ -1286,8 +1277,8 @@ export function onChildChanged( * 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. + * {@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 @@ -1320,8 +1311,8 @@ export function onChildChanged( * 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. + * {@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 @@ -1378,8 +1369,8 @@ export function onChildChanged( * 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. + * {@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` @@ -1413,8 +1404,8 @@ export function onChildMoved( * 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. + * {@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` @@ -1445,8 +1436,8 @@ export function onChildMoved( * 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. + * {@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` @@ -1501,8 +1492,8 @@ export function onChildMoved( * 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. + * {@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 @@ -1537,8 +1528,8 @@ export function onChildRemoved( * 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. + * {@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 @@ -1570,8 +1561,8 @@ export function onChildRemoved( * 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. + * {@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 @@ -1638,10 +1629,10 @@ export { EventType }; * callbacks. * * @param query - The query that the listener was registered with. - * @param eventType One of the following strings: "value", "child_added", + * @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 + * @param callback - The callback function that was passed to `on()` or * `undefined` to remove all callbacks. */ export function off( @@ -1748,9 +1739,8 @@ class QueryEndAtConstraint extends QueryConstraint { * 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}. + * 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 @@ -1875,9 +1865,8 @@ class QueryStartAtConstraint extends QueryConstraint { * 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}. + * 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 @@ -1939,7 +1928,7 @@ class QueryStartAfterConstraint extends QueryConstraint { * 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 + * @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. @@ -1990,9 +1979,8 @@ class QueryLimitToFirstConstraint extends QueryConstraint { * `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}. + * 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. */ @@ -2039,9 +2027,8 @@ class QueryLimitToLastConstraint extends QueryConstraint { * `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}. + * 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. */ @@ -2090,12 +2077,11 @@ class QueryOrderByChildConstraint extends QueryConstraint { * 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. + * the{@link https://firebase.google.com/docs/database/security/indexing-data} + * 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}. + * 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. */ @@ -2138,9 +2124,8 @@ class QueryOrderByKeyConstraint extends QueryConstraint { * * 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}. + * 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(); @@ -2166,9 +2151,9 @@ 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. + * 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(); @@ -2196,9 +2181,8 @@ class QueryOrderByValueConstraint extends QueryConstraint { * 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}. + * 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(); @@ -2246,9 +2230,8 @@ class QueryEqualToValueConstraint extends QueryConstraint { * 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}. + * 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 diff --git a/packages/database/src/exp/ServerValue.ts b/packages/database/src/exp/ServerValue.ts index 30cdffdd509..c8fa7825d42 100644 --- a/packages/database/src/exp/ServerValue.ts +++ b/packages/database/src/exp/ServerValue.ts @@ -32,7 +32,7 @@ export function serverTimestamp(): object { * 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. + * @param delta - the amount to modify the current value atomically. * @returns A placeholder value for modifying data atomically server-side. */ export function increment(delta: number): object { diff --git a/packages/database/src/realtime/BrowserPollConnection.ts b/packages/database/src/realtime/BrowserPollConnection.ts index 5eb864972a8..4f60632d1f1 100644 --- a/packages/database/src/realtime/BrowserPollConnection.ts +++ b/packages/database/src/realtime/BrowserPollConnection.ts @@ -99,12 +99,12 @@ export class BrowserPollConnection implements Transport { private onDisconnect_: ((a?: boolean) => void) | null; /** - * @param connId An identifier for this connection, used for logging - * @param repoInfo The info for the endpoint to send data to. - * @param applicationId The Firebase App ID for this project. - * @param transportSessionId Optional transportSessionid if we are reconnecting for an existing + * @param connId - An identifier for this connection, used for logging + * @param repoInfo - The info for the endpoint to send data to. + * @param applicationId - The Firebase App ID for this project. + * @param transportSessionId - Optional transportSessionid if we are reconnecting for an existing * transport session - * @param lastSessionId Optional lastSessionId if the PersistentConnection has already created a + * @param lastSessionId - Optional lastSessionId if the PersistentConnection has already created a * connection previously */ constructor( @@ -121,8 +121,8 @@ export class BrowserPollConnection implements Transport { } /** - * @param onMessage Callback when messages arrive - * @param onDisconnect Callback with connection lost. + * @param onMessage - Callback when messages arrive + * @param onDisconnect - Callback with connection lost. */ open(onMessage: (msg: {}) => void, onDisconnect: (a?: boolean) => void) { this.curSegmentNum = 0; @@ -330,7 +330,7 @@ export class BrowserPollConnection implements Transport { /** * Send the JSON object down to the server. It will need to be stringified, base64 encoded, and then * broken into chunks (since URLs have a small maximum length). - * @param data The JSON data to transmit. + * @param data - The JSON data to transmit. */ send(data: {}) { const dataStr = stringify(data); diff --git a/packages/database/src/realtime/Connection.ts b/packages/database/src/realtime/Connection.ts index 25f86aeb411..6c2ef7967ec 100644 --- a/packages/database/src/realtime/Connection.ts +++ b/packages/database/src/realtime/Connection.ts @@ -212,7 +212,7 @@ export class Connection { } /** - * @param dataMsg An arbitrary data message to be sent to the server + * @param dataMsg - An arbitrary data message to be sent to the server */ sendRequest(dataMsg: object) { // wrap in a data message envelope and send it on @@ -367,7 +367,7 @@ export class Connection { } /** - * @param handshake The handshake data returned from the server + * @param handshake - The handshake data returned from the server */ private onHandshake_(handshake: { ts: number; @@ -478,7 +478,7 @@ export class Connection { } /** - * @param everConnected Whether or not the connection ever reached a server. Used to determine if + * @param everConnected - Whether or not the connection ever reached a server. Used to determine if * we should flush the host cache */ private onConnectionLost_(everConnected: boolean) { diff --git a/packages/database/src/realtime/Transport.ts b/packages/database/src/realtime/Transport.ts index c8d6839be1d..f3433c4c354 100644 --- a/packages/database/src/realtime/Transport.ts +++ b/packages/database/src/realtime/Transport.ts @@ -47,10 +47,10 @@ export abstract class Transport { abstract connId: string; /** - * @param connId An identifier for this connection, used for logging - * @param repoInfo The info for the endpoint to send data to. - * @param transportSessionId Optional transportSessionId if this is connecting to an existing transport session - * @param lastSessionId Optional lastSessionId if there was a previous connection + * @param connId - An identifier for this connection, used for logging + * @param repoInfo - The info for the endpoint to send data to. + * @param transportSessionId - Optional transportSessionId if this is connecting to an existing transport session + * @param lastSessionId - Optional lastSessionId if there was a previous connection * @interface */ // eslint-disable-next-line @typescript-eslint/no-useless-constructor @@ -62,8 +62,8 @@ export abstract class Transport { ) {} /** - * @param onMessage Callback when messages arrive - * @param onDisconnect Callback with connection lost. + * @param onMessage - Callback when messages arrive + * @param onDisconnect - Callback with connection lost. */ abstract open( onMessage: (a: {}) => void, @@ -75,7 +75,7 @@ export abstract class Transport { abstract close(): void; /** - * @param data The JSON data to transmit + * @param data - The JSON data to transmit */ abstract send(data: {}): void; diff --git a/packages/database/src/realtime/TransportManager.ts b/packages/database/src/realtime/TransportManager.ts index 19ec62dc2e4..36d732fb840 100644 --- a/packages/database/src/realtime/TransportManager.ts +++ b/packages/database/src/realtime/TransportManager.ts @@ -37,7 +37,7 @@ export class TransportManager { } /** - * @param repoInfo Metadata around the namespace we're connecting to + * @param repoInfo - Metadata around the namespace we're connecting to */ constructor(repoInfo: RepoInfo) { this.initTransports_(repoInfo); diff --git a/packages/database/src/realtime/WebSocketConnection.ts b/packages/database/src/realtime/WebSocketConnection.ts index 929f2f799d1..dad520c3bc0 100644 --- a/packages/database/src/realtime/WebSocketConnection.ts +++ b/packages/database/src/realtime/WebSocketConnection.ts @@ -73,12 +73,12 @@ export class WebSocketConnection implements Transport { private nodeAdmin: boolean; /** - * @param connId identifier for this transport - * @param repoInfo The info for the websocket endpoint. - * @param applicationId The Firebase App ID for this project. - * @param transportSessionId Optional transportSessionId if this is connecting to an existing transport + * @param connId - identifier for this transport + * @param repoInfo - The info for the websocket endpoint. + * @param applicationId - The Firebase App ID for this project. + * @param transportSessionId - Optional transportSessionId if this is connecting to an existing transport * session - * @param lastSessionId Optional lastSessionId if there was a previous connection + * @param lastSessionId - Optional lastSessionId if there was a previous connection */ constructor( public connId: string, @@ -98,10 +98,10 @@ export class WebSocketConnection implements Transport { } /** - * @param repoInfo The info for the websocket endpoint. - * @param transportSessionId Optional transportSessionId if this is connecting to an existing transport + * @param repoInfo - The info for the websocket endpoint. + * @param transportSessionId - Optional transportSessionId if this is connecting to an existing transport * session - * @param lastSessionId Optional lastSessionId if there was a previous connection + * @param lastSessionId - Optional lastSessionId if there was a previous connection * @returns connection url */ private static connectionURL_( @@ -130,8 +130,8 @@ export class WebSocketConnection implements Transport { } /** - * @param onMessage Callback when messages arrive - * @param onDisconnect Callback with connection lost. + * @param onMessage - Callback when messages arrive + * @param onDisconnect - Callback with connection lost. */ open(onMessage: (msg: {}) => void, onDisconnect: (a?: boolean) => void) { this.onDisconnect = onDisconnect; @@ -279,7 +279,7 @@ export class WebSocketConnection implements Transport { } /** - * @param frameCount The number of frames we are expecting from the server + * @param frameCount - The number of frames we are expecting from the server */ private handleNewFrameCount_(frameCount: number) { this.totalFrames = frameCount; @@ -307,7 +307,7 @@ export class WebSocketConnection implements Transport { /** * Process a websocket frame that has arrived from the server. - * @param mess The frame data + * @param mess - The frame data */ handleIncomingFrame(mess: { [k: string]: unknown }) { if (this.mySock === null) { @@ -333,7 +333,7 @@ export class WebSocketConnection implements Transport { /** * Send a message to the server - * @param data The JSON object to transmit + * @param data - The JSON object to transmit */ send(data: {}) { this.resetKeepAlive(); @@ -414,7 +414,7 @@ export class WebSocketConnection implements Transport { /** * Send a string over the websocket. * - * @param str String to send. + * @param str - String to send. */ private sendString_(str: string) { // Firefox seems to sometimes throw exceptions (NS_ERROR_UNEXPECTED) from websocket .send() diff --git a/packages/database/test/helpers/events.ts b/packages/database/test/helpers/events.ts index 20be8461d70..144ea2b10d5 100644 --- a/packages/database/test/helpers/events.ts +++ b/packages/database/test/helpers/events.ts @@ -42,7 +42,7 @@ function rawPath(firebaseRef: Reference) { /** * Creates a struct which waits for many events. - * @param pathAndEvents an array of tuples of [Firebase, [event type strings]] + * @param pathAndEvents - an array of tuples of [Firebase, [event type strings]] */ export function eventTestHelper(pathAndEvents, helperName?) { let resolve, reject; diff --git a/repo-scripts/prune-dts/prune-dts.ts b/repo-scripts/prune-dts/prune-dts.ts index a2ac2fbb101..745d0f8ab26 100644 --- a/repo-scripts/prune-dts/prune-dts.ts +++ b/repo-scripts/prune-dts/prune-dts.ts @@ -79,7 +79,7 @@ export async function removeUnusedImports( function hasPrivatePrefix(name: ts.Identifier): boolean { // Identifiers that are prefixed with an underscore are not not included in // the public API. - return name.escapedText.toString().startsWith('_'); + return !!name.escapedText?.toString().startsWith('_'); } /** Returns whether type identified by `name` is exported. */ From e3b6c9336891d4363f0826569c91d7d0c2aee52b Mon Sep 17 00:00:00 2001 From: Sebastian Schmidt Date: Tue, 6 Apr 2021 15:42:03 -0600 Subject: [PATCH 2/4] Allow extra script dependencies --- packages/database/.eslintrc.js | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/packages/database/.eslintrc.js b/packages/database/.eslintrc.js index d569aa23a76..3a04a986c41 100644 --- a/packages/database/.eslintrc.js +++ b/packages/database/.eslintrc.js @@ -53,6 +53,12 @@ module.exports = { rules: { '@typescript-eslint/no-explicit-any': 'off' } + }, + { + files: ['scripts/*.ts'], + rules: { + 'import/no-extraneous-dependencies': 'off' + } } ] }; From 925409cf811e4756b836e98b7998e5f98a669e88 Mon Sep 17 00:00:00 2001 From: Sebastian Schmidt Date: Wed, 7 Apr 2021 09:52:57 -0600 Subject: [PATCH 3/4] Add API Review file --- common/api-review/database-exp.api.md | 241 ++++++++++++++++++++++++++ 1 file changed, 241 insertions(+) create mode 100644 common/api-review/database-exp.api.md diff --git a/common/api-review/database-exp.api.md b/common/api-review/database-exp.api.md new file mode 100644 index 00000000000..718e32cc15a --- /dev/null +++ b/common/api-review/database-exp.api.md @@ -0,0 +1,241 @@ +## API Report File for "@firebase/database-exp" + +> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/). + +```ts + +import { FirebaseApp } from '@firebase/app'; + +// @public (undocumented) +export class DataSnapshot { + child(path: string): DataSnapshot; + exists(): boolean; + exportVal(): any; + forEach(action: (child: DataSnapshot) => boolean | void): boolean; + hasChild(path: string): boolean; + hasChildren(): boolean; + get key(): string | null; + get priority(): string | number | null; + // (undocumented) + readonly ref: Reference; + get size(): number; + toJSON(): object | null; + val(): any; +} + +// @public +export function enableLogging(enabled: boolean, persistent?: boolean): any; + +// @public +export function enableLogging(logger?: (message: string) => unknown, persistent?: boolean): any; + +// @public +export function endAt(value: number | string | boolean | null, key?: string): QueryConstraint; + +// @public +export function endBefore(value: number | string | boolean | null, key?: string): QueryConstraint; + +// @public +export function equalTo(value: number | string | boolean | null, key?: string): QueryConstraint; + +// @public +export type EventType = 'value' | 'child_added' | 'child_changed' | 'child_moved' | 'child_removed'; + +// @public +export class FirebaseDatabase { + // (undocumented) + readonly app: FirebaseApp; + // (undocumented) + readonly 'type' = "database"; +} + +// @public +export function get(query: Query): Promise; + +// @public +export function getDatabase(app: FirebaseApp, url?: string): FirebaseDatabase; + +// @public +export function goOffline(db: FirebaseDatabase): void; + +// @public +export function goOnline(db: FirebaseDatabase): void; + +// @public +export function increment(delta: number): object; + +// @public +export function limitToFirst(limit: number): QueryConstraint; + +// @public +export function limitToLast(limit: number): QueryConstraint; + +// @public +export interface ListenOptions { + readonly onlyOnce?: boolean; +} + +// @public +export function off(query: Query, eventType?: EventType, callback?: (snapshot: DataSnapshot, previousChildName?: string | null) => unknown): void; + +// @public +export function onChildAdded(query: Query, callback: (snapshot: DataSnapshot, previousChildName?: string | null) => unknown, cancelCallback?: (error: Error) => unknown): Unsubscribe; + +// @public +export function onChildAdded(query: Query, callback: (snapshot: DataSnapshot, previousChildName: string | null) => unknown, options: ListenOptions): Unsubscribe; + +// @public +export function onChildAdded(query: Query, callback: (snapshot: DataSnapshot, previousChildName: string | null) => unknown, cancelCallback: (error: Error) => unknown, options: ListenOptions): Unsubscribe; + +// @public +export function onChildChanged(query: Query, callback: (snapshot: DataSnapshot, previousChildName: string | null) => unknown, cancelCallback?: (error: Error) => unknown): Unsubscribe; + +// @public +export function onChildChanged(query: Query, callback: (snapshot: DataSnapshot, previousChildName: string | null) => unknown, options: ListenOptions): Unsubscribe; + +// @public +export function onChildChanged(query: Query, callback: (snapshot: DataSnapshot, previousChildName: string | null) => unknown, cancelCallback: (error: Error) => unknown, options: ListenOptions): Unsubscribe; + +// @public +export function onChildMoved(query: Query, callback: (snapshot: DataSnapshot, previousChildName: string | null) => unknown, cancelCallback?: (error: Error) => unknown): Unsubscribe; + +// @public +export function onChildMoved(query: Query, callback: (snapshot: DataSnapshot, previousChildName: string | null) => unknown, options: ListenOptions): Unsubscribe; + +// @public +export function onChildMoved(query: Query, callback: (snapshot: DataSnapshot, previousChildName: string | null) => unknown, cancelCallback: (error: Error) => unknown, options: ListenOptions): Unsubscribe; + +// @public +export function onChildRemoved(query: Query, callback: (snapshot: DataSnapshot) => unknown, cancelCallback?: (error: Error) => unknown): Unsubscribe; + +// @public +export function onChildRemoved(query: Query, callback: (snapshot: DataSnapshot) => unknown, options: ListenOptions): Unsubscribe; + +// @public +export function onChildRemoved(query: Query, callback: (snapshot: DataSnapshot) => unknown, cancelCallback: (error: Error) => unknown, options: ListenOptions): Unsubscribe; + +// @public +export class OnDisconnect { + cancel(): Promise; + remove(): Promise; + set(value: unknown): Promise; + setWithPriority(value: unknown, priority: number | string | null): Promise; + update(values: object): Promise; +} + +// @public +export function onDisconnect(ref: Reference): OnDisconnect; + +// @public +export function onValue(query: Query, callback: (snapshot: DataSnapshot) => unknown, cancelCallback?: (error: Error) => unknown): Unsubscribe; + +// @public +export function onValue(query: Query, callback: (snapshot: DataSnapshot) => unknown, options: ListenOptions): Unsubscribe; + +// @public +export function onValue(query: Query, callback: (snapshot: DataSnapshot) => unknown, cancelCallback: (error: Error) => unknown, options: ListenOptions): Unsubscribe; + +// @public +export function orderByChild(path: string): QueryConstraint; + +// @public +export function orderByKey(): QueryConstraint; + +// @public +export function orderByPriority(): QueryConstraint; + +// @public +export function orderByValue(): QueryConstraint; + +// @public +export function push(parent: Reference, value?: unknown): ThenableReference; + +// @public +export interface Query { + isEqual(other: Query | null): boolean; + readonly ref: Reference; + toJSON(): string; + toString(): string; +} + +// @public +export function query(query: Query, ...queryConstraints: QueryConstraint[]): Query; + +// @public +export abstract class QueryConstraint { + abstract readonly type: QueryConstraintType; +} + +// @public +export type QueryConstraintType = 'endAt' | 'endBefore' | 'startAt' | 'startAfter' | 'limitToFirst' | 'limitToLast' | 'orderByChild' | 'orderByKey' | 'orderByPriority' | 'orderByValue' | 'equalTo'; + +// @public +export function ref(db: FirebaseDatabase, path?: string): Reference; + +// @public +export interface Reference extends Query { + readonly key: string | null; + readonly parent: Reference | null; + readonly root: Reference; +} + +// @public +export function refFromURL(db: FirebaseDatabase, url: string): Reference; + +// @public +export function remove(ref: Reference): Promise; + +// @public +export function runTransaction(ref: Reference, transactionUpdate: (currentData: any) => unknown, options?: TransactionOptions): Promise; + +// @public +export function serverTimestamp(): object; + +// @public +export function set(ref: Reference, value: unknown): Promise; + +// @public +export function setPriority(ref: Reference, priority: string | number | null): Promise; + +// @public +export function setWithPriority(ref: Reference, value: unknown, priority: string | number | null): Promise; + +// @public +export function startAfter(value: number | string | boolean | null, key?: string): QueryConstraint; + +// @public +export function startAt(value?: number | string | boolean | null, key?: string): QueryConstraint; + +// @public +export interface ThenableReference extends Reference, Pick, 'then' | 'catch'> { +} + +// @public +export interface TransactionOptions { + readonly applyLocally?: boolean; +} + +// @public (undocumented) +export class TransactionResult { + constructor(committed: boolean, snapshot: DataSnapshot); + // (undocumented) + readonly committed: boolean; + // (undocumented) + readonly snapshot: DataSnapshot; + // (undocumented) + toJSON(): object; +} + +// @public +export type Unsubscribe = () => void; + +// @public +export function update(ref: Reference, values: object): Promise; + +// @public +export function useDatabaseEmulator(db: FirebaseDatabase, host: string, port: number): void; + + +// (No @packageDocumentation comment for this package) + +``` From bc540563866021ee5e6b6b3b3ddd934bba7ad857 Mon Sep 17 00:00:00 2001 From: Sebastian Schmidt Date: Wed, 7 Apr 2021 10:03:22 -0600 Subject: [PATCH 4/4] Fix undocumented docs --- common/api-review/database-exp.api.md | 9 +-------- packages/database/src/api/Reference.ts | 1 + packages/database/src/exp/Database.ts | 7 ++++++- packages/database/src/exp/Reference_impl.ts | 1 + packages/database/src/exp/Transaction.ts | 15 +++++++++++---- 5 files changed, 20 insertions(+), 13 deletions(-) diff --git a/common/api-review/database-exp.api.md b/common/api-review/database-exp.api.md index 718e32cc15a..7a36c6f43b1 100644 --- a/common/api-review/database-exp.api.md +++ b/common/api-review/database-exp.api.md @@ -16,7 +16,6 @@ export class DataSnapshot { hasChildren(): boolean; get key(): string | null; get priority(): string | number | null; - // (undocumented) readonly ref: Reference; get size(): number; toJSON(): object | null; @@ -43,9 +42,7 @@ export type EventType = 'value' | 'child_added' | 'child_changed' | 'child_moved // @public export class FirebaseDatabase { - // (undocumented) readonly app: FirebaseApp; - // (undocumented) readonly 'type' = "database"; } @@ -215,14 +212,10 @@ export interface TransactionOptions { readonly applyLocally?: boolean; } -// @public (undocumented) +// @public export class TransactionResult { - constructor(committed: boolean, snapshot: DataSnapshot); - // (undocumented) readonly committed: boolean; - // (undocumented) readonly snapshot: DataSnapshot; - // (undocumented) toJSON(): object; } diff --git a/packages/database/src/api/Reference.ts b/packages/database/src/api/Reference.ts index 98315eb1370..7e1328d9dca 100644 --- a/packages/database/src/api/Reference.ts +++ b/packages/database/src/api/Reference.ts @@ -72,6 +72,7 @@ import { runTransaction } from '../exp/Transaction'; import { Database } from './Database'; import { OnDisconnect } from './onDisconnect'; import { TransactionResult } from './TransactionResult'; + /** * Class representing a firebase data snapshot. It wraps a SnapshotNode and * surfaces the public methods (val, forEach, etc.) we want to expose. diff --git a/packages/database/src/exp/Database.ts b/packages/database/src/exp/Database.ts index 0d9981beb1d..77d083bc66b 100644 --- a/packages/database/src/exp/Database.ts +++ b/packages/database/src/exp/Database.ts @@ -200,6 +200,7 @@ export function repoManagerForceRestClient(forceRestClient: boolean): void { * Class representing a Firebase Realtime Database. */ export class FirebaseDatabase implements _FirebaseService { + /** Represents a database instance. */ readonly 'type' = 'database'; /** Track if the instance has been used (root or repo accessed) */ @@ -209,7 +210,11 @@ export class FirebaseDatabase implements _FirebaseService { private _rootInternal?: ReferenceImpl; /** @hideconstructor */ - constructor(private _repoInternal: Repo, readonly app: FirebaseApp) {} + constructor( + private _repoInternal: Repo, + /** The FirebaseApp associated with this Realtime Database instance. */ + readonly app: FirebaseApp + ) {} get _repo(): Repo { if (!this._instanceStarted) { diff --git a/packages/database/src/exp/Reference_impl.ts b/packages/database/src/exp/Reference_impl.ts index 599b32c8bd5..4f4d6b7e754 100644 --- a/packages/database/src/exp/Reference_impl.ts +++ b/packages/database/src/exp/Reference_impl.ts @@ -289,6 +289,7 @@ export class DataSnapshot { */ constructor( readonly _node: Node, + /** The location of this DataSnapshot. */ readonly ref: ReferenceImpl, readonly _index: Index ) {} diff --git a/packages/database/src/exp/Transaction.ts b/packages/database/src/exp/Transaction.ts index a7555ec3f99..66304cc55c3 100644 --- a/packages/database/src/exp/Transaction.ts +++ b/packages/database/src/exp/Transaction.ts @@ -36,12 +36,19 @@ export interface TransactionOptions { readonly applyLocally?: boolean; } +/** + * A type for the resolve value of Firebase.transaction. + */ export class TransactionResult { - /** - * A type for the resolve value of Firebase.transaction. - */ - constructor(readonly committed: boolean, readonly snapshot: DataSnapshot) {} + /** @hideconstructor */ + constructor( + /** Whether the transaction was successfully committed. */ + readonly committed: boolean, + /** The resulting data snapshot. */ + readonly snapshot: DataSnapshot + ) {} + /** Returns a JSON-serializable representation of this object. */ toJSON(): object { return { committed: this.committed, snapshot: this.snapshot.toJSON() }; }