add middleware composition section

Author: svozza

docs/features/event-handler/rest.md

@@ -427,6 +427,25 @@ During the middleware execution chain, the response object (`reqCtx.res`) can be
 other middleware or the route handler. When you destructure the request context, you capture
 a reference to the response object as it existed at that moment, not the current response.
 
+#### Composing middleware
+
+You can create reusable middleware stacks by using the `composeMiddleware` function to combine
+multiple middleware into a single middleware function. This is useful for creating standardized
+middleware combinations that can be shared across different routes or applications.
+
+=== "index.ts"
+
+    ```ts hl_lines="25-26 32 35"
+    --8<-- "examples/snippets/event-handler/rest/advanced_mw_compose_middleware.ts:3"
+    ```
+
+The `composeMiddleware` function maintains the same execution order as if you had applied the
+middleware individually, following the onion pattern where middleware execute in order during
+pre-processing and in reverse order during post-processing.
+
+!!! note "Composition order"
+    Unlike traditional function composition which typically works right-to-left, `composeMiddleware` follows the convention used by most web frameworks and executes middleware left-to-right (first to last in the array). This means `composeMiddleware([a, b, c])` executes middleware `a` first, then `b`, then `c`.
+
 ### Fine grained responses
 
 You can use the Web API's `Response` object to have full control over the response. For

examples/snippets/event-handler/rest/advanced_mw_compose_middleware.ts

@@ -0,0 +1,57 @@
+declare const getAllTodos: () => Promise<any[]>;
+declare const putTodo: (body: any) => Promise<any>;
+
+import {
+  composeMiddleware,
+  Router,
+} from '@aws-lambda-powertools/event-handler/experimental-rest';
+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();
+
+// Individual middleware functions
+const logging: Middleware = async (params, reqCtx, next) => {
+  logger.info(`Request: ${reqCtx.request.method} ${reqCtx.request.url}`);
+  await next();
+  logger.info(`Response: ${reqCtx.res.status}`);
+};
+
+const cors: Middleware = async (params, reqCtx, next) => {
+  await next();
+  reqCtx.res.headers.set('Access-Control-Allow-Origin', '*');
+  reqCtx.res.headers.set(
+    'Access-Control-Allow-Methods',
+    'GET, POST, PUT, DELETE'
+  );
+};
+
+const rateLimit: Middleware = async (params, reqCtx, next) => {
+  // Rate limiting logic would go here
+  reqCtx.res.headers.set('X-RateLimit-Limit', '100');
+  await next();
+};
+
+// Compose middleware stack for all requests
+const apiMiddleware = composeMiddleware([logging, cors, rateLimit]);
+
+const app = new Router();
+
+// Use composed middleware globally
+app.use(apiMiddleware);
+
+app.get('/todos', async () => {
+  const todos = await getAllTodos();
+  return { todos };
+});
+
+app.post('/todos', async (params, { request }) => {
+  const body = await request.json();
+  const todo = await putTodo(body);
+  return todo;
+});
+
+export const handler = async (event: unknown, context: Context) => {
+  return await app.resolve(event, context);
+};