@hile/redis-idempotency 3.0.1 → 3.0.2

package/README.md

@@ -2,21 +2,24 @@
 
 Redis-backed idempotency primitives for Hile services. The package name names the storage backend; the API names stay storage-neutral:
 
+- `new RedisIdempotency(redis).run(key, fn, options)` for class-first service composition
 - `withIdempotency(redis, key, fn, options)` for functions, message handlers, jobs, and model `main()` bodies
 - `idempotent(options)` for Koa-style `@hile/model` `Pipeline` middleware
 - `stableHash(value)` for payload fingerprints
 
+从 3.0.0 开始，新增或重构的 Hile 架构包统一进入 3.x 版本线，2.x 时代结束。
+
 ## Why this package exists
 
 Retries are normal in distributed systems. `Application.call()` may retry after timeout, queues may redeliver a message, and users may submit the same form twice. If the retried operation writes money, quota, notifications, or orders, duplicate execution becomes a real business bug.
 
-This package provides a shared Redis state machine:
+This package provides a shared Redis state machine on top of `@hile/redis-lock`:
 
 ```
 FREE -> IN_FLIGHT(owner token) -> DONE(cached result)
 ```
 
-The state lives in a single Redis key. Lua scripts atomically acquire, read, commit, and release the key so callers across processes share the same view.
+The idempotency state lives in the idempotency key, while execution ownership is guarded by a Redis lease lock. Lua scripts still commit and clear the business state only when the caller owns the underlying lock.
 
 Important boundary: Redis idempotency is not exactly-once. If the business side effect succeeds and the process crashes before the `DONE` state is committed, a later retry may run the function again. For money, quota, orders, and notifications, keep database unique constraints, transactions, outbox records, or provider idempotency keys as the final wall.
 
@@ -40,17 +43,17 @@ const redis = await loadService(redisService)
 ```typescript
 import { loadService } from '@hile/core'
 import redisService from '@hile/ioredis'
-import { stableHash, withIdempotency } from '@hile/redis-idempotency'
+import { RedisIdempotency, stableHash } from '@hile/redis-idempotency'
 
 const redis = await loadService(redisService)
+const idempotency = new RedisIdempotency(redis)
 
 async function debitWallet(input: {
   tenantId: string
   requestId: string
   amount: number
 }) {
-  return withIdempotency(
-    redis,
+  return idempotency.run(
     `idem:prod:wallet:debit:${input.tenantId}:${input.requestId}`,
     async () => {
       // Put the side-effecting operation here.
@@ -77,13 +80,22 @@ What happens:
 
 ### withIdempotency(redis, key, fn, options)
 
+`withIdempotency()` 是兼容函数，内部会创建 `RedisIdempotency` 实例并调用 `.run()`。新代码更推荐在服务层复用 `RedisIdempotency` 实例。
+
+### RedisIdempotency
+
 ```typescript
-function withIdempotency<T>(
-  redis: RedisLike,
-  key: string,
-  fn: () => Promise<T>,
-  options: IdempotencyOptions<T>,
-): Promise<T>
+const idempotency = new RedisIdempotency(redis)
+
+await idempotency.run(
+  'idem:prod:wallet:debit:t1:r1',
+  async () => performDebit(input),
+  {
+    lockTtl: 60_000,
+    resultTtl: 86_400_000,
+    fingerprint,
+  },
+)
 ```
 
 `key` must already include the full namespace. A safe format is:
@@ -148,6 +160,7 @@ const fingerprint = stableHash({
 ### idempotent(options)
 
 `idempotent()` is a Koa-style `PipelineMiddleware`. It wraps `await next()`, caches `ctx.state.result`, and writes cached results back to `ctx.state.result`.
+Pass `resultCodec` when `ctx.state.result` contains non-JSON types; the middleware forwards it to the underlying `RedisIdempotency` run.
 
 ```typescript
 import { Pipeline, PipelineContext } from '@hile/model'
@@ -213,7 +226,7 @@ For normal Hile models that load Redis through `services: [redisService]`, or fo
 | Kafka / queue consumer | max handler time + margin | 24h or redelivery SLA |
 | Payment/recharge callback | max handler time + margin | 24h+ or provider retry SLA |
 
-If a job can run longer than a predictable `lockTtl`, do not use this package as-is for that job until lease renewal exists.
+If a job can run longer than a predictable `lockTtl`, do not use this package as-is for that job until the idempotency layer exposes lease renewal.
 
 ## Testing
 

package/SKILL.md

@@ -12,14 +12,15 @@ Use `@hile/redis-idempotency` when a write operation may be retried or redeliver
 Package name names the backend; API names stay generic:
 
 ```typescript
-import { stableHash, withIdempotency } from '@hile/redis-idempotency'
+import { RedisIdempotency, stableHash } from '@hile/redis-idempotency'
 ```
 
 Wrap the smallest side-effecting function:
 
 ```typescript
-return withIdempotency(
-  redis,
+const idempotency = new RedisIdempotency(redis)
+
+return idempotency.run(
   `idem:prod:wallet:debit:${tenantId}:${requestId}`,
   () => debitWallet(input),
   {
@@ -30,6 +31,12 @@ return withIdempotency(
 )
 ```
 
+`withIdempotency(redis, key, fn, options)` remains as a compatibility wrapper around `RedisIdempotency.run()`.
+
+## Redis Lock Base
+
+`@hile/redis-idempotency` is a higher-level abstraction over `@hile/redis-lock`: use the lock package for execution ownership and waiting, and keep idempotency-specific `IN_FLIGHT` / `DONE` state in this package.
+
 ## Key Design
 
 | Do | Avoid |

package/dist/idempotency.d.ts

@@ -0,0 +1,17 @@
+import { RedisLock } from '@hile/redis-lock';
+import type { IdempotencyOptions, IdempotencyResultCodec, RedisLike } from './types';
+export interface RedisIdempotencyDependencies {
+    locks?: RedisLock;
+}
+export declare class RedisIdempotency {
+    private readonly locks;
+    private readonly store;
+    constructor(redis: RedisLike, dependencies?: RedisIdempotencyDependencies);
+    run<T>(key: string, fn: () => Promise<T>, options: IdempotencyOptions<T>): Promise<T>;
+    private makeLockKey;
+    private handleInFlight;
+    private runAsOwner;
+    private waitForResult;
+    private mapLockError;
+}
+export type RedisIdempotencyResultCodec<T = unknown> = IdempotencyResultCodec<T>;

package/dist/idempotency.js

@@ -0,0 +1,137 @@
+import { LockConflictError, LockOwnershipLostError, LockTimeoutError, RedisLock, } from '@hile/redis-lock';
+import { IdempotencyConflictError, IdempotencyOwnershipLostError, IdempotencyPayloadMismatchError, IdempotencyRetryableError, IdempotencyTimeoutError, } from './errors.js';
+import { RedisIdempotencyStore } from './store.js';
+const sleep = (ms) => new Promise(resolve => setTimeout(resolve, ms));
+function assertPositiveInteger(value, name) {
+    if (!Number.isFinite(value) || value <= 0 || Math.trunc(value) !== value) {
+        throw new TypeError(`${name} must be a positive integer`);
+    }
+}
+function resolveOptions(options) {
+    assertPositiveInteger(options.lockTtl, 'lockTtl');
+    assertPositiveInteger(options.resultTtl, 'resultTtl');
+    if (!options.fingerprint)
+        throw new TypeError('fingerprint is required');
+    const resolved = {
+        ...options,
+        wait: options.wait ?? options.lockTtl,
+        onConflict: options.onConflict ?? 'wait',
+        pollInterval: options.pollInterval ?? 20,
+        maxPollInterval: options.maxPollInterval ?? 500,
+    };
+    assertPositiveInteger(resolved.wait, 'wait');
+    assertPositiveInteger(resolved.pollInterval, 'pollInterval');
+    assertPositiveInteger(resolved.maxPollInterval, 'maxPollInterval');
+    return resolved;
+}
+export class RedisIdempotency {
+    locks;
+    store;
+    constructor(redis, dependencies = {}) {
+        this.locks = dependencies.locks ?? new RedisLock(redis);
+        this.store = new RedisIdempotencyStore(redis);
+    }
+    async run(key, fn, options) {
+        const resolved = resolveOptions(options);
+        const context = {
+            key,
+            lockKey: this.makeLockKey(key),
+            fn,
+            options: resolved,
+        };
+        const existing = await this.store.read(key, resolved.fingerprint, resolved.resultCodec);
+        if (existing.type === 'cached')
+            return existing.data;
+        if (existing.type === 'mismatch')
+            throw new IdempotencyPayloadMismatchError(key);
+        if (existing.type === 'in-flight')
+            return this.handleInFlight(context);
+        try {
+            return await this.locks.withLock(context.lockKey, { ttl: resolved.lockTtl, wait: 0 }, lease => this.runAsOwner(context, lease, false));
+        }
+        catch (err) {
+            if (!(err instanceof LockConflictError))
+                throw this.mapLockError(key, err);
+            if (resolved.onConflict === 'reject')
+                throw new IdempotencyConflictError(key);
+        }
+        try {
+            return await this.locks.withLock(context.lockKey, {
+                ttl: resolved.lockTtl,
+                wait: resolved.wait,
+                pollInterval: resolved.pollInterval,
+                maxPollInterval: resolved.maxPollInterval,
+            }, lease => this.runAsOwner(context, lease, true));
+        }
+        catch (err) {
+            throw this.mapLockError(key, err);
+        }
+    }
+    makeLockKey(key) {
+        return `${key}:lock`;
+    }
+    async handleInFlight(context) {
+        if (context.options.onConflict === 'reject') {
+            throw new IdempotencyConflictError(context.key);
+        }
+        return this.waitForResult(context);
+    }
+    async runAsOwner(context, lease, contended) {
+        const current = await this.store.read(context.key, context.options.fingerprint, context.options.resultCodec);
+        if (current.type === 'cached')
+            return current.data;
+        if (current.type === 'mismatch')
+            throw new IdempotencyPayloadMismatchError(context.key);
+        if (current.type === 'in-flight')
+            return this.handleInFlight(context);
+        if (contended)
+            throw new IdempotencyRetryableError(context.key);
+        await this.store.markInFlight(context.key, lease.token, context.options.fingerprint, context.options.lockTtl);
+        let result;
+        try {
+            result = await context.fn();
+        }
+        catch (err) {
+            let cleared;
+            try {
+                cleared = await this.store.clearInFlightIfLockOwner(context.key, lease.key, lease.token);
+            }
+            catch (releaseErr) {
+                throw new AggregateError([err, releaseErr], 'Idempotency operation failed and clearing the in-flight key also failed');
+            }
+            if (!cleared) {
+                throw new AggregateError([err, new IdempotencyOwnershipLostError(context.key)], 'Idempotency operation failed and clearing the in-flight key also failed');
+            }
+            throw err;
+        }
+        const committed = await this.store.commitDoneIfLockOwner(context.key, lease.key, lease.token, context.options.fingerprint, result, context.options.resultTtl, context.options.resultCodec);
+        if (!committed)
+            throw new IdempotencyOwnershipLostError(context.key);
+        return result;
+    }
+    async waitForResult(context) {
+        const deadline = Date.now() + context.options.wait;
+        let delay = context.options.pollInterval;
+        while (Date.now() < deadline) {
+            const state = await this.store.read(context.key, context.options.fingerprint, context.options.resultCodec);
+            if (state.type === 'empty')
+                throw new IdempotencyRetryableError(context.key);
+            if (state.type === 'mismatch')
+                throw new IdempotencyPayloadMismatchError(context.key);
+            if (state.type === 'cached')
+                return state.data;
+            await sleep(Math.min(delay, Math.max(0, deadline - Date.now())));
+            delay = Math.min(delay * 2, context.options.maxPollInterval);
+        }
+        throw new IdempotencyTimeoutError(context.key);
+    }
+    mapLockError(key, err) {
+        if (err instanceof LockConflictError)
+            return new IdempotencyConflictError(key);
+        if (err instanceof LockTimeoutError)
+            return new IdempotencyTimeoutError(key);
+        if (err instanceof LockOwnershipLostError)
+            return new IdempotencyOwnershipLostError(key);
+        return err;
+    }
+}

package/dist/index.d.ts

@@ -1,5 +1,7 @@
 export { IdempotencyConflictError, IdempotencyError, IdempotencyOwnershipLostError, IdempotencyPayloadMismatchError, IdempotencyRetryableError, IdempotencyTimeoutError, } from './errors.js';
+export { RedisIdempotency } from './idempotency.js';
 export { idempotent } from './middleware.js';
 export { stableHash } from './stable-hash.js';
 export { withIdempotency } from './with-idempotency.js';
 export type { IdempotencyOptions, IdempotencyResultCodec, IdempotencyState, IdempotentMiddlewareOptions, JsonValue, RedisLike, StoredIdempotencyResult, } from './types.js';
+export type { RedisIdempotencyDependencies } from './idempotency.js';

package/dist/index.js

@@ -1,4 +1,5 @@
 export { IdempotencyConflictError, IdempotencyError, IdempotencyOwnershipLostError, IdempotencyPayloadMismatchError, IdempotencyRetryableError, IdempotencyTimeoutError, } from './errors.js';
+export { RedisIdempotency } from './idempotency.js';
 export { idempotent } from './middleware.js';
 export { stableHash } from './stable-hash.js';
 export { withIdempotency } from './with-idempotency.js';

package/dist/middleware.d.ts

@@ -1,3 +1,3 @@
 import type { PipelineMiddleware } from '@hile/model';
 import type { IdempotentMiddlewareOptions } from './types';
-export declare function idempotent<TInput extends object = Record<string, unknown>>(options: IdempotentMiddlewareOptions<TInput>): PipelineMiddleware<TInput>;
+export declare function idempotent<TInput extends object = Record<string, unknown>, TResult = unknown>(options: IdempotentMiddlewareOptions<TInput, TResult>): PipelineMiddleware<TInput>;

package/dist/middleware.js

@@ -15,6 +15,7 @@ export function idempotent(options) {
             pollInterval: options.pollInterval,
             maxPollInterval: options.maxPollInterval,
             fingerprint: resolveFingerprint(options.fingerprint, ctx.args),
+            resultCodec: options.resultCodec,
         });
         ctx.state.result = result;
     };

package/dist/result-codec.d.ts

@@ -0,0 +1,4 @@
+import type { IdempotencyResultCodec, StoredIdempotencyResult } from './types';
+export declare function encodeResult<T>(value: T, codec?: IdempotencyResultCodec<T>): StoredIdempotencyResult;
+export declare function decodeResult<T>(stored: StoredIdempotencyResult, codec?: IdempotencyResultCodec<T>): T;
+export declare function assertStoredResult(value: unknown): StoredIdempotencyResult;

package/dist/result-codec.js

@@ -0,0 +1,96 @@
+function isPlainObject(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+function resultSerializationError(path, reason) {
+    return new TypeError(`Idempotency result must be JSON-serializable at ${path}: ${reason}. Provide resultCodec for custom result types.`);
+}
+function toJsonValue(value, path = 'result', seen = new WeakSet()) {
+    if (value === null)
+        return null;
+    if (typeof value === 'string' || typeof value === 'boolean')
+        return value;
+    if (typeof value === 'number') {
+        if (!Number.isFinite(value))
+            throw resultSerializationError(path, 'non-finite numbers are not JSON values');
+        return value;
+    }
+    const type = typeof value;
+    if (type === 'undefined')
+        throw resultSerializationError(path, 'undefined is only supported as the top-level result');
+    if (type === 'bigint' || type === 'symbol' || type === 'function') {
+        throw resultSerializationError(path, `${type} is not a JSON value`);
+    }
+    if (typeof value !== 'object') {
+        throw resultSerializationError(path, `${type} is not a JSON value`);
+    }
+    if (seen.has(value)) {
+        throw resultSerializationError(path, 'circular references are not JSON values');
+    }
+    seen.add(value);
+    if (Array.isArray(value)) {
+        const array = [];
+        for (let i = 0; i < value.length; i += 1) {
+            if (!(i in value))
+                throw resultSerializationError(`${path}[${i}]`, 'sparse arrays are not JSON values');
+            array.push(toJsonValue(value[i], `${path}[${i}]`, seen));
+        }
+        seen.delete(value);
+        return array;
+    }
+    if (!isPlainObject(value)) {
+        seen.delete(value);
+        throw resultSerializationError(path, `${Object.prototype.toString.call(value)} is not a plain JSON object`);
+    }
+    const symbols = Object.getOwnPropertySymbols(value);
+    if (symbols.length > 0) {
+        seen.delete(value);
+        throw resultSerializationError(path, 'symbol keys are not JSON values');
+    }
+    const object = {};
+    for (const key of Object.keys(value)) {
+        object[key] = toJsonValue(value[key], `${path}.${key}`, seen);
+    }
+    seen.delete(value);
+    return object;
+}
+export function encodeResult(value, codec) {
+    if (codec) {
+        const encoded = codec.serialize(value);
+        if (typeof encoded !== 'string') {
+            throw new TypeError('resultCodec.serialize must return a string');
+        }
+        return { encoding: 'custom', value: encoded };
+    }
+    if (value === undefined)
+        return { encoding: 'undefined' };
+    return { encoding: 'json', value: toJsonValue(value) };
+}
+export function decodeResult(stored, codec) {
+    if (stored.encoding === 'undefined')
+        return undefined;
+    if (stored.encoding === 'json')
+        return stored.value;
+    if (stored.encoding === 'custom') {
+        if (!codec) {
+            throw new TypeError('Cached idempotency result requires resultCodec to deserialize');
+        }
+        return codec.deserialize(stored.value);
+    }
+    throw new Error('Invalid cached idempotency result');
+}
+export function assertStoredResult(value) {
+    if (typeof value !== 'object' || value === null || !('encoding' in value)) {
+        throw new Error('Invalid cached idempotency result');
+    }
+    const stored = value;
+    if (stored.encoding === 'undefined')
+        return stored;
+    if (stored.encoding === 'json' && 'value' in stored)
+        return stored;
+    if (stored.encoding === 'custom' && typeof stored.value === 'string')
+        return stored;
+    throw new Error('Invalid cached idempotency result');
+}

package/dist/scripts.d.ts

@@ -1,3 +1,2 @@
-export declare const ACQUIRE_OR_READ = "\n-- ACQUIRE_OR_READ\nlocal raw = redis.call('GET', KEYS[1])\nif not raw then\n  redis.call('SET', KEYS[1], ARGV[3], 'PX', ARGV[4])\n  return { 'ACQUIRED' }\nend\n\nlocal value = cjson.decode(raw)\nif value.fingerprint ~= ARGV[2] then\n  return { 'MISMATCH' }\nend\nif value.state == 'DONE' then\n  return { 'CACHED', raw }\nend\nreturn { 'IN_FLIGHT' }\n";
-export declare const COMMIT_IF_OWNER = "\n-- COMMIT_IF_OWNER\nlocal raw = redis.call('GET', KEYS[1])\nif not raw then return 0 end\nlocal value = cjson.decode(raw)\nif value.state == 'IN_FLIGHT' and value.token == ARGV[1] then\n  redis.call('SET', KEYS[1], ARGV[2], 'PX', ARGV[3])\n  return 1\nend\nreturn 0\n";
-export declare const RELEASE_IF_OWNER = "\n-- RELEASE_IF_OWNER\nlocal raw = redis.call('GET', KEYS[1])\nif not raw then return 0 end\nlocal value = cjson.decode(raw)\nif value.state == 'IN_FLIGHT' and value.token == ARGV[1] then\n  return redis.call('DEL', KEYS[1])\nend\nreturn 0\n";
+export declare const COMMIT_DONE_IF_LOCK_OWNER = "\n-- COMMIT_DONE_IF_LOCK_OWNER\nif redis.call('GET', KEYS[2]) ~= ARGV[1] then\n  return 0\nend\n\nlocal raw = redis.call('GET', KEYS[1])\nif not raw then return 0 end\nlocal value = cjson.decode(raw)\nif value.state == 'IN_FLIGHT' and value.token == ARGV[1] then\n  redis.call('SET', KEYS[1], ARGV[2], 'PX', ARGV[3])\n  return 1\nend\nreturn 0\n";
+export declare const CLEAR_IN_FLIGHT_IF_LOCK_OWNER = "\n-- CLEAR_IN_FLIGHT_IF_LOCK_OWNER\nif redis.call('GET', KEYS[2]) ~= ARGV[1] then\n  return 0\nend\n\nlocal raw = redis.call('GET', KEYS[1])\nif not raw then return 0 end\nlocal value = cjson.decode(raw)\nif value.state == 'IN_FLIGHT' and value.token == ARGV[1] then\n  return redis.call('DEL', KEYS[1])\nend\nreturn 0\n";

package/dist/scripts.js

@@ -1,22 +1,9 @@
-export const ACQUIRE_OR_READ = `
--- ACQUIRE_OR_READ
-local raw = redis.call('GET', KEYS[1])
-if not raw then
-  redis.call('SET', KEYS[1], ARGV[3], 'PX', ARGV[4])
-  return { 'ACQUIRED' }
+export const COMMIT_DONE_IF_LOCK_OWNER = `
+-- COMMIT_DONE_IF_LOCK_OWNER
+if redis.call('GET', KEYS[2]) ~= ARGV[1] then
+  return 0
 end
 
-local value = cjson.decode(raw)
-if value.fingerprint ~= ARGV[2] then
-  return { 'MISMATCH' }
-end
-if value.state == 'DONE' then
-  return { 'CACHED', raw }
-end
-return { 'IN_FLIGHT' }
-`;
-export const COMMIT_IF_OWNER = `
--- COMMIT_IF_OWNER
 local raw = redis.call('GET', KEYS[1])
 if not raw then return 0 end
 local value = cjson.decode(raw)
@@ -26,8 +13,12 @@ if value.state == 'IN_FLIGHT' and value.token == ARGV[1] then
 end
 return 0
 `;
-export const RELEASE_IF_OWNER = `
--- RELEASE_IF_OWNER
+export const CLEAR_IN_FLIGHT_IF_LOCK_OWNER = `
+-- CLEAR_IN_FLIGHT_IF_LOCK_OWNER
+if redis.call('GET', KEYS[2]) ~= ARGV[1] then
+  return 0
+end
+
 local raw = redis.call('GET', KEYS[1])
 if not raw then return 0 end
 local value = cjson.decode(raw)

package/dist/state.d.ts

@@ -0,0 +1,4 @@
+import type { IdempotencyResultCodec, IdempotencyState } from './types';
+export declare function parseState<T>(raw: string): IdempotencyState<T>;
+export declare function createInFlightState(token: string, fingerprint: string): IdempotencyState;
+export declare function createDoneState<T>(fingerprint: string, result: T, resultCodec: IdempotencyResultCodec<T> | undefined): IdempotencyState<T>;

package/dist/state.js

@@ -0,0 +1,20 @@
+import { encodeResult } from './result-codec.js';
+export function parseState(raw) {
+    return JSON.parse(raw);
+}
+export function createInFlightState(token, fingerprint) {
+    return {
+        state: 'IN_FLIGHT',
+        token,
+        fingerprint,
+        startedAt: Date.now(),
+    };
+}
+export function createDoneState(fingerprint, result, resultCodec) {
+    return {
+        state: 'DONE',
+        fingerprint,
+        data: encodeResult(result, resultCodec),
+        finishedAt: Date.now(),
+    };
+}

package/dist/store.d.ts

@@ -0,0 +1,22 @@
+import type { IdempotencyResultCodec, IdempotencyState, RedisLike } from './types';
+export type IdempotencyReadResult<T> = {
+    type: 'empty';
+} | {
+    type: 'cached';
+    data: T;
+} | {
+    type: 'mismatch';
+} | {
+    type: 'in-flight';
+    state: Extract<IdempotencyState<T>, {
+        state: 'IN_FLIGHT';
+    }>;
+};
+export declare class RedisIdempotencyStore {
+    private readonly redis;
+    constructor(redis: RedisLike);
+    read<T>(key: string, fingerprint: string, resultCodec: IdempotencyResultCodec<T> | undefined): Promise<IdempotencyReadResult<T>>;
+    markInFlight(key: string, token: string, fingerprint: string, lockTtl: number): Promise<void>;
+    commitDoneIfLockOwner<T>(key: string, lockKey: string, token: string, fingerprint: string, result: T, resultTtl: number, resultCodec: IdempotencyResultCodec<T> | undefined): Promise<boolean>;
+    clearInFlightIfLockOwner(key: string, lockKey: string, token: string): Promise<boolean>;
+}

package/dist/store.js

@@ -0,0 +1,33 @@
+import { decodeResult, assertStoredResult } from './result-codec.js';
+import { CLEAR_IN_FLIGHT_IF_LOCK_OWNER, COMMIT_DONE_IF_LOCK_OWNER } from './scripts.js';
+import { createDoneState, createInFlightState, parseState } from './state.js';
+export class RedisIdempotencyStore {
+    redis;
+    constructor(redis) {
+        this.redis = redis;
+    }
+    async read(key, fingerprint, resultCodec) {
+        const raw = await this.redis.get(key);
+        if (!raw)
+            return { type: 'empty' };
+        const state = parseState(raw);
+        if (state.fingerprint !== fingerprint)
+            return { type: 'mismatch' };
+        if (state.state === 'DONE') {
+            return { type: 'cached', data: decodeResult(assertStoredResult(state.data), resultCodec) };
+        }
+        return { type: 'in-flight', state };
+    }
+    async markInFlight(key, token, fingerprint, lockTtl) {
+        await this.redis.set(key, JSON.stringify(createInFlightState(token, fingerprint)), 'PX', lockTtl);
+    }
+    async commitDoneIfLockOwner(key, lockKey, token, fingerprint, result, resultTtl, resultCodec) {
+        const done = createDoneState(fingerprint, result, resultCodec);
+        const committed = await this.redis.eval(COMMIT_DONE_IF_LOCK_OWNER, 2, key, lockKey, token, JSON.stringify(done), resultTtl);
+        return committed === 1;
+    }
+    async clearInFlightIfLockOwner(key, lockKey, token) {
+        const cleared = await this.redis.eval(CLEAR_IN_FLIGHT_IF_LOCK_OWNER, 2, key, lockKey, token);
+        return cleared === 1;
+    }
+}

package/dist/types.d.ts

@@ -1,3 +1,4 @@
+import type { RedisLockLike } from '@hile/redis-lock';
 export type RedisEvalResult = unknown;
 export type JsonValue = string | number | boolean | null | JsonValue[] | {
     [key: string]: JsonValue;
@@ -11,11 +12,10 @@ export type StoredIdempotencyResult = {
     encoding: 'custom';
     value: string;
 };
-export interface RedisLike {
+export interface RedisLike extends RedisLockLike {
     get(key: string): Promise<string | null>;
     set(key: string, value: string, px: 'PX', ttl: number): Promise<unknown>;
     del(key: string): Promise<unknown>;
-    eval(script: string, numberOfKeys: number, key: string, ...args: Array<string | number>): Promise<RedisEvalResult>;
 }
 export interface IdempotencyResultCodec<T = unknown> {
     serialize(value: T): string;
@@ -31,7 +31,7 @@ export interface IdempotencyOptions<T = unknown> {
     maxPollInterval?: number;
     resultCodec?: IdempotencyResultCodec<T>;
 }
-export interface IdempotentMiddlewareOptions<TInput extends object = Record<string, unknown>> extends Omit<IdempotencyOptions, 'fingerprint'> {
+export interface IdempotentMiddlewareOptions<TInput extends object = Record<string, unknown>, TResult = unknown> extends Omit<IdempotencyOptions<TResult>, 'fingerprint'> {
     redis: RedisLike;
     key: (input: TInput) => string;
     fingerprint: string | ((input: TInput) => string);

package/dist/with-idempotency.js

@@ -1,213 +1,4 @@
-import { randomUUID } from 'node:crypto';
-import { IdempotencyConflictError, IdempotencyOwnershipLostError, IdempotencyPayloadMismatchError, IdempotencyRetryableError, IdempotencyTimeoutError, } from './errors.js';
-import { ACQUIRE_OR_READ, COMMIT_IF_OWNER, RELEASE_IF_OWNER } from './scripts.js';
-const sleep = (ms) => new Promise(resolve => setTimeout(resolve, ms));
-function assertPositiveInteger(value, name) {
-    if (!Number.isFinite(value) || value <= 0 || Math.trunc(value) !== value) {
-        throw new TypeError(`${name} must be a positive integer`);
-    }
-}
-function isPlainObject(value) {
-    if (typeof value !== 'object' || value === null)
-        return false;
-    const prototype = Object.getPrototypeOf(value);
-    return prototype === Object.prototype || prototype === null;
-}
-function resultSerializationError(path, reason) {
-    return new TypeError(`Idempotency result must be JSON-serializable at ${path}: ${reason}. Provide resultCodec for custom result types.`);
-}
-function toJsonValue(value, path = 'result', seen = new WeakSet()) {
-    if (value === null)
-        return null;
-    if (typeof value === 'string' || typeof value === 'boolean')
-        return value;
-    if (typeof value === 'number') {
-        if (!Number.isFinite(value))
-            throw resultSerializationError(path, 'non-finite numbers are not JSON values');
-        return value;
-    }
-    const type = typeof value;
-    if (type === 'undefined')
-        throw resultSerializationError(path, 'undefined is only supported as the top-level result');
-    if (type === 'bigint' || type === 'symbol' || type === 'function') {
-        throw resultSerializationError(path, `${type} is not a JSON value`);
-    }
-    if (typeof value !== 'object') {
-        throw resultSerializationError(path, `${type} is not a JSON value`);
-    }
-    if (seen.has(value)) {
-        throw resultSerializationError(path, 'circular references are not JSON values');
-    }
-    seen.add(value);
-    if (Array.isArray(value)) {
-        const array = [];
-        for (let i = 0; i < value.length; i += 1) {
-            if (!(i in value))
-                throw resultSerializationError(`${path}[${i}]`, 'sparse arrays are not JSON values');
-            array.push(toJsonValue(value[i], `${path}[${i}]`, seen));
-        }
-        seen.delete(value);
-        return array;
-    }
-    if (!isPlainObject(value)) {
-        seen.delete(value);
-        throw resultSerializationError(path, `${Object.prototype.toString.call(value)} is not a plain JSON object`);
-    }
-    const symbols = Object.getOwnPropertySymbols(value);
-    if (symbols.length > 0) {
-        seen.delete(value);
-        throw resultSerializationError(path, 'symbol keys are not JSON values');
-    }
-    const object = {};
-    for (const key of Object.keys(value)) {
-        object[key] = toJsonValue(value[key], `${path}.${key}`, seen);
-    }
-    seen.delete(value);
-    return object;
-}
-function encodeResult(value, codec) {
-    if (codec) {
-        const encoded = codec.serialize(value);
-        if (typeof encoded !== 'string') {
-            throw new TypeError('resultCodec.serialize must return a string');
-        }
-        return { encoding: 'custom', value: encoded };
-    }
-    if (value === undefined)
-        return { encoding: 'undefined' };
-    return { encoding: 'json', value: toJsonValue(value) };
-}
-function decodeResult(stored, codec) {
-    if (stored.encoding === 'undefined')
-        return undefined;
-    if (stored.encoding === 'json')
-        return stored.value;
-    if (stored.encoding === 'custom') {
-        if (!codec) {
-            throw new TypeError('Cached idempotency result requires resultCodec to deserialize');
-        }
-        return codec.deserialize(stored.value);
-    }
-    throw new Error('Invalid cached idempotency result');
-}
-function assertStoredResult(value) {
-    if (typeof value !== 'object' || value === null || !('encoding' in value)) {
-        throw new Error('Invalid cached idempotency result');
-    }
-    const stored = value;
-    if (stored.encoding === 'undefined')
-        return stored;
-    if (stored.encoding === 'json' && 'value' in stored)
-        return stored;
-    if (stored.encoding === 'custom' && typeof stored.value === 'string')
-        return stored;
-    throw new Error('Invalid cached idempotency result');
-}
-function normalizeEvalArray(value) {
-    if (!Array.isArray(value)) {
-        throw new Error('Invalid Redis idempotency script result');
-    }
-    return value;
-}
-function parseState(raw) {
-    return JSON.parse(raw);
-}
-async function acquireOrRead(redis, key, token, fingerprint, lockTtl, resultCodec) {
-    const inFlight = {
-        state: 'IN_FLIGHT',
-        token,
-        fingerprint,
-        startedAt: Date.now(),
-    };
-    const result = normalizeEvalArray(await redis.eval(ACQUIRE_OR_READ, 1, key, token, fingerprint, JSON.stringify(inFlight), lockTtl));
-    const status = result[0];
-    if (status === 'ACQUIRED')
-        return { type: 'acquired' };
-    if (status === 'MISMATCH')
-        return { type: 'mismatch' };
-    if (status === 'IN_FLIGHT')
-        return { type: 'in-flight' };
-    if (status === 'CACHED') {
-        const raw = result[1];
-        if (typeof raw !== 'string')
-            throw new Error('Invalid cached idempotency state');
-        const state = parseState(raw);
-        if (state.state !== 'DONE')
-            throw new Error('Invalid cached idempotency state');
-        return { type: 'cached', data: decodeResult(assertStoredResult(state.data), resultCodec) };
-    }
-    throw new Error(`Unknown idempotency script status: ${String(status)}`);
-}
-async function commitIfOwner(redis, key, token, fingerprint, result, resultTtl, resultCodec) {
-    const done = {
-        state: 'DONE',
-        fingerprint,
-        data: encodeResult(result, resultCodec),
-        finishedAt: Date.now(),
-    };
-    const committed = await redis.eval(COMMIT_IF_OWNER, 1, key, token, JSON.stringify(done), resultTtl);
-    return committed === 1;
-}
-async function releaseIfOwner(redis, key, token) {
-    await redis.eval(RELEASE_IF_OWNER, 1, key, token);
-}
-async function readState(redis, key) {
-    const raw = await redis.get(key);
-    if (!raw)
-        return null;
-    return parseState(raw);
-}
-async function waitForResult(redis, key, fingerprint, timeout, pollInterval, maxPollInterval, resultCodec) {
-    const deadline = Date.now() + timeout;
-    let delay = pollInterval;
-    while (Date.now() < deadline) {
-        const state = await readState(redis, key);
-        if (!state)
-            throw new IdempotencyRetryableError(key);
-        if (state.fingerprint !== fingerprint)
-            throw new IdempotencyPayloadMismatchError(key);
-        if (state.state === 'DONE')
-            return decodeResult(assertStoredResult(state.data), resultCodec);
-        await sleep(delay);
-        delay = Math.min(delay * 2, maxPollInterval);
-    }
-    throw new IdempotencyTimeoutError(key);
-}
+import { RedisIdempotency } from './idempotency.js';
 export async function withIdempotency(redis, key, fn, options) {
-    assertPositiveInteger(options.lockTtl, 'lockTtl');
-    assertPositiveInteger(options.resultTtl, 'resultTtl');
-    if (!options.fingerprint)
-        throw new TypeError('fingerprint is required');
-    const { lockTtl, resultTtl, fingerprint, wait = lockTtl, onConflict = 'wait', pollInterval = 20, maxPollInterval = 500, resultCodec, } = options;
-    assertPositiveInteger(wait, 'wait');
-    assertPositiveInteger(pollInterval, 'pollInterval');
-    assertPositiveInteger(maxPollInterval, 'maxPollInterval');
-    const token = randomUUID();
-    const acquired = await acquireOrRead(redis, key, token, fingerprint, lockTtl, resultCodec);
-    if (acquired.type === 'cached')
-        return acquired.data;
-    if (acquired.type === 'mismatch')
-        throw new IdempotencyPayloadMismatchError(key);
-    if (acquired.type === 'acquired') {
-        let result;
-        try {
-            result = await fn();
-        }
-        catch (err) {
-            try {
-                await releaseIfOwner(redis, key, token);
-            }
-            catch (releaseErr) {
-                throw new AggregateError([err, releaseErr], 'Idempotency operation failed and releasing the in-flight key also failed');
-            }
-            throw err;
-        }
-        const committed = await commitIfOwner(redis, key, token, fingerprint, result, resultTtl, resultCodec);
-        if (!committed)
-            throw new IdempotencyOwnershipLostError(key);
-        return result;
-    }
-    if (onConflict === 'reject')
-        throw new IdempotencyConflictError(key);
-    return waitForResult(redis, key, fingerprint, wait, pollInterval, maxPollInterval, resultCodec);
+    return new RedisIdempotency(redis).run(key, fn, options);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hile/redis-idempotency",
-  "version": "3.0.1",
+  "version": "3.0.2",
   "type": "module",
   "main": "./dist/index.js",
   "scripts": {
@@ -22,7 +22,8 @@
     "vitest": "^4.0.18"
   },
   "dependencies": {
-    "@hile/model": "^3.0.1"
+    "@hile/model": "^3.0.1",
+    "@hile/redis-lock": "^3.0.1"
   },
-  "gitHead": "ffc9f14ed2591075290c77c1bcc0afc67ecf1794"
+  "gitHead": "88f52fb95743f86761778776aff23631fcf9d821"
 }