From 1271dd95405ad97e7117b6872ac0923ce095a476 Mon Sep 17 00:00:00 2001 From: Hiranya Jayathilaka Date: Mon, 11 Jan 2021 16:29:29 -0800 Subject: [PATCH 1/3] fix: Added lightweight App interface --- docgen/generate-docs.js | 1 + gulpfile.js | 1 + src/core.ts | 143 ++++++++++++++++++++++++++++++++++ src/firebase-namespace-api.ts | 130 ++----------------------------- 4 files changed, 150 insertions(+), 125 deletions(-) create mode 100644 src/core.ts diff --git a/docgen/generate-docs.js b/docgen/generate-docs.js index 4f8b8df736..7025ff8da5 100644 --- a/docgen/generate-docs.js +++ b/docgen/generate-docs.js @@ -28,6 +28,7 @@ const repoPath = path.resolve(`${__dirname}/..`); const defaultSources = [ `${repoPath}/lib/firebase-namespace.d.ts`, `${repoPath}/lib/firebase-namespace-api.d.ts`, + `${repoPath}/lib/core.d.ts`, `${repoPath}/lib/**/*.d.ts`, ]; diff --git a/gulpfile.js b/gulpfile.js index 9ca1aeb941..3776404b3e 100644 --- a/gulpfile.js +++ b/gulpfile.js @@ -86,6 +86,7 @@ gulp.task('compile', function() { 'lib/**/*.js', 'lib/**/index.d.ts', 'lib/firebase-namespace-api.d.ts', + 'lib/core.d.ts', '!lib/utils/index.d.ts', ]; diff --git a/src/core.ts b/src/core.ts new file mode 100644 index 0000000000..243e231f0f --- /dev/null +++ b/src/core.ts @@ -0,0 +1,143 @@ +/*! + * Copyright 2021 Google Inc. + * + * 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 { Agent } from 'http'; + +import { credential } from './credential/index'; + +/** + * Available options to pass to [`initializeApp()`](admin#.initializeApp). + */ +export interface AppOptions { + + /** + * A {@link credential.Credential `Credential`} object used to + * authenticate the Admin SDK. + * + * See [Initialize the SDK](/docs/admin/setup#initialize_the_sdk) for detailed + * documentation and code samples. + */ + credential?: credential.Credential; + + /** + * The object to use as the [`auth`](/docs/reference/security/database/#auth) + * variable in your Realtime Database Rules when the Admin SDK reads from or + * writes to the Realtime Database. This allows you to downscope the Admin SDK + * from its default full read and write privileges. + * + * You can pass `null` to act as an unauthenticated client. + * + * See + * [Authenticate with limited privileges](/docs/database/admin/start#authenticate-with-limited-privileges) + * for detailed documentation and code samples. + */ + databaseAuthVariableOverride?: object | null; + + /** + * The URL of the Realtime Database from which to read and write data. + */ + databaseURL?: string; + + /** + * The ID of the service account to be used for signing custom tokens. This + * can be found in the `client_email` field of a service account JSON file. + */ + serviceAccountId?: string; + + /** + * The name of the Google Cloud Storage bucket used for storing application data. + * Use only the bucket name without any prefixes or additions (do *not* prefix + * the name with "gs://"). + */ + storageBucket?: string; + + /** + * The ID of the Google Cloud project associated with the App. + */ + projectId?: string; + + /** + * An [HTTP Agent](https://nodejs.org/api/http.html#http_class_http_agent) + * to be used when making outgoing HTTP calls. This Agent instance is used + * by all services that make REST calls (e.g. `auth`, `messaging`, + * `projectManagement`). + * + * Realtime Database and Firestore use other means of communicating with + * the backend servers, so they do not use this HTTP Agent. `Credential` + * instances also do not use this HTTP Agent, but instead support + * specifying an HTTP Agent in the corresponding factory methods. + */ + httpAgent?: Agent; +} + +export interface App { + + /** + * The (read-only) name for this app. + * + * The default app's name is `"[DEFAULT]"`. + * + * @example + * ```javascript + * // The default app's name is "[DEFAULT]" + * admin.initializeApp(defaultAppConfig); + * console.log(admin.app().name); // "[DEFAULT]" + * ``` + * + * @example + * ```javascript + * // A named app's name is what you provide to initializeApp() + * var otherApp = admin.initializeApp(otherAppConfig, "other"); + * console.log(otherApp.name); // "other" + * ``` + */ + name: string; + + /** + * The (read-only) configuration options for this app. These are the original + * parameters given in + * {@link + * https://firebase.google.com/docs/reference/admin/node/admin#.initializeApp + * `admin.initializeApp()`}. + * + * @example + * ```javascript + * var app = admin.initializeApp(config); + * console.log(app.options.credential === config.credential); // true + * console.log(app.options.databaseURL === config.databaseURL); // true + * ``` + */ + options: AppOptions; + + /** + * Renders this local `FirebaseApp` unusable and frees the resources of + * all associated services (though it does *not* clean up any backend + * resources). When running the SDK locally, this method + * must be called to ensure graceful termination of the process. + * + * @example + * ```javascript + * app.delete() + * .then(function() { + * console.log("App deleted successfully"); + * }) + * .catch(function(error) { + * console.log("Error deleting app:", error); + * }); + * ``` + */ + delete(): Promise; +} \ No newline at end of file diff --git a/src/firebase-namespace-api.ts b/src/firebase-namespace-api.ts index 36df1b778d..b79810c5f8 100644 --- a/src/firebase-namespace-api.ts +++ b/src/firebase-namespace-api.ts @@ -14,9 +14,7 @@ * limitations under the License. */ -import { Agent } from 'http'; import { auth } from './auth/index'; -import { credential } from './credential/index'; import { database } from './database/index'; import { firestore } from './firestore/index'; import { instanceId } from './instance-id/index'; @@ -27,6 +25,10 @@ import { remoteConfig } from './remote-config/index'; import { securityRules } from './security-rules/index'; import { storage } from './storage/index'; +import { AppOptions, App as AppCore } from './core'; + +export { AppOptions }; + /** * `FirebaseError` is a subclass of the standard JavaScript `Error` object. In * addition to a message string and stack trace, it contains a string code. @@ -106,71 +108,6 @@ export interface FirebaseArrayIndexError { error: FirebaseError; } -/** - * Available options to pass to [`initializeApp()`](admin#.initializeApp). - */ -export interface AppOptions { - - /** - * A {@link credential.Credential `Credential`} object used to - * authenticate the Admin SDK. - * - * See [Initialize the SDK](/docs/admin/setup#initialize_the_sdk) for detailed - * documentation and code samples. - */ - credential?: credential.Credential; - - /** - * The object to use as the [`auth`](/docs/reference/security/database/#auth) - * variable in your Realtime Database Rules when the Admin SDK reads from or - * writes to the Realtime Database. This allows you to downscope the Admin SDK - * from its default full read and write privileges. - * - * You can pass `null` to act as an unauthenticated client. - * - * See - * [Authenticate with limited privileges](/docs/database/admin/start#authenticate-with-limited-privileges) - * for detailed documentation and code samples. - */ - databaseAuthVariableOverride?: object | null; - - /** - * The URL of the Realtime Database from which to read and write data. - */ - databaseURL?: string; - - /** - * The ID of the service account to be used for signing custom tokens. This - * can be found in the `client_email` field of a service account JSON file. - */ - serviceAccountId?: string; - - /** - * The name of the Google Cloud Storage bucket used for storing application data. - * Use only the bucket name without any prefixes or additions (do *not* prefix - * the name with "gs://"). - */ - storageBucket?: string; - - /** - * The ID of the Google Cloud project associated with the App. - */ - projectId?: string; - - /** - * An [HTTP Agent](https://nodejs.org/api/http.html#http_class_http_agent) - * to be used when making outgoing HTTP calls. This Agent instance is used - * by all services that make REST calls (e.g. `auth`, `messaging`, - * `projectManagement`). - * - * Realtime Database and Firestore use other means of communicating with - * the backend servers, so they do not use this HTTP Agent. `Credential` - * instances also do not use this HTTP Agent, but instead support - * specifying an HTTP Agent in the corresponding factory methods. - */ - httpAgent?: Agent; -} - // eslint-disable-next-line @typescript-eslint/no-namespace export namespace app { /** @@ -183,45 +120,7 @@ export namespace app { * `admin.initializeApp()`} * to create an app. */ - export interface App { - - /** - * The (read-only) name for this app. - * - * The default app's name is `"[DEFAULT]"`. - * - * @example - * ```javascript - * // The default app's name is "[DEFAULT]" - * admin.initializeApp(defaultAppConfig); - * console.log(admin.app().name); // "[DEFAULT]" - * ``` - * - * @example - * ```javascript - * // A named app's name is what you provide to initializeApp() - * var otherApp = admin.initializeApp(otherAppConfig, "other"); - * console.log(otherApp.name); // "other" - * ``` - */ - name: string; - - /** - * The (read-only) configuration options for this app. These are the original - * parameters given in - * {@link - * https://firebase.google.com/docs/reference/admin/node/admin#.initializeApp - * `admin.initializeApp()`}. - * - * @example - * ```javascript - * var app = admin.initializeApp(config); - * console.log(app.options.credential === config.credential); // true - * console.log(app.options.databaseURL === config.databaseURL); // true - * ``` - */ - options: AppOptions; - + export interface App extends AppCore { auth(): auth.Auth; database(url?: string): database.Database; firestore(): firestore.Firestore; @@ -232,25 +131,6 @@ export namespace app { remoteConfig(): remoteConfig.RemoteConfig; securityRules(): securityRules.SecurityRules; storage(): storage.Storage; - - /** - * Renders this local `FirebaseApp` unusable and frees the resources of - * all associated services (though it does *not* clean up any backend - * resources). When running the SDK locally, this method - * must be called to ensure graceful termination of the process. - * - * @example - * ```javascript - * app.delete() - * .then(function() { - * console.log("App deleted successfully"); - * }) - * .catch(function(error) { - * console.log("Error deleting app:", error); - * }); - * ``` - */ - delete(): Promise; } } From f0253c380685ebfbc71c1b1cfe0f5540dc55783f Mon Sep 17 00:00:00 2001 From: Hiranya Jayathilaka Date: Mon, 11 Jan 2021 16:35:42 -0800 Subject: [PATCH 2/3] fix: Updated API report --- etc/firebase-admin.api.md | 12 ++++++++---- src/core.ts | 2 +- src/firebase-namespace-api.ts | 3 ++- 3 files changed, 11 insertions(+), 6 deletions(-) diff --git a/etc/firebase-admin.api.md b/etc/firebase-admin.api.md index b5b810a5e6..a89b4359c8 100644 --- a/etc/firebase-admin.api.md +++ b/etc/firebase-admin.api.md @@ -9,17 +9,23 @@ import { Bucket } from '@google-cloud/storage'; import * as _firestore from '@google-cloud/firestore'; import * as rtdb from '@firebase/database-types'; +// @public (undocumented) +export interface App { + delete(): Promise; + name: string; + options: AppOptions; +} + // @public (undocumented) export function app(name?: string): app.App; // @public (undocumented) export namespace app { - export interface App { + export interface App extends App { // (undocumented) auth(): auth.Auth; // (undocumented) database(url?: string): database.Database; - delete(): Promise; // (undocumented) firestore(): firestore.Firestore; // (undocumented) @@ -28,8 +34,6 @@ export namespace app { machineLearning(): machineLearning.MachineLearning; // (undocumented) messaging(): messaging.Messaging; - name: string; - options: AppOptions; // (undocumented) projectManagement(): projectManagement.ProjectManagement; // (undocumented) diff --git a/src/core.ts b/src/core.ts index 243e231f0f..b36cc4bb1d 100644 --- a/src/core.ts +++ b/src/core.ts @@ -140,4 +140,4 @@ export interface App { * ``` */ delete(): Promise; -} \ No newline at end of file +} diff --git a/src/firebase-namespace-api.ts b/src/firebase-namespace-api.ts index b79810c5f8..ddbdd2a020 100644 --- a/src/firebase-namespace-api.ts +++ b/src/firebase-namespace-api.ts @@ -25,8 +25,9 @@ import { remoteConfig } from './remote-config/index'; import { securityRules } from './security-rules/index'; import { storage } from './storage/index'; -import { AppOptions, App as AppCore } from './core'; +import { App as AppCore, AppOptions } from './core'; +export { App } from './core'; export { AppOptions }; /** From a67edfd88910f34df6e43e6d8f7ab7c97ad66770 Mon Sep 17 00:00:00 2001 From: Hiranya Jayathilaka Date: Mon, 11 Jan 2021 17:05:45 -0800 Subject: [PATCH 3/3] fix: Consolidated export statements --- src/firebase-namespace-api.ts | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/src/firebase-namespace-api.ts b/src/firebase-namespace-api.ts index ddbdd2a020..da78a8c393 100644 --- a/src/firebase-namespace-api.ts +++ b/src/firebase-namespace-api.ts @@ -27,8 +27,7 @@ import { storage } from './storage/index'; import { App as AppCore, AppOptions } from './core'; -export { App } from './core'; -export { AppOptions }; +export * from './core'; /** * `FirebaseError` is a subclass of the standard JavaScript `Error` object. In