redlock-universal

library0.8.4jsnpmunverified

A production-ready distributed locking library for Redis and Valkey supporting all three major clients: node-redis, ioredis, and Valkey GLIDE. Version 0.8.4, stable and actively maintained. It uses the Redlock algorithm for fault-tolerant locks with automatic lock extension and cleanup. Key differentiator: universal client support while maintaining sub-millisecond performance (0.377ms latency, comparable to dedicated libraries). Includes TypeScript types, monitoring hooks, and optional LockManager for multi-node setups.

database devops

npm install redlock-universal

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · REDLOCK-UNIVERSAL

redlock-universal

databasejavascriptv0.8.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.

createLock

✓ import { createLock } from 'redlock-universal'

✗ const createLock = require('redlock-universal')

ESM-only since v0.8.0. Top-level default export does not exist.

IoredisAdapter

✓ import { IoredisAdapter } from 'redlock-universal'

✗ import { IoRedisAdapter } from 'redlock-universal'

Note the capitalization: 'IoredisAdapter' not 'IoRedisAdapter'. Case-sensitive.

NodeRedisAdapter

✓ import { NodeRedisAdapter } from 'redlock-universal'

✗ import { RedisAdapter } from 'redlock-universal'

Named 'NodeRedisAdapter' to avoid confusion with the 'redis' npm package.

LockManager

✓ import { LockManager } from 'redlock-universal'

Requires at least one node defined; default export unavailable.

Shows how to acquire and automatically manage a distributed lock using ioredis with auto-extension.

import { createLock, IoredisAdapter } from 'redlock-universal'; import Redis from 'ioredis'; const lock = createLock({ adapter: new IoredisAdapter(new Redis()), key: 'my-resource', ttl: 30000, }); await lock.using(async () => { // Critical section - lock auto-extends and releases console.log('Lock acquired'); });

Debug

Known issues

breakingESM-only since v0.8.0. CommonJS require() will fail.

fix

Use import syntax or dynamic import().

affects: >=0.8.0

breakingNode.js engine requirement was raised to >=22.0.0 in v0.8.0.

fix

Upgrade Node.js to 22.0.0 or later.

affects: >=0.8.0

deprecatedThe 'monitor' option is deprecated in v0.8.0. Use 'monitoring' instead.

fix

Replace 'monitor' with 'monitoring' in configuration.

affects: >=0.8.0

gotchaLockManager.acquireLock requires at least one node configured. For single-instance use, use createLock.

fix

Use createLock for a single Redis/Valkey instance.

affects: >=0.8.0

gotchaIoredisAdapter constructor expects an ioredis-compatible instance, not a connection string.

fix

Pass new Redis() or RedisCluster instance.

affects: >=0.8.0

Errors

Common errors & fixes

Error [ERR_REQUIRE_ESM]: require() of ES Module not supported.

Using CommonJS require() on an ESM-only package.

fix

Switch to import syntax or use dynamic import() in CJS context.

TypeError: adapter is not a constructor

Adapter imported incorrectly or not instantiated.

fix

Ensure adapter is correctly imported and instantiated: new IoredisAdapter(new Redis())

Error: At least one node is required

LockManager created without any nodes.

fix

Pass an array of adapters: new LockManager({ nodes: [adapter], defaultTTL: 30000 })

TypeError: Cannot read properties of undefined (reading 'using')

createLock returns undefined if configuration is invalid.

fix

Check that key and adapter are provided and valid.

Upgrade

Version history

0.8.4latest on npm

Audit

Dependencies

@valkey/valkey-glideoptionalOptional peer: needed only if using Valkey GLIDE adapter

ioredisoptionalOptional peer: needed only if using ioredis adapter

redisoptionalOptional peer: needed only if using node-redis adapter

Agent activity

3 hits · last 30 days

node