feat(event-handler): add type-safe Store API for request and shared state (#5081)

Co-authored-by: Swopnil Dangol <swopnildangol@gmail.com>

Author: svozza

docs/features/event-handler/http.md

@@ -922,6 +922,94 @@ When necessary, you can set a prefix when including a `Router` instance. This me
     --8<-- "examples/snippets/event-handler/http/split_route_prefix_index.ts"
     ```
 
+### Store
+
+The Store API provides a way to share data between middleware and route handlers without relying on closures or module-level variables. There are two types of store: **request** and **shared**.
+
+#### Request store
+
+The request store is scoped to a single invocation. Each time your Lambda function handles a request, a fresh store is created. This is ideal for passing values like authenticated user IDs or parsed tokens from middleware to route handlers.
+
+You can interact with the request store directly on the request context using `set`, `get`, `has`, and `delete`.
+
+=== "index.ts"
+
+    ```ts hl_lines="12 18"
+    --8<-- "examples/snippets/event-handler/http/advanced_store_request.ts:8"
+    ```
+
+    1. Middleware stores the authenticated user ID in the request store.
+    2. Route handler retrieves the user ID set by middleware.
+
+!!! note "Request store lifecycle"
+    The request store is created at the beginning of each invocation and is not shared across concurrent or subsequent requests. You don't need to clean up after yourself — the store is discarded when the invocation completes.
+
+#### Shared store
+
+The shared store lives on the `Router` instance and persists across invocations for the lifetime of the execution environment. This makes it suitable for values that are expensive to compute and don't change between requests, such as database clients, configuration, or feature flags.
+
+You can access the shared store via `app.shared` at the module level (e.g., during cold start), or via `reqCtx.shared` inside middleware and route handlers.
+
+=== "index.ts"
+
+    ```ts hl_lines="7-8 11-12"
+    --8<-- "examples/snippets/event-handler/http/advanced_store_shared.ts"
+    ```
+
+    1. Set shared values at the module level during cold start.
+    2. Access shared values inside route handlers via `reqCtx.shared`.
+
+#### Typed stores
+
+By default, both stores accept any string key and return `unknown` values. When you know the shape of your data ahead of time, you can define an `Env` type to get full type safety on store keys and values.
+
+=== "index.ts"
+
+    ```ts hl_lines="4-9 14 20-21 27-28 31"
+    --8<-- "examples/snippets/event-handler/http/advanced_store_typed.ts:8"
+    ```
+
+    1. Define the shape of the request store — keys and their value types.
+    2. Define the shape of the shared store.
+    3. `app.shared.set` only accepts keys defined in `AppEnv['store']['shared']` with matching value types.
+    4. `reqCtx.set` only accepts keys defined in `AppEnv['store']['request']` with matching value types.
+    5. `reqCtx.get('userId')` returns `string | undefined` instead of `unknown`.
+    6. `reqCtx.shared.get('db')` returns the typed database client or `undefined`.
+    7. Accessing a key not defined in `AppEnv` is a type error — the compiler only allows `'userId'` and `'isAdmin'`.
+
+!!! tip "Store values are always `T | undefined`"
+    Even with typed stores, `get` returns `T[K] | undefined`. This ensures you handle the case where a value hasn't been set yet, for example if a middleware hasn't run or a shared value wasn't initialized during cold start.
+
+#### Typed stores with split routers
+
+When using [split routers](#split-routers), each sub-router can declare its own `Env` type with only the store keys it needs. You can then chain `includeRouter` calls to merge the store types together, so the parent router sees all keys from all sub-routers.
+
+=== "index.ts"
+
+    ```ts hl_lines="5-9 12-16 32 35-36 38-39"
+    --8<-- "examples/snippets/event-handler/http/advanced_store_include_router.ts"
+    ```
+
+    1. Chaining `includeRouter` calls merges the store types from each sub-router.
+    2. Inferred as `string | undefined` — from `AuthEnv`.
+    3. Inferred as `number | undefined` — from `FeatureEnv`.
+    4. Assigning `maxResults` to a `string` variable produces a type error — the compiler knows it's a `number`.
+
+Alternatively, you can declare the full environment type upfront on the parent router using the `MergeEnv` utility type.
+`MergeEnv` takes a tuple of `Env` types and intersects their request and shared stores into a single `Env`,
+so you don't have to manually write out the combined type.
+This is useful when you prefer to define the parent's type in one place rather than relying on chaining to infer it.
+
+=== "index.ts"
+
+    ```ts hl_lines="18 32-34"
+    --8<-- "examples/snippets/event-handler/http/advanced_store_declare_upfront.ts"
+    ```
+
+    1. `MergeEnv` computes the intersection of the sub-router store types into a single `Env`.
+    2. The parent router is created with the merged `AppEnv` type — all store keys are known upfront.
+    3. `includeRouter` accepts any sub-router whose `Env` is a subset of the parent's.
+
 ### Considerations
 
 This utility is optimized for AWS Lambda computing model and prioritizes fast startup, minimal feature set, and quick onboarding for triggers supported by Lambda.

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

@@ -0,0 +1,42 @@
+import { Router } from '@aws-lambda-powertools/event-handler/http';
+import type { MergeEnv } from '@aws-lambda-powertools/event-handler/types';
+
+type AuthEnv = {
+  store: {
+    request: { userId: string };
+    shared: { db: { query: (sql: string) => Promise<unknown> } };
+  };
+};
+
+type FeatureEnv = {
+  store: {
+    request: { maxResults: number };
+    shared: { cache: Map<string, unknown> };
+  };
+};
+
+type AppEnv = MergeEnv<[AuthEnv, FeatureEnv]>; // (1)!
+
+const authRouter = new Router<AuthEnv>();
+authRouter.use(async ({ reqCtx, next }) => {
+  reqCtx.set('userId', 'user-123');
+  await next();
+});
+
+const featureRouter = new Router<FeatureEnv>();
+featureRouter.use(async ({ reqCtx, next }) => {
+  reqCtx.set('maxResults', 50);
+  await next();
+});
+
+const app = new Router<AppEnv>(); // (2)!
+app.includeRouter(authRouter); // (3)!
+app.includeRouter(featureRouter);
+
+app.get('/dashboard', (reqCtx) => {
+  const userId = reqCtx.get('userId'); // string | undefined
+  const maxResults = reqCtx.get('maxResults'); // number | undefined
+
+  if (!userId || !maxResults) return { ready: false };
+  return { userId, maxResults };
+});

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

@@ -0,0 +1,43 @@
+import { Router } from '@aws-lambda-powertools/event-handler/http';
+
+// Each sub-router declares only the store keys it needs
+
+type AuthEnv = {
+  store: {
+    request: { userId: string };
+    shared: { db: { query: (sql: string) => Promise<unknown> } };
+  };
+};
+
+type FeatureEnv = {
+  store: {
+    request: { maxResults: number };
+    shared: { cache: Map<string, unknown> };
+  };
+};
+
+const authRouter = new Router<AuthEnv>();
+authRouter.use(async ({ reqCtx, next }) => {
+  reqCtx.set('userId', 'user-123');
+  await next();
+});
+
+const featureRouter = new Router<FeatureEnv>();
+featureRouter.use(async ({ reqCtx, next }) => {
+  reqCtx.set('maxResults', 50);
+  await next();
+});
+
+// Chain includeRouter to merge store types // (1)!
+const app = new Router().includeRouter(authRouter).includeRouter(featureRouter);
+
+app.get('/dashboard', (reqCtx) => {
+  const userId = reqCtx.get('userId'); // (2)!
+  const maxResults = reqCtx.get('maxResults'); // (3)!
+
+  // @ts-expect-error - maxResults is number | undefined, not string
+  const _wrong: string = reqCtx.get('maxResults'); // (4)!
+
+  if (!userId || !maxResults) return { ready: false };
+  return { userId, maxResults };
+});

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

@@ -0,0 +1,33 @@
+declare const getUserProfile: (
+  userId: string
+) => Promise<{ name: string; email: string }>;
+declare const jwt: {
+  verify(token: string, secret: string): { sub: string };
+};
+
+import { Router } from '@aws-lambda-powertools/event-handler/http';
+import type { Context } from 'aws-lambda';
+
+const app = new Router();
+
+// Middleware sets a value in the request store
+app.use(async ({ reqCtx, next }) => {
+  const auth = reqCtx.req.headers.get('Authorization') ?? '';
+  const token = auth.replace('Bearer ', '');
+  const { sub } = jwt.verify(token, 'secret');
+
+  reqCtx.set('userId', sub); // (1)!
+
+  await next();
+});
+
+app.get('/profile', async (reqCtx) => {
+  const userId = reqCtx.get('userId'); // (2)!
+  if (!userId) return { error: 'Not authenticated' };
+
+  const profile = await getUserProfile(userId as string);
+  return { profile };
+});
+
+export const handler = async (event: unknown, context: Context) =>
+  app.resolve(event, context);

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

@@ -0,0 +1,19 @@
+import { Router } from '@aws-lambda-powertools/event-handler/http';
+import type { Context } from 'aws-lambda';
+
+const app = new Router();
+
+// Set shared values during cold start
+app.shared.set('region', process.env.AWS_REGION ?? 'us-east-1'); // (1)!
+app.shared.set('startedAt', Date.now());
+
+app.get('/health', (reqCtx) => {
+  const region = reqCtx.shared.get('region') as string; // (2)!
+  const startedAt = reqCtx.shared.get('startedAt') as number;
+  const uptime = Date.now() - startedAt;
+
+  return { status: 'ok', region, uptime };
+});
+
+export const handler = async (event: unknown, context: Context) =>
+  app.resolve(event, context);

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

@@ -0,0 +1,45 @@
+declare const jwt: {
+  verify(token: string, secret: string): { sub: string; isAdmin: boolean };
+};
+declare const createDbClient: () => {
+  query: (sql: string) => Promise<unknown>;
+};
+
+import { Router } from '@aws-lambda-powertools/event-handler/http';
+import type { Context } from 'aws-lambda';
+
+type AppEnv = {
+  store: {
+    request: { userId: string; isAdmin: boolean }; // (1)!
+    shared: { db: { query: (sql: string) => Promise<unknown> } }; // (2)!
+  };
+};
+
+const app = new Router<AppEnv>();
+
+// Shared store is typed — only accepts keys defined in AppEnv
+app.shared.set('db', createDbClient()); // (3)!
+
+app.use(async ({ reqCtx, next }) => {
+  const auth = reqCtx.req.headers.get('Authorization') ?? '';
+  const { sub, isAdmin } = jwt.verify(auth.replace('Bearer ', ''), 'secret');
+
+  reqCtx.set('userId', sub); // (4)!
+  reqCtx.set('isAdmin', isAdmin);
+
+  await next();
+});
+
+app.get('/profile', async (reqCtx) => {
+  const userId = reqCtx.get('userId'); // (5)!
+  const db = reqCtx.shared.get('db'); // (6)!
+
+  // @ts-expect-error - 'email' is not a key defined in AppEnv
+  reqCtx.get('email'); // (7)!
+
+  if (!userId || !db) return { error: 'not ready' };
+  return { userId };
+});
+
+export const handler = async (event: unknown, context: Context) =>
+  app.resolve(event, context);

packages/event-handler/package.json

@@ -13,7 +13,7 @@
     "test": "vitest --run",
     "test:unit": "vitest --run tests/unit",
     "test:unit:coverage": "vitest --run tests/unit --coverage.enabled --coverage.thresholds.100 --coverage.include='src/**'",
-    "test:unit:types": "echo 'Not Implemented'",
+    "test:unit:types": "vitest --typecheck --run tests/types",
     "test:e2e:nodejs20x": "RUNTIME=nodejs20x vitest run tests/e2e",
     "test:e2e:nodejs22x": "RUNTIME=nodejs22x vitest run tests/e2e",
     "test:e2e:nodejs24x": "RUNTIME=nodejs24x vitest run tests/e2e",
@@ -70,6 +70,16 @@
         "default": "./lib/esm/types/index.js"
       }
     },
+    "./store": {
+      "require": {
+        "types": "./lib/cjs/store/index.d.ts",
+        "default": "./lib/cjs/store/index.js"
+      },
+      "import": {
+        "types": "./lib/esm/store/index.d.ts",
+        "default": "./lib/esm/store/index.js"
+      }
+    },
     "./http": {
       "require": {
         "types": "./lib/cjs/http/index.d.ts",

packages/event-handler/src/http/Route.ts

@@ -1,4 +1,5 @@
 import type {
+  Env,
   HandlerResponse,
   HttpMethod,
   Middleware,
@@ -17,13 +18,13 @@ class Route<
   readonly id: string;
   readonly method: string;
   readonly path: Path;
-  readonly handler: RouteHandler | TypedRouteHandler<TReq, TResBody, TRes>;
+  readonly handler: RouteHandler | TypedRouteHandler<Env, TReq, TResBody, TRes>;
   readonly middleware: Middleware[];
 
   constructor(
     method: HttpMethod,
     path: Path,
-    handler: RouteHandler | TypedRouteHandler<TReq, TResBody, TRes>,
+    handler: RouteHandler | TypedRouteHandler<Env, TReq, TResBody, TRes>,
     middleware: Middleware[] = []
   ) {
     this.id = `${method}:${path}`;