lambda-deadline-middleware 1.0.1 → 2.0.0

package/README.md

@@ -3,22 +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,
-destroying in-flight OpenTelemetry/X-Ray spans without export. 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
-- Optional OpenTelemetry span events on deadline aborts (detected dynamically)
-- 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
 
@@ -28,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";
@@ -58,74 +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),
+);
 ```
 
-`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.
+When an external signal is set via `setDeadlineSignal()`:
 
-## Configuration
+- 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
 
-### Flush Buffer
+When no external signal is set, the auto-computed signal (from `withLambdaDeadline`) is used.
 
-The flush buffer is subtracted from the remaining Lambda time to leave room for telemetry export and error handling:
+**Important:** `withLambdaDeadline` must wrap the outside. It creates the `AsyncLocalStorage` scope that
+`setDeadlineSignal` writes into.
 
 ```typescript
-// Default: 1000ms
-dynamodb.middlewareStack.use(deadlineMiddleware());
+// ✅ Correct: withLambdaDeadline on the outside
+export const handler = withLambdaDeadline(
+  middy({ timeoutEarlyInMillis: 1000 }).handler(baseHandler),
+);
 
-// Custom: 500ms
-dynamodb.middlewareStack.use(deadlineMiddleware({ flushBufferMs: 500 }));
+// ❌ Wrong: store doesn't exist yet when baseHandler runs
+export const handler = middy({ timeoutEarlyInMillis: 1000 }).handler(
+  withLambdaDeadline(baseHandler),
+);
 ```
 
-### Telemetry
+`setDeadlineSignal` only affects AWS SDK calls (via the Smithy middleware stack). For other async work, pass the signal
+yourself:
 
-If `@opentelemetry/api` is installed, span events are emitted on deadline aborts. Disable with:
+```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
+
+Subtracted from remaining Lambda time to leave room for cleanup:
 
 ```typescript
-dynamodb.middlewareStack.use(deadlineMiddleware({ telemetryEnabled: false }));
+// Default: 1000ms flush buffer
+export const handler = withLambdaDeadline(myHandler);
+
+// 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;
 }
@@ -133,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({
@@ -153,8 +235,7 @@ await dynamodb.send(
 
 ### `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>(
@@ -163,25 +244,25 @@ function withLambdaDeadline<TEvent, TResult>(
 ): (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;
@@ -189,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: FlushBufferMs;
-  readonly remainingMs: Milliseconds;
+  readonly deadlineMs: number;
+  readonly flushBufferMs: number;
+  readonly remainingMs: number;
 }
 ```
 
@@ -203,29 +286,24 @@ class DeadlineExceededError extends Error {
 ```typescript
 interface DeadlineOptions {
   readonly flushBufferMs?: number; // Default: 1000
-  readonly telemetryEnabled?: boolean; // Default: true
 }
 ```
 
 ### Types
 
-| Type                  | Description                                                                  |
-| --------------------- | ---------------------------------------------------------------------------- |
-| `Milliseconds`        | Branded number representing a duration in ms                                 |
-| `FlushBufferMs`       | Branded number for the flush buffer                                          |
-| `RequestDeadlineMs`   | Branded number for a computed deadline                                       |
-| `DeadlineComputation` | Discriminated union: `"deadline"` \| `"insufficient-time"` \| `"no-context"` |
-| `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;AAWA,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\n// Sentinel allows AsyncLocalStorage.run() to accept null/undefined context\n// without throwing, while the accessor can distinguish \"no context stored\"\n// from \"context present but missing the method\".\nconst NO_CONTEXT: unique symbol = Symbol(\"no-context\");\n\ntype StoreValue = LambdaContextLike | typeof NO_CONTEXT;\n\nconst contextStorage = new AsyncLocalStorage<StoreValue>();\n\nexport const run = <T>(context: LambdaContextLike | null | undefined, fn: () => T): T => {\n  const value: StoreValue = context ?? NO_CONTEXT;\n  return contextStorage.run(value, fn);\n};\n\nexport const getRemainingTimeInMillis = (): number | undefined => {\n  const store = contextStorage.getStore();\n\n  if (store === undefined || store === NO_CONTEXT) {\n    return undefined;\n  }\n\n  if (typeof store.getRemainingTimeInMillis !== \"function\") {\n    return undefined;\n  }\n\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,24 +1,55 @@
 // SPDX-FileCopyrightText: 2026 lambda-deadline-middleware contributors
 // SPDX-License-Identifier: MIT
 import { AsyncLocalStorage } from "node:async_hooks";
-// Sentinel allows AsyncLocalStorage.run() to accept null/undefined context
-// without throwing, while the accessor can distinguish "no context stored"
-// from "context present but missing the method".
-const NO_CONTEXT = Symbol("no-context");
+import { DeadlineExceededError } from "./error.js";
 const contextStorage = new AsyncLocalStorage();
-export const run = (context, fn) => {
-	const value = context ?? NO_CONTEXT;
-	return contextStorage.run(value, fn);
-};
-export const getRemainingTimeInMillis = () => {
+/**
+* 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 || store === NO_CONTEXT) {
-		return undefined;
+	if (store === undefined) {
+		throw new Error("setDeadlineSignal() must be called within a withLambdaDeadline() scope");
 	}
-	if (typeof store.getRemainingTimeInMillis !== "function") {
-		return undefined;
+	store.signal = signal;
+};
+/**
+* Retrieve the deadline signal for the current invocation, if one exists.
+*/
+export const getDeadlineSignal = () => {
+	const store = contextStorage.getStore();
+	if (store === undefined) return undefined;
+	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 store.getRemainingTimeInMillis();
+	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;;;;AAWlC,MAAM,aAA4B,OAAO,YAAY;AAIrD,MAAM,iBAAiB,IAAI,kBAA8B;AAEzD,OAAO,MAAM,OAAU,SAA+C,OAAmB;CACvF,MAAM,QAAoB,WAAW;CACrC,OAAO,eAAe,IAAI,OAAO,EAAE;AACrC;AAEA,OAAO,MAAM,iCAAqD;CAChE,MAAM,QAAQ,eAAe,SAAS;CAEtC,IAAI,UAAU,aAAa,UAAU,YAAY;EAC/C,OAAO;CACT;CAEA,IAAI,OAAO,MAAM,6BAA6B,YAAY;EACxD,OAAO;CACT;CAEA,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\n// Sentinel allows AsyncLocalStorage.run() to accept null/undefined context\n// without throwing, while the accessor can distinguish \"no context stored\"\n// from \"context present but missing the method\".\nconst NO_CONTEXT: unique symbol = Symbol(\"no-context\");\n\ntype StoreValue = LambdaContextLike | typeof NO_CONTEXT;\n\nconst contextStorage = new AsyncLocalStorage<StoreValue>();\n\nexport const run = <T>(context: LambdaContextLike | null | undefined, fn: () => T): T => {\n  const value: StoreValue = context ?? NO_CONTEXT;\n  return contextStorage.run(value, fn);\n};\n\nexport const getRemainingTimeInMillis = (): number | undefined => {\n  const store = contextStorage.getStore();\n\n  if (store === undefined || store === NO_CONTEXT) {\n    return undefined;\n  }\n\n  if (typeof store.getRemainingTimeInMillis !== \"function\") {\n    return undefined;\n  }\n\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 { FlushBufferMs, Milliseconds } from "./types.js";
 interface DeadlineExceededInit {
-	readonly deadlineMs: Milliseconds;
-	readonly flushBufferMs: FlushBufferMs;
-	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: FlushBufferMs;
-	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,eAAe,oBAAoB;UAEvC,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 { FlushBufferMs, Milliseconds } from \"./types.js\";\n\ninterface DeadlineExceededInit {\n  readonly deadlineMs: Milliseconds;\n  readonly flushBufferMs: FlushBufferMs;\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: FlushBufferMs;\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 { FlushBufferMs, Milliseconds } from \"./types.js\";\n\ninterface DeadlineExceededInit {\n  readonly deadlineMs: Milliseconds;\n  readonly flushBufferMs: FlushBufferMs;\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: FlushBufferMs;\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 { deadlineMiddleware } from "./registration.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, FlushBufferMs, RequestDeadlineMs, DeadlineComputation, DeadlineMiddlewareConfig, 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,cACE,cACA,eACA,mBACA,qBACA,0BACA,uBACK;AAEP,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 \"./registration.js\";\nexport { DeadlineExceededError, isDeadlineExceeded } from \"./error.js\";\nexport { getRemainingTimeInMillis } from \"./context-store.js\";\n\nexport type {\n  Milliseconds,\n  FlushBufferMs,\n  RequestDeadlineMs,\n  DeadlineComputation,\n  DeadlineMiddlewareConfig,\n  DeadlineOptions,\n} 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 { deadlineMiddleware } from "./registration.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 \"./registration.js\";\nexport { DeadlineExceededError, isDeadlineExceeded } from \"./error.js\";\nexport { getRemainingTimeInMillis } from \"./context-store.js\";\n\nexport type {\n  Milliseconds,\n  FlushBufferMs,\n  RequestDeadlineMs,\n  DeadlineComputation,\n  DeadlineMiddlewareConfig,\n  DeadlineOptions,\n} 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,15 +1,7 @@
-import type { DeadlineComputation, DeadlineMiddlewareConfig, RequestDeadlineMs } from "./types.js";
-import type { FinalizeRequestMiddleware } from "@smithy/types";
-export declare const computeDeadline: (config: DeadlineMiddlewareConfig) => DeadlineComputation;
-export interface DeadlineTimer {
-	readonly controller: AbortController;
-	[Symbol.dispose]: () => void;
-}
-export declare const createDeadlineTimer: (deadlineMs: RequestDeadlineMs, config: DeadlineMiddlewareConfig) => DeadlineTimer;
-export declare const composeSignals: (existing: AbortSignal | undefined, deadline: AbortSignal) => AbortSignal;
-export declare const deadlineMiddlewareHandler: <
+import type { Pluggable } from "@smithy/types";
+export declare const deadlineMiddleware: <
 	Input extends object,
 	Output extends object
->(config: DeadlineMiddlewareConfig) => FinalizeRequestMiddleware<Input, Output>;
+>() => Pluggable<Input, Output>;
 
 //# sourceMappingURL=middleware.d.ts.map