firebase-functions 3.21.0 → 3.22.0

package/lib/bin/firebase-functions.js

@@ -1,5 +1,26 @@
 #!/usr/bin/env node
 "use strict";
+// The MIT License (MIT)
+//
+// Copyright (c) 2022 Firebase
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in all
+// copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+// SOFTWARE.
 Object.defineProperty(exports, "__esModule", { value: true });
 const express = require("express");
 const loader_1 = require("../runtime/loader");

package/lib/cloud-functions.d.ts

@@ -3,6 +3,7 @@ import { DeploymentOptions, FailurePolicy, Schedule } from './function-configura
 export { Request, Response };
 import { Duration } from './common/encoding';
 import { ManifestEndpoint, ManifestRequiredAPI } from './runtime/manifest';
+export { Change } from './common/change';
 /**
  * @hidden
  *
@@ -111,54 +112,6 @@ export interface EventContext {
      */
     timestamp: string;
 }
-/**
- * The Functions interface for events that change state, such as
- * Realtime Database or Cloud Firestore `onWrite` and `onUpdate`.
- *
- * For more information about the format used to construct `Change` objects, see
- * [`cloud-functions.ChangeJson`](/docs/reference/functions/cloud_functions_.changejson).
- *
- */
-export declare class Change<T> {
-    before: T;
-    after: T;
-    constructor(before: T, after: T);
-}
-/**
- * `ChangeJson` is the JSON format used to construct a Change object.
- */
-export interface ChangeJson {
-    /**
-     * Key-value pairs representing state of data after the change.
-     */
-    after?: any;
-    /**
-     * Key-value pairs representing state of data before the change. If
-     * `fieldMask` is set, then only fields that changed are present in `before`.
-     */
-    before?: any;
-    /**
-     * @hidden
-     * Comma-separated string that represents names of fields that changed.
-     */
-    fieldMask?: string;
-}
-export declare namespace Change {
-    /**
-     * @hidden
-     * Factory method for creating a Change from a `before` object and an `after`
-     * object.
-     */
-    function fromObjects<T>(before: T, after: T): Change<T>;
-    /**
-     * @hidden
-     * Factory method for creating a Change from a JSON and an optional customizer
-     * function to be applied to both the `before` and the `after` fields.
-     */
-    function fromJSON<T>(json: ChangeJson, customizer?: (x: any) => T): Change<T>;
-    /** @hidden */
-    function applyFieldMask(sparseBefore: any, after: any, fieldMask: string): any;
-}
 /**
  * Resource is a standard format for defining a resource
  * (google.rpc.context.AttributeContext.Resource). In Cloud Functions, it is the
@@ -173,46 +126,35 @@ export interface Resource {
     };
 }
 /**
- * @hidden
- * TriggerAnnotated is used internally by the firebase CLI to understand what
+ * TriggerAnnotion is used internally by the firebase CLI to understand what
  * type of Cloud Function to deploy.
  */
-export interface TriggerAnnotated {
-    __trigger: {
-        availableMemoryMb?: number;
-        blockingTrigger?: {
-            eventType: string;
-            options?: Record<string, unknown>;
-        };
-        eventTrigger?: {
-            eventType: string;
-            resource: string;
-            service: string;
-        };
-        failurePolicy?: FailurePolicy;
-        httpsTrigger?: {
-            invoker?: string[];
-        };
-        labels?: {
-            [key: string]: string;
-        };
-        regions?: string[];
-        schedule?: Schedule;
-        timeout?: Duration;
-        vpcConnector?: string;
-        vpcConnectorEgressSettings?: string;
-        serviceAccountEmail?: string;
-        ingressSettings?: string;
-        secrets?: string[];
+interface TriggerAnnotation {
+    availableMemoryMb?: number;
+    blockingTrigger?: {
+        eventType: string;
+        options?: Record<string, unknown>;
     };
-}
-/**
- * @hidden
- * EndpointAnnotated is used to generate the manifest that conforms to the container contract.
- */
-export interface EndpointAnnotated {
-    __endpoint: ManifestEndpoint;
-    __requiredAPIs?: ManifestRequiredAPI[];
+    eventTrigger?: {
+        eventType: string;
+        resource: string;
+        service: string;
+    };
+    failurePolicy?: FailurePolicy;
+    httpsTrigger?: {
+        invoker?: string[];
+    };
+    labels?: {
+        [key: string]: string;
+    };
+    regions?: string[];
+    schedule?: Schedule;
+    timeout?: Duration;
+    vpcConnector?: string;
+    vpcConnectorEgressSettings?: string;
+    serviceAccountEmail?: string;
+    ingressSettings?: string;
+    secrets?: string[];
 }
 /**
  * A Runnable has a `run` method which directly invokes the user-defined
@@ -230,11 +172,27 @@ export interface Runnable<T> {
  * [`Response`](https://expressjs.com/en/api.html#res) objects as its only
  * arguments.
  */
-export declare type HttpsFunction = TriggerAnnotated & EndpointAnnotated & ((req: Request, resp: Response) => void | Promise<void>);
+export interface HttpsFunction {
+    (req: Request, resp: Response): void | Promise<void>;
+    /** @alpha */
+    __trigger: TriggerAnnotation;
+    /** @alpha */
+    __endpoint: ManifestEndpoint;
+    /** @alpha */
+    __requiredAPIs?: ManifestRequiredAPI[];
+}
 /**
  * The Cloud Function type for Blocking triggers.
  */
-export declare type BlockingFunction = HttpsFunction;
+export interface BlockingFunction {
+    (req: Request, resp: Response): void | Promise<void>;
+    /** @alpha */
+    __trigger: TriggerAnnotation;
+    /** @alpha */
+    __endpoint: ManifestEndpoint;
+    /** @alpha */
+    __requiredAPIs?: ManifestRequiredAPI[];
+}
 /**
  * The Cloud Function type for all non-HTTPS triggers. This should be exported
  * from your JavaScript file to define a Cloud Function.
@@ -242,7 +200,15 @@ export declare type BlockingFunction = HttpsFunction;
  * This type is a special JavaScript function which takes a templated
  * `Event` object as its only argument.
  */
-export declare type CloudFunction<T> = Runnable<T> & TriggerAnnotated & EndpointAnnotated & ((input: any, context?: any) => PromiseLike<any> | any);
+export interface CloudFunction<T> extends Runnable<T> {
+    (input: any, context?: any): PromiseLike<any> | any;
+    /** @alpha */
+    __trigger: TriggerAnnotation;
+    /** @alpha */
+    __endpoint: ManifestEndpoint;
+    /** @alpha */
+    __requiredAPIs?: ManifestRequiredAPI[];
+}
 /** @hidden */
 export interface MakeCloudFunctionArgs<EventData> {
     after?: (raw: Event) => void;

package/lib/cloud-functions.js

@@ -26,67 +26,10 @@ const _ = require("lodash");
 const function_configuration_1 = require("./function-configuration");
 const logger_1 = require("./logger");
 const encoding_1 = require("./common/encoding");
+var change_1 = require("./common/change");
+Object.defineProperty(exports, "Change", { enumerable: true, get: function () { return change_1.Change; } });
 /** @hidden */
 const WILDCARD_REGEX = new RegExp('{[^/{}]*}', 'g');
-/**
- * The Functions interface for events that change state, such as
- * Realtime Database or Cloud Firestore `onWrite` and `onUpdate`.
- *
- * For more information about the format used to construct `Change` objects, see
- * [`cloud-functions.ChangeJson`](/docs/reference/functions/cloud_functions_.changejson).
- *
- */
-class Change {
-    constructor(before, after) {
-        this.before = before;
-        this.after = after;
-    }
-}
-exports.Change = Change;
-(function (Change) {
-    /** @hidden */
-    function reinterpretCast(x) {
-        return x;
-    }
-    /**
-     * @hidden
-     * Factory method for creating a Change from a `before` object and an `after`
-     * object.
-     */
-    function fromObjects(before, after) {
-        return new Change(before, after);
-    }
-    Change.fromObjects = fromObjects;
-    /**
-     * @hidden
-     * Factory method for creating a Change from a JSON and an optional customizer
-     * function to be applied to both the `before` and the `after` fields.
-     */
-    function fromJSON(json, customizer = reinterpretCast) {
-        let before = { ...json.before };
-        if (json.fieldMask) {
-            before = applyFieldMask(before, json.after, json.fieldMask);
-        }
-        return Change.fromObjects(customizer(before || {}), customizer(json.after || {}));
-    }
-    Change.fromJSON = fromJSON;
-    /** @hidden */
-    function applyFieldMask(sparseBefore, after, fieldMask) {
-        const before = { ...after };
-        const masks = fieldMask.split(',');
-        masks.forEach((mask) => {
-            const val = _.get(sparseBefore, mask);
-            if (typeof val === 'undefined') {
-                _.unset(before, mask);
-            }
-            else {
-                _.set(before, mask, val);
-            }
-        });
-        return before;
-    }
-    Change.applyFieldMask = applyFieldMask;
-})(Change = exports.Change || (exports.Change = {}));
 /** @hidden */
 function makeCloudFunction({ after = () => { }, before = () => { }, contextOnlyHandler, dataConstructor = (raw) => raw.data, eventType, handler, labels = {}, legacyEventType, options = {}, provider, service, triggerResource, }) {
     const cloudFunction = (data, context) => {

package/lib/common/change.d.ts

@@ -0,0 +1,46 @@
+/**
+ * `ChangeJson` is the JSON format used to construct a Change object.
+ */
+export interface ChangeJson {
+    /**
+     * Key-value pairs representing state of data after the change.
+     */
+    after?: any;
+    /**
+     * Key-value pairs representing state of data before the change. If
+     * `fieldMask` is set, then only fields that changed are present in `before`.
+     */
+    before?: any;
+    /**
+     * @hidden
+     * Comma-separated string that represents names of fields that changed.
+     */
+    fieldMask?: string;
+}
+/** @hidden */
+export declare function applyFieldMask(sparseBefore: any, after: any, fieldMask: string): any;
+/**
+ * The Functions interface for events that change state, such as
+ * Realtime Database or Cloud Firestore `onWrite` and `onUpdate`.
+ *
+ * For more information about the format used to construct `Change` objects, see
+ * {@link ChangeJson} below.
+ *
+ */
+export declare class Change<T> {
+    before: T;
+    after: T;
+    /**
+     * @hidden
+     * Factory method for creating a Change from a `before` object and an `after`
+     * object.
+     */
+    static fromObjects<T>(before: T, after: T): Change<T>;
+    /**
+     * @hidden
+     * Factory method for creating a Change from a JSON and an optional customizer
+     * function to be applied to both the `before` and the `after` fields.
+     */
+    static fromJSON<T>(json: ChangeJson, customizer?: (x: any) => T): Change<T>;
+    constructor(before: T, after: T);
+}

package/lib/common/change.js

@@ -0,0 +1,82 @@
+"use strict";
+// The MIT License (MIT)
+//
+// Copyright (c) 2022 Firebase
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in all
+// copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+// SOFTWARE.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Change = exports.applyFieldMask = void 0;
+/** @hidden */
+function applyFieldMask(sparseBefore, after, fieldMask) {
+    const before = { ...after };
+    const masks = fieldMask.split(',');
+    for (const mask of masks) {
+        const parts = mask.split('.');
+        const head = parts[0];
+        const tail = parts.slice(1).join('.');
+        if (parts.length > 1) {
+            before[head] = applyFieldMask(sparseBefore === null || sparseBefore === void 0 ? void 0 : sparseBefore[head], after[head], tail);
+            continue;
+        }
+        const val = sparseBefore === null || sparseBefore === void 0 ? void 0 : sparseBefore[head];
+        if (typeof val === 'undefined') {
+            delete before[mask];
+        }
+        else {
+            before[mask] = val;
+        }
+    }
+    return before;
+}
+exports.applyFieldMask = applyFieldMask;
+/**
+ * The Functions interface for events that change state, such as
+ * Realtime Database or Cloud Firestore `onWrite` and `onUpdate`.
+ *
+ * For more information about the format used to construct `Change` objects, see
+ * {@link ChangeJson} below.
+ *
+ */
+class Change {
+    constructor(before, after) {
+        this.before = before;
+        this.after = after;
+    }
+    /**
+     * @hidden
+     * Factory method for creating a Change from a `before` object and an `after`
+     * object.
+     */
+    static fromObjects(before, after) {
+        return new Change(before, after);
+    }
+    /**
+     * @hidden
+     * Factory method for creating a Change from a JSON and an optional customizer
+     * function to be applied to both the `before` and the `after` fields.
+     */
+    static fromJSON(json, customizer = (x) => x) {
+        let before = { ...json.before };
+        if (json.fieldMask) {
+            before = applyFieldMask(before, json.after, json.fieldMask);
+        }
+        return Change.fromObjects(customizer(before || {}), customizer(json.after || {}));
+    }
+}
+exports.Change = Change;

package/lib/common/encoding.js

@@ -1,5 +1,25 @@
 "use strict";
-// Copied from firebase-tools/src/gcp/proto
+// The MIT License (MIT)
+//
+// Copyright (c) 2021 Firebase
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in all
+// copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+// SOFTWARE.
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.convertInvoker = exports.serviceAccountFromShorthand = exports.convertIfPresent = exports.copyIfPresent = exports.durationFromSeconds = void 0;
 /** Get a google.protobuf.Duration for a number of seconds. */

package/lib/common/providers/database.d.ts

@@ -0,0 +1,145 @@
+import * as firebase from 'firebase-admin';
+/**
+ * Interface representing a Firebase Realtime Database data snapshot.
+ */
+export declare class DataSnapshot {
+    private app?;
+    instance: string;
+    /** @hidden */
+    private _ref;
+    /** @hidden */
+    private _path;
+    /** @hidden */
+    private _data;
+    /** @hidden */
+    private _childPath;
+    constructor(data: any, path?: string, // path will be undefined for the database root
+    app?: firebase.app.App, instance?: string);
+    /**
+     * Returns a [`Reference`](/docs/reference/admin/node/admin.database.Reference)
+     * to the Database location where the triggering write occurred. Has
+     * full read and write access.
+     */
+    get ref(): firebase.database.Reference;
+    /**
+     * The key (last part of the path) of the location of this `DataSnapshot`.
+     *
+     * The last token in a Database location is considered its key. For example,
+     * "ada" is the key for the `/users/ada/` node. Accessing the key on any
+     * `DataSnapshot` will return the key for the location that generated it.
+     * However, accessing the key on the root URL of a Database will return `null`.
+     */
+    get key(): string;
+    /**
+     * Extracts a JavaScript value from a `DataSnapshot`.
+     *
+     * Depending on the data in a `DataSnapshot`, the `val()` method may return a
+     * scalar type (string, number, or boolean), an array, or an object. It may also
+     * return `null`, indicating that the `DataSnapshot` is empty (contains no
+     * data).
+     *
+     * @return The DataSnapshot's contents as a JavaScript value (Object,
+     *   Array, string, number, boolean, or `null`).
+     */
+    val(): any;
+    /**
+     * Exports the entire contents of the `DataSnapshot` as a JavaScript object.
+     *
+     * The `exportVal()` method is similar to `val()`, except priority information
+     * is included (if available), making it suitable for backing up your data.
+     *
+     * @return The contents of the `DataSnapshot` as a JavaScript value
+     *   (Object, Array, string, number, boolean, or `null`).
+     */
+    exportVal(): any;
+    /**
+     * Gets the priority value of the data in this `DataSnapshot`.
+     *
+     * As an alternative to using priority, applications can order collections by
+     * ordinary properties. See [Sorting and filtering
+     * data](/docs/database/web/lists-of-data#sorting_and_filtering_data).
+     *
+     * @return The priority value of the data.
+     */
+    getPriority(): string | number | null;
+    /**
+     * Returns `true` if this `DataSnapshot` contains any data. It is slightly more
+     * efficient than using `snapshot.val() !== null`.
+     *
+     * @return `true` if this `DataSnapshot` contains any data; otherwise, `false`.
+     */
+    exists(): boolean;
+    /**
+     * Gets a `DataSnapshot` for the location at the specified relative path.
+     *
+     * The relative path can either be a simple child name (for example, "ada") or
+     * a deeper slash-separated path (for example, "ada/name/first").
+     *
+     * @param path A relative path from this location to the desired child
+     *   location.
+     * @return The specified child location.
+     */
+    child(childPath: string): DataSnapshot;
+    /**
+     * Enumerates the `DataSnapshot`s of the children items.
+     *
+     * Because of the way JavaScript objects work, the ordering of data in the
+     * JavaScript object returned by `val()` is not guaranteed to match the ordering
+     * on the server nor the ordering of `child_added` events. That is where
+     * `forEach()` comes in handy. It guarantees the children of a `DataSnapshot`
+     * will be iterated in their query order.
+     *
+     * If no explicit `orderBy*()` method is used, results are returned
+     * ordered by key (unless priorities are used, in which case, results are
+     * returned by priority).
+     *
+     * @param action A function that will be called for each child `DataSnapshot`.
+     *   The callback can return `true` to cancel further enumeration.
+     *
+     * @return `true` if enumeration was canceled due to your callback
+     *   returning `true`.
+     */
+    forEach(action: (a: DataSnapshot) => boolean | void): boolean;
+    /**
+     * Returns `true` if the specified child path has (non-`null`) data.
+     *
+     * @param path A relative path to the location of a potential child.
+     * @return `true` if data exists at the specified child path; otherwise,
+     *   `false`.
+     */
+    hasChild(childPath: string): boolean;
+    /**
+     * Returns whether or not the `DataSnapshot` has any non-`null` child
+     * properties.
+     *
+     * You can use `hasChildren()` to determine if a `DataSnapshot` has any
+     * children. If it does, you can enumerate them using `forEach()`. If it
+     * doesn't, then either this snapshot contains a primitive value (which can be
+     * retrieved with `val()`) or it is empty (in which case, `val()` will return
+     * `null`).
+     *
+     * @return `true` if this snapshot has any children; else `false`.
+     */
+    hasChildren(): boolean;
+    /**
+     * Returns the number of child properties of this `DataSnapshot`.
+     *
+     * @return Number of child properties of this `DataSnapshot`.
+     */
+    numChildren(): number;
+    /**
+     * Returns a JSON-serializable representation of this object.
+     *
+     * @return A JSON-serializable representation of this object.
+     */
+    toJSON(): Object;
+    /** Recursive function to check if keys are numeric & convert node object to array if they are
+     *
+     * @hidden
+     */
+    private _checkAndConvertToArray;
+    /** @hidden */
+    private _dup;
+    /** @hidden */
+    private _fullPath;
+}