WIP: Add makeIntegrationFn util

Author: mydea

packages/core/src/integration.ts

@@ -1,4 +1,4 @@
-import type { Client, Event, EventHint, Integration, Options } from '@sentry/types';
+import type { Client, Event, EventHint, Integration, IntegrationFn, IntegrationFnResult, Options } from '@sentry/types';
 import { arrayify, logger } from '@sentry/utils';
 
 import { DEBUG_BUILD } from './debug-build';
@@ -155,3 +155,27 @@ function findIndex<T>(arr: T[], callback: (item: T) => boolean): number {
 
   return -1;
 }
+
+/**
+ * Generate a full integration function from a simple function.
+ * This will ensure to add the given name both to the function definition, as well as to the integration return value.
+ */
+export function makeIntegrationFn<
+  Fn extends (...rest: any[]) => Partial<IntegrationFnResult>,
+>(name: string, fn: Fn): ((...rest: Parameters<Fn>) => ReturnType<Fn> & { name: string }) & { id: string } {
+  const patchedFn = addIdToIntegrationFnResult(name, fn);
+
+
+  return Object.assign(patchedFn, { id: name });
+}
+
+function addIdToIntegrationFnResult<Fn extends (...rest: any[]) => Partial<IntegrationFnResult>>(
+  name: string,
+  fn: Fn,
+): (...rest: Parameters<Fn>) => ReturnType<Fn> & { name: string } {
+  const patchedFn = ((...rest: Parameters<Fn>): ReturnType<Fn> & { name: string } => {
+    return { ...fn(...rest), name } as ReturnType<Fn> & { name: string };
+  });
+
+  return patchedFn;
+}

packages/core/test/lib/integration.test.ts

@@ -2,7 +2,13 @@ import type { Integration, Options } from '@sentry/types';
 import { logger } from '@sentry/utils';
 
 import { Hub, makeMain } from '../../src/hub';
-import { addIntegration, getIntegrationsToSetup, installedIntegrations, setupIntegration } from '../../src/integration';
+import {
+  addIntegration,
+  getIntegrationsToSetup,
+  installedIntegrations,
+  makeIntegrationFn,
+  setupIntegration,
+} from '../../src/integration';
 import { TestClient, getDefaultTestClientOptions } from '../mocks/client';
 
 function getTestClient(): TestClient {
@@ -647,3 +653,69 @@ describe('addIntegration', () => {
     expect(warnings).toHaveBeenCalledWith('Cannot add integration "test" because no SDK Client is available.');
   });
 });
+
+describe('makeIntegrationFn', () => {
+  it('works with a minimal integration', () => {
+    const myIntegration = makeIntegrationFn('testName', () => {
+      return {};
+    });
+
+    expect(myIntegration.id).toBe('testName');
+
+    const integration = myIntegration();
+    expect(integration).toEqual({
+      name: 'testName',
+    });
+
+    // @ts-expect-error This SHOULD error
+    myIntegration({});
+  });
+
+  it('works with integration options', () => {
+    const myIntegration = makeIntegrationFn('testName', (_options: { xxx: string }) => {
+      return {};
+    });
+
+    expect(myIntegration.id).toBe('testName');
+
+    const integration = myIntegration({ xxx: 'aa' });
+    expect(integration).toEqual({
+      name: 'testName',
+    });
+
+    // @ts-expect-error This SHOULD error
+    myIntegration();
+    // @ts-expect-error This SHOULD error
+    myIntegration({});
+  });
+
+  it('works with integration hooks', () => {
+    const setup = jest.fn();
+    const setupOnce = jest.fn();
+    const processEvent = jest.fn();
+    const preprocessEvent = jest.fn();
+
+    const myIntegration = makeIntegrationFn('testName', () => {
+      return {
+        setup,
+        setupOnce,
+        processEvent,
+        preprocessEvent,
+      };
+    });
+
+    expect(myIntegration.id).toBe('testName');
+
+    const integration = myIntegration();
+    expect(integration).toEqual({
+      name: 'testName',
+      setup,
+      setupOnce,
+      processEvent,
+      preprocessEvent,
+    });
+
+    // @ts-expect-error This SHOULD error
+    makeIntegrationFn('testName', () => ({ other: 'aha' }));
+  });
+});

packages/types/src/index.ts

@@ -52,7 +52,7 @@ export type { EventProcessor } from './eventprocessor';
 export type { Exception } from './exception';
 export type { Extra, Extras } from './extra';
 export type { Hub } from './hub';
-export type { Integration, IntegrationClass } from './integration';
+export type { Integration, IntegrationClass, IntegrationFn, IntegrationFnResult } from './integration';
 export type { Mechanism } from './mechanism';
 export type { ExtractedNodeRequestData, HttpHeaderValue, Primitive, WorkerLocation } from './misc';
 export type { ClientOptions, Options } from './options';

packages/types/src/integration.ts

@@ -10,7 +10,49 @@ export interface IntegrationClass<T> {
    */
   id: string;
 
-  new (...args: any[]): T;
+  new(...args: any[]): T;
+}
+
+/**
+ * An integration in function form.
+ * This is expected to return an integration result,
+ * and also have a `name` property that holds the integration name (so we can e.g. filter these before actually calling them).
+ */
+export type IntegrationFn<Fn extends ((...rest: any[]) => IntegrationFnResult)> = { id: string } & Fn;
+
+export interface IntegrationFnResult {
+  /**
+   * The name of the integration.
+   */
+  name: string;
+
+  /**
+   * This hook is only called once, even if multiple clients are created.
+   * It does not receives any arguments, and should only use for e.g. global monkey patching and similar things.
+   */
+  setupOnce?(): void;
+
+  /**
+   * Set up an integration for the given client.
+   * Receives the client as argument.
+   *
+   * Whenever possible, prefer this over `setupOnce`, as that is only run for the first client,
+   * whereas `setup` runs for each client. Only truly global things (e.g. registering global handlers)
+   * should be done in `setupOnce`.
+   */
+  setup?(client: Client): void;
+
+  /**
+   * An optional hook that allows to preprocess an event _before_ it is passed to all other event processors.
+   */
+  preprocessEvent?(event: Event, hint: EventHint | undefined, client: Client): void;
+
+  /**
+   * An optional hook that allows to process an event.
+   * Return `null` to drop the event, or mutate the event & return it.
+   * This receives the client that the integration was installed for as third argument.
+   */
+  processEvent?(event: Event, hint: EventHint, client: Client): Event | null | PromiseLike<Event | null>;
 }
 
 /** Integration interface */