docs(event-handler): add http router decorator examples (#4950)

Co-authored-by: Stefano Vozza <[email protected]>

Author: matthew2564

docs/features/event-handler/http.md

@@ -167,6 +167,19 @@ If you need to accept multiple HTTP methods in a single function, or support an
 !!! tip
     We recommend defining separate route handlers for each HTTP method within your Lambda function, as the functionality typically differs between operations such as `GET`, `POST`, `PUT`, `DELETE` etc
 
+#### Using decorators
+
+If you prefer to use the decorator syntax, you can use the same methods on a class method to register your route handlers. Learn more about how Powertools for TypeScript supports [decorators](../../getting-started/usage-patterns.md).
+
+=== "Decorator syntax"
+
+    ```ts hl_lines="10 21 32"
+    --8<-- "examples/snippets/event-handler/http/gettingStarted_decorators_basic.ts"
+    ```
+
+    !!! tip
+        We recommend passing a reference to `this` to ensure the correct class scope is propagated to the route handler functions.
+
 ### Data validation
 
 !!! note "Coming soon"
@@ -195,6 +208,12 @@ Error handlers receive the error object and the request context as arguments, an
     --8<-- "examples/snippets/event-handler/http/gettingStarted_error_handling.ts:4"
     ```
 
+=== "Using decorators"
+
+    ```ts hl_lines="16"
+    --8<-- "examples/snippets/event-handler/http/gettingStarted_error_handling_decorators.ts"
+    ```
+
 ### Built-in Error Handlers
 
 We provide built-in error handlers for common routing errors so you don't have to specify the Error type explicitly.
@@ -209,6 +228,12 @@ By default, we return a `404 Not Found` response for unmatched routes.
     --8<-- "examples/snippets/event-handler/http/gettingStarted_built_in_error_handler.ts"
     ```
 
+=== "Using decorators"
+
+    ```ts hl_lines="15 31"
+    --8<-- "examples/snippets/event-handler/http/gettingStarted_built_in_error_handler_decorators.ts"
+    ```
+
 ### Throwing HTTP errors
 
 You can throw HTTP errors in your route handlers to stop execution and return specific HTTP status codes and messages. Event Handler provides a set of built-in HTTP error classes that you can use to throw common HTTP errors.
@@ -295,14 +320,20 @@ executes last in post-processing wins.
 
 You can use `app.use()` to register middleware that should always run regardless of the route
 and you can apply middleware to specific routes by passing them as arguments before the route
-handler.
+handler or as a second argument to the route decorator.
 
 === "index.ts"
 
     ```ts hl_lines="9-14 16-21 31"
     --8<-- "examples/snippets/event-handler/http/advanced_mw_middleware_order.ts:3"
     ```
 
+=== "Using decorators"
+
+    ```ts hl_lines="18-22 34"
+    --8<-- "examples/snippets/event-handler/http/advanced_mw_middleware_order_decorators.ts:3"
+    ```
+
 === "Response"
 
     ```json hl_lines="6-7"

examples/snippets/event-handler/http/advanced_mw_middleware_order_decorators.ts

@@ -0,0 +1,50 @@
+declare function getAllTodos(): Promise<{ id: string; title: string }[]>;
+declare function putTodo<T>(todo: unknown): Promise<{ id: string } & T>;
+
+import type { LambdaInterface } from '@aws-lambda-powertools/commons/types';
+import { Router } from '@aws-lambda-powertools/event-handler/http';
+import type { Middleware } from '@aws-lambda-powertools/event-handler/types';
+import { Logger } from '@aws-lambda-powertools/logger';
+import type { Context } from 'aws-lambda';
+
+const logger = new Logger();
+const app = new Router({ logger });
+
+// Global middleware - executes first in pre-processing, last in post-processing
+app.use(async ({ reqCtx, next }) => {
+  reqCtx.res.headers.set('x-pre-processed-by', 'global-middleware');
+  await next();
+  reqCtx.res.headers.set('x-post-processed-by', 'global-middleware');
+});
+
+// Route-specific middleware - executes second in pre-processing, first in post-processing
+const routeMiddleware: Middleware = async ({ reqCtx, next }) => {
+  reqCtx.res.headers.set('x-pre-processed-by', 'route-middleware');
+  await next();
+  reqCtx.res.headers.set('x-post-processed-by', 'route-middleware');
+};
+
+class Lambda implements LambdaInterface {
+  @app.get('/todos')
+  public async getTodos() {
+    const todos = await getAllTodos();
+    return { todos };
+  }
+
+  // This route will have:
+  // x-pre-processed-by: route-middleware (route middleware overwrites global)
+  // x-post-processed-by: global-middleware (global middleware executes last)
+  @app.post('/todos', [routeMiddleware])
+  public async createTodo({ req }: { req: Request }) {
+    const body = await req.json();
+    const todo = await putTodo(body);
+    return todo;
+  }
+
+  async handler(event: unknown, context: Context) {
+    return app.resolve(event, context, { scope: this });
+  }
+}
+
+const lambda = new Lambda();
+export const handler = lambda.handler.bind(lambda);

examples/snippets/event-handler/http/gettingStarted_built_in_error_handler_decorators.ts

@@ -0,0 +1,46 @@
+import type { LambdaInterface } from '@aws-lambda-powertools/commons/types';
+import {
+  HttpStatusCodes,
+  type MethodNotAllowedError,
+  type NotFoundError,
+  Router,
+} from '@aws-lambda-powertools/event-handler/http';
+import { Logger } from '@aws-lambda-powertools/logger';
+import type { Context } from 'aws-lambda';
+
+const logger = new Logger();
+const app = new Router({ logger });
+
+class Lambda implements LambdaInterface {
+  @app.notFound()
+  public async handleNotFound(
+    error: NotFoundError,
+    reqCtx: { req: { headers: { get: (key: string) => string | null } } }
+  ) {
+    logger.error('Unable to get todo', { error });
+
+    return {
+      statusCode: HttpStatusCodes.IM_A_TEAPOT,
+      body: "I'm a teapot!",
+      headers: {
+        'x-correlation-id': reqCtx.req.headers.get('x-correlation-id'),
+      },
+    };
+  }
+
+  @app.methodNotAllowed()
+  public async handleMethodNotAllowed(error: MethodNotAllowedError) {
+    logger.error('Method not allowed', { error });
+
+    return {
+      body: 'This method is not allowed',
+    };
+  }
+
+  async handler(event: unknown, context: Context) {
+    return app.resolve(event, context, { scope: this });
+  }
+}
+
+const lambda = new Lambda();
+export const handler = lambda.handler.bind(lambda);

examples/snippets/event-handler/http/gettingStarted_decorators_basic.ts

@@ -0,0 +1,47 @@
+import type { LambdaInterface } from '@aws-lambda-powertools/commons/types';
+import { Router } from '@aws-lambda-powertools/event-handler/http';
+import { Logger } from '@aws-lambda-powertools/logger';
+import type { Context } from 'aws-lambda';
+
+const logger = new Logger();
+const app = new Router({ logger });
+
+class Lambda implements LambdaInterface {
+  @app.get('/todos/:todoId')
+  public async getTodo({ params }: { params: { todoId: string } }) {
+    logger.debug('Getting todo', { todoId: params.todoId });
+
+    return {
+      id: params.todoId,
+      title: 'Todo Title',
+      completed: false,
+    };
+  }
+
+  @app.post('/todos')
+  public async createTodo({ body }: { body: { title: string } }) {
+    logger.debug('Creating todo', { title: body.title });
+
+    return {
+      id: 'new-todo-id',
+      title: body.title,
+      completed: false,
+    };
+  }
+
+  @app.delete('/todos/:todoId')
+  public async deleteTodo({ params }: { params: { todoId: string } }) {
+    logger.debug('Deleting todo', { todoId: params.todoId });
+
+    return {
+      message: `Todo ${params.todoId} deleted`,
+    };
+  }
+
+  async handler(event: unknown, context: Context) {
+    return app.resolve(event, context, { scope: this });
+  }
+}
+
+const lambda = new Lambda();
+export const handler = lambda.handler.bind(lambda);

examples/snippets/event-handler/http/gettingStarted_error_handling_decorators.ts

@@ -0,0 +1,43 @@
+import type { LambdaInterface } from '@aws-lambda-powertools/commons/types';
+import {
+  HttpStatusCodes,
+  Router,
+} from '@aws-lambda-powertools/event-handler/http';
+import { Logger } from '@aws-lambda-powertools/logger';
+import type { Context } from 'aws-lambda';
+
+declare function getTodoById<T>(todoId: unknown): Promise<{ id: string } & T>;
+declare class GetTodoError extends Error {}
+
+const logger = new Logger();
+const app = new Router({ logger });
+
+class Lambda implements LambdaInterface {
+  @app.errorHandler(GetTodoError)
+  public async handleGetTodoError(
+    error: GetTodoError,
+    reqCtx: {
+      req: { headers: { get: (key: string) => string | null } };
+    }
+  ) {
+    logger.error('Unable to get todo', { error });
+
+    return {
+      statusCode: HttpStatusCodes.BAD_REQUEST,
+      message: `Bad request: ${error.message} - ${reqCtx.req.headers.get('x-correlation-id')}`,
+    };
+  }
+
+  @app.get('/todos/:todoId')
+  public async getTodo({ params }: { params: { todoId: string } }) {
+    const todo = await getTodoById(params.todoId); // May throw GetTodoError
+    return { todo };
+  }
+
+  async handler(event: unknown, context: Context) {
+    return app.resolve(event, context, { scope: this });
+  }
+}
+
+const lambda = new Lambda();
+export const handler = lambda.handler.bind(lambda);