ref: make type exlusive

Author: mydea

packages/core/src/exports.ts

@@ -20,6 +20,7 @@ import { isThenable, logger, timestampInSeconds, uuid4 } from '@sentry/utils';
 import type { Hub } from './hub';
 import { getCurrentHub } from './hub';
 import type { Scope } from './scope';
+import type { ExclusiveEventHintOrCaptureContext } from './utils/prepareEvent';
 import { parseEventHintOrCaptureContext } from './utils/prepareEvent';
 
 // Note: All functions in this file are typed with a return value of `ReturnType<Hub[HUB_FUNCTION]>`,
@@ -37,7 +38,7 @@ import { parseEventHintOrCaptureContext } from './utils/prepareEvent';
 export function captureException(
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   exception: any,
-  hint?: CaptureContext | EventHint,
+  hint?: ExclusiveEventHintOrCaptureContext,
 ): ReturnType<Hub['captureException']> {
   return getCurrentHub().captureException(exception, parseEventHintOrCaptureContext(hint));
 }

packages/core/src/utils/prepareEvent.ts

@@ -4,14 +4,14 @@ import type {
   ClientOptions,
   Event,
   EventHint,
+  Scope as ScopeInterface,
   ScopeContext,
   StackFrame,
   StackParser,
 } from '@sentry/types';
 import {
   addExceptionMechanism,
   dateTimestampInSeconds,
-  dropUndefinedKeys,
   GLOBAL_OBJ,
   normalize,
   resolvedSyncPromise,
@@ -23,6 +23,15 @@ import { DEFAULT_ENVIRONMENT } from '../constants';
 import { getGlobalEventProcessors, notifyEventProcessors } from '../eventProcessors';
 import { Scope } from '../scope';
 
+/**
+ * This type makes sure that we get either a CaptureContext, OR an EventHint.
+ * It does not allow mixing them, which could lead to unexpected outcomes, e.g. this is disallowed:
+ * { user: { id: '123' }, mechanism: { handled: false } }
+ */
+export type ExclusiveEventHintOrCaptureContext =
+  | (CaptureContext & Partial<{ [key in keyof EventHint]: never }>)
+  | (EventHint & Partial<{ [key in keyof ScopeContext]: never }>);
+
 /**
  * Adds common information to events.
  *
@@ -336,7 +345,9 @@ function normalizeEvent(event: Event | null, depth: number, maxBreadth: number):
  * Parse either an `EventHint` directly, or convert a `CaptureContext` to an `EventHint`.
  * This is used to allow to update method signatures that used to accept a `CaptureContext` but should now accept an `EventHint`.
  */
-export function parseEventHintOrCaptureContext(hint: CaptureContext | EventHint | undefined): EventHint | undefined {
+export function parseEventHintOrCaptureContext(
+  hint: ExclusiveEventHintOrCaptureContext | undefined,
+): EventHint | undefined {
   if (!hint) {
     return undefined;
   }
@@ -346,24 +357,33 @@ export function parseEventHintOrCaptureContext(hint: CaptureContext | EventHint
     return { captureContext: hint };
   }
 
-  const hintOrScopeContext = hint as Partial<ScopeContext> & Partial<EventHint>;
-
-  // Else, we need to make sure to pick the legacy CaptureContext fields off & merge them into the hint
-  const { user, level, extra, contexts, tags, fingerprint, requestSession, propagationContext, ...eventHint } =
-    hintOrScopeContext;
-
-  const captureContext = {
-    ...dropUndefinedKeys({ user, level, extra, contexts, tags, fingerprint, requestSession, propagationContext }),
-    ...hintOrScopeContext.captureContext,
-  };
-
-  if (Object.keys(captureContext).length) {
-    eventHint.captureContext = captureContext;
+  if (hintIsScopeContext(hint)) {
+    return {
+      captureContext: hint,
+    };
   }
 
-  return eventHint;
+  return hint;
 }
 
-function hintIsScopeOrFunction(hint: CaptureContext | EventHint): hint is Scope | (() => Scope) {
+function hintIsScopeOrFunction(
+  hint: CaptureContext | EventHint,
+): hint is ScopeInterface | ((scope: ScopeInterface) => ScopeInterface) {
   return hint instanceof Scope || typeof hint === 'function';
 }
+
+type ScopeContextProperty = keyof ScopeContext;
+const captureContextKeys: readonly ScopeContextProperty[] = [
+  'user',
+  'level',
+  'extra',
+  'contexts',
+  'tags',
+  'fingerprint',
+  'requestSession',
+  'propagationContext',
+] as const;
+
+function hintIsScopeContext(hint: Partial<ScopeContext> | EventHint): hint is Partial<ScopeContext> {
+  return Object.keys(hint).some(key => captureContextKeys.includes(key as ScopeContextProperty));
+}

packages/core/test/lib/prepareEvent.test.ts

@@ -1,4 +1,4 @@
-import type { Event, ScopeContext } from '@sentry/types';
+import type { Event, EventHint, ScopeContext } from '@sentry/types';
 import { createStackParser, GLOBAL_OBJ } from '@sentry/utils';
 
 import { Scope } from '../../src/scope';
@@ -130,15 +130,15 @@ describe('parseEventHintOrCaptureContext', () => {
     expect(actual).toEqual({ captureContext: scope });
   });
 
-  it('works with a plain EventHint', () => {
-    const hint = {
+  it('works with an EventHint', () => {
+    const hint: EventHint = {
       mechanism: { handled: false },
     };
     const actual = parseEventHintOrCaptureContext(hint);
     expect(actual).toEqual(hint);
   });
 
-  it('works with a plain ScopeContext', () => {
+  it('works with a ScopeContext', () => {
     const scopeContext: ScopeContext = {
       user: { id: 'xxx' },
       level: 'debug',
@@ -156,31 +156,4 @@ describe('parseEventHintOrCaptureContext', () => {
     const actual = parseEventHintOrCaptureContext(scopeContext);
     expect(actual).toEqual({ captureContext: scopeContext });
   });
-
-  it('works with a ScopeContext & event hint mixed', () => {
-    const scopeContext: ScopeContext = {
-      user: { id: 'xxx' },
-      level: 'debug',
-      extra: { foo: 'bar' },
-      contexts: { os: { name: 'linux' } },
-      tags: { foo: 'bar' },
-      fingerprint: ['xx', 'yy'],
-      requestSession: { status: 'ok' },
-      propagationContext: {
-        traceId: 'xxx',
-        spanId: 'yyy',
-      },
-    };
-
-    const actual = parseEventHintOrCaptureContext({
-      ...scopeContext,
-      mechanism: { handled: false },
-      captureContext: { level: 'error' },
-    });
-    expect(actual).toEqual({
-      // captureContext is merged, where the eventHint takes prededence
-      captureContext: { ...scopeContext, level: 'error' },
-      mechanism: { handled: false },
-    });
-  });
 });