redlock2

library5.0.0-beta.3jsnpmunverified

A distributed lock implementation for Redis based on the Redlock algorithm. The current stable version is 4.x (note: 5.0.0-beta.3 is prerelease). It provides strong locking guarantees for both single-redis and multi-redis environments with fault tolerance. Key differentiators include built-in lock extension via the `using` API with abort signals, automatic retry with configurable jitter, and TypeScript types. Ships as ESM with CommonJS fallback since version 5.

database

npm install redlock2

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · REDLOCK2

redlock2

databasejavascriptv5.0.0-beta.3

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.

Redlock

✓ import Redlock from 'redlock'

✗ const Redlock = require('redlock')

Default import for ESM. For CommonJS projects, use Redlock = require('redlock').default or ensure your project handles ESM interop.

Lock

✓ import type { Lock } from 'redlock'

✗ import { Lock } from 'redlock'

Lock is a type, not a value. It is not exported as a runtime construct.

ResourceLockedError

✓ import { ResourceLockedError } from 'redlock'

Named export for error types. Only available in ESM imports; CommonJS users should use require('redlock').ResourceLockedError.

ExecutionError

✓ import { ExecutionError } from 'redlock'

✗ import ExecutionError from 'redlock'

ExecutionError is a named export, not the default.

Shows basic usage of Redlock with ioredis, including lock acquisition via the `using` method.

import Client from 'ioredis'; import Redlock from 'redlock'; const redis = new Client({ host: 'localhost' }); const redlock = new Redlock([redis], { retryCount: 10, retryDelay: 200, retryJitter: 200 }); await redlock.using(['my-resource'], 5000, async (signal) => { // Critical section here if (signal.aborted) { throw signal.error; } console.log('Lock acquired!'); }); redis.quit();

Debug

Known issues

breakingVersion 5 changes to ESM-only (with CommonJS fallback). CommonJS projects may need to use dynamic import or configure their bundler.

fix

If using CommonJS, use `const Redlock = (await import('redlock')).default` or switch to ESM.

affects: >=5.0.0

breakingioredis is now a peer dependency (v5) rather than a runtime dependency. You must install ioredis separately.

fix

Run `npm install ioredis` alongside `npm install redlock`.

affects: >=5.0.0

gotchaLock duration (TTL) must be an integer. Passing a float will cause unexpected behavior.

fix

Ensure the second parameter to `acquire` or `using` is an integer (e.g., 5000, not 5000.5).

affects: >=1.0.0

gotchaDo not modify Redlock instance properties after first use. Changing `retryCount` after a lock is attempted can lead to inconsistent state.

fix

Treat Redlock options as immutable after instantiation.

affects: >=1.0.0

gotchaThe `extend` method returns a new Lock instance. The old lock is no longer valid after extension.

fix

Always replace the old lock variable with the result of `lock.extend()`.

affects: >=4.0.0

deprecatedIn v4, the `lock` event and `unlock` event were deprecated. They are removed in v5.

fix

Remove event listeners for 'lock' and 'unlock'. Use the `using` API instead.

affects: >=5.0.0

Errors

Common errors & fixes

Error: Redlock has not been properly configured.

Instantiating Redlock without providing an array of clients.

fix

Pass an array of ioredis clients: `new Redlock([client])`.

TypeError: redlock.acquire is not a function

Using default import in CommonJS without proper interop.

fix

Use `const Redlock = require('redlock').default` or switch to ESM.

LockError: The lock was lost.

Lock extension failed (e.g., network partition or Redis down).

fix

Handle `ResourceLockedError` and retry. Ensure at least 3 Redis instances for fault tolerance.

ReferenceError: ResourceLockedError is not defined

Trying to import ResourceLockedError in CommonJS without destructuring.

fix

Use `const { ResourceLockedError } = require('redlock')`.

Upgrade

Version history

5.0.0-beta.3latest on npm

Audit

Dependencies

ioredisrequiredRequired to connect to Redis (peer dependency in v5, runtime dependency in v4)

Agent activity

5 hits · last 30 days

node