@firebase/app 0.9.29 → 0.10.0-canary.42fcdfe4c

package/dist/app.d.ts

@@ -197,6 +197,88 @@ export declare interface FirebaseOptions {
     measurementId?: string;
 }
 
+/**
+ * A {@link @firebase/app#FirebaseServerApp} holds the initialization information
+ * for a collection of services running in server environments.
+ *
+ * Do not call this constructor directly. Instead, use
+ * {@link (initializeServerApp:1) | initializeServerApp()} to create
+ * an app.
+ *
+ * @public
+ */
+export declare interface FirebaseServerApp extends FirebaseApp {
+    /**
+     * There is no `getApp()` operation for `FirebaseServerApp`, so the name is not relevant for
+     * applications. However, it may be used internally, and is declared here so that
+     * `FirebaseServerApp` conforms to the `FirebaseApp` interface.
+     */
+    name: string;
+    /**
+     * The (read-only) configuration settings for this server app. These are the original
+     * parameters given in {@link (initializeServerApp:1) | initializeServerApp()}.
+     *
+     * @example
+     * ```javascript
+     * const app = initializeServerApp(settings);
+     * console.log(app.settings.authIdToken === options.authIdToken);  // true
+     * ```
+     */
+    readonly settings: FirebaseServerAppSettings;
+}
+
+/**
+ * @public
+ *
+ * Configuration options given to {@link (initializeServerApp:1) | initializeServerApp()}
+ */
+export declare interface FirebaseServerAppSettings extends FirebaseAppSettings {
+    /**
+     * An optional Auth ID token used to resume a signed in user session from a client
+     * runtime environment.
+     *
+     * Invoking `getAuth` with a `FirebaseServerApp` configured with a validated `authIdToken`
+     * causes an automatic attempt to sign in the user that the `authIdToken` represents. The token
+     * needs to have been recently minted for this operation to succeed.
+     *
+     * If the token fails local verification, or if the Auth service has failed to validate it when
+     * the Auth SDK is initialized, then a warning is logged to the console and the Auth SDK will not
+     * sign in a user on initalization.
+     *
+     * If a user is successfully signed in, then the Auth instance's `onAuthStateChanged` callback
+     * is invoked with the `User` object as per standard Auth flows. However, `User` objects
+     * created via an `authIdToken` do not have a refresh token. Attempted `refreshToken`
+     * operations fail.
+     */
+    authIdToken?: string;
+    /**
+     * An optional object. If provided, the Firebase SDK uses a `FinalizationRegistry`
+     * object to monitor the garbage collection status of the provided object. The
+     * Firebase SDK releases its reference on the `FirebaseServerApp` instance when the
+     * provided `releaseOnDeref` object is garbage collected.
+     *
+     * You can use this field to reduce memory management overhead for your application.
+     * If provided, an app running in a SSR pass does not need to perform
+     * `FirebaseServerApp` cleanup, so long as the reference object is deleted (by falling out of
+     * SSR scope, for instance.)
+     *
+     * If an object is not provided then the application must clean up the `FirebaseServerApp`
+     * instance by invoking `deleteApp`.
+     *
+     * If the application provides an object in this parameter, but the application is
+     * executed in a JavaScript engine that predates the support of `FinalizationRegistry`
+     * (introduced in node v14.6.0, for instance), then an error is thrown at `FirebaseServerApp`
+     * initialization.
+     */
+    releaseOnDeref?: object;
+    /**
+     * There is no `getApp()` operation for `FirebaseServerApp`, so the name is not relevant for
+     * applications. However, it may be used internally, and is declared here so that
+     * `FirebaseServerApp` conforms to the `FirebaseApp` interface.
+     */
+    name?: undefined;
+}
+
 /**
  * @internal
  */
@@ -320,6 +402,69 @@ export declare function initializeApp(options: FirebaseOptions, config?: Firebas
  */
 export declare function initializeApp(): FirebaseApp;
 
+/**
+ * Creates and initializes a {@link @firebase/app#FirebaseServerApp} instance.
+ *
+ * The `FirebaseServerApp` is similar to `FirebaseApp`, but is intended for execution in
+ * server side rendering environments only. Initialization will fail if invoked from a
+ * browser environment.
+ *
+ * See
+ * {@link
+ *   https://firebase.google.com/docs/web/setup#add_firebase_to_your_app
+ *   | Add Firebase to your app} and
+ * {@link
+ *   https://firebase.google.com/docs/web/setup#multiple-projects
+ *   | Initialize multiple projects} for detailed documentation.
+ *
+ * @example
+ * ```javascript
+ *
+ * // Initialize an instance of `FirebaseServerApp`.
+ * // Retrieve your own options values by adding a web app on
+ * // https://console.firebase.google.com
+ * initializeServerApp({
+ *     apiKey: "AIza....",                             // Auth / General Use
+ *     authDomain: "YOUR_APP.firebaseapp.com",         // Auth with popup/redirect
+ *     databaseURL: "https://YOUR_APP.firebaseio.com", // Realtime Database
+ *     storageBucket: "YOUR_APP.appspot.com",          // Storage
+ *     messagingSenderId: "123456789"                  // Cloud Messaging
+ *   },
+ *   {
+ *    authIdToken: "Your Auth ID Token"
+ *   });
+ * ```
+ *
+ * @param options - `Firebase.AppOptions` to configure the app's services, or a
+ *   a `FirebaseApp` instance which contains the `AppOptions` within.
+ * @param config - `FirebaseServerApp` configuration.
+ *
+ * @returns The initialized `FirebaseServerApp`.
+ *
+ * @public
+ */
+export declare function initializeServerApp(options: FirebaseOptions | FirebaseApp, config: FirebaseServerAppSettings): FirebaseServerApp;
+
+/**
+ *
+ * @param obj - an object of type FirebaseApp or FirebaseOptions.
+ *
+ * @returns true if the provide object is of type FirebaseApp.
+ *
+ * @internal
+ */
+export declare function _isFirebaseApp(obj: FirebaseApp | FirebaseOptions): obj is FirebaseApp;
+
+/**
+ *
+ * @param obj - an object of type FirebaseApp.
+ *
+ * @returns true if the provided object is of type FirebaseServerAppImpl.
+ *
+ * @internal
+ */
+export declare function _isFirebaseServerApp(obj: FirebaseApp | FirebaseServerApp): obj is FirebaseServerApp;
+
 /**
  * Sets log handler for all Firebase SDKs.
  * @param logCallback - An optional custom log handler that executes user code whenever
@@ -365,6 +510,11 @@ export declare function _removeServiceInstance<T extends Name>(app: FirebaseApp,
  */
 export declare const SDK_VERSION: string;
 
+/**
+ * @internal
+ */
+export declare const _serverApps: Map<string, FirebaseServerApp>;
+
 /**
  * Sets log level for all Firebase SDKs.
  *

package/dist/esm/app/src/api.d.ts

@@ -14,7 +14,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import { FirebaseApp, FirebaseOptions, FirebaseAppSettings } from './public-types';
+import { FirebaseApp, FirebaseServerApp, FirebaseOptions, FirebaseAppSettings, FirebaseServerAppSettings } from './public-types';
 import { LogLevelString, LogCallback, LogOptions } from '@firebase/logger';
 export { FirebaseError } from '@firebase/util';
 /**
@@ -83,6 +83,48 @@ export declare function initializeApp(options: FirebaseOptions, config?: Firebas
  * @public
  */
 export declare function initializeApp(): FirebaseApp;
+/**
+ * Creates and initializes a {@link @firebase/app#FirebaseServerApp} instance.
+ *
+ * The `FirebaseServerApp` is similar to `FirebaseApp`, but is intended for execution in
+ * server side rendering environments only. Initialization will fail if invoked from a
+ * browser environment.
+ *
+ * See
+ * {@link
+ *   https://firebase.google.com/docs/web/setup#add_firebase_to_your_app
+ *   | Add Firebase to your app} and
+ * {@link
+ *   https://firebase.google.com/docs/web/setup#multiple-projects
+ *   | Initialize multiple projects} for detailed documentation.
+ *
+ * @example
+ * ```javascript
+ *
+ * // Initialize an instance of `FirebaseServerApp`.
+ * // Retrieve your own options values by adding a web app on
+ * // https://console.firebase.google.com
+ * initializeServerApp({
+ *     apiKey: "AIza....",                             // Auth / General Use
+ *     authDomain: "YOUR_APP.firebaseapp.com",         // Auth with popup/redirect
+ *     databaseURL: "https://YOUR_APP.firebaseio.com", // Realtime Database
+ *     storageBucket: "YOUR_APP.appspot.com",          // Storage
+ *     messagingSenderId: "123456789"                  // Cloud Messaging
+ *   },
+ *   {
+ *    authIdToken: "Your Auth ID Token"
+ *   });
+ * ```
+ *
+ * @param options - `Firebase.AppOptions` to configure the app's services, or a
+ *   a `FirebaseApp` instance which contains the `AppOptions` within.
+ * @param config - `FirebaseServerApp` configuration.
+ *
+ * @returns The initialized `FirebaseServerApp`.
+ *
+ * @public
+ */
+export declare function initializeServerApp(options: FirebaseOptions | FirebaseApp, config: FirebaseServerAppSettings): FirebaseServerApp;
 /**
  * Retrieves a {@link @firebase/app#FirebaseApp} instance.
  *

package/dist/esm/app/src/errors.d.ts

@@ -20,13 +20,16 @@ export declare const enum AppError {
     BAD_APP_NAME = "bad-app-name",
     DUPLICATE_APP = "duplicate-app",
     APP_DELETED = "app-deleted",
+    SERVER_APP_DELETED = "server-app-deleted",
     NO_OPTIONS = "no-options",
     INVALID_APP_ARGUMENT = "invalid-app-argument",
     INVALID_LOG_ARGUMENT = "invalid-log-argument",
     IDB_OPEN = "idb-open",
     IDB_GET = "idb-get",
     IDB_WRITE = "idb-set",
-    IDB_DELETE = "idb-delete"
+    IDB_DELETE = "idb-delete",
+    FINALIZATION_REGISTRY_NOT_SUPPORTED = "finalization-registry-not-supported",
+    INVALID_SERVER_APP_ENVIRONMENT = "invalid-server-app-environment"
 }
 interface ErrorParams {
     [AppError.NO_APP]: {
@@ -56,6 +59,9 @@ interface ErrorParams {
     [AppError.IDB_DELETE]: {
         originalErrorMessage?: string;
     };
+    [AppError.FINALIZATION_REGISTRY_NOT_SUPPORTED]: {
+        appName?: string;
+    };
 }
 export declare const ERROR_FACTORY: ErrorFactory<AppError, ErrorParams>;
 export {};

package/dist/esm/app/src/firebaseApp.d.ts

@@ -17,8 +17,8 @@
 import { FirebaseApp, FirebaseOptions, FirebaseAppSettings } from './public-types';
 import { ComponentContainer } from '@firebase/component';
 export declare class FirebaseAppImpl implements FirebaseApp {
-    private readonly _options;
-    private readonly _name;
+    protected readonly _options: FirebaseOptions;
+    protected readonly _name: string;
     /**
      * Original config values passed in as a constructor parameter.
      * It is only used to compare with another config object to support idempotent initializeApp().
@@ -27,7 +27,7 @@ export declare class FirebaseAppImpl implements FirebaseApp {
      */
     private readonly _config;
     private _automaticDataCollectionEnabled;
-    private _isDeleted;
+    protected _isDeleted: boolean;
     private readonly _container;
     constructor(options: FirebaseOptions, config: Required<FirebaseAppSettings>, container: ComponentContainer);
     get automaticDataCollectionEnabled(): boolean;
@@ -42,5 +42,5 @@ export declare class FirebaseAppImpl implements FirebaseApp {
      * This function will throw an Error if the App has already been deleted -
      * use before performing API actions on the App.
      */
-    private checkDestroyed;
+    protected checkDestroyed(): void;
 }

package/dist/esm/app/src/firebaseServerApp.d.ts

@@ -0,0 +1,35 @@
+/**
+ * @license
+ * Copyright 2023 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 { FirebaseServerApp, FirebaseServerAppSettings, FirebaseOptions } from './public-types';
+import { ComponentContainer } from '@firebase/component';
+import { FirebaseAppImpl } from './firebaseApp';
+export declare class FirebaseServerAppImpl extends FirebaseAppImpl implements FirebaseServerApp {
+    private readonly _serverConfig;
+    private _finalizationRegistry;
+    private _refCount;
+    constructor(options: FirebaseOptions | FirebaseAppImpl, serverConfig: FirebaseServerAppSettings, name: string, container: ComponentContainer);
+    get refCount(): number;
+    incRefCount(obj: object | undefined): void;
+    decRefCount(): number;
+    private automaticCleanup;
+    get settings(): FirebaseServerAppSettings;
+    /**
+     * This function will throw an Error if the App has already been deleted -
+     * use before performing API actions on the App.
+     */
+    protected checkDestroyed(): void;
+}

package/dist/esm/app/src/firebaseServerApp.test.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @license
+ * Copyright 2023 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 '../test/setup';

package/dist/esm/app/src/internal.d.ts

@@ -14,13 +14,17 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import { FirebaseApp } from './public-types';
+import { FirebaseApp, FirebaseOptions, FirebaseServerApp } from './public-types';
 import { Component, Provider, Name } from '@firebase/component';
 import { DEFAULT_ENTRY_NAME } from './constants';
 /**
  * @internal
  */
 export declare const _apps: Map<string, FirebaseApp>;
+/**
+ * @internal
+ */
+export declare const _serverApps: Map<string, FirebaseServerApp>;
 /**
  * Registered components.
  *
@@ -65,6 +69,24 @@ export declare function _getProvider<T extends Name>(app: FirebaseApp, name: T):
  * @internal
  */
 export declare function _removeServiceInstance<T extends Name>(app: FirebaseApp, name: T, instanceIdentifier?: string): void;
+/**
+ *
+ * @param obj - an object of type FirebaseApp or FirebaseOptions.
+ *
+ * @returns true if the provide object is of type FirebaseApp.
+ *
+ * @internal
+ */
+export declare function _isFirebaseApp(obj: FirebaseApp | FirebaseOptions): obj is FirebaseApp;
+/**
+ *
+ * @param obj - an object of type FirebaseApp.
+ *
+ * @returns true if the provided object is of type FirebaseServerAppImpl.
+ *
+ * @internal
+ */
+export declare function _isFirebaseServerApp(obj: FirebaseApp | FirebaseServerApp): obj is FirebaseServerApp;
 /**
  * Test only
  *

package/dist/esm/app/src/public-types.d.ts

@@ -62,6 +62,35 @@ export interface FirebaseApp {
      */
     automaticDataCollectionEnabled: boolean;
 }
+/**
+ * A {@link @firebase/app#FirebaseServerApp} holds the initialization information
+ * for a collection of services running in server environments.
+ *
+ * Do not call this constructor directly. Instead, use
+ * {@link (initializeServerApp:1) | initializeServerApp()} to create
+ * an app.
+ *
+ * @public
+ */
+export interface FirebaseServerApp extends FirebaseApp {
+    /**
+     * There is no `getApp()` operation for `FirebaseServerApp`, so the name is not relevant for
+     * applications. However, it may be used internally, and is declared here so that
+     * `FirebaseServerApp` conforms to the `FirebaseApp` interface.
+     */
+    name: string;
+    /**
+     * The (read-only) configuration settings for this server app. These are the original
+     * parameters given in {@link (initializeServerApp:1) | initializeServerApp()}.
+     *
+     * @example
+     * ```javascript
+     * const app = initializeServerApp(settings);
+     * console.log(app.settings.authIdToken === options.authIdToken);  // true
+     * ```
+     */
+    readonly settings: FirebaseServerAppSettings;
+}
 /**
  * @public
  *
@@ -128,6 +157,57 @@ export interface FirebaseAppSettings {
      */
     automaticDataCollectionEnabled?: boolean;
 }
+/**
+ * @public
+ *
+ * Configuration options given to {@link (initializeServerApp:1) | initializeServerApp()}
+ */
+export interface FirebaseServerAppSettings extends FirebaseAppSettings {
+    /**
+     * An optional Auth ID token used to resume a signed in user session from a client
+     * runtime environment.
+     *
+     * Invoking `getAuth` with a `FirebaseServerApp` configured with a validated `authIdToken`
+     * causes an automatic attempt to sign in the user that the `authIdToken` represents. The token
+     * needs to have been recently minted for this operation to succeed.
+     *
+     * If the token fails local verification, or if the Auth service has failed to validate it when
+     * the Auth SDK is initialized, then a warning is logged to the console and the Auth SDK will not
+     * sign in a user on initalization.
+     *
+     * If a user is successfully signed in, then the Auth instance's `onAuthStateChanged` callback
+     * is invoked with the `User` object as per standard Auth flows. However, `User` objects
+     * created via an `authIdToken` do not have a refresh token. Attempted `refreshToken`
+     * operations fail.
+     */
+    authIdToken?: string;
+    /**
+     * An optional object. If provided, the Firebase SDK uses a `FinalizationRegistry`
+     * object to monitor the garbage collection status of the provided object. The
+     * Firebase SDK releases its reference on the `FirebaseServerApp` instance when the
+     * provided `releaseOnDeref` object is garbage collected.
+     *
+     * You can use this field to reduce memory management overhead for your application.
+     * If provided, an app running in a SSR pass does not need to perform
+     * `FirebaseServerApp` cleanup, so long as the reference object is deleted (by falling out of
+     * SSR scope, for instance.)
+     *
+     * If an object is not provided then the application must clean up the `FirebaseServerApp`
+     * instance by invoking `deleteApp`.
+     *
+     * If the application provides an object in this parameter, but the application is
+     * executed in a JavaScript engine that predates the support of `FinalizationRegistry`
+     * (introduced in node v14.6.0, for instance), then an error is thrown at `FirebaseServerApp`
+     * initialization.
+     */
+    releaseOnDeref?: object;
+    /**
+     * There is no `getApp()` operation for `FirebaseServerApp`, so the name is not relevant for
+     * applications. However, it may be used internally, and is declared here so that
+     * `FirebaseServerApp` conforms to the `FirebaseApp` interface.
+     */
+    name?: undefined;
+}
 /**
  * @internal
  */