@siglo/redis 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2017 Jerico de guzman
+
+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

@@ -1,3 +1,227 @@
-# Temporary Holding Version
+# @siglo/redis Adapter Guide
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+`@siglo/redis` provides an in-memory distributed persistence, step response caching, atomic idempotency deduplication, and distributed single-flight coordination layer for `Siglo` workflows. It is powered by Redis and compatible with standalone Redis, Redis Sentinel, and Redis Cluster via `ioredis`.
+
+---
+
+## 1. Overview & Architecture
+
+The Redis adapter family encompasses three core modules:
+
+```mermaid
+flowchart TD
+    subgraph Package["@siglo/redis"]
+        direction LR
+        SA["RedisStorageAdapter<br/>• Ephemeral State<br/>• Step Caching<br/>• Context Hash Stream"]
+        IS["RedisIdempotencyStore<br/>• Atomic NX Claims<br/>• Result Caching<br/>• Fast Lock Release"]
+        LK["RedisLock<br/>• Distributed Mutex<br/>• Token Verification<br/>• Safe Lua Releasing"]
+    end
+
+    subgraph RedisServer["Redis Server"]
+        Keys1["siglo:[ns:]checkpoint:id<br/>siglo:cache:key"]
+        Keys2["siglo:idemp:key"]
+        Keys3["siglo:lock:key<br/>siglo:[ns:]context:id:step"]
+    end
+
+    SA --> Keys1
+    SA --> Keys3
+    IS --> Keys2
+    LK --> Keys3
+```
+
+---
+
+## 2. Installation & Requirements
+
+Install `@siglo/redis` alongside `ioredis`:
+
+```bash
+npm install @siglo/core @siglo/redis ioredis
+```
+
+Peer dependency matrix:
+- `Siglo`: `*` (v1.0.0+)
+- `ioredis`: `^5.0.0 || ^6.0.0`
+
+---
+
+## 3. Key Topology & Redis Data Structures
+
+`@siglo/redis` uses structured key namespaces:
+
+| Key Pattern | Redis Type | Default TTL | Description |
+| :--- | :--- | :--- | :--- |
+| `siglo:[<ns>:]checkpoint:<stackId>` | `string` (JSON) | 7 days (`604800000ms`) | Serialized execution stack for workflow resumption. Partitioned by tenant namespace if provided (`siglo:<ns>:checkpoint:<stackId>`). |
+| `siglo:cache:<key>` | `string` (JSON) | 24 hours (`86400000ms`) | Cached step evaluation output. |
+| `siglo:[<ns>:]context:<stackId>:<stepId>` | `hash` | 7 days (`604800000ms`) | Active context field mutations for auditing. Partitioned by tenant namespace if provided (`siglo:<ns>:context:<stackId>:<stepId>`). |
+| `siglo:idemp:<key>` | `string` | 24 hours (`86400000ms`) | Idempotency lock status (`in-progress` or `COMPLETED:<json>`). |
+| `siglo:lock:<key>` | `string` (UUID) | Caller specified (e.g. 10s) | Distributed mutex lock holding worker token. |
+
+---
+
+## 4. `RedisStorageAdapter` Reference
+
+Implements the standard `StorageAdapter` interface for high-performance checkpointing and step caching.
+
+```typescript
+import { RedisStorageAdapter } from '@siglo/redis';
+```
+
+### Options (`RedisStorageAdapterOptions`)
+
+| Option | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `client` | `RedisClientInterface \| Redis` | *Required* | Active `ioredis` instance. |
+| `keyPrefix` | `string` | `'siglo:'` | Root prefix for all Redis keys. |
+| `checkpointTtlMs` | `number` | `604800000` (7 days) | Checkpoint expiration TTL. |
+| `cacheTtlMs` | `number` | `86400000` (24 hours) | Default step response cache expiration TTL. |
+| `recordContextChanges` | `boolean` | `true` | When `true`, streams field updates to Redis Hashes. |
+
+### Methods
+
+- **`saveCheckpoint(checkpoint)`**: Saves JSON-serialized execution stack with millisecond TTL (`SET key val PX ttl`).
+- **`getCheckpoint(stackId, namespace?)`**: Retrieves and parses serialized checkpoint (checks namespaced key first, falling back to legacy key). Returns `undefined` if not found.
+- **`getCachedStep(key)`**: Retrieves cached step response.
+- **`setCachedStep(key, value, ttlMs?)`**: Writes cached step response with specified TTL.
+- **`onContextChange(entry)`**: Executes `HSET` on `siglo:[<ns>:]context:<stackId>:<stepId>` and refreshes TTL with `PEXPIRE`.
+
+---
+
+## 5. `RedisIdempotencyStore` Reference
+
+Provides distributed, atomic idempotency guarantees across multi-instance clusters using Redis `SET key val PX ttl NX` semantics.
+
+```typescript
+import { RedisIdempotencyStore } from '@siglo/redis';
+```
+
+### Options (`RedisIdempotencyOptions`)
+
+| Option | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `client` | `RedisClientInterface \| Redis` | *Required* | Active `ioredis` instance. |
+| `keyPrefix` | `string` | `'siglo:idemp:'` | Prefix for idempotency keys. |
+| `defaultTtlMs` | `number` | `86400000` (24 hours) | Default lock TTL. |
+
+### Claim States & Transitions:
+1. **`claim(key, ttlMs?)`**:
+   - Executes atomic Redis `SET <key> "in-progress" PX <ttl> NX`.
+   - If Redis returns `'OK'`: Returns `'claimed'`.
+   - If key exists and starts with `COMPLETED:`: Returns `'completed'`.
+   - If key exists with value `in-progress`: Returns `'in-progress'`.
+2. **`complete(key, result, ttlMs?)`**:
+   - Overwrites key with `COMPLETED:${JSON.stringify(result)}`.
+3. **`fail(key, error)`**:
+   - Deletes the key if it is currently `'in-progress'`, freeing the lock so subsequent retries can proceed.
+4. **`getResult(key)`**:
+   - Returns the deserialized result for completed keys.
+
+---
+
+## 6. `RedisLock` (Distributed Mutex & Single-Flight Coordination)
+
+`RedisLock` prevents duplicate parallel execution of sensitive workflows (e.g., end-of-month payroll, nightly data synchronization) across multiple server instances.
+
+```typescript
+import { RedisLock, RedisLockOptions } from '@siglo/redis';
+
+// Simple prefix configuration:
+const lock = new RedisLock(redis, 'siglo:lock:');
+
+// Full options configuration:
+const strictLock = new RedisLock(redis, {
+    keyPrefix: 'siglo:lock:',
+    strictAtomicity: true, // Enforces Redis eval (Lua) for atomic lock release
+});
+```
+
+### Options (`RedisLockOptions`)
+
+| Option | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `keyPrefix` | `string` | `'siglo:lock:'` | Root prefix for distributed mutex keys. |
+| `strictAtomicity` | `boolean` | `false` | When `true`, enforces strict atomic Lua evaluation (`client.eval`) during lock release, throwing an error if Lua scripting is unavailable rather than falling back to non-atomic commands, preventing TOCTOU race conditions. |
+
+### Methods:
+
+#### `acquire(lockKey, ttlMs?, customToken?)`
+Attempts atomic acquisition (`SET key token PX ttl NX`). Returns `{ acquired: boolean, token: string }`.
+
+#### `release(lockKey, token)`
+Safely releases the lock only if the current value matches the caller's unique token. Uses atomic Lua scripting:
+```lua
+if redis.call("get", KEYS[1]) == ARGV[1] then
+    return redis.call("del", KEYS[1])
+else
+    return 0
+end
+```
+When `strictAtomicity` is enabled, failure or absence of Lua `eval` will throw an error to prevent non-atomic release races.
+
+#### `withLock(lockKey, fn, ttlMs?)`
+Executes an asynchronous function wrapped in single-flight protection:
+- Acquires lock.
+- If acquisition fails, throws `Error('Failed to acquire lock for key: ...')`.
+- Executes `fn()`.
+- Releases lock in a `finally` block, ensuring no leaked locks even on unhandled exceptions.
+
+---
+
+## 7. Complete Production Example
+
+```typescript
+import { Redis } from 'ioredis';
+import { Step, flow } from '@siglo/core';
+import {
+    RedisStorageAdapter,
+    RedisIdempotencyStore,
+    RedisLock
+} from '@siglo/redis';
+
+// 1. Initialize Redis Client
+const redis = new Redis('redis://localhost:6379');
+
+// 2. Register Global Storage
+const storageAdapter = new RedisStorageAdapter({
+    client: redis,
+    checkpointTtlMs: 86400000, // 24 hours
+});
+Step.useStorage(storageAdapter);
+
+// 3. Initialize Idempotency & Distributed Lock
+const idempotencyStore = new RedisIdempotencyStore({ client: redis });
+const redisLock = new RedisLock(redis, { strictAtomicity: true });
+
+// 4. Define Workflow with Step Caching
+const fetchExchangeRates = Step.create('fetchRates', async () => {
+    // Heavy external HTTP call
+    return { EUR: 1.08, GBP: 1.27, JPY: 154.2 };
+})
+    .cache({ ttlMs: 300000, key: () => 'currency-rates-latest' }) // 5-minute cache
+    ;
+
+const settleInvoice = Step.create('settleInvoice', async ({ invoiceId, amount, currency }: any) => {
+    return { invoiceId, settled: true, amountUSD: amount * 1.08 };
+});
+
+const billingFlow = flow(fetchExchangeRates, settleInvoice);
+
+// 5. Single-Flight Execution Runner
+async function processDailySettlement() {
+    // Only one cluster node can execute this block at a time
+    return await redisLock.withLock('lock:daily-settlement', async () => {
+        console.log('Acquired single-flight lock. Starting settlement flow...');
+        return await billingFlow.run({
+            invoiceId: 'INV-2026-10',
+            amount: 5000,
+            currency: 'EUR',
+        });
+    }, 15000); // 15-second lock timeout
+}
+
+// 6. Graceful Shutdown
+process.on('SIGTERM', async () => {
+    await redis.quit();
+    process.exit(0);
+});
+```

package/dist/adapter.d.ts

@@ -0,0 +1,31 @@
+import { StorageAdapter, SerializedExecutionStack } from '@siglo/core';
+import { RedisStorageAdapterOptions } from './types';
+export declare class RedisStorageAdapter implements StorageAdapter {
+    readonly name = "redis";
+    private client;
+    private keyPrefix;
+    private cacheTtlMs;
+    private checkpointTtlMs;
+    private recordContextChanges;
+    constructor(options: RedisStorageAdapterOptions);
+    private cacheKey;
+    private checkpointKey;
+    private waitRecordKey;
+    private contextKey;
+    onContextChange(entry: {
+        namespace?: string;
+        stackId: string;
+        stepId: string;
+        field: string;
+        value: any;
+        timestamp: number;
+    }): Promise<void>;
+    saveCheckpoint(checkpoint: SerializedExecutionStack): Promise<void>;
+    getCheckpoint(stackId: string, namespace?: string): Promise<SerializedExecutionStack | undefined>;
+    cleanExpiredCheckpoints(): Promise<number>;
+    saveWaitRecord(record: any): Promise<void>;
+    getWaitRecord(correlationKeyOrStackId: string): Promise<any | undefined>;
+    getCachedStep(key: string): Promise<any | undefined>;
+    setCachedStep(key: string, value: any, ttlMs?: number): Promise<void>;
+}
+//# sourceMappingURL=adapter.d.ts.map

package/dist/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AACvE,OAAO,EAAE,0BAA0B,EAAwB,MAAM,SAAS,CAAC;AAE3E,qBAAa,mBAAoB,YAAW,cAAc;IACtD,SAAgB,IAAI,WAAW;IAC/B,OAAO,CAAC,MAAM,CAAuB;IACrC,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,eAAe,CAAS;IAChC,OAAO,CAAC,oBAAoB,CAAU;gBAE1B,OAAO,EAAE,0BAA0B;IAW/C,OAAO,CAAC,QAAQ;IAIhB,OAAO,CAAC,aAAa;IAMrB,OAAO,CAAC,aAAa;IAIrB,OAAO,CAAC,UAAU;IAMZ,eAAe,CAAC,KAAK,EAAE;QACzB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,OAAO,EAAE,MAAM,CAAC;QAChB,MAAM,EAAE,MAAM,CAAC;QACf,KAAK,EAAE,MAAM,CAAC;QACd,KAAK,EAAE,GAAG,CAAC;QACX,SAAS,EAAE,MAAM,CAAC;KACrB,GAAG,OAAO,CAAC,IAAI,CAAC;IAmBX,cAAc,CAAC,UAAU,EAAE,wBAAwB,GAAG,OAAO,CAAC,IAAI,CAAC;IASnE,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,wBAAwB,GAAG,SAAS,CAAC;IAqBjG,uBAAuB,IAAI,OAAO,CAAC,MAAM,CAAC;IAI1C,cAAc,CAAC,MAAM,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC;IAa1C,aAAa,CAAC,uBAAuB,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,GAAG,SAAS,CAAC;IAgBxE,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,GAAG,SAAS,CAAC;IAgBpD,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAS9E"}

package/dist/adapter.js

@@ -0,0 +1,142 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RedisStorageAdapter = void 0;
+class RedisStorageAdapter {
+    name = 'redis';
+    client;
+    keyPrefix;
+    cacheTtlMs;
+    checkpointTtlMs;
+    recordContextChanges;
+    constructor(options) {
+        if (!options || !options.client) {
+            throw new Error('RedisStorageAdapter requires a valid Redis client instance.');
+        }
+        this.client = options.client;
+        this.keyPrefix = options.keyPrefix || 'siglo:';
+        this.cacheTtlMs = options.cacheTtlMs || 86400000; // 24 hours
+        this.checkpointTtlMs = options.checkpointTtlMs || 604800000; // 7 days
+        this.recordContextChanges = options.recordContextChanges ?? true;
+    }
+    cacheKey(key) {
+        return `${this.keyPrefix}cache:${key}`;
+    }
+    checkpointKey(stackId, namespace) {
+        return namespace
+            ? `${this.keyPrefix}${namespace}:checkpoint:${stackId}`
+            : `${this.keyPrefix}checkpoint:${stackId}`;
+    }
+    waitRecordKey(key) {
+        return `${this.keyPrefix}wait:${key}`;
+    }
+    contextKey(stackId, stepId, namespace) {
+        return namespace
+            ? `${this.keyPrefix}${namespace}:context:${stackId}:${stepId}`
+            : `${this.keyPrefix}context:${stackId}:${stepId}`;
+    }
+    async onContextChange(entry) {
+        if (!this.recordContextChanges) {
+            return;
+        }
+        try {
+            const key = this.contextKey(entry.stackId, entry.stepId, entry.namespace);
+            const serialized = typeof entry.value === 'object' && entry.value !== null
+                ? JSON.stringify(entry.value)
+                : String(entry.value ?? '');
+            await this.client.hset(key, entry.field, serialized);
+            if (this.client.pexpire) {
+                await this.client.pexpire(key, this.checkpointTtlMs);
+            }
+        }
+        catch {
+            // Non-blocking telemetry error: silently ignore to protect execution flow
+        }
+    }
+    async saveCheckpoint(checkpoint) {
+        if (!checkpoint || !checkpoint.stackId) {
+            return;
+        }
+        const key = this.checkpointKey(checkpoint.stackId, checkpoint.namespace);
+        const serialized = JSON.stringify(checkpoint);
+        await this.client.set(key, serialized, 'PX', this.checkpointTtlMs);
+    }
+    async getCheckpoint(stackId, namespace) {
+        if (!stackId) {
+            return undefined;
+        }
+        let data = null;
+        if (namespace) {
+            data = await this.client.get(this.checkpointKey(stackId, namespace));
+        }
+        if (!data) {
+            data = await this.client.get(this.checkpointKey(stackId));
+        }
+        if (!data) {
+            return undefined;
+        }
+        try {
+            return JSON.parse(data);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    async cleanExpiredCheckpoints() {
+        return 0; // Handled automatically by Redis TTL expiration
+    }
+    async saveWaitRecord(record) {
+        if (!record || (!record.correlationKey && !record.stackId)) {
+            return;
+        }
+        const serialized = JSON.stringify(record);
+        if (record.correlationKey) {
+            await this.client.set(this.waitRecordKey(record.correlationKey), serialized, 'PX', this.checkpointTtlMs);
+        }
+        if (record.stackId) {
+            await this.client.set(this.waitRecordKey(record.stackId), serialized, 'PX', this.checkpointTtlMs);
+        }
+    }
+    async getWaitRecord(correlationKeyOrStackId) {
+        if (!correlationKeyOrStackId) {
+            return undefined;
+        }
+        const data = await this.client.get(this.waitRecordKey(correlationKeyOrStackId));
+        if (data) {
+            try {
+                return JSON.parse(data);
+            }
+            catch {
+                return undefined;
+            }
+        }
+        const cp = await this.getCheckpoint(correlationKeyOrStackId);
+        return cp?.metadata?.waitRecord;
+    }
+    async getCachedStep(key) {
+        if (!key) {
+            return undefined;
+        }
+        const fullKey = this.cacheKey(key);
+        const data = await this.client.get(fullKey);
+        if (!data) {
+            return undefined;
+        }
+        try {
+            return JSON.parse(data);
+        }
+        catch {
+            return data;
+        }
+    }
+    async setCachedStep(key, value, ttlMs) {
+        if (!key) {
+            return;
+        }
+        const fullKey = this.cacheKey(key);
+        const effectiveTtl = ttlMs || this.cacheTtlMs;
+        const serialized = typeof value === 'object' && value !== null ? JSON.stringify(value) : JSON.stringify({ value });
+        await this.client.set(fullKey, serialized, 'PX', effectiveTtl);
+    }
+}
+exports.RedisStorageAdapter = RedisStorageAdapter;
+//# sourceMappingURL=adapter.js.map

package/dist/adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.js","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"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"}

package/dist/idempotency.d.ts

@@ -0,0 +1,14 @@
+import { IdempotencyStore } from '@siglo/core';
+import { RedisIdempotencyOptions } from './types';
+export declare class RedisIdempotencyStore implements IdempotencyStore {
+    private client;
+    private keyPrefix;
+    private defaultTtlMs;
+    constructor(options: RedisIdempotencyOptions);
+    private formatKey;
+    claim(key: string, ttlMs?: number): Promise<'claimed' | 'completed' | 'in-progress'>;
+    complete(key: string, result: unknown, ttlMs?: number): Promise<void>;
+    fail(key: string, _error: unknown): Promise<void>;
+    getResult(key: string): Promise<unknown | undefined>;
+}
+//# sourceMappingURL=idempotency.d.ts.map

package/dist/idempotency.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"idempotency.d.ts","sourceRoot":"","sources":["../src/idempotency.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EAAE,uBAAuB,EAAwB,MAAM,SAAS,CAAC;AAKxE,qBAAa,qBAAsB,YAAW,gBAAgB;IAC1D,OAAO,CAAC,MAAM,CAAuB;IACrC,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,YAAY,CAAS;gBAEjB,OAAO,EAAE,uBAAuB;IAS5C,OAAO,CAAC,SAAS;IAIX,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,WAAW,GAAG,aAAa,CAAC;IAmBpF,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAOrE,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IASjD,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,SAAS,CAAC;CAY7D"}

package/dist/idempotency.js

@@ -0,0 +1,65 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RedisIdempotencyStore = void 0;
+const COMPLETED_PREFIX = 'COMPLETED:';
+const IN_PROGRESS_VAL = 'in-progress';
+class RedisIdempotencyStore {
+    client;
+    keyPrefix;
+    defaultTtlMs;
+    constructor(options) {
+        if (!options || !options.client) {
+            throw new Error('RedisIdempotencyStore requires a valid Redis client instance.');
+        }
+        this.client = options.client;
+        this.keyPrefix = options.keyPrefix || 'siglo:idemp:';
+        this.defaultTtlMs = options.defaultTtlMs || 86400000; // 24 hours default
+    }
+    formatKey(key) {
+        return `${this.keyPrefix}${key}`;
+    }
+    async claim(key, ttlMs) {
+        const fullKey = this.formatKey(key);
+        const effectiveTtl = ttlMs || this.defaultTtlMs;
+        // Atomic lock attempt: SET fullKey "in-progress" NX PX effectiveTtl
+        const response = await this.client.set(fullKey, IN_PROGRESS_VAL, 'PX', effectiveTtl, 'NX');
+        if (response === 'OK') {
+            return 'claimed';
+        }
+        // Already exists: inspect current state
+        const existing = await this.client.get(fullKey);
+        if (existing && existing.startsWith(COMPLETED_PREFIX)) {
+            return 'completed';
+        }
+        return 'in-progress';
+    }
+    async complete(key, result, ttlMs) {
+        const fullKey = this.formatKey(key);
+        const effectiveTtl = ttlMs || this.defaultTtlMs;
+        const payload = COMPLETED_PREFIX + JSON.stringify(result ?? null);
+        await this.client.set(fullKey, payload, 'PX', effectiveTtl);
+    }
+    async fail(key, _error) {
+        const fullKey = this.formatKey(key);
+        // Clear in-flight claim to allow subsequent retry execution
+        const existing = await this.client.get(fullKey);
+        if (existing === IN_PROGRESS_VAL) {
+            await this.client.del(fullKey);
+        }
+    }
+    async getResult(key) {
+        const fullKey = this.formatKey(key);
+        const data = await this.client.get(fullKey);
+        if (data && data.startsWith(COMPLETED_PREFIX)) {
+            try {
+                return JSON.parse(data.slice(COMPLETED_PREFIX.length));
+            }
+            catch {
+                return undefined;
+            }
+        }
+        return undefined;
+    }
+}
+exports.RedisIdempotencyStore = RedisIdempotencyStore;
+//# sourceMappingURL=idempotency.js.map

package/dist/idempotency.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"idempotency.js","sourceRoot":"","sources":["../src/idempotency.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export * from './types';
+export * from './adapter';
+export * from './idempotency';
+export * from './lock';
+export * from './nonce';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,WAAW,CAAC;AAC1B,cAAc,eAAe,CAAC;AAC9B,cAAc,QAAQ,CAAC;AACvB,cAAc,SAAS,CAAC"}

package/dist/index.js

@@ -0,0 +1,22 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./types"), exports);
+__exportStar(require("./adapter"), exports);
+__exportStar(require("./idempotency"), exports);
+__exportStar(require("./lock"), exports);
+__exportStar(require("./nonce"), exports);
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,0CAAwB;AACxB,4CAA0B;AAC1B,gDAA8B;AAC9B,yCAAuB;AACvB,0CAAwB"}

package/dist/lock.d.ts

@@ -0,0 +1,29 @@
+import { RedisClientInterface } from './types';
+export interface RedisLockResult {
+    acquired: boolean;
+    token: string;
+}
+export interface RedisLockOptions {
+    keyPrefix?: string;
+    strictAtomicity?: boolean;
+}
+export declare class RedisLock {
+    private client;
+    private keyPrefix;
+    private strictAtomicity;
+    constructor(client: RedisClientInterface, optionsOrPrefix?: string | RedisLockOptions);
+    private fullKey;
+    /**
+     * Attempts to acquire an atomic distributed lock for single-flight coordination.
+     */
+    acquire(lockKey: string, ttlMs?: number, customToken?: string): Promise<RedisLockResult>;
+    /**
+     * Releases the lock safely only if the token matches.
+     */
+    release(lockKey: string, token: string): Promise<boolean>;
+    /**
+     * Executes an async operation with single-flight lock protection.
+     */
+    withLock<T>(lockKey: string, fn: () => Promise<T>, ttlMs?: number): Promise<T>;
+}
+//# sourceMappingURL=lock.d.ts.map

package/dist/lock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lock.d.ts","sourceRoot":"","sources":["../src/lock.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAC;AAE/C,MAAM,WAAW,eAAe;IAC5B,QAAQ,EAAE,OAAO,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,gBAAgB;IAC7B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED,qBAAa,SAAS;IAClB,OAAO,CAAC,MAAM,CAAuB;IACrC,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,eAAe,CAAU;gBAErB,MAAM,EAAE,oBAAoB,EAAE,eAAe,GAAE,MAAM,GAAG,gBAAgC;IAcpG,OAAO,CAAC,OAAO;IAIf;;OAEG;IACG,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,GAAE,MAAc,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC;IAUrG;;OAEG;IACG,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IA2B/D;;OAEG;IACG,QAAQ,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,KAAK,GAAE,MAAc,GAAG,OAAO,CAAC,CAAC,CAAC;CAW9F"}

package/dist/lock.js

@@ -0,0 +1,79 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RedisLock = void 0;
+const crypto_1 = require("crypto");
+class RedisLock {
+    client;
+    keyPrefix;
+    strictAtomicity;
+    constructor(client, optionsOrPrefix = 'siglo:lock:') {
+        if (!client) {
+            throw new Error('RedisLock requires a valid Redis client instance.');
+        }
+        this.client = client;
+        if (typeof optionsOrPrefix === 'string') {
+            this.keyPrefix = optionsOrPrefix;
+            this.strictAtomicity = false;
+        }
+        else {
+            this.keyPrefix = optionsOrPrefix.keyPrefix || 'siglo:lock:';
+            this.strictAtomicity = optionsOrPrefix.strictAtomicity ?? false;
+        }
+    }
+    fullKey(key) {
+        return `${this.keyPrefix}${key}`;
+    }
+    /**
+     * Attempts to acquire an atomic distributed lock for single-flight coordination.
+     */
+    async acquire(lockKey, ttlMs = 10000, customToken) {
+        const key = this.fullKey(lockKey);
+        const token = customToken || `lock_${Date.now()}_${(0, crypto_1.randomBytes)(16).toString('hex')}`;
+        const res = await this.client.set(key, token, 'PX', ttlMs, 'NX');
+        const acquired = res === 'OK';
+        return { acquired, token };
+    }
+    /**
+     * Releases the lock safely only if the token matches.
+     */
+    async release(lockKey, token) {
+        const key = this.fullKey(lockKey);
+        if (this.client.eval) {
+            const lua = `
+                if redis.call("get", KEYS[1]) == ARGV[1] then
+                    return redis.call("del", KEYS[1])
+                else
+                    return 0
+                end
+            `;
+            const res = await this.client.eval(lua, 1, key, token);
+            return res === 1;
+        }
+        if (this.strictAtomicity) {
+            throw new Error('RedisLock: client.eval is required for atomic release to prevent TOCTOU race condition.');
+        }
+        const currentVal = await this.client.get(key);
+        if (currentVal === token) {
+            await this.client.del(key);
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Executes an async operation with single-flight lock protection.
+     */
+    async withLock(lockKey, fn, ttlMs = 10000) {
+        const { acquired, token } = await this.acquire(lockKey, ttlMs);
+        if (!acquired) {
+            throw new Error(`Failed to acquire lock for key: ${lockKey} (in-use or concurrent execution)`);
+        }
+        try {
+            return await fn();
+        }
+        finally {
+            await this.release(lockKey, token).catch(() => { });
+        }
+    }
+}
+exports.RedisLock = RedisLock;
+//# sourceMappingURL=lock.js.map

package/dist/lock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lock.js","sourceRoot":"","sources":["../src/lock.ts"],"names":[],"mappings":";;;AAAA,mCAAqC;AAarC,MAAa,SAAS;IACV,MAAM,CAAuB;IAC7B,SAAS,CAAS;IAClB,eAAe,CAAU;IAEjC,YAAY,MAA4B,EAAE,kBAA6C,aAAa;QAChG,IAAI,CAAC,MAAM,EAAE,CAAC;YACV,MAAM,IAAI,KAAK,CAAC,mDAAmD,CAAC,CAAC;QACzE,CAAC;QACD,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,OAAO,eAAe,KAAK,QAAQ,EAAE,CAAC;YACtC,IAAI,CAAC,SAAS,GAAG,eAAe,CAAC;YACjC,IAAI,CAAC,eAAe,GAAG,KAAK,CAAC;QACjC,CAAC;aAAM,CAAC;YACJ,IAAI,CAAC,SAAS,GAAG,eAAe,CAAC,SAAS,IAAI,aAAa,CAAC;YAC5D,IAAI,CAAC,eAAe,GAAG,eAAe,CAAC,eAAe,IAAI,KAAK,CAAC;QACpE,CAAC;IACL,CAAC;IAEO,OAAO,CAAC,GAAW;QACvB,OAAO,GAAG,IAAI,CAAC,SAAS,GAAG,GAAG,EAAE,CAAC;IACrC,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,OAAO,CAAC,OAAe,EAAE,QAAgB,KAAK,EAAE,WAAoB;QACtE,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;QAClC,MAAM,KAAK,GAAG,WAAW,IAAI,QAAQ,IAAI,CAAC,GAAG,EAAE,IAAI,IAAA,oBAAW,EAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QAErF,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC;QACjE,MAAM,QAAQ,GAAG,GAAG,KAAK,IAAI,CAAC;QAE9B,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC;IAC/B,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,OAAO,CAAC,OAAe,EAAE,KAAa;QACxC,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;QAElC,IAAI,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;YACnB,MAAM,GAAG,GAAG;;;;;;aAMX,CAAC;YACF,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC;YACvD,OAAO,GAAG,KAAK,CAAC,CAAC;QACrB,CAAC;QAED,IAAI,IAAI,CAAC,eAAe,EAAE,CAAC;YACvB,MAAM,IAAI,KAAK,CAAC,yFAAyF,CAAC,CAAC;QAC/G,CAAC;QAED,MAAM,UAAU,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAC9C,IAAI,UAAU,KAAK,KAAK,EAAE,CAAC;YACvB,MAAM,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YAC3B,OAAO,IAAI,CAAC;QAChB,CAAC;QACD,OAAO,KAAK,CAAC;IACjB,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,QAAQ,CAAI,OAAe,EAAE,EAAoB,EAAE,QAAgB,KAAK;QAC1E,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QAC/D,IAAI,CAAC,QAAQ,EAAE,CAAC;YACZ,MAAM,IAAI,KAAK,CAAC,mCAAmC,OAAO,mCAAmC,CAAC,CAAC;QACnG,CAAC;QACD,IAAI,CAAC;YACD,OAAO,MAAM,EAAE,EAAE,CAAC;QACtB,CAAC;gBAAS,CAAC;YACP,MAAM,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;QACvD,CAAC;IACL,CAAC;CACJ;AAhFD,8BAgFC"}

package/dist/nonce.d.ts

@@ -0,0 +1,16 @@
+import { RedisNonceStoreOptions } from './types';
+/**
+ * Distributed Redis nonce / signature deduplication store for webhook replay attack prevention.
+ * Uses atomic Redis `SET ... PX ... NX` to enforce single-use tokens within the tolerance window.
+ */
+export declare class RedisNonceStore {
+    private client;
+    private keyPrefix;
+    constructor(options: RedisNonceStoreOptions);
+    /**
+     * Atomically claims a deduplication key with TTL.
+     * Returns true if claimed (first delivery attempt), or false if key already exists (replay).
+     */
+    claim(key: string, ttlSeconds: number): Promise<boolean>;
+}
+//# sourceMappingURL=nonce.d.ts.map

package/dist/nonce.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nonce.d.ts","sourceRoot":"","sources":["../src/nonce.ts"],"names":[],"mappings":"AAAA,OAAO,EAAwB,sBAAsB,EAAE,MAAM,SAAS,CAAC;AAEvE;;;GAGG;AACH,qBAAa,eAAe;IACxB,OAAO,CAAC,MAAM,CAAuB;IACrC,OAAO,CAAC,SAAS,CAAS;gBAEd,OAAO,EAAE,sBAAsB;IAQ3C;;;OAGG;IACG,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;CAMjE"}

package/dist/nonce.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RedisNonceStore = void 0;
+/**
+ * Distributed Redis nonce / signature deduplication store for webhook replay attack prevention.
+ * Uses atomic Redis `SET ... PX ... NX` to enforce single-use tokens within the tolerance window.
+ */
+class RedisNonceStore {
+    client;
+    keyPrefix;
+    constructor(options) {
+        if (!options || !options.client) {
+            throw new Error('RedisNonceStore requires a valid Redis client instance.');
+        }
+        this.client = options.client;
+        this.keyPrefix = options.keyPrefix || 'siglo:wh:dedup:';
+    }
+    /**
+     * Atomically claims a deduplication key with TTL.
+     * Returns true if claimed (first delivery attempt), or false if key already exists (replay).
+     */
+    async claim(key, ttlSeconds) {
+        const fullKey = `${this.keyPrefix}${key}`;
+        const ttlMs = Math.max(1, Math.floor(ttlSeconds * 1000));
+        const res = await this.client.set(fullKey, '1', 'PX', ttlMs, 'NX');
+        return res === 'OK';
+    }
+}
+exports.RedisNonceStore = RedisNonceStore;
+//# sourceMappingURL=nonce.js.map

package/dist/nonce.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nonce.js","sourceRoot":"","sources":["../src/nonce.ts"],"names":[],"mappings":";;;AAEA;;;GAGG;AACH,MAAa,eAAe;IAChB,MAAM,CAAuB;IAC7B,SAAS,CAAS;IAE1B,YAAY,OAA+B;QACvC,IAAI,CAAC,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC;YAC9B,MAAM,IAAI,KAAK,CAAC,yDAAyD,CAAC,CAAC;QAC/E,CAAC;QACD,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;QAC7B,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,iBAAiB,CAAC;IAC5D,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,KAAK,CAAC,GAAW,EAAE,UAAkB;QACvC,MAAM,OAAO,GAAG,GAAG,IAAI,CAAC,SAAS,GAAG,GAAG,EAAE,CAAC;QAC1C,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,UAAU,GAAG,IAAI,CAAC,CAAC,CAAC;QACzD,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC;QACnE,OAAO,GAAG,KAAK,IAAI,CAAC;IACxB,CAAC;CACJ;AAtBD,0CAsBC"}

package/dist/types.d.ts

@@ -0,0 +1,27 @@
+export interface RedisClientInterface {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, ...args: any[]): Promise<'OK' | string | null>;
+    del(key: string | string[]): Promise<number>;
+    hset(key: string, field: string | Record<string, string>, value?: string): Promise<number>;
+    hgetall?(key: string): Promise<Record<string, string>>;
+    expire?(key: string, seconds: number): Promise<number>;
+    pexpire?(key: string, milliseconds: number): Promise<number>;
+    eval?(script: string, numKeys: number, ...args: (string | number)[]): Promise<any>;
+}
+export interface RedisStorageAdapterOptions {
+    client: RedisClientInterface;
+    keyPrefix?: string;
+    cacheTtlMs?: number;
+    checkpointTtlMs?: number;
+    recordContextChanges?: boolean;
+}
+export interface RedisIdempotencyOptions {
+    client: RedisClientInterface;
+    keyPrefix?: string;
+    defaultTtlMs?: number;
+}
+export interface RedisNonceStoreOptions {
+    client: RedisClientInterface;
+    keyPrefix?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,oBAAoB;IACjC,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACzC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,GAAG,OAAO,CAAC,IAAI,GAAG,MAAM,GAAG,IAAI,CAAC,CAAC;IAC/E,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC7C,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC3F,OAAO,CAAC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACvD,MAAM,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACvD,OAAO,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC7D,IAAI,CAAC,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;CACtF;AAED,MAAM,WAAW,0BAA0B;IACvC,MAAM,EAAE,oBAAoB,CAAC;IAC7B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,oBAAoB,CAAC,EAAE,OAAO,CAAC;CAClC;AAED,MAAM,WAAW,uBAAuB;IACpC,MAAM,EAAE,oBAAoB,CAAC;IAC7B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,sBAAsB;IACnC,MAAM,EAAE,oBAAoB,CAAC;IAC7B,SAAS,CAAC,EAAE,MAAM,CAAC;CACtB"}

package/dist/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -1,6 +1,61 @@
 {
   "name": "@siglo/redis",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Production Redis distributed cache, durable checkpoint, and idempotency adapter for Siglo workflows",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepublishOnly": "npm run build",
+    "test": "npm run build && mocha -r tsx 'src/**/*.test.ts'"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jsoftgem/siglo.git",
+    "directory": "packages/redis"
+  },
+  "author": "Jerico de Guzman",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/jsoftgem/siglo/issues"
+  },
+  "homepage": "https://github.com/jsoftgem/siglo#readme",
+  "dependencies": {
+    "@siglo/core": "^1.0.0"
+  },
+  "peerDependencies": {
+    "ioredis": "^5.0.0 || ^6.0.0"
+  },
+  "peerDependenciesMeta": {
+    "ioredis": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/chai": "^5.2.3",
+    "@types/mocha": "^10.0.10",
+    "@types/node": "^26.6.5",
+    "chai": "^3.5.0",
+    "mocha": "^12.0.3",
+    "tsx": "^4.23.15",
+    "typescript": "~5.7.0"
+  }
+}