fix: rename v1 Event to LegacyEvent to avoid api-extractor conflict

Author: taeold

ESM_BUGBASH.md

@@ -0,0 +1,252 @@
+# Firebase Functions ESM Support Bug Bash
+
+**Author:** Daniel Lee
+**Created:** October 28, 2025
+**Updated:** October 28, 2025
+**Related:** CF3 Bugbashes
+
+## Background
+
+We are shipping native ESM support for `firebase-functions`. This allows developers to use modern JavaScript `import`/`export` syntax directly without transpilation, aligning with the broader Node.js ecosystem. We are using a dual-build approach to maintain backward compatibility for CommonJS users.
+
+## Setup
+
+- Install the pre-release version of the Firebase CLI: `npm i -g firebase-tools@latest` (or specific version if applicable)
+- Install the pre-release version of the SDK in your test project: `npm i firebase-functions@next`
+
+## Scenarios to Test
+
+### 1. The "Modern" User (Pure ESM)
+
+Create a fresh project with `"type": "module"`.
+
+**`package.json`**
+
+```json
+{
+  "name": "esm-functions-test",
+  "type": "module",
+  "engines": { "node": "18" },
+  "main": "index.js",
+  "dependencies": {
+    "firebase-functions": "next",
+    "firebase-admin": "latest"
+  }
+}
+```
+
+**`index.js`**
+
+```javascript
+import { initializeApp } from "firebase-admin/app";
+import { onRequest } from "firebase-functions/v2/https";
+import { onDocumentCreated } from "firebase-functions/v2/firestore";
+import { onSchedule } from "firebase-functions/v2/scheduler";
+import * as logger from "firebase-functions/logger";
+import { defineString } from "firebase-functions/params";
+
+// V1 imports for comparison/legacy support test
+import * as functionsV1 from "firebase-functions/v1";
+
+initializeApp();
+
+const welcomeMessage = defineString("WELCOME_MESSAGE", { default: "Hello from ESM!" });
+
+// V2 HTTP Request
+export const helloWorld = onRequest((request, response) => {
+  logger.info("Hello logs!", { structuredData: true });
+  response.send(`${welcomeMessage.value()} - V2 HTTP`);
+});
+
+// V2 Firestore Trigger
+export const onUserCreated = onDocumentCreated("users/{userId}", (event) => {
+  const snapshot = event.data;
+  if (!snapshot) {
+    logger.error("No data associated with the event");
+    return;
+  }
+  const data = snapshot.data();
+  logger.log("New user created in Firestore (ESM):", data);
+  return snapshot.ref.set({ signedUpAt: new Date().toISOString() }, { merge: true });
+});
+
+// V2 Scheduler
+export const everyMinute = onSchedule("every 1 minutes", async (event) => {
+  logger.debug("Running scheduled task (ESM)");
+});
+
+// V1 Auth Trigger (Legacy compatibility in ESM)
+export const onAuthUserCreatedV1 = functionsV1.auth.user().onCreate((user) => {
+  logger.info("V1 Auth trigger running in ESM mode for user:", user.uid);
+  return null;
+});
+```
+
+### 2. The "Legacy" User (CommonJS)
+
+Upgrade an existing CJS project.
+
+**`package.json`**
+
+```json
+{
+  "name": "cjs-functions-test",
+  "engines": { "node": "18" },
+  "main": "index.js",
+  "dependencies": {
+    "firebase-functions": "next",
+    "firebase-admin": "latest"
+  }
+}
+```
+
+**`index.js`**
+
+```javascript
+const { initializeApp } = require("firebase-admin/app");
+const { onRequest } = require("firebase-functions/v2/https");
+const { onDocumentWritten } = require("firebase-functions/v2/firestore");
+const logger = require("firebase-functions/logger");
+const functionsV1 = require("firebase-functions/v1");
+
+initializeApp();
+
+// V2 HTTP
+exports.helloCJS = onRequest((req, res) => {
+  logger.info("Logging from CJS", { foo: "bar" });
+  res.send("Hello from CommonJS!");
+});
+
+// V2 Firestore
+exports.onDataChanged = onDocumentWritten("data/{docId}", (event) => {
+  logger.warn("Data changed (CJS trigger)");
+});
+
+// V1 Realtime Database (Legacy test)
+exports.onRTDBWriteV1 = functionsV1.database
+  .ref("/messages/{pushId}")
+  .onWrite((change, context) => {
+    logger.info("V1 RTDB trigger in CJS");
+    return null;
+  });
+```
+
+### 3. The "Hybrid" User (TypeScript with `NodeNext`)
+
+Test modern TypeScript compilation.
+
+**`package.json`**
+
+```json
+{
+  "name": "ts-nodenext-test",
+  "type": "module",
+  "engines": { "node": "18" },
+  "main": "lib/index.js",
+  "scripts": {
+    "build": "tsc",
+    "serve": "npm run build && firebase emulators:start --only functions",
+    "deploy": "npm run build && firebase deploy --only functions"
+  },
+  "dependencies": {
+    "firebase-functions": "next",
+    "firebase-admin": "latest"
+  },
+  "devDependencies": {
+    "typescript": "latest",
+    "@types/node": "latest"
+  }
+}
+```
+
+**`tsconfig.json`**
+
+```json
+{
+  "compilerOptions": {
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "target": "ES2022",
+    "outDir": "lib",
+    "rootDir": "src",
+    "sourceMap": true,
+    "strict": true
+  },
+  "include": ["src/**/*"]
+}
+```
+
+**`src/index.ts`**
+
+```typescript
+import { initializeApp } from "firebase-admin/app";
+import { onRequest } from "firebase-functions/v2/https";
+import * as logger from "firebase-functions/logger";
+import { onMessagePublished } from "firebase-functions/v2/pubsub";
+
+initializeApp();
+
+export const tsHttp = onRequest((req, res) => {
+  logger.info("TypeScript NodeNext HTTP hit");
+  res.json({ message: "Hello from TS NodeNext" });
+});
+
+export const tsPubSub = onMessagePublished("my-topic", (event) => {
+  logger.info("Received PubSub message", event.data.message.json);
+});
+```
+
+### 4. The "Dual Hazard" Stress Test (Advanced)
+
+Attempt to load both CJS and ESM versions in the same runtime to check for state duplication.
+
+**`package.json`**
+
+```json
+{
+  "name": "hazard-test",
+  "type": "module",
+  "main": "index.js",
+  "dependencies": {
+    "firebase-functions": "next"
+  }
+}
+```
+
+**`legacy-require.cjs`**
+
+```javascript
+const functionsCJS = require("firebase-functions");
+module.exports = functionsCJS;
+```
+
+**`index.js`**
+
+```javascript
+import { onRequest } from "firebase-functions/v2/https";
+import * as logger from "firebase-functions/logger";
+import { createRequire } from "module";
+import * as functionsESM from "firebase-functions";
+
+const require = createRequire(import.meta.url);
+const functionsCJS = require("./legacy-require.cjs");
+
+export const hazardTest = onRequest((req, res) => {
+  const isSameV1 = functionsESM.default === functionsCJS;
+
+  logger.info("Dual Package Hazard Check", {
+    isSameV1Instance: isSameV1,
+  });
+
+  res.json({
+    hazardDetected: !isSameV1,
+    message: "If hazardDetected is true, two copies of the SDK are loaded.",
+  });
+});
+```
+
+## Focus Areas for Bugs
+
+- **Type resolution errors:** Ensure `tsc` works cleanly in various configurations.
+- **Runtime errors:** Watch for `ERR_REQUIRE_ESM` or similar Node.js module loading errors during deployment or emulation.
+- **Inconsistent behavior:** If the dual package hazard is triggered, check if global state (like `config()` or initialized apps) behaves unexpectedly.

cloudbuild.test.yaml

@@ -0,0 +1,10 @@
+steps:
+  - name: 'node:22'
+    entrypoint: 'bash'
+    args:
+      - '-c'
+      - |
+        node --version
+        npm --version
+        npm ci
+        npm run build

src/v1/cloud-functions.ts

@@ -54,7 +54,7 @@ const WILDCARD_REGEX = new RegExp("{[^/{}]*}", "g");
 /**
  * Wire format for an event.
  */
-export interface Event {
+export interface LegacyEvent {
   /**
    * Wire format for an event context.
    */
@@ -344,7 +344,7 @@ export interface BlockingFunction {
  * from your JavaScript file to define a Cloud Function.
  *
  * This type is a special JavaScript function which takes a templated
- * `Event` object as its only argument.
+ * `LegacyEvent` object as its only argument.
  */
 export interface CloudFunction<T> extends Runnable<T> {
   (input: any, context?: any): PromiseLike<any> | any;
@@ -361,10 +361,10 @@ export interface CloudFunction<T> extends Runnable<T> {
 
 /** @internal */
 export interface MakeCloudFunctionArgs<EventData> {
-  after?: (raw: Event) => void;
-  before?: (raw: Event) => void;
+  after?: (raw: LegacyEvent) => void;
+  before?: (raw: LegacyEvent) => void;
   contextOnlyHandler?: (context: EventContext) => PromiseLike<any> | any;
-  dataConstructor?: (raw: Event) => EventData;
+  dataConstructor?: (raw: LegacyEvent) => EventData;
   eventType: string;
   handler?: (data: EventData, context: EventContext) => PromiseLike<any> | any;
   labels?: Record<string, string>;
@@ -382,7 +382,7 @@ export interface MakeCloudFunctionArgs<EventData> {
 /** @internal */
 export function makeCloudFunction<EventData>({
   contextOnlyHandler,
-  dataConstructor = (raw: Event) => raw.data,
+  dataConstructor = (raw: LegacyEvent) => raw.data,
   eventType,
   handler,
   labels = {},
@@ -406,7 +406,7 @@ export function makeCloudFunction<EventData>({
       };
     }
 
-    const event: Event = {
+    const event: LegacyEvent = {
       data,
       context,
     };
@@ -550,7 +550,7 @@ function _makeParams(
   return params;
 }
 
-function _makeAuth(event: Event, authType: string) {
+function _makeAuth(event: LegacyEvent, authType: string) {
   if (authType === "UNAUTHENTICATED") {
     return null;
   }
@@ -560,7 +560,7 @@ function _makeAuth(event: Event, authType: string) {
   };
 }
 
-function _detectAuthType(event: Event) {
+function _detectAuthType(event: LegacyEvent) {
   if (event.context?.auth?.admin) {
     return "ADMIN";
   }

src/v1/providers/analytics.ts

@@ -20,7 +20,7 @@
 // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 // SOFTWARE.
 
-import { CloudFunction, Event, EventContext, makeCloudFunction } from "../cloud-functions";
+import { CloudFunction, LegacyEvent, EventContext, makeCloudFunction } from "../cloud-functions";
 import { DeploymentOptions } from "../function-configuration";
 
 /** @internal */
@@ -70,7 +70,7 @@ export class AnalyticsEventBuilder {
   onLog(
     handler: (event: AnalyticsEvent, context: EventContext) => PromiseLike<any> | any
   ): CloudFunction<AnalyticsEvent> {
-    const dataConstructor = (raw: Event) => {
+    const dataConstructor = (raw: LegacyEvent) => {
       return new AnalyticsEvent(raw.data);
     };
     return makeCloudFunction({

src/v1/providers/auth.ts

@@ -40,7 +40,7 @@ import {
 import {
   BlockingFunction,
   CloudFunction,
-  Event,
+  LegacyEvent,
   EventContext,
   makeCloudFunction,
   optionsToEndpoint,
@@ -108,7 +108,7 @@ export function _userWithOptions(options: DeploymentOptions, userOptions: UserOp
  * @public
  */
 export class UserBuilder {
-  private static dataConstructor(raw: Event): UserRecord {
+  private static dataConstructor(raw: LegacyEvent): UserRecord {
     return userRecordConstructor(raw.data);
   }