feat(browser): Export functional integrations & deprecate classes

mydea · mydea · commit 03220c0bbbd9 · 2024-01-19T14:17:32.000+01:00
Also deprecate the `Integrations` hash.
diff --git a/MIGRATION.md b/MIGRATION.md
@@ -28,13 +28,26 @@ integrations from the `Integrations.XXX` hash, is deprecated in favor of using t
 
 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()`      |
+| Old                       | New                              |
+| ------------------------- | -------------------------------- |
+| `new InboundFilters()`    | `inboundFiltersIntegrations()`   |
+| `new FunctionToString()`  | `functionToStringIntegration()`  |
+| `new LinkedErrors()`      | `linkedErrorsIntegration()`      |
+| `new ModuleMetadata()`    | `moduleMetadataIntegration()`    |
+| `new CaptureConsole()`    | `captureConsoleIntegration()`    |
+| `new Debug()`             | `debugIntegration()`             |
+| `new Dedupe()`            | `dedupeIntegration()`            |
+| `new ExtraErrorData()`    | `extraErrorDataIntegration()`    |
+| `new ReportingObserver()` | `reportingObserverIntegration()` |
+| `new RewriteFrames()`     | `rewriteFramesIntegration()`     |
+| `new SessionTiming()`     | `sessionTimingIntegration()`     |
+| `new HttpClient()`        | `httpClientIntegration()`        |
+| `new ContextLines()`      | `contextLinesIntegration()`      |
+| `new Breadcrumbs()`       | `breadcrumbsIntegration()`       |
+| `new GlobalHandlers()`    | `globalHandlersIntegration()`    |
+| `new HttpContext()`       | `httpContextIntegration()`       |
+| `new LinkedErrors()`      | `linkedErrorsIntegration()`      |
+| `new TryCatch()`          | `browserApiErrorsIntegration()`  |
 
 ## Deprecate `hub.bindClient()` and `makeMain()`
 
diff --git a/packages/astro/src/index.types.ts b/packages/astro/src/index.types.ts
@@ -14,8 +14,11 @@ import sentryAstro from './index.server';
 export declare function init(options: Options | clientSdk.BrowserOptions | serverSdk.NodeOptions): void;
 
 // We export a merged Integrations object so that users can (at least typing-wise) use all integrations everywhere.
+// eslint-disable-next-line deprecation/deprecation
 export declare const Integrations: typeof clientSdk.Integrations & typeof serverSdk.Integrations;
 
+export declare const linkedErrorsIntegration: typeof clientSdk.linkedErrorsIntegration;
+
 export declare const defaultIntegrations: Integration[];
 export declare const getDefaultIntegrations: (options: Options) => Integration[];
 export declare const defaultStackParser: StackParser;
diff --git a/packages/browser/src/exports.ts b/packages/browser/src/exports.ts
@@ -100,4 +100,13 @@ export {
   // eslint-disable-next-line deprecation/deprecation
   wrap,
 } from './sdk';
+
+export { breadcrumbsIntegration } from './integrations/breadcrumbs';
+export { dedupeIntegration } from './integrations/dedupe';
+export { globalHandlersIntegration } from './integrations/globalhandlers';
+export { httpContextIntegration } from './integrations/httpcontext';
+export { linkedErrorsIntegration } from './integrations/linkederrors';
+export { browserApiErrorsIntegration } from './integrations/trycatch';
+
+// eslint-disable-next-line deprecation/deprecation
 export { GlobalHandlers, TryCatch, Breadcrumbs, LinkedErrors, HttpContext, Dedupe } from './integrations';
diff --git a/packages/browser/src/index.ts b/packages/browser/src/index.ts
@@ -12,13 +12,15 @@ if (WINDOW.Sentry && WINDOW.Sentry.Integrations) {
   windowIntegrations = WINDOW.Sentry.Integrations;
 }
 
+/** @deprecated Import the integration function directly, e.g. `inboundFiltersIntegration()` instead of `new Integrations.InboundFilter(). */
 const INTEGRATIONS = {
   ...windowIntegrations,
   // eslint-disable-next-line deprecation/deprecation
   ...CoreIntegrations,
   ...BrowserIntegrations,
 };
 
+// eslint-disable-next-line deprecation/deprecation
 export { INTEGRATIONS as Integrations };
 
 export { Replay } from '@sentry/replay';
diff --git a/packages/browser/src/integrations/breadcrumbs.ts b/packages/browser/src/integrations/breadcrumbs.ts
@@ -1,5 +1,5 @@
 /* eslint-disable max-lines */
-import { addBreadcrumb, convertIntegrationFnToClass, getClient } from '@sentry/core';
+import { addBreadcrumb, convertIntegrationFnToClass, defineIntegration, getClient } from '@sentry/core';
 import type {
   Client,
   Event as SentryEvent,
@@ -57,7 +57,7 @@ const MAX_ALLOWED_STRING_LENGTH = 1024;
 
 const INTEGRATION_NAME = 'Breadcrumbs';
 
-const breadcrumbsIntegration = ((options: Partial<BreadcrumbsOptions> = {}) => {
+const _breadcrumbsIntegration = ((options: Partial<BreadcrumbsOptions> = {}) => {
   const _options = {
     console: true,
     dom: true,
@@ -95,8 +95,12 @@ const breadcrumbsIntegration = ((options: Partial<BreadcrumbsOptions> = {}) => {
   };
 }) satisfies IntegrationFn;
 
+export const breadcrumbsIntegration = defineIntegration(_breadcrumbsIntegration);
+
 /**
  * Default Breadcrumbs instrumentations
+ *
+ * @deprecated Use `breadcrumbsIntegration()` instead.
  */
 // eslint-disable-next-line deprecation/deprecation
 export const Breadcrumbs = convertIntegrationFnToClass(INTEGRATION_NAME, breadcrumbsIntegration) as IntegrationClass<
diff --git a/packages/browser/src/integrations/dedupe.ts b/packages/browser/src/integrations/dedupe.ts
@@ -1,12 +1,12 @@
-import { convertIntegrationFnToClass } from '@sentry/core';
+import { convertIntegrationFnToClass, defineIntegration } from '@sentry/core';
 import type { Event, Exception, Integration, IntegrationClass, IntegrationFn, StackFrame } from '@sentry/types';
 import { logger } from '@sentry/utils';
 
 import { DEBUG_BUILD } from '../debug-build';
 
 const INTEGRATION_NAME = 'Dedupe';
 
-const dedupeIntegration = (() => {
+const _dedupeIntegration = (() => {
   let previousEvent: Event | undefined;
 
   return {
@@ -33,7 +33,12 @@ const dedupeIntegration = (() => {
   };
 }) satisfies IntegrationFn;
 
-/** Deduplication filter */
+export const dedupeIntegration = defineIntegration(_dedupeIntegration);
+
+/**
+ * Deduplication filter.
+ * @deprecated Use `dedupeIntegration()` instead.
+ */
 // eslint-disable-next-line deprecation/deprecation
 export const Dedupe = convertIntegrationFnToClass(INTEGRATION_NAME, dedupeIntegration) as IntegrationClass<
   Integration & { processEvent: (event: Event) => Event }
diff --git a/packages/browser/src/integrations/globalhandlers.ts b/packages/browser/src/integrations/globalhandlers.ts
@@ -1,5 +1,5 @@
 /* eslint-disable @typescript-eslint/no-unsafe-member-access */
-import { captureEvent, convertIntegrationFnToClass, getClient } from '@sentry/core';
+import { captureEvent, convertIntegrationFnToClass, defineIntegration, getClient } from '@sentry/core';
 import type {
   Client,
   Event,
@@ -30,7 +30,7 @@ type GlobalHandlersIntegrations = Record<GlobalHandlersIntegrationsOptionKeys, b
 
 const INTEGRATION_NAME = 'GlobalHandlers';
 
-const globalHandlersIntegration = ((options: Partial<GlobalHandlersIntegrations> = {}) => {
+const _globalHandlersIntegration = ((options: Partial<GlobalHandlersIntegrations> = {}) => {
   const _options = {
     onerror: true,
     onunhandledrejection: true,
@@ -55,7 +55,12 @@ const globalHandlersIntegration = ((options: Partial<GlobalHandlersIntegrations>
   };
 }) satisfies IntegrationFn;
 
-/** Global handlers */
+export const globalHandlersIntegration = defineIntegration(_globalHandlersIntegration);
+
+/**
+ * Global handlers.
+ * @deprecated Use `globalHandlersIntegration()` instead.
+ */
 // eslint-disable-next-line deprecation/deprecation
 export const GlobalHandlers = convertIntegrationFnToClass(
   INTEGRATION_NAME,
diff --git a/packages/browser/src/integrations/httpcontext.ts b/packages/browser/src/integrations/httpcontext.ts
@@ -1,11 +1,11 @@
-import { convertIntegrationFnToClass } from '@sentry/core';
+import { convertIntegrationFnToClass, defineIntegration } from '@sentry/core';
 import type { Event, Integration, IntegrationClass, IntegrationFn } from '@sentry/types';
 
 import { WINDOW } from '../helpers';
 
 const INTEGRATION_NAME = 'HttpContext';
 
-const httpContextIntegration = (() => {
+const _httpContextIntegration = (() => {
   return {
     name: INTEGRATION_NAME,
     // TODO v8: Remove this
@@ -33,7 +33,12 @@ const httpContextIntegration = (() => {
   };
 }) satisfies IntegrationFn;
 
-/** HttpContext integration collects information about HTTP request headers */
+export const httpContextIntegration = defineIntegration(_httpContextIntegration);
+
+/**
+ * HttpContext integration collects information about HTTP request headers.
+ * @deprecated Use `httpContextIntegration()` instead.
+ */
 // eslint-disable-next-line deprecation/deprecation
 export const HttpContext = convertIntegrationFnToClass(INTEGRATION_NAME, httpContextIntegration) as IntegrationClass<
   Integration & { preprocessEvent: (event: Event) => void }
diff --git a/packages/browser/src/integrations/index.ts b/packages/browser/src/integrations/index.ts
@@ -1,3 +1,4 @@
+/* eslint-disable deprecation/deprecation */
 export { GlobalHandlers } from './globalhandlers';
 export { TryCatch } from './trycatch';
 export { Breadcrumbs } from './breadcrumbs';
diff --git a/packages/browser/src/integrations/linkederrors.ts b/packages/browser/src/integrations/linkederrors.ts
@@ -1,4 +1,4 @@
-import { convertIntegrationFnToClass } from '@sentry/core';
+import { convertIntegrationFnToClass, defineIntegration } from '@sentry/core';
 import type { Client, Event, EventHint, Integration, IntegrationClass, IntegrationFn } from '@sentry/types';
 import { applyAggregateErrorsToEvent } from '@sentry/utils';
 import { exceptionFromError } from '../eventbuilder';
@@ -13,7 +13,7 @@ const DEFAULT_LIMIT = 5;
 
 const INTEGRATION_NAME = 'LinkedErrors';
 
-const linkedErrorsIntegration = ((options: LinkedErrorsOptions = {}) => {
+const _linkedErrorsIntegration = ((options: LinkedErrorsOptions = {}) => {
   const limit = options.limit || DEFAULT_LIMIT;
   const key = options.key || DEFAULT_KEY;
 
@@ -38,7 +38,12 @@ const linkedErrorsIntegration = ((options: LinkedErrorsOptions = {}) => {
   };
 }) satisfies IntegrationFn;
 
-/** Aggregrate linked errors in an event. */
+export const linkedErrorsIntegration = defineIntegration(_linkedErrorsIntegration);
+
+/**
+ * Aggregrate linked errors in an event.
+ * @deprecated Use `linkedErrorsIntegration()` instead.
+ */
 // eslint-disable-next-line deprecation/deprecation
 export const LinkedErrors = convertIntegrationFnToClass(INTEGRATION_NAME, linkedErrorsIntegration) as IntegrationClass<
   Integration & { preprocessEvent: (event: Event, hint: EventHint, client: Client) => void }
diff --git a/packages/browser/src/integrations/trycatch.ts b/packages/browser/src/integrations/trycatch.ts
@@ -1,4 +1,4 @@
-import { convertIntegrationFnToClass } from '@sentry/core';
+import { convertIntegrationFnToClass, defineIntegration } from '@sentry/core';
 import type { Integration, IntegrationClass, IntegrationFn, WrappedFunction } from '@sentry/types';
 import { fill, getFunctionName, getOriginalFunction } from '@sentry/utils';
 
@@ -50,7 +50,7 @@ interface TryCatchOptions {
   eventTarget: boolean | string[];
 }
 
-const browserApiErrorsIntegration = ((options: Partial<TryCatchOptions> = {}) => {
+const _browserApiErrorsIntegration = ((options: Partial<TryCatchOptions> = {}) => {
   const _options = {
     XMLHttpRequest: true,
     eventTarget: true,
@@ -90,7 +90,12 @@ const browserApiErrorsIntegration = ((options: Partial<TryCatchOptions> = {}) =>
   };
 }) satisfies IntegrationFn;
 
-/** Wrap timer functions and event targets to catch errors and provide better meta data */
+export const browserApiErrorsIntegration = defineIntegration(_browserApiErrorsIntegration);
+
+/**
+ * Wrap timer functions and event targets to catch errors and provide better meta data.
+ * @deprecated Use `browserApiErrorsIntegration()` instead.
+ */
 // eslint-disable-next-line deprecation/deprecation
 export const TryCatch = convertIntegrationFnToClass(
   INTEGRATION_NAME,
diff --git a/packages/browser/src/sdk.ts b/packages/browser/src/sdk.ts
@@ -1,7 +1,6 @@
 import type { Hub } from '@sentry/core';
+import { functionToStringIntegration, inboundFiltersIntegration } from '@sentry/core';
 import {
-  FunctionToString,
-  InboundFilters,
   captureSession,
   getClient,
   getCurrentHub,
@@ -23,22 +22,25 @@ import { BrowserClient } from './client';
 import { DEBUG_BUILD } from './debug-build';
 import type { ReportDialogOptions } from './helpers';
 import { WINDOW, wrap as internalWrap } from './helpers';
-import { Breadcrumbs, Dedupe, GlobalHandlers, HttpContext, LinkedErrors, TryCatch } from './integrations';
+import { breadcrumbsIntegration } from './integrations/breadcrumbs';
+import { dedupeIntegration } from './integrations/dedupe';
+import { globalHandlersIntegration } from './integrations/globalhandlers';
+import { httpContextIntegration } from './integrations/httpcontext';
+import { linkedErrorsIntegration } from './integrations/linkederrors';
+import { browserApiErrorsIntegration } from './integrations/trycatch';
 import { defaultStackParser } from './stack-parsers';
 import { makeFetchTransport, makeXHRTransport } from './transports';
 
 /** @deprecated Use `getDefaultIntegrations(options)` instead. */
 export const defaultIntegrations = [
-  /* eslint-disable deprecation/deprecation */
-  new InboundFilters(),
-  new FunctionToString(),
-  /* eslint-enable deprecation/deprecation */
-  new TryCatch(),
-  new Breadcrumbs(),
-  new GlobalHandlers(),
-  new LinkedErrors(),
-  new Dedupe(),
-  new HttpContext(),
+  inboundFiltersIntegration(),
+  functionToStringIntegration(),
+  browserApiErrorsIntegration(),
+  breadcrumbsIntegration(),
+  globalHandlersIntegration(),
+  linkedErrorsIntegration(),
+  dedupeIntegration(),
+  httpContextIntegration(),
 ];
 
 /** Get the default integrations for the browser SDK. */
diff --git a/packages/browser/test/unit/integrations/breadcrumbs.test.ts b/packages/browser/test/unit/integrations/breadcrumbs.test.ts
@@ -8,6 +8,7 @@ describe('Breadcrumbs', () => {
     const client = new BrowserClient({
       ...getDefaultBrowserClientOptions(),
       dsn: 'https://username@domain/123',
+      // eslint-disable-next-line deprecation/deprecation
       integrations: [new Breadcrumbs()],
     });
 
diff --git a/packages/deno/src/sdk.ts b/packages/deno/src/sdk.ts
@@ -1,6 +1,6 @@
-import { Breadcrumbs, Dedupe } from '@sentry/browser';
+import { breadcrumbsIntegration, dedupeIntegration } from '@sentry/browser';
 import type { ServerRuntimeClientOptions } from '@sentry/core';
-import { FunctionToString, InboundFilters, LinkedErrors } from '@sentry/core';
+import { functionToStringIntegration, inboundFiltersIntegration, linkedErrorsIntegration } from '@sentry/core';
 import { getIntegrationsToSetup, initAndBind } from '@sentry/core';
 import type { Integration, Options, StackParser } from '@sentry/types';
 import { createStackParser, nodeStackLineParser, stackParserFromStackParserOptions } from '@sentry/utils';
@@ -12,15 +12,13 @@ import type { DenoOptions } from './types';
 
 /** @deprecated Use `getDefaultIntegrations(options)` instead. */
 export const defaultIntegrations = [
-  /* eslint-disable deprecation/deprecation */
   // Common
-  new InboundFilters(),
-  new FunctionToString(),
-  new LinkedErrors(),
-  /* eslint-enable deprecation/deprecation */
+  inboundFiltersIntegration(),
+  functionToStringIntegration(),
+  linkedErrorsIntegration(),
   // From Browser
-  new Dedupe(),
-  new Breadcrumbs({
+  dedupeIntegration(),
+  breadcrumbsIntegration({
     dom: false,
     history: false,
     xhr: false,
diff --git a/packages/nextjs/src/client/index.ts b/packages/nextjs/src/client/index.ts
@@ -18,7 +18,9 @@ export * from '@sentry/react';
 export { nextRouterInstrumentation } from './routing/nextRoutingInstrumentation';
 export { captureUnderscoreErrorException } from '../common/_error';
 
+/** @deprecated Import the integration function directly, e.g. `inboundFiltersIntegration()` instead of `new Integrations.InboundFilter(). */
 export const Integrations = {
+  // eslint-disable-next-line deprecation/deprecation
   ...OriginalIntegrations,
   BrowserTracing,
 };
diff --git a/packages/nextjs/src/index.types.ts b/packages/nextjs/src/index.types.ts
@@ -20,10 +20,13 @@ export declare function init(
 ): void;
 
 // We export a merged Integrations object so that users can (at least typing-wise) use all integrations everywhere.
+// eslint-disable-next-line deprecation/deprecation
 export declare const Integrations: typeof clientSdk.Integrations &
   typeof serverSdk.Integrations &
   typeof edgeSdk.Integrations;
 
+export declare const linkedErrorsIntegration: typeof clientSdk.linkedErrorsIntegration;
+
 export declare const defaultIntegrations: Integration[];
 export declare const getDefaultIntegrations: (options: Options) => Integration[];
 export declare const defaultStackParser: StackParser;
diff --git a/packages/nextjs/test/clientSdk.test.ts b/packages/nextjs/test/clientSdk.test.ts
@@ -6,7 +6,7 @@ import type { Integration } from '@sentry/types';
 import { logger } from '@sentry/utils';
 import { JSDOM } from 'jsdom';
 
-import { BrowserTracing, Integrations, init, nextRouterInstrumentation } from '../src/client';
+import { BrowserTracing, breadcrumbsIntegration, init, nextRouterInstrumentation } from '../src/client';
 
 const reactInit = jest.spyOn(SentryReact, 'init');
 const captureEvent = jest.spyOn(BaseClient.prototype, 'captureEvent');
@@ -108,12 +108,12 @@ describe('Client init()', () => {
     type ModifiedInitOptionsIntegrationArray = { defaultIntegrations: Integration[]; integrations: Integration[] };
 
     it('supports passing unrelated integrations through options', () => {
-      init({ integrations: [new Integrations.Breadcrumbs({ console: false })] });
+      init({ integrations: [breadcrumbsIntegration({ console: false })] });
 
       const reactInitOptions = reactInit.mock.calls[0][0] as ModifiedInitOptionsIntegrationArray;
-      const breadcrumbsIntegration = findIntegrationByName(reactInitOptions.integrations, 'Breadcrumbs');
+      const installedBreadcrumbsIntegration = findIntegrationByName(reactInitOptions.integrations, 'Breadcrumbs');
 
-      expect(breadcrumbsIntegration).toBeDefined();
+      expect(installedBreadcrumbsIntegration).toBeDefined();
     });
 
     describe('`BrowserTracing` integration', () => {
diff --git a/packages/remix/src/index.types.ts b/packages/remix/src/index.types.ts
@@ -13,8 +13,11 @@ import type { RemixOptions } from './utils/remixOptions';
 export declare function init(options: RemixOptions): void;
 
 // We export a merged Integrations object so that users can (at least typing-wise) use all integrations everywhere.
+// eslint-disable-next-line deprecation/deprecation
 export declare const Integrations: typeof clientSdk.Integrations & typeof serverSdk.Integrations;
 
+export declare const linkedErrorsIntegration: typeof clientSdk.linkedErrorsIntegration;
+
 export declare const defaultIntegrations: Integration[];
 export declare const getDefaultIntegrations: (options: Options) => Integration[];
 export declare const defaultStackParser: StackParser;
diff --git a/packages/sveltekit/src/index.types.ts b/packages/sveltekit/src/index.types.ts

Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+/* eslint-disable deprecation/deprecation */`
`1`	`2`	`export { GlobalHandlers } from './globalhandlers';`
`2`	`3`	`export { TryCatch } from './trycatch';`
`3`	`4`	`export { Breadcrumbs } from './breadcrumbs';`