@hile/redis-idempotency 2.1.2

package/README.md

@@ -0,0 +1,224 @@
+# @hile/redis-idempotency
+
+Redis-backed idempotency primitives for Hile services. The package name names the storage backend; the API names stay storage-neutral:
+
+- `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
+
+## 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:
+
+```
+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.
+
+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.
+
+## Install
+
+```bash
+pnpm add @hile/redis-idempotency @hile/ioredis
+```
+
+The package accepts any Redis client matching `RedisLike`. In Hile apps, the usual client comes from `@hile/ioredis`:
+
+```typescript
+import { loadService } from '@hile/core'
+import redisService from '@hile/ioredis'
+
+const redis = await loadService(redisService)
+```
+
+## Quick Start
+
+```typescript
+import { loadService } from '@hile/core'
+import redisService from '@hile/ioredis'
+import { stableHash, withIdempotency } from '@hile/redis-idempotency'
+
+const redis = await loadService(redisService)
+
+async function debitWallet(input: {
+  tenantId: string
+  requestId: string
+  amount: number
+}) {
+  return withIdempotency(
+    redis,
+    `idem:prod:wallet:debit:${input.tenantId}:${input.requestId}`,
+    async () => {
+      // Put the side-effecting operation here.
+      return performDebit(input)
+    },
+    {
+      lockTtl: 60_000,
+      resultTtl: 24 * 60 * 60 * 1000,
+      fingerprint: stableHash(input),
+    },
+  )
+}
+```
+
+What happens:
+
+1. First caller writes `IN_FLIGHT` and runs `performDebit`.
+2. Concurrent callers with the same key and fingerprint wait for `DONE`.
+3. Later callers with the same key and fingerprint receive the cached result.
+4. Same key with a different fingerprint throws `IdempotencyPayloadMismatchError`.
+5. If `performDebit` throws, the `IN_FLIGHT` key is released so a retry can run.
+
+## API
+
+### withIdempotency(redis, key, fn, options)
+
+```typescript
+function withIdempotency<T>(
+  redis: RedisLike,
+  key: string,
+  fn: () => Promise<T>,
+  options: IdempotencyOptions<T>,
+): Promise<T>
+```
+
+`key` must already include the full namespace. A safe format is:
+
+```
+idem:{env}:{service}:{operation}:{tenantId}:{businessId}
+```
+
+Do not use transport message IDs as business keys. Prefer request IDs, order IDs, provider transaction IDs, or ledger IDs.
+
+#### IdempotencyOptions
+
+| Option | Required | Meaning |
+|---|---:|---|
+| `lockTtl` | yes | How long the `IN_FLIGHT` owner may run before Redis expires the key. Must exceed normal business execution time. |
+| `resultTtl` | yes | How long the successful `DONE` result is cached. Must cover the retry/redelivery window. |
+| `fingerprint` | yes | Stable hash of the payload. Prevents reusing one key for different requests. |
+| `wait` | no | How long a concurrent caller waits for `DONE`. Defaults to `lockTtl`. |
+| `onConflict` | no | `'wait'` or `'reject'`. Defaults to `'wait'`. |
+| `pollInterval` | no | Initial polling delay in ms. Defaults to `20`. |
+| `maxPollInterval` | no | Max polling delay in ms. Defaults to `500`. |
+| `resultCodec` | no | Custom result serializer/deserializer for non-JSON return values. |
+
+#### Result serialization
+
+By default, cached results must be plain JSON values: `null`, strings, finite numbers, booleans, arrays, and plain objects. The package rejects `Date`, `Map`, `Set`, `BigInt`, functions, symbols, circular references, sparse arrays, class instances, and nested `undefined` values instead of caching a lossy value.
+
+Use `resultCodec` when the function returns richer types:
+
+```typescript
+const resultCodec = {
+  serialize: (value: { createdAt: Date }) => JSON.stringify({
+    createdAt: value.createdAt.toISOString(),
+  }),
+  deserialize: (raw: string) => {
+    const value = JSON.parse(raw) as { createdAt: string }
+    return { createdAt: new Date(value.createdAt) }
+  },
+}
+
+await withIdempotency(redis, key, createRecord, {
+  lockTtl: 60_000,
+  resultTtl: 86_400_000,
+  fingerprint,
+  resultCodec,
+})
+```
+
+### stableHash(value)
+
+```typescript
+const fingerprint = stableHash({
+  method: 'POST',
+  path: '/-/wallet/debit',
+  tenantId,
+  body,
+})
+```
+
+`stableHash` sorts plain object keys before hashing, so `{ a: 1, b: 2 }` and `{ b: 2, a: 1 }` produce the same fingerprint. It rejects unsupported object types, sparse arrays, and circular references instead of hashing them as `{}`; build fingerprints from plain request DTOs.
+
+### 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`.
+
+```typescript
+import { Pipeline, PipelineContext } from '@hile/model'
+import { idempotent, stableHash } from '@hile/redis-idempotency'
+
+const pipeline = new Pipeline<{ tenantId: string; requestId: string }>()
+pipeline.use(idempotent({
+  redis,
+  key: (input) => `idem:prod:wallet:debit:${input.tenantId}:${input.requestId}`,
+  fingerprint: stableHash,
+  lockTtl: 60_000,
+  resultTtl: 86_400_000,
+}))
+pipeline.use(async (ctx) => {
+  ctx.state.result = await performDebit(ctx.args)
+})
+
+const ctx = new PipelineContext({ tenantId: 't1', requestId: 'r1' })
+await pipeline.dispatch(ctx)
+console.log(ctx.state.result)
+```
+
+Current `@hile/model@2.1.1` `defineModel()` returns a local `result` variable from its terminal middleware. That means a short-circuited middleware cannot make `model.handler()` return `ctx.state.result`. Until `@hile/model` returns `ctx.state.result`, prefer function-level `withIdempotency()` inside `main()`:
+
+```typescript
+const debitModel = defineModel({
+  services: [redisService],
+  async main([redis], input: DebitInput) {
+    return withIdempotency(
+      redis,
+      `idem:prod:wallet:debit:${input.tenantId}:${input.requestId}`,
+      () => performDebit(input),
+      {
+        lockTtl: 60_000,
+        resultTtl: 86_400_000,
+        fingerprint: stableHash(input),
+      },
+    )
+  },
+})
+```
+
+## Error Types
+
+| Error | When it happens | Recommended handling |
+|---|---|---|
+| `IdempotencyConflictError` | Same key is already `IN_FLIGHT` and `onConflict: 'reject'` | Return 409 or let queue retry later |
+| `IdempotencyTimeoutError` | Waited for `DONE` longer than `wait` | Retry with the same key |
+| `IdempotencyPayloadMismatchError` | Same key was reused with a different fingerprint | Treat as caller bug or replay risk |
+| `IdempotencyOwnershipLostError` | Owner finished after losing the Redis key | Investigate `lockTtl`; business side effect may have run |
+| `IdempotencyRetryableError` | In-flight key disappeared before `DONE` was visible | Retry with the same key |
+| `AggregateError` | The wrapped function failed and releasing the `IN_FLIGHT` key also failed | Inspect both `errors`; the key may remain until `lockTtl` |
+
+## TTL Guidance
+
+| Scenario | `lockTtl` | `resultTtl` |
+|---|---:|---:|
+| HTTP form submit | max handler time + margin | 5-30 minutes |
+| Internal `Application.call()` write | max handler time + margin | max retry window |
+| 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.
+
+## Testing
+
+```bash
+pnpm --filter @hile/redis-idempotency test
+pnpm --filter @hile/redis-idempotency build
+```
+
+## License
+
+MIT

package/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: redis-idempotency
+description: Use when implementing duplicate-execution protection for Redis-backed Hile workflows, retries, queue consumers, message handlers, or write models.
+---
+
+# Redis Idempotency
+
+Use `@hile/redis-idempotency` when a write operation may be retried or redelivered and must not run side effects twice.
+
+## Core Rule
+
+Package name names the backend; API names stay generic:
+
+```typescript
+import { stableHash, withIdempotency } from '@hile/redis-idempotency'
+```
+
+Wrap the smallest side-effecting function:
+
+```typescript
+return withIdempotency(
+  redis,
+  `idem:prod:wallet:debit:${tenantId}:${requestId}`,
+  () => debitWallet(input),
+  {
+    lockTtl: 60_000,
+    resultTtl: 86_400_000,
+    fingerprint: stableHash(input),
+  },
+)
+```
+
+## Key Design
+
+| Do | Avoid |
+|---|---|
+| Use business keys: `tenantId + requestId`, `orderId`, `providerTxnId` | Transport IDs, random UUID per retry |
+| Include environment/service/operation prefix | Global keys like `idem:${id}` |
+| Bind payload with `fingerprint` | Same key for different bodies |
+
+## Serialization Boundaries
+
+Build `stableHash()` fingerprints from plain DTOs. It rejects unsupported object types, sparse arrays, and circular references instead of silently treating `Map`, `Set`, or `RegExp` as `{}`.
+
+Default cached results must be plain JSON values. If the wrapped function returns `Date`, `BigInt`, class instances, `Map` / `Set`, or any other rich type, pass `resultCodec` so cache hits deserialize to the same shape as the first call.
+
+## Current Model Guidance
+
+Prefer function-level `withIdempotency()` inside `defineModel().main`. Current `@hile/model@2.1.1` does not return `ctx.state.result` on middleware short-circuit, so `idempotent()` is safe for raw `Pipeline` usage and future model versions that return `ctx.state.result`, but not for current `defineModel` cache hits.
+
+## Failure Policy
+
+High-risk writes should fail closed when Redis is unavailable. Do not bypass idempotency for money, quota, recharge, order creation, or notifications unless there is a stronger business-level unique constraint.
+
+If the business function fails and releasing the `IN_FLIGHT` key also fails, `withIdempotency()` throws `AggregateError`; inspect both `errors` entries and assume the key may remain until `lockTtl`.
+
+## Final Wall
+
+Redis idempotency is not exactly-once. Keep DB unique constraints, transaction records, outbox rows, or provider idempotency keys for irreversible side effects.

package/dist/errors.d.ts

@@ -0,0 +1,19 @@
+export declare class IdempotencyError extends Error {
+    readonly key: string;
+    constructor(message: string, key: string);
+}
+export declare class IdempotencyConflictError extends IdempotencyError {
+    constructor(key: string);
+}
+export declare class IdempotencyTimeoutError extends IdempotencyError {
+    constructor(key: string);
+}
+export declare class IdempotencyPayloadMismatchError extends IdempotencyError {
+    constructor(key: string);
+}
+export declare class IdempotencyOwnershipLostError extends IdempotencyError {
+    constructor(key: string);
+}
+export declare class IdempotencyRetryableError extends IdempotencyError {
+    constructor(key: string);
+}

package/dist/errors.js

@@ -0,0 +1,33 @@
+export class IdempotencyError extends Error {
+    key;
+    constructor(message, key) {
+        super(message);
+        this.key = key;
+        this.name = new.target.name;
+    }
+}
+export class IdempotencyConflictError extends IdempotencyError {
+    constructor(key) {
+        super(`Idempotency key is already in flight: ${key}`, key);
+    }
+}
+export class IdempotencyTimeoutError extends IdempotencyError {
+    constructor(key) {
+        super(`Timed out waiting for idempotency result: ${key}`, key);
+    }
+}
+export class IdempotencyPayloadMismatchError extends IdempotencyError {
+    constructor(key) {
+        super(`Idempotency key was reused with a different payload: ${key}`, key);
+    }
+}
+export class IdempotencyOwnershipLostError extends IdempotencyError {
+    constructor(key) {
+        super(`Idempotency owner lost the in-flight key before commit: ${key}`, key);
+    }
+}
+export class IdempotencyRetryableError extends IdempotencyError {
+    constructor(key) {
+        super(`Idempotency in-flight key disappeared before a result was available: ${key}`, key);
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { IdempotencyConflictError, IdempotencyError, IdempotencyOwnershipLostError, IdempotencyPayloadMismatchError, IdempotencyRetryableError, IdempotencyTimeoutError, } from './errors.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';

package/dist/index.js

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

package/dist/middleware.d.ts

@@ -0,0 +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>;

package/dist/middleware.js

@@ -0,0 +1,21 @@
+import { withIdempotency } from './with-idempotency.js';
+function resolveFingerprint(fingerprint, input) {
+    return typeof fingerprint === 'function' ? fingerprint(input) : fingerprint;
+}
+export function idempotent(options) {
+    return async (ctx, next) => {
+        const result = await withIdempotency(options.redis, options.key(ctx.args), async () => {
+            await next();
+            return ctx.state.result;
+        }, {
+            lockTtl: options.lockTtl,
+            resultTtl: options.resultTtl,
+            wait: options.wait,
+            onConflict: options.onConflict,
+            pollInterval: options.pollInterval,
+            maxPollInterval: options.maxPollInterval,
+            fingerprint: resolveFingerprint(options.fingerprint, ctx.args),
+        });
+        ctx.state.result = result;
+    };
+}

package/dist/scripts.d.ts

@@ -0,0 +1,3 @@
+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";

package/dist/scripts.js

@@ -0,0 +1,38 @@
+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' }
+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)
+if value.state == 'IN_FLIGHT' and value.token == ARGV[1] then
+  redis.call('SET', KEYS[1], ARGV[2], 'PX', ARGV[3])
+  return 1
+end
+return 0
+`;
+export const RELEASE_IF_OWNER = `
+-- RELEASE_IF_OWNER
+local raw = redis.call('GET', KEYS[1])
+if not raw then return 0 end
+local value = cjson.decode(raw)
+if value.state == 'IN_FLIGHT' and value.token == ARGV[1] then
+  return redis.call('DEL', KEYS[1])
+end
+return 0
+`;

package/dist/stable-hash.d.ts

@@ -0,0 +1 @@
+export declare function stableHash(value: unknown): string;

package/dist/stable-hash.js

@@ -0,0 +1,70 @@
+import { createHash } from 'node:crypto';
+function isPlainObject(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+function stableStringify(value, seen = new WeakSet()) {
+    if (value === undefined)
+        return 'undefined';
+    if (value === null)
+        return 'null';
+    const type = typeof value;
+    if (type === 'string')
+        return `string:${JSON.stringify(value)}`;
+    if (type === 'number') {
+        if (Number.isNaN(value))
+            return 'number:NaN';
+        if (Object.is(value, -0))
+            return 'number:-0';
+        return `number:${String(value)}`;
+    }
+    if (type === 'boolean')
+        return `boolean:${String(value)}`;
+    if (type === 'bigint')
+        return `bigint:${String(value)}`;
+    if (type === 'symbol' || type === 'function') {
+        throw new TypeError(`stableHash does not support ${type} values`);
+    }
+    if (typeof value !== 'object') {
+        return `${type}:${String(value)}`;
+    }
+    if (seen.has(value)) {
+        throw new TypeError('stableHash does not support circular values');
+    }
+    seen.add(value);
+    if (value instanceof Date) {
+        if (Number.isNaN(value.getTime()))
+            throw new TypeError('stableHash does not support invalid Date values');
+        seen.delete(value);
+        return `date:${value.toISOString()}`;
+    }
+    if (Buffer.isBuffer(value)) {
+        seen.delete(value);
+        return `buffer:${value.toString('base64')}`;
+    }
+    if (Array.isArray(value)) {
+        const items = [];
+        for (let i = 0; i < value.length; i += 1) {
+            if (!(i in value))
+                throw new TypeError('stableHash does not support sparse arrays');
+            items.push(stableStringify(value[i], seen));
+        }
+        const result = `array:[${items.join(',')}]`;
+        seen.delete(value);
+        return result;
+    }
+    if (!isPlainObject(value)) {
+        seen.delete(value);
+        throw new TypeError(`stableHash does not support ${Object.prototype.toString.call(value)} values`);
+    }
+    const object = value;
+    const keys = Object.keys(object).sort();
+    const result = `object:{${keys.map(key => `${JSON.stringify(key)}:${stableStringify(object[key], seen)}`).join(',')}}`;
+    seen.delete(value);
+    return result;
+}
+export function stableHash(value) {
+    return createHash('sha256').update(stableStringify(value)).digest('hex');
+}

package/dist/types.d.ts

@@ -0,0 +1,49 @@
+export type RedisEvalResult = unknown;
+export type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export type StoredIdempotencyResult = {
+    encoding: 'undefined';
+} | {
+    encoding: 'json';
+    value: JsonValue;
+} | {
+    encoding: 'custom';
+    value: string;
+};
+export interface RedisLike {
+    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;
+    deserialize(value: string): T;
+}
+export interface IdempotencyOptions<T = unknown> {
+    lockTtl: number;
+    resultTtl: number;
+    fingerprint: string;
+    wait?: number;
+    onConflict?: 'wait' | 'reject';
+    pollInterval?: number;
+    maxPollInterval?: number;
+    resultCodec?: IdempotencyResultCodec<T>;
+}
+export interface IdempotentMiddlewareOptions<TInput extends object = Record<string, unknown>> extends Omit<IdempotencyOptions, 'fingerprint'> {
+    redis: RedisLike;
+    key: (input: TInput) => string;
+    fingerprint: string | ((input: TInput) => string);
+}
+export type IdempotencyState<T = unknown> = {
+    state: 'IN_FLIGHT';
+    token: string;
+    fingerprint: string;
+    startedAt: number;
+} | {
+    state: 'DONE';
+    fingerprint: string;
+    data: StoredIdempotencyResult;
+    finishedAt: number;
+};

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/with-idempotency.d.ts

@@ -0,0 +1,2 @@
+import type { IdempotencyOptions, RedisLike } from './types';
+export declare function withIdempotency<T>(redis: RedisLike, key: string, fn: () => Promise<T>, options: IdempotencyOptions<T>): Promise<T>;

package/dist/with-idempotency.js

@@ -0,0 +1,213 @@
+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);
+}
+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);
+}

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@hile/redis-idempotency",
+  "version": "2.1.2",
+  "type": "module",
+  "main": "./dist/index.js",
+  "scripts": {
+    "build": "tsc -b && fix-esm-import-path --preserve-import-type ./dist",
+    "dev": "tsc -b --watch",
+    "test": "vitest run"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "SKILL.md"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "fix-esm-import-path": "^1.10.3",
+    "vitest": "^4.0.18"
+  },
+  "dependencies": {
+    "@hile/model": "^2.1.1"
+  },
+  "gitHead": "93da114ef293e48682e7df94d89418dfbf9a0226"
+}