@idempotix/redis 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 stacks0x
+
+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,106 @@
+# @idempotix/redis
+
+Redis storage adapter for Idempotix using ioredis.
+
+[![npm version](https://img.shields.io/npm/v/@idempotix/redis.svg)](https://www.npmjs.com/package/@idempotix/redis)
+
+## Installation
+
+```bash
+npm install @idempotix/core @idempotix/redis ioredis
+```
+
+## Quick Start
+
+```typescript
+import { redis } from '@idempotix/redis';
+import { express as idempotent } from '@idempotix/express';
+
+// From environment variable (Idempotix_REDIS_URL)
+app.post('/orders', idempotent({ storage: redis() }), handler);
+```
+
+## Configuration
+
+```typescript
+import { redis } from '@idempotix/redis';
+
+// From environment variable
+const storage = redis();
+
+// From URL (password in URL)
+const storage = redis('redis://:password@localhost:6379');
+
+// With options
+const storage = redis({
+  url: 'redis://localhost:6379',
+  keyPrefix: 'myapp:idem:',
+});
+
+// With existing ioredis client
+import Redis from 'ioredis';
+const client = new Redis({ host: 'localhost', password: 'secret' });
+const storage = redis({ client });
+```
+
+## Environment Variables
+
+| Variable              | Description                                                |
+| --------------------- | ---------------------------------------------------------- |
+| `Idempotix_REDIS_URL` | Redis connection URL (e.g., `redis://:password@host:6379`) |
+
+## Redis Cluster
+
+```typescript
+import Redis from 'ioredis';
+import { redis } from '@idempotix/redis';
+
+const cluster = new Redis.Cluster([
+  { host: 'node1.example.com', port: 6379 },
+  { host: 'node2.example.com', port: 6379 },
+]);
+
+const storage = redis({ client: cluster });
+```
+
+## AWS ElastiCache
+
+```typescript
+const storage = redis('redis://your-cluster.cache.amazonaws.com:6379');
+```
+
+## Usage with Express
+
+```typescript
+import { express as idempotent, configure } from '@idempotix/express';
+import { redis } from '@idempotix/redis';
+
+const idempotent = configure({
+  storage: redis(),
+  ttl: '1h',
+});
+
+app.post('/orders', idempotent(), orderHandler);
+app.post('/payments', idempotent({ required: true }), paymentHandler);
+```
+
+## Usage with Next.js
+
+```typescript
+import { next } from '@idempotix/next';
+import { redis } from '@idempotix/redis';
+
+export const POST = next({ storage: redis() })(handler);
+```
+
+## Key Prefix
+
+All keys are prefixed with `Idempotix:` by default. Customize with:
+
+```typescript
+const storage = redis({ keyPrefix: 'myapp:idem:' });
+```
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,156 @@
+'use strict';
+
+var Redis = require('ioredis');
+
+function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
+
+var Redis__default = /*#__PURE__*/_interopDefault(Redis);
+
+// src/index.ts
+var ENV_REDIS_URL = "Idempotix_REDIS_URL";
+var ACQUIRE_SCRIPT = `
+local key = KEYS[1]
+local hash = ARGV[1]
+local ttl = tonumber(ARGV[2])
+local now = tonumber(ARGV[3])
+
+local existing = redis.call('GET', key)
+if existing then
+  return existing
+end
+
+local record = cjson.encode({
+  status = 'in_progress',
+  hash = hash ~= '' and hash or nil,
+  startedAt = now
+})
+redis.call('SET', key, record, 'PX', ttl)
+return nil
+`;
+var RedisStorage = class {
+  client;
+  keyPrefix;
+  ownsClient;
+  /**
+   * Maximum payload size in bytes (default: 10MB).
+   * Prevents excessively large values from being stored in Redis.
+   */
+  maxPayloadSize;
+  constructor(options) {
+    this.client = options._client;
+    this.keyPrefix = options.keyPrefix ?? "Idempotix:";
+    this.ownsClient = options._ownsClient;
+    this.maxPayloadSize = options.maxPayloadSize ?? 10 * 1024 * 1024;
+  }
+  prefixKey(key) {
+    return `${this.keyPrefix}${key}`;
+  }
+  async acquire(key, hash, ttl) {
+    const prefixedKey = this.prefixKey(key);
+    const now = Date.now();
+    const result = await this.client.eval(
+      ACQUIRE_SCRIPT,
+      1,
+      prefixedKey,
+      hash ?? "",
+      ttl.toString(),
+      now.toString()
+    );
+    if (result === null) {
+      return { status: "acquired" };
+    }
+    let existing;
+    try {
+      existing = JSON.parse(result);
+    } catch {
+      await this.client.del(prefixedKey);
+      return { status: "acquired" };
+    }
+    if (hash && existing.hash && existing.hash !== hash) {
+      return {
+        status: "mismatch",
+        existingHash: existing.hash,
+        providedHash: hash
+      };
+    }
+    if (existing.status === "completed") {
+      return {
+        status: "hit",
+        response: {
+          data: existing.data,
+          createdAt: existing.createdAt,
+          hash: existing.hash
+        }
+      };
+    }
+    return { status: "conflict", startedAt: existing.startedAt };
+  }
+  async save(key, response) {
+    const prefixedKey = this.prefixKey(key);
+    const existing = await this.client.get(prefixedKey);
+    if (!existing) return;
+    const ttl = await this.client.pttl(prefixedKey);
+    if (ttl <= 0) return;
+    const record = {
+      status: "completed",
+      hash: response.hash,
+      data: response.data,
+      createdAt: response.createdAt,
+      startedAt: Date.now()
+    };
+    await this.client.set(prefixedKey, JSON.stringify(record), "PX", ttl);
+  }
+  async release(key) {
+    await this.client.del(this.prefixKey(key));
+  }
+  async delete(key) {
+    await this.client.del(this.prefixKey(key));
+  }
+  async clear() {
+    const keys = await this.client.keys(`${this.keyPrefix}*`);
+    if (keys.length > 0) {
+      await this.client.del(...keys);
+    }
+  }
+  /**
+   * Disconnect the Redis client if we own it.
+   * Call this during shutdown if using auto-created client.
+   */
+  async disconnect() {
+    if (this.ownsClient) {
+      await this.client.quit();
+    }
+  }
+};
+function redis(urlOrOptions) {
+  if (typeof urlOrOptions === "string") {
+    return createRedisStorage({ url: urlOrOptions });
+  }
+  return createRedisStorage(urlOrOptions ?? {});
+}
+function createRedisStorage(options) {
+  let client;
+  let ownsClient = false;
+  if (options.client) {
+    client = options.client;
+  } else {
+    const url = options.url ?? process.env[ENV_REDIS_URL];
+    if (!url) {
+      throw new Error(
+        `Redis URL not provided. Either pass a URL, provide a client, or set ${ENV_REDIS_URL} environment variable.`
+      );
+    }
+    client = new Redis__default.default(url);
+    ownsClient = true;
+  }
+  return new RedisStorage({
+    ...options,
+    _client: client,
+    _ownsClient: ownsClient
+  });
+}
+
+exports.RedisStorage = RedisStorage;
+exports.redis = redis;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":["Redis"],"mappings":"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","file":"index.cjs","sourcesContent":["/**\n * @idempotix/redis - Redis storage adapter for Idempotix\n *\n * Uses ioredis for standard Redis connections (TCP-based).\n * For HTTP-based Redis (Upstash, Vercel KV), use @idempotix/upstash.\n */\n\nimport type { StorageAdapter, AcquireResult, StoredResponse } from '@idempotix/core';\nimport Redis, { type Cluster } from 'ioredis';\n\n/**\n * Environment variable for Redis URL.\n * Scoped to Idempotix to avoid accidental connections.\n */\nconst ENV_REDIS_URL = 'Idempotix_REDIS_URL';\n\n/**\n * Options for the Redis storage adapter.\n */\nexport interface RedisOptions {\n  /**\n   * Redis connection URL.\n   * If not provided, uses Idempotix_REDIS_URL environment variable.\n   */\n  url?: string;\n\n  /**\n   * Existing ioredis client instance.\n   * Takes precedence over url if provided.\n   */\n  client?: Redis | Cluster;\n\n  /**\n   * Key prefix for namespacing.\n   * @default 'Idempotix:'\n   */\n  keyPrefix?: string;\n\n  /**\n   * Maximum payload size in bytes.\n   * Responses exceeding this limit will skip caching.\n   * Set to 0 to disable size checking.\n   * @default 10485760 (10MB)\n   */\n  maxPayloadSize?: number;\n}\n\n/**\n * Internal record structure stored in Redis.\n */\ninterface RedisRecord {\n  status: 'in_progress' | 'completed';\n  hash: string | null;\n  data?: unknown;\n  createdAt: number;\n  startedAt: number;\n}\n\n/**\n * Lua script for atomic acquire.\n * Returns: null if acquired, JSON string if exists\n */\nconst ACQUIRE_SCRIPT = `\nlocal key = KEYS[1]\nlocal hash = ARGV[1]\nlocal ttl = tonumber(ARGV[2])\nlocal now = tonumber(ARGV[3])\n\nlocal existing = redis.call('GET', key)\nif existing then\n  return existing\nend\n\nlocal record = cjson.encode({\n  status = 'in_progress',\n  hash = hash ~= '' and hash or nil,\n  startedAt = now\n})\nredis.call('SET', key, record, 'PX', ttl)\nreturn nil\n`;\n\n/**\n * Redis storage adapter using ioredis.\n *\n * Works with:\n * - Self-hosted Redis\n * - AWS ElastiCache\n * - Redis Cloud\n * - Azure Cache for Redis\n * - DigitalOcean Managed Redis\n * - Any Redis-compatible service via TCP\n *\n * @example\n * ```typescript\n * import { redis } from '@idempotix/redis';\n *\n * // From environment (Idempotix_REDIS_URL)\n * const storage = redis();\n *\n * // From URL\n * const storage = redis('redis://localhost:6379');\n *\n * // With existing client\n * import Redis from 'ioredis';\n * const storage = redis({ client: new Redis() });\n * ```\n */\nexport class RedisStorage implements StorageAdapter {\n  private readonly client: Redis | Cluster;\n  private readonly keyPrefix: string;\n  private readonly ownsClient: boolean;\n\n  /**\n   * Maximum payload size in bytes (default: 10MB).\n   * Prevents excessively large values from being stored in Redis.\n   */\n  readonly maxPayloadSize: number;\n\n  constructor(options: RedisOptions & { _client: Redis | Cluster; _ownsClient: boolean }) {\n    this.client = options._client;\n    this.keyPrefix = options.keyPrefix ?? 'Idempotix:';\n    this.ownsClient = options._ownsClient;\n    this.maxPayloadSize = options.maxPayloadSize ?? 10 * 1024 * 1024;\n  }\n\n  private prefixKey(key: string): string {\n    return `${this.keyPrefix}${key}`;\n  }\n\n  async acquire(key: string, hash: string | null, ttl: number): Promise<AcquireResult> {\n    const prefixedKey = this.prefixKey(key);\n    const now = Date.now();\n\n    // Try to get existing or set new atomically\n    const result = (await (this.client as Redis).eval(\n      ACQUIRE_SCRIPT,\n      1,\n      prefixedKey,\n      hash ?? '',\n      ttl.toString(),\n      now.toString()\n    )) as string | null;\n\n    // Lock acquired\n    if (result === null) {\n      return { status: 'acquired' };\n    }\n\n    // Parse existing record\n    let existing: RedisRecord;\n    try {\n      existing = JSON.parse(result);\n    } catch {\n      // Corrupted data, delete and try again\n      await this.client.del(prefixedKey);\n      return { status: 'acquired' };\n    }\n\n    // Check for hash mismatch\n    if (hash && existing.hash && existing.hash !== hash) {\n      return {\n        status: 'mismatch',\n        existingHash: existing.hash,\n        providedHash: hash,\n      };\n    }\n\n    // If completed, return cached response\n    if (existing.status === 'completed') {\n      return {\n        status: 'hit',\n        response: {\n          data: existing.data,\n          createdAt: existing.createdAt,\n          hash: existing.hash,\n        },\n      };\n    }\n\n    // If in progress, return conflict\n    return { status: 'conflict', startedAt: existing.startedAt };\n  }\n\n  async save(key: string, response: StoredResponse): Promise<void> {\n    const prefixedKey = this.prefixKey(key);\n\n    // Get existing record to preserve TTL\n    const existing = await this.client.get(prefixedKey);\n    if (!existing) return;\n\n    const ttl = await this.client.pttl(prefixedKey);\n    if (ttl <= 0) return;\n\n    const record: RedisRecord = {\n      status: 'completed',\n      hash: response.hash,\n      data: response.data,\n      createdAt: response.createdAt,\n      startedAt: Date.now(),\n    };\n\n    await this.client.set(prefixedKey, JSON.stringify(record), 'PX', ttl);\n  }\n\n  async release(key: string): Promise<void> {\n    await this.client.del(this.prefixKey(key));\n  }\n\n  async delete(key: string): Promise<void> {\n    await this.client.del(this.prefixKey(key));\n  }\n\n  async clear(): Promise<void> {\n    const keys = await this.client.keys(`${this.keyPrefix}*`);\n    if (keys.length > 0) {\n      await this.client.del(...keys);\n    }\n  }\n\n  /**\n   * Disconnect the Redis client if we own it.\n   * Call this during shutdown if using auto-created client.\n   */\n  async disconnect(): Promise<void> {\n    if (this.ownsClient) {\n      await this.client.quit();\n    }\n  }\n}\n\n/**\n * Create a Redis storage adapter.\n *\n * @example\n * ```typescript\n * import { idempotix } from '@idempotix/core';\n * import { redis } from '@idempotix/redis';\n *\n * // Auto-detect from Idempotix_REDIS_URL\n * idempotix.configure({ storage: redis() });\n *\n * // With explicit URL\n * idempotix.configure({ storage: redis('redis://localhost:6379') });\n *\n * // With options\n * idempotix.configure({\n *   storage: redis({\n *     url: 'redis://localhost:6379',\n *     keyPrefix: 'myapp:',\n *   }),\n * });\n *\n * // With existing client\n * import Redis from 'ioredis';\n * idempotix.configure({\n *   storage: redis({ client: new Redis() }),\n * });\n * ```\n */\nexport function redis(urlOrOptions?: string | RedisOptions): RedisStorage {\n  // Handle string URL\n  if (typeof urlOrOptions === 'string') {\n    return createRedisStorage({ url: urlOrOptions });\n  }\n\n  return createRedisStorage(urlOrOptions ?? {});\n}\n\n/**\n * Internal factory to create Redis storage.\n */\nfunction createRedisStorage(options: RedisOptions): RedisStorage {\n  let client: Redis | Cluster;\n  let ownsClient = false;\n\n  if (options.client) {\n    // Use provided client\n    client = options.client;\n  } else {\n    // Create new client\n    const url = options.url ?? process.env[ENV_REDIS_URL];\n\n    if (!url) {\n      throw new Error(\n        `Redis URL not provided. Either pass a URL, provide a client, or set ${ENV_REDIS_URL} environment variable.`\n      );\n    }\n\n    client = new Redis(url);\n    ownsClient = true;\n  }\n\n  return new RedisStorage({\n    ...options,\n    _client: client,\n    _ownsClient: ownsClient,\n  });\n}\n\n// Re-export types\nexport type { StorageAdapter, AcquireResult, StoredResponse } from '@idempotix/core';\n"]}

package/dist/index.d.cts

@@ -0,0 +1,121 @@
+import { StorageAdapter, AcquireResult, StoredResponse } from '@idempotix/core';
+export { AcquireResult, StorageAdapter, StoredResponse } from '@idempotix/core';
+import Redis, { Cluster } from 'ioredis';
+
+/**
+ * @idempotix/redis - Redis storage adapter for Idempotix
+ *
+ * Uses ioredis for standard Redis connections (TCP-based).
+ * For HTTP-based Redis (Upstash, Vercel KV), use @idempotix/upstash.
+ */
+
+/**
+ * Options for the Redis storage adapter.
+ */
+interface RedisOptions {
+    /**
+     * Redis connection URL.
+     * If not provided, uses Idempotix_REDIS_URL environment variable.
+     */
+    url?: string;
+    /**
+     * Existing ioredis client instance.
+     * Takes precedence over url if provided.
+     */
+    client?: Redis | Cluster;
+    /**
+     * Key prefix for namespacing.
+     * @default 'Idempotix:'
+     */
+    keyPrefix?: string;
+    /**
+     * Maximum payload size in bytes.
+     * Responses exceeding this limit will skip caching.
+     * Set to 0 to disable size checking.
+     * @default 10485760 (10MB)
+     */
+    maxPayloadSize?: number;
+}
+/**
+ * Redis storage adapter using ioredis.
+ *
+ * Works with:
+ * - Self-hosted Redis
+ * - AWS ElastiCache
+ * - Redis Cloud
+ * - Azure Cache for Redis
+ * - DigitalOcean Managed Redis
+ * - Any Redis-compatible service via TCP
+ *
+ * @example
+ * ```typescript
+ * import { redis } from '@idempotix/redis';
+ *
+ * // From environment (Idempotix_REDIS_URL)
+ * const storage = redis();
+ *
+ * // From URL
+ * const storage = redis('redis://localhost:6379');
+ *
+ * // With existing client
+ * import Redis from 'ioredis';
+ * const storage = redis({ client: new Redis() });
+ * ```
+ */
+declare class RedisStorage implements StorageAdapter {
+    private readonly client;
+    private readonly keyPrefix;
+    private readonly ownsClient;
+    /**
+     * Maximum payload size in bytes (default: 10MB).
+     * Prevents excessively large values from being stored in Redis.
+     */
+    readonly maxPayloadSize: number;
+    constructor(options: RedisOptions & {
+        _client: Redis | Cluster;
+        _ownsClient: boolean;
+    });
+    private prefixKey;
+    acquire(key: string, hash: string | null, ttl: number): Promise<AcquireResult>;
+    save(key: string, response: StoredResponse): Promise<void>;
+    release(key: string): Promise<void>;
+    delete(key: string): Promise<void>;
+    clear(): Promise<void>;
+    /**
+     * Disconnect the Redis client if we own it.
+     * Call this during shutdown if using auto-created client.
+     */
+    disconnect(): Promise<void>;
+}
+/**
+ * Create a Redis storage adapter.
+ *
+ * @example
+ * ```typescript
+ * import { idempotix } from '@idempotix/core';
+ * import { redis } from '@idempotix/redis';
+ *
+ * // Auto-detect from Idempotix_REDIS_URL
+ * idempotix.configure({ storage: redis() });
+ *
+ * // With explicit URL
+ * idempotix.configure({ storage: redis('redis://localhost:6379') });
+ *
+ * // With options
+ * idempotix.configure({
+ *   storage: redis({
+ *     url: 'redis://localhost:6379',
+ *     keyPrefix: 'myapp:',
+ *   }),
+ * });
+ *
+ * // With existing client
+ * import Redis from 'ioredis';
+ * idempotix.configure({
+ *   storage: redis({ client: new Redis() }),
+ * });
+ * ```
+ */
+declare function redis(urlOrOptions?: string | RedisOptions): RedisStorage;
+
+export { type RedisOptions, RedisStorage, redis };

package/dist/index.d.ts

@@ -0,0 +1,121 @@
+import { StorageAdapter, AcquireResult, StoredResponse } from '@idempotix/core';
+export { AcquireResult, StorageAdapter, StoredResponse } from '@idempotix/core';
+import Redis, { Cluster } from 'ioredis';
+
+/**
+ * @idempotix/redis - Redis storage adapter for Idempotix
+ *
+ * Uses ioredis for standard Redis connections (TCP-based).
+ * For HTTP-based Redis (Upstash, Vercel KV), use @idempotix/upstash.
+ */
+
+/**
+ * Options for the Redis storage adapter.
+ */
+interface RedisOptions {
+    /**
+     * Redis connection URL.
+     * If not provided, uses Idempotix_REDIS_URL environment variable.
+     */
+    url?: string;
+    /**
+     * Existing ioredis client instance.
+     * Takes precedence over url if provided.
+     */
+    client?: Redis | Cluster;
+    /**
+     * Key prefix for namespacing.
+     * @default 'Idempotix:'
+     */
+    keyPrefix?: string;
+    /**
+     * Maximum payload size in bytes.
+     * Responses exceeding this limit will skip caching.
+     * Set to 0 to disable size checking.
+     * @default 10485760 (10MB)
+     */
+    maxPayloadSize?: number;
+}
+/**
+ * Redis storage adapter using ioredis.
+ *
+ * Works with:
+ * - Self-hosted Redis
+ * - AWS ElastiCache
+ * - Redis Cloud
+ * - Azure Cache for Redis
+ * - DigitalOcean Managed Redis
+ * - Any Redis-compatible service via TCP
+ *
+ * @example
+ * ```typescript
+ * import { redis } from '@idempotix/redis';
+ *
+ * // From environment (Idempotix_REDIS_URL)
+ * const storage = redis();
+ *
+ * // From URL
+ * const storage = redis('redis://localhost:6379');
+ *
+ * // With existing client
+ * import Redis from 'ioredis';
+ * const storage = redis({ client: new Redis() });
+ * ```
+ */
+declare class RedisStorage implements StorageAdapter {
+    private readonly client;
+    private readonly keyPrefix;
+    private readonly ownsClient;
+    /**
+     * Maximum payload size in bytes (default: 10MB).
+     * Prevents excessively large values from being stored in Redis.
+     */
+    readonly maxPayloadSize: number;
+    constructor(options: RedisOptions & {
+        _client: Redis | Cluster;
+        _ownsClient: boolean;
+    });
+    private prefixKey;
+    acquire(key: string, hash: string | null, ttl: number): Promise<AcquireResult>;
+    save(key: string, response: StoredResponse): Promise<void>;
+    release(key: string): Promise<void>;
+    delete(key: string): Promise<void>;
+    clear(): Promise<void>;
+    /**
+     * Disconnect the Redis client if we own it.
+     * Call this during shutdown if using auto-created client.
+     */
+    disconnect(): Promise<void>;
+}
+/**
+ * Create a Redis storage adapter.
+ *
+ * @example
+ * ```typescript
+ * import { idempotix } from '@idempotix/core';
+ * import { redis } from '@idempotix/redis';
+ *
+ * // Auto-detect from Idempotix_REDIS_URL
+ * idempotix.configure({ storage: redis() });
+ *
+ * // With explicit URL
+ * idempotix.configure({ storage: redis('redis://localhost:6379') });
+ *
+ * // With options
+ * idempotix.configure({
+ *   storage: redis({
+ *     url: 'redis://localhost:6379',
+ *     keyPrefix: 'myapp:',
+ *   }),
+ * });
+ *
+ * // With existing client
+ * import Redis from 'ioredis';
+ * idempotix.configure({
+ *   storage: redis({ client: new Redis() }),
+ * });
+ * ```
+ */
+declare function redis(urlOrOptions?: string | RedisOptions): RedisStorage;
+
+export { type RedisOptions, RedisStorage, redis };

package/dist/index.js

@@ -0,0 +1,149 @@
+import Redis from 'ioredis';
+
+// src/index.ts
+var ENV_REDIS_URL = "Idempotix_REDIS_URL";
+var ACQUIRE_SCRIPT = `
+local key = KEYS[1]
+local hash = ARGV[1]
+local ttl = tonumber(ARGV[2])
+local now = tonumber(ARGV[3])
+
+local existing = redis.call('GET', key)
+if existing then
+  return existing
+end
+
+local record = cjson.encode({
+  status = 'in_progress',
+  hash = hash ~= '' and hash or nil,
+  startedAt = now
+})
+redis.call('SET', key, record, 'PX', ttl)
+return nil
+`;
+var RedisStorage = class {
+  client;
+  keyPrefix;
+  ownsClient;
+  /**
+   * Maximum payload size in bytes (default: 10MB).
+   * Prevents excessively large values from being stored in Redis.
+   */
+  maxPayloadSize;
+  constructor(options) {
+    this.client = options._client;
+    this.keyPrefix = options.keyPrefix ?? "Idempotix:";
+    this.ownsClient = options._ownsClient;
+    this.maxPayloadSize = options.maxPayloadSize ?? 10 * 1024 * 1024;
+  }
+  prefixKey(key) {
+    return `${this.keyPrefix}${key}`;
+  }
+  async acquire(key, hash, ttl) {
+    const prefixedKey = this.prefixKey(key);
+    const now = Date.now();
+    const result = await this.client.eval(
+      ACQUIRE_SCRIPT,
+      1,
+      prefixedKey,
+      hash ?? "",
+      ttl.toString(),
+      now.toString()
+    );
+    if (result === null) {
+      return { status: "acquired" };
+    }
+    let existing;
+    try {
+      existing = JSON.parse(result);
+    } catch {
+      await this.client.del(prefixedKey);
+      return { status: "acquired" };
+    }
+    if (hash && existing.hash && existing.hash !== hash) {
+      return {
+        status: "mismatch",
+        existingHash: existing.hash,
+        providedHash: hash
+      };
+    }
+    if (existing.status === "completed") {
+      return {
+        status: "hit",
+        response: {
+          data: existing.data,
+          createdAt: existing.createdAt,
+          hash: existing.hash
+        }
+      };
+    }
+    return { status: "conflict", startedAt: existing.startedAt };
+  }
+  async save(key, response) {
+    const prefixedKey = this.prefixKey(key);
+    const existing = await this.client.get(prefixedKey);
+    if (!existing) return;
+    const ttl = await this.client.pttl(prefixedKey);
+    if (ttl <= 0) return;
+    const record = {
+      status: "completed",
+      hash: response.hash,
+      data: response.data,
+      createdAt: response.createdAt,
+      startedAt: Date.now()
+    };
+    await this.client.set(prefixedKey, JSON.stringify(record), "PX", ttl);
+  }
+  async release(key) {
+    await this.client.del(this.prefixKey(key));
+  }
+  async delete(key) {
+    await this.client.del(this.prefixKey(key));
+  }
+  async clear() {
+    const keys = await this.client.keys(`${this.keyPrefix}*`);
+    if (keys.length > 0) {
+      await this.client.del(...keys);
+    }
+  }
+  /**
+   * Disconnect the Redis client if we own it.
+   * Call this during shutdown if using auto-created client.
+   */
+  async disconnect() {
+    if (this.ownsClient) {
+      await this.client.quit();
+    }
+  }
+};
+function redis(urlOrOptions) {
+  if (typeof urlOrOptions === "string") {
+    return createRedisStorage({ url: urlOrOptions });
+  }
+  return createRedisStorage(urlOrOptions ?? {});
+}
+function createRedisStorage(options) {
+  let client;
+  let ownsClient = false;
+  if (options.client) {
+    client = options.client;
+  } else {
+    const url = options.url ?? process.env[ENV_REDIS_URL];
+    if (!url) {
+      throw new Error(
+        `Redis URL not provided. Either pass a URL, provide a client, or set ${ENV_REDIS_URL} environment variable.`
+      );
+    }
+    client = new Redis(url);
+    ownsClient = true;
+  }
+  return new RedisStorage({
+    ...options,
+    _client: client,
+    _ownsClient: ownsClient
+  });
+}
+
+export { RedisStorage, redis };
+//# 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 * @idempotix/redis - Redis storage adapter for Idempotix\n *\n * Uses ioredis for standard Redis connections (TCP-based).\n * For HTTP-based Redis (Upstash, Vercel KV), use @idempotix/upstash.\n */\n\nimport type { StorageAdapter, AcquireResult, StoredResponse } from '@idempotix/core';\nimport Redis, { type Cluster } from 'ioredis';\n\n/**\n * Environment variable for Redis URL.\n * Scoped to Idempotix to avoid accidental connections.\n */\nconst ENV_REDIS_URL = 'Idempotix_REDIS_URL';\n\n/**\n * Options for the Redis storage adapter.\n */\nexport interface RedisOptions {\n  /**\n   * Redis connection URL.\n   * If not provided, uses Idempotix_REDIS_URL environment variable.\n   */\n  url?: string;\n\n  /**\n   * Existing ioredis client instance.\n   * Takes precedence over url if provided.\n   */\n  client?: Redis | Cluster;\n\n  /**\n   * Key prefix for namespacing.\n   * @default 'Idempotix:'\n   */\n  keyPrefix?: string;\n\n  /**\n   * Maximum payload size in bytes.\n   * Responses exceeding this limit will skip caching.\n   * Set to 0 to disable size checking.\n   * @default 10485760 (10MB)\n   */\n  maxPayloadSize?: number;\n}\n\n/**\n * Internal record structure stored in Redis.\n */\ninterface RedisRecord {\n  status: 'in_progress' | 'completed';\n  hash: string | null;\n  data?: unknown;\n  createdAt: number;\n  startedAt: number;\n}\n\n/**\n * Lua script for atomic acquire.\n * Returns: null if acquired, JSON string if exists\n */\nconst ACQUIRE_SCRIPT = `\nlocal key = KEYS[1]\nlocal hash = ARGV[1]\nlocal ttl = tonumber(ARGV[2])\nlocal now = tonumber(ARGV[3])\n\nlocal existing = redis.call('GET', key)\nif existing then\n  return existing\nend\n\nlocal record = cjson.encode({\n  status = 'in_progress',\n  hash = hash ~= '' and hash or nil,\n  startedAt = now\n})\nredis.call('SET', key, record, 'PX', ttl)\nreturn nil\n`;\n\n/**\n * Redis storage adapter using ioredis.\n *\n * Works with:\n * - Self-hosted Redis\n * - AWS ElastiCache\n * - Redis Cloud\n * - Azure Cache for Redis\n * - DigitalOcean Managed Redis\n * - Any Redis-compatible service via TCP\n *\n * @example\n * ```typescript\n * import { redis } from '@idempotix/redis';\n *\n * // From environment (Idempotix_REDIS_URL)\n * const storage = redis();\n *\n * // From URL\n * const storage = redis('redis://localhost:6379');\n *\n * // With existing client\n * import Redis from 'ioredis';\n * const storage = redis({ client: new Redis() });\n * ```\n */\nexport class RedisStorage implements StorageAdapter {\n  private readonly client: Redis | Cluster;\n  private readonly keyPrefix: string;\n  private readonly ownsClient: boolean;\n\n  /**\n   * Maximum payload size in bytes (default: 10MB).\n   * Prevents excessively large values from being stored in Redis.\n   */\n  readonly maxPayloadSize: number;\n\n  constructor(options: RedisOptions & { _client: Redis | Cluster; _ownsClient: boolean }) {\n    this.client = options._client;\n    this.keyPrefix = options.keyPrefix ?? 'Idempotix:';\n    this.ownsClient = options._ownsClient;\n    this.maxPayloadSize = options.maxPayloadSize ?? 10 * 1024 * 1024;\n  }\n\n  private prefixKey(key: string): string {\n    return `${this.keyPrefix}${key}`;\n  }\n\n  async acquire(key: string, hash: string | null, ttl: number): Promise<AcquireResult> {\n    const prefixedKey = this.prefixKey(key);\n    const now = Date.now();\n\n    // Try to get existing or set new atomically\n    const result = (await (this.client as Redis).eval(\n      ACQUIRE_SCRIPT,\n      1,\n      prefixedKey,\n      hash ?? '',\n      ttl.toString(),\n      now.toString()\n    )) as string | null;\n\n    // Lock acquired\n    if (result === null) {\n      return { status: 'acquired' };\n    }\n\n    // Parse existing record\n    let existing: RedisRecord;\n    try {\n      existing = JSON.parse(result);\n    } catch {\n      // Corrupted data, delete and try again\n      await this.client.del(prefixedKey);\n      return { status: 'acquired' };\n    }\n\n    // Check for hash mismatch\n    if (hash && existing.hash && existing.hash !== hash) {\n      return {\n        status: 'mismatch',\n        existingHash: existing.hash,\n        providedHash: hash,\n      };\n    }\n\n    // If completed, return cached response\n    if (existing.status === 'completed') {\n      return {\n        status: 'hit',\n        response: {\n          data: existing.data,\n          createdAt: existing.createdAt,\n          hash: existing.hash,\n        },\n      };\n    }\n\n    // If in progress, return conflict\n    return { status: 'conflict', startedAt: existing.startedAt };\n  }\n\n  async save(key: string, response: StoredResponse): Promise<void> {\n    const prefixedKey = this.prefixKey(key);\n\n    // Get existing record to preserve TTL\n    const existing = await this.client.get(prefixedKey);\n    if (!existing) return;\n\n    const ttl = await this.client.pttl(prefixedKey);\n    if (ttl <= 0) return;\n\n    const record: RedisRecord = {\n      status: 'completed',\n      hash: response.hash,\n      data: response.data,\n      createdAt: response.createdAt,\n      startedAt: Date.now(),\n    };\n\n    await this.client.set(prefixedKey, JSON.stringify(record), 'PX', ttl);\n  }\n\n  async release(key: string): Promise<void> {\n    await this.client.del(this.prefixKey(key));\n  }\n\n  async delete(key: string): Promise<void> {\n    await this.client.del(this.prefixKey(key));\n  }\n\n  async clear(): Promise<void> {\n    const keys = await this.client.keys(`${this.keyPrefix}*`);\n    if (keys.length > 0) {\n      await this.client.del(...keys);\n    }\n  }\n\n  /**\n   * Disconnect the Redis client if we own it.\n   * Call this during shutdown if using auto-created client.\n   */\n  async disconnect(): Promise<void> {\n    if (this.ownsClient) {\n      await this.client.quit();\n    }\n  }\n}\n\n/**\n * Create a Redis storage adapter.\n *\n * @example\n * ```typescript\n * import { idempotix } from '@idempotix/core';\n * import { redis } from '@idempotix/redis';\n *\n * // Auto-detect from Idempotix_REDIS_URL\n * idempotix.configure({ storage: redis() });\n *\n * // With explicit URL\n * idempotix.configure({ storage: redis('redis://localhost:6379') });\n *\n * // With options\n * idempotix.configure({\n *   storage: redis({\n *     url: 'redis://localhost:6379',\n *     keyPrefix: 'myapp:',\n *   }),\n * });\n *\n * // With existing client\n * import Redis from 'ioredis';\n * idempotix.configure({\n *   storage: redis({ client: new Redis() }),\n * });\n * ```\n */\nexport function redis(urlOrOptions?: string | RedisOptions): RedisStorage {\n  // Handle string URL\n  if (typeof urlOrOptions === 'string') {\n    return createRedisStorage({ url: urlOrOptions });\n  }\n\n  return createRedisStorage(urlOrOptions ?? {});\n}\n\n/**\n * Internal factory to create Redis storage.\n */\nfunction createRedisStorage(options: RedisOptions): RedisStorage {\n  let client: Redis | Cluster;\n  let ownsClient = false;\n\n  if (options.client) {\n    // Use provided client\n    client = options.client;\n  } else {\n    // Create new client\n    const url = options.url ?? process.env[ENV_REDIS_URL];\n\n    if (!url) {\n      throw new Error(\n        `Redis URL not provided. Either pass a URL, provide a client, or set ${ENV_REDIS_URL} environment variable.`\n      );\n    }\n\n    client = new Redis(url);\n    ownsClient = true;\n  }\n\n  return new RedisStorage({\n    ...options,\n    _client: client,\n    _ownsClient: ownsClient,\n  });\n}\n\n// Re-export types\nexport type { StorageAdapter, AcquireResult, StoredResponse } from '@idempotix/core';\n"]}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@idempotix/redis",
+  "version": "1.0.0",
+  "description": "Redis storage adapter for Idempotix idempotency - works with ioredis",
+  "author": "stacks0x",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/stacks0x/idempotix.git",
+    "directory": "packages/redis"
+  },
+  "keywords": [
+    "idempotency",
+    "idempotent",
+    "redis",
+    "ioredis",
+    "storage",
+    "cache",
+    "elasticache",
+    "redis-cloud"
+  ],
+  "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"
+  ],
+  "dependencies": {
+    "@idempotix/core": "1.0.0"
+  },
+  "peerDependencies": {
+    "ioredis": "^5.0.0"
+  },
+  "devDependencies": {
+    "ioredis": "^5.3.2",
+    "tsup": "^8.0.1",
+    "typescript": "^5.3.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  }
+}