Registry / storage / idempotency-redis

idempotency-redis

library1.5.1jsnpmunverified

idempotency-redis (v1.5.1) is a Node.js library that guarantees idempotent execution of operations using Redis for shared state and distributed locking. It ensures that for a given idempotency key, only one execution occurs; concurrent calls with the same key replay the cached result (including errors). Built on ioredis and using Redlock for distributed mutex, it differentiates from simple Redis-based idempotency by handling concurrent requests, caching failures, and providing custom error handling callbacks. Released as stable (since v1), with peer dependency ioredis 5.x.

storage

npm install idempotency-redis

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · IDEMPOTENCY-REDIS

idempotency-redis

storagejavascriptv1.5.1

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

IdempotentExecutor

✓ import { IdempotentExecutor } from 'idempotency-redis';

✗ import IdempotentExecutor from 'idempotency-redis';

This package exports named exports only; no default export.

IdempotentExecutorCriticalError

✓ import { IdempotentExecutorCriticalError } from 'idempotency-redis';

✗ // Not available as default or require destructure from different path

Exported error class, useful for catching critical failures.

IdempotentExecutor (CommonJS)

✓ const { IdempotentExecutor } = require('idempotency-redis');

✗ const IdempotentExecutor = require('idempotency-redis');

CommonJS users must destructure from the module; the module does not have a default export.

Shows creating an executor, running an idempotent operation with a key, and demonstrating that duplicate calls return the cached result instead of executing again.

import Redis from 'ioredis'; import { IdempotentExecutor } from 'idempotency-redis'; const redis = new Redis({ host: process.env.REDIS_HOST ?? 'localhost', port: Number(process.env.REDIS_PORT ?? 6379), }); const executor = new IdempotentExecutor(redis, { ttlMs: 300_000, // optional: expire results after 5 minutes }); // Idempotent operation const result = await executor.run('payment-txn-123', async () => { // e.g., process payment const response = await fetch('https://api.example.com/charge', { method: 'POST', body: JSON.stringify({ amount: 100 }), headers: { 'Content-Type': 'application/json' }, }); if (!response.ok) throw new Error('Charge failed'); return response.json(); }); console.log(result); // Duplicate call returns cached result const result2 = await executor.run('payment-txn-123', async () => { throw new Error('Should not be called'); }); console.log(result2); // same as above redis.quit();

Debug

Known issues

gotchaDo not use colons (:) in namespace or idempotencyKey values as they are used as delimiters in Redis keys.

fix

Replace colons with hyphens or underscores in namespace and key values.

affects: >=1.0.0

breakingNode.js version requirement: ^20.0.0 || ^22.0.0 || ^24.0.0. Older versions are not supported.

fix

Upgrade Node.js to one of the supported major versions.

affects: >=1.0.0

deprecatedNo deprecated features yet; the library is actively maintained.

fix

N/A

affects: >=1.0.0

gotchaErrors are cached and replayed by default. If you do not want errors to be cached, provide a shouldIgnoreError callback returning true for those errors.

fix

Pass shouldIgnoreError to executor constructor: new IdempotentExecutor(redis, { shouldIgnoreError: (err) => true })

affects: >=1.0.0

gotchaIf caching the final result fails, the executor throws an IdempotentExecutorCriticalError which may break idempotency. Ensure Redis is stable.

fix

Catch IdempotentExecutorCriticalError and handle appropriately (e.g., implement fallback).

affects: >=1.0.0

Errors

Common errors & fixes

Error [ERR_REQUIRE_ESM]: require() of ES Module /path/to/node_modules/idempotency-redis/src/index.ts from /path/to/your-file.js not supported.

The library is ESM-only (type: module). Using require() in a CommonJS file without dynamic import fails.

fix

Use dynamic import: const { IdempotentExecutor } = await import('idempotency-redis');

TypeError: IdempotentExecutor is not a constructor

Using default import instead of named import: import IdempotentExecutor from '...' leads to undefined.

fix

Use named import: import { IdempotentExecutor } from 'idempotency-redis';

Module not found: Can't resolve 'ioredis'

ioredis is a peer dependency not installed.

fix

Run: npm install ioredis

Upgrade

Version history

1.5.1latest on npm

Audit

Dependencies

ioredisrequiredRequired as peer dependency; provides the Redis client used by the executor.

Agent activity

23 hits · last 30 days

node

OpenAI (training)

Resources

githubgit://github.com/foreverest/idempotency-redis ↗

packageidempotency-redis ↗

homepagehttps://github.com/foreverest/idempotency-redis#readme ↗