fix: Resolve dual-package hazard for params in ESM (#1780)

* fix: Resolve dual-package hazard for params in ESM

We resolve two critical issues caused by the "Dual-Package Hazard" when using `firebase-functions` in ESM projects:

1.   Separate instances of the `declaredParams` in `firebase-functions/params` led to params not being detected when used in ESM modules.

To fix, we implement a Global Singleton pattern for `declaredParams` using `globalThis` and a version-scoped `Symbol.for` key. This ensures both builds share the same global storage for collecting param API uses.

1. `instanceof` checks failed because the CJS `Expression`/`ResetValue` instances deferred from the ESM ones.

To fix, we implement a custom `[Symbol.hasInstance]` on `Expression` and `ResetValue` classes using specfic branded tags to identify instances across package boundaries.

* fix: Resolve dual-package hazard for params in ESM

This commit resolves two critical issues caused by the "Dual-Package Hazard" when using `firebase-functions` in ESM projects:

1.  **Split State (Missing Params)**:
    The SDK bootstrap code (CJS) and User Code (ESM) were using separate instances of the `declaredParams` array.
    *   **Fix**: Implemented a Global Singleton pattern for `declaredParams` using `globalThis` and a version-scoped `Symbol.for` key. This ensures both builds share the same storage.

2.  **Identity Mismatch (Deployment Error)**:
    `instanceof Expression` checks in the SDK bootstrap code failed because the user's `Expression` instance (ESM) differed from the bootstrap's class (CJS).
    *   **Fix**: Implemented `[Symbol.hasInstance]` on `Expression` and `ResetValue` classes.
    *   **Mechanism**: Uses `Symbol.for` tags (`firebase-functions:Expression:Tag`) to robustly identify instances across package boundaries, avoiding fragile duck-typing or strict class identity checks.

This ensures that parameterized configuration works correctly regardless of the module system used.

* fix changelog

* clarify comments.

* formatter

Author: taeold

CHANGELOG.md

@@ -0,0 +1 @@
+- Fix "Dual-Package Hazard" for parameterized configuration in ESM projects. (#1780)

scripts/bin-test/sources/commonjs-params/index.js

@@ -0,0 +1,8 @@
+const { defineInt } = require("firebase-functions/params");
+const { onRequest } = require("firebase-functions/v2/https");
+
+const minInstances = defineInt("MIN_INSTANCES", { default: 1 });
+
+exports.v2http = onRequest({ minInstances }, (req, res) => {
+    res.send("PASS");
+});

scripts/bin-test/sources/commonjs-params/package.json

@@ -0,0 +1,4 @@
+{
+  "name": "commonjs-params",
+  "main": "index.js"
+}

scripts/bin-test/sources/esm-params/index.js

@@ -0,0 +1,8 @@
+import { defineInt } from "firebase-functions/params";
+import { onRequest } from "firebase-functions/v2/https";
+
+const minInstances = defineInt("MIN_INSTANCES", { default: 1 });
+
+export const v2http = onRequest({ minInstances }, (req, res) => {
+    res.send("PASS");
+});

scripts/bin-test/sources/esm-params/package.json

@@ -0,0 +1,4 @@
+{
+  "name": "esm-params",
+  "type": "module"
+}

scripts/bin-test/test.ts

@@ -362,6 +362,32 @@ describe("functions.yaml", function () {
           extensions: BASE_EXTENSIONS,
         },
       },
+      {
+        name: "with params",
+        modulePath: "./scripts/bin-test/sources/commonjs-params",
+        expected: {
+          endpoints: {
+            v2http: {
+              ...DEFAULT_V2_OPTIONS,
+              platform: "gcfv2",
+              entryPoint: "v2http",
+              labels: {},
+              httpsTrigger: {},
+              minInstances: "{{ params.MIN_INSTANCES }}",
+            },
+          },
+          requiredAPIs: [],
+          specVersion: "v1alpha1",
+          params: [
+            {
+              name: "MIN_INSTANCES",
+              type: "int",
+              default: 1,
+            },
+          ],
+          extensions: {},
+        },
+      },
     ];
 
     for (const tc of testcases) {
@@ -396,6 +422,32 @@ describe("functions.yaml", function () {
         modulePath: "./scripts/bin-test/sources/esm-ext",
         expected: BASE_STACK,
       },
+      {
+        name: "with params",
+        modulePath: "./scripts/bin-test/sources/esm-params",
+        expected: {
+          endpoints: {
+            v2http: {
+              ...DEFAULT_V2_OPTIONS,
+              platform: "gcfv2",
+              entryPoint: "v2http",
+              labels: {},
+              httpsTrigger: {},
+              minInstances: "{{ params.MIN_INSTANCES }}",
+            },
+          },
+          requiredAPIs: [],
+          specVersion: "v1alpha1",
+          params: [
+            {
+              name: "MIN_INSTANCES",
+              type: "int",
+              default: 1,
+            },
+          ],
+          extensions: {},
+        },
+      },
     ];
 
     for (const tc of testcases) {

src/common/options.ts

@@ -19,12 +19,27 @@
 // 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.
+const RESET_VALUE_TAG = Symbol.for("firebase-functions:ResetValue:Tag");
+
 /**
  * Special configuration type to reset configuration to platform default.
  *
  * @alpha
  */
 export class ResetValue {
+  /**
+   * Handle the "Dual-Package Hazard".
+   *
+   * We implement custom `Symbol.hasInstance` to so CJS/ESM ResetValue instances
+   * are recognized as the same type.
+   */
+  static [Symbol.hasInstance](instance: unknown): boolean {
+    return (instance as { [RESET_VALUE_TAG]?: boolean })?.[RESET_VALUE_TAG] === true;
+  }
+
+  get [RESET_VALUE_TAG](): boolean {
+    return true;
+  }
   toJSON(): null {
     return null;
   }

src/params/index.ts

@@ -46,7 +46,28 @@ export { Expression };
 export type { ParamOptions };
 
 type SecretOrExpr = Param<any> | SecretParam | JsonSecretParam<any>;
-export const declaredParams: SecretOrExpr[] = [];
+
+/**
+ * Use a global singleton to manage the list of declared parameters.
+ *
+ * This ensures that parameters are shared between CJS and ESM builds,
+ * avoiding the "dual-package hazard" where the src/bin/firebase-functions.ts (CJS) sees
+ * an empty list while the user's code (ESM) populates a different list.
+ */
+const majorVersion =
+  // @ts-expect-error __FIREBASE_FUNCTIONS_MAJOR_VERSION__ is injected at build time
+  typeof __FIREBASE_FUNCTIONS_MAJOR_VERSION__ !== "undefined"
+    ? // @ts-expect-error __FIREBASE_FUNCTIONS_MAJOR_VERSION__ is injected at build time
+      __FIREBASE_FUNCTIONS_MAJOR_VERSION__
+    : "0";
+const GLOBAL_SYMBOL = Symbol.for(`firebase-functions:params:declaredParams:v${majorVersion}`);
+const globalSymbols = globalThis as unknown as Record<symbol, SecretOrExpr[]>;
+
+if (!globalSymbols[GLOBAL_SYMBOL]) {
+  globalSymbols[GLOBAL_SYMBOL] = [];
+}
+
+export const declaredParams: SecretOrExpr[] = globalSymbols[GLOBAL_SYMBOL];
 
 /**
  * Use a helper to manage the list such that parameters are uniquely

src/params/types.ts

@@ -22,12 +22,27 @@
 
 import * as logger from "../logger";
 
+const EXPRESSION_TAG = Symbol.for("firebase-functions:Expression:Tag");
+
 /*
  * A CEL expression which can be evaluated during function deployment, and
  * resolved to a value of the generic type parameter: i.e, you can pass
  * an Expression<number> as the value of an option that normally accepts numbers.
  */
 export abstract class Expression<T extends string | number | boolean | string[]> {
+  /**
+   * Handle the "Dual-Package Hazard" .
+   *
+   * We implement custom `Symbol.hasInstance` to so CJS/ESM Expression instances
+   * are recognized as the same type.
+   */
+  static [Symbol.hasInstance](instance: unknown): boolean {
+    return (instance as { [EXPRESSION_TAG]?: boolean })?.[EXPRESSION_TAG] === true;
+  }
+
+  get [EXPRESSION_TAG](): boolean {
+    return true;
+  }
   /** Returns the expression's runtime value, based on the CLI's resolution of parameters. */
   value(): T {
     if (process.env.FUNCTIONS_CONTROL_API === "true") {

tsdown.config.mts

@@ -1,4 +1,8 @@
 import { defineConfig } from "tsdown";
+import { readFileSync } from "fs";
+
+const pkg = JSON.parse(readFileSync("./package.json", "utf-8"));
+const majorVersion = pkg.version.split(".")[0];
 
 const rewriteProtoPathMjs = {
   name: "rewrite-proto-path-mjs",
@@ -13,6 +17,11 @@ const rewriteProtoPathMjs = {
 // Note: We use tsc (via tsconfig.release.json) for .d.ts generation instead of tsdown's
 // built-in dts option due to issues with rolldown-plugin-dts.
 // See: https://github.com/sxzz/rolldown-plugin-dts/issues/121
+
+const define = {
+  __FIREBASE_FUNCTIONS_MAJOR_VERSION__: JSON.stringify(majorVersion),
+};
+
 export default defineConfig([
   {
     entry: "src/**/*.ts",
@@ -23,6 +32,7 @@ export default defineConfig([
     dts: false, // Use tsc for type declarations
     treeshake: false,
     external: ["../../../protos/compiledFirestore"],
+    define,
   },
   {
     entry: "src/**/*.ts",
@@ -33,5 +43,6 @@ export default defineConfig([
     dts: false, // Use tsc for type declarations
     treeshake: false,
     plugins: [rewriteProtoPathMjs],
+    define,
   },
 ]);