ref(types): Stop using Severity enum (#4926)

Note: This and #4896 are together a (slightly updated) repeat of #4497, to get it onto the main v7 branch.

Our original v7 plan called for deprecating and then removing the `Severity` enum which lives in `@sentry/types`, because enums transpile to a two-way lookup function with a fairly hefty footprint (see this SO answer[1] from one of the maintainers of TS). We therefore added a new `SeverityLevel` type, which is the union of all of `Severity`'s underlying values, and directed people to use that instead. Though we subsequently decided not to remove `Severity` (at least in v7), we agreed that we should stop using it internally. This implements that change.

Key Changes:

- `Severity` and `severityFromString` have been redeprecated.
- The original plan to have `SeverityLevel` live in `@sentry/utils` has been reverted, and it now lives only in `@sentry/types`. 
- The internal `SeverityLevels` array on which we were basing `SeverityLevel` has been removed. While we lose the elegance of the derived type, we gain the ability to truly only export types from `@sentry/types`.
- Wherever we accept a `Severity` value, we now also accept a `SeverityLevel`.
- All internal uses of `Severity` values have been replaced with the equivalent string constants.
- A new `severityLevelFromString` function has been introduced, and is now used in place of `SeverityFromString`.
- The tests for `severityFromString` have been cleaned up and replaced with equivalent tests for `SeverityLevelFromString`.

[1] https://stackoverflow.com/a/28818850

Author: lobsterkatie

packages/browser/src/client.ts

@@ -1,5 +1,5 @@
 import { BaseClient, getEnvelopeEndpointWithUrlEncodedAuth, initAPIDetails, Scope, SDK_VERSION } from '@sentry/core';
-import { Event, EventHint, Options, Severity, Transport, TransportOptions } from '@sentry/types';
+import { Event, EventHint, Options, Severity, SeverityLevel, Transport, TransportOptions } from '@sentry/types';
 import { getGlobalObject, logger, stackParserFromOptions, supportsFetch } from '@sentry/utils';
 
 import { eventFromException, eventFromMessage } from './eventbuilder';
@@ -89,7 +89,12 @@ export class BrowserClient extends BaseClient<BrowserOptions> {
   /**
    * @inheritDoc
    */
-  public eventFromMessage(message: string, level: Severity = Severity.Info, hint?: EventHint): PromiseLike<Event> {
+  public eventFromMessage(
+    message: string,
+    // eslint-disable-next-line deprecation/deprecation
+    level: Severity | SeverityLevel = 'info',
+    hint?: EventHint,
+  ): PromiseLike<Event> {
     return eventFromMessage(
       stackParserFromOptions(this._options),
       message,

packages/browser/src/eventbuilder.ts

@@ -1,4 +1,4 @@
-import { Event, EventHint, Exception, Severity, StackFrame, StackParser } from '@sentry/types';
+import { Event, EventHint, Exception, Severity, SeverityLevel, StackFrame, StackParser } from '@sentry/types';
 import {
   addExceptionMechanism,
   addExceptionTypeValue,
@@ -150,7 +150,7 @@ export function eventFromException(
   const syntheticException = (hint && hint.syntheticException) || undefined;
   const event = eventFromUnknownInput(stackParser, exception, syntheticException, attachStacktrace);
   addExceptionMechanism(event); // defaults to { type: 'generic', handled: true }
-  event.level = Severity.Error;
+  event.level = 'error';
   if (hint && hint.event_id) {
     event.event_id = hint.event_id;
   }
@@ -164,7 +164,8 @@ export function eventFromException(
 export function eventFromMessage(
   stackParser: StackParser,
   message: string,
-  level: Severity = Severity.Info,
+  // eslint-disable-next-line deprecation/deprecation
+  level: Severity | SeverityLevel = 'info',
   hint?: EventHint,
   attachStacktrace?: boolean,
 ): PromiseLike<Event> {

packages/browser/src/exports.ts

@@ -8,15 +8,15 @@ export {
   EventStatus,
   Exception,
   Response,
+  // eslint-disable-next-line deprecation/deprecation
   Severity,
+  SeverityLevel,
   StackFrame,
   Stacktrace,
   Thread,
   User,
 } from '@sentry/types';
 
-export { SeverityLevel } from '@sentry/utils';
-
 export {
   addGlobalEventProcessor,
   addBreadcrumb,

packages/browser/src/integrations/breadcrumbs.ts

@@ -1,15 +1,15 @@
 /* eslint-disable @typescript-eslint/no-unsafe-member-access */
 /* eslint-disable max-lines */
 import { getCurrentHub } from '@sentry/core';
-import { Event, Integration, Severity } from '@sentry/types';
+import { Event, Integration } from '@sentry/types';
 import {
   addInstrumentationHandler,
   getEventDescription,
   getGlobalObject,
   htmlTreeAsString,
   parseUrl,
   safeJoin,
-  severityFromString,
+  severityLevelFromString,
 } from '@sentry/utils';
 
 /** JSDoc */
@@ -157,7 +157,7 @@ function _consoleBreadcrumb(handlerData: { [key: string]: any }): void {
       arguments: handlerData.args,
       logger: 'console',
     },
-    level: severityFromString(handlerData.level),
+    level: severityLevelFromString(handlerData.level),
     message: safeJoin(handlerData.args, ' '),
   };
 
@@ -230,7 +230,7 @@ function _fetchBreadcrumb(handlerData: { [key: string]: any }): void {
       {
         category: 'fetch',
         data: handlerData.fetchData,
-        level: Severity.Error,
+        level: 'error',
         type: 'http',
       },
       {

packages/browser/src/integrations/globalhandlers.ts

@@ -1,6 +1,6 @@
 /* eslint-disable @typescript-eslint/no-unsafe-member-access */
 import { getCurrentHub } from '@sentry/core';
-import { Event, EventHint, Hub, Integration, Primitive, Severity, StackParser } from '@sentry/types';
+import { Event, EventHint, Hub, Integration, Primitive, StackParser } from '@sentry/types';
 import {
   addExceptionMechanism,
   addInstrumentationHandler,
@@ -100,7 +100,7 @@ function _installGlobalOnErrorHandler(): void {
               column,
             );
 
-      event.level = Severity.Error;
+      event.level = 'error';
 
       addMechanismAndCapture(hub, error, event, 'onerror');
     },
@@ -146,7 +146,7 @@ function _installGlobalOnUnhandledRejectionHandler(): void {
         ? _eventFromRejectionWithPrimitive(error)
         : eventFromUnknownInput(stackParser, error, undefined, attachStacktrace, true);
 
-      event.level = Severity.Error;
+      event.level = 'error';
 
       addMechanismAndCapture(hub, error, event, 'onunhandledrejection');
       return;

packages/core/src/baseclient.ts

@@ -9,6 +9,7 @@ import {
   IntegrationClass,
   Options,
   Severity,
+  SeverityLevel,
   Transport,
 } from '@sentry/types';
 import {
@@ -131,7 +132,13 @@ export abstract class BaseClient<O extends Options> implements Client<O> {
   /**
    * @inheritDoc
    */
-  public captureMessage(message: string, level?: Severity, hint?: EventHint, scope?: Scope): string | undefined {
+  public captureMessage(
+    message: string,
+    // eslint-disable-next-line deprecation/deprecation
+    level?: Severity | SeverityLevel,
+    hint?: EventHint,
+    scope?: Scope,
+  ): string | undefined {
     let eventId: string | undefined = hint && hint.event_id;
 
     const promisedEvent = isPrimitive(message)
@@ -685,7 +692,12 @@ export abstract class BaseClient<O extends Options> implements Client<O> {
   /**
    * @inheritDoc
    */
-  public abstract eventFromMessage(_message: string, _level?: Severity, _hint?: EventHint): PromiseLike<Event>;
+  public abstract eventFromMessage(
+    _message: string,
+    // eslint-disable-next-line deprecation/deprecation
+    _level?: Severity | SeverityLevel,
+    _hint?: EventHint,
+  ): PromiseLike<Event>;
 }
 
 /**

packages/core/test/mocks/client.ts

@@ -1,5 +1,5 @@
 import { Session } from '@sentry/hub';
-import { Event, Options, Severity, Transport } from '@sentry/types';
+import { Event, Options, Severity, SeverityLevel, Transport } from '@sentry/types';
 import { resolvedSyncPromise } from '@sentry/utils';
 
 import { BaseClient } from '../../src/baseclient';
@@ -38,7 +38,11 @@ export class TestClient extends BaseClient<TestOptions> {
     });
   }
 
-  public eventFromMessage(message: string, level: Severity = Severity.Info): PromiseLike<Event> {
+  public eventFromMessage(
+    message: string,
+    // eslint-disable-next-line deprecation/deprecation
+    level: Severity | SeverityLevel = 'info',
+  ): PromiseLike<Event> {
     return resolvedSyncPromise({ message, level });
   }
 

packages/hub/src/hub.ts

@@ -14,6 +14,7 @@ import {
   Primitive,
   SessionContext,
   Severity,
+  SeverityLevel,
   Transaction,
   TransactionContext,
   User,
@@ -213,7 +214,12 @@ export class Hub implements HubInterface {
   /**
    * @inheritDoc
    */
-  public captureMessage(message: string, level?: Severity, hint?: EventHint): string {
+  public captureMessage(
+    message: string,
+    // eslint-disable-next-line deprecation/deprecation
+    level?: Severity | SeverityLevel,
+    hint?: EventHint,
+  ): string {
     const eventId = (this._lastEventId = hint && hint.event_id ? hint.event_id : uuid4());
     let finalHint = hint;
 

packages/hub/src/scope.ts

@@ -14,6 +14,7 @@ import {
   Scope as ScopeInterface,
   ScopeContext,
   Severity,
+  SeverityLevel,
   Span,
   Transaction,
   User,
@@ -61,7 +62,8 @@ export class Scope implements ScopeInterface {
   protected _fingerprint?: string[];
 
   /** Severity */
-  protected _level?: Severity;
+  // eslint-disable-next-line deprecation/deprecation
+  protected _level?: Severity | SeverityLevel;
 
   /** Transaction Name */
   protected _transactionName?: string;
@@ -208,7 +210,10 @@ export class Scope implements ScopeInterface {
   /**
    * @inheritDoc
    */
-  public setLevel(level: Severity): this {
+  public setLevel(
+    // eslint-disable-next-line deprecation/deprecation
+    level: Severity | SeverityLevel,
+  ): this {
     this._level = level;
     this._notifyScopeListeners();
     return this;

packages/hub/test/scope.test.ts

@@ -1,4 +1,4 @@
-import { Event, EventHint, Severity } from '@sentry/types';
+import { Event, EventHint } from '@sentry/types';
 import { getGlobalObject } from '@sentry/utils';
 
 import { addGlobalEventProcessor, Scope } from '../src';
@@ -85,8 +85,8 @@ describe('Scope', () => {
 
     test('setLevel', () => {
       const scope = new Scope();
-      scope.setLevel(Severity.Critical);
-      expect((scope as any)._level).toEqual(Severity.Critical);
+      scope.setLevel('critical');
+      expect((scope as any)._level).toEqual('critical');
     });
 
     test('setTransactionName', () => {
@@ -137,8 +137,8 @@ describe('Scope', () => {
 
     test('chaining', () => {
       const scope = new Scope();
-      scope.setLevel(Severity.Critical).setUser({ id: '1' });
-      expect((scope as any)._level).toEqual(Severity.Critical);
+      scope.setLevel('critical').setUser({ id: '1' });
+      expect((scope as any)._level).toEqual('critical');
       expect((scope as any)._user).toEqual({ id: '1' });
     });
   });
@@ -202,7 +202,7 @@ describe('Scope', () => {
       scope.setTag('a', 'b');
       scope.setUser({ id: '1' });
       scope.setFingerprint(['abcd']);
-      scope.setLevel(Severity.Warning);
+      scope.setLevel('warning');
       scope.setTransactionName('/abc');
       scope.addBreadcrumb({ message: 'test' });
       scope.setContext('os', { id: '1' });
@@ -294,11 +294,11 @@ describe('Scope', () => {
     test('scope level should have priority over event level', () => {
       expect.assertions(1);
       const scope = new Scope();
-      scope.setLevel(Severity.Warning);
+      scope.setLevel('warning');
       const event: Event = {};
-      event.level = Severity.Critical;
+      event.level = 'critical';
       return scope.applyToEvent(event).then(processedEvent => {
-        expect(processedEvent!.level).toEqual(Severity.Warning);
+        expect(processedEvent!.level).toEqual('warning');
       });
     });
 
@@ -410,7 +410,7 @@ describe('Scope', () => {
       scope.setContext('foo', { id: '1' });
       scope.setContext('bar', { id: '2' });
       scope.setUser({ id: '1337' });
-      scope.setLevel(Severity.Info);
+      scope.setLevel('info');
       scope.setFingerprint(['foo']);
       scope.setRequestSession({ status: 'ok' });
     });
@@ -458,7 +458,7 @@ describe('Scope', () => {
       localScope.setContext('bar', { id: '3' });
       localScope.setContext('baz', { id: '4' });
       localScope.setUser({ id: '42' });
-      localScope.setLevel(Severity.Warning);
+      localScope.setLevel('warning');
       localScope.setFingerprint(['bar']);
       (localScope as any)._requestSession = { status: 'ok' };
 

packages/integrations/src/captureconsole.ts

@@ -1,5 +1,5 @@
 import { EventProcessor, Hub, Integration } from '@sentry/types';
-import { CONSOLE_LEVELS, fill, getGlobalObject, safeJoin, severityFromString } from '@sentry/utils';
+import { CONSOLE_LEVELS, fill, getGlobalObject, safeJoin, severityLevelFromString } from '@sentry/utils';
 
 const global = getGlobalObject<Window | NodeJS.Global>();
 
@@ -48,7 +48,7 @@ export class CaptureConsole implements Integration {
 
         if (hub.getIntegration(CaptureConsole)) {
           hub.withScope(scope => {
-            scope.setLevel(severityFromString(level));
+            scope.setLevel(severityLevelFromString(level));
             scope.setExtra('arguments', args);
             scope.addEventProcessor(event => {
               event.logger = 'console';

packages/minimal/src/index.ts

@@ -8,6 +8,7 @@ import {
   Extras,
   Primitive,
   Severity,
+  SeverityLevel,
   Transaction,
   TransactionContext,
   User,
@@ -52,7 +53,11 @@ export function captureException(exception: any, captureContext?: CaptureContext
  * @param Severity Define the level of the message.
  * @returns The generated eventId.
  */
-export function captureMessage(message: string, captureContext?: CaptureContext | Severity): string {
+export function captureMessage(
+  message: string,
+  // eslint-disable-next-line deprecation/deprecation
+  captureContext?: CaptureContext | Severity | SeverityLevel,
+): string {
   const syntheticException = new Error(message);
 
   // This is necessary to provide explicit scopes upgrade, without changing the original

packages/minimal/test/lib/minimal.test.ts

@@ -1,5 +1,4 @@
 import { getCurrentHub, getHubFromCarrier, Scope } from '@sentry/hub';
-import { Severity } from '@sentry/types';
 
 import {
   _callOnClient,
@@ -165,8 +164,8 @@ describe('Minimal', () => {
       const client: any = new TestClient({});
       const scope = getCurrentHub().pushScope();
       getCurrentHub().bindClient(client);
-      scope.setLevel(Severity.Warning);
-      expect(global.__SENTRY__.hub._stack[1].scope._level).toEqual(Severity.Warning);
+      scope.setLevel('warning');
+      expect(global.__SENTRY__.hub._stack[1].scope._level).toEqual('warning');
     });
   });
 
@@ -245,16 +244,16 @@ describe('Minimal', () => {
 
   test('withScope', () => {
     withScope(scope => {
-      scope.setLevel(Severity.Warning);
+      scope.setLevel('warning');
       scope.setFingerprint(['1']);
       withScope(scope2 => {
-        scope2.setLevel(Severity.Info);
+        scope2.setLevel('info');
         scope2.setFingerprint(['2']);
         withScope(scope3 => {
           scope3.clear();
-          expect(global.__SENTRY__.hub._stack[1].scope._level).toEqual(Severity.Warning);
+          expect(global.__SENTRY__.hub._stack[1].scope._level).toEqual('warning');
           expect(global.__SENTRY__.hub._stack[1].scope._fingerprint).toEqual(['1']);
-          expect(global.__SENTRY__.hub._stack[2].scope._level).toEqual(Severity.Info);
+          expect(global.__SENTRY__.hub._stack[2].scope._level).toEqual('info');
           expect(global.__SENTRY__.hub._stack[2].scope._fingerprint).toEqual(['2']);
           expect(global.__SENTRY__.hub._stack[3].scope._level).toBeUndefined();
         });

packages/node-integration-tests/suites/public-api/addBreadcrumb/multiple_breadcrumbs/scenario.ts

@@ -8,7 +8,7 @@ Sentry.init({
 Sentry.addBreadcrumb({
   category: 'foo',
   message: 'bar',
-  level: Sentry.Severity.Critical,
+  level: 'critical',
 });
 
 Sentry.addBreadcrumb({

packages/node-integration-tests/suites/public-api/addBreadcrumb/simple_breadcrumb/scenario.ts

@@ -8,7 +8,7 @@ Sentry.init({
 Sentry.addBreadcrumb({
   category: 'foo',
   message: 'bar',
-  level: Sentry.Severity.Critical,
+  level: 'critical',
 });
 
 Sentry.captureMessage('test_simple');