Add Support for API report

Pruned DTS file: https://gist.github.com/schmidt-sebastian/2401be010ce057988495823ffe446a1d

Author: schmidt-sebastian

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 {

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"
 }

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,

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"
   },

packages/database/scripts/api-report.ts

@@ -0,0 +1,176 @@
+/**
+ * @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';
+
+/* 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<void> {
+  // 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();

packages/database/src/api/Database.ts

@@ -54,8 +54,8 @@ export class Database implements FirebaseService, Compat<ExpDatabase> {
    *
    * <p>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<ExpDatabase> {
    * 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.

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<ExpDataSnapshot> {
   /**
    * 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<ExpDataSnapshot> {
   /**
    * 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<ExpDataSnapshot> {
   /**
    * 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<QueryImpl> {
 
   /**
    * 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<ReferenceImpl> {
     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)
     );

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<T>({
   app,