{"id":45594,"library":"node-redisson","title":"node-redisson","description":"A Redis-based distributed lock for Node.js that mirrors Java Redisson's semantics, featuring automatic watchdog renewal and unlock notifications. Version 1.0.4 (as of early 2025) is the initial stable release; the package ships TypeScript types, requires Node >=16, and declares a peer dependency on TypeScript ^5.7.2. Unlike alternatives like node-redlock, node-redisson eliminates the need to manually estimate lock hold durations or implement renewal logic. It uses ioredis under the hood for Redis connectivity.","status":"active","version":"1.0.4","language":"javascript","source_language":"en","source_url":"https://github.com/smilecc/node-redisson","tags":["javascript","nodejs","redlock","distributed","lock","redis","redisson","typescript"],"install":[{"cmd":"npm install node-redisson","lang":"bash","label":"npm"},{"cmd":"yarn add node-redisson","lang":"bash","label":"yarn"},{"cmd":"pnpm add node-redisson","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Redis client for connecting to the Redis server","package":"ioredis","optional":false}],"imports":[{"note":"The package is ESM-only; CommonJS require() will fail. Use dynamic import() if needed.","wrong":"const Redisson = require('node-redisson')","symbol":"Redisson","correct":"import { Redisson } from 'node-redisson'"},{"note":"The lock class is named RedissonLock, not just Lock. Also exported as type Lock for TypeScript.","wrong":"import { Lock } from 'node-redisson'","symbol":"RedissonLock","correct":"import { RedissonLock } from 'node-redisson'"},{"note":"Lock is only a type, not a runtime value. Use type-only import for TypeScript.","wrong":"import { Lock } from 'node-redisson' (will get undefined at runtime)","symbol":"Lock (type)","correct":"import type { Lock } from 'node-redisson'"}],"quickstart":{"code":"import { Redisson } from 'node-redisson';\n\nconst redisson = new Redisson({\n  redis: {\n    options: {\n      host: '127.0.0.1',\n      port: 42800,\n    },\n  },\n});\n\nasync function main() {\n  const lock = redisson.getLock('Example:LockName');\n  await lock.lock();\n  try {\n    // critical section\n    console.log('Lock acquired');\n  } finally {\n    await lock.unlock();\n  }\n}\n\nmain().catch(console.error);","lang":"typescript","description":"Creates a Redisson instance, obtains a named lock, acquires it with auto-renewal, executes critical work, and releases the lock in a finally block."},"warnings":[{"fix":"Configure ioredis retry strategy with a maximum retry count or timeout in the Redisson options under redis.options.","message":"The 'lock' method may block indefinitely if the Redis server becomes unreachable because the default retry strategy in ioredis can cause infinite retries.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Upgrade Node.js to version 16 or later.","message":"Node.js versions below 16 are not supported. The package may fail to install or run on older Node.js versions.","severity":"deprecated","affected_versions":"<=15.x"},{"fix":"Ensure Redis server meets the minimum version requirement based on the chosen messaging method.","message":"When using PubSub messaging (default), Redis version must be >=3. Using Streams requires Redis >=5. Older Redis versions may silently fail or cause unexpected behavior.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Adjust the lock watchdog timeout via the 'lockWatchdogTimeout' option in Redisson config, or implement your own fallback logic.","message":"The default lock timeout is 30 seconds. If the watchdog fails to renew (e.g., network partition), the lock will be released automatically after that period, possibly causing race conditions.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Update instantiation to 'new Redisson({ redis: { options: { host, port } } })'.","message":"Version 1.0.0 introduced the constructor signature change from earlier pre-release versions. The 'redis' property is now required inside the options object.","severity":"breaking","affected_versions":"<1.0.0"}],"env_vars":null,"search_vec":"'1.0.4':26 '16':43 '2025':30 '5.7.2':51 'altern':53 'automat':19 'base':7 'connect':82 'declar':45 'depend':48 'distribut':8,86 'durat':69 'earli':29 'elimin':61 'estim':66 'featur':18 'hold':68 'hood':79 'implement':71 'initi':33 'ioredi':76 'java':14 'javascript':83 'like':54 'lock':9,67,87 'logic':73 'manual':65 'mirror':13 'need':63 'node':2,42,56,59 'node-redisson':1,58 'node-redlock':55 'node.js':11 'nodej':84 'notif':24 'packag':37 'peer':47 'redi':6,81,88 'redis-bas':5 'redisson':3,15,60,89 'redlock':57,85 'releas':35 'renew':21,72 'requir':41 'semant':17 'ship':38 'stabl':34 'type':40 'typescript':39,50,90 'unlik':52 'unlock':23 'use':75 'version':25 'watchdog':20","created_at":"2026-06-07T12:55:46.714430+00:00","updated_at":"2026-06-07T12:55:46.714430+00:00","problems":[{"fix":"Run 'pnpm add node-redisson ioredis' (or npm/yarn equivalent).","cause":"The package is not installed or not in the project's dependencies.","error":"Cannot find module 'node-redisson'"},{"fix":"Use 'import { Redisson } from 'node-redisson'' instead of require().","cause":"Trying to require() an ESM-only package.","error":"ERR_REQUIRE_ESM"},{"fix":"Ensure you pass an object with a 'redis' property: new Redisson({ redis: { options: { ... } } }).","cause":"The Redisson instance was not created correctly; likely missing the 'redis' config.","error":"TypeError: redisson.getLock is not a function"}],"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://smilecc.github.io/node-redisson/","github":"https://github.com/smilecc/node-redisson","docs":null,"changelog":null,"pypi":null,"npm":"node-redisson","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}}