lambda-deadline-middleware 0.0.0 → 1.0.1

package/package.json

@@ -1,12 +1,18 @@
 {
   "name": "lambda-deadline-middleware",
-  "version": "0.0.0",
+  "version": "1.0.1",
   "description": "AWS SDK v3 middleware for automatic Lambda deadline propagation via AbortController-based timeouts",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mikkopiu/lambda-deadline-middleware"
+  },
   "files": [
     "dist",
     "src",
     "LICENSE",
+    "LICENSES",
+    "REUSE.toml",
     "SECURITY.md"
   ],
   "type": "module",
@@ -20,28 +26,47 @@
     "access": "public",
     "provenance": true
   },
+  "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",
+    "typecheck": "tsc",
+    "lint": "oxlint --type-aware --type-check --fix .",
+    "lint:check": "oxlint --type-aware --type-check .",
+    "fmt": "oxfmt .",
+    "fmt:check": "oxfmt --check .",
+    "lint:knip": "knip",
+    "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",
+    "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",
+    "sbom": "pnpm sbom --sbom-format cyclonedx --sbom-spec-version 1.5 --sbom-type library > sbom.cdx.json",
+    "release": "semantic-release"
+  },
   "devDependencies": {
-    "@aws-sdk/client-dynamodb": "^3.1062.0",
-    "@aws-sdk/client-s3": "^3.1062.0",
-    "@aws-sdk/client-sqs": "^3.1062.0",
+    "@aws-sdk/client-dynamodb": "^3.1064.0",
+    "@aws-sdk/client-s3": "^3.1064.0",
+    "@aws-sdk/client-sqs": "^3.1064.0",
     "@commitlint/cli": "^21.0.2",
     "@commitlint/config-conventional": "^21.0.2",
     "@fast-check/vitest": "^0.4.1",
-    "@semantic-release/changelog": "6.0.3",
     "@semantic-release/commit-analyzer": "13.0.1",
-    "@semantic-release/git": "10.0.1",
     "@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.1",
+    "@types/node": "^25.9.2",
     "@vitest/coverage-v8": "^4.1.8",
     "conventional-changelog-conventionalcommits": "^9.3.1",
-    "knip": "^6.15.0",
+    "knip": "^6.16.1",
     "lefthook": "^2.1.9",
     "oxc-transform": "^0.134.0",
     "oxfmt": "^0.53.0",
-    "oxlint": "^1.68.0",
+    "oxlint": "^1.69.0",
     "oxlint-tsgolint": "^0.23.0",
     "semantic-release": "25.0.3",
     "typescript": "^6.0.3",
@@ -50,24 +75,5 @@
   "engines": {
     "node": ">=24"
   },
-  "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",
-    "typecheck": "tsc",
-    "lint": "oxlint --type-aware --type-check --fix .",
-    "lint:check": "oxlint --type-aware --type-check .",
-    "fmt": "oxfmt .",
-    "fmt:check": "oxfmt --check .",
-    "lint:knip": "knip",
-    "sast": "scripts/ensure-opengrep.sh scan .",
-    "sast:check": "scripts/ensure-opengrep.sh scan --error .",
-    "sca": "podman run --rm -v \"$(pwd):/src: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\" ghcr.io/aquasecurity/trivy:0.71.0@sha256:016eae51fdcf989332a5404af7e8f625cd5d95d7c0907a221d080a996f556500 fs --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",
-    "sbom": "pnpm sbom --sbom-format cyclonedx --sbom-spec-version 1.5 --sbom-type library > sbom.cdx.json",
-    "release": "semantic-release"
-  }
-}
+  "packageManager": "pnpm@11.5.2+sha512.71c631e382066efc25625d5cf029075de07b61b37f6e27350fbd84b1bda5864c8c1967adc280776b45c30a715c0359a3be08fef42d5bb09e2b99029979692916"
+}

package/src/config.ts

@@ -1,10 +1,12 @@
-// SPDX-FileCopyrightText: 2024 lambda-deadline-middleware contributors
+// SPDX-FileCopyrightText: 2026 lambda-deadline-middleware contributors
 // SPDX-License-Identifier: MIT
 
 import { flushBufferMs } from "./types.js";
 import type { DeadlineMiddlewareConfig, DeadlineOptions } from "./types.js";
 
-export function parseConfig(raw: DeadlineOptions | undefined): DeadlineMiddlewareConfig {
+// "Parse, don't validate": config is validated once here and returned as branded types.
+// Internal code can't receive unvalidated values. Invalid config throws TypeError at startup, not during requests.
+export const parseConfig = (raw: DeadlineOptions | undefined): DeadlineMiddlewareConfig => {
   const buffer = raw?.flushBufferMs ?? 1000;
   if (buffer < 0) {
     throw new TypeError(`flushBufferMs option must be non-negative, received: ${buffer}`);
@@ -13,4 +15,4 @@ export function parseConfig(raw: DeadlineOptions | undefined): DeadlineMiddlewar
     flushBufferMs: flushBufferMs(buffer),
     telemetryEnabled: raw?.telemetryEnabled ?? true,
   };
-}
+};

package/src/context-store.ts

@@ -1,8 +1,10 @@
-// SPDX-FileCopyrightText: 2024 lambda-deadline-middleware contributors
+// SPDX-FileCopyrightText: 2026 lambda-deadline-middleware contributors
 // SPDX-License-Identifier: MIT
 
 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.
 export interface LambdaContextLike {
   getRemainingTimeInMillis?: () => number;
 }
@@ -16,12 +18,12 @@ type StoreValue = LambdaContextLike | typeof NO_CONTEXT;
 
 const contextStorage = new AsyncLocalStorage<StoreValue>();
 
-export function run<T>(context: LambdaContextLike | null | undefined, fn: () => T): T {
+export const run = <T>(context: LambdaContextLike | null | undefined, fn: () => T): T => {
   const value: StoreValue = context ?? NO_CONTEXT;
   return contextStorage.run(value, fn);
-}
+};
 
-export function getRemainingTimeInMillis(): number | undefined {
+export const getRemainingTimeInMillis = (): number | undefined => {
   const store = contextStorage.getStore();
 
   if (store === undefined || store === NO_CONTEXT) {
@@ -33,4 +35,4 @@ export function getRemainingTimeInMillis(): number | undefined {
   }
 
   return store.getRemainingTimeInMillis();
-}
+};

package/src/error.ts

@@ -1,4 +1,4 @@
-// SPDX-FileCopyrightText: 2024 lambda-deadline-middleware contributors
+// SPDX-FileCopyrightText: 2026 lambda-deadline-middleware contributors
 // SPDX-License-Identifier: MIT
 
 import type { FlushBufferMs, Milliseconds } from "./types.js";
@@ -27,8 +27,8 @@ export class DeadlineExceededError extends Error {
 
 // Structural check rather than instanceof — works across module boundaries
 // and serialization boundaries where prototype chain may be broken.
-export function isDeadlineExceeded(error: unknown): error is DeadlineExceededError {
+export const isDeadlineExceeded = (error: unknown): error is DeadlineExceededError => {
   if (error === null || error === undefined) return false;
   if (typeof error !== "object") return false;
   return (error as { name?: unknown }).name === "DeadlineExceededError";
-}
+};

package/src/handler-wrapper.ts

@@ -1,4 +1,4 @@
-// SPDX-FileCopyrightText: 2024 lambda-deadline-middleware contributors
+// SPDX-FileCopyrightText: 2026 lambda-deadline-middleware contributors
 // SPDX-License-Identifier: MIT
 
 import { run } from "./context-store.js";
@@ -10,10 +10,10 @@ type AsyncHandler<TEvent, TResult> = (
   context: LambdaContextLike,
 ) => Promise<TResult>;
 
-export function withLambdaDeadline<TEvent, TResult>(
-  handler: AsyncHandler<TEvent, TResult>,
-  _options?: DeadlineOptions,
-): AsyncHandler<TEvent, TResult> {
-  return async (event: TEvent, context: LambdaContextLike): Promise<TResult> =>
+export const withLambdaDeadline =
+  <TEvent, TResult>(
+    handler: AsyncHandler<TEvent, TResult>,
+    _options?: DeadlineOptions,
+  ): AsyncHandler<TEvent, TResult> =>
+  async (event: TEvent, context: LambdaContextLike): Promise<TResult> =>
     run(context, async () => handler(event, context));
-}

package/src/index.ts

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

package/src/middleware.ts

@@ -1,4 +1,4 @@
-// SPDX-FileCopyrightText: 2024 lambda-deadline-middleware contributors
+// SPDX-FileCopyrightText: 2026 lambda-deadline-middleware contributors
 // SPDX-License-Identifier: MIT
 
 import { getRemainingTimeInMillis } from "./context-store.js";
@@ -14,7 +14,7 @@ import type {
   HandlerExecutionContext,
 } from "@smithy/types";
 
-export function computeDeadline(config: DeadlineMiddlewareConfig): DeadlineComputation {
+export const computeDeadline = (config: DeadlineMiddlewareConfig): DeadlineComputation => {
   const remaining = getRemainingTimeInMillis();
 
   if (remaining === undefined) {
@@ -33,17 +33,17 @@ export function computeDeadline(config: DeadlineMiddlewareConfig): DeadlineCompu
 
   // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- branded narrowing: deadline is validated > 0 above
   return { kind: "deadline", value: deadline as RequestDeadlineMs };
-}
+};
 
 export interface DeadlineTimer {
   readonly controller: AbortController;
   [Symbol.dispose]: () => void;
 }
 
-export function createDeadlineTimer(
+export const createDeadlineTimer = (
   deadlineMs: RequestDeadlineMs,
   config: DeadlineMiddlewareConfig,
-): DeadlineTimer {
+): DeadlineTimer => {
   const controller = new AbortController();
   const remaining = milliseconds(deadlineMs + config.flushBufferMs);
   const error = new DeadlineExceededError({
@@ -60,50 +60,52 @@ export function createDeadlineTimer(
       clearTimeout(timeoutId);
     },
   };
-}
+};
 
-export function composeSignals(
+export const composeSignals = (
   existing: AbortSignal | undefined,
   deadline: AbortSignal,
-): AbortSignal {
+): AbortSignal => {
   if (existing === undefined) return deadline;
   return AbortSignal.any([existing, deadline]);
-}
+};
 
-export function deadlineMiddlewareHandler(
-  config: DeadlineMiddlewareConfig,
-): FinalizeRequestMiddleware<object, object> {
-  return (
-    next: FinalizeHandler<object, object>,
+export const deadlineMiddlewareHandler =
+  <Input extends object, Output extends object>(
+    config: DeadlineMiddlewareConfig,
+  ): FinalizeRequestMiddleware<Input, Output> =>
+  (
+    next: FinalizeHandler<Input, Output>,
     _context: HandlerExecutionContext,
-  ): FinalizeHandler<object, object> =>
-    // oxlint-disable-next-line typescript/consistent-return -- switch is exhaustive over DeadlineComputation discriminated union
-    async (args: FinalizeHandlerArguments<object>): Promise<FinalizeHandlerOutput<object>> => {
-      const computation = computeDeadline(config);
+  ): FinalizeHandler<Input, Output> =>
+  // oxlint-disable-next-line typescript/consistent-return -- switch is exhaustive over DeadlineComputation discriminated union
+  async (args: FinalizeHandlerArguments<Input>): Promise<FinalizeHandlerOutput<Output>> => {
+    const computation = computeDeadline(config);
 
-      switch (computation.kind) {
-        case "no-context":
-          return next(args);
+    switch (computation.kind) {
+      case "no-context":
+        return next(args);
 
-        case "insufficient-time":
-          throw new DeadlineExceededError({
-            deadlineMs: milliseconds(0),
-            flushBufferMs: computation.buffer,
-            remainingMs: computation.remaining,
-          });
+      case "insufficient-time":
+        throw new DeadlineExceededError({
+          deadlineMs: milliseconds(0),
+          flushBufferMs: computation.buffer,
+          remainingMs: computation.remaining,
+        });
 
-        case "deadline": {
-          using timer = createDeadlineTimer(computation.value, config);
-          // 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, timer.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;
-        }
+      case "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 = createDeadlineTimer(computation.value, config);
+        // 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, timer.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;
       }
-    };
-}
+    }
+  };

package/src/registration.ts

@@ -1,4 +1,4 @@
-// SPDX-FileCopyrightText: 2024 lambda-deadline-middleware contributors
+// SPDX-FileCopyrightText: 2026 lambda-deadline-middleware contributors
 // SPDX-License-Identifier: MIT
 
 import type { Pluggable } from "@smithy/types";
@@ -7,30 +7,21 @@ import { parseConfig } from "./config.js";
 import { deadlineMiddlewareHandler } from "./middleware.js";
 import type { DeadlineOptions } from "./types.js";
 
-export function deadlineMiddleware(options?: DeadlineOptions): Pluggable<object, object> {
+export const deadlineMiddleware = <Input extends object, Output extends object>(
+  options?: DeadlineOptions,
+): Pluggable<Input, Output> => {
   const config = parseConfig(options);
 
   return {
     applyToStack(stack) {
-      stack.add(deadlineMiddlewareHandler(config), {
+      // 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(deadlineMiddlewareHandler<Input, Output>(config), {
         step: "finalizeRequest",
         name: "deadlineMiddleware",
         override: true,
       });
     },
   };
-}
-
-// WeakSet allows GC of discarded clients in long-running processes
-// while still preventing duplicate middleware registration.
-const registeredClients = new WeakSet<object>();
-
-export function withDeadline<
-  // oxlint-disable-next-line typescript/no-explicit-any -- AWS SDK clients use varying ServiceInput/OutputTypes generics, making `any` the only correct constraint here
-  T extends { middlewareStack: { use: (pluggable: Pluggable<any, any>) => void } },
->(client: T, options?: DeadlineOptions): T {
-  if (registeredClients.has(client)) return client;
-  registeredClients.add(client);
-  client.middlewareStack.use(deadlineMiddleware(options));
-  return client;
-}
+};

package/src/telemetry.ts

@@ -1,9 +1,12 @@
-// SPDX-FileCopyrightText: 2024 lambda-deadline-middleware contributors
+// SPDX-FileCopyrightText: 2026 lambda-deadline-middleware contributors
 // SPDX-License-Identifier: MIT
 
 import type { DeadlineExceededError } from "./error.js";
 import type { DeadlineMiddlewareConfig } from "./types.js";
 
+// OpenTelemetry is detected dynamically rather than declared as a peerDependency.
+// This avoids forcing all consumers to install @opentelemetry/api or suppress peer warnings.
+// Detection happens once at first use and the result is cached for the process lifetime.
 interface AbortDetails {
   readonly deadlineMs: number;
   readonly flushBufferMs: number;
@@ -18,7 +21,7 @@ interface TelemetryEmitter {
 let emitter: TelemetryEmitter | undefined;
 let detected = false;
 
-async function detectEmitter(): Promise<TelemetryEmitter | undefined> {
+const detectEmitter = async (): Promise<TelemetryEmitter | undefined> => {
   if (detected) return emitter;
   detected = true;
 
@@ -104,12 +107,12 @@ async function detectEmitter(): Promise<TelemetryEmitter | undefined> {
   }
 
   return emitter;
-}
+};
 
-export async function emitDeadlineAbort(
+export const emitDeadlineAbort = async (
   error: DeadlineExceededError,
   config: DeadlineMiddlewareConfig,
-): Promise<void> {
+): Promise<void> => {
   try {
     if (!config.telemetryEnabled) return;
 
@@ -126,4 +129,4 @@ export async function emitDeadlineAbort(
   } catch {
     // Telemetry must never disrupt request processing
   }
-}
+};

package/src/types.ts

@@ -1,6 +1,8 @@
-// SPDX-FileCopyrightText: 2024 lambda-deadline-middleware contributors
+// SPDX-FileCopyrightText: 2026 lambda-deadline-middleware contributors
 // SPDX-License-Identifier: MIT
 
+// Branded types prevent interchange errors at compile time (e.g. passing seconds where milliseconds are expected).
+// Zero runtime cost. Smart constructors below validate at the boundary and brand the value.
 declare const BrandSymbol: unique symbol;
 
 type Brand<T, B extends string> = T & { readonly [BrandSymbol]: B };
@@ -11,15 +13,15 @@ export type FlushBufferMs = Brand<number, "FlushBufferMs">;
 
 export type RequestDeadlineMs = Brand<number, "RequestDeadlineMs">;
 
-export function milliseconds(value: 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 function flushBufferMs(value: number): FlushBufferMs {
+export const flushBufferMs = (value: number): FlushBufferMs => {
   if (!Number.isFinite(value)) {
     throw new TypeError(`flushBufferMs value must be finite, received: ${value}`);
   }
@@ -28,7 +30,7 @@ export function flushBufferMs(value: number): FlushBufferMs {
   }
   // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- branded type constructor: value is validated above
   return value as FlushBufferMs;
-}
+};
 
 export type DeadlineComputation =
   | { readonly kind: "deadline"; readonly value: RequestDeadlineMs }