fix(core): restore patchExpressModule legacy signature compatibility

Add an overload and runtime fallback for the deprecated single-options argument, reintroduce the deprecated ExpressIntegrationOptions.express field, and add a regression test for legacy callers.

Co-Authored-By: gpt-5.3-codex-high <noreply@anthropic.com>

Author: cursoragent

packages/core/src/integrations/express/index.ts

@@ -60,6 +60,12 @@ import { setSDKProcessingMetadata } from './set-sdk-processing-metadata';
 const getExpressExport = (express: ExpressModuleExport): ExpressExport =>
   hasDefaultProp(express) ? express.default : (express as ExpressExport);
 
+type LegacyPatchExpressModuleOptions = ExpressIntegrationOptions & {
+  express: ExpressModuleExport;
+};
+
+let _didWarnLegacyPatchExpressModule = false;
+
 /**
  * This is a portable instrumentatiton function that works in any environment
  * where Express can be loaded, without depending on OpenTelemetry.
@@ -72,7 +78,46 @@ const getExpressExport = (express: ExpressModuleExport): ExpressExport =>
  * Sentry.patchExpressModule(express, () => ({}));
  * ```
  */
-export const patchExpressModule = (moduleExports: ExpressModuleExport, getOptions: () => ExpressIntegrationOptions) => {
+export function patchExpressModule(
+  moduleExports: ExpressModuleExport,
+  getOptions: () => ExpressIntegrationOptions,
+): ExpressExport;
+/**
+ * @deprecated Pass the Express module export as the first argument and options getter as the second argument.
+ */
+export function patchExpressModule(options: LegacyPatchExpressModuleOptions): ExpressExport;
+export function patchExpressModule(
+  moduleExportsOrOptions: ExpressModuleExport | LegacyPatchExpressModuleOptions,
+  getOptions?: () => ExpressIntegrationOptions,
+): ExpressExport {
+  const isLegacyOptionsObject =
+    !getOptions &&
+    typeof moduleExportsOrOptions === 'object' &&
+    moduleExportsOrOptions !== null &&
+    'express' in moduleExportsOrOptions;
+
+  let moduleExports: ExpressModuleExport;
+  let getExpressOptions: () => ExpressIntegrationOptions;
+
+  if (isLegacyOptionsObject) {
+    moduleExports = moduleExportsOrOptions.express;
+    getExpressOptions = () => moduleExportsOrOptions;
+  } else {
+    moduleExports = moduleExportsOrOptions;
+    if (!getOptions) {
+      throw new TypeError('`patchExpressModule(moduleExports, getOptions)` requires a `getOptions` callback');
+    }
+    getExpressOptions = getOptions;
+  }
+
+  if (isLegacyOptionsObject && !_didWarnLegacyPatchExpressModule) {
+    _didWarnLegacyPatchExpressModule = true;
+    DEBUG_BUILD &&
+      debug.warn(
+        '[Express] `patchExpressModule(options)` is deprecated. Use `patchExpressModule(moduleExports, getOptions)` instead.',
+      );
+  }
+
   // pass in the require() or import() result of express
   const express = getExpressExport(moduleExports);
   const routerProto: ExpressRouterv4 | ExpressRouterv5 | undefined = isExpressWithRouterPrototype(express)
@@ -94,7 +139,7 @@ export const patchExpressModule = (moduleExports: ExpressModuleExport, getOption
       function routeTrace(this: ExpressRouter, ...args: Parameters<typeof originalRouteMethod>[]) {
         const route = originalRouteMethod.apply(this, args);
         const layer = this.stack[this.stack.length - 1] as ExpressLayer;
-        patchLayer(getOptions, layer, getLayerPath(args));
+        patchLayer(getExpressOptions, layer, getLayerPath(args));
         return route;
       },
     );
@@ -114,7 +159,7 @@ export const patchExpressModule = (moduleExports: ExpressModuleExport, getOption
         if (!layer) {
           return route;
         }
-        patchLayer(getOptions, layer, getLayerPath(args));
+        patchLayer(getExpressOptions, layer, getLayerPath(args));
         return route;
       },
     );
@@ -142,7 +187,7 @@ export const patchExpressModule = (moduleExports: ExpressModuleExport, getOption
         if (router) {
           const layer = router.stack[router.stack.length - 1];
           if (layer) {
-            patchLayer(getOptions, layer, getLayerPath(args));
+            patchLayer(getExpressOptions, layer, getLayerPath(args));
           }
         }
         return route;
@@ -153,7 +198,7 @@ export const patchExpressModule = (moduleExports: ExpressModuleExport, getOption
   }
 
   return express;
-};
+}
 
 /**
  * An Express-compatible error handler, used by setupExpressErrorHandler

packages/core/src/integrations/express/types.ts

@@ -136,6 +136,10 @@ export type ExpressRouter = {
 export type IgnoreMatcher = string | RegExp | ((name: string) => boolean);
 
 export type ExpressIntegrationOptions = {
+  /**
+   * @deprecated Pass the Express module export as the first argument to `patchExpressModule` instead.
+   */
+  express?: ExpressModuleExport;
   /** Ignore specific based on their name */
   ignoreLayers?: IgnoreMatcher[];
   /** Ignore specific layers based on their type */

packages/core/test/lib/integrations/express/index.test.ts

@@ -52,15 +52,22 @@ vi.mock('../../../../src/debug-build', () => ({
   DEBUG_BUILD: true,
 }));
 const debugErrors: [string, Error][] = [];
+const debugWarnings: string[] = [];
 vi.mock('../../../../src/utils/debug-logger', () => ({
   debug: {
     error: (msg: string, er: Error) => {
       debugErrors.push([msg, er]);
     },
+    warn: (msg: string) => {
+      debugWarnings.push(msg);
+    },
   },
 }));
 
-beforeEach(() => (patchLayerCalls.length = 0));
+beforeEach(() => {
+  patchLayerCalls.length = 0;
+  debugWarnings.length = 0;
+});
 const patchLayerCalls: [getOptions: () => ExpressIntegrationOptions, layer: ExpressLayer, layerPath?: string][] = [];
 
 vi.mock('../../../../src/integrations/express/patch-layer', () => ({
@@ -129,6 +136,18 @@ function getExpress5(): ExpressExportv5 & { spies: ExpressSpies } {
 }
 
 describe('patchExpressModule', () => {
+  it('supports deprecated options signature', () => {
+    const expressv4 = getExpress4();
+    const options = { express: expressv4, ignoreLayers: [/foo/] };
+    patchExpressModule(options);
+    expressv4.Router.use('a');
+
+    expect(patchLayerCalls[0]?.[0]()).toStrictEqual(options);
+    expect(debugWarnings).toStrictEqual([
+      '[Express] `patchExpressModule(options)` is deprecated. Use `patchExpressModule(moduleExports, getOptions)` instead.',
+    ]);
+  });
+
   it('throws trying to patch/unpatch the wrong thing', () => {
     expect(() => {
       patchExpressModule({} as unknown as ExpressModuleExport, () => ({}));