lambda-deadline-middleware 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 lambda-deadline-middleware contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,278 @@
+<!-- SPDX-FileCopyrightText: 2024 lambda-deadline-middleware contributors -->
+<!-- SPDX-License-Identifier: MIT -->
+
+# lambda-deadline-middleware
+
+Zero-dependency AWS SDK v3 middleware that automatically propagates Lambda execution deadlines to outgoing SDK calls via `AbortController`-based timeouts.
+
+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.
+
+## Features
+
+- **Automatic deadline propagation** — no manual timeout configuration per call
+- **Fresh deadline per retry** — each SDK retry attempt gets a deadline based on _current_ remaining time
+- **Signal composition** — preserves caller-provided `AbortSignal` via `AbortSignal.any()`
+- **Zero runtime dependencies** — uses `@smithy/types` for compile-time types only
+- **Safe outside Lambda** — complete no-op when no Lambda context is available
+- **OpenTelemetry integration** — optional span events on deadline aborts (detected dynamically)
+- **Type-safe** — branded types prevent millisecond/buffer interchange at compile time
+
+## Requirements
+
+- Node.js ≥ 24
+- AWS SDK v3 (built against `@smithy/types` ≥ 3.0.0)
+
+## Installation
+
+```bash
+pnpm add lambda-deadline-middleware
+```
+
+## Quick Start
+
+```typescript
+import { withLambdaDeadline, withDeadline } from "lambda-deadline-middleware";
+import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
+
+// 1. Wrap your Lambda handler
+export const handler = withLambdaDeadline(async (event, context) => {
+  const result = await dynamodb.send(
+    new GetItemCommand({
+      /* ... */
+    }),
+  );
+  return { statusCode: 200, body: JSON.stringify(result) };
+});
+
+// 2. Register middleware on SDK clients
+const dynamodb = withDeadline(new DynamoDBClient({}));
+```
+
+That's it. Every SDK call through `dynamodb` will automatically receive a timeout derived from the Lambda's remaining execution time minus a 1000ms flush buffer.
+
+## Architecture
+
+```mermaid
+graph TB
+    subgraph "Lambda Runtime"
+        LR[Lambda Runtime] -->|invokes| HW[Handler Wrapper<br/>withLambdaDeadline]
+        HW -->|stores context| ALS[AsyncLocalStorage<br/>Lambda Context Store]
+        HW -->|delegates to| UH[User Handler]
+        UH -->|sends command| SDK[AWS SDK v3 Client]
+
+        subgraph "SDK Middleware Stack"
+            direction TB
+            INIT[Initialize Step]
+            FIN[Finalize Step]
+            RETRY[Retry Middleware]
+            DM[Deadline Middleware<br/>← attempt level]
+            HTTP[HTTP Handler]
+
+            INIT --> FIN --> RETRY
+            RETRY -->|per attempt| DM --> HTTP
+        end
+
+        DM -->|reads remaining time| ALS
+        DM -->|creates| AC[AbortController<br/>+ setTimeout]
+        AC -->|signal attached to| HTTP
+    end
+
+    SDK -->|middleware stack| INIT
+
+    style DM fill:#f9a825,stroke:#f57f17
+    style ALS fill:#42a5f5,stroke:#1565c0
+    style HW fill:#66bb6a,stroke:#2e7d32
+```
+
+The middleware registers at the **attempt level** of the SDK stack — it executes once per HTTP request dispatch including retries, computing a fresh deadline each time.
+
+## Configuration
+
+### Flush Buffer
+
+The flush buffer is subtracted from the remaining Lambda time to leave room for telemetry export and error handling:
+
+```typescript
+// Default: 1000ms flush buffer
+const client = withDeadline(new DynamoDBClient({}));
+
+// Custom: 500ms flush buffer
+const client = withDeadline(new DynamoDBClient({}), { flushBufferMs: 500 });
+
+// No buffer: use full remaining time
+const client = withDeadline(new DynamoDBClient({}), { flushBufferMs: 0 });
+```
+
+### Handler-Level Defaults
+
+```typescript
+export const handler = withLambdaDeadline(
+  async (event, context) => {
+    /* ... */
+  },
+  { flushBufferMs: 2000, telemetryEnabled: false },
+);
+```
+
+### Telemetry
+
+OpenTelemetry integration is detected dynamically. If `@opentelemetry/api` is installed, span events are emitted on deadline aborts. Disable with:
+
+```typescript
+const client = withDeadline(new DynamoDBClient({}), { telemetryEnabled: false });
+```
+
+## API Reference
+
+### `withLambdaDeadline(handler, options?)`
+
+Wraps a Lambda handler to initialize the context store.
+
+```typescript
+function withLambdaDeadline<TEvent, TResult>(
+  handler: (event: TEvent, context: LambdaContextLike) => Promise<TResult>,
+  options?: DeadlineOptions,
+): (event: TEvent, context: LambdaContextLike) => Promise<TResult>;
+```
+
+### `withDeadline(client, options?)`
+
+Registers the deadline middleware on an SDK client. Returns the same client instance. Idempotent — subsequent calls on the same client are no-ops.
+
+```typescript
+function withDeadline<T extends { middlewareStack: { use: Function } }>(
+  client: T,
+  options?: DeadlineOptions,
+): T;
+```
+
+### `deadlineMiddleware(options?)`
+
+Factory returning a `Pluggable` object for `client.middlewareStack.use()`.
+
+```typescript
+function deadlineMiddleware(options?: DeadlineOptions): Pluggable<object, object>;
+```
+
+### `getRemainingTimeInMillis()`
+
+Accessor for the current Lambda's remaining execution time. Returns `undefined` outside a Lambda context.
+
+```typescript
+function getRemainingTimeInMillis(): number | undefined;
+```
+
+### `DeadlineExceededError`
+
+Error thrown when a request is aborted due to deadline expiration.
+
+```typescript
+class DeadlineExceededError extends Error {
+  readonly name: "DeadlineExceededError";
+  readonly deadlineMs: Milliseconds;
+  readonly flushBufferMs: FlushBufferMs;
+  readonly remainingMs: Milliseconds;
+}
+```
+
+### `isDeadlineExceeded(error)`
+
+Type guard for deadline-triggered abort errors.
+
+```typescript
+function isDeadlineExceeded(error: unknown): error is DeadlineExceededError;
+```
+
+### `DeadlineOptions`
+
+```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"` |
+| `DeadlineMiddlewareConfig` | Validated configuration (internal)                                           |
+| `LambdaContextLike`        | Minimal interface: `{ getRemainingTimeInMillis?(): number }`                 |
+
+## Error Handling
+
+```typescript
+import { isDeadlineExceeded } from "lambda-deadline-middleware";
+
+try {
+  await client.send(
+    new GetItemCommand({
+      /* ... */
+    }),
+  );
+} catch (error) {
+  if (isDeadlineExceeded(error)) {
+    console.log(`Deadline exceeded: ${error.deadlineMs}ms`);
+    console.log(`Remaining time was: ${error.remainingMs}ms`);
+    // Handle graceful degradation
+  }
+  throw error;
+}
+```
+
+When remaining time is less than or equal to the flush buffer, the middleware throws `DeadlineExceededError` immediately without dispatching an HTTP request.
+
+## Advanced Usage
+
+### Direct Pluggable Registration
+
+```typescript
+import { deadlineMiddleware } from "lambda-deadline-middleware";
+
+const client = new S3Client({});
+client.middlewareStack.use(deadlineMiddleware({ flushBufferMs: 750 }));
+```
+
+### Combining with Existing Abort Signals
+
+The middleware composes signals — your existing signal is preserved:
+
+```typescript
+const controller = new AbortController();
+setTimeout(() => controller.abort(), 5000); // your own timeout
+
+await client.send(
+  new GetItemCommand({
+    /* ... */
+  }),
+  {
+    abortSignal: controller.signal, // both signals are respected
+  },
+);
+```
+
+### Multiple Clients
+
+```typescript
+const dynamodb = withDeadline(new DynamoDBClient({}));
+const sqs = withDeadline(new SQSClient({}), { flushBufferMs: 2000 });
+const s3 = withDeadline(new S3Client({}), { flushBufferMs: 500 });
+```
+
+## Reporting Bugs
+
+Found a bug? Please open a [GitHub Issue](https://github.com/mikkopiu/lambda-deadline-middleware/issues/new) with:
+
+- Your Node.js version and AWS SDK version
+- A minimal code snippet reproducing the problem
+- Expected vs actual behavior
+
+For security vulnerabilities, see [SECURITY.md](SECURITY.md) instead.
+
+## License
+
+[MIT](LICENSE)

package/SECURITY.md

@@ -0,0 +1,95 @@
+<!-- SPDX-FileCopyrightText: 2024 lambda-deadline-middleware contributors -->
+<!-- SPDX-License-Identifier: MIT -->
+
+# Security
+
+This document describes the supply chain security practices for `lambda-deadline-middleware`.
+
+## Provenance Verification
+
+Every published release includes SLSA Level 3 provenance attestation, generated
+automatically by GitHub Actions using the `--provenance` flag during `npm publish`.
+
+### Verifying provenance
+
+```bash
+npm audit signatures
+```
+
+This command verifies that the package was:
+
+- Built from the source repository (not a compromised local machine)
+- Published by the expected GitHub Actions workflow
+- Signed with a valid sigstore certificate tied to the workflow identity
+
+You can also inspect the provenance bundle directly:
+
+```bash
+npm provenance --package-name lambda-deadline-middleware
+```
+
+## SBOM (Software Bill of Materials)
+
+Each release includes a CycloneDX SBOM (`sbom.cdx.json`) attached as a GitHub
+Release asset. The SBOM lists all runtime and development dependencies with their
+versions, providing full transparency into the package's dependency tree.
+
+### Generating the SBOM locally
+
+```bash
+pnpm run sbom
+```
+
+This produces `sbom.cdx.json` in the project root using pnpm's native CycloneDX SBOM generation.
+
+### SBOM format
+
+- **Specification**: CycloneDX v1.5
+- **Format**: JSON
+- **Tool**: `pnpm sbom` (native, since pnpm 11)
+- **Contents**: Component inventory including direct and transitive dependencies
+
+## Sigstore Signing
+
+All published artifacts are signed using **keyless sigstore signing** via OIDC
+identity federation. This means:
+
+- **No long-lived signing keys**: Signing happens via short-lived certificates
+  issued by Fulcio, tied to the GitHub Actions OIDC identity.
+- **Transparency log**: All signatures are recorded in the Rekor transparency log,
+  providing a tamper-evident audit trail.
+- **Verification without publisher keys**: Consumers verify signatures using the
+  sigstore root of trust, not a publisher-managed key.
+
+### How it works in CI
+
+1. The GitHub Actions release workflow requests an OIDC token from GitHub.
+2. The OIDC token is exchanged with Fulcio for a short-lived signing certificate.
+3. The npm package is signed with the certificate during `npm publish --provenance`.
+4. The signature and certificate are recorded in the Rekor transparency log.
+5. npm stores the provenance bundle alongside the package tarball.
+
+### Verifying signatures
+
+Signature verification is automatic when running `npm audit signatures`. The npm
+CLI checks:
+
+- The certificate was issued by Fulcio
+- The OIDC identity matches the expected repository and workflow
+- The signature is recorded in the Rekor transparency log
+- The package content matches the signed digest
+
+## Reporting Vulnerabilities
+
+If you discover a security vulnerability in this package, please report it
+responsibly by opening a [GitHub Security Advisory](https://github.com/mikkopiu/lambda-deadline-middleware/security/advisories/new) on this repository. Do not
+file a public issue for security vulnerabilities.
+
+### Response Timeline
+
+We aim to acknowledge vulnerability reports within 72 hours. For critical
+issues, we target a fix or mitigation plan within 14 days. Lower-severity
+issues are addressed as part of normal maintenance cycles.
+
+Resolved vulnerabilities are disclosed publicly via GitHub Security Advisories
+once a fix is released.

package/dist/config.d.ts

@@ -0,0 +1,4 @@
+import type { DeadlineMiddlewareConfig, DeadlineOptions } from "./types.js";
+export declare function parseConfig(raw: DeadlineOptions | undefined): DeadlineMiddlewareConfig;
+
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"mappings":"AAIA,cAAc,0BAA0B,uBAAuB;AAE/D,OAAO,iBAAS,YAAY,KAAK,8BAA8B","names":[],"sources":["src/config.ts"],"version":3,"sourcesContent":["// SPDX-FileCopyrightText: 2024 lambda-deadline-middleware contributors\n// SPDX-License-Identifier: MIT\n\nimport { flushBufferMs } from \"./types.js\";\nimport type { DeadlineMiddlewareConfig, DeadlineOptions } from \"./types.js\";\n\nexport function parseConfig(raw: DeadlineOptions | undefined): DeadlineMiddlewareConfig {\n  const buffer = raw?.flushBufferMs ?? 1000;\n  if (buffer < 0) {\n    throw new TypeError(`flushBufferMs option must be non-negative, received: ${buffer}`);\n  }\n  return {\n    flushBufferMs: flushBufferMs(buffer),\n    telemetryEnabled: raw?.telemetryEnabled ?? true,\n  };\n}\n"]}

package/dist/config.js

@@ -0,0 +1,15 @@
+// SPDX-FileCopyrightText: 2024 lambda-deadline-middleware contributors
+// SPDX-License-Identifier: MIT
+import { flushBufferMs } from "./types.js";
+export function parseConfig(raw) {
+	const buffer = raw?.flushBufferMs ?? 1e3;
+	if (buffer < 0) {
+		throw new TypeError(`flushBufferMs option must be non-negative, received: ${buffer}`);
+	}
+	return {
+		flushBufferMs: flushBufferMs(buffer),
+		telemetryEnabled: raw?.telemetryEnabled ?? true
+	};
+}
+
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"mappings":";;AAGA,SAAS,qBAAqB;AAG9B,OAAO,SAAS,YAAY,KAA4D;CACtF,MAAM,SAAS,KAAK,iBAAiB;CACrC,IAAI,SAAS,GAAG;EACd,MAAM,IAAI,UAAU,wDAAwD,QAAQ;CACtF;CACA,OAAO;EACL,eAAe,cAAc,MAAM;EACnC,kBAAkB,KAAK,oBAAoB;CAC7C;AACF","names":[],"sources":["src/config.ts"],"version":3,"sourcesContent":["// SPDX-FileCopyrightText: 2024 lambda-deadline-middleware contributors\n// SPDX-License-Identifier: MIT\n\nimport { flushBufferMs } from \"./types.js\";\nimport type { DeadlineMiddlewareConfig, DeadlineOptions } from \"./types.js\";\n\nexport function parseConfig(raw: DeadlineOptions | undefined): DeadlineMiddlewareConfig {\n  const buffer = raw?.flushBufferMs ?? 1000;\n  if (buffer < 0) {\n    throw new TypeError(`flushBufferMs option must be non-negative, received: ${buffer}`);\n  }\n  return {\n    flushBufferMs: flushBufferMs(buffer),\n    telemetryEnabled: raw?.telemetryEnabled ?? true,\n  };\n}\n"]}

package/dist/context-store.d.ts

@@ -0,0 +1,7 @@
+export interface LambdaContextLike {
+	getRemainingTimeInMillis?: () => number;
+}
+export declare function run<T>(context: LambdaContextLike | null | undefined, fn: () => T): T;
+export declare function getRemainingTimeInMillis(): number | undefined;
+
+//# sourceMappingURL=context-store.d.ts.map

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

@@ -0,0 +1 @@
+{"mappings":"AAKA,iBAAiB,kBAAkB;CACjC;AACF;AAWA,OAAO,iBAAS,IAAI,GAAG,SAAS,sCAAsC,UAAU,IAAI;AAKpF,OAAO,iBAAS","names":[],"sources":["src/context-store.ts"],"version":3,"sourcesContent":["// SPDX-FileCopyrightText: 2024 lambda-deadline-middleware contributors\n// SPDX-License-Identifier: MIT\n\nimport { AsyncLocalStorage } from \"node:async_hooks\";\n\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 function 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 function 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"]}

package/dist/context-store.js

@@ -0,0 +1,24 @@
+// SPDX-FileCopyrightText: 2024 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");
+const contextStorage = new AsyncLocalStorage();
+export function run(context, fn) {
+	const value = context ?? NO_CONTEXT;
+	return contextStorage.run(value, fn);
+}
+export function getRemainingTimeInMillis() {
+	const store = contextStorage.getStore();
+	if (store === undefined || store === NO_CONTEXT) {
+		return undefined;
+	}
+	if (typeof store.getRemainingTimeInMillis !== "function") {
+		return undefined;
+	}
+	return store.getRemainingTimeInMillis();
+}
+
+//# sourceMappingURL=context-store.js.map

package/dist/context-store.js.map

@@ -0,0 +1 @@
+{"mappings":";;AAGA,SAAS,yBAAyB;;;;AASlC,MAAM,aAA4B,OAAO,YAAY;AAIrD,MAAM,iBAAiB,IAAI,kBAA8B;AAEzD,OAAO,SAAS,IAAO,SAA+C,IAAgB;CACpF,MAAM,QAAoB,WAAW;CACrC,OAAO,eAAe,IAAI,OAAO,EAAE;AACrC;AAEA,OAAO,SAAS,2BAA+C;CAC7D,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: 2024 lambda-deadline-middleware contributors\n// SPDX-License-Identifier: MIT\n\nimport { AsyncLocalStorage } from \"node:async_hooks\";\n\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 function 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 function 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"]}

package/dist/error.d.ts

@@ -0,0 +1,17 @@
+import type { FlushBufferMs, Milliseconds } from "./types.js";
+interface DeadlineExceededInit {
+	readonly deadlineMs: Milliseconds;
+	readonly flushBufferMs: FlushBufferMs;
+	readonly remainingMs: Milliseconds;
+}
+export declare class DeadlineExceededError extends Error {
+	override readonly name = "DeadlineExceededError";
+	readonly deadlineMs: Milliseconds;
+	readonly flushBufferMs: FlushBufferMs;
+	readonly remainingMs: Milliseconds;
+	constructor(init: DeadlineExceededInit);
+}
+export declare function isDeadlineExceeded(error: unknown): error is DeadlineExceededError;
+export {};
+
+//# sourceMappingURL=error.d.ts.map

package/dist/error.d.ts.map

@@ -0,0 +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,iBAAS,mBAAmB,iBAAiB,SAAS","names":[],"sources":["src/error.ts"],"version":3,"sourcesContent":["// SPDX-FileCopyrightText: 2024 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 function 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

@@ -0,0 +1,21 @@
+export class DeadlineExceededError extends Error {
+	name = "DeadlineExceededError";
+	deadlineMs;
+	flushBufferMs;
+	remainingMs;
+	constructor(init) {
+		super(`Request deadline exceeded: ${init.deadlineMs}ms deadline (${init.flushBufferMs}ms flush buffer)`);
+		this.deadlineMs = init.deadlineMs;
+		this.flushBufferMs = init.flushBufferMs;
+		this.remainingMs = init.remainingMs;
+	}
+}
+// Structural check rather than instanceof — works across module boundaries
+// and serialization boundaries where prototype chain may be broken.
+export function isDeadlineExceeded(error) {
+	if (error === null || error === undefined) return false;
+	if (typeof error !== "object") return false;
+	return error.name === "DeadlineExceededError";
+}
+
+//# sourceMappingURL=error.js.map

package/dist/error.js.map

@@ -0,0 +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,SAAS,mBAAmB,OAAgD;CACjF,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: 2024 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 function 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/handler-wrapper.d.ts

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

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

@@ -0,0 +1 @@
+{"mappings":"AAIA,cAAc,yBAAyB;AACvC,cAAc,uBAAuB;KAEhC;CAAa;CAAQ;KACxB,OAAO,QACP,SAAS,sBACN,QAAQ;AAEb,OAAO,iBAAS;CAAmB;CAAQ;EACzC,SAAS,aAAa,QAAQ,UAC9B,WAAW,kBACV,aAAa,QAAQ","names":[],"sources":["src/handler-wrapper.ts"],"version":3,"sourcesContent":["// SPDX-FileCopyrightText: 2024 lambda-deadline-middleware contributors\n// SPDX-License-Identifier: MIT\n\nimport { run } from \"./context-store.js\";\nimport type { LambdaContextLike } from \"./context-store.js\";\nimport type { DeadlineOptions } from \"./types.js\";\n\ntype AsyncHandler<TEvent, TResult> = (\n  event: TEvent,\n  context: LambdaContextLike,\n) => Promise<TResult>;\n\nexport function withLambdaDeadline<TEvent, TResult>(\n  handler: AsyncHandler<TEvent, TResult>,\n  _options?: DeadlineOptions,\n): AsyncHandler<TEvent, TResult> {\n  return async (event: TEvent, context: LambdaContextLike): Promise<TResult> =>\n    run(context, async () => handler(event, context));\n}\n"]}

package/dist/handler-wrapper.js

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

package/dist/handler-wrapper.js.map

@@ -0,0 +1 @@
+{"mappings":";;AAGA,SAAS,WAAW;AASpB,OAAO,SAAS,mBACd,SACA,UAC+B;CAC/B,OAAO,OAAO,OAAe,YAC3B,IAAI,SAAS,YAAY,QAAQ,OAAO,OAAO,CAAC;AACpD","names":[],"sources":["src/handler-wrapper.ts"],"version":3,"sourcesContent":["// SPDX-FileCopyrightText: 2024 lambda-deadline-middleware contributors\n// SPDX-License-Identifier: MIT\n\nimport { run } from \"./context-store.js\";\nimport type { LambdaContextLike } from \"./context-store.js\";\nimport type { DeadlineOptions } from \"./types.js\";\n\ntype AsyncHandler<TEvent, TResult> = (\n  event: TEvent,\n  context: LambdaContextLike,\n) => Promise<TResult>;\n\nexport function withLambdaDeadline<TEvent, TResult>(\n  handler: AsyncHandler<TEvent, TResult>,\n  _options?: DeadlineOptions,\n): AsyncHandler<TEvent, TResult> {\n  return async (event: TEvent, context: LambdaContextLike): Promise<TResult> =>\n    run(context, async () => handler(event, context));\n}\n"]}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { withLambdaDeadline } from "./handler-wrapper.js";
+export { deadlineMiddleware, withDeadline } from "./registration.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 { LambdaContextLike } from "./context-store.js";
+
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"mappings":"AAGA,SAAS,0BAA0B;AACnC,SAAS,oBAAoB,oBAAoB;AACjD,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: 2024 lambda-deadline-middleware contributors\n// SPDX-License-Identifier: MIT\n\nexport { withLambdaDeadline } from \"./handler-wrapper.js\";\nexport { deadlineMiddleware, withDeadline } 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"]}

package/dist/index.js

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

package/dist/index.js.map

@@ -0,0 +1 @@
+{"mappings":";;AAGA,SAAS,0BAA0B;AACnC,SAAS,oBAAoB,oBAAoB;AACjD,SAAS,uBAAuB,0BAA0B;AAC1D,SAAS,gCAAgC","names":[],"sources":["src/index.ts"],"version":3,"sourcesContent":["// SPDX-FileCopyrightText: 2024 lambda-deadline-middleware contributors\n// SPDX-License-Identifier: MIT\n\nexport { withLambdaDeadline } from \"./handler-wrapper.js\";\nexport { deadlineMiddleware, withDeadline } 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"]}

package/dist/middleware.d.ts

@@ -0,0 +1,12 @@
+import type { DeadlineComputation, DeadlineMiddlewareConfig, RequestDeadlineMs } from "./types.js";
+import type { FinalizeRequestMiddleware } from "@smithy/types";
+export declare function computeDeadline(config: DeadlineMiddlewareConfig): DeadlineComputation;
+export interface DeadlineTimer {
+	readonly controller: AbortController;
+	[Symbol.dispose]: () => void;
+}
+export declare function createDeadlineTimer(deadlineMs: RequestDeadlineMs, config: DeadlineMiddlewareConfig): DeadlineTimer;
+export declare function composeSignals(existing: AbortSignal | undefined, deadline: AbortSignal): AbortSignal;
+export declare function deadlineMiddlewareHandler(config: DeadlineMiddlewareConfig): FinalizeRequestMiddleware<object, object>;
+
+//# sourceMappingURL=middleware.d.ts.map

package/dist/middleware.d.ts.map

@@ -0,0 +1 @@
+{"mappings":"AAKA,cAAc,qBAAqB,0BAA0B,yBAAyB;AAGtF,cAIE,iCAEK;AAEP,OAAO,iBAAS,gBAAgB,QAAQ,2BAA2B;AAqBnE,iBAAiB,cAAc;UACpB,YAAY;EACpB,OAAO;AACV;AAEA,OAAO,iBAAS,oBACd,YAAY,mBACZ,QAAQ,2BACP;AAmBH,OAAO,iBAAS,eACd,UAAU,yBACV,UAAU,cACT;AAKH,OAAO,iBAAS,0BACd,QAAQ,2BACP","names":[],"sources":["src/middleware.ts"],"version":3,"sourcesContent":["// SPDX-FileCopyrightText: 2024 lambda-deadline-middleware contributors\n// SPDX-License-Identifier: MIT\n\nimport { getRemainingTimeInMillis } from \"./context-store.js\";\nimport { DeadlineExceededError } from \"./error.js\";\nimport type { DeadlineComputation, DeadlineMiddlewareConfig, RequestDeadlineMs } from \"./types.js\";\nimport { milliseconds } from \"./types.js\";\n\nimport type {\n  FinalizeHandler,\n  FinalizeHandlerArguments,\n  FinalizeHandlerOutput,\n  FinalizeRequestMiddleware,\n  HandlerExecutionContext,\n} from \"@smithy/types\";\n\nexport function computeDeadline(config: DeadlineMiddlewareConfig): DeadlineComputation {\n  const remaining = getRemainingTimeInMillis();\n\n  if (remaining === undefined) {\n    return { kind: \"no-context\" };\n  }\n\n  const deadline = remaining - config.flushBufferMs;\n\n  if (deadline <= 0) {\n    return {\n      kind: \"insufficient-time\",\n      remaining: milliseconds(remaining),\n      buffer: config.flushBufferMs,\n    };\n  }\n\n  // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- branded narrowing: deadline is validated > 0 above\n  return { kind: \"deadline\", value: deadline as RequestDeadlineMs };\n}\n\nexport interface DeadlineTimer {\n  readonly controller: AbortController;\n  [Symbol.dispose]: () => void;\n}\n\nexport function createDeadlineTimer(\n  deadlineMs: RequestDeadlineMs,\n  config: DeadlineMiddlewareConfig,\n): DeadlineTimer {\n  const controller = new AbortController();\n  const remaining = milliseconds(deadlineMs + config.flushBufferMs);\n  const error = new DeadlineExceededError({\n    deadlineMs: milliseconds(deadlineMs),\n    flushBufferMs: config.flushBufferMs,\n    remainingMs: remaining,\n  });\n  const timeoutId = setTimeout(() => {\n    controller.abort(error);\n  }, deadlineMs);\n  return {\n    controller,\n    [Symbol.dispose]() {\n      clearTimeout(timeoutId);\n    },\n  };\n}\n\nexport function 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 function deadlineMiddlewareHandler(\n  config: DeadlineMiddlewareConfig,\n): FinalizeRequestMiddleware<object, object> {\n  return (\n    next: FinalizeHandler<object, object>,\n    _context: HandlerExecutionContext,\n  ): FinalizeHandler<object, object> =>\n    // oxlint-disable-next-line typescript/consistent-return -- switch is exhaustive over DeadlineComputation discriminated union\n    async (args: FinalizeHandlerArguments<object>): Promise<FinalizeHandlerOutput<object>> => {\n      const computation = computeDeadline(config);\n\n      switch (computation.kind) {\n        case \"no-context\":\n          return next(args);\n\n        case \"insufficient-time\":\n          throw new DeadlineExceededError({\n            deadlineMs: milliseconds(0),\n            flushBufferMs: computation.buffer,\n            remainingMs: computation.remaining,\n          });\n\n        case \"deadline\": {\n          using timer = createDeadlineTimer(computation.value, config);\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, timer.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    };\n}\n"]}