@oncely/express 1.0.0

package/README.md

@@ -0,0 +1,49 @@
+# @oncely/express
+
+Express middleware for oncely idempotency.
+
+## Installation
+
+npm install @oncely/core @oncely/express
+
+## Usage
+
+import express from 'express';
+import { express as idempotent, configure } from '@oncely/express';
+
+const app = express();
+
+// Zero-config (uses memory storage)
+app.post('/orders', idempotent(), async (req, res) => {
+res.status(201).json(await createOrder(req.body));
+});
+
+// With options
+app.post('/payments', idempotent({
+required: true,
+ttl: '1h',
+}), paymentHandler);
+
+// Pre-configured factory
+import { redis } from '@oncely/redis';
+
+const idempotent = configure({
+storage: redis(),
+ttl: '1h',
+});
+
+app.post('/orders', idempotent(), orderHandler);
+app.post('/payments', idempotent({ required: true }), paymentHandler);
+
+## Headers
+
+Request: Idempotency-Key
+Response: Idempotency-Key, Idempotency-Replay (on cache hit)
+
+## License
+
+MIT
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,263 @@
+'use strict';
+
+var core = require('@oncely/core');
+
+// src/index.ts
+var PROBLEM_BASE = "https://oncely.dev/errors";
+var IDEMPOTENCY_KEY_HEADER = "Idempotency-Key";
+var IDEMPOTENCY_REPLAY_HEADER = "Idempotency-Replay";
+var defaultStorage = null;
+function getStorage(provided) {
+  if (provided) return provided;
+  if (!defaultStorage) {
+    defaultStorage = new core.MemoryStorage();
+  }
+  return defaultStorage;
+}
+function express(options = {}) {
+  const {
+    storage: providedStorage,
+    ttl = "24h",
+    required = false,
+    methods = ["POST", "PUT", "PATCH", "DELETE"],
+    getKey = (req) => req.get(IDEMPOTENCY_KEY_HEADER),
+    getHash = (req) => req.body ? core.hashObject(req.body) : null,
+    includeHeaders = true,
+    debug = false,
+    failOpen = false,
+    onHit,
+    onMiss,
+    onError
+  } = options;
+  const storage = getStorage(providedStorage);
+  const ttlMs = core.parseTtl(ttl);
+  const log = (message) => {
+    if (debug) {
+      console.log(`[oncely/express] ${message}`);
+    }
+  };
+  return async (req, res, next) => {
+    if (!methods.includes(req.method)) {
+      return next();
+    }
+    const key = getKey(req);
+    if (!key && !required) {
+      return next();
+    }
+    if (!key && required) {
+      if (includeHeaders) {
+        res.set("Content-Type", "application/problem+json");
+      }
+      res.status(400).json({
+        type: `${PROBLEM_BASE}/key-required`,
+        title: "Idempotency Key Required",
+        status: 400,
+        detail: `The ${IDEMPOTENCY_KEY_HEADER} header is required for this request.`
+      });
+      return;
+    }
+    const hash = getHash(req);
+    try {
+      log(`Acquiring lock for key: ${key}`);
+      let result;
+      try {
+        result = await storage.acquire(key, hash, ttlMs);
+      } catch (storageErr) {
+        if (failOpen) {
+          log(`Storage error for key: ${key}, failing open`);
+          onError?.(key, storageErr);
+          return next();
+        }
+        throw storageErr;
+      }
+      if (result.status === "hit") {
+        log(`Cache hit for key: ${key}`);
+        onHit?.(key, result.response);
+        const cached = result.response.data;
+        if (includeHeaders) {
+          res.set(IDEMPOTENCY_KEY_HEADER, key);
+          res.set(IDEMPOTENCY_REPLAY_HEADER, "true");
+          if (cached.headers) {
+            for (const [name, value] of Object.entries(cached.headers)) {
+              if (value !== void 0 && !name.toLowerCase().startsWith("x-powered-by")) {
+                res.set(name, value);
+              }
+            }
+          }
+        }
+        res.status(cached.status);
+        if (cached.body !== void 0) {
+          if (typeof cached.body === "object") {
+            res.json(cached.body);
+          } else {
+            res.send(cached.body);
+          }
+        } else {
+          res.end();
+        }
+        return;
+      }
+      if (result.status === "conflict") {
+        log(`Conflict for key: ${key}`);
+        if (includeHeaders) {
+          res.set("Content-Type", "application/problem+json");
+          res.set(IDEMPOTENCY_KEY_HEADER, key);
+          res.set("Retry-After", "1");
+        }
+        res.status(409).json({
+          type: `${PROBLEM_BASE}/conflict`,
+          title: "Conflict",
+          status: 409,
+          detail: "A request with this idempotency key is already being processed."
+        });
+        return;
+      }
+      if (result.status === "mismatch") {
+        log(`Hash mismatch for key: ${key}`);
+        if (includeHeaders) {
+          res.set("Content-Type", "application/problem+json");
+          res.set(IDEMPOTENCY_KEY_HEADER, key);
+        }
+        res.status(422).json({
+          type: `${PROBLEM_BASE}/mismatch`,
+          title: "Idempotency Key Mismatch",
+          status: 422,
+          detail: "The request body does not match the original request for this idempotency key.",
+          existingHash: result.existingHash,
+          providedHash: result.providedHash
+        });
+        return;
+      }
+      log(`Lock acquired for key: ${key}`);
+      onMiss?.(key);
+      const captured = {
+        status: 200,
+        headers: {},
+        body: void 0
+      };
+      const originalJson = res.json.bind(res);
+      const originalSend = res.send.bind(res);
+      const originalEnd = res.end.bind(res);
+      const originalSetHeader = res.setHeader.bind(res);
+      let finished = false;
+      res.setHeader = function(name, value) {
+        captured.headers[name] = value;
+        return originalSetHeader(name, value);
+      };
+      res.json = function(data) {
+        if (!finished) {
+          captured.body = data;
+          captured.status = res.statusCode;
+        }
+        return originalJson(data);
+      };
+      res.send = function(data) {
+        if (!finished) {
+          captured.body = data;
+          captured.status = res.statusCode;
+        }
+        return originalSend(data);
+      };
+      res.end = function(chunk, encoding, _cb) {
+        if (!finished) {
+          finished = true;
+          captured.status = res.statusCode;
+          if (chunk !== void 0 && captured.body === void 0) {
+            captured.body = chunk;
+          }
+          if (includeHeaders) {
+            originalSetHeader(IDEMPOTENCY_KEY_HEADER, key);
+          }
+          const storedResponse = {
+            data: captured,
+            createdAt: Date.now(),
+            hash
+          };
+          storage.save(key, storedResponse).catch((err) => {
+            log(`Failed to save response for key: ${key}`);
+            onError?.(key, err);
+          });
+        }
+        return originalEnd.call(res, chunk, encoding);
+      };
+      res.on("error", async () => {
+        if (!finished) {
+          finished = true;
+          log(`Response error for key: ${key}, releasing lock`);
+          await storage.release(key).catch(() => {
+          });
+        }
+      });
+      req.on("close", async () => {
+        if (!finished && !res.writableFinished) {
+          finished = true;
+          log(`Client disconnected for key: ${key}, releasing lock`);
+          await storage.release(key).catch(() => {
+          });
+        }
+      });
+      next();
+    } catch (err) {
+      if (err instanceof core.IdempotencyError) {
+        if (includeHeaders) {
+          res.set("Content-Type", "application/problem+json");
+          res.set(IDEMPOTENCY_KEY_HEADER, key);
+          if (err instanceof core.ConflictError) {
+            res.set("Retry-After", String(err.retryAfter ?? 1));
+          }
+        }
+        let type = `${PROBLEM_BASE}/error`;
+        if (err instanceof core.MissingKeyError) type = `${PROBLEM_BASE}/key-required`;
+        else if (err instanceof core.ConflictError) type = `${PROBLEM_BASE}/conflict`;
+        else if (err instanceof core.MismatchError) type = `${PROBLEM_BASE}/mismatch`;
+        res.status(err.statusCode).json({
+          type,
+          title: err.name,
+          status: err.statusCode,
+          detail: err.message
+        });
+        return;
+      }
+      next(err);
+    }
+  };
+}
+function configure(defaults) {
+  return (overrides = {}) => express({ ...defaults, ...overrides });
+}
+core.oncely.express = express;
+
+Object.defineProperty(exports, "ConflictError", {
+  enumerable: true,
+  get: function () { return core.ConflictError; }
+});
+Object.defineProperty(exports, "IdempotencyError", {
+  enumerable: true,
+  get: function () { return core.IdempotencyError; }
+});
+Object.defineProperty(exports, "MemoryStorage", {
+  enumerable: true,
+  get: function () { return core.MemoryStorage; }
+});
+Object.defineProperty(exports, "MismatchError", {
+  enumerable: true,
+  get: function () { return core.MismatchError; }
+});
+Object.defineProperty(exports, "MissingKeyError", {
+  enumerable: true,
+  get: function () { return core.MissingKeyError; }
+});
+Object.defineProperty(exports, "hashObject", {
+  enumerable: true,
+  get: function () { return core.hashObject; }
+});
+Object.defineProperty(exports, "oncely", {
+  enumerable: true,
+  get: function () { return core.oncely; }
+});
+exports.IDEMPOTENCY_KEY_HEADER = IDEMPOTENCY_KEY_HEADER;
+exports.IDEMPOTENCY_REPLAY_HEADER = IDEMPOTENCY_REPLAY_HEADER;
+exports.configure = configure;
+exports.express = express;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":["MemoryStorage","hashObject","parseTtl","IdempotencyError","ConflictError","MissingKeyError","MismatchError","oncely"],"mappings":"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","file":"index.cjs","sourcesContent":["/**\n * @oncely/express - Express middleware for oncely idempotency\n *\n * Provides Express middleware that wraps route handlers with idempotency protection.\n *\n * @example\n * ```typescript\n * import { oncely } from '@oncely/core';\n * import '@oncely/express';\n *\n * // Now oncely.express() is available\n * app.post('/orders', oncely.express(), async (req, res) => {\n *   const order = await createOrder(req.body);\n *   res.status(201).json(order);\n * });\n * ```\n */\n\nimport type { Request, Response, NextFunction, RequestHandler } from 'express';\nimport {\n  oncely,\n  MemoryStorage,\n  hashObject,\n  parseTtl,\n  IdempotencyError,\n  ConflictError,\n  MissingKeyError,\n  MismatchError,\n  type StorageAdapter,\n  type OncelyOptions,\n  type StoredResponse,\n} from '@oncely/core';\n\n// RFC 7807 Problem Details type URL base\nconst PROBLEM_BASE = 'https://oncely.dev/errors';\n\n/**\n * IETF standard header names\n */\nexport const IDEMPOTENCY_KEY_HEADER = 'Idempotency-Key';\nexport const IDEMPOTENCY_REPLAY_HEADER = 'Idempotency-Replay';\n\n/**\n * Options for Express idempotency middleware\n */\nexport interface ExpressMiddlewareOptions {\n  /**\n   * Storage adapter for persisting idempotency records.\n   * @default oncely.config.storage or memory\n   */\n  storage?: StorageAdapter;\n\n  /**\n   * TTL for idempotency records in milliseconds or duration string.\n   * @default oncely.config.ttl or '24h'\n   */\n  ttl?: number | string;\n\n  /**\n   * Whether to require an idempotency key.\n   * If true, returns 400 when key is missing.\n   * @default false\n   */\n  required?: boolean;\n\n  /**\n   * HTTP methods to apply idempotency to.\n   * @default ['POST', 'PUT', 'PATCH', 'DELETE']\n   */\n  methods?: string[];\n\n  /**\n   * Custom function to extract idempotency key from request.\n   * @default Reads Idempotency-Key header\n   */\n  getKey?: (req: Request) => string | undefined;\n\n  /**\n   * Custom function to generate hash from request for mismatch detection.\n   * @default Uses hashObject(req.body)\n   */\n  getHash?: (req: Request) => string | null;\n\n  /**\n   * Whether to add idempotency headers to responses.\n   * @default true\n   */\n  includeHeaders?: boolean;\n\n  /**\n   * Debug mode for logging.\n   * @default false\n   */\n  debug?: boolean;\n\n  /**\n   * Callback when a cached response is returned.\n   */\n  onHit?: OncelyOptions['onHit'];\n\n  /**\n   * Callback when a new response is generated.\n   */\n  onMiss?: OncelyOptions['onMiss'];\n\n  /**\n   * Callback when an error occurs.\n   */\n  onError?: OncelyOptions['onError'];\n\n  /**\n   * If true, proceed with the request when storage fails (e.g., Redis down).\n   * When false (default), storage errors return 500.\n   * Use with non-critical idempotency where availability is more important.\n   * @default false\n   */\n  failOpen?: boolean;\n}\n\n/**\n * Captured response data\n */\ninterface CapturedResponse {\n  status: number;\n  headers: Record<string, string | string[] | number | undefined>;\n  body: unknown;\n}\n\n// Shared default storage instance\nlet defaultStorage: StorageAdapter | null = null;\n\nfunction getStorage(provided?: StorageAdapter): StorageAdapter {\n  if (provided) return provided;\n  if (!defaultStorage) {\n    defaultStorage = new MemoryStorage();\n  }\n  return defaultStorage;\n}\n\n/**\n * Create Express middleware for idempotency.\n *\n * @example\n * ```typescript\n * // Basic usage with defaults\n * app.post('/orders', express(), orderHandler);\n *\n * // With options\n * app.post('/payments', express({\n *   storage: redis(),\n *   required: true,\n *   ttl: '1h',\n * }), paymentHandler);\n *\n * // Custom key extraction\n * app.post('/api/:version/orders', express({\n *   getKey: (req) => req.headers['x-request-id'] as string,\n * }), orderHandler);\n * ```\n */\nexport function express(options: ExpressMiddlewareOptions = {}): RequestHandler {\n  const {\n    storage: providedStorage,\n    ttl = '24h',\n    required = false,\n    methods = ['POST', 'PUT', 'PATCH', 'DELETE'],\n    getKey = (req) => req.get(IDEMPOTENCY_KEY_HEADER),\n    getHash = (req) => (req.body ? hashObject(req.body) : null),\n    includeHeaders = true,\n    debug = false,\n    failOpen = false,\n    onHit,\n    onMiss,\n    onError,\n  } = options;\n\n  const storage = getStorage(providedStorage);\n  const ttlMs = parseTtl(ttl);\n\n  const log = (message: string) => {\n    if (debug) {\n      console.log(`[oncely/express] ${message}`);\n    }\n  };\n\n  return async (req: Request, res: Response, next: NextFunction): Promise<void> => {\n    // Skip if method not in list\n    if (!methods.includes(req.method)) {\n      return next();\n    }\n\n    // Get idempotency key\n    const key = getKey(req);\n\n    // Skip if no key and not required\n    if (!key && !required) {\n      return next();\n    }\n\n    // Return 400 if key required but not provided\n    if (!key && required) {\n      if (includeHeaders) {\n        res.set('Content-Type', 'application/problem+json');\n      }\n      res.status(400).json({\n        type: `${PROBLEM_BASE}/key-required`,\n        title: 'Idempotency Key Required',\n        status: 400,\n        detail: `The ${IDEMPOTENCY_KEY_HEADER} header is required for this request.`,\n      });\n      return;\n    }\n\n    // Compute request hash for mismatch detection\n    const hash = getHash(req);\n\n    try {\n      log(`Acquiring lock for key: ${key}`);\n      let result;\n      try {\n        result = await storage.acquire(key!, hash, ttlMs);\n      } catch (storageErr) {\n        // Storage failed (e.g., Redis down)\n        if (failOpen) {\n          log(`Storage error for key: ${key}, failing open`);\n          onError?.(key!, storageErr as Error);\n          return next(); // Proceed without idempotency protection\n        }\n        throw storageErr;\n      }\n\n      if (result.status === 'hit') {\n        // Return cached response\n        log(`Cache hit for key: ${key}`);\n        onHit?.(key!, result.response);\n        const cached = result.response.data as CapturedResponse;\n\n        if (includeHeaders) {\n          res.set(IDEMPOTENCY_KEY_HEADER, key!);\n          res.set(IDEMPOTENCY_REPLAY_HEADER, 'true');\n\n          // Restore original headers\n          if (cached.headers) {\n            for (const [name, value] of Object.entries(cached.headers)) {\n              if (value !== undefined && !name.toLowerCase().startsWith('x-powered-by')) {\n                res.set(name, value as string);\n              }\n            }\n          }\n        }\n\n        res.status(cached.status);\n        if (cached.body !== undefined) {\n          if (typeof cached.body === 'object') {\n            res.json(cached.body);\n          } else {\n            res.send(cached.body);\n          }\n        } else {\n          res.end();\n        }\n        return;\n      }\n\n      if (result.status === 'conflict') {\n        log(`Conflict for key: ${key}`);\n        if (includeHeaders) {\n          res.set('Content-Type', 'application/problem+json');\n          res.set(IDEMPOTENCY_KEY_HEADER, key!);\n          res.set('Retry-After', '1');\n        }\n        res.status(409).json({\n          type: `${PROBLEM_BASE}/conflict`,\n          title: 'Conflict',\n          status: 409,\n          detail: 'A request with this idempotency key is already being processed.',\n        });\n        return;\n      }\n\n      if (result.status === 'mismatch') {\n        log(`Hash mismatch for key: ${key}`);\n        if (includeHeaders) {\n          res.set('Content-Type', 'application/problem+json');\n          res.set(IDEMPOTENCY_KEY_HEADER, key!);\n        }\n        res.status(422).json({\n          type: `${PROBLEM_BASE}/mismatch`,\n          title: 'Idempotency Key Mismatch',\n          status: 422,\n          detail: 'The request body does not match the original request for this idempotency key.',\n          existingHash: result.existingHash,\n          providedHash: result.providedHash,\n        });\n        return;\n      }\n\n      // status === 'acquired' - proceed with handler\n      log(`Lock acquired for key: ${key}`);\n      onMiss?.(key!);\n\n      // Capture response\n      const captured: CapturedResponse = {\n        status: 200,\n        headers: {},\n        body: undefined,\n      };\n\n      // Store original methods\n      const originalJson = res.json.bind(res);\n      const originalSend = res.send.bind(res);\n      const originalEnd = res.end.bind(res);\n      const originalSetHeader = res.setHeader.bind(res);\n      let finished = false;\n\n      // Capture headers\n      res.setHeader = function (name: string, value: string | string[] | number) {\n        captured.headers[name] = value;\n        return originalSetHeader(name, value);\n      };\n\n      // Capture JSON responses\n      res.json = function (data: unknown) {\n        if (!finished) {\n          captured.body = data;\n          captured.status = res.statusCode;\n        }\n        return originalJson(data);\n      };\n\n      // Capture send responses\n      res.send = function (data: unknown) {\n        if (!finished) {\n          captured.body = data;\n          captured.status = res.statusCode;\n        }\n        return originalSend(data);\n      };\n\n      // Capture end and save\n      // eslint-disable-next-line @typescript-eslint/no-explicit-any\n      res.end = function (chunk?: any, encoding?: any, _cb?: any) {\n        if (!finished) {\n          finished = true;\n          captured.status = res.statusCode;\n          if (chunk !== undefined && captured.body === undefined) {\n            captured.body = chunk;\n          }\n\n          // Add idempotency headers\n          if (includeHeaders) {\n            originalSetHeader(IDEMPOTENCY_KEY_HEADER, key!);\n          }\n\n          // Save response asynchronously (don't block)\n          const storedResponse: StoredResponse = {\n            data: captured,\n            createdAt: Date.now(),\n            hash,\n          };\n\n          storage.save(key!, storedResponse).catch((err) => {\n            log(`Failed to save response for key: ${key}`);\n            onError?.(key!, err as Error);\n          });\n        }\n\n        return originalEnd.call(res, chunk, encoding);\n      } as typeof res.end;\n\n      // Handle errors - release lock\n      res.on('error', async () => {\n        if (!finished) {\n          finished = true;\n          log(`Response error for key: ${key}, releasing lock`);\n          await storage.release(key!).catch(() => {});\n        }\n      });\n\n      // Handle client disconnect before response completes - release lock to allow retry\n      req.on('close', async () => {\n        if (!finished && !res.writableFinished) {\n          finished = true;\n          log(`Client disconnected for key: ${key}, releasing lock`);\n          await storage.release(key!).catch(() => {});\n        }\n      });\n\n      // Call next handler\n      next();\n    } catch (err) {\n      // Handle oncely errors\n      if (err instanceof IdempotencyError) {\n        if (includeHeaders) {\n          res.set('Content-Type', 'application/problem+json');\n          res.set(IDEMPOTENCY_KEY_HEADER, key!);\n\n          if (err instanceof ConflictError) {\n            res.set('Retry-After', String(err.retryAfter ?? 1));\n          }\n        }\n\n        let type = `${PROBLEM_BASE}/error`;\n        if (err instanceof MissingKeyError) type = `${PROBLEM_BASE}/key-required`;\n        else if (err instanceof ConflictError) type = `${PROBLEM_BASE}/conflict`;\n        else if (err instanceof MismatchError) type = `${PROBLEM_BASE}/mismatch`;\n\n        res.status(err.statusCode).json({\n          type,\n          title: err.name,\n          status: err.statusCode,\n          detail: err.message,\n        });\n        return;\n      }\n\n      // Pass other errors to Express error handler\n      next(err);\n    }\n  };\n}\n\n/**\n * Create a pre-configured middleware factory with default options.\n *\n * @example\n * ```typescript\n * import { configure } from '@oncely/express';\n * import { redis } from '@oncely/redis';\n *\n * const idempotent = configure({\n *   storage: redis(),\n *   ttl: '1h',\n * });\n *\n * app.post('/orders', idempotent(), orderHandler);\n * app.post('/payments', idempotent({ required: true }), paymentHandler);\n * ```\n */\nexport function configure(\n  defaults: ExpressMiddlewareOptions\n): (overrides?: Partial<ExpressMiddlewareOptions>) => RequestHandler {\n  return (overrides = {}) => express({ ...defaults, ...overrides });\n}\n\n// Augment oncely namespace\ndeclare module '@oncely/core' {\n  interface OncelyNamespace {\n    /**\n     * Create Express middleware for idempotency.\n     */\n    express: typeof express;\n  }\n}\n\n// Register on oncely namespace\n(oncely as Record<string, unknown>).express = express;\n\n// Re-export types and utilities\nexport {\n  oncely,\n  MemoryStorage,\n  hashObject,\n  IdempotencyError,\n  MissingKeyError,\n  ConflictError,\n  MismatchError,\n  type StorageAdapter,\n  type OncelyOptions,\n} from '@oncely/core';\n"]}

package/dist/index.d.cts

@@ -0,0 +1,142 @@
+import { Request, RequestHandler } from 'express';
+import { StorageAdapter, OncelyOptions } from '@oncely/core';
+export { ConflictError, IdempotencyError, MemoryStorage, MismatchError, MissingKeyError, OncelyOptions, StorageAdapter, hashObject, oncely } from '@oncely/core';
+
+/**
+ * @oncely/express - Express middleware for oncely idempotency
+ *
+ * Provides Express middleware that wraps route handlers with idempotency protection.
+ *
+ * @example
+ * ```typescript
+ * import { oncely } from '@oncely/core';
+ * import '@oncely/express';
+ *
+ * // Now oncely.express() is available
+ * app.post('/orders', oncely.express(), async (req, res) => {
+ *   const order = await createOrder(req.body);
+ *   res.status(201).json(order);
+ * });
+ * ```
+ */
+
+/**
+ * IETF standard header names
+ */
+declare const IDEMPOTENCY_KEY_HEADER = "Idempotency-Key";
+declare const IDEMPOTENCY_REPLAY_HEADER = "Idempotency-Replay";
+/**
+ * Options for Express idempotency middleware
+ */
+interface ExpressMiddlewareOptions {
+    /**
+     * Storage adapter for persisting idempotency records.
+     * @default oncely.config.storage or memory
+     */
+    storage?: StorageAdapter;
+    /**
+     * TTL for idempotency records in milliseconds or duration string.
+     * @default oncely.config.ttl or '24h'
+     */
+    ttl?: number | string;
+    /**
+     * Whether to require an idempotency key.
+     * If true, returns 400 when key is missing.
+     * @default false
+     */
+    required?: boolean;
+    /**
+     * HTTP methods to apply idempotency to.
+     * @default ['POST', 'PUT', 'PATCH', 'DELETE']
+     */
+    methods?: string[];
+    /**
+     * Custom function to extract idempotency key from request.
+     * @default Reads Idempotency-Key header
+     */
+    getKey?: (req: Request) => string | undefined;
+    /**
+     * Custom function to generate hash from request for mismatch detection.
+     * @default Uses hashObject(req.body)
+     */
+    getHash?: (req: Request) => string | null;
+    /**
+     * Whether to add idempotency headers to responses.
+     * @default true
+     */
+    includeHeaders?: boolean;
+    /**
+     * Debug mode for logging.
+     * @default false
+     */
+    debug?: boolean;
+    /**
+     * Callback when a cached response is returned.
+     */
+    onHit?: OncelyOptions['onHit'];
+    /**
+     * Callback when a new response is generated.
+     */
+    onMiss?: OncelyOptions['onMiss'];
+    /**
+     * Callback when an error occurs.
+     */
+    onError?: OncelyOptions['onError'];
+    /**
+     * If true, proceed with the request when storage fails (e.g., Redis down).
+     * When false (default), storage errors return 500.
+     * Use with non-critical idempotency where availability is more important.
+     * @default false
+     */
+    failOpen?: boolean;
+}
+/**
+ * Create Express middleware for idempotency.
+ *
+ * @example
+ * ```typescript
+ * // Basic usage with defaults
+ * app.post('/orders', express(), orderHandler);
+ *
+ * // With options
+ * app.post('/payments', express({
+ *   storage: redis(),
+ *   required: true,
+ *   ttl: '1h',
+ * }), paymentHandler);
+ *
+ * // Custom key extraction
+ * app.post('/api/:version/orders', express({
+ *   getKey: (req) => req.headers['x-request-id'] as string,
+ * }), orderHandler);
+ * ```
+ */
+declare function express(options?: ExpressMiddlewareOptions): RequestHandler;
+/**
+ * Create a pre-configured middleware factory with default options.
+ *
+ * @example
+ * ```typescript
+ * import { configure } from '@oncely/express';
+ * import { redis } from '@oncely/redis';
+ *
+ * const idempotent = configure({
+ *   storage: redis(),
+ *   ttl: '1h',
+ * });
+ *
+ * app.post('/orders', idempotent(), orderHandler);
+ * app.post('/payments', idempotent({ required: true }), paymentHandler);
+ * ```
+ */
+declare function configure(defaults: ExpressMiddlewareOptions): (overrides?: Partial<ExpressMiddlewareOptions>) => RequestHandler;
+declare module '@oncely/core' {
+    interface OncelyNamespace {
+        /**
+         * Create Express middleware for idempotency.
+         */
+        express: typeof express;
+    }
+}
+
+export { type ExpressMiddlewareOptions, IDEMPOTENCY_KEY_HEADER, IDEMPOTENCY_REPLAY_HEADER, configure, express };

package/dist/index.d.ts

@@ -0,0 +1,142 @@
+import { Request, RequestHandler } from 'express';
+import { StorageAdapter, OncelyOptions } from '@oncely/core';
+export { ConflictError, IdempotencyError, MemoryStorage, MismatchError, MissingKeyError, OncelyOptions, StorageAdapter, hashObject, oncely } from '@oncely/core';
+
+/**
+ * @oncely/express - Express middleware for oncely idempotency
+ *
+ * Provides Express middleware that wraps route handlers with idempotency protection.
+ *
+ * @example
+ * ```typescript
+ * import { oncely } from '@oncely/core';
+ * import '@oncely/express';
+ *
+ * // Now oncely.express() is available
+ * app.post('/orders', oncely.express(), async (req, res) => {
+ *   const order = await createOrder(req.body);
+ *   res.status(201).json(order);
+ * });
+ * ```
+ */
+
+/**
+ * IETF standard header names
+ */
+declare const IDEMPOTENCY_KEY_HEADER = "Idempotency-Key";
+declare const IDEMPOTENCY_REPLAY_HEADER = "Idempotency-Replay";
+/**
+ * Options for Express idempotency middleware
+ */
+interface ExpressMiddlewareOptions {
+    /**
+     * Storage adapter for persisting idempotency records.
+     * @default oncely.config.storage or memory
+     */
+    storage?: StorageAdapter;
+    /**
+     * TTL for idempotency records in milliseconds or duration string.
+     * @default oncely.config.ttl or '24h'
+     */
+    ttl?: number | string;
+    /**
+     * Whether to require an idempotency key.
+     * If true, returns 400 when key is missing.
+     * @default false
+     */
+    required?: boolean;
+    /**
+     * HTTP methods to apply idempotency to.
+     * @default ['POST', 'PUT', 'PATCH', 'DELETE']
+     */
+    methods?: string[];
+    /**
+     * Custom function to extract idempotency key from request.
+     * @default Reads Idempotency-Key header
+     */
+    getKey?: (req: Request) => string | undefined;
+    /**
+     * Custom function to generate hash from request for mismatch detection.
+     * @default Uses hashObject(req.body)
+     */
+    getHash?: (req: Request) => string | null;
+    /**
+     * Whether to add idempotency headers to responses.
+     * @default true
+     */
+    includeHeaders?: boolean;
+    /**
+     * Debug mode for logging.
+     * @default false
+     */
+    debug?: boolean;
+    /**
+     * Callback when a cached response is returned.
+     */
+    onHit?: OncelyOptions['onHit'];
+    /**
+     * Callback when a new response is generated.
+     */
+    onMiss?: OncelyOptions['onMiss'];
+    /**
+     * Callback when an error occurs.
+     */
+    onError?: OncelyOptions['onError'];
+    /**
+     * If true, proceed with the request when storage fails (e.g., Redis down).
+     * When false (default), storage errors return 500.
+     * Use with non-critical idempotency where availability is more important.
+     * @default false
+     */
+    failOpen?: boolean;
+}
+/**
+ * Create Express middleware for idempotency.
+ *
+ * @example
+ * ```typescript
+ * // Basic usage with defaults
+ * app.post('/orders', express(), orderHandler);
+ *
+ * // With options
+ * app.post('/payments', express({
+ *   storage: redis(),
+ *   required: true,
+ *   ttl: '1h',
+ * }), paymentHandler);
+ *
+ * // Custom key extraction
+ * app.post('/api/:version/orders', express({
+ *   getKey: (req) => req.headers['x-request-id'] as string,
+ * }), orderHandler);
+ * ```
+ */
+declare function express(options?: ExpressMiddlewareOptions): RequestHandler;
+/**
+ * Create a pre-configured middleware factory with default options.
+ *
+ * @example
+ * ```typescript
+ * import { configure } from '@oncely/express';
+ * import { redis } from '@oncely/redis';
+ *
+ * const idempotent = configure({
+ *   storage: redis(),
+ *   ttl: '1h',
+ * });
+ *
+ * app.post('/orders', idempotent(), orderHandler);
+ * app.post('/payments', idempotent({ required: true }), paymentHandler);
+ * ```
+ */
+declare function configure(defaults: ExpressMiddlewareOptions): (overrides?: Partial<ExpressMiddlewareOptions>) => RequestHandler;
+declare module '@oncely/core' {
+    interface OncelyNamespace {
+        /**
+         * Create Express middleware for idempotency.
+         */
+        express: typeof express;
+    }
+}
+
+export { type ExpressMiddlewareOptions, IDEMPOTENCY_KEY_HEADER, IDEMPOTENCY_REPLAY_HEADER, configure, express };

package/dist/index.js

@@ -0,0 +1,231 @@
+import { oncely, hashObject, parseTtl, IdempotencyError, ConflictError, MemoryStorage, MissingKeyError, MismatchError } from '@oncely/core';
+export { ConflictError, IdempotencyError, MemoryStorage, MismatchError, MissingKeyError, hashObject, oncely } from '@oncely/core';
+
+// src/index.ts
+var PROBLEM_BASE = "https://oncely.dev/errors";
+var IDEMPOTENCY_KEY_HEADER = "Idempotency-Key";
+var IDEMPOTENCY_REPLAY_HEADER = "Idempotency-Replay";
+var defaultStorage = null;
+function getStorage(provided) {
+  if (provided) return provided;
+  if (!defaultStorage) {
+    defaultStorage = new MemoryStorage();
+  }
+  return defaultStorage;
+}
+function express(options = {}) {
+  const {
+    storage: providedStorage,
+    ttl = "24h",
+    required = false,
+    methods = ["POST", "PUT", "PATCH", "DELETE"],
+    getKey = (req) => req.get(IDEMPOTENCY_KEY_HEADER),
+    getHash = (req) => req.body ? hashObject(req.body) : null,
+    includeHeaders = true,
+    debug = false,
+    failOpen = false,
+    onHit,
+    onMiss,
+    onError
+  } = options;
+  const storage = getStorage(providedStorage);
+  const ttlMs = parseTtl(ttl);
+  const log = (message) => {
+    if (debug) {
+      console.log(`[oncely/express] ${message}`);
+    }
+  };
+  return async (req, res, next) => {
+    if (!methods.includes(req.method)) {
+      return next();
+    }
+    const key = getKey(req);
+    if (!key && !required) {
+      return next();
+    }
+    if (!key && required) {
+      if (includeHeaders) {
+        res.set("Content-Type", "application/problem+json");
+      }
+      res.status(400).json({
+        type: `${PROBLEM_BASE}/key-required`,
+        title: "Idempotency Key Required",
+        status: 400,
+        detail: `The ${IDEMPOTENCY_KEY_HEADER} header is required for this request.`
+      });
+      return;
+    }
+    const hash = getHash(req);
+    try {
+      log(`Acquiring lock for key: ${key}`);
+      let result;
+      try {
+        result = await storage.acquire(key, hash, ttlMs);
+      } catch (storageErr) {
+        if (failOpen) {
+          log(`Storage error for key: ${key}, failing open`);
+          onError?.(key, storageErr);
+          return next();
+        }
+        throw storageErr;
+      }
+      if (result.status === "hit") {
+        log(`Cache hit for key: ${key}`);
+        onHit?.(key, result.response);
+        const cached = result.response.data;
+        if (includeHeaders) {
+          res.set(IDEMPOTENCY_KEY_HEADER, key);
+          res.set(IDEMPOTENCY_REPLAY_HEADER, "true");
+          if (cached.headers) {
+            for (const [name, value] of Object.entries(cached.headers)) {
+              if (value !== void 0 && !name.toLowerCase().startsWith("x-powered-by")) {
+                res.set(name, value);
+              }
+            }
+          }
+        }
+        res.status(cached.status);
+        if (cached.body !== void 0) {
+          if (typeof cached.body === "object") {
+            res.json(cached.body);
+          } else {
+            res.send(cached.body);
+          }
+        } else {
+          res.end();
+        }
+        return;
+      }
+      if (result.status === "conflict") {
+        log(`Conflict for key: ${key}`);
+        if (includeHeaders) {
+          res.set("Content-Type", "application/problem+json");
+          res.set(IDEMPOTENCY_KEY_HEADER, key);
+          res.set("Retry-After", "1");
+        }
+        res.status(409).json({
+          type: `${PROBLEM_BASE}/conflict`,
+          title: "Conflict",
+          status: 409,
+          detail: "A request with this idempotency key is already being processed."
+        });
+        return;
+      }
+      if (result.status === "mismatch") {
+        log(`Hash mismatch for key: ${key}`);
+        if (includeHeaders) {
+          res.set("Content-Type", "application/problem+json");
+          res.set(IDEMPOTENCY_KEY_HEADER, key);
+        }
+        res.status(422).json({
+          type: `${PROBLEM_BASE}/mismatch`,
+          title: "Idempotency Key Mismatch",
+          status: 422,
+          detail: "The request body does not match the original request for this idempotency key.",
+          existingHash: result.existingHash,
+          providedHash: result.providedHash
+        });
+        return;
+      }
+      log(`Lock acquired for key: ${key}`);
+      onMiss?.(key);
+      const captured = {
+        status: 200,
+        headers: {},
+        body: void 0
+      };
+      const originalJson = res.json.bind(res);
+      const originalSend = res.send.bind(res);
+      const originalEnd = res.end.bind(res);
+      const originalSetHeader = res.setHeader.bind(res);
+      let finished = false;
+      res.setHeader = function(name, value) {
+        captured.headers[name] = value;
+        return originalSetHeader(name, value);
+      };
+      res.json = function(data) {
+        if (!finished) {
+          captured.body = data;
+          captured.status = res.statusCode;
+        }
+        return originalJson(data);
+      };
+      res.send = function(data) {
+        if (!finished) {
+          captured.body = data;
+          captured.status = res.statusCode;
+        }
+        return originalSend(data);
+      };
+      res.end = function(chunk, encoding, _cb) {
+        if (!finished) {
+          finished = true;
+          captured.status = res.statusCode;
+          if (chunk !== void 0 && captured.body === void 0) {
+            captured.body = chunk;
+          }
+          if (includeHeaders) {
+            originalSetHeader(IDEMPOTENCY_KEY_HEADER, key);
+          }
+          const storedResponse = {
+            data: captured,
+            createdAt: Date.now(),
+            hash
+          };
+          storage.save(key, storedResponse).catch((err) => {
+            log(`Failed to save response for key: ${key}`);
+            onError?.(key, err);
+          });
+        }
+        return originalEnd.call(res, chunk, encoding);
+      };
+      res.on("error", async () => {
+        if (!finished) {
+          finished = true;
+          log(`Response error for key: ${key}, releasing lock`);
+          await storage.release(key).catch(() => {
+          });
+        }
+      });
+      req.on("close", async () => {
+        if (!finished && !res.writableFinished) {
+          finished = true;
+          log(`Client disconnected for key: ${key}, releasing lock`);
+          await storage.release(key).catch(() => {
+          });
+        }
+      });
+      next();
+    } catch (err) {
+      if (err instanceof IdempotencyError) {
+        if (includeHeaders) {
+          res.set("Content-Type", "application/problem+json");
+          res.set(IDEMPOTENCY_KEY_HEADER, key);
+          if (err instanceof ConflictError) {
+            res.set("Retry-After", String(err.retryAfter ?? 1));
+          }
+        }
+        let type = `${PROBLEM_BASE}/error`;
+        if (err instanceof MissingKeyError) type = `${PROBLEM_BASE}/key-required`;
+        else if (err instanceof ConflictError) type = `${PROBLEM_BASE}/conflict`;
+        else if (err instanceof MismatchError) type = `${PROBLEM_BASE}/mismatch`;
+        res.status(err.statusCode).json({
+          type,
+          title: err.name,
+          status: err.statusCode,
+          detail: err.message
+        });
+        return;
+      }
+      next(err);
+    }
+  };
+}
+function configure(defaults) {
+  return (overrides = {}) => express({ ...defaults, ...overrides });
+}
+oncely.express = express;
+
+export { IDEMPOTENCY_KEY_HEADER, IDEMPOTENCY_REPLAY_HEADER, configure, express };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * @oncely/express - Express middleware for oncely idempotency\n *\n * Provides Express middleware that wraps route handlers with idempotency protection.\n *\n * @example\n * ```typescript\n * import { oncely } from '@oncely/core';\n * import '@oncely/express';\n *\n * // Now oncely.express() is available\n * app.post('/orders', oncely.express(), async (req, res) => {\n *   const order = await createOrder(req.body);\n *   res.status(201).json(order);\n * });\n * ```\n */\n\nimport type { Request, Response, NextFunction, RequestHandler } from 'express';\nimport {\n  oncely,\n  MemoryStorage,\n  hashObject,\n  parseTtl,\n  IdempotencyError,\n  ConflictError,\n  MissingKeyError,\n  MismatchError,\n  type StorageAdapter,\n  type OncelyOptions,\n  type StoredResponse,\n} from '@oncely/core';\n\n// RFC 7807 Problem Details type URL base\nconst PROBLEM_BASE = 'https://oncely.dev/errors';\n\n/**\n * IETF standard header names\n */\nexport const IDEMPOTENCY_KEY_HEADER = 'Idempotency-Key';\nexport const IDEMPOTENCY_REPLAY_HEADER = 'Idempotency-Replay';\n\n/**\n * Options for Express idempotency middleware\n */\nexport interface ExpressMiddlewareOptions {\n  /**\n   * Storage adapter for persisting idempotency records.\n   * @default oncely.config.storage or memory\n   */\n  storage?: StorageAdapter;\n\n  /**\n   * TTL for idempotency records in milliseconds or duration string.\n   * @default oncely.config.ttl or '24h'\n   */\n  ttl?: number | string;\n\n  /**\n   * Whether to require an idempotency key.\n   * If true, returns 400 when key is missing.\n   * @default false\n   */\n  required?: boolean;\n\n  /**\n   * HTTP methods to apply idempotency to.\n   * @default ['POST', 'PUT', 'PATCH', 'DELETE']\n   */\n  methods?: string[];\n\n  /**\n   * Custom function to extract idempotency key from request.\n   * @default Reads Idempotency-Key header\n   */\n  getKey?: (req: Request) => string | undefined;\n\n  /**\n   * Custom function to generate hash from request for mismatch detection.\n   * @default Uses hashObject(req.body)\n   */\n  getHash?: (req: Request) => string | null;\n\n  /**\n   * Whether to add idempotency headers to responses.\n   * @default true\n   */\n  includeHeaders?: boolean;\n\n  /**\n   * Debug mode for logging.\n   * @default false\n   */\n  debug?: boolean;\n\n  /**\n   * Callback when a cached response is returned.\n   */\n  onHit?: OncelyOptions['onHit'];\n\n  /**\n   * Callback when a new response is generated.\n   */\n  onMiss?: OncelyOptions['onMiss'];\n\n  /**\n   * Callback when an error occurs.\n   */\n  onError?: OncelyOptions['onError'];\n\n  /**\n   * If true, proceed with the request when storage fails (e.g., Redis down).\n   * When false (default), storage errors return 500.\n   * Use with non-critical idempotency where availability is more important.\n   * @default false\n   */\n  failOpen?: boolean;\n}\n\n/**\n * Captured response data\n */\ninterface CapturedResponse {\n  status: number;\n  headers: Record<string, string | string[] | number | undefined>;\n  body: unknown;\n}\n\n// Shared default storage instance\nlet defaultStorage: StorageAdapter | null = null;\n\nfunction getStorage(provided?: StorageAdapter): StorageAdapter {\n  if (provided) return provided;\n  if (!defaultStorage) {\n    defaultStorage = new MemoryStorage();\n  }\n  return defaultStorage;\n}\n\n/**\n * Create Express middleware for idempotency.\n *\n * @example\n * ```typescript\n * // Basic usage with defaults\n * app.post('/orders', express(), orderHandler);\n *\n * // With options\n * app.post('/payments', express({\n *   storage: redis(),\n *   required: true,\n *   ttl: '1h',\n * }), paymentHandler);\n *\n * // Custom key extraction\n * app.post('/api/:version/orders', express({\n *   getKey: (req) => req.headers['x-request-id'] as string,\n * }), orderHandler);\n * ```\n */\nexport function express(options: ExpressMiddlewareOptions = {}): RequestHandler {\n  const {\n    storage: providedStorage,\n    ttl = '24h',\n    required = false,\n    methods = ['POST', 'PUT', 'PATCH', 'DELETE'],\n    getKey = (req) => req.get(IDEMPOTENCY_KEY_HEADER),\n    getHash = (req) => (req.body ? hashObject(req.body) : null),\n    includeHeaders = true,\n    debug = false,\n    failOpen = false,\n    onHit,\n    onMiss,\n    onError,\n  } = options;\n\n  const storage = getStorage(providedStorage);\n  const ttlMs = parseTtl(ttl);\n\n  const log = (message: string) => {\n    if (debug) {\n      console.log(`[oncely/express] ${message}`);\n    }\n  };\n\n  return async (req: Request, res: Response, next: NextFunction): Promise<void> => {\n    // Skip if method not in list\n    if (!methods.includes(req.method)) {\n      return next();\n    }\n\n    // Get idempotency key\n    const key = getKey(req);\n\n    // Skip if no key and not required\n    if (!key && !required) {\n      return next();\n    }\n\n    // Return 400 if key required but not provided\n    if (!key && required) {\n      if (includeHeaders) {\n        res.set('Content-Type', 'application/problem+json');\n      }\n      res.status(400).json({\n        type: `${PROBLEM_BASE}/key-required`,\n        title: 'Idempotency Key Required',\n        status: 400,\n        detail: `The ${IDEMPOTENCY_KEY_HEADER} header is required for this request.`,\n      });\n      return;\n    }\n\n    // Compute request hash for mismatch detection\n    const hash = getHash(req);\n\n    try {\n      log(`Acquiring lock for key: ${key}`);\n      let result;\n      try {\n        result = await storage.acquire(key!, hash, ttlMs);\n      } catch (storageErr) {\n        // Storage failed (e.g., Redis down)\n        if (failOpen) {\n          log(`Storage error for key: ${key}, failing open`);\n          onError?.(key!, storageErr as Error);\n          return next(); // Proceed without idempotency protection\n        }\n        throw storageErr;\n      }\n\n      if (result.status === 'hit') {\n        // Return cached response\n        log(`Cache hit for key: ${key}`);\n        onHit?.(key!, result.response);\n        const cached = result.response.data as CapturedResponse;\n\n        if (includeHeaders) {\n          res.set(IDEMPOTENCY_KEY_HEADER, key!);\n          res.set(IDEMPOTENCY_REPLAY_HEADER, 'true');\n\n          // Restore original headers\n          if (cached.headers) {\n            for (const [name, value] of Object.entries(cached.headers)) {\n              if (value !== undefined && !name.toLowerCase().startsWith('x-powered-by')) {\n                res.set(name, value as string);\n              }\n            }\n          }\n        }\n\n        res.status(cached.status);\n        if (cached.body !== undefined) {\n          if (typeof cached.body === 'object') {\n            res.json(cached.body);\n          } else {\n            res.send(cached.body);\n          }\n        } else {\n          res.end();\n        }\n        return;\n      }\n\n      if (result.status === 'conflict') {\n        log(`Conflict for key: ${key}`);\n        if (includeHeaders) {\n          res.set('Content-Type', 'application/problem+json');\n          res.set(IDEMPOTENCY_KEY_HEADER, key!);\n          res.set('Retry-After', '1');\n        }\n        res.status(409).json({\n          type: `${PROBLEM_BASE}/conflict`,\n          title: 'Conflict',\n          status: 409,\n          detail: 'A request with this idempotency key is already being processed.',\n        });\n        return;\n      }\n\n      if (result.status === 'mismatch') {\n        log(`Hash mismatch for key: ${key}`);\n        if (includeHeaders) {\n          res.set('Content-Type', 'application/problem+json');\n          res.set(IDEMPOTENCY_KEY_HEADER, key!);\n        }\n        res.status(422).json({\n          type: `${PROBLEM_BASE}/mismatch`,\n          title: 'Idempotency Key Mismatch',\n          status: 422,\n          detail: 'The request body does not match the original request for this idempotency key.',\n          existingHash: result.existingHash,\n          providedHash: result.providedHash,\n        });\n        return;\n      }\n\n      // status === 'acquired' - proceed with handler\n      log(`Lock acquired for key: ${key}`);\n      onMiss?.(key!);\n\n      // Capture response\n      const captured: CapturedResponse = {\n        status: 200,\n        headers: {},\n        body: undefined,\n      };\n\n      // Store original methods\n      const originalJson = res.json.bind(res);\n      const originalSend = res.send.bind(res);\n      const originalEnd = res.end.bind(res);\n      const originalSetHeader = res.setHeader.bind(res);\n      let finished = false;\n\n      // Capture headers\n      res.setHeader = function (name: string, value: string | string[] | number) {\n        captured.headers[name] = value;\n        return originalSetHeader(name, value);\n      };\n\n      // Capture JSON responses\n      res.json = function (data: unknown) {\n        if (!finished) {\n          captured.body = data;\n          captured.status = res.statusCode;\n        }\n        return originalJson(data);\n      };\n\n      // Capture send responses\n      res.send = function (data: unknown) {\n        if (!finished) {\n          captured.body = data;\n          captured.status = res.statusCode;\n        }\n        return originalSend(data);\n      };\n\n      // Capture end and save\n      // eslint-disable-next-line @typescript-eslint/no-explicit-any\n      res.end = function (chunk?: any, encoding?: any, _cb?: any) {\n        if (!finished) {\n          finished = true;\n          captured.status = res.statusCode;\n          if (chunk !== undefined && captured.body === undefined) {\n            captured.body = chunk;\n          }\n\n          // Add idempotency headers\n          if (includeHeaders) {\n            originalSetHeader(IDEMPOTENCY_KEY_HEADER, key!);\n          }\n\n          // Save response asynchronously (don't block)\n          const storedResponse: StoredResponse = {\n            data: captured,\n            createdAt: Date.now(),\n            hash,\n          };\n\n          storage.save(key!, storedResponse).catch((err) => {\n            log(`Failed to save response for key: ${key}`);\n            onError?.(key!, err as Error);\n          });\n        }\n\n        return originalEnd.call(res, chunk, encoding);\n      } as typeof res.end;\n\n      // Handle errors - release lock\n      res.on('error', async () => {\n        if (!finished) {\n          finished = true;\n          log(`Response error for key: ${key}, releasing lock`);\n          await storage.release(key!).catch(() => {});\n        }\n      });\n\n      // Handle client disconnect before response completes - release lock to allow retry\n      req.on('close', async () => {\n        if (!finished && !res.writableFinished) {\n          finished = true;\n          log(`Client disconnected for key: ${key}, releasing lock`);\n          await storage.release(key!).catch(() => {});\n        }\n      });\n\n      // Call next handler\n      next();\n    } catch (err) {\n      // Handle oncely errors\n      if (err instanceof IdempotencyError) {\n        if (includeHeaders) {\n          res.set('Content-Type', 'application/problem+json');\n          res.set(IDEMPOTENCY_KEY_HEADER, key!);\n\n          if (err instanceof ConflictError) {\n            res.set('Retry-After', String(err.retryAfter ?? 1));\n          }\n        }\n\n        let type = `${PROBLEM_BASE}/error`;\n        if (err instanceof MissingKeyError) type = `${PROBLEM_BASE}/key-required`;\n        else if (err instanceof ConflictError) type = `${PROBLEM_BASE}/conflict`;\n        else if (err instanceof MismatchError) type = `${PROBLEM_BASE}/mismatch`;\n\n        res.status(err.statusCode).json({\n          type,\n          title: err.name,\n          status: err.statusCode,\n          detail: err.message,\n        });\n        return;\n      }\n\n      // Pass other errors to Express error handler\n      next(err);\n    }\n  };\n}\n\n/**\n * Create a pre-configured middleware factory with default options.\n *\n * @example\n * ```typescript\n * import { configure } from '@oncely/express';\n * import { redis } from '@oncely/redis';\n *\n * const idempotent = configure({\n *   storage: redis(),\n *   ttl: '1h',\n * });\n *\n * app.post('/orders', idempotent(), orderHandler);\n * app.post('/payments', idempotent({ required: true }), paymentHandler);\n * ```\n */\nexport function configure(\n  defaults: ExpressMiddlewareOptions\n): (overrides?: Partial<ExpressMiddlewareOptions>) => RequestHandler {\n  return (overrides = {}) => express({ ...defaults, ...overrides });\n}\n\n// Augment oncely namespace\ndeclare module '@oncely/core' {\n  interface OncelyNamespace {\n    /**\n     * Create Express middleware for idempotency.\n     */\n    express: typeof express;\n  }\n}\n\n// Register on oncely namespace\n(oncely as Record<string, unknown>).express = express;\n\n// Re-export types and utilities\nexport {\n  oncely,\n  MemoryStorage,\n  hashObject,\n  IdempotencyError,\n  MissingKeyError,\n  ConflictError,\n  MismatchError,\n  type StorageAdapter,\n  type OncelyOptions,\n} from '@oncely/core';\n"]}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@oncely/express",
+  "version": "1.0.0",
+  "description": "Express middleware for oncely idempotency",
+  "author": "stacks0x",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/stacks0x/oncely.git",
+    "directory": "packages/express"
+  },
+  "keywords": [
+    "oncely",
+    "idempotency",
+    "express",
+    "middleware"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  },
+  "peerDependencies": {
+    "@oncely/core": "workspace:*",
+    "express": "^4.18.0 || ^5.0.0"
+  },
+  "devDependencies": {
+    "@oncely/core": "workspace:*",
+    "@types/express": "^5.0.6",
+    "express": "^5.2.1",
+    "tsup": "^8.0.1",
+    "typescript": "^5.3.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}