{"id":45130,"library":"idempotency-redis","title":"idempotency-redis","description":"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.","status":"active","version":"1.5.1","language":"javascript","source_language":"en","source_url":"git://github.com/foreverest/idempotency-redis","tags":["javascript","idempotency","redis","redlock","ioredis","typescript"],"install":[{"cmd":"npm install idempotency-redis","lang":"bash","label":"npm"},{"cmd":"yarn add idempotency-redis","lang":"bash","label":"yarn"},{"cmd":"pnpm add idempotency-redis","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required as peer dependency; provides the Redis client used by the executor.","package":"ioredis","optional":false}],"imports":[{"note":"This package exports named exports only; no default export.","wrong":"import IdempotentExecutor from 'idempotency-redis';","symbol":"IdempotentExecutor","correct":"import { IdempotentExecutor } from 'idempotency-redis';"},{"note":"Exported error class, useful for catching critical failures.","wrong":"// Not available as default or require destructure from different path","symbol":"IdempotentExecutorCriticalError","correct":"import { IdempotentExecutorCriticalError } from 'idempotency-redis';"},{"note":"CommonJS users must destructure from the module; the module does not have a default export.","wrong":"const IdempotentExecutor = require('idempotency-redis');","symbol":"IdempotentExecutor (CommonJS)","correct":"const { IdempotentExecutor } = require('idempotency-redis');"}],"quickstart":{"code":"import Redis from 'ioredis';\nimport { IdempotentExecutor } from 'idempotency-redis';\n\nconst redis = new Redis({\n  host: process.env.REDIS_HOST ?? 'localhost',\n  port: Number(process.env.REDIS_PORT ?? 6379),\n});\n\nconst executor = new IdempotentExecutor(redis, {\n  ttlMs: 300_000, // optional: expire results after 5 minutes\n});\n\n// Idempotent operation\nconst result = await executor.run('payment-txn-123', async () => {\n  // e.g., process payment\n  const response = await fetch('https://api.example.com/charge', {\n    method: 'POST',\n    body: JSON.stringify({ amount: 100 }),\n    headers: { 'Content-Type': 'application/json' },\n  });\n  if (!response.ok) throw new Error('Charge failed');\n  return response.json();\n});\n\nconsole.log(result);\n\n// Duplicate call returns cached result\nconst result2 = await executor.run('payment-txn-123', async () => {\n  throw new Error('Should not be called');\n});\nconsole.log(result2); // same as above\n\nredis.quit();","lang":"typescript","description":"Shows creating an executor, running an idempotent operation with a key, and demonstrating that duplicate calls return the cached result instead of executing again."},"warnings":[{"fix":"Replace colons with hyphens or underscores in namespace and key values.","message":"Do not use colons (:) in namespace or idempotencyKey values as they are used as delimiters in Redis keys.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Upgrade Node.js to one of the supported major versions.","message":"Node.js version requirement: ^20.0.0 || ^22.0.0 || ^24.0.0. Older versions are not supported.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"N/A","message":"No deprecated features yet; the library is actively maintained.","severity":"deprecated","affected_versions":">=1.0.0"},{"fix":"Pass shouldIgnoreError to executor constructor: new IdempotentExecutor(redis, { shouldIgnoreError: (err) => true })","message":"Errors are cached and replayed by default. If you do not want errors to be cached, provide a shouldIgnoreError callback returning true for those errors.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Catch IdempotentExecutorCriticalError and handle appropriately (e.g., implement fallback).","message":"If caching the final result fails, the executor throws an IdempotentExecutorCriticalError which may break idempotency. Ensure Redis is stable.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"search_vec":"'5':88 'base':65 'built':50 'cach':46,71 'call':39 'callback':78 'concurr':38,69 'custom':75 'depend':86 'differenti':60 'distribut':24,57 'ensur':27 'error':49,76 'execut':15,36 'failur':72 'given':31 'guarante':13 'handl':68,77 'idempot':2,5,14,32,66,91 'idempotency-redi':1,4 'includ':48 'ioredi':52,87,94 'javascript':90 'key':33,43 'librari':11 'lock':25 'mutex':58 'node.js':10 'occur':37 'one':35 'oper':17 'peer':85 'provid':74 'redi':3,6,19,64,92 'redis-bas':63 'redlock':55,93 'releas':79 'replay':44 'request':70 'result':47 'share':21 'simpl':62 'sinc':82 'stabl':81 'state':22 'typescript':95 'use':18,54 'v1':83 'v1.5.1':7 'x':89","created_at":"2026-06-07T12:53:30.953193+00:00","updated_at":"2026-06-07T12:53:30.953193+00:00","problems":[{"fix":"Use dynamic import: const { IdempotentExecutor } = await import('idempotency-redis');","cause":"The library is ESM-only (type: module). Using require() in a CommonJS file without dynamic import fails.","error":"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."},{"fix":"Use named import: import { IdempotentExecutor } from 'idempotency-redis';","cause":"Using default import instead of named import: import IdempotentExecutor from '...' leads to undefined.","error":"TypeError: IdempotentExecutor is not a constructor"},{"fix":"Run: npm install ioredis","cause":"ioredis is a peer dependency not installed.","error":"Module not found: Can't resolve 'ioredis'"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null,"type":"library","homepage":"https://github.com/foreverest/idempotency-redis#readme","github":"git://github.com/foreverest/idempotency-redis","docs":null,"changelog":null,"pypi":null,"npm":"idempotency-redis","openapi_spec":null,"status_page":null,"smithery":null,"categories":["storage"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-07","next_check":"2026-09-05","install_tag":null}}