@saga-bus/middleware-idempotency 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Dean Foran
+
+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,282 @@
+# @saga-bus/middleware-idempotency
+
+Idempotency middleware for saga-bus that prevents duplicate message processing.
+
+## Installation
+
+```bash
+npm install @saga-bus/middleware-idempotency
+# or
+pnpm add @saga-bus/middleware-idempotency
+```
+
+For Redis support:
+
+```bash
+npm install ioredis
+```
+
+## Features
+
+- **Message Deduplication**: Prevent duplicate message processing within a configurable time window
+- **Multiple Storage Backends**: In-memory (development) and Redis (production)
+- **Flexible ID Extraction**: Custom message ID extraction strategies
+- **Configurable Behavior**: Skip, log, or throw on duplicates
+- **Delivery Guarantees**: Choose between at-most-once or at-least-once semantics
+
+## Quick Start
+
+```typescript
+import { createBus } from "@saga-bus/core";
+import {
+  createIdempotencyMiddleware,
+  InMemoryIdempotencyStore,
+} from "@saga-bus/middleware-idempotency";
+
+const idempotencyMiddleware = createIdempotencyMiddleware({
+  store: new InMemoryIdempotencyStore(),
+  windowMs: 60000, // 1 minute deduplication window
+});
+
+const bus = createBus({
+  transport,
+  store,
+  sagas: [OrderSaga],
+  middleware: [idempotencyMiddleware],
+});
+```
+
+## API Reference
+
+### createIdempotencyMiddleware(options)
+
+Creates middleware that prevents duplicate message processing.
+
+```typescript
+interface IdempotencyMiddlewareOptions {
+  /** Store for tracking processed message IDs */
+  store: IdempotencyStore;
+
+  /** Time window for deduplication in milliseconds (default: 60000) */
+  windowMs?: number;
+
+  /** Function to extract message ID from envelope (default: envelope.id) */
+  getMessageId?: (envelope: MessageEnvelope) => string;
+
+  /** Action on duplicate: "skip" | "log" | "throw" (default: "skip") */
+  onDuplicate?: "skip" | "log" | "throw";
+
+  /** Logger for duplicate detection messages */
+  logger?: { warn(message: string, meta?: Record<string, unknown>): void };
+
+  /** Message types to exclude from idempotency checks */
+  excludeTypes?: string[];
+
+  /** When to mark message as processed: "before" | "after" (default: "after") */
+  markTiming?: "before" | "after";
+}
+```
+
+### InMemoryIdempotencyStore
+
+In-memory store for development and testing. Not suitable for distributed systems.
+
+```typescript
+import { InMemoryIdempotencyStore } from "@saga-bus/middleware-idempotency";
+
+const store = new InMemoryIdempotencyStore();
+
+// Optional: specify cleanup interval (default: 60000ms)
+const store = new InMemoryIdempotencyStore(30000);
+
+// Stop cleanup interval when done
+store.stop();
+```
+
+### RedisIdempotencyStore
+
+Redis-backed store for production distributed systems.
+
+```typescript
+import Redis from "ioredis";
+import { RedisIdempotencyStore } from "@saga-bus/middleware-idempotency";
+
+const redis = new Redis();
+
+const store = new RedisIdempotencyStore({
+  redis,
+  keyPrefix: "idempotency:", // default
+});
+```
+
+### DuplicateMessageError
+
+Error thrown when `onDuplicate: "throw"` and a duplicate is detected.
+
+```typescript
+import { DuplicateMessageError } from "@saga-bus/middleware-idempotency";
+
+try {
+  await bus.publish(message);
+} catch (error) {
+  if (error instanceof DuplicateMessageError) {
+    console.log(`Duplicate: ${error.messageId} (${error.messageType})`);
+  }
+}
+```
+
+## Examples
+
+### Basic Usage
+
+```typescript
+import {
+  createIdempotencyMiddleware,
+  InMemoryIdempotencyStore,
+} from "@saga-bus/middleware-idempotency";
+
+const middleware = createIdempotencyMiddleware({
+  store: new InMemoryIdempotencyStore(),
+  windowMs: 300000, // 5 minutes
+});
+```
+
+### With Redis (Production)
+
+```typescript
+import Redis from "ioredis";
+import {
+  createIdempotencyMiddleware,
+  RedisIdempotencyStore,
+} from "@saga-bus/middleware-idempotency";
+
+const redis = new Redis(process.env.REDIS_URL);
+
+const middleware = createIdempotencyMiddleware({
+  store: new RedisIdempotencyStore({ redis }),
+  windowMs: 300000,
+});
+```
+
+### Custom Message ID Extraction
+
+```typescript
+// Use a combination of type and correlation ID for deduplication
+const middleware = createIdempotencyMiddleware({
+  store,
+  getMessageId: (envelope) =>
+    `${envelope.type}:${envelope.headers["x-correlation-id"]}`,
+});
+```
+
+### Logging Duplicates
+
+```typescript
+import { logger } from "./logger";
+
+const middleware = createIdempotencyMiddleware({
+  store,
+  onDuplicate: "log",
+  logger: {
+    warn: (message, meta) => logger.warn(message, meta),
+  },
+});
+```
+
+### Throwing on Duplicates
+
+```typescript
+import { createIdempotencyMiddleware, DuplicateMessageError } from "@saga-bus/middleware-idempotency";
+
+const middleware = createIdempotencyMiddleware({
+  store,
+  onDuplicate: "throw",
+});
+
+// In your error handler
+app.onError((error, c) => {
+  if (error instanceof DuplicateMessageError) {
+    return c.json({ error: "Duplicate request" }, 409);
+  }
+  throw error;
+});
+```
+
+### Excluding Message Types
+
+```typescript
+// Don't deduplicate heartbeat or ping messages
+const middleware = createIdempotencyMiddleware({
+  store,
+  excludeTypes: ["Heartbeat", "Ping", "HealthCheck"],
+});
+```
+
+### At-Most-Once vs At-Least-Once
+
+```typescript
+// At-most-once: Mark before processing
+// If processing fails, message won't be retried
+const atMostOnce = createIdempotencyMiddleware({
+  store,
+  markTiming: "before",
+});
+
+// At-least-once: Mark after processing (default)
+// If processing fails, message can be retried
+const atLeastOnce = createIdempotencyMiddleware({
+  store,
+  markTiming: "after",
+});
+```
+
+## Custom Store Implementation
+
+Implement the `IdempotencyStore` interface for custom storage:
+
+```typescript
+import type { IdempotencyStore } from "@saga-bus/middleware-idempotency";
+
+class MyCustomStore implements IdempotencyStore {
+  async has(messageId: string): Promise<boolean> {
+    // Check if messageId exists
+  }
+
+  async set(messageId: string, ttlMs?: number): Promise<void> {
+    // Store messageId with optional TTL
+  }
+
+  async delete(messageId: string): Promise<void> {
+    // Remove messageId
+  }
+
+  async clear(): Promise<void> {
+    // Clear all entries
+  }
+}
+```
+
+## How It Works
+
+1. When a message arrives, the middleware extracts its ID
+2. It checks if the ID exists in the store
+3. If found (duplicate):
+   - `skip`: Silently skip processing
+   - `log`: Log warning and skip
+   - `throw`: Throw `DuplicateMessageError`
+4. If not found (new message):
+   - With `markTiming: "before"`: Mark as processed, then run handler
+   - With `markTiming: "after"`: Run handler, then mark as processed
+5. The ID expires after `windowMs` milliseconds
+
+## Best Practices
+
+1. **Use Redis in production** for distributed systems with multiple instances
+2. **Set appropriate window sizes** based on your retry policies
+3. **Use `markTiming: "after"`** (default) for at-least-once delivery with retries
+4. **Use `markTiming: "before"`** for at-most-once delivery when idempotency is critical
+5. **Exclude naturally idempotent messages** like heartbeats and health checks
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,198 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  DuplicateMessageError: () => DuplicateMessageError,
+  InMemoryIdempotencyStore: () => InMemoryIdempotencyStore,
+  RedisIdempotencyStore: () => RedisIdempotencyStore,
+  createIdempotencyMiddleware: () => createIdempotencyMiddleware
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/types.ts
+var DuplicateMessageError = class extends Error {
+  messageId;
+  messageType;
+  constructor(messageId, messageType) {
+    super(`Duplicate message detected: ${messageId} (type: ${messageType})`);
+    this.name = "DuplicateMessageError";
+    this.messageId = messageId;
+    this.messageType = messageType;
+  }
+};
+
+// src/IdempotencyMiddleware.ts
+var defaultGetMessageId = (envelope) => envelope.id;
+function createIdempotencyMiddleware(options) {
+  const {
+    store,
+    windowMs = 6e4,
+    getMessageId = defaultGetMessageId,
+    onDuplicate = "skip",
+    logger,
+    excludeTypes = [],
+    markTiming = "after"
+  } = options;
+  const excludeSet = new Set(excludeTypes);
+  return async (ctx, next) => {
+    const { envelope } = ctx;
+    if (excludeSet.has(envelope.type)) {
+      await next();
+      return;
+    }
+    const messageId = getMessageId(envelope);
+    const isDuplicate = await store.has(messageId);
+    if (isDuplicate) {
+      switch (onDuplicate) {
+        case "throw":
+          throw new DuplicateMessageError(messageId, envelope.type);
+        case "log":
+          logger?.warn("Duplicate message detected, skipping", {
+            messageId,
+            messageType: envelope.type,
+            correlationId: ctx.correlationId,
+            sagaName: ctx.sagaName
+          });
+        // Fall through to skip
+        case "skip":
+        default:
+          return;
+      }
+    }
+    if (markTiming === "before") {
+      await store.set(messageId, windowMs);
+    }
+    await next();
+    if (markTiming === "after") {
+      await store.set(messageId, windowMs);
+    }
+  };
+}
+
+// src/stores/InMemoryIdempotencyStore.ts
+var InMemoryIdempotencyStore = class {
+  store = /* @__PURE__ */ new Map();
+  cleanupInterval = null;
+  /**
+   * Create an in-memory idempotency store.
+   * @param cleanupIntervalMs - How often to clean up expired entries (default: 60000ms)
+   */
+  constructor(cleanupIntervalMs = 6e4) {
+    if (cleanupIntervalMs > 0) {
+      this.cleanupInterval = setInterval(() => {
+        this.cleanup();
+      }, cleanupIntervalMs);
+      this.cleanupInterval.unref?.();
+    }
+  }
+  async has(messageId) {
+    const entry = this.store.get(messageId);
+    if (!entry) {
+      return false;
+    }
+    if (entry.expiresAt !== null && Date.now() > entry.expiresAt) {
+      this.store.delete(messageId);
+      return false;
+    }
+    return true;
+  }
+  async set(messageId, ttlMs) {
+    const expiresAt = ttlMs != null ? Date.now() + ttlMs : null;
+    this.store.set(messageId, { expiresAt });
+  }
+  async delete(messageId) {
+    this.store.delete(messageId);
+  }
+  async clear() {
+    this.store.clear();
+  }
+  /**
+   * Get the number of entries in the store (for testing).
+   */
+  get size() {
+    return this.store.size;
+  }
+  /**
+   * Stop the cleanup interval.
+   */
+  stop() {
+    if (this.cleanupInterval) {
+      clearInterval(this.cleanupInterval);
+      this.cleanupInterval = null;
+    }
+  }
+  /**
+   * Remove expired entries.
+   */
+  cleanup() {
+    const now = Date.now();
+    for (const [key, entry] of this.store) {
+      if (entry.expiresAt !== null && now > entry.expiresAt) {
+        this.store.delete(key);
+      }
+    }
+  }
+};
+
+// src/stores/RedisIdempotencyStore.ts
+var RedisIdempotencyStore = class {
+  redis;
+  keyPrefix;
+  constructor(options) {
+    this.redis = options.redis;
+    this.keyPrefix = options.keyPrefix ?? "idempotency:";
+  }
+  key(messageId) {
+    return `${this.keyPrefix}${messageId}`;
+  }
+  async has(messageId) {
+    const result = await this.redis.get(this.key(messageId));
+    return result !== null;
+  }
+  async set(messageId, ttlMs) {
+    const key = this.key(messageId);
+    if (ttlMs != null) {
+      const ttlSeconds = Math.ceil(ttlMs / 1e3);
+      await this.redis.setex(key, ttlSeconds, "1");
+    } else {
+      await this.redis.set(key, "1");
+    }
+  }
+  async delete(messageId) {
+    await this.redis.del(this.key(messageId));
+  }
+  async clear() {
+    const keys = await this.redis.keys(`${this.keyPrefix}*`);
+    if (keys.length > 0) {
+      for (const key of keys) {
+        await this.redis.del(key);
+      }
+    }
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DuplicateMessageError,
+  InMemoryIdempotencyStore,
+  RedisIdempotencyStore,
+  createIdempotencyMiddleware
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/types.ts","../src/IdempotencyMiddleware.ts","../src/stores/InMemoryIdempotencyStore.ts","../src/stores/RedisIdempotencyStore.ts"],"sourcesContent":["export { createIdempotencyMiddleware } from \"./IdempotencyMiddleware.js\";\nexport { InMemoryIdempotencyStore } from \"./stores/InMemoryIdempotencyStore.js\";\nexport { RedisIdempotencyStore } from \"./stores/RedisIdempotencyStore.js\";\nexport type { RedisIdempotencyStoreOptions } from \"./stores/RedisIdempotencyStore.js\";\nexport {\n  DuplicateMessageError,\n  type IdempotencyStore,\n  type IdempotencyMiddlewareOptions,\n  type MessageIdExtractor,\n  type DuplicateAction,\n} from \"./types.js\";\n","import type { MessageEnvelope } from \"@saga-bus/core\";\n\n/**\n * Store interface for tracking processed message IDs.\n */\nexport interface IdempotencyStore {\n  /**\n   * Check if a message ID has been processed.\n   * @param messageId - The message ID to check\n   * @returns true if the message was already processed\n   */\n  has(messageId: string): Promise<boolean>;\n\n  /**\n   * Mark a message ID as processed.\n   * @param messageId - The message ID to mark\n   * @param ttlMs - Time to live in milliseconds (optional)\n   */\n  set(messageId: string, ttlMs?: number): Promise<void>;\n\n  /**\n   * Remove a message ID from the store.\n   * @param messageId - The message ID to remove\n   */\n  delete(messageId: string): Promise<void>;\n\n  /**\n   * Clear all entries (useful for testing).\n   */\n  clear(): Promise<void>;\n}\n\n/**\n * Function to extract message ID from an envelope.\n */\nexport type MessageIdExtractor = (envelope: MessageEnvelope) => string;\n\n/**\n * Action to take when a duplicate message is detected.\n */\nexport type DuplicateAction = \"skip\" | \"log\" | \"throw\";\n\n/**\n * Options for the idempotency middleware.\n */\nexport interface IdempotencyMiddlewareOptions {\n  /**\n   * Store for tracking processed message IDs.\n   */\n  store: IdempotencyStore;\n\n  /**\n   * Time window for deduplication in milliseconds.\n   * Messages with the same ID within this window will be considered duplicates.\n   * @default 60000 (1 minute)\n   */\n  windowMs?: number;\n\n  /**\n   * Function to extract the message ID from an envelope.\n   * Defaults to using envelope.id.\n   */\n  getMessageId?: MessageIdExtractor;\n\n  /**\n   * Action to take when a duplicate is detected.\n   * - \"skip\": Silently skip processing (default)\n   * - \"log\": Skip but log a warning\n   * - \"throw\": Throw a DuplicateMessageError\n   * @default \"skip\"\n   */\n  onDuplicate?: DuplicateAction;\n\n  /**\n   * Custom logger for duplicate detection messages.\n   */\n  logger?: {\n    warn(message: string, meta?: Record<string, unknown>): void;\n  };\n\n  /**\n   * Message types to exclude from idempotency checks.\n   * Useful for messages that are naturally idempotent or should always be processed.\n   */\n  excludeTypes?: string[];\n\n  /**\n   * Whether to mark message as processed before or after handler execution.\n   * - \"before\": Mark before processing (at-most-once delivery)\n   * - \"after\": Mark after processing (at-least-once delivery, default)\n   * @default \"after\"\n   */\n  markTiming?: \"before\" | \"after\";\n}\n\n/**\n * Error thrown when a duplicate message is detected and onDuplicate is \"throw\".\n */\nexport class DuplicateMessageError extends Error {\n  public readonly messageId: string;\n  public readonly messageType: string;\n\n  constructor(messageId: string, messageType: string) {\n    super(`Duplicate message detected: ${messageId} (type: ${messageType})`);\n    this.name = \"DuplicateMessageError\";\n    this.messageId = messageId;\n    this.messageType = messageType;\n  }\n}\n","import type { SagaMiddleware, SagaPipelineContext } from \"@saga-bus/core\";\nimport type { IdempotencyMiddlewareOptions, MessageIdExtractor } from \"./types.js\";\nimport { DuplicateMessageError } from \"./types.js\";\n\n/**\n * Default message ID extractor - uses the envelope ID.\n */\nconst defaultGetMessageId: MessageIdExtractor = (envelope) => envelope.id;\n\n/**\n * Creates idempotency middleware that prevents duplicate message processing.\n *\n * @example\n * ```typescript\n * import { createIdempotencyMiddleware, InMemoryIdempotencyStore } from \"@saga-bus/middleware-idempotency\";\n *\n * const idempotencyMiddleware = createIdempotencyMiddleware({\n *   store: new InMemoryIdempotencyStore(),\n *   windowMs: 60000, // 1 minute deduplication window\n * });\n *\n * const bus = createBus({\n *   transport,\n *   store,\n *   sagas: [MySaga],\n *   middleware: [idempotencyMiddleware],\n * });\n * ```\n */\nexport function createIdempotencyMiddleware(\n  options: IdempotencyMiddlewareOptions\n): SagaMiddleware {\n  const {\n    store,\n    windowMs = 60000,\n    getMessageId = defaultGetMessageId,\n    onDuplicate = \"skip\",\n    logger,\n    excludeTypes = [],\n    markTiming = \"after\",\n  } = options;\n\n  const excludeSet = new Set(excludeTypes);\n\n  return async (ctx: SagaPipelineContext, next: () => Promise<void>) => {\n    const { envelope } = ctx;\n\n    // Check if this message type should be excluded from idempotency checks\n    if (excludeSet.has(envelope.type)) {\n      await next();\n      return;\n    }\n\n    // Extract message ID\n    const messageId = getMessageId(envelope);\n\n    // Check if message was already processed\n    const isDuplicate = await store.has(messageId);\n\n    if (isDuplicate) {\n      switch (onDuplicate) {\n        case \"throw\":\n          throw new DuplicateMessageError(messageId, envelope.type);\n\n        case \"log\":\n          logger?.warn(\"Duplicate message detected, skipping\", {\n            messageId,\n            messageType: envelope.type,\n            correlationId: ctx.correlationId,\n            sagaName: ctx.sagaName,\n          });\n          // Fall through to skip\n\n        case \"skip\":\n        default:\n          // Skip processing - don't call next()\n          return;\n      }\n    }\n\n    // Mark as processed before handler (at-most-once)\n    if (markTiming === \"before\") {\n      await store.set(messageId, windowMs);\n    }\n\n    // Process the message\n    await next();\n\n    // Mark as processed after handler (at-least-once, default)\n    if (markTiming === \"after\") {\n      await store.set(messageId, windowMs);\n    }\n  };\n}\n","import type { IdempotencyStore } from \"../types.js\";\n\ninterface StoreEntry {\n  expiresAt: number | null;\n}\n\n/**\n * In-memory idempotency store for development and testing.\n * Not suitable for distributed systems with multiple instances.\n */\nexport class InMemoryIdempotencyStore implements IdempotencyStore {\n  private readonly store = new Map<string, StoreEntry>();\n  private cleanupInterval: ReturnType<typeof setInterval> | null = null;\n\n  /**\n   * Create an in-memory idempotency store.\n   * @param cleanupIntervalMs - How often to clean up expired entries (default: 60000ms)\n   */\n  constructor(cleanupIntervalMs: number = 60000) {\n    if (cleanupIntervalMs > 0) {\n      this.cleanupInterval = setInterval(() => {\n        this.cleanup();\n      }, cleanupIntervalMs);\n      // Don't keep the process alive just for cleanup\n      this.cleanupInterval.unref?.();\n    }\n  }\n\n  async has(messageId: string): Promise<boolean> {\n    const entry = this.store.get(messageId);\n    if (!entry) {\n      return false;\n    }\n    // Check if expired\n    if (entry.expiresAt !== null && Date.now() > entry.expiresAt) {\n      this.store.delete(messageId);\n      return false;\n    }\n    return true;\n  }\n\n  async set(messageId: string, ttlMs?: number): Promise<void> {\n    const expiresAt = ttlMs != null ? Date.now() + ttlMs : null;\n    this.store.set(messageId, { expiresAt });\n  }\n\n  async delete(messageId: string): Promise<void> {\n    this.store.delete(messageId);\n  }\n\n  async clear(): Promise<void> {\n    this.store.clear();\n  }\n\n  /**\n   * Get the number of entries in the store (for testing).\n   */\n  get size(): number {\n    return this.store.size;\n  }\n\n  /**\n   * Stop the cleanup interval.\n   */\n  stop(): void {\n    if (this.cleanupInterval) {\n      clearInterval(this.cleanupInterval);\n      this.cleanupInterval = null;\n    }\n  }\n\n  /**\n   * Remove expired entries.\n   */\n  private cleanup(): void {\n    const now = Date.now();\n    for (const [key, entry] of this.store) {\n      if (entry.expiresAt !== null && now > entry.expiresAt) {\n        this.store.delete(key);\n      }\n    }\n  }\n}\n","import type { IdempotencyStore } from \"../types.js\";\n\n// Use a type-only import for Redis to make it optional\ntype Redis = {\n  get(key: string): Promise<string | null>;\n  set(key: string, value: string, mode?: string, duration?: number): Promise<string | null>;\n  setex(key: string, seconds: number, value: string): Promise<string>;\n  del(key: string): Promise<number>;\n  keys(pattern: string): Promise<string[]>;\n};\n\n/**\n * Options for the Redis idempotency store.\n */\nexport interface RedisIdempotencyStoreOptions {\n  /**\n   * Redis client instance (ioredis).\n   */\n  redis: Redis;\n\n  /**\n   * Key prefix for all idempotency keys.\n   * @default \"idempotency:\"\n   */\n  keyPrefix?: string;\n}\n\n/**\n * Redis-backed idempotency store for distributed systems.\n * Requires ioredis as a peer dependency.\n */\nexport class RedisIdempotencyStore implements IdempotencyStore {\n  private readonly redis: Redis;\n  private readonly keyPrefix: string;\n\n  constructor(options: RedisIdempotencyStoreOptions) {\n    this.redis = options.redis;\n    this.keyPrefix = options.keyPrefix ?? \"idempotency:\";\n  }\n\n  private key(messageId: string): string {\n    return `${this.keyPrefix}${messageId}`;\n  }\n\n  async has(messageId: string): Promise<boolean> {\n    const result = await this.redis.get(this.key(messageId));\n    return result !== null;\n  }\n\n  async set(messageId: string, ttlMs?: number): Promise<void> {\n    const key = this.key(messageId);\n    if (ttlMs != null) {\n      // Convert ms to seconds (Redis SETEX uses seconds)\n      const ttlSeconds = Math.ceil(ttlMs / 1000);\n      await this.redis.setex(key, ttlSeconds, \"1\");\n    } else {\n      await this.redis.set(key, \"1\");\n    }\n  }\n\n  async delete(messageId: string): Promise<void> {\n    await this.redis.del(this.key(messageId));\n  }\n\n  async clear(): Promise<void> {\n    // Get all keys with our prefix and delete them\n    const keys = await this.redis.keys(`${this.keyPrefix}*`);\n    if (keys.length > 0) {\n      for (const key of keys) {\n        await this.redis.del(key);\n      }\n    }\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/index.d.cts

@@ -0,0 +1,180 @@
+import { MessageEnvelope, SagaMiddleware } from '@saga-bus/core';
+
+/**
+ * Store interface for tracking processed message IDs.
+ */
+interface IdempotencyStore {
+    /**
+     * Check if a message ID has been processed.
+     * @param messageId - The message ID to check
+     * @returns true if the message was already processed
+     */
+    has(messageId: string): Promise<boolean>;
+    /**
+     * Mark a message ID as processed.
+     * @param messageId - The message ID to mark
+     * @param ttlMs - Time to live in milliseconds (optional)
+     */
+    set(messageId: string, ttlMs?: number): Promise<void>;
+    /**
+     * Remove a message ID from the store.
+     * @param messageId - The message ID to remove
+     */
+    delete(messageId: string): Promise<void>;
+    /**
+     * Clear all entries (useful for testing).
+     */
+    clear(): Promise<void>;
+}
+/**
+ * Function to extract message ID from an envelope.
+ */
+type MessageIdExtractor = (envelope: MessageEnvelope) => string;
+/**
+ * Action to take when a duplicate message is detected.
+ */
+type DuplicateAction = "skip" | "log" | "throw";
+/**
+ * Options for the idempotency middleware.
+ */
+interface IdempotencyMiddlewareOptions {
+    /**
+     * Store for tracking processed message IDs.
+     */
+    store: IdempotencyStore;
+    /**
+     * Time window for deduplication in milliseconds.
+     * Messages with the same ID within this window will be considered duplicates.
+     * @default 60000 (1 minute)
+     */
+    windowMs?: number;
+    /**
+     * Function to extract the message ID from an envelope.
+     * Defaults to using envelope.id.
+     */
+    getMessageId?: MessageIdExtractor;
+    /**
+     * Action to take when a duplicate is detected.
+     * - "skip": Silently skip processing (default)
+     * - "log": Skip but log a warning
+     * - "throw": Throw a DuplicateMessageError
+     * @default "skip"
+     */
+    onDuplicate?: DuplicateAction;
+    /**
+     * Custom logger for duplicate detection messages.
+     */
+    logger?: {
+        warn(message: string, meta?: Record<string, unknown>): void;
+    };
+    /**
+     * Message types to exclude from idempotency checks.
+     * Useful for messages that are naturally idempotent or should always be processed.
+     */
+    excludeTypes?: string[];
+    /**
+     * Whether to mark message as processed before or after handler execution.
+     * - "before": Mark before processing (at-most-once delivery)
+     * - "after": Mark after processing (at-least-once delivery, default)
+     * @default "after"
+     */
+    markTiming?: "before" | "after";
+}
+/**
+ * Error thrown when a duplicate message is detected and onDuplicate is "throw".
+ */
+declare class DuplicateMessageError extends Error {
+    readonly messageId: string;
+    readonly messageType: string;
+    constructor(messageId: string, messageType: string);
+}
+
+/**
+ * Creates idempotency middleware that prevents duplicate message processing.
+ *
+ * @example
+ * ```typescript
+ * import { createIdempotencyMiddleware, InMemoryIdempotencyStore } from "@saga-bus/middleware-idempotency";
+ *
+ * const idempotencyMiddleware = createIdempotencyMiddleware({
+ *   store: new InMemoryIdempotencyStore(),
+ *   windowMs: 60000, // 1 minute deduplication window
+ * });
+ *
+ * const bus = createBus({
+ *   transport,
+ *   store,
+ *   sagas: [MySaga],
+ *   middleware: [idempotencyMiddleware],
+ * });
+ * ```
+ */
+declare function createIdempotencyMiddleware(options: IdempotencyMiddlewareOptions): SagaMiddleware;
+
+/**
+ * In-memory idempotency store for development and testing.
+ * Not suitable for distributed systems with multiple instances.
+ */
+declare class InMemoryIdempotencyStore implements IdempotencyStore {
+    private readonly store;
+    private cleanupInterval;
+    /**
+     * Create an in-memory idempotency store.
+     * @param cleanupIntervalMs - How often to clean up expired entries (default: 60000ms)
+     */
+    constructor(cleanupIntervalMs?: number);
+    has(messageId: string): Promise<boolean>;
+    set(messageId: string, ttlMs?: number): Promise<void>;
+    delete(messageId: string): Promise<void>;
+    clear(): Promise<void>;
+    /**
+     * Get the number of entries in the store (for testing).
+     */
+    get size(): number;
+    /**
+     * Stop the cleanup interval.
+     */
+    stop(): void;
+    /**
+     * Remove expired entries.
+     */
+    private cleanup;
+}
+
+type Redis = {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, mode?: string, duration?: number): Promise<string | null>;
+    setex(key: string, seconds: number, value: string): Promise<string>;
+    del(key: string): Promise<number>;
+    keys(pattern: string): Promise<string[]>;
+};
+/**
+ * Options for the Redis idempotency store.
+ */
+interface RedisIdempotencyStoreOptions {
+    /**
+     * Redis client instance (ioredis).
+     */
+    redis: Redis;
+    /**
+     * Key prefix for all idempotency keys.
+     * @default "idempotency:"
+     */
+    keyPrefix?: string;
+}
+/**
+ * Redis-backed idempotency store for distributed systems.
+ * Requires ioredis as a peer dependency.
+ */
+declare class RedisIdempotencyStore implements IdempotencyStore {
+    private readonly redis;
+    private readonly keyPrefix;
+    constructor(options: RedisIdempotencyStoreOptions);
+    private key;
+    has(messageId: string): Promise<boolean>;
+    set(messageId: string, ttlMs?: number): Promise<void>;
+    delete(messageId: string): Promise<void>;
+    clear(): Promise<void>;
+}
+
+export { type DuplicateAction, DuplicateMessageError, type IdempotencyMiddlewareOptions, type IdempotencyStore, InMemoryIdempotencyStore, type MessageIdExtractor, RedisIdempotencyStore, type RedisIdempotencyStoreOptions, createIdempotencyMiddleware };

package/dist/index.d.ts

@@ -0,0 +1,180 @@
+import { MessageEnvelope, SagaMiddleware } from '@saga-bus/core';
+
+/**
+ * Store interface for tracking processed message IDs.
+ */
+interface IdempotencyStore {
+    /**
+     * Check if a message ID has been processed.
+     * @param messageId - The message ID to check
+     * @returns true if the message was already processed
+     */
+    has(messageId: string): Promise<boolean>;
+    /**
+     * Mark a message ID as processed.
+     * @param messageId - The message ID to mark
+     * @param ttlMs - Time to live in milliseconds (optional)
+     */
+    set(messageId: string, ttlMs?: number): Promise<void>;
+    /**
+     * Remove a message ID from the store.
+     * @param messageId - The message ID to remove
+     */
+    delete(messageId: string): Promise<void>;
+    /**
+     * Clear all entries (useful for testing).
+     */
+    clear(): Promise<void>;
+}
+/**
+ * Function to extract message ID from an envelope.
+ */
+type MessageIdExtractor = (envelope: MessageEnvelope) => string;
+/**
+ * Action to take when a duplicate message is detected.
+ */
+type DuplicateAction = "skip" | "log" | "throw";
+/**
+ * Options for the idempotency middleware.
+ */
+interface IdempotencyMiddlewareOptions {
+    /**
+     * Store for tracking processed message IDs.
+     */
+    store: IdempotencyStore;
+    /**
+     * Time window for deduplication in milliseconds.
+     * Messages with the same ID within this window will be considered duplicates.
+     * @default 60000 (1 minute)
+     */
+    windowMs?: number;
+    /**
+     * Function to extract the message ID from an envelope.
+     * Defaults to using envelope.id.
+     */
+    getMessageId?: MessageIdExtractor;
+    /**
+     * Action to take when a duplicate is detected.
+     * - "skip": Silently skip processing (default)
+     * - "log": Skip but log a warning
+     * - "throw": Throw a DuplicateMessageError
+     * @default "skip"
+     */
+    onDuplicate?: DuplicateAction;
+    /**
+     * Custom logger for duplicate detection messages.
+     */
+    logger?: {
+        warn(message: string, meta?: Record<string, unknown>): void;
+    };
+    /**
+     * Message types to exclude from idempotency checks.
+     * Useful for messages that are naturally idempotent or should always be processed.
+     */
+    excludeTypes?: string[];
+    /**
+     * Whether to mark message as processed before or after handler execution.
+     * - "before": Mark before processing (at-most-once delivery)
+     * - "after": Mark after processing (at-least-once delivery, default)
+     * @default "after"
+     */
+    markTiming?: "before" | "after";
+}
+/**
+ * Error thrown when a duplicate message is detected and onDuplicate is "throw".
+ */
+declare class DuplicateMessageError extends Error {
+    readonly messageId: string;
+    readonly messageType: string;
+    constructor(messageId: string, messageType: string);
+}
+
+/**
+ * Creates idempotency middleware that prevents duplicate message processing.
+ *
+ * @example
+ * ```typescript
+ * import { createIdempotencyMiddleware, InMemoryIdempotencyStore } from "@saga-bus/middleware-idempotency";
+ *
+ * const idempotencyMiddleware = createIdempotencyMiddleware({
+ *   store: new InMemoryIdempotencyStore(),
+ *   windowMs: 60000, // 1 minute deduplication window
+ * });
+ *
+ * const bus = createBus({
+ *   transport,
+ *   store,
+ *   sagas: [MySaga],
+ *   middleware: [idempotencyMiddleware],
+ * });
+ * ```
+ */
+declare function createIdempotencyMiddleware(options: IdempotencyMiddlewareOptions): SagaMiddleware;
+
+/**
+ * In-memory idempotency store for development and testing.
+ * Not suitable for distributed systems with multiple instances.
+ */
+declare class InMemoryIdempotencyStore implements IdempotencyStore {
+    private readonly store;
+    private cleanupInterval;
+    /**
+     * Create an in-memory idempotency store.
+     * @param cleanupIntervalMs - How often to clean up expired entries (default: 60000ms)
+     */
+    constructor(cleanupIntervalMs?: number);
+    has(messageId: string): Promise<boolean>;
+    set(messageId: string, ttlMs?: number): Promise<void>;
+    delete(messageId: string): Promise<void>;
+    clear(): Promise<void>;
+    /**
+     * Get the number of entries in the store (for testing).
+     */
+    get size(): number;
+    /**
+     * Stop the cleanup interval.
+     */
+    stop(): void;
+    /**
+     * Remove expired entries.
+     */
+    private cleanup;
+}
+
+type Redis = {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, mode?: string, duration?: number): Promise<string | null>;
+    setex(key: string, seconds: number, value: string): Promise<string>;
+    del(key: string): Promise<number>;
+    keys(pattern: string): Promise<string[]>;
+};
+/**
+ * Options for the Redis idempotency store.
+ */
+interface RedisIdempotencyStoreOptions {
+    /**
+     * Redis client instance (ioredis).
+     */
+    redis: Redis;
+    /**
+     * Key prefix for all idempotency keys.
+     * @default "idempotency:"
+     */
+    keyPrefix?: string;
+}
+/**
+ * Redis-backed idempotency store for distributed systems.
+ * Requires ioredis as a peer dependency.
+ */
+declare class RedisIdempotencyStore implements IdempotencyStore {
+    private readonly redis;
+    private readonly keyPrefix;
+    constructor(options: RedisIdempotencyStoreOptions);
+    private key;
+    has(messageId: string): Promise<boolean>;
+    set(messageId: string, ttlMs?: number): Promise<void>;
+    delete(messageId: string): Promise<void>;
+    clear(): Promise<void>;
+}
+
+export { type DuplicateAction, DuplicateMessageError, type IdempotencyMiddlewareOptions, type IdempotencyStore, InMemoryIdempotencyStore, type MessageIdExtractor, RedisIdempotencyStore, type RedisIdempotencyStoreOptions, createIdempotencyMiddleware };

package/dist/index.js

@@ -0,0 +1,168 @@
+// src/types.ts
+var DuplicateMessageError = class extends Error {
+  messageId;
+  messageType;
+  constructor(messageId, messageType) {
+    super(`Duplicate message detected: ${messageId} (type: ${messageType})`);
+    this.name = "DuplicateMessageError";
+    this.messageId = messageId;
+    this.messageType = messageType;
+  }
+};
+
+// src/IdempotencyMiddleware.ts
+var defaultGetMessageId = (envelope) => envelope.id;
+function createIdempotencyMiddleware(options) {
+  const {
+    store,
+    windowMs = 6e4,
+    getMessageId = defaultGetMessageId,
+    onDuplicate = "skip",
+    logger,
+    excludeTypes = [],
+    markTiming = "after"
+  } = options;
+  const excludeSet = new Set(excludeTypes);
+  return async (ctx, next) => {
+    const { envelope } = ctx;
+    if (excludeSet.has(envelope.type)) {
+      await next();
+      return;
+    }
+    const messageId = getMessageId(envelope);
+    const isDuplicate = await store.has(messageId);
+    if (isDuplicate) {
+      switch (onDuplicate) {
+        case "throw":
+          throw new DuplicateMessageError(messageId, envelope.type);
+        case "log":
+          logger?.warn("Duplicate message detected, skipping", {
+            messageId,
+            messageType: envelope.type,
+            correlationId: ctx.correlationId,
+            sagaName: ctx.sagaName
+          });
+        // Fall through to skip
+        case "skip":
+        default:
+          return;
+      }
+    }
+    if (markTiming === "before") {
+      await store.set(messageId, windowMs);
+    }
+    await next();
+    if (markTiming === "after") {
+      await store.set(messageId, windowMs);
+    }
+  };
+}
+
+// src/stores/InMemoryIdempotencyStore.ts
+var InMemoryIdempotencyStore = class {
+  store = /* @__PURE__ */ new Map();
+  cleanupInterval = null;
+  /**
+   * Create an in-memory idempotency store.
+   * @param cleanupIntervalMs - How often to clean up expired entries (default: 60000ms)
+   */
+  constructor(cleanupIntervalMs = 6e4) {
+    if (cleanupIntervalMs > 0) {
+      this.cleanupInterval = setInterval(() => {
+        this.cleanup();
+      }, cleanupIntervalMs);
+      this.cleanupInterval.unref?.();
+    }
+  }
+  async has(messageId) {
+    const entry = this.store.get(messageId);
+    if (!entry) {
+      return false;
+    }
+    if (entry.expiresAt !== null && Date.now() > entry.expiresAt) {
+      this.store.delete(messageId);
+      return false;
+    }
+    return true;
+  }
+  async set(messageId, ttlMs) {
+    const expiresAt = ttlMs != null ? Date.now() + ttlMs : null;
+    this.store.set(messageId, { expiresAt });
+  }
+  async delete(messageId) {
+    this.store.delete(messageId);
+  }
+  async clear() {
+    this.store.clear();
+  }
+  /**
+   * Get the number of entries in the store (for testing).
+   */
+  get size() {
+    return this.store.size;
+  }
+  /**
+   * Stop the cleanup interval.
+   */
+  stop() {
+    if (this.cleanupInterval) {
+      clearInterval(this.cleanupInterval);
+      this.cleanupInterval = null;
+    }
+  }
+  /**
+   * Remove expired entries.
+   */
+  cleanup() {
+    const now = Date.now();
+    for (const [key, entry] of this.store) {
+      if (entry.expiresAt !== null && now > entry.expiresAt) {
+        this.store.delete(key);
+      }
+    }
+  }
+};
+
+// src/stores/RedisIdempotencyStore.ts
+var RedisIdempotencyStore = class {
+  redis;
+  keyPrefix;
+  constructor(options) {
+    this.redis = options.redis;
+    this.keyPrefix = options.keyPrefix ?? "idempotency:";
+  }
+  key(messageId) {
+    return `${this.keyPrefix}${messageId}`;
+  }
+  async has(messageId) {
+    const result = await this.redis.get(this.key(messageId));
+    return result !== null;
+  }
+  async set(messageId, ttlMs) {
+    const key = this.key(messageId);
+    if (ttlMs != null) {
+      const ttlSeconds = Math.ceil(ttlMs / 1e3);
+      await this.redis.setex(key, ttlSeconds, "1");
+    } else {
+      await this.redis.set(key, "1");
+    }
+  }
+  async delete(messageId) {
+    await this.redis.del(this.key(messageId));
+  }
+  async clear() {
+    const keys = await this.redis.keys(`${this.keyPrefix}*`);
+    if (keys.length > 0) {
+      for (const key of keys) {
+        await this.redis.del(key);
+      }
+    }
+  }
+};
+export {
+  DuplicateMessageError,
+  InMemoryIdempotencyStore,
+  RedisIdempotencyStore,
+  createIdempotencyMiddleware
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/types.ts","../src/IdempotencyMiddleware.ts","../src/stores/InMemoryIdempotencyStore.ts","../src/stores/RedisIdempotencyStore.ts"],"sourcesContent":["import type { MessageEnvelope } from \"@saga-bus/core\";\n\n/**\n * Store interface for tracking processed message IDs.\n */\nexport interface IdempotencyStore {\n  /**\n   * Check if a message ID has been processed.\n   * @param messageId - The message ID to check\n   * @returns true if the message was already processed\n   */\n  has(messageId: string): Promise<boolean>;\n\n  /**\n   * Mark a message ID as processed.\n   * @param messageId - The message ID to mark\n   * @param ttlMs - Time to live in milliseconds (optional)\n   */\n  set(messageId: string, ttlMs?: number): Promise<void>;\n\n  /**\n   * Remove a message ID from the store.\n   * @param messageId - The message ID to remove\n   */\n  delete(messageId: string): Promise<void>;\n\n  /**\n   * Clear all entries (useful for testing).\n   */\n  clear(): Promise<void>;\n}\n\n/**\n * Function to extract message ID from an envelope.\n */\nexport type MessageIdExtractor = (envelope: MessageEnvelope) => string;\n\n/**\n * Action to take when a duplicate message is detected.\n */\nexport type DuplicateAction = \"skip\" | \"log\" | \"throw\";\n\n/**\n * Options for the idempotency middleware.\n */\nexport interface IdempotencyMiddlewareOptions {\n  /**\n   * Store for tracking processed message IDs.\n   */\n  store: IdempotencyStore;\n\n  /**\n   * Time window for deduplication in milliseconds.\n   * Messages with the same ID within this window will be considered duplicates.\n   * @default 60000 (1 minute)\n   */\n  windowMs?: number;\n\n  /**\n   * Function to extract the message ID from an envelope.\n   * Defaults to using envelope.id.\n   */\n  getMessageId?: MessageIdExtractor;\n\n  /**\n   * Action to take when a duplicate is detected.\n   * - \"skip\": Silently skip processing (default)\n   * - \"log\": Skip but log a warning\n   * - \"throw\": Throw a DuplicateMessageError\n   * @default \"skip\"\n   */\n  onDuplicate?: DuplicateAction;\n\n  /**\n   * Custom logger for duplicate detection messages.\n   */\n  logger?: {\n    warn(message: string, meta?: Record<string, unknown>): void;\n  };\n\n  /**\n   * Message types to exclude from idempotency checks.\n   * Useful for messages that are naturally idempotent or should always be processed.\n   */\n  excludeTypes?: string[];\n\n  /**\n   * Whether to mark message as processed before or after handler execution.\n   * - \"before\": Mark before processing (at-most-once delivery)\n   * - \"after\": Mark after processing (at-least-once delivery, default)\n   * @default \"after\"\n   */\n  markTiming?: \"before\" | \"after\";\n}\n\n/**\n * Error thrown when a duplicate message is detected and onDuplicate is \"throw\".\n */\nexport class DuplicateMessageError extends Error {\n  public readonly messageId: string;\n  public readonly messageType: string;\n\n  constructor(messageId: string, messageType: string) {\n    super(`Duplicate message detected: ${messageId} (type: ${messageType})`);\n    this.name = \"DuplicateMessageError\";\n    this.messageId = messageId;\n    this.messageType = messageType;\n  }\n}\n","import type { SagaMiddleware, SagaPipelineContext } from \"@saga-bus/core\";\nimport type { IdempotencyMiddlewareOptions, MessageIdExtractor } from \"./types.js\";\nimport { DuplicateMessageError } from \"./types.js\";\n\n/**\n * Default message ID extractor - uses the envelope ID.\n */\nconst defaultGetMessageId: MessageIdExtractor = (envelope) => envelope.id;\n\n/**\n * Creates idempotency middleware that prevents duplicate message processing.\n *\n * @example\n * ```typescript\n * import { createIdempotencyMiddleware, InMemoryIdempotencyStore } from \"@saga-bus/middleware-idempotency\";\n *\n * const idempotencyMiddleware = createIdempotencyMiddleware({\n *   store: new InMemoryIdempotencyStore(),\n *   windowMs: 60000, // 1 minute deduplication window\n * });\n *\n * const bus = createBus({\n *   transport,\n *   store,\n *   sagas: [MySaga],\n *   middleware: [idempotencyMiddleware],\n * });\n * ```\n */\nexport function createIdempotencyMiddleware(\n  options: IdempotencyMiddlewareOptions\n): SagaMiddleware {\n  const {\n    store,\n    windowMs = 60000,\n    getMessageId = defaultGetMessageId,\n    onDuplicate = \"skip\",\n    logger,\n    excludeTypes = [],\n    markTiming = \"after\",\n  } = options;\n\n  const excludeSet = new Set(excludeTypes);\n\n  return async (ctx: SagaPipelineContext, next: () => Promise<void>) => {\n    const { envelope } = ctx;\n\n    // Check if this message type should be excluded from idempotency checks\n    if (excludeSet.has(envelope.type)) {\n      await next();\n      return;\n    }\n\n    // Extract message ID\n    const messageId = getMessageId(envelope);\n\n    // Check if message was already processed\n    const isDuplicate = await store.has(messageId);\n\n    if (isDuplicate) {\n      switch (onDuplicate) {\n        case \"throw\":\n          throw new DuplicateMessageError(messageId, envelope.type);\n\n        case \"log\":\n          logger?.warn(\"Duplicate message detected, skipping\", {\n            messageId,\n            messageType: envelope.type,\n            correlationId: ctx.correlationId,\n            sagaName: ctx.sagaName,\n          });\n          // Fall through to skip\n\n        case \"skip\":\n        default:\n          // Skip processing - don't call next()\n          return;\n      }\n    }\n\n    // Mark as processed before handler (at-most-once)\n    if (markTiming === \"before\") {\n      await store.set(messageId, windowMs);\n    }\n\n    // Process the message\n    await next();\n\n    // Mark as processed after handler (at-least-once, default)\n    if (markTiming === \"after\") {\n      await store.set(messageId, windowMs);\n    }\n  };\n}\n","import type { IdempotencyStore } from \"../types.js\";\n\ninterface StoreEntry {\n  expiresAt: number | null;\n}\n\n/**\n * In-memory idempotency store for development and testing.\n * Not suitable for distributed systems with multiple instances.\n */\nexport class InMemoryIdempotencyStore implements IdempotencyStore {\n  private readonly store = new Map<string, StoreEntry>();\n  private cleanupInterval: ReturnType<typeof setInterval> | null = null;\n\n  /**\n   * Create an in-memory idempotency store.\n   * @param cleanupIntervalMs - How often to clean up expired entries (default: 60000ms)\n   */\n  constructor(cleanupIntervalMs: number = 60000) {\n    if (cleanupIntervalMs > 0) {\n      this.cleanupInterval = setInterval(() => {\n        this.cleanup();\n      }, cleanupIntervalMs);\n      // Don't keep the process alive just for cleanup\n      this.cleanupInterval.unref?.();\n    }\n  }\n\n  async has(messageId: string): Promise<boolean> {\n    const entry = this.store.get(messageId);\n    if (!entry) {\n      return false;\n    }\n    // Check if expired\n    if (entry.expiresAt !== null && Date.now() > entry.expiresAt) {\n      this.store.delete(messageId);\n      return false;\n    }\n    return true;\n  }\n\n  async set(messageId: string, ttlMs?: number): Promise<void> {\n    const expiresAt = ttlMs != null ? Date.now() + ttlMs : null;\n    this.store.set(messageId, { expiresAt });\n  }\n\n  async delete(messageId: string): Promise<void> {\n    this.store.delete(messageId);\n  }\n\n  async clear(): Promise<void> {\n    this.store.clear();\n  }\n\n  /**\n   * Get the number of entries in the store (for testing).\n   */\n  get size(): number {\n    return this.store.size;\n  }\n\n  /**\n   * Stop the cleanup interval.\n   */\n  stop(): void {\n    if (this.cleanupInterval) {\n      clearInterval(this.cleanupInterval);\n      this.cleanupInterval = null;\n    }\n  }\n\n  /**\n   * Remove expired entries.\n   */\n  private cleanup(): void {\n    const now = Date.now();\n    for (const [key, entry] of this.store) {\n      if (entry.expiresAt !== null && now > entry.expiresAt) {\n        this.store.delete(key);\n      }\n    }\n  }\n}\n","import type { IdempotencyStore } from \"../types.js\";\n\n// Use a type-only import for Redis to make it optional\ntype Redis = {\n  get(key: string): Promise<string | null>;\n  set(key: string, value: string, mode?: string, duration?: number): Promise<string | null>;\n  setex(key: string, seconds: number, value: string): Promise<string>;\n  del(key: string): Promise<number>;\n  keys(pattern: string): Promise<string[]>;\n};\n\n/**\n * Options for the Redis idempotency store.\n */\nexport interface RedisIdempotencyStoreOptions {\n  /**\n   * Redis client instance (ioredis).\n   */\n  redis: Redis;\n\n  /**\n   * Key prefix for all idempotency keys.\n   * @default \"idempotency:\"\n   */\n  keyPrefix?: string;\n}\n\n/**\n * Redis-backed idempotency store for distributed systems.\n * Requires ioredis as a peer dependency.\n */\nexport class RedisIdempotencyStore implements IdempotencyStore {\n  private readonly redis: Redis;\n  private readonly keyPrefix: string;\n\n  constructor(options: RedisIdempotencyStoreOptions) {\n    this.redis = options.redis;\n    this.keyPrefix = options.keyPrefix ?? \"idempotency:\";\n  }\n\n  private key(messageId: string): string {\n    return `${this.keyPrefix}${messageId}`;\n  }\n\n  async has(messageId: string): Promise<boolean> {\n    const result = await this.redis.get(this.key(messageId));\n    return result !== null;\n  }\n\n  async set(messageId: string, ttlMs?: number): Promise<void> {\n    const key = this.key(messageId);\n    if (ttlMs != null) {\n      // Convert ms to seconds (Redis SETEX uses seconds)\n      const ttlSeconds = Math.ceil(ttlMs / 1000);\n      await this.redis.setex(key, ttlSeconds, \"1\");\n    } else {\n      await this.redis.set(key, \"1\");\n    }\n  }\n\n  async delete(messageId: string): Promise<void> {\n    await this.redis.del(this.key(messageId));\n  }\n\n  async clear(): Promise<void> {\n    // Get all keys with our prefix and delete them\n    const keys = await this.redis.keys(`${this.keyPrefix}*`);\n    if (keys.length > 0) {\n      for (const key of keys) {\n        await this.redis.del(key);\n      }\n    }\n  }\n}\n"],"mappings":";AAkGO,IAAM,wBAAN,cAAoC,MAAM;AAAA,EAC/B;AAAA,EACA;AAAA,EAEhB,YAAY,WAAmB,aAAqB;AAClD,UAAM,+BAA+B,SAAS,WAAW,WAAW,GAAG;AACvE,SAAK,OAAO;AACZ,SAAK,YAAY;AACjB,SAAK,cAAc;AAAA,EACrB;AACF;;;ACrGA,IAAM,sBAA0C,CAAC,aAAa,SAAS;AAsBhE,SAAS,4BACd,SACgB;AAChB,QAAM;AAAA,IACJ;AAAA,IACA,WAAW;AAAA,IACX,eAAe;AAAA,IACf,cAAc;AAAA,IACd;AAAA,IACA,eAAe,CAAC;AAAA,IAChB,aAAa;AAAA,EACf,IAAI;AAEJ,QAAM,aAAa,IAAI,IAAI,YAAY;AAEvC,SAAO,OAAO,KAA0B,SAA8B;AACpE,UAAM,EAAE,SAAS,IAAI;AAGrB,QAAI,WAAW,IAAI,SAAS,IAAI,GAAG;AACjC,YAAM,KAAK;AACX;AAAA,IACF;AAGA,UAAM,YAAY,aAAa,QAAQ;AAGvC,UAAM,cAAc,MAAM,MAAM,IAAI,SAAS;AAE7C,QAAI,aAAa;AACf,cAAQ,aAAa;AAAA,QACnB,KAAK;AACH,gBAAM,IAAI,sBAAsB,WAAW,SAAS,IAAI;AAAA,QAE1D,KAAK;AACH,kBAAQ,KAAK,wCAAwC;AAAA,YACnD;AAAA,YACA,aAAa,SAAS;AAAA,YACtB,eAAe,IAAI;AAAA,YACnB,UAAU,IAAI;AAAA,UAChB,CAAC;AAAA;AAAA,QAGH,KAAK;AAAA,QACL;AAEE;AAAA,MACJ;AAAA,IACF;AAGA,QAAI,eAAe,UAAU;AAC3B,YAAM,MAAM,IAAI,WAAW,QAAQ;AAAA,IACrC;AAGA,UAAM,KAAK;AAGX,QAAI,eAAe,SAAS;AAC1B,YAAM,MAAM,IAAI,WAAW,QAAQ;AAAA,IACrC;AAAA,EACF;AACF;;;ACnFO,IAAM,2BAAN,MAA2D;AAAA,EAC/C,QAAQ,oBAAI,IAAwB;AAAA,EAC7C,kBAAyD;AAAA;AAAA;AAAA;AAAA;AAAA,EAMjE,YAAY,oBAA4B,KAAO;AAC7C,QAAI,oBAAoB,GAAG;AACzB,WAAK,kBAAkB,YAAY,MAAM;AACvC,aAAK,QAAQ;AAAA,MACf,GAAG,iBAAiB;AAEpB,WAAK,gBAAgB,QAAQ;AAAA,IAC/B;AAAA,EACF;AAAA,EAEA,MAAM,IAAI,WAAqC;AAC7C,UAAM,QAAQ,KAAK,MAAM,IAAI,SAAS;AACtC,QAAI,CAAC,OAAO;AACV,aAAO;AAAA,IACT;AAEA,QAAI,MAAM,cAAc,QAAQ,KAAK,IAAI,IAAI,MAAM,WAAW;AAC5D,WAAK,MAAM,OAAO,SAAS;AAC3B,aAAO;AAAA,IACT;AACA,WAAO;AAAA,EACT;AAAA,EAEA,MAAM,IAAI,WAAmB,OAA+B;AAC1D,UAAM,YAAY,SAAS,OAAO,KAAK,IAAI,IAAI,QAAQ;AACvD,SAAK,MAAM,IAAI,WAAW,EAAE,UAAU,CAAC;AAAA,EACzC;AAAA,EAEA,MAAM,OAAO,WAAkC;AAC7C,SAAK,MAAM,OAAO,SAAS;AAAA,EAC7B;AAAA,EAEA,MAAM,QAAuB;AAC3B,SAAK,MAAM,MAAM;AAAA,EACnB;AAAA;AAAA;AAAA;AAAA,EAKA,IAAI,OAAe;AACjB,WAAO,KAAK,MAAM;AAAA,EACpB;AAAA;AAAA;AAAA;AAAA,EAKA,OAAa;AACX,QAAI,KAAK,iBAAiB;AACxB,oBAAc,KAAK,eAAe;AAClC,WAAK,kBAAkB;AAAA,IACzB;AAAA,EACF;AAAA;AAAA;AAAA;AAAA,EAKQ,UAAgB;AACtB,UAAM,MAAM,KAAK,IAAI;AACrB,eAAW,CAAC,KAAK,KAAK,KAAK,KAAK,OAAO;AACrC,UAAI,MAAM,cAAc,QAAQ,MAAM,MAAM,WAAW;AACrD,aAAK,MAAM,OAAO,GAAG;AAAA,MACvB;AAAA,IACF;AAAA,EACF;AACF;;;ACnDO,IAAM,wBAAN,MAAwD;AAAA,EAC5C;AAAA,EACA;AAAA,EAEjB,YAAY,SAAuC;AACjD,SAAK,QAAQ,QAAQ;AACrB,SAAK,YAAY,QAAQ,aAAa;AAAA,EACxC;AAAA,EAEQ,IAAI,WAA2B;AACrC,WAAO,GAAG,KAAK,SAAS,GAAG,SAAS;AAAA,EACtC;AAAA,EAEA,MAAM,IAAI,WAAqC;AAC7C,UAAM,SAAS,MAAM,KAAK,MAAM,IAAI,KAAK,IAAI,SAAS,CAAC;AACvD,WAAO,WAAW;AAAA,EACpB;AAAA,EAEA,MAAM,IAAI,WAAmB,OAA+B;AAC1D,UAAM,MAAM,KAAK,IAAI,SAAS;AAC9B,QAAI,SAAS,MAAM;AAEjB,YAAM,aAAa,KAAK,KAAK,QAAQ,GAAI;AACzC,YAAM,KAAK,MAAM,MAAM,KAAK,YAAY,GAAG;AAAA,IAC7C,OAAO;AACL,YAAM,KAAK,MAAM,IAAI,KAAK,GAAG;AAAA,IAC/B;AAAA,EACF;AAAA,EAEA,MAAM,OAAO,WAAkC;AAC7C,UAAM,KAAK,MAAM,IAAI,KAAK,IAAI,SAAS,CAAC;AAAA,EAC1C;AAAA,EAEA,MAAM,QAAuB;AAE3B,UAAM,OAAO,MAAM,KAAK,MAAM,KAAK,GAAG,KAAK,SAAS,GAAG;AACvD,QAAI,KAAK,SAAS,GAAG;AACnB,iBAAW,OAAO,MAAM;AACtB,cAAM,KAAK,MAAM,IAAI,GAAG;AAAA,MAC1B;AAAA,IACF;AAAA,EACF;AACF;","names":[]}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@saga-bus/middleware-idempotency",
+  "version": "0.1.0",
+  "description": "Idempotency middleware for saga-bus message deduplication",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@saga-bus/core": "0.1.0"
+  },
+  "peerDependencies": {
+    "ioredis": ">=5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "ioredis": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.21",
+    "ioredis": "^5.6.1",
+    "tsup": "^8.0.0",
+    "typescript": "^5.9.2",
+    "vitest": "^3.0.0",
+    "@repo/eslint-config": "0.0.0",
+    "@repo/typescript-config": "0.0.0"
+  },
+  "keywords": [
+    "saga",
+    "saga-bus",
+    "middleware",
+    "idempotency",
+    "deduplication",
+    "event-sourcing"
+  ],
+  "license": "MIT",
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "lint": "eslint src/",
+    "check-types": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}