ref(nextjs): Rename wrapper functions (#6788)

Author: lforst

packages/nextjs/src/config/templates/apiWrapperTemplate.ts

@@ -54,7 +54,7 @@ export const config = {
   },
 };
 
-export default userProvidedHandler ? Sentry.withSentryAPI(userProvidedHandler, '__ROUTE__') : undefined;
+export default userProvidedHandler ? Sentry.wrapApiHandlerWithSentry(userProvidedHandler, '__ROUTE__') : undefined;
 
 // Re-export anything exported by the page module we're wrapping. When processing this code, Rollup is smart enough to
 // not include anything whose name matchs something we've explicitly exported above.

packages/nextjs/src/config/templates/middlewareWrapperTemplate.ts

@@ -40,8 +40,10 @@ if ('middleware' in userApiModule && typeof userApiModule.middleware === 'functi
   userProvidedDefaultHandler = userApiModule;
 }
 
-export const middleware = userProvidedNamedHandler ? Sentry.withSentryMiddleware(userProvidedNamedHandler) : undefined;
-export default userProvidedDefaultHandler ? Sentry.withSentryMiddleware(userProvidedDefaultHandler) : undefined;
+export const middleware = userProvidedNamedHandler
+  ? Sentry.wrapMiddlewareWithSentry(userProvidedNamedHandler)
+  : undefined;
+export default userProvidedDefaultHandler ? Sentry.wrapMiddlewareWithSentry(userProvidedDefaultHandler) : undefined;
 
 // Re-export anything exported by the page module we're wrapping. When processing this code, Rollup is smart enough to
 // not include anything whose name matchs something we've explicitly exported above.

packages/nextjs/src/config/templates/pageWrapperTemplate.ts

@@ -28,24 +28,24 @@ const origGetStaticProps = userPageModule.getStaticProps;
 const origGetServerSideProps = userPageModule.getServerSideProps;
 
 const getInitialPropsWrappers: Record<string, any> = {
-  '/_app': Sentry.withSentryServerSideAppGetInitialProps,
-  '/_document': Sentry.withSentryServerSideDocumentGetInitialProps,
-  '/_error': Sentry.withSentryServerSideErrorGetInitialProps,
+  '/_app': Sentry.wrapAppGetInitialPropsWithSentry,
+  '/_document': Sentry.wrapDocumentGetInitialPropsWithSentry,
+  '/_error': Sentry.wrapErrorGetInitialPropsWithSentry,
 };
 
-const getInitialPropsWrapper = getInitialPropsWrappers['__ROUTE__'] || Sentry.withSentryServerSideGetInitialProps;
+const getInitialPropsWrapper = getInitialPropsWrappers['__ROUTE__'] || Sentry.wrapGetInitialPropsWithSentry;
 
 if (typeof origGetInitialProps === 'function') {
   pageComponent.getInitialProps = getInitialPropsWrapper(origGetInitialProps) as NextPageComponent['getInitialProps'];
 }
 
 export const getStaticProps =
   typeof origGetStaticProps === 'function'
-    ? Sentry.withSentryGetStaticProps(origGetStaticProps, '__ROUTE__')
+    ? Sentry.wrapGetStaticPropsWithSentry(origGetStaticProps, '__ROUTE__')
     : undefined;
 export const getServerSideProps =
   typeof origGetServerSideProps === 'function'
-    ? Sentry.withSentryGetServerSideProps(origGetServerSideProps, '__ROUTE__')
+    ? Sentry.wrapGetServerSidePropsWithSentry(origGetServerSideProps, '__ROUTE__')
     : undefined;
 
 export default pageComponent;

packages/nextjs/src/edge/index.ts

@@ -131,5 +131,11 @@ export function lastEventId(): string | undefined {
 export { flush } from './utils/flush';
 
 export * from '@sentry/core';
-export { withSentryAPI } from './withSentryAPI';
-export { withSentryMiddleware } from './withSentryMiddleware';
+
+export {
+  // eslint-disable-next-line deprecation/deprecation
+  withSentryAPI,
+  wrapApiHandlerWithSentry,
+} from './wrapApiHandlerWithSentry';
+
+export { wrapMiddlewareWithSentry } from './wrapMiddlewareWithSentry';

packages/nextjs/src/edge/withSentryAPI.ts renamed to packages/nextjs/src/edge/wrapApiHandlerWithSentry.ts

@@ -6,7 +6,7 @@ import { withEdgeWrapping } from './utils/edgeWrapperUtils';
 /**
  * Wraps a Next.js edge route handler with Sentry error and performance instrumentation.
  */
-export function withSentryAPI<H extends EdgeRouteHandler>(
+export function wrapApiHandlerWithSentry<H extends EdgeRouteHandler>(
   handler: H,
   parameterizedRoute: string,
 ): (...params: Parameters<H>) => Promise<ReturnType<H>> {
@@ -21,9 +21,14 @@ export function withSentryAPI<H extends EdgeRouteHandler>(
           ? `handler (${parameterizedRoute})`
           : `${req.method} ${parameterizedRoute}`,
       spanOp: activeSpan ? 'function' : 'http.server',
-      mechanismFunctionName: 'withSentryAPI',
+      mechanismFunctionName: 'wrapApiHandlerWithSentry',
     });
 
     return await wrappedHandler.apply(this, args);
   };
 }
+
+/**
+ * @deprecated Use `wrapApiHandlerWithSentry` instead.
+ */
+export const withSentryAPI = wrapApiHandlerWithSentry;

packages/nextjs/src/edge/withSentryMiddleware.ts renamed to packages/nextjs/src/edge/wrapMiddlewareWithSentry.ts

@@ -3,8 +3,11 @@ import { withEdgeWrapping } from './utils/edgeWrapperUtils';
 
 /**
  * Wraps Next.js middleware with Sentry error and performance instrumentation.
+ *
+ * @param middleware The middleware handler.
+ * @returns a wrapped middleware handler.
  */
-export function withSentryMiddleware<H extends EdgeRouteHandler>(
+export function wrapMiddlewareWithSentry<H extends EdgeRouteHandler>(
   middleware: H,
 ): (...params: Parameters<H>) => Promise<ReturnType<H>> {
   return withEdgeWrapping(middleware, {

packages/nextjs/src/index.types.ts

@@ -30,9 +30,26 @@ export declare function flush(timeout?: number | undefined): PromiseLike<boolean
 export declare function lastEventId(): string | undefined;
 export declare function getSentryRelease(fallback?: string): string | undefined;
 
+/**
+ * @deprecated Use `wrapApiHandlerWithSentry` instead
+ */
 export declare function withSentryAPI<APIHandler extends (...args: any[]) => any>(
   handler: APIHandler,
   parameterizedRoute: string,
 ): (
   ...args: Parameters<APIHandler>
 ) => ReturnType<APIHandler> extends Promise<unknown> ? ReturnType<APIHandler> : Promise<ReturnType<APIHandler>>;
+
+/**
+ * Wraps a Next.js API handler with Sentry error and performance instrumentation.
+ *
+ * @param handler The handler exported from the API route file.
+ * @param parameterizedRoute The page's parameterized route.
+ * @returns The wrapped handler.
+ */
+export declare function wrapApiHandlerWithSentry<APIHandler extends (...args: any[]) => any>(
+  handler: APIHandler,
+  parameterizedRoute: string,
+): (
+  ...args: Parameters<APIHandler>
+) => ReturnType<APIHandler> extends Promise<unknown> ? ReturnType<APIHandler> : Promise<ReturnType<APIHandler>>;

packages/nextjs/src/server/index.ts

@@ -148,10 +148,44 @@ const deprecatedIsBuild = (): boolean => isBuild();
 // eslint-disable-next-line deprecation/deprecation
 export { deprecatedIsBuild as isBuild };
 
-export { withSentryGetStaticProps } from './withSentryGetStaticProps';
-export { withSentryServerSideGetInitialProps } from './withSentryServerSideGetInitialProps';
-export { withSentryServerSideAppGetInitialProps } from './withSentryServerSideAppGetInitialProps';
-export { withSentryServerSideDocumentGetInitialProps } from './withSentryServerSideDocumentGetInitialProps';
-export { withSentryServerSideErrorGetInitialProps } from './withSentryServerSideErrorGetInitialProps';
-export { withSentryGetServerSideProps } from './withSentryGetServerSideProps';
-export { withSentry, withSentryAPI } from './withSentryAPI';
+export {
+  // eslint-disable-next-line deprecation/deprecation
+  withSentryGetStaticProps,
+  wrapGetStaticPropsWithSentry,
+} from './wrapGetStaticPropsWithSentry';
+
+export {
+  // eslint-disable-next-line deprecation/deprecation
+  withSentryServerSideGetInitialProps,
+  wrapGetInitialPropsWithSentry,
+} from './wrapGetInitialPropsWithSentry';
+
+export {
+  // eslint-disable-next-line deprecation/deprecation
+  withSentryServerSideAppGetInitialProps,
+  wrapAppGetInitialPropsWithSentry,
+} from './wrapAppGetInitialPropsWithSentry';
+export {
+  // eslint-disable-next-line deprecation/deprecation
+  withSentryServerSideDocumentGetInitialProps,
+  wrapDocumentGetInitialPropsWithSentry,
+} from './wrapDocumentGetInitialPropsWithSentry';
+export {
+  // eslint-disable-next-line deprecation/deprecation
+  withSentryServerSideErrorGetInitialProps,
+  wrapErrorGetInitialPropsWithSentry,
+} from './wrapErrorGetInitialPropsWithSentry';
+
+export {
+  // eslint-disable-next-line deprecation/deprecation
+  withSentryGetServerSideProps,
+  wrapGetServerSidePropsWithSentry,
+} from './wrapGetServerSidePropsWithSentry';
+
+export {
+  // eslint-disable-next-line deprecation/deprecation
+  withSentry,
+  // eslint-disable-next-line deprecation/deprecation
+  withSentryAPI,
+  wrapApiHandlerWithSentry,
+} from './wrapApiHandlerWithSentry';

packages/nextjs/src/server/withSentryAPI.ts renamed to packages/nextjs/src/server/wrapApiHandlerWithSentry.ts

@@ -25,7 +25,7 @@ import { autoEndTransactionOnResponseEnd, finishTransaction, flushQueue } from '
  * @param parameterizedRoute The page's route, passed in via the proxy loader
  * @returns The wrapped handler
  */
-export function withSentryAPI(
+export function wrapApiHandlerWithSentry(
   maybeWrappedHandler: NextApiHandler | WrappedNextApiHandler,
   parameterizedRoute: string,
 ): WrappedNextApiHandler {
@@ -47,20 +47,28 @@ export function withSentryAPI(
     );
   }
 
+  // eslint-disable-next-line deprecation/deprecation
   return withSentry(maybeWrappedHandler, parameterizedRoute);
 }
 
 /**
- * Legacy function for manually wrapping API route handlers, now used as the innards of `withSentryAPI`.
+ * @deprecated Use `wrapApiHandlerWithSentry()` instead
+ */
+export const withSentryAPI = wrapApiHandlerWithSentry;
+
+/**
+ * Legacy function for manually wrapping API route handlers, now used as the innards of `wrapApiHandlerWithSentry`.
  *
  * @param origHandler The user's original API route handler
  * @param parameterizedRoute The route whose handler is being wrapped. Meant for internal use only.
  * @returns A wrapped version of the handler
+ *
+ * @deprecated Use `wrapApiWithSentry()` instead
  */
 export function withSentry(origHandler: NextApiHandler, parameterizedRoute?: string): WrappedNextApiHandler {
   // eslint-disable-next-line @typescript-eslint/explicit-module-boundary-types
   return async function sentryWrappedHandler(req: AugmentedNextApiRequest, res: AugmentedNextApiResponse) {
-    // We're now auto-wrapping API route handlers using `withSentryAPI` (which uses `withSentry` under the hood), but
+    // We're now auto-wrapping API route handlers using `wrapApiHandlerWithSentry` (which uses `withSentry` under the hood), but
     // users still may have their routes manually wrapped with `withSentry`. This check makes `sentryWrappedHandler`
     // idempotent so that those cases don't break anything.
     if (req.__withSentry_applied__) {

packages/nextjs/src/server/withSentryServerSideAppGetInitialProps.ts renamed to packages/nextjs/src/server/wrapAppGetInitialPropsWithSentry.ts

@@ -19,7 +19,7 @@ type AppGetInitialProps = typeof App['getInitialProps'];
  * @param parameterizedRoute The page's parameterized route
  * @returns A wrapped version of the function
  */
-export function withSentryServerSideAppGetInitialProps(origAppGetInitialProps: AppGetInitialProps): AppGetInitialProps {
+export function wrapAppGetInitialPropsWithSentry(origAppGetInitialProps: AppGetInitialProps): AppGetInitialProps {
   return async function (this: unknown, ...args: Parameters<AppGetInitialProps>): ReturnType<AppGetInitialProps> {
     if (isBuild()) {
       return origAppGetInitialProps.apply(this, args);
@@ -72,3 +72,8 @@ export function withSentryServerSideAppGetInitialProps(origAppGetInitialProps: A
     }
   };
 }
+
+/**
+ * @deprecated Use `wrapAppGetInitialPropsWithSentry` instead.
+ */
+export const withSentryServerSideAppGetInitialProps = wrapAppGetInitialPropsWithSentry;

packages/nextjs/src/server/withSentryServerSideDocumentGetInitialProps.ts renamed to packages/nextjs/src/server/wrapDocumentGetInitialPropsWithSentry.ts

@@ -14,7 +14,7 @@ type DocumentGetInitialProps = typeof Document.getInitialProps;
  * @param parameterizedRoute The page's parameterized route
  * @returns A wrapped version of the function
  */
-export function withSentryServerSideDocumentGetInitialProps(
+export function wrapDocumentGetInitialPropsWithSentry(
   origDocumentGetInitialProps: DocumentGetInitialProps,
 ): DocumentGetInitialProps {
   return async function (
@@ -47,3 +47,8 @@ export function withSentryServerSideDocumentGetInitialProps(
     }
   };
 }
+
+/**
+ * @deprecated Use `wrapDocumentGetInitialPropsWithSentry` instead.
+ */
+export const withSentryServerSideDocumentGetInitialProps = wrapDocumentGetInitialPropsWithSentry;

packages/nextjs/src/server/withSentryServerSideErrorGetInitialProps.ts renamed to packages/nextjs/src/server/wrapErrorGetInitialPropsWithSentry.ts

@@ -20,7 +20,7 @@ type ErrorGetInitialProps = (context: NextPageContext) => Promise<ErrorProps>;
  * @param parameterizedRoute The page's parameterized route
  * @returns A wrapped version of the function
  */
-export function withSentryServerSideErrorGetInitialProps(
+export function wrapErrorGetInitialPropsWithSentry(
   origErrorGetInitialProps: ErrorGetInitialProps,
 ): ErrorGetInitialProps {
   return async function (this: unknown, ...args: Parameters<ErrorGetInitialProps>): ReturnType<ErrorGetInitialProps> {
@@ -63,3 +63,8 @@ export function withSentryServerSideErrorGetInitialProps(
     }
   };
 }
+
+/**
+ * @deprecated Use `wrapErrorGetInitialPropsWithSentry` instead.
+ */
+export const withSentryServerSideErrorGetInitialProps = wrapErrorGetInitialPropsWithSentry;

packages/nextjs/src/server/withSentryServerSideGetInitialProps.ts renamed to packages/nextjs/src/server/wrapGetInitialPropsWithSentry.ts

@@ -18,7 +18,7 @@ type GetInitialProps = Required<NextPage>['getInitialProps'];
  * @param parameterizedRoute The page's parameterized route
  * @returns A wrapped version of the function
  */
-export function withSentryServerSideGetInitialProps(origGetInitialProps: GetInitialProps): GetInitialProps {
+export function wrapGetInitialPropsWithSentry(origGetInitialProps: GetInitialProps): GetInitialProps {
   return async function (this: unknown, ...args: Parameters<GetInitialProps>): Promise<ReturnType<GetInitialProps>> {
     if (isBuild()) {
       return origGetInitialProps.apply(this, args);
@@ -59,3 +59,8 @@ export function withSentryServerSideGetInitialProps(origGetInitialProps: GetInit
     }
   };
 }
+
+/**
+ * @deprecated Use `wrapGetInitialPropsWithSentry` instead.
+ */
+export const withSentryServerSideGetInitialProps = wrapGetInitialPropsWithSentry;

packages/nextjs/src/server/withSentryGetServerSideProps.ts renamed to packages/nextjs/src/server/wrapGetServerSidePropsWithSentry.ts

@@ -16,7 +16,7 @@ import {
  * @param parameterizedRoute The page's parameterized route
  * @returns A wrapped version of the function
  */
-export function withSentryGetServerSideProps(
+export function wrapGetServerSidePropsWithSentry(
   origGetServerSideProps: GetServerSideProps,
   parameterizedRoute: string,
 ): GetServerSideProps {
@@ -57,3 +57,8 @@ export function withSentryGetServerSideProps(
     }
   };
 }
+
+/**
+ * @deprecated Use `withSentryGetServerSideProps` instead.
+ */
+export const withSentryGetServerSideProps = wrapGetServerSidePropsWithSentry;

packages/nextjs/src/server/withSentryGetStaticProps.ts renamed to packages/nextjs/src/server/wrapGetStaticPropsWithSentry.ts

@@ -12,7 +12,7 @@ type Props = { [key: string]: unknown };
  * @param parameterizedRoute The page's parameterized route
  * @returns A wrapped version of the function
  */
-export function withSentryGetStaticProps(
+export function wrapGetStaticPropsWithSentry(
   origGetStaticProps: GetStaticProps<Props>,
   parameterizedRoute: string,
 ): GetStaticProps<Props> {
@@ -31,3 +31,8 @@ export function withSentryGetStaticProps(
     });
   };
 }
+
+/**
+ * @deprecated Use `wrapGetStaticPropsWithSentry` instead.
+ */
+export const withSentryGetStaticProps = wrapGetStaticPropsWithSentry;

packages/nextjs/test/config/withSentry.test.ts

@@ -45,6 +45,7 @@ describe('withSentry', () => {
     res.send('Good dog, Maisey!');
   };
 
+  // eslint-disable-next-line deprecation/deprecation
   const wrappedHandlerNoError = withSentry(origHandlerNoError);
 
   beforeEach(() => {

packages/nextjs/test/config/wrappers.test.ts

@@ -2,7 +2,7 @@ import * as SentryCore from '@sentry/core';
 import * as SentryTracing from '@sentry/tracing';
 import type { IncomingMessage, ServerResponse } from 'http';
 
-import { withSentryGetServerSideProps, withSentryServerSideGetInitialProps } from '../../src/server';
+import { wrapGetInitialPropsWithSentry, wrapGetServerSidePropsWithSentry } from '../../src/server';
 
 const startTransactionSpy = jest.spyOn(SentryCore, 'startTransaction');
 
@@ -23,10 +23,10 @@ describe('data-fetching function wrappers', () => {
       jest.clearAllMocks();
     });
 
-    test('withSentryGetServerSideProps', async () => {
+    test('wrapGetServerSidePropsWithSentry', async () => {
       const origFunction = jest.fn(async () => ({ props: {} }));
 
-      const wrappedOriginal = withSentryGetServerSideProps(origFunction, route);
+      const wrappedOriginal = wrapGetServerSidePropsWithSentry(origFunction, route);
       await wrappedOriginal({ req, res } as any);
 
       expect(startTransactionSpy).toHaveBeenCalledWith(
@@ -43,10 +43,10 @@ describe('data-fetching function wrappers', () => {
       );
     });
 
-    test('withSentryServerSideGetInitialProps', async () => {
+    test('wrapGetInitialPropsWithSentry', async () => {
       const origFunction = jest.fn(async () => ({}));
 
-      const wrappedOriginal = withSentryServerSideGetInitialProps(origFunction);
+      const wrappedOriginal = wrapGetInitialPropsWithSentry(origFunction);
       await wrappedOriginal({ req, res, pathname: route } as any);
 
       expect(startTransactionSpy).toHaveBeenCalledWith(