chore(event-handler): expose rest handler functionality (#4458)

Author: svozza

packages/event-handler/package.json

@@ -67,6 +67,16 @@
         "types": "./lib/esm/types/index.d.ts",
         "default": "./lib/esm/types/index.js"
       }
+    },
+    "./experimental-rest": {
+      "require": {
+        "types": "./lib/cjs/rest/index.d.ts",
+        "default": "./lib/cjs/rest/index.js"
+      },
+      "import": {
+        "types": "./lib/esm/rest/index.d.ts",
+        "default": "./lib/esm/rest/index.js"
+      }
     }
   },
   "typesVersions": {
@@ -86,6 +96,10 @@
       "types": [
         "./lib/cjs/types/index.d.ts",
         "./lib/esm/types/index.d.ts"
+      ],
+      "experimental-rest": [
+        "./lib/cjs/rest/index.d.ts",
+        "./lib/esm/rest/index.d.ts"
       ]
     }
   },

packages/event-handler/src/rest/RouteHandlerRegistry.ts

@@ -3,7 +3,7 @@ import type {
   DynamicRoute,
   HttpMethod,
   Path,
-  RouteHandlerOptions,
+  RestRouteHandlerOptions,
   RouteRegistryOptions,
   ValidationResult,
 } from '../types/rest.js';
@@ -147,7 +147,10 @@ class RouteHandlerRegistry {
    * @param path - The path to match
    * @returns Route handler options or null if no match found
    */
-  public resolve(method: HttpMethod, path: Path): RouteHandlerOptions | null {
+  public resolve(
+    method: HttpMethod,
+    path: Path
+  ): RestRouteHandlerOptions | null {
     if (this.#shouldSort) {
       this.#dynamicRoutes.sort(this.#compareRouteSpecificity);
       this.#shouldSort = false;

packages/event-handler/src/rest/Router.ts

@@ -13,16 +13,16 @@ import type {
   Middleware,
   Path,
   RequestContext,
+  RestRouteOptions,
+  RestRouterOptions,
   RouteHandler,
-  RouteOptions,
-  RouterOptions,
 } from '../types/rest.js';
 import { HttpErrorCodes, HttpVerbs } from './constants.js';
 import {
   handlerResultToProxyResult,
-  handlerResultToResponse,
+  handlerResultToWebResponse,
   proxyEventToWebRequest,
-  responseToProxyResult,
+  webResponseToProxyResult,
 } from './converters.js';
 import { ErrorHandlerRegistry } from './ErrorHandlerRegistry.js';
 import {
@@ -57,7 +57,7 @@ class Router {
    */
   protected readonly isDev: boolean = false;
 
-  public constructor(options?: RouterOptions) {
+  public constructor(options?: RestRouterOptions) {
     this.context = {};
     const alcLogLevel = getStringFromEnv({
       key: 'AWS_LAMBDA_LOG_LEVEL',
@@ -236,7 +236,7 @@ class Router {
 
       const handlerMiddleware: Middleware = async (params, options, next) => {
         const handlerResult = await handler(params, options);
-        options.res = handlerResultToResponse(
+        options.res = handlerResultToWebResponse(
           handlerResult,
           options.res.headers
         );
@@ -266,11 +266,11 @@ class Router {
         ...handlerOptions,
         scope: options?.scope,
       });
-      return await responseToProxyResult(result);
+      return await webResponseToProxyResult(result);
     }
   }
 
-  public route(handler: RouteHandler, options: RouteOptions): void {
+  public route(handler: RouteHandler, options: RestRouteOptions): void {
     const { method, path, middleware = [] } = options;
     const methods = Array.isArray(method) ? method : [method];
 

packages/event-handler/src/rest/converters.ts

@@ -74,7 +74,7 @@ export const proxyEventToWebRequest = (
  * @param response - The Web API Response object
  * @returns An API Gateway proxy result
  */
-export const responseToProxyResult = async (
+export const webResponseToProxyResult = async (
   response: Response
 ): Promise<APIGatewayProxyResult> => {
   const headers: Record<string, string> = {};
@@ -111,7 +111,7 @@ export const responseToProxyResult = async (
  * @param headers - Optional headers to be included in the response
  * @returns A Web API Response object
  */
-export const handlerResultToResponse = (
+export const handlerResultToWebResponse = (
   response: HandlerResponse,
   resHeaders?: Headers
 ): Response => {
@@ -159,7 +159,7 @@ export const handlerResultToProxyResult = async (
     return response;
   }
   if (response instanceof Response) {
-    return await responseToProxyResult(response);
+    return await webResponseToProxyResult(response);
   }
   return {
     statusCode: 200,

packages/event-handler/src/rest/index.ts

@@ -0,0 +1,28 @@
+export { HttpErrorCodes, HttpVerbs } from './constants.js';
+export {
+  handlerResultToProxyResult,
+  handlerResultToWebResponse,
+  proxyEventToWebRequest,
+  webResponseToProxyResult,
+} from './converters.js';
+export {
+  BadRequestError,
+  ForbiddenError,
+  InternalServerError,
+  MethodNotAllowedError,
+  NotFoundError,
+  ParameterValidationError,
+  RequestEntityTooLargeError,
+  RequestTimeoutError,
+  RouteMatchingError,
+  ServiceError,
+  ServiceUnavailableError,
+  UnauthorizedError,
+} from './errors.js';
+export { Router } from './Router.js';
+export {
+  composeMiddleware,
+  isAPIGatewayProxyEvent,
+  isAPIGatewayProxyResult,
+  isHttpMethod,
+} from './utils.js';

packages/event-handler/src/types/index.ts

@@ -30,3 +30,19 @@ export type {
   Anything,
   ResolveOptions,
 } from './common.js';
+
+export type {
+  ErrorHandler,
+  ErrorResolveOptions,
+  ErrorResponse,
+  HandlerResponse,
+  HttpMethod,
+  HttpStatusCode,
+  Middleware,
+  Path,
+  RequestContext,
+  RestRouteHandlerOptions,
+  RestRouteOptions,
+  RestRouterOptions,
+  RouteHandler,
+} from './rest.js';

packages/event-handler/src/types/rest.ts

@@ -36,7 +36,7 @@ interface ErrorConstructor<T extends Error = Error> {
 /**
  * Options for the {@link Router} class
  */
-type RouterOptions = {
+type RestRouterOptions = {
   /**
    * A logger instance to be used for logging debug, warning, and error messages.
    *
@@ -67,14 +67,14 @@ type HttpStatusCode = (typeof HttpErrorCodes)[keyof typeof HttpErrorCodes];
 
 type Path = `/${string}`;
 
-type RouteHandlerOptions = {
+type RestRouteHandlerOptions = {
   handler: RouteHandler;
   params: Record<string, string>;
   rawParams: Record<string, string>;
   middleware: Middleware[];
 };
 
-type RouteOptions = {
+type RestRouteOptions = {
   method: HttpMethod | HttpMethod[];
   path: Path;
   middleware?: Middleware[];
@@ -125,10 +125,10 @@ export type {
   Middleware,
   Path,
   RequestContext,
-  RouterOptions,
+  RestRouterOptions,
   RouteHandler,
-  RouteOptions,
-  RouteHandlerOptions,
+  RestRouteOptions,
+  RestRouteHandlerOptions,
   RouteRegistryOptions,
   ValidationResult,
 };

packages/event-handler/tests/unit/rest/ErrorHandlerRegistry.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, it } from 'vitest';
-import { HttpErrorCodes } from '../../../src/rest/constants.js';
 import { ErrorHandlerRegistry } from '../../../src/rest/ErrorHandlerRegistry.js';
+import { HttpErrorCodes } from '../../../src/rest/index.js';
 import type {
   HttpStatusCode,
   RequestContext,

packages/event-handler/tests/unit/rest/RouteHandlerRegistry.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest';
-import { HttpVerbs } from '../../../src/rest/constants.js';
+import { HttpVerbs } from '../../../src/rest/index.js';
 import { Route } from '../../../src/rest/Route.js';
 import { RouteHandlerRegistry } from '../../../src/rest/RouteHandlerRegistry.js';
 import type { Path } from '../../../src/types/rest.js';

packages/event-handler/tests/unit/rest/Router/basic-routing.test.ts

@@ -1,8 +1,11 @@
 import context from '@aws-lambda-powertools/testing-utils/context';
 import { describe, expect, it } from 'vitest';
-import { HttpErrorCodes, HttpVerbs } from '../../../../src/rest/constants.js';
-import { InternalServerError } from '../../../../src/rest/errors.js';
-import { Router } from '../../../../src/rest/Router.js';
+import {
+  HttpErrorCodes,
+  HttpVerbs,
+  InternalServerError,
+  Router,
+} from '../../../../src/rest/index.js';
 import type { HttpMethod, RouteHandler } from '../../../../src/types/rest.js';
 import { createTestEvent } from '../helpers.js';