lambda-deadline-middleware 1.1.0 → 2.0.0

package/README.md

@@ -3,21 +3,65 @@
 
 # lambda-deadline-middleware
 
-Zero-dependency AWS SDK v3 middleware that automatically propagates Lambda execution deadlines to outgoing SDK calls via
-`AbortController`-based timeouts.
+[![npm version](https://img.shields.io/npm/v/lambda-deadline-middleware)](https://www.npmjs.com/package/lambda-deadline-middleware)
+[![CI](https://github.com/mikkopiu/lambda-deadline-middleware/actions/workflows/ci.yml/badge.svg)](https://github.com/mikkopiu/lambda-deadline-middleware/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 
-When an AWS SDK call hangs inside a Lambda function, the runtime terminates the process at the configured timeout
-without throwing an error or giving your code a chance to react. This library prevents that by computing per-request
-deadlines from the Lambda's remaining execution time and aborting requests before the hard timeout fires.
+Zero-dependency AWS SDK v3 middleware that propagates Lambda deadlines to outgoing SDK calls via `AbortSignal`.
+
+When an AWS SDK call hangs inside a Lambda, the runtime kills the process without throwing an error or giving your code
+a chance to react. This library attaches an `AbortSignal` to every outgoing SDK request so your calls fail fast instead
+of getting killed silently. The signal comes either from an external source you provide or is computed once from the
+Lambda's remaining execution time.
+
+```typescript
+import { withLambdaDeadline, deadlineMiddleware } from "lambda-deadline-middleware";
+import { DynamoDBClient, GetItemCommand } from "@aws-sdk/client-dynamodb";
+
+const dynamodb = new DynamoDBClient({});
+dynamodb.middlewareStack.use(deadlineMiddleware());
+
+export const handler = withLambdaDeadline(async (event, context) => {
+  return dynamodb.send(new GetItemCommand({ TableName: "my-table", Key: { id: { S: event.id } } }));
+});
+```
 
 ## Features
 
-- Automatic deadline propagation, no manual timeout configuration per call
-- Fresh deadline per retry: each SDK retry attempt uses _current_ remaining time
-- Signal composition: preserves caller-provided `AbortSignal` via `AbortSignal.any()`
-- Zero runtime dependencies (`@smithy/types` is compile-time only)
-- Complete no-op when no Lambda context is available
-- Branded types prevent millisecond/buffer interchange at compile time
+- Zero runtime dependencies
+- Bring your own `AbortSignal` (from Middy, a manual `AbortController`, or any framework), or let the library compute
+  one from `getRemainingTimeInMillis()` at invocation start
+- One signal per invocation: covers all SDK calls and retries within the handler
+- Works alongside per-request `abortSignal` options you pass to `.send()`
+- Complete no-op outside Lambda (safe in local dev and tests)
+
+## How It Works
+
+```mermaid
+flowchart LR
+    subgraph Handler startup
+        A[Lambda Runtime] --> B[withLambdaDeadline]
+        B -->|compute signal once| C[AbortSignal.timeout]
+        B --> D[Your Handler]
+    end
+
+    subgraph Per outgoing SDK request
+        E[SDK .send] --> F[Deadline Middleware]
+        F -->|signal exists?| G[Compose with request signal]
+        F -->|no signal| H[Pass through]
+        G --> I[HTTP Request]
+        H --> I
+    end
+
+    D --> E
+
+    style F fill:#f9a825,stroke:#f57f17
+    style B fill:#66bb6a,stroke:#2e7d32
+```
+
+`withLambdaDeadline` computes `AbortSignal.timeout(remaining - flushBuffer)` once at invocation start and stores it in
+`AsyncLocalStorage`. The middleware reads it on each outgoing request and composes it with any per-request signal. If
+`setDeadlineSignal()` was called, that signal is used instead.
 
 ## Requirements
 
@@ -27,18 +71,17 @@ deadlines from the Lambda's remaining execution time and aborting requests befor
 ## Installation
 
 ```bash
-pnpm add lambda-deadline-middleware
+npm install lambda-deadline-middleware
 ```
 
 ## Usage
 
-Setup requires two pieces:
+Setup has two parts:
 
-1. **Wrap your handler** with `withLambdaDeadline`. This stores the Lambda `context` (specifically
-   `getRemainingTimeInMillis()`) in `AsyncLocalStorage` so the SDK middleware can read it. The SDK middleware stack has
-   no access to the Lambda context on its own.
+1. **Wrap your handler** with `withLambdaDeadline`. Computes the deadline signal once and stores it in
+   `AsyncLocalStorage`.
 
-2. **Register the middleware** on each SDK client via the standard `middlewareStack.use()` pattern.
+2. **Register the middleware** on each SDK client.
 
 ```typescript
 import { withLambdaDeadline, deadlineMiddleware } from "lambda-deadline-middleware";
@@ -57,66 +100,114 @@ export const handler = withLambdaDeadline(async (event, context) => {
 });
 ```
 
-Every SDK call through `dynamodb` now receives a timeout derived from the Lambda's remaining execution time minus a
-configurable flush buffer (default: 1000ms).
+Every SDK call through `dynamodb` gets an `AbortSignal` that fires at `remainingTime - flushBuffer` ms from handler
+start.
 
-## How It Works
+## External Signal (Middy, manual AbortController, etc.)
 
-```mermaid
-flowchart LR
-    subgraph Lambda Invocation
-        direction LR
-        A[Lambda Runtime] --> B[withLambdaDeadline]
-        B --> C[Your Handler]
-        C --> D[SDK .send]
-    end
+If you already have an `AbortSignal` (from Middy's `timeoutEarlyInMillis`, a manual controller, or anything else), pass
+it in directly:
 
-    subgraph Per Attempt
-        direction LR
-        D --> E[Deadline Middleware]
-        E -->|getRemainingTimeInMillis\nminus flush buffer| F[AbortController\n+ setTimeout]
-        F --> G[HTTP Request]
-    end
+```typescript
+import {
+  withLambdaDeadline,
+  deadlineMiddleware,
+  setDeadlineSignal,
+} from "lambda-deadline-middleware";
+import middy from "@middy/core";
+import { DynamoDBClient, GetItemCommand } from "@aws-sdk/client-dynamodb";
 
-    style E fill:#f9a825,stroke:#f57f17
-    style B fill:#66bb6a,stroke:#2e7d32
+const dynamodb = new DynamoDBClient({});
+dynamodb.middlewareStack.use(deadlineMiddleware());
+
+// Middy passes { signal } as the third argument when timeoutEarlyInMillis is set
+const baseHandler = async (event, context, { signal }) => {
+  setDeadlineSignal(signal);
+  const result = await dynamodb.send(
+    new GetItemCommand({
+      /* ... */
+    }),
+  );
+  return { statusCode: 200, body: JSON.stringify(result) };
+};
+
+export const handler = withLambdaDeadline(
+  middy({ timeoutEarlyInMillis: 1000 }).handler(baseHandler),
+);
+```
+
+When an external signal is set via `setDeadlineSignal()`:
+
+- It **replaces** the auto-computed signal for the current invocation
+- The signal is composed with any per-request `AbortSignal` via `AbortSignal.any()`
+- You control when and why the abort fires
+
+When no external signal is set, the auto-computed signal (from `withLambdaDeadline`) is used.
+
+**Important:** `withLambdaDeadline` must wrap the outside. It creates the `AsyncLocalStorage` scope that
+`setDeadlineSignal` writes into.
+
+```typescript
+// ✅ Correct: withLambdaDeadline on the outside
+export const handler = withLambdaDeadline(
+  middy({ timeoutEarlyInMillis: 1000 }).handler(baseHandler),
+);
+
+// ❌ Wrong: store doesn't exist yet when baseHandler runs
+export const handler = middy({ timeoutEarlyInMillis: 1000 }).handler(
+  withLambdaDeadline(baseHandler),
+);
 ```
 
-`withLambdaDeadline` stores the Lambda context in `AsyncLocalStorage`. The deadline middleware reads it on every attempt
-(including retries), computes a fresh timeout, and attaches an `AbortSignal` to the outgoing HTTP request.
+`setDeadlineSignal` only affects AWS SDK calls (via the Smithy middleware stack). For other async work, pass the signal
+yourself:
+
+```typescript
+const baseHandler = async (event, context, { signal }) => {
+  setDeadlineSignal(signal);
+
+  // SDK calls: aborted via middleware
+  const item = await dynamodb.send(
+    new GetItemCommand({
+      /* ... */
+    }),
+  );
+
+  // Non-SDK calls: pass signal manually
+  const response = await fetch("https://api.example.com/data", { signal });
+};
+```
 
 ## Configuration
 
 ### Flush Buffer
 
-The flush buffer is subtracted from the remaining Lambda time to leave room for graceful shutdown and error handling:
+Subtracted from remaining Lambda time to leave room for cleanup:
 
 ```typescript
-// Default: 1000ms
-dynamodb.middlewareStack.use(deadlineMiddleware());
+// Default: 1000ms flush buffer
+export const handler = withLambdaDeadline(myHandler);
 
-// Custom: 500ms
-dynamodb.middlewareStack.use(deadlineMiddleware({ flushBufferMs: 500 }));
+// Custom: 500ms flush buffer
+export const handler = withLambdaDeadline(myHandler, { flushBufferMs: 500 });
 ```
 
+Only applies to automatic signal computation. With `setDeadlineSignal()`, you control timing yourself.
+
 ## Error Handling
 
-When remaining time is less than or equal to the flush buffer, the middleware throws `DeadlineExceededError` immediately
-without dispatching an HTTP request.
+When remaining time ≤ flush buffer, `withLambdaDeadline` throws `DeadlineExceededError` without calling the handler:
 
 ```typescript
 import { isDeadlineExceeded } from "lambda-deadline-middleware";
 
 try {
-  await dynamodb.send(
-    new GetItemCommand({
-      /* ... */
-    }),
-  );
+  await handler(event, context);
 } catch (error) {
   if (isDeadlineExceeded(error)) {
-    console.log(`Deadline exceeded: ${error.deadlineMs}ms`);
-    console.log(`Remaining time was: ${error.remainingMs}ms`);
+    console.log(
+      `Deadline exceeded: remaining ${error.remainingMs}ms, buffer ${error.flushBufferMs}ms`,
+    );
   }
   throw error;
 }
@@ -124,11 +215,11 @@ try {
 
 ## Signal Composition
 
-If you pass an `AbortSignal` to a request, the middleware composes both signals:
+If you pass an `AbortSignal` to a specific SDK request, the middleware composes both. Whichever fires first wins:
 
 ```typescript
 const controller = new AbortController();
-setTimeout(() => controller.abort(), 5000);
+setTimeout(() => controller.abort(), 2000);
 
 await dynamodb.send(
   new GetItemCommand({
@@ -142,36 +233,36 @@ await dynamodb.send(
 
 ## API Reference
 
-### `withLambdaDeadline(handler)`
+### `withLambdaDeadline(handler, options?)`
 
-Wraps a Lambda handler to store the Lambda context in `AsyncLocalStorage`. Required for the middleware to access
-`getRemainingTimeInMillis()`.
+Wraps a Lambda handler. Computes `AbortSignal.timeout(remaining - flushBuffer)` and stores it in `AsyncLocalStorage`.
 
 ```typescript
 function withLambdaDeadline<TEvent, TResult>(
   handler: (event: TEvent, context: LambdaContextLike) => Promise<TResult>,
+  options?: DeadlineOptions,
 ): (event: TEvent, context: LambdaContextLike) => Promise<TResult>;
 ```
 
-### `deadlineMiddleware(options?)`
+### `deadlineMiddleware()`
 
-Returns a `Pluggable` for `client.middlewareStack.use()`.
+Returns a `Pluggable` for `client.middlewareStack.use()`. Attaches the stored deadline signal to outgoing requests.
 
 ```typescript
-function deadlineMiddleware(options?: DeadlineOptions): Pluggable<object, object>;
+function deadlineMiddleware(): Pluggable<object, object>;
 ```
 
-### `getRemainingTimeInMillis()`
+### `setDeadlineSignal(signal)`
 
-Accessor for the current Lambda's remaining execution time. Returns `undefined` outside a Lambda context.
+Replaces the deadline signal for the current invocation. Must be called within a `withLambdaDeadline()` scope.
 
 ```typescript
-function getRemainingTimeInMillis(): number | undefined;
+function setDeadlineSignal(signal: AbortSignal): void;
 ```
 
 ### `isDeadlineExceeded(error)`
 
-Type guard for deadline-triggered abort errors.
+Type guard for deadline-triggered errors.
 
 ```typescript
 function isDeadlineExceeded(error: unknown): error is DeadlineExceededError;
@@ -179,12 +270,14 @@ function isDeadlineExceeded(error: unknown): error is DeadlineExceededError;
 
 ### `DeadlineExceededError`
 
+Thrown by `withLambdaDeadline` when `remainingTime ≤ flushBufferMs`.
+
 ```typescript
 class DeadlineExceededError extends Error {
   readonly name: "DeadlineExceededError";
-  readonly deadlineMs: Milliseconds;
-  readonly flushBufferMs: Milliseconds;
-  readonly remainingMs: Milliseconds;
+  readonly deadlineMs: number;
+  readonly flushBufferMs: number;
+  readonly remainingMs: number;
 }
 ```
 
@@ -198,20 +291,19 @@ interface DeadlineOptions {
 
 ### Types
 
-| Type                | Description                                                  |
-| ------------------- | ------------------------------------------------------------ |
-| `Milliseconds`      | Branded number representing a duration in ms                 |
-| `LambdaContextLike` | Minimal interface: `{ getRemainingTimeInMillis?(): number }` |
+| Type                | Description                                                      |
+| ------------------- | ---------------------------------------------------------------- |
+| `LambdaContextLike` | Minimal interface: `{ getRemainingTimeInMillis?: () => number }` |
 
 ## Reporting Bugs
 
-Found a bug? Please open a [GitHub Issue](https://github.com/mikkopiu/lambda-deadline-middleware/issues/new) with:
+Found a bug? Please open a [GitHub Issue](https://github.com/mikkopiu/lambda-deadline-middleware/issues/new) with a
+minimal reproduction, your Node.js version, and AWS SDK version. For security vulnerabilities, see
+[SECURITY.md](SECURITY.md).
 
-- Your Node.js version and AWS SDK version
-- A minimal code snippet reproducing the problem
-- Expected vs actual behavior
+## Changelog
 
-For security vulnerabilities, see [SECURITY.md](SECURITY.md) instead.
+See [GitHub Releases](https://github.com/mikkopiu/lambda-deadline-middleware/releases).
 
 ## License
 

package/dist/context-store.d.ts

@@ -1,7 +1,30 @@
+import type { DeadlineOptions } from "./types.js";
 export interface LambdaContextLike {
 	getRemainingTimeInMillis?: () => number;
 }
-export declare const run: <T>(context: LambdaContextLike | null | undefined, fn: () => T) => T;
-export declare const getRemainingTimeInMillis: () => number | undefined;
+/**
+* Store an external AbortSignal for the current invocation.
+* When set, the SDK middleware uses this signal directly instead of
+* the auto-computed deadline signal.
+*
+* Call this at the start of your handler, before any SDK calls.
+* The signal is scoped to the current async context (AsyncLocalStorage).
+*/
+export declare const setDeadlineSignal: (signal: AbortSignal) => void;
+/**
+* Retrieve the deadline signal for the current invocation, if one exists.
+*/
+export declare const getDeadlineSignal: () => AbortSignal | undefined;
+type AsyncHandler<
+	TEvent,
+	TContext extends LambdaContextLike,
+	TResult
+> = (event: TEvent, context: TContext) => Promise<TResult>;
+export declare const withLambdaDeadline: <
+	TEvent,
+	TContext extends LambdaContextLike,
+	TResult
+>(handler: AsyncHandler<TEvent, TContext, TResult>, options?: DeadlineOptions) => AsyncHandler<TEvent, TContext, TResult>;
+export {};
 
 //# sourceMappingURL=context-store.d.ts.map

package/dist/context-store.d.ts.map

@@ -1 +1 @@
-{"mappings":"AAOA,iBAAiB,kBAAkB;CACjC;AACF;AAIA,OAAO,cAAM,MAAO,GAAG,SAAS,sCAAsC,UAAU,MAAI;AAKpF,OAAO,cAAM","names":[],"sources":["src/context-store.ts"],"version":3,"sourcesContent":["// SPDX-FileCopyrightText: 2026 lambda-deadline-middleware contributors\n// SPDX-License-Identifier: MIT\n\nimport { AsyncLocalStorage } from \"node:async_hooks\";\n\n// AsyncLocalStorage propagates the Lambda context through the entire async call chain without parameter threading.\n// SDK middleware executes deep in the Smithy stack where we can't pass the context through function signatures.\nexport interface LambdaContextLike {\n  getRemainingTimeInMillis?: () => number;\n}\n\nconst contextStorage = new AsyncLocalStorage<LambdaContextLike>();\n\nexport const run = <T>(context: LambdaContextLike | null | undefined, fn: () => T): T => {\n  if (context === null || context === undefined) return fn();\n  return contextStorage.run(context, fn);\n};\n\nexport const getRemainingTimeInMillis = (): number | undefined => {\n  const store = contextStorage.getStore();\n  if (store === undefined) return undefined;\n  if (typeof store.getRemainingTimeInMillis !== \"function\") return undefined;\n  return store.getRemainingTimeInMillis();\n};\n"]}
+{"mappings":"AAOA,cAAc,uBAAuB;AAIrC,iBAAiB,kBAAkB;CACjC;AACF;;;;;;;;;AAgBA,OAAO,cAAM,oBAAqB,QAAQ;;;;AAW1C,OAAO,cAAM,yBAAwB;KAOhC;CAAa;CAAQ,iBAAiB;CAAmB;KAC5D,OAAO,QACP,SAAS,aACN,QAAQ;AAEb,OAAO,cAAM;CACV;CAAQ,iBAAiB;CAAmB;EAC3C,SAAS,aAAa,QAAQ,UAAU,UACxC,UAAU,oBACT,aAAa,QAAQ,UAAU","names":[],"sources":["src/context-store.ts"],"version":3,"sourcesContent":["// SPDX-FileCopyrightText: 2026 lambda-deadline-middleware contributors\n// SPDX-License-Identifier: MIT\n\nimport { AsyncLocalStorage } from \"node:async_hooks\";\n\nimport { DeadlineExceededError } from \"./error.js\";\n\nimport type { DeadlineOptions } from \"./types.js\";\n\n// AsyncLocalStorage propagates the deadline signal through the entire async call chain.\n// SDK middleware executes deep in the Smithy stack where we can't pass it through function signatures.\nexport interface LambdaContextLike {\n  getRemainingTimeInMillis?: () => number;\n}\n\ninterface DeadlineStore {\n  signal?: AbortSignal;\n}\n\nconst contextStorage = new AsyncLocalStorage<DeadlineStore>();\n\n/**\n * Store an external AbortSignal for the current invocation.\n * When set, the SDK middleware uses this signal directly instead of\n * the auto-computed deadline signal.\n *\n * Call this at the start of your handler, before any SDK calls.\n * The signal is scoped to the current async context (AsyncLocalStorage).\n */\nexport const setDeadlineSignal = (signal: AbortSignal): void => {\n  const store = contextStorage.getStore();\n  if (store === undefined) {\n    throw new Error(\"setDeadlineSignal() must be called within a withLambdaDeadline() scope\");\n  }\n  store.signal = signal;\n};\n\n/**\n * Retrieve the deadline signal for the current invocation, if one exists.\n */\nexport const getDeadlineSignal = (): AbortSignal | undefined => {\n  const store = contextStorage.getStore();\n  if (store === undefined) return undefined;\n  return store.signal;\n};\n\n// Handler wrapper — computes the deadline signal once at invocation start and stores it via AsyncLocalStorage.\ntype AsyncHandler<TEvent, TContext extends LambdaContextLike, TResult> = (\n  event: TEvent,\n  context: TContext,\n) => Promise<TResult>;\n\nexport const withLambdaDeadline =\n  <TEvent, TContext extends LambdaContextLike, TResult>(\n    handler: AsyncHandler<TEvent, TContext, TResult>,\n    options?: DeadlineOptions,\n  ): AsyncHandler<TEvent, TContext, TResult> =>\n  async (event: TEvent, context: TContext): Promise<TResult> => {\n    const store: DeadlineStore = {};\n\n    // Compute the auto-deadline signal once, up front.\n    // If the user calls setDeadlineSignal() later, it overwrites this.\n    // oxlint-disable-next-line typescript/no-unnecessary-condition -- runtime safety: context may be null/undefined despite types (e.g. untyped callers)\n    if (context !== null && context !== undefined) {\n      const remaining =\n        typeof context.getRemainingTimeInMillis === \"function\"\n          ? context.getRemainingTimeInMillis()\n          : undefined;\n\n      if (remaining !== undefined) {\n        const rawBuffer = options?.flushBufferMs ?? 1000;\n        if (rawBuffer < 0) {\n          throw new TypeError(`flushBufferMs option must be non-negative, received: ${rawBuffer}`);\n        }\n        const deadline = remaining - rawBuffer;\n\n        if (deadline <= 0) {\n          throw new DeadlineExceededError({\n            deadlineMs: 0,\n            flushBufferMs: rawBuffer,\n            remainingMs: remaining,\n          });\n        }\n\n        store.signal = AbortSignal.timeout(deadline);\n      }\n    }\n\n    return contextStorage.run(store, async () => handler(event, context));\n  };\n"]}

package/dist/context-store.js

@@ -1,16 +1,55 @@
 // SPDX-FileCopyrightText: 2026 lambda-deadline-middleware contributors
 // SPDX-License-Identifier: MIT
 import { AsyncLocalStorage } from "node:async_hooks";
+import { DeadlineExceededError } from "./error.js";
 const contextStorage = new AsyncLocalStorage();
-export const run = (context, fn) => {
-	if (context === null || context === undefined) return fn();
-	return contextStorage.run(context, fn);
+/**
+* Store an external AbortSignal for the current invocation.
+* When set, the SDK middleware uses this signal directly instead of
+* the auto-computed deadline signal.
+*
+* Call this at the start of your handler, before any SDK calls.
+* The signal is scoped to the current async context (AsyncLocalStorage).
+*/
+export const setDeadlineSignal = (signal) => {
+	const store = contextStorage.getStore();
+	if (store === undefined) {
+		throw new Error("setDeadlineSignal() must be called within a withLambdaDeadline() scope");
+	}
+	store.signal = signal;
 };
-export const getRemainingTimeInMillis = () => {
+/**
+* Retrieve the deadline signal for the current invocation, if one exists.
+*/
+export const getDeadlineSignal = () => {
 	const store = contextStorage.getStore();
 	if (store === undefined) return undefined;
-	if (typeof store.getRemainingTimeInMillis !== "function") return undefined;
-	return store.getRemainingTimeInMillis();
+	return store.signal;
+};
+export const withLambdaDeadline = (handler, options) => async (event, context) => {
+	const store = {};
+	// Compute the auto-deadline signal once, up front.
+	// If the user calls setDeadlineSignal() later, it overwrites this.
+	// oxlint-disable-next-line typescript/no-unnecessary-condition -- runtime safety: context may be null/undefined despite types (e.g. untyped callers)
+	if (context !== null && context !== undefined) {
+		const remaining = typeof context.getRemainingTimeInMillis === "function" ? context.getRemainingTimeInMillis() : undefined;
+		if (remaining !== undefined) {
+			const rawBuffer = options?.flushBufferMs ?? 1e3;
+			if (rawBuffer < 0) {
+				throw new TypeError(`flushBufferMs option must be non-negative, received: ${rawBuffer}`);
+			}
+			const deadline = remaining - rawBuffer;
+			if (deadline <= 0) {
+				throw new DeadlineExceededError({
+					deadlineMs: 0,
+					flushBufferMs: rawBuffer,
+					remainingMs: remaining
+				});
+			}
+			store.signal = AbortSignal.timeout(deadline);
+		}
+	}
+	return contextStorage.run(store, async () => handler(event, context));
 };
 
 //# sourceMappingURL=context-store.js.map

package/dist/context-store.js.map

@@ -1 +1 @@
-{"mappings":";;AAGA,SAAS,yBAAyB;AAQlC,MAAM,iBAAiB,IAAI,kBAAqC;AAEhE,OAAO,MAAM,OAAU,SAA+C,OAAmB;CACvF,IAAI,YAAY,QAAQ,YAAY,WAAW,OAAO,GAAG;CACzD,OAAO,eAAe,IAAI,SAAS,EAAE;AACvC;AAEA,OAAO,MAAM,iCAAqD;CAChE,MAAM,QAAQ,eAAe,SAAS;CACtC,IAAI,UAAU,WAAW,OAAO;CAChC,IAAI,OAAO,MAAM,6BAA6B,YAAY,OAAO;CACjE,OAAO,MAAM,yBAAyB;AACxC","names":[],"sources":["src/context-store.ts"],"version":3,"sourcesContent":["// SPDX-FileCopyrightText: 2026 lambda-deadline-middleware contributors\n// SPDX-License-Identifier: MIT\n\nimport { AsyncLocalStorage } from \"node:async_hooks\";\n\n// AsyncLocalStorage propagates the Lambda context through the entire async call chain without parameter threading.\n// SDK middleware executes deep in the Smithy stack where we can't pass the context through function signatures.\nexport interface LambdaContextLike {\n  getRemainingTimeInMillis?: () => number;\n}\n\nconst contextStorage = new AsyncLocalStorage<LambdaContextLike>();\n\nexport const run = <T>(context: LambdaContextLike | null | undefined, fn: () => T): T => {\n  if (context === null || context === undefined) return fn();\n  return contextStorage.run(context, fn);\n};\n\nexport const getRemainingTimeInMillis = (): number | undefined => {\n  const store = contextStorage.getStore();\n  if (store === undefined) return undefined;\n  if (typeof store.getRemainingTimeInMillis !== \"function\") return undefined;\n  return store.getRemainingTimeInMillis();\n};\n"]}
+{"mappings":";;AAGA,SAAS,yBAAyB;AAElC,SAAS,6BAA6B;AActC,MAAM,iBAAiB,IAAI,kBAAiC;;;;;;;;;AAU5D,OAAO,MAAM,qBAAqB,WAA8B;CAC9D,MAAM,QAAQ,eAAe,SAAS;CACtC,IAAI,UAAU,WAAW;EACvB,MAAM,IAAI,MAAM,wEAAwE;CAC1F;CACA,MAAM,SAAS;AACjB;;;;AAKA,OAAO,MAAM,0BAAmD;CAC9D,MAAM,QAAQ,eAAe,SAAS;CACtC,IAAI,UAAU,WAAW,OAAO;CAChC,OAAO,MAAM;AACf;AAQA,OAAO,MAAM,sBAET,SACA,YAEF,OAAO,OAAe,YAAwC;CAC5D,MAAM,QAAuB,CAAC;;;;CAK9B,IAAI,YAAY,QAAQ,YAAY,WAAW;EAC7C,MAAM,YACJ,OAAO,QAAQ,6BAA6B,aACxC,QAAQ,yBAAyB,IACjC;EAEN,IAAI,cAAc,WAAW;GAC3B,MAAM,YAAY,SAAS,iBAAiB;GAC5C,IAAI,YAAY,GAAG;IACjB,MAAM,IAAI,UAAU,wDAAwD,WAAW;GACzF;GACA,MAAM,WAAW,YAAY;GAE7B,IAAI,YAAY,GAAG;IACjB,MAAM,IAAI,sBAAsB;KAC9B,YAAY;KACZ,eAAe;KACf,aAAa;IACf,CAAC;GACH;GAEA,MAAM,SAAS,YAAY,QAAQ,QAAQ;EAC7C;CACF;CAEA,OAAO,eAAe,IAAI,OAAO,YAAY,QAAQ,OAAO,OAAO,CAAC;AACtE","names":[],"sources":["src/context-store.ts"],"version":3,"sourcesContent":["// SPDX-FileCopyrightText: 2026 lambda-deadline-middleware contributors\n// SPDX-License-Identifier: MIT\n\nimport { AsyncLocalStorage } from \"node:async_hooks\";\n\nimport { DeadlineExceededError } from \"./error.js\";\n\nimport type { DeadlineOptions } from \"./types.js\";\n\n// AsyncLocalStorage propagates the deadline signal through the entire async call chain.\n// SDK middleware executes deep in the Smithy stack where we can't pass it through function signatures.\nexport interface LambdaContextLike {\n  getRemainingTimeInMillis?: () => number;\n}\n\ninterface DeadlineStore {\n  signal?: AbortSignal;\n}\n\nconst contextStorage = new AsyncLocalStorage<DeadlineStore>();\n\n/**\n * Store an external AbortSignal for the current invocation.\n * When set, the SDK middleware uses this signal directly instead of\n * the auto-computed deadline signal.\n *\n * Call this at the start of your handler, before any SDK calls.\n * The signal is scoped to the current async context (AsyncLocalStorage).\n */\nexport const setDeadlineSignal = (signal: AbortSignal): void => {\n  const store = contextStorage.getStore();\n  if (store === undefined) {\n    throw new Error(\"setDeadlineSignal() must be called within a withLambdaDeadline() scope\");\n  }\n  store.signal = signal;\n};\n\n/**\n * Retrieve the deadline signal for the current invocation, if one exists.\n */\nexport const getDeadlineSignal = (): AbortSignal | undefined => {\n  const store = contextStorage.getStore();\n  if (store === undefined) return undefined;\n  return store.signal;\n};\n\n// Handler wrapper — computes the deadline signal once at invocation start and stores it via AsyncLocalStorage.\ntype AsyncHandler<TEvent, TContext extends LambdaContextLike, TResult> = (\n  event: TEvent,\n  context: TContext,\n) => Promise<TResult>;\n\nexport const withLambdaDeadline =\n  <TEvent, TContext extends LambdaContextLike, TResult>(\n    handler: AsyncHandler<TEvent, TContext, TResult>,\n    options?: DeadlineOptions,\n  ): AsyncHandler<TEvent, TContext, TResult> =>\n  async (event: TEvent, context: TContext): Promise<TResult> => {\n    const store: DeadlineStore = {};\n\n    // Compute the auto-deadline signal once, up front.\n    // If the user calls setDeadlineSignal() later, it overwrites this.\n    // oxlint-disable-next-line typescript/no-unnecessary-condition -- runtime safety: context may be null/undefined despite types (e.g. untyped callers)\n    if (context !== null && context !== undefined) {\n      const remaining =\n        typeof context.getRemainingTimeInMillis === \"function\"\n          ? context.getRemainingTimeInMillis()\n          : undefined;\n\n      if (remaining !== undefined) {\n        const rawBuffer = options?.flushBufferMs ?? 1000;\n        if (rawBuffer < 0) {\n          throw new TypeError(`flushBufferMs option must be non-negative, received: ${rawBuffer}`);\n        }\n        const deadline = remaining - rawBuffer;\n\n        if (deadline <= 0) {\n          throw new DeadlineExceededError({\n            deadlineMs: 0,\n            flushBufferMs: rawBuffer,\n            remainingMs: remaining,\n          });\n        }\n\n        store.signal = AbortSignal.timeout(deadline);\n      }\n    }\n\n    return contextStorage.run(store, async () => handler(event, context));\n  };\n"]}

package/dist/error.d.ts

@@ -1,14 +1,13 @@
-import type { Milliseconds } from "./types.js";
 interface DeadlineExceededInit {
-	readonly deadlineMs: Milliseconds;
-	readonly flushBufferMs: Milliseconds;
-	readonly remainingMs: Milliseconds;
+	readonly deadlineMs: number;
+	readonly flushBufferMs: number;
+	readonly remainingMs: number;
 }
 export declare class DeadlineExceededError extends Error {
 	override readonly name = "DeadlineExceededError";
-	readonly deadlineMs: Milliseconds;
-	readonly flushBufferMs: Milliseconds;
-	readonly remainingMs: Milliseconds;
+	readonly deadlineMs: number;
+	readonly flushBufferMs: number;
+	readonly remainingMs: number;
 	constructor(init: DeadlineExceededInit);
 }
 export declare const isDeadlineExceeded: (error: unknown) => error is DeadlineExceededError;

package/dist/error.d.ts.map

@@ -1 +1 @@
-{"mappings":"AAGA,cAAc,oBAAoB;UAExB,qBAAqB;UACpB,YAAY;UACZ,eAAe;UACf,aAAa;AACxB;AAEA,OAAO,cAAM,8BAA8B,MAAM;CAC/C,kBAAkB,OAAO;CACzB,SAAS,YAAY;CACrB,SAAS,eAAe;CACxB,SAAS,aAAa;CAEtB,YAAY,MAAM;AAQpB;AAIA,OAAO,cAAM,qBAAsB,mBAAiB,SAAS","names":[],"sources":["src/error.ts"],"version":3,"sourcesContent":["// SPDX-FileCopyrightText: 2026 lambda-deadline-middleware contributors\n// SPDX-License-Identifier: MIT\n\nimport type { Milliseconds } from \"./types.js\";\n\ninterface DeadlineExceededInit {\n  readonly deadlineMs: Milliseconds;\n  readonly flushBufferMs: Milliseconds;\n  readonly remainingMs: Milliseconds;\n}\n\nexport class DeadlineExceededError extends Error {\n  override readonly name = \"DeadlineExceededError\" as const;\n  readonly deadlineMs: Milliseconds;\n  readonly flushBufferMs: Milliseconds;\n  readonly remainingMs: Milliseconds;\n\n  constructor(init: DeadlineExceededInit) {\n    super(\n      `Request deadline exceeded: ${init.deadlineMs}ms deadline (${init.flushBufferMs}ms flush buffer)`,\n    );\n    this.deadlineMs = init.deadlineMs;\n    this.flushBufferMs = init.flushBufferMs;\n    this.remainingMs = init.remainingMs;\n  }\n}\n\n// Structural check rather than instanceof — works across module boundaries\n// and serialization boundaries where prototype chain may be broken.\nexport const isDeadlineExceeded = (error: unknown): error is DeadlineExceededError => {\n  if (error === null || error === undefined) return false;\n  if (typeof error !== \"object\") return false;\n  return (error as { name?: unknown }).name === \"DeadlineExceededError\";\n};\n"]}
+{"mappings":"UAGU,qBAAqB;UACpB;UACA;UACA;AACX;AAEA,OAAO,cAAM,8BAA8B,MAAM;CAC/C,kBAAkB,OAAO;CACzB,SAAS;CACT,SAAS;CACT,SAAS;CAET,YAAY,MAAM;AAQpB;AAIA,OAAO,cAAM,qBAAsB,mBAAiB,SAAS","names":[],"sources":["src/error.ts"],"version":3,"sourcesContent":["// SPDX-FileCopyrightText: 2026 lambda-deadline-middleware contributors\n// SPDX-License-Identifier: MIT\n\ninterface DeadlineExceededInit {\n  readonly deadlineMs: number;\n  readonly flushBufferMs: number;\n  readonly remainingMs: number;\n}\n\nexport class DeadlineExceededError extends Error {\n  override readonly name = \"DeadlineExceededError\" as const;\n  readonly deadlineMs: number;\n  readonly flushBufferMs: number;\n  readonly remainingMs: number;\n\n  constructor(init: DeadlineExceededInit) {\n    super(\n      `Request deadline exceeded: ${init.deadlineMs}ms deadline (${init.flushBufferMs}ms flush buffer)`,\n    );\n    this.deadlineMs = init.deadlineMs;\n    this.flushBufferMs = init.flushBufferMs;\n    this.remainingMs = init.remainingMs;\n  }\n}\n\n// Structural check rather than instanceof — works across module boundaries\n// and serialization boundaries where prototype chain may be broken.\nexport const isDeadlineExceeded = (error: unknown): error is DeadlineExceededError => {\n  if (error === null || error === undefined) return false;\n  if (typeof error !== \"object\") return false;\n  return (error as { name?: unknown }).name === \"DeadlineExceededError\";\n};\n"]}

package/dist/error.js.map

@@ -1 +1 @@
-{"mappings":"AAWA,OAAO,MAAM,8BAA8B,MAAM;CAC/C,AAAkB,OAAO;CACzB,AAAS;CACT,AAAS;CACT,AAAS;CAET,YAAY,MAA4B;EACtC,MACE,8BAA8B,KAAK,WAAW,eAAe,KAAK,cAAc,iBAClF;EACA,KAAK,aAAa,KAAK;EACvB,KAAK,gBAAgB,KAAK;EAC1B,KAAK,cAAc,KAAK;CAC1B;AACF;;;AAIA,OAAO,MAAM,sBAAsB,UAAmD;CACpF,IAAI,UAAU,QAAQ,UAAU,WAAW,OAAO;CAClD,IAAI,OAAO,UAAU,UAAU,OAAO;CACtC,OAAQ,MAA6B,SAAS;AAChD","names":[],"sources":["src/error.ts"],"version":3,"sourcesContent":["// SPDX-FileCopyrightText: 2026 lambda-deadline-middleware contributors\n// SPDX-License-Identifier: MIT\n\nimport type { Milliseconds } from \"./types.js\";\n\ninterface DeadlineExceededInit {\n  readonly deadlineMs: Milliseconds;\n  readonly flushBufferMs: Milliseconds;\n  readonly remainingMs: Milliseconds;\n}\n\nexport class DeadlineExceededError extends Error {\n  override readonly name = \"DeadlineExceededError\" as const;\n  readonly deadlineMs: Milliseconds;\n  readonly flushBufferMs: Milliseconds;\n  readonly remainingMs: Milliseconds;\n\n  constructor(init: DeadlineExceededInit) {\n    super(\n      `Request deadline exceeded: ${init.deadlineMs}ms deadline (${init.flushBufferMs}ms flush buffer)`,\n    );\n    this.deadlineMs = init.deadlineMs;\n    this.flushBufferMs = init.flushBufferMs;\n    this.remainingMs = init.remainingMs;\n  }\n}\n\n// Structural check rather than instanceof — works across module boundaries\n// and serialization boundaries where prototype chain may be broken.\nexport const isDeadlineExceeded = (error: unknown): error is DeadlineExceededError => {\n  if (error === null || error === undefined) return false;\n  if (typeof error !== \"object\") return false;\n  return (error as { name?: unknown }).name === \"DeadlineExceededError\";\n};\n"]}
+{"mappings":"AASA,OAAO,MAAM,8BAA8B,MAAM;CAC/C,AAAkB,OAAO;CACzB,AAAS;CACT,AAAS;CACT,AAAS;CAET,YAAY,MAA4B;EACtC,MACE,8BAA8B,KAAK,WAAW,eAAe,KAAK,cAAc,iBAClF;EACA,KAAK,aAAa,KAAK;EACvB,KAAK,gBAAgB,KAAK;EAC1B,KAAK,cAAc,KAAK;CAC1B;AACF;;;AAIA,OAAO,MAAM,sBAAsB,UAAmD;CACpF,IAAI,UAAU,QAAQ,UAAU,WAAW,OAAO;CAClD,IAAI,OAAO,UAAU,UAAU,OAAO;CACtC,OAAQ,MAA6B,SAAS;AAChD","names":[],"sources":["src/error.ts"],"version":3,"sourcesContent":["// SPDX-FileCopyrightText: 2026 lambda-deadline-middleware contributors\n// SPDX-License-Identifier: MIT\n\ninterface DeadlineExceededInit {\n  readonly deadlineMs: number;\n  readonly flushBufferMs: number;\n  readonly remainingMs: number;\n}\n\nexport class DeadlineExceededError extends Error {\n  override readonly name = \"DeadlineExceededError\" as const;\n  readonly deadlineMs: number;\n  readonly flushBufferMs: number;\n  readonly remainingMs: number;\n\n  constructor(init: DeadlineExceededInit) {\n    super(\n      `Request deadline exceeded: ${init.deadlineMs}ms deadline (${init.flushBufferMs}ms flush buffer)`,\n    );\n    this.deadlineMs = init.deadlineMs;\n    this.flushBufferMs = init.flushBufferMs;\n    this.remainingMs = init.remainingMs;\n  }\n}\n\n// Structural check rather than instanceof — works across module boundaries\n// and serialization boundaries where prototype chain may be broken.\nexport const isDeadlineExceeded = (error: unknown): error is DeadlineExceededError => {\n  if (error === null || error === undefined) return false;\n  if (typeof error !== \"object\") return false;\n  return (error as { name?: unknown }).name === \"DeadlineExceededError\";\n};\n"]}

package/dist/index.d.ts

@@ -1,8 +1,7 @@
-export { withLambdaDeadline } from "./handler-wrapper.js";
+export { withLambdaDeadline, setDeadlineSignal } from "./context-store.js";
 export { deadlineMiddleware } from "./middleware.js";
 export { DeadlineExceededError, isDeadlineExceeded } from "./error.js";
-export { getRemainingTimeInMillis } from "./context-store.js";
-export type { Milliseconds, DeadlineOptions } from "./types.js";
+export type { DeadlineOptions } from "./types.js";
 export type { LambdaContextLike } from "./context-store.js";
 
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"mappings":"AAGA,SAAS,0BAA0B;AACnC,SAAS,0BAA0B;AACnC,SAAS,uBAAuB,0BAA0B;AAC1D,SAAS,gCAAgC;AAEzC,cAAc,cAAc,uBAAuB;AAEnD,cAAc,yBAAyB","names":[],"sources":["src/index.ts"],"version":3,"sourcesContent":["// SPDX-FileCopyrightText: 2026 lambda-deadline-middleware contributors\n// SPDX-License-Identifier: MIT\n\nexport { withLambdaDeadline } from \"./handler-wrapper.js\";\nexport { deadlineMiddleware } from \"./middleware.js\";\nexport { DeadlineExceededError, isDeadlineExceeded } from \"./error.js\";\nexport { getRemainingTimeInMillis } from \"./context-store.js\";\n\nexport type { Milliseconds, DeadlineOptions } from \"./types.js\";\n\nexport type { LambdaContextLike } from \"./context-store.js\";\n"]}
+{"mappings":"AAGA,SAAS,oBAAoB,yBAAyB;AACtD,SAAS,0BAA0B;AACnC,SAAS,uBAAuB,0BAA0B;AAE1D,cAAc,uBAAuB;AACrC,cAAc,yBAAyB","names":[],"sources":["src/index.ts"],"version":3,"sourcesContent":["// SPDX-FileCopyrightText: 2026 lambda-deadline-middleware contributors\n// SPDX-License-Identifier: MIT\n\nexport { withLambdaDeadline, setDeadlineSignal } from \"./context-store.js\";\nexport { deadlineMiddleware } from \"./middleware.js\";\nexport { DeadlineExceededError, isDeadlineExceeded } from \"./error.js\";\n\nexport type { DeadlineOptions } from \"./types.js\";\nexport type { LambdaContextLike } from \"./context-store.js\";\n"]}

package/dist/index.js

@@ -1,8 +1,7 @@
 // SPDX-FileCopyrightText: 2026 lambda-deadline-middleware contributors
 // SPDX-License-Identifier: MIT
-export { withLambdaDeadline } from "./handler-wrapper.js";
+export { withLambdaDeadline, setDeadlineSignal } from "./context-store.js";
 export { deadlineMiddleware } from "./middleware.js";
 export { DeadlineExceededError, isDeadlineExceeded } from "./error.js";
-export { getRemainingTimeInMillis } from "./context-store.js";
 
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"mappings":";;AAGA,SAAS,0BAA0B;AACnC,SAAS,0BAA0B;AACnC,SAAS,uBAAuB,0BAA0B;AAC1D,SAAS,gCAAgC","names":[],"sources":["src/index.ts"],"version":3,"sourcesContent":["// SPDX-FileCopyrightText: 2026 lambda-deadline-middleware contributors\n// SPDX-License-Identifier: MIT\n\nexport { withLambdaDeadline } from \"./handler-wrapper.js\";\nexport { deadlineMiddleware } from \"./middleware.js\";\nexport { DeadlineExceededError, isDeadlineExceeded } from \"./error.js\";\nexport { getRemainingTimeInMillis } from \"./context-store.js\";\n\nexport type { Milliseconds, DeadlineOptions } from \"./types.js\";\n\nexport type { LambdaContextLike } from \"./context-store.js\";\n"]}
+{"mappings":";;AAGA,SAAS,oBAAoB,yBAAyB;AACtD,SAAS,0BAA0B;AACnC,SAAS,uBAAuB,0BAA0B","names":[],"sources":["src/index.ts"],"version":3,"sourcesContent":["// SPDX-FileCopyrightText: 2026 lambda-deadline-middleware contributors\n// SPDX-License-Identifier: MIT\n\nexport { withLambdaDeadline, setDeadlineSignal } from \"./context-store.js\";\nexport { deadlineMiddleware } from \"./middleware.js\";\nexport { DeadlineExceededError, isDeadlineExceeded } from \"./error.js\";\n\nexport type { DeadlineOptions } from \"./types.js\";\nexport type { LambdaContextLike } from \"./context-store.js\";\n"]}

package/dist/middleware.d.ts

@@ -1,9 +1,7 @@
 import type { Pluggable } from "@smithy/types";
-import type { DeadlineOptions } from "./types.js";
-export declare const composeSignals: (existing: AbortSignal | undefined, deadline: AbortSignal) => AbortSignal;
 export declare const deadlineMiddleware: <
 	Input extends object,
 	Output extends object
->(options?: DeadlineOptions) => Pluggable<Input, Output>;
+>() => Pluggable<Input, Output>;
 
 //# sourceMappingURL=middleware.d.ts.map

package/dist/middleware.d.ts.map

@@ -1 +1 @@
-{"mappings":"AAGA,cAKE,iBACK;AAMP,cAAc,uBAAuB;AAErC,OAAO,cAAM,iBACX,UAAU,yBACV,UAAU,gBACT;AAKH,OAAO,cAAM;CAAsB;CAAsB;EACvD,UAAU,oBACT,UAAU,OAAO","names":[],"sources":["src/middleware.ts"],"version":3,"sourcesContent":["// SPDX-FileCopyrightText: 2026 lambda-deadline-middleware contributors\n// SPDX-License-Identifier: MIT\n\nimport type {\n  FinalizeHandler,\n  FinalizeHandlerArguments,\n  FinalizeHandlerOutput,\n  HandlerExecutionContext,\n  Pluggable,\n} from \"@smithy/types\";\n\nimport { getRemainingTimeInMillis } from \"./context-store.js\";\nimport { DeadlineExceededError } from \"./error.js\";\nimport { milliseconds } from \"./types.js\";\n\nimport type { DeadlineOptions } from \"./types.js\";\n\nexport const composeSignals = (\n  existing: AbortSignal | undefined,\n  deadline: AbortSignal,\n): AbortSignal => {\n  if (existing === undefined) return deadline;\n  return AbortSignal.any([existing, deadline]);\n};\n\nexport const deadlineMiddleware = <Input extends object, Output extends object>(\n  options?: DeadlineOptions,\n): Pluggable<Input, Output> => {\n  const raw = options?.flushBufferMs ?? 1000;\n  if (raw < 0) {\n    throw new TypeError(`flushBufferMs option must be non-negative, received: ${raw}`);\n  }\n  const flushBufferMs = milliseconds(raw);\n\n  return {\n    applyToStack(stack) {\n      // Registered at \"finalizeRequest\" (attempt level) rather than API-call level so each retry gets a deadline\n      // computed from the actual remaining time at that moment. API-call level would cache a stale deadline\n      // across retries, which grow more dangerous after backoff delays eat into remaining time.\n      stack.add(\n        (\n          next: FinalizeHandler<Input, Output>,\n          _context: HandlerExecutionContext,\n        ): FinalizeHandler<Input, Output> =>\n          async (args: FinalizeHandlerArguments<Input>): Promise<FinalizeHandlerOutput<Output>> => {\n            const remaining = getRemainingTimeInMillis();\n            if (remaining === undefined) return next(args);\n\n            const deadline = remaining - flushBufferMs;\n\n            if (deadline <= 0) {\n              throw new DeadlineExceededError({\n                deadlineMs: milliseconds(0),\n                flushBufferMs,\n                remainingMs: milliseconds(remaining),\n              });\n            }\n\n            const controller = new AbortController();\n            const timeoutId = setTimeout(() => {\n              controller.abort(\n                new DeadlineExceededError({\n                  deadlineMs: milliseconds(deadline),\n                  flushBufferMs,\n                  remainingMs: milliseconds(remaining),\n                }),\n              );\n            }, deadline);\n\n            // `using` guarantees cleanup (clearTimeout) even if next() throws, the promise rejects,\n            // or an external abort signal fires — strictly more reliable than try/finally.\n            using _timer = {\n              [Symbol.dispose]() {\n                clearTimeout(timeoutId);\n              },\n            };\n\n            // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- Smithy request is an opaque object; we access optional signal property\n            const request = args.request as { signal?: AbortSignal } | undefined;\n            const signal = composeSignals(request?.signal, controller.signal);\n            const result = await next({\n              ...args,\n              // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- spreading opaque Smithy request to add signal\n              request: { ...(args.request as object), signal },\n            });\n            return result;\n          },\n        {\n          step: \"finalizeRequest\",\n          name: \"deadlineMiddleware\",\n          override: true,\n        },\n      );\n    },\n  };\n};\n"]}
+{"mappings":"AAGA,cAKE,iBACK;AAIP,OAAO,cAAM;CAAsB;CAAsB;OAA0B,UACjF,OACA","names":[],"sources":["src/middleware.ts"],"version":3,"sourcesContent":["// SPDX-FileCopyrightText: 2026 lambda-deadline-middleware contributors\n// SPDX-License-Identifier: MIT\n\nimport type {\n  FinalizeHandler,\n  FinalizeHandlerArguments,\n  FinalizeHandlerOutput,\n  HandlerExecutionContext,\n  Pluggable,\n} from \"@smithy/types\";\n\nimport { getDeadlineSignal } from \"./context-store.js\";\n\nexport const deadlineMiddleware = <Input extends object, Output extends object>(): Pluggable<\n  Input,\n  Output\n> => ({\n  applyToStack(stack) {\n    stack.add(\n      (\n        next: FinalizeHandler<Input, Output>,\n        _context: HandlerExecutionContext,\n      ): FinalizeHandler<Input, Output> =>\n        async (args: FinalizeHandlerArguments<Input>): Promise<FinalizeHandlerOutput<Output>> => {\n          const deadlineSignal = getDeadlineSignal();\n          if (deadlineSignal === undefined) return next(args);\n\n          // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- Smithy request is an opaque object\n          const request = args.request as { signal?: AbortSignal } | undefined;\n          const existing = request?.signal;\n          const signal = existing ? AbortSignal.any([existing, deadlineSignal]) : deadlineSignal;\n\n          return next({\n            ...args,\n            // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- spreading opaque Smithy request to add signal\n            request: { ...(args.request as object), signal },\n          });\n        },\n      {\n        step: \"finalizeRequest\",\n        name: \"deadlineMiddleware\",\n        override: true,\n      },\n    );\n  },\n});\n"]}

package/dist/middleware.js

@@ -1,62 +1,25 @@
-import { getRemainingTimeInMillis } from "./context-store.js";
-import { DeadlineExceededError } from "./error.js";
-import { milliseconds } from "./types.js";
-export const composeSignals = (existing, deadline) => {
-	if (existing === undefined) return deadline;
-	return AbortSignal.any([existing, deadline]);
-};
-export const deadlineMiddleware = (options) => {
-	const raw = options?.flushBufferMs ?? 1e3;
-	if (raw < 0) {
-		throw new TypeError(`flushBufferMs option must be non-negative, received: ${raw}`);
-	}
-	const flushBufferMs = milliseconds(raw);
-	return { applyToStack(stack) {
-		// Registered at "finalizeRequest" (attempt level) rather than API-call level so each retry gets a deadline
-		// computed from the actual remaining time at that moment. API-call level would cache a stale deadline
-		// across retries, which grow more dangerous after backoff delays eat into remaining time.
-		stack.add((next, _context) => async (args) => {
-			const remaining = getRemainingTimeInMillis();
-			if (remaining === undefined) return next(args);
-			const deadline = remaining - flushBufferMs;
-			if (deadline <= 0) {
-				throw new DeadlineExceededError({
-					deadlineMs: milliseconds(0),
-					flushBufferMs,
-					remainingMs: milliseconds(remaining)
-				});
+import { getDeadlineSignal } from "./context-store.js";
+export const deadlineMiddleware = () => ({ applyToStack(stack) {
+	stack.add((next, _context) => async (args) => {
+		const deadlineSignal = getDeadlineSignal();
+		if (deadlineSignal === undefined) return next(args);
+		// oxlint-disable-next-line typescript/no-unsafe-type-assertion -- Smithy request is an opaque object
+		const request = args.request;
+		const existing = request?.signal;
+		const signal = existing ? AbortSignal.any([existing, deadlineSignal]) : deadlineSignal;
+		return next({
+			...args,
+			// oxlint-disable-next-line typescript/no-unsafe-type-assertion -- spreading opaque Smithy request to add signal
+			request: {
+				...args.request,
+				signal
 			}
-			const controller = new AbortController();
-			const timeoutId = setTimeout(() => {
-				controller.abort(new DeadlineExceededError({
-					deadlineMs: milliseconds(deadline),
-					flushBufferMs,
-					remainingMs: milliseconds(remaining)
-				}));
-			}, deadline);
-			// `using` guarantees cleanup (clearTimeout) even if next() throws, the promise rejects,
-			// or an external abort signal fires — strictly more reliable than try/finally.
-			using _timer = { [Symbol.dispose]() {
-				clearTimeout(timeoutId);
-			} };
-			// oxlint-disable-next-line typescript/no-unsafe-type-assertion -- Smithy request is an opaque object; we access optional signal property
-			const request = args.request;
-			const signal = composeSignals(request?.signal, controller.signal);
-			const result = await next({
-				...args,
-				// oxlint-disable-next-line typescript/no-unsafe-type-assertion -- spreading opaque Smithy request to add signal
-				request: {
-					...args.request,
-					signal
-				}
-			});
-			return result;
-		}, {
-			step: "finalizeRequest",
-			name: "deadlineMiddleware",
-			override: true
 		});
-	} };
-};
+	}, {
+		step: "finalizeRequest",
+		name: "deadlineMiddleware",
+		override: true
+	});
+} });
 
 //# sourceMappingURL=middleware.js.map

package/dist/middleware.js.map

@@ -1 +1 @@
-{"mappings":"AAWA,SAAS,gCAAgC;AACzC,SAAS,6BAA6B;AACtC,SAAS,oBAAoB;AAI7B,OAAO,MAAM,kBACX,UACA,aACgB;CAChB,IAAI,aAAa,WAAW,OAAO;CACnC,OAAO,YAAY,IAAI,CAAC,UAAU,QAAQ,CAAC;AAC7C;AAEA,OAAO,MAAM,sBACX,YAC6B;CAC7B,MAAM,MAAM,SAAS,iBAAiB;CACtC,IAAI,MAAM,GAAG;EACX,MAAM,IAAI,UAAU,wDAAwD,KAAK;CACnF;CACA,MAAM,gBAAgB,aAAa,GAAG;CAEtC,OAAO,EACL,aAAa,OAAO;;;;EAIlB,MAAM,KAEF,MACA,aAEA,OAAO,SAAkF;GACvF,MAAM,YAAY,yBAAyB;GAC3C,IAAI,cAAc,WAAW,OAAO,KAAK,IAAI;GAE7C,MAAM,WAAW,YAAY;GAE7B,IAAI,YAAY,GAAG;IACjB,MAAM,IAAI,sBAAsB;KAC9B,YAAY,aAAa,CAAC;KAC1B;KACA,aAAa,aAAa,SAAS;IACrC,CAAC;GACH;GAEA,MAAM,aAAa,IAAI,gBAAgB;GACvC,MAAM,YAAY,iBAAiB;IACjC,WAAW,MACT,IAAI,sBAAsB;KACxB,YAAY,aAAa,QAAQ;KACjC;KACA,aAAa,aAAa,SAAS;IACrC,CAAC,CACH;GACF,GAAG,QAAQ;;;GAIX,MAAM,SAAS,EACb,CAAC,OAAO,WAAW;IACjB,aAAa,SAAS;GACxB,EACF;;GAGA,MAAM,UAAU,KAAK;GACrB,MAAM,SAAS,eAAe,SAAS,QAAQ,WAAW,MAAM;GAChE,MAAM,SAAS,MAAM,KAAK;IACxB,GAAG;;IAEH,SAAS;KAAE,GAAI,KAAK;KAAoB;IAAO;GACjD,CAAC;GACD,OAAO;EACT,GACF;GACE,MAAM;GACN,MAAM;GACN,UAAU;EACZ,CACF;CACF,EACF;AACF","names":[],"sources":["src/middleware.ts"],"version":3,"sourcesContent":["// SPDX-FileCopyrightText: 2026 lambda-deadline-middleware contributors\n// SPDX-License-Identifier: MIT\n\nimport type {\n  FinalizeHandler,\n  FinalizeHandlerArguments,\n  FinalizeHandlerOutput,\n  HandlerExecutionContext,\n  Pluggable,\n} from \"@smithy/types\";\n\nimport { getRemainingTimeInMillis } from \"./context-store.js\";\nimport { DeadlineExceededError } from \"./error.js\";\nimport { milliseconds } from \"./types.js\";\n\nimport type { DeadlineOptions } from \"./types.js\";\n\nexport const composeSignals = (\n  existing: AbortSignal | undefined,\n  deadline: AbortSignal,\n): AbortSignal => {\n  if (existing === undefined) return deadline;\n  return AbortSignal.any([existing, deadline]);\n};\n\nexport const deadlineMiddleware = <Input extends object, Output extends object>(\n  options?: DeadlineOptions,\n): Pluggable<Input, Output> => {\n  const raw = options?.flushBufferMs ?? 1000;\n  if (raw < 0) {\n    throw new TypeError(`flushBufferMs option must be non-negative, received: ${raw}`);\n  }\n  const flushBufferMs = milliseconds(raw);\n\n  return {\n    applyToStack(stack) {\n      // Registered at \"finalizeRequest\" (attempt level) rather than API-call level so each retry gets a deadline\n      // computed from the actual remaining time at that moment. API-call level would cache a stale deadline\n      // across retries, which grow more dangerous after backoff delays eat into remaining time.\n      stack.add(\n        (\n          next: FinalizeHandler<Input, Output>,\n          _context: HandlerExecutionContext,\n        ): FinalizeHandler<Input, Output> =>\n          async (args: FinalizeHandlerArguments<Input>): Promise<FinalizeHandlerOutput<Output>> => {\n            const remaining = getRemainingTimeInMillis();\n            if (remaining === undefined) return next(args);\n\n            const deadline = remaining - flushBufferMs;\n\n            if (deadline <= 0) {\n              throw new DeadlineExceededError({\n                deadlineMs: milliseconds(0),\n                flushBufferMs,\n                remainingMs: milliseconds(remaining),\n              });\n            }\n\n            const controller = new AbortController();\n            const timeoutId = setTimeout(() => {\n              controller.abort(\n                new DeadlineExceededError({\n                  deadlineMs: milliseconds(deadline),\n                  flushBufferMs,\n                  remainingMs: milliseconds(remaining),\n                }),\n              );\n            }, deadline);\n\n            // `using` guarantees cleanup (clearTimeout) even if next() throws, the promise rejects,\n            // or an external abort signal fires — strictly more reliable than try/finally.\n            using _timer = {\n              [Symbol.dispose]() {\n                clearTimeout(timeoutId);\n              },\n            };\n\n            // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- Smithy request is an opaque object; we access optional signal property\n            const request = args.request as { signal?: AbortSignal } | undefined;\n            const signal = composeSignals(request?.signal, controller.signal);\n            const result = await next({\n              ...args,\n              // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- spreading opaque Smithy request to add signal\n              request: { ...(args.request as object), signal },\n            });\n            return result;\n          },\n        {\n          step: \"finalizeRequest\",\n          name: \"deadlineMiddleware\",\n          override: true,\n        },\n      );\n    },\n  };\n};\n"]}
+{"mappings":"AAWA,SAAS,yBAAyB;AAElC,OAAO,MAAM,4BAGP,EACJ,aAAa,OAAO;CAClB,MAAM,KAEF,MACA,aAEA,OAAO,SAAkF;EACvF,MAAM,iBAAiB,kBAAkB;EACzC,IAAI,mBAAmB,WAAW,OAAO,KAAK,IAAI;;EAGlD,MAAM,UAAU,KAAK;EACrB,MAAM,WAAW,SAAS;EAC1B,MAAM,SAAS,WAAW,YAAY,IAAI,CAAC,UAAU,cAAc,CAAC,IAAI;EAExE,OAAO,KAAK;GACV,GAAG;;GAEH,SAAS;IAAE,GAAI,KAAK;IAAoB;GAAO;EACjD,CAAC;CACH,GACF;EACE,MAAM;EACN,MAAM;EACN,UAAU;CACZ,CACF;AACF,EACF","names":[],"sources":["src/middleware.ts"],"version":3,"sourcesContent":["// SPDX-FileCopyrightText: 2026 lambda-deadline-middleware contributors\n// SPDX-License-Identifier: MIT\n\nimport type {\n  FinalizeHandler,\n  FinalizeHandlerArguments,\n  FinalizeHandlerOutput,\n  HandlerExecutionContext,\n  Pluggable,\n} from \"@smithy/types\";\n\nimport { getDeadlineSignal } from \"./context-store.js\";\n\nexport const deadlineMiddleware = <Input extends object, Output extends object>(): Pluggable<\n  Input,\n  Output\n> => ({\n  applyToStack(stack) {\n    stack.add(\n      (\n        next: FinalizeHandler<Input, Output>,\n        _context: HandlerExecutionContext,\n      ): FinalizeHandler<Input, Output> =>\n        async (args: FinalizeHandlerArguments<Input>): Promise<FinalizeHandlerOutput<Output>> => {\n          const deadlineSignal = getDeadlineSignal();\n          if (deadlineSignal === undefined) return next(args);\n\n          // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- Smithy request is an opaque object\n          const request = args.request as { signal?: AbortSignal } | undefined;\n          const existing = request?.signal;\n          const signal = existing ? AbortSignal.any([existing, deadlineSignal]) : deadlineSignal;\n\n          return next({\n            ...args,\n            // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- spreading opaque Smithy request to add signal\n            request: { ...(args.request as object), signal },\n          });\n        },\n      {\n        step: \"finalizeRequest\",\n        name: \"deadlineMiddleware\",\n        override: true,\n      },\n    );\n  },\n});\n"]}

package/dist/types.d.ts

@@ -1,15 +1,5 @@
-declare const BrandSymbol: unique symbol;
-type Brand<
-	T,
-	B extends string
-> = T & {
-	readonly [BrandSymbol]: B;
-};
-export type Milliseconds = Brand<number, "Milliseconds">;
-export declare const milliseconds: (value: number) => Milliseconds;
 export interface DeadlineOptions {
 	readonly flushBufferMs?: number;
 }
-export {};
 
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"mappings":"AAKA,cAAc;KAET;CAAM;CAAG;IAAoB,IAAI;WAAY,cAAc;AAAE;AAElE,YAAY,eAAe,cAAc;AAEzC,OAAO,cAAM,eAAgB,kBAAgB;AAQ7C,iBAAiB,gBAAgB;UACtB;AACX","names":[],"sources":["src/types.ts"],"version":3,"sourcesContent":["// SPDX-FileCopyrightText: 2026 lambda-deadline-middleware contributors\n// SPDX-License-Identifier: MIT\n\n// Branded type prevents interchange errors at compile time (e.g. passing seconds where milliseconds are expected).\n// Zero runtime cost. Smart constructor below validates at the boundary and brands the value.\ndeclare const BrandSymbol: unique symbol;\n\ntype Brand<T, B extends string> = T & { readonly [BrandSymbol]: B };\n\nexport type Milliseconds = Brand<number, \"Milliseconds\">;\n\nexport const milliseconds = (value: number): Milliseconds => {\n  if (!Number.isFinite(value)) {\n    throw new TypeError(`milliseconds value must be finite, received: ${value}`);\n  }\n  // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- branded type constructor: value is validated above\n  return value as Milliseconds;\n};\n\nexport interface DeadlineOptions {\n  readonly flushBufferMs?: number;\n}\n"]}
+{"mappings":"AAGA,iBAAiB,gBAAgB;UACtB;AACX","names":[],"sources":["src/types.ts"],"version":3,"sourcesContent":["// SPDX-FileCopyrightText: 2026 lambda-deadline-middleware contributors\n// SPDX-License-Identifier: MIT\n\nexport interface DeadlineOptions {\n  readonly flushBufferMs?: number;\n}\n"]}

package/dist/types.js

@@ -1,9 +1,3 @@
-export const milliseconds = (value) => {
-	if (!Number.isFinite(value)) {
-		throw new TypeError(`milliseconds value must be finite, received: ${value}`);
-	}
-	// oxlint-disable-next-line typescript/no-unsafe-type-assertion -- branded type constructor: value is validated above
-	return value;
-};
+export {};
 
 //# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -1 +1 @@
-{"mappings":"AAWA,OAAO,MAAM,gBAAgB,UAAgC;CAC3D,IAAI,CAAC,OAAO,SAAS,KAAK,GAAG;EAC3B,MAAM,IAAI,UAAU,gDAAgD,OAAO;CAC7E;;CAEA,OAAO;AACT","names":[],"sources":["src/types.ts"],"version":3,"sourcesContent":["// SPDX-FileCopyrightText: 2026 lambda-deadline-middleware contributors\n// SPDX-License-Identifier: MIT\n\n// Branded type prevents interchange errors at compile time (e.g. passing seconds where milliseconds are expected).\n// Zero runtime cost. Smart constructor below validates at the boundary and brands the value.\ndeclare const BrandSymbol: unique symbol;\n\ntype Brand<T, B extends string> = T & { readonly [BrandSymbol]: B };\n\nexport type Milliseconds = Brand<number, \"Milliseconds\">;\n\nexport const milliseconds = (value: number): Milliseconds => {\n  if (!Number.isFinite(value)) {\n    throw new TypeError(`milliseconds value must be finite, received: ${value}`);\n  }\n  // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- branded type constructor: value is validated above\n  return value as Milliseconds;\n};\n\nexport interface DeadlineOptions {\n  readonly flushBufferMs?: number;\n}\n"]}
+{"mappings":"","names":[],"sources":["src/types.ts"],"version":3,"sourcesContent":["// SPDX-FileCopyrightText: 2026 lambda-deadline-middleware contributors\n// SPDX-License-Identifier: MIT\n\nexport interface DeadlineOptions {\n  readonly flushBufferMs?: number;\n}\n"]}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "lambda-deadline-middleware",
-  "version": "1.1.0",
-  "description": "AWS SDK v3 middleware for automatic Lambda deadline propagation via AbortController-based timeouts",
+  "version": "2.0.0",
+  "description": "Zero-dependency AWS SDK v3 middleware that propagates Lambda deadlines to outgoing SDK calls via AbortSignal",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -28,19 +28,19 @@
   },
   "scripts": {
     "build": "node --experimental-strip-types scripts/build.ts",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "bench": "vitest bench --run --outputJson=bench-results.json && node --experimental-strip-types scripts/validate-bench.ts",
+    "test": "vitest run --config .config/vitest.config.ts",
+    "test:watch": "vitest --config .config/vitest.config.ts",
+    "bench": "vitest bench --run --config .config/vitest.config.ts --outputJson=bench-results.json && node --experimental-strip-types scripts/validate-bench.ts",
     "typecheck": "tsc",
-    "lint": "oxlint --type-aware --type-check --fix .",
-    "lint:check": "oxlint --type-aware --type-check .",
+    "lint": "oxlint --fix .",
+    "lint:check": "oxlint .",
     "fmt": "oxfmt .",
     "fmt:check": "oxfmt --check .",
-    "lint:knip": "knip",
+    "lint:knip": "knip --config .config/knip.js",
     "sast": "scripts/ensure-opengrep.sh scan .",
     "sast:check": "scripts/ensure-opengrep.sh scan --error .",
-    "sca": "podman run --rm -v \"$(pwd):/src:Z\" -v trivy-cache:/root/.cache/trivy:Z ghcr.io/aquasecurity/trivy:0.71.0@sha256:016eae51fdcf989332a5404af7e8f625cd5d95d7c0907a221d080a996f556500 fs --scanners vuln --include-dev-deps --exit-code 1 --severity HIGH,CRITICAL /src",
-    "sca:full": "podman run --rm -v \"$(pwd):/src:Z\" -v trivy-cache:/root/.cache/trivy:Z ghcr.io/aquasecurity/trivy:0.71.0@sha256:016eae51fdcf989332a5404af7e8f625cd5d95d7c0907a221d080a996f556500 fs --scanners vuln,secret,misconfig --include-dev-deps /src",
+    "sca": "podman run --rm -v \"$(pwd):/src:Z\" -v trivy-cache:/root/.cache/trivy:Z ghcr.io/aquasecurity/trivy:0.71.0@sha256:016eae51fdcf989332a5404af7e8f625cd5d95d7c0907a221d080a996f556500 fs --config /src/.config/trivy.yaml --ignorefile /src/.config/.trivyignore --scanners vuln --include-dev-deps --exit-code 1 --severity HIGH,CRITICAL /src",
+    "sca:full": "podman run --rm -v \"$(pwd):/src:Z\" -v trivy-cache:/root/.cache/trivy:Z ghcr.io/aquasecurity/trivy:0.71.0@sha256:016eae51fdcf989332a5404af7e8f625cd5d95d7c0907a221d080a996f556500 fs --config /src/.config/trivy.yaml --ignorefile /src/.config/.trivyignore --scanners vuln,secret,misconfig --include-dev-deps /src",
     "actionlint": "podman run --rm -w /repo -v \"$(pwd):/repo:Z\" docker.io/rhysd/actionlint:1.7.12@sha256:9d36088643581e728c969f35141f88139fec77280b2be23c1f66f8e40e1025e7",
     "security": "pnpm run sast:check && pnpm run sca && pnpm run actionlint",
     "prepare": "lefthook install",
@@ -48,9 +48,9 @@
     "release": "semantic-release"
   },
   "devDependencies": {
-    "@aws-sdk/client-dynamodb": "^3.1064.0",
-    "@aws-sdk/client-s3": "^3.1064.0",
-    "@aws-sdk/client-sqs": "^3.1064.0",
+    "@aws-sdk/client-dynamodb": "^3.1073.0",
+    "@aws-sdk/client-s3": "^3.1073.0",
+    "@aws-sdk/client-sqs": "^3.1073.0",
     "@commitlint/cli": "^21.0.2",
     "@commitlint/config-conventional": "^21.0.2",
     "@fast-check/vitest": "^0.4.1",
@@ -58,19 +58,19 @@
     "@semantic-release/github": "12.0.8",
     "@semantic-release/npm": "13.1.5",
     "@semantic-release/release-notes-generator": "14.1.1",
-    "@smithy/types": "^4.14.3",
-    "@types/node": "^25.9.2",
-    "@vitest/coverage-v8": "^4.1.8",
+    "@smithy/types": "^4.15.0",
+    "@types/node": "^25.9.4",
+    "@vitest/coverage-v8": "^4.1.9",
     "conventional-changelog-conventionalcommits": "^9.3.1",
-    "knip": "^6.16.1",
+    "knip": "^6.17.1",
     "lefthook": "^2.1.9",
     "oxc-transform": "^0.135.0",
     "oxfmt": "^0.54.0",
-    "oxlint": "^1.69.0",
+    "oxlint": "^1.70.0",
     "oxlint-tsgolint": "^0.23.0",
     "semantic-release": "25.0.5",
     "typescript": "^6.0.3",
-    "vitest": "^4.1.8"
+    "vitest": "^4.1.9"
   },
   "engines": {
     "node": ">=24"

package/src/context-store.ts

@@ -3,22 +3,88 @@
 
 import { AsyncLocalStorage } from "node:async_hooks";
 
-// AsyncLocalStorage propagates the Lambda context through the entire async call chain without parameter threading.
-// SDK middleware executes deep in the Smithy stack where we can't pass the context through function signatures.
+import { DeadlineExceededError } from "./error.js";
+
+import type { DeadlineOptions } from "./types.js";
+
+// AsyncLocalStorage propagates the deadline signal through the entire async call chain.
+// SDK middleware executes deep in the Smithy stack where we can't pass it through function signatures.
 export interface LambdaContextLike {
   getRemainingTimeInMillis?: () => number;
 }
 
-const contextStorage = new AsyncLocalStorage<LambdaContextLike>();
+interface DeadlineStore {
+  signal?: AbortSignal;
+}
+
+const contextStorage = new AsyncLocalStorage<DeadlineStore>();
 
-export const run = <T>(context: LambdaContextLike | null | undefined, fn: () => T): T => {
-  if (context === null || context === undefined) return fn();
-  return contextStorage.run(context, fn);
+/**
+ * Store an external AbortSignal for the current invocation.
+ * When set, the SDK middleware uses this signal directly instead of
+ * the auto-computed deadline signal.
+ *
+ * Call this at the start of your handler, before any SDK calls.
+ * The signal is scoped to the current async context (AsyncLocalStorage).
+ */
+export const setDeadlineSignal = (signal: AbortSignal): void => {
+  const store = contextStorage.getStore();
+  if (store === undefined) {
+    throw new Error("setDeadlineSignal() must be called within a withLambdaDeadline() scope");
+  }
+  store.signal = signal;
 };
 
-export const getRemainingTimeInMillis = (): number | undefined => {
+/**
+ * Retrieve the deadline signal for the current invocation, if one exists.
+ */
+export const getDeadlineSignal = (): AbortSignal | undefined => {
   const store = contextStorage.getStore();
   if (store === undefined) return undefined;
-  if (typeof store.getRemainingTimeInMillis !== "function") return undefined;
-  return store.getRemainingTimeInMillis();
+  return store.signal;
 };
+
+// Handler wrapper — computes the deadline signal once at invocation start and stores it via AsyncLocalStorage.
+type AsyncHandler<TEvent, TContext extends LambdaContextLike, TResult> = (
+  event: TEvent,
+  context: TContext,
+) => Promise<TResult>;
+
+export const withLambdaDeadline =
+  <TEvent, TContext extends LambdaContextLike, TResult>(
+    handler: AsyncHandler<TEvent, TContext, TResult>,
+    options?: DeadlineOptions,
+  ): AsyncHandler<TEvent, TContext, TResult> =>
+  async (event: TEvent, context: TContext): Promise<TResult> => {
+    const store: DeadlineStore = {};
+
+    // Compute the auto-deadline signal once, up front.
+    // If the user calls setDeadlineSignal() later, it overwrites this.
+    // oxlint-disable-next-line typescript/no-unnecessary-condition -- runtime safety: context may be null/undefined despite types (e.g. untyped callers)
+    if (context !== null && context !== undefined) {
+      const remaining =
+        typeof context.getRemainingTimeInMillis === "function"
+          ? context.getRemainingTimeInMillis()
+          : undefined;
+
+      if (remaining !== undefined) {
+        const rawBuffer = options?.flushBufferMs ?? 1000;
+        if (rawBuffer < 0) {
+          throw new TypeError(`flushBufferMs option must be non-negative, received: ${rawBuffer}`);
+        }
+        const deadline = remaining - rawBuffer;
+
+        if (deadline <= 0) {
+          throw new DeadlineExceededError({
+            deadlineMs: 0,
+            flushBufferMs: rawBuffer,
+            remainingMs: remaining,
+          });
+        }
+
+        store.signal = AbortSignal.timeout(deadline);
+      }
+    }
+
+    return contextStorage.run(store, async () => handler(event, context));
+  };

package/src/error.ts

@@ -1,19 +1,17 @@
 // SPDX-FileCopyrightText: 2026 lambda-deadline-middleware contributors
 // SPDX-License-Identifier: MIT
 
-import type { Milliseconds } from "./types.js";
-
 interface DeadlineExceededInit {
-  readonly deadlineMs: Milliseconds;
-  readonly flushBufferMs: Milliseconds;
-  readonly remainingMs: Milliseconds;
+  readonly deadlineMs: number;
+  readonly flushBufferMs: number;
+  readonly remainingMs: number;
 }
 
 export class DeadlineExceededError extends Error {
   override readonly name = "DeadlineExceededError" as const;
-  readonly deadlineMs: Milliseconds;
-  readonly flushBufferMs: Milliseconds;
-  readonly remainingMs: Milliseconds;
+  readonly deadlineMs: number;
+  readonly flushBufferMs: number;
+  readonly remainingMs: number;
 
   constructor(init: DeadlineExceededInit) {
     super(

package/src/index.ts

@@ -1,11 +1,9 @@
 // SPDX-FileCopyrightText: 2026 lambda-deadline-middleware contributors
 // SPDX-License-Identifier: MIT
 
-export { withLambdaDeadline } from "./handler-wrapper.js";
+export { withLambdaDeadline, setDeadlineSignal } from "./context-store.js";
 export { deadlineMiddleware } from "./middleware.js";
 export { DeadlineExceededError, isDeadlineExceeded } from "./error.js";
-export { getRemainingTimeInMillis } from "./context-store.js";
-
-export type { Milliseconds, DeadlineOptions } from "./types.js";
 
+export type { DeadlineOptions } from "./types.js";
 export type { LambdaContextLike } from "./context-store.js";

package/src/middleware.ts

@@ -9,88 +9,38 @@ import type {
   Pluggable,
 } from "@smithy/types";
 
-import { getRemainingTimeInMillis } from "./context-store.js";
-import { DeadlineExceededError } from "./error.js";
-import { milliseconds } from "./types.js";
-
-import type { DeadlineOptions } from "./types.js";
-
-export const composeSignals = (
-  existing: AbortSignal | undefined,
-  deadline: AbortSignal,
-): AbortSignal => {
-  if (existing === undefined) return deadline;
-  return AbortSignal.any([existing, deadline]);
-};
-
-export const deadlineMiddleware = <Input extends object, Output extends object>(
-  options?: DeadlineOptions,
-): Pluggable<Input, Output> => {
-  const raw = options?.flushBufferMs ?? 1000;
-  if (raw < 0) {
-    throw new TypeError(`flushBufferMs option must be non-negative, received: ${raw}`);
-  }
-  const flushBufferMs = milliseconds(raw);
-
-  return {
-    applyToStack(stack) {
-      // Registered at "finalizeRequest" (attempt level) rather than API-call level so each retry gets a deadline
-      // computed from the actual remaining time at that moment. API-call level would cache a stale deadline
-      // across retries, which grow more dangerous after backoff delays eat into remaining time.
-      stack.add(
-        (
-          next: FinalizeHandler<Input, Output>,
-          _context: HandlerExecutionContext,
-        ): FinalizeHandler<Input, Output> =>
-          async (args: FinalizeHandlerArguments<Input>): Promise<FinalizeHandlerOutput<Output>> => {
-            const remaining = getRemainingTimeInMillis();
-            if (remaining === undefined) return next(args);
-
-            const deadline = remaining - flushBufferMs;
-
-            if (deadline <= 0) {
-              throw new DeadlineExceededError({
-                deadlineMs: milliseconds(0),
-                flushBufferMs,
-                remainingMs: milliseconds(remaining),
-              });
-            }
-
-            const controller = new AbortController();
-            const timeoutId = setTimeout(() => {
-              controller.abort(
-                new DeadlineExceededError({
-                  deadlineMs: milliseconds(deadline),
-                  flushBufferMs,
-                  remainingMs: milliseconds(remaining),
-                }),
-              );
-            }, deadline);
-
-            // `using` guarantees cleanup (clearTimeout) even if next() throws, the promise rejects,
-            // or an external abort signal fires — strictly more reliable than try/finally.
-            using _timer = {
-              [Symbol.dispose]() {
-                clearTimeout(timeoutId);
-              },
-            };
-
-            // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- Smithy request is an opaque object; we access optional signal property
-            const request = args.request as { signal?: AbortSignal } | undefined;
-            const signal = composeSignals(request?.signal, controller.signal);
-            const result = await next({
-              ...args,
-              // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- spreading opaque Smithy request to add signal
-              request: { ...(args.request as object), signal },
-            });
-            return result;
-          },
-        {
-          step: "finalizeRequest",
-          name: "deadlineMiddleware",
-          override: true,
+import { getDeadlineSignal } from "./context-store.js";
+
+export const deadlineMiddleware = <Input extends object, Output extends object>(): Pluggable<
+  Input,
+  Output
+> => ({
+  applyToStack(stack) {
+    stack.add(
+      (
+        next: FinalizeHandler<Input, Output>,
+        _context: HandlerExecutionContext,
+      ): FinalizeHandler<Input, Output> =>
+        async (args: FinalizeHandlerArguments<Input>): Promise<FinalizeHandlerOutput<Output>> => {
+          const deadlineSignal = getDeadlineSignal();
+          if (deadlineSignal === undefined) return next(args);
+
+          // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- Smithy request is an opaque object
+          const request = args.request as { signal?: AbortSignal } | undefined;
+          const existing = request?.signal;
+          const signal = existing ? AbortSignal.any([existing, deadlineSignal]) : deadlineSignal;
+
+          return next({
+            ...args,
+            // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- spreading opaque Smithy request to add signal
+            request: { ...(args.request as object), signal },
+          });
         },
-      );
-    },
-  };
-};
+      {
+        step: "finalizeRequest",
+        name: "deadlineMiddleware",
+        override: true,
+      },
+    );
+  },
+});

package/src/types.ts

@@ -1,22 +1,6 @@
 // SPDX-FileCopyrightText: 2026 lambda-deadline-middleware contributors
 // SPDX-License-Identifier: MIT
 
-// Branded type prevents interchange errors at compile time (e.g. passing seconds where milliseconds are expected).
-// Zero runtime cost. Smart constructor below validates at the boundary and brands the value.
-declare const BrandSymbol: unique symbol;
-
-type Brand<T, B extends string> = T & { readonly [BrandSymbol]: B };
-
-export type Milliseconds = Brand<number, "Milliseconds">;
-
-export const milliseconds = (value: number): Milliseconds => {
-  if (!Number.isFinite(value)) {
-    throw new TypeError(`milliseconds value must be finite, received: ${value}`);
-  }
-  // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- branded type constructor: value is validated above
-  return value as Milliseconds;
-};
-
 export interface DeadlineOptions {
   readonly flushBufferMs?: number;
 }

package/dist/handler-wrapper.d.ts

@@ -1,14 +0,0 @@
-import type { LambdaContextLike } from "./context-store.js";
-type AsyncHandler<
-	TEvent,
-	TContext extends LambdaContextLike,
-	TResult
-> = (event: TEvent, context: TContext) => Promise<TResult>;
-export declare const withLambdaDeadline: <
-	TEvent,
-	TContext extends LambdaContextLike,
-	TResult
->(handler: AsyncHandler<TEvent, TContext, TResult>) => AsyncHandler<TEvent, TContext, TResult>;
-export {};
-
-//# sourceMappingURL=handler-wrapper.d.ts.map

package/dist/handler-wrapper.d.ts.map

@@ -1 +0,0 @@
-{"mappings":"AAKA,cAAc,yBAAyB;KAElC;CAAa;CAAQ,iBAAiB;CAAmB;KAC5D,OAAO,QACP,SAAS,aACN,QAAQ;AAEb,OAAO,cAAM;CACV;CAAQ,iBAAiB;CAAmB;EAC3C,SAAS,aAAa,QAAQ,UAAU,aACvC,aAAa,QAAQ,UAAU","names":[],"sources":["src/handler-wrapper.ts"],"version":3,"sourcesContent":["// SPDX-FileCopyrightText: 2026 lambda-deadline-middleware contributors\n// SPDX-License-Identifier: MIT\n\nimport { run } from \"./context-store.js\";\n\nimport type { LambdaContextLike } from \"./context-store.js\";\n\ntype AsyncHandler<TEvent, TContext extends LambdaContextLike, TResult> = (\n  event: TEvent,\n  context: TContext,\n) => Promise<TResult>;\n\nexport const withLambdaDeadline =\n  <TEvent, TContext extends LambdaContextLike, TResult>(\n    handler: AsyncHandler<TEvent, TContext, TResult>,\n  ): AsyncHandler<TEvent, TContext, TResult> =>\n  async (event: TEvent, context: TContext): Promise<TResult> =>\n    run(context, async () => handler(event, context));\n"]}

package/dist/handler-wrapper.js

@@ -1,6 +0,0 @@
-// SPDX-FileCopyrightText: 2026 lambda-deadline-middleware contributors
-// SPDX-License-Identifier: MIT
-import { run } from "./context-store.js";
-export const withLambdaDeadline = (handler) => async (event, context) => run(context, async () => handler(event, context));
-
-//# sourceMappingURL=handler-wrapper.js.map

package/dist/handler-wrapper.js.map

@@ -1 +0,0 @@
-{"mappings":";;AAGA,SAAS,WAAW;AASpB,OAAO,MAAM,sBAET,YAEF,OAAO,OAAe,YACpB,IAAI,SAAS,YAAY,QAAQ,OAAO,OAAO,CAAC","names":[],"sources":["src/handler-wrapper.ts"],"version":3,"sourcesContent":["// SPDX-FileCopyrightText: 2026 lambda-deadline-middleware contributors\n// SPDX-License-Identifier: MIT\n\nimport { run } from \"./context-store.js\";\n\nimport type { LambdaContextLike } from \"./context-store.js\";\n\ntype AsyncHandler<TEvent, TContext extends LambdaContextLike, TResult> = (\n  event: TEvent,\n  context: TContext,\n) => Promise<TResult>;\n\nexport const withLambdaDeadline =\n  <TEvent, TContext extends LambdaContextLike, TResult>(\n    handler: AsyncHandler<TEvent, TContext, TResult>,\n  ): AsyncHandler<TEvent, TContext, TResult> =>\n  async (event: TEvent, context: TContext): Promise<TResult> =>\n    run(context, async () => handler(event, context));\n"]}

package/src/handler-wrapper.ts

@@ -1,18 +0,0 @@
-// SPDX-FileCopyrightText: 2026 lambda-deadline-middleware contributors
-// SPDX-License-Identifier: MIT
-
-import { run } from "./context-store.js";
-
-import type { LambdaContextLike } from "./context-store.js";
-
-type AsyncHandler<TEvent, TContext extends LambdaContextLike, TResult> = (
-  event: TEvent,
-  context: TContext,
-) => Promise<TResult>;
-
-export const withLambdaDeadline =
-  <TEvent, TContext extends LambdaContextLike, TResult>(
-    handler: AsyncHandler<TEvent, TContext, TResult>,
-  ): AsyncHandler<TEvent, TContext, TResult> =>
-  async (event: TEvent, context: TContext): Promise<TResult> =>
-    run(context, async () => handler(event, context));