feat(core): Deprecate integration classes & Integrations.X (#10198)

Instead, export the functional components from core, which users should
directly use.

This also adds a tiny `defineIntegration` utility which takes care of
obscuring the actual integration implementation for external use, so
this remains private and we can refactor this if we need to.

Author: mydea

MIGRATION.md

@@ -18,6 +18,24 @@ be removed.
 Instead of `getCurrentHub()`, use the respective replacement API directly - see [Deprecate Hub](#deprecate-hub) for
 details.
 
+## Deprecate class-based integrations
+
+In v7, integrations are classes and can be added as e.g. `integrations: [new Sentry.Integrations.ContextLines()]`. In
+v8, integrations will not be classes anymore, but instead functions. Both the use as a class, as well as accessing
+integrations from the `Integrations.XXX` hash, is deprecated in favor of using the new functional integrations
+
+- for example, `new Integrations.LinkedErrors()` becomes `linkedErrorsIntegration()`.
+
+The following list shows how integrations should be migrated:
+
+| Old                      | New                             |
+| ------------------------ | ------------------------------- |
+| `new InboundFilters()`   | `inboundFiltersIntegrations()`  |
+| `new FunctionToString()` | `functionToStringIntegration()` |
+| `new LinkedErrors()`     | `linkedErrorsIntegration()`     |
+| `new ModuleMetadata()`   | `moduleMetadataIntegration()`   |
+| `new RequestData()`      | `requestDataIntegration()`      |
+
 ## Deprecate `hub.bindClient()` and `makeMain()`
 
 Instead, either directly use `initAndBind()`, or the new APIs `setCurrentClient()` and `client.init()`. See

packages/browser/src/exports.ts

@@ -65,9 +65,13 @@ export {
   setUser,
   withScope,
   withIsolationScope,
+  // eslint-disable-next-line deprecation/deprecation
   FunctionToString,
+  // eslint-disable-next-line deprecation/deprecation
   InboundFilters,
   metrics,
+  functionToStringIntegration,
+  inboundFiltersIntegration,
 } from '@sentry/core';
 
 export { WINDOW } from './helpers';

packages/browser/src/index.bundle.base.ts

@@ -16,6 +16,7 @@ if (WINDOW.Sentry && WINDOW.Sentry.Integrations) {
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 const INTEGRATIONS: Record<string, new (...args: any[]) => Integration> = {
   ...windowIntegrations,
+  // eslint-disable-next-line deprecation/deprecation
   ...CoreIntegrations,
   ...BrowserIntegrations,
 };

packages/browser/src/index.ts

@@ -14,6 +14,7 @@ if (WINDOW.Sentry && WINDOW.Sentry.Integrations) {
 
 const INTEGRATIONS = {
   ...windowIntegrations,
+  // eslint-disable-next-line deprecation/deprecation
   ...CoreIntegrations,
   ...BrowserIntegrations,
 };
@@ -52,7 +53,9 @@ export {
   // eslint-disable-next-line deprecation/deprecation
   trace,
   makeMultiplexedTransport,
+  // eslint-disable-next-line deprecation/deprecation
   ModuleMetadata,
+  moduleMetadataIntegration,
 } from '@sentry/core';
 export type { SpanStatusType } from '@sentry/core';
 export type { Span } from '@sentry/types';

packages/browser/src/sdk.ts

@@ -1,6 +1,7 @@
 import type { Hub } from '@sentry/core';
 import {
-  Integrations as CoreIntegrations,
+  FunctionToString,
+  InboundFilters,
   captureSession,
   getClient,
   getCurrentHub,
@@ -26,16 +27,18 @@ import { Breadcrumbs, Dedupe, GlobalHandlers, HttpContext, LinkedErrors, TryCatc
 import { defaultStackParser } from './stack-parsers';
 import { makeFetchTransport, makeXHRTransport } from './transports';
 
+/* eslint-disable deprecation/deprecation */
 export const defaultIntegrations = [
-  new CoreIntegrations.InboundFilters(),
-  new CoreIntegrations.FunctionToString(),
+  new InboundFilters(),
+  new FunctionToString(),
   new TryCatch(),
   new Breadcrumbs(),
   new GlobalHandlers(),
   new LinkedErrors(),
   new Dedupe(),
   new HttpContext(),
 ];
+/* eslint-enable deprecation/deprecation */
 
 /**
  * A magic string that build tooling can leverage in order to inject a release value into the SDK.

packages/browser/test/unit/index.test.ts

@@ -1,12 +1,11 @@
-import { SDK_VERSION, getReportDialogEndpoint } from '@sentry/core';
+import { InboundFilters, SDK_VERSION, getReportDialogEndpoint } from '@sentry/core';
 import type { WrappedFunction } from '@sentry/types';
 import * as utils from '@sentry/utils';
 
 import type { Event } from '../../src';
 import { setCurrentClient } from '../../src';
 import {
   BrowserClient,
-  Integrations,
   Scope,
   WINDOW,
   addBreadcrumb,
@@ -269,7 +268,10 @@ describe('SentryBrowser', () => {
       const options = getDefaultBrowserClientOptions({
         beforeSend: localBeforeSend,
         dsn,
-        integrations: [new Integrations.InboundFilters({ ignoreErrors: ['capture'] })],
+        integrations: [
+          // eslint-disable-next-line deprecation/deprecation
+          new InboundFilters({ ignoreErrors: ['capture'] }),
+        ],
       });
       const client = new BrowserClient(options);
       setCurrentClient(client);

packages/bun/src/index.ts

@@ -79,6 +79,10 @@ export {
   startSpanManual,
   continueTrace,
   metrics,
+  functionToStringIntegration,
+  inboundFiltersIntegration,
+  linkedErrorsIntegration,
+  requestDataIntegration,
 } from '@sentry/core';
 export type { SpanStatusType } from '@sentry/core';
 export { autoDiscoverNodePerformanceMonitoringIntegrations, cron } from '@sentry/node';
@@ -92,6 +96,7 @@ import { Integrations as NodeIntegrations } from '@sentry/node';
 import * as BunIntegrations from './integrations';
 
 const INTEGRATIONS = {
+  // eslint-disable-next-line deprecation/deprecation
   ...CoreIntegrations,
   ...NodeIntegrations,
   ...BunIntegrations,

packages/bun/src/sdk.ts

@@ -1,17 +1,18 @@
 /* eslint-disable max-lines */
-import { Integrations as CoreIntegrations } from '@sentry/core';
+import { FunctionToString, InboundFilters, LinkedErrors } from '@sentry/core';
 import { Integrations as NodeIntegrations, init as initNode } from '@sentry/node';
 
 import { BunClient } from './client';
 import { BunServer } from './integrations';
 import { makeFetchTransport } from './transports';
 import type { BunOptions } from './types';
 
+/* eslint-disable deprecation/deprecation */
 export const defaultIntegrations = [
   // Common
-  new CoreIntegrations.InboundFilters(),
-  new CoreIntegrations.FunctionToString(),
-  new CoreIntegrations.LinkedErrors(),
+  new InboundFilters(),
+  new FunctionToString(),
+  new LinkedErrors(),
   // Native Wrappers
   new NodeIntegrations.Console(),
   new NodeIntegrations.Http(),
@@ -28,6 +29,7 @@ export const defaultIntegrations = [
   // Bun Specific
   new BunServer(),
 ];
+/* eslint-enable deprecation/deprecation */
 
 /**
  * The Sentry Bun SDK Client.

packages/core/src/index.ts

@@ -69,10 +69,10 @@ export { SDK_VERSION } from './version';
 export {
   getIntegrationsToSetup,
   addIntegration,
+  defineIntegration,
   // eslint-disable-next-line deprecation/deprecation
   convertIntegrationFnToClass,
 } from './integration';
-export { FunctionToString, InboundFilters, LinkedErrors } from './integrations';
 export { applyScopeDataToEvent, mergeScopeData } from './utils/applyScopeDataToEvent';
 export { prepareEvent } from './utils/prepareEvent';
 export { createCheckInEnvelope } from './checkin';
@@ -86,9 +86,23 @@ export {
 } from './utils/spanUtils';
 export { getRootSpan } from './utils/getRootSpan';
 export { DEFAULT_ENVIRONMENT } from './constants';
+/* eslint-disable deprecation/deprecation */
 export { ModuleMetadata } from './integrations/metadata';
 export { RequestData } from './integrations/requestdata';
-import * as Integrations from './integrations';
+export { InboundFilters } from './integrations/inboundfilters';
+export { FunctionToString } from './integrations/functiontostring';
+export { LinkedErrors } from './integrations/linkederrors';
+/* eslint-enable deprecation/deprecation */
+import * as INTEGRATIONS from './integrations';
+export { functionToStringIntegration } from './integrations/functiontostring';
+export { inboundFiltersIntegration } from './integrations/inboundfilters';
+export { linkedErrorsIntegration } from './integrations/linkederrors';
+export { moduleMetadataIntegration } from './integrations/metadata';
+export { requestDataIntegration } from './integrations/requestdata';
 export { metrics } from './metrics/exports';
 
+/** @deprecated Import the integration function directly, e.g. `inboundFiltersIntegration()` instead of `new Integrations.InboundFilter(). */
+const Integrations = INTEGRATIONS;
+
+// eslint-disable-next-line deprecation/deprecation
 export { Integrations };

packages/core/src/integration.ts

@@ -1,4 +1,13 @@
-import type { Client, Event, EventHint, Integration, IntegrationClass, IntegrationFn, Options } from '@sentry/types';
+import type {
+  Client,
+  Event,
+  EventHint,
+  Integration,
+  IntegrationClass,
+  IntegrationFn,
+  IntegrationFnResult,
+  Options,
+} from '@sentry/types';
 import { arrayify, logger } from '@sentry/utils';
 
 import { DEBUG_BUILD } from './debug-build';
@@ -177,3 +186,11 @@ export function convertIntegrationFnToClass<Fn extends IntegrationFn>(
     { id: name },
   ) as unknown as IntegrationClass<Integration>;
 }
+
+/**
+ * Define an integration function that can be used to create an integration instance.
+ * Note that this by design hides the implementation details of the integration, as they are considered internal.
+ */
+export function defineIntegration<Fn extends IntegrationFn>(fn: Fn): (...args: Parameters<Fn>) => IntegrationFnResult {
+  return fn;
+}