feat(nestjs): Deprecate @WithSentry in favor of @SentryExceptionCaptured

CHANGELOG.md

@@ -8,6 +8,10 @@
 
 ## Unreleased
 
+### Deprecated `@WithSentry` in `@sentry/nestjs`
+
+The `@WithSentry` decorator was deprecated. Use `@SentryExceptionCaptured` instead. This is a simple renaming and functionality stays identical.
+
 - "You miss 100 percent of the chances you don't take. — Wayne Gretzky" — Michael Scott
 
 ## 8.38.0

dev-packages/e2e-tests/test-applications/nestjs-with-submodules-decorator/src/example-global.filter.ts

@@ -1,10 +1,10 @@
 import { ArgumentsHost, BadRequestException, Catch, ExceptionFilter } from '@nestjs/common';
-import { WithSentry } from '@sentry/nestjs';
+import { SentryExceptionCaptured } from '@sentry/nestjs';
 import { Request, Response } from 'express';
 
 @Catch()
 export class ExampleWrappedGlobalFilter implements ExceptionFilter {
-  @WithSentry()
+  @SentryExceptionCaptured()
   catch(exception: BadRequestException, host: ArgumentsHost): void {
     const ctx = host.switchToHttp();
     const response = ctx.getResponse<Response>();

docs/migration/draft-v9-migration-guide.md

@@ -11,3 +11,7 @@
 ## `@sentry/core`
 
 - Deprecated `transactionNamingScheme` option in `requestDataIntegration`.
+
+## `@sentry/nestjs`
+
+- Deprecated `@WithSentry`. Use `@SentryExceptionCaptured` instead.

packages/nestjs/README.md

@@ -72,16 +72,16 @@ export class AppModule {}
 
 In case you are using a global catch-all exception filter (which is either a filter registered with
 `app.useGlobalFilters()` or a filter registered in your app module providers annotated with an empty `@Catch()`
-decorator), add a `@WithSentry()` decorator to the `catch()` method of this global error filter. This decorator will
-report all unexpected errors that are received by your global error filter to Sentry:
+decorator), add a `@SentryExceptionCaptured()` decorator to the `catch()` method of this global error filter. This
+decorator will report all unexpected errors that are received by your global error filter to Sentry:
 
 ```typescript
 import { Catch, ExceptionFilter } from '@nestjs/common';
 import { WithSentry } from '@sentry/nestjs';
 
 @Catch()
 export class YourCatchAllExceptionFilter implements ExceptionFilter {
-  @WithSentry()
+  @SentryExceptionCaptured()
   catch(exception, host): void {
     // your implementation here
   }

packages/nestjs/src/decorators.ts

@@ -0,0 +1,89 @@
+import { captureException } from '@sentry/core';
+import * as Sentry from '@sentry/node';
+import { startSpan } from '@sentry/node';
+import type { MonitorConfig } from '@sentry/types';
+import { isExpectedError } from './helpers';
+
+/**
+ * A decorator wrapping the native nest Cron decorator, sending check-ins to Sentry.
+ */
+export const SentryCron = (monitorSlug: string, monitorConfig?: MonitorConfig): MethodDecorator => {
+  return (target: unknown, propertyKey, descriptor: PropertyDescriptor) => {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const originalMethod = descriptor.value as (...args: any[]) => Promise<any>;
+
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    descriptor.value = function (...args: any[]) {
+      return Sentry.withMonitor(
+        monitorSlug,
+        () => {
+          return originalMethod.apply(this, args);
+        },
+        monitorConfig,
+      );
+    };
+    return descriptor;
+  };
+};
+
+/**
+ * A decorator usable to wrap arbitrary functions with spans.
+ */
+export function SentryTraced(op: string = 'function') {
+  return function (target: unknown, propertyKey: string, descriptor: PropertyDescriptor) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const originalMethod = descriptor.value as (...args: any[]) => Promise<any> | any; // function can be sync or async
+
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    descriptor.value = function (...args: any[]) {
+      return startSpan(
+        {
+          op: op,
+          name: propertyKey,
+        },
+        () => {
+          return originalMethod.apply(this, args);
+        },
+      );
+    };
+
+    // preserve the original name on the decorated function
+    Object.defineProperty(descriptor.value, 'name', {
+      value: originalMethod.name,
+      configurable: true,
+      enumerable: true,
+      writable: true,
+    });
+
+    return descriptor;
+  };
+}
+
+/**
+ * A decorator to wrap user-defined exception filters and add Sentry error reporting.
+ */
+export function SentryExceptionCaptured() {
+  return function (target: unknown, propertyKey: string, descriptor: PropertyDescriptor) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const originalCatch = descriptor.value as (exception: unknown, host: unknown, ...args: any[]) => void;
+
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    descriptor.value = function (exception: unknown, host: unknown, ...args: any[]) {
+      if (isExpectedError(exception)) {
+        return originalCatch.apply(this, [exception, host, ...args]);
+      }
+
+      captureException(exception);
+      return originalCatch.apply(this, [exception, host, ...args]);
+    };
+
+    return descriptor;
+  };
+}
+
+/**
+ * A decorator to wrap user-defined exception filters and add Sentry error reporting.
+ *
+ * @deprecated This decorator was renamed and will be removed in a future major version. Use `SentryExceptionCaptured` instead.
+ */
+export const WithSentry = SentryExceptionCaptured;

packages/nestjs/src/index.ts

@@ -2,6 +2,10 @@ export * from '@sentry/node';
 
 export { init } from './sdk';
 
-export { SentryTraced } from './decorators/sentry-traced';
-export { SentryCron } from './decorators/sentry-cron';
-export { WithSentry } from './decorators/with-sentry';
+export {
+  SentryTraced,
+  SentryCron,
+  // eslint-disable-next-line deprecation/deprecation
+  WithSentry,
+  SentryExceptionCaptured,
+} from './decorators';