node-redisson

library1.0.4jsnpmunverified

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.

storage

npm install node-redisson

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · NODE-REDISSON

node-redisson

storagejavascriptv1.0.4

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.

Redisson

✓ import { Redisson } from 'node-redisson'

✗ const Redisson = require('node-redisson')

The package is ESM-only; CommonJS require() will fail. Use dynamic import() if needed.

RedissonLock

✓ import { RedissonLock } from 'node-redisson'

✗ import { Lock } from 'node-redisson'

The lock class is named RedissonLock, not just Lock. Also exported as type Lock for TypeScript.

Lock (type)

✓ import type { Lock } from 'node-redisson'

✗ import { Lock } from 'node-redisson' (will get undefined at runtime)

Lock is only a type, not a runtime value. Use type-only import for TypeScript.

Creates a Redisson instance, obtains a named lock, acquires it with auto-renewal, executes critical work, and releases the lock in a finally block.

import { Redisson } from 'node-redisson'; const redisson = new Redisson({ redis: { options: { host: '127.0.0.1', port: 42800, }, }, }); async function main() { const lock = redisson.getLock('Example:LockName'); await lock.lock(); try { // critical section console.log('Lock acquired'); } finally { await lock.unlock(); } } main().catch(console.error);

Debug

Known issues

gotchaThe 'lock' method may block indefinitely if the Redis server becomes unreachable because the default retry strategy in ioredis can cause infinite retries.

fix

Configure ioredis retry strategy with a maximum retry count or timeout in the Redisson options under redis.options.

affects: >=1.0.0

deprecatedNode.js versions below 16 are not supported. The package may fail to install or run on older Node.js versions.

fix

Upgrade Node.js to version 16 or later.

affects: <=15.x

gotchaWhen using PubSub messaging (default), Redis version must be >=3. Using Streams requires Redis >=5. Older Redis versions may silently fail or cause unexpected behavior.

fix

Ensure Redis server meets the minimum version requirement based on the chosen messaging method.

affects: >=1.0.0

gotchaThe 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.

fix

Adjust the lock watchdog timeout via the 'lockWatchdogTimeout' option in Redisson config, or implement your own fallback logic.

affects: >=1.0.0

breakingVersion 1.0.0 introduced the constructor signature change from earlier pre-release versions. The 'redis' property is now required inside the options object.

fix

Update instantiation to 'new Redisson({ redis: { options: { host, port } } })'.

affects: <1.0.0

Errors

Common errors & fixes

Cannot find module 'node-redisson'

The package is not installed or not in the project's dependencies.

fix

Run 'pnpm add node-redisson ioredis' (or npm/yarn equivalent).

ERR_REQUIRE_ESM

Trying to require() an ESM-only package.

fix

Use 'import { Redisson } from 'node-redisson'' instead of require().

TypeError: redisson.getLock is not a function

The Redisson instance was not created correctly; likely missing the 'redis' config.

fix

Ensure you pass an object with a 'redis' property: new Redisson({ redis: { options: { ... } } }).

Upgrade

Version history

1.0.4latest on npm

Audit

Dependencies

ioredisrequiredRedis client for connecting to the Redis server

Agent activity

24 hits · last 30 days

node

Amazon

Resources

githubhttps://github.com/smilecc/node-redisson ↗

packagenode-redisson ↗

homepagehttps://smilecc.github.io/node-redisson/ ↗