ioredis-lock

library4.0.0jsnpmunverified

ioredis-lock v4.0.0 provides distributed locking for Node.js using Redis and the ioredis client. It uses Lua scripts for atomic acquire (SET key uuid PX timeout NX) and release operations, avoiding race conditions inherent in SETNX or WATCH/MULTI strategies. Requires Redis >= 2.6.12 and peer dependency ioredis ~4.x.x. Key features: configurable timeout, retries, delay; supports promises via bluebird; includes custom error types for acquisition, release, and extension failures. Compared to alternatives like redis-redlock or node-redlock, ioredis-lock is lighter and tightly coupled with ioredis, but does not implement the full Redlock algorithm for multi-master setups.

database

npm install ioredis-lock

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · IOREDIS-LOCK

ioredis-lock

databasejavascriptv4.0.0

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 'ioredis-lock';

✗ const createLock = require('ioredis-lock').createLock;

ESM is available since v4. The package also exports a default object with createLock, setDefaults, getAcquiredLocks, and error classes.

LockAcquisitionError

✓ import { LockAcquisitionError } from 'ioredis-lock';

✗ import LockAcquisitionError from 'ioredis-lock';

Named export, not default.

Lock (type)

✓ import type { Lock } from 'ioredis-lock';

TypeScript users should use this type for lock instances.

Default import

✓ import redislock from 'ioredis-lock';

✗ const redislock = require('ioredis-lock');

ESM default import returns an object with methods. The CJS require also works but is not recommended for modern projects.

Demonstrates creating a distributed lock with ioredis-lock, acquiring, performing critical work, and releasing with error handling for lock acquisition and release failures.

import Redis from 'ioredis'; import { createLock, LockAcquisitionError, LockReleaseError } from 'ioredis-lock'; const client = new Redis({ host: process.env.REDIS_HOST ?? 'localhost', port: parseInt(process.env.REDIS_PORT ?? '6379'), }); const lock = createLock(client, { timeout: 20000, retries: 3, delay: 100, }); async function main() { try { await lock.acquire('app:feature:lock'); console.log('Lock acquired'); // critical section await lock.release(); console.log('Lock released'); } catch (err) { if (err instanceof LockAcquisitionError) { console.error('Failed to acquire lock:', err.message); } else if (err instanceof LockReleaseError) { console.error('Failed to release lock:', err.message); } else { throw err; } } finally { client.quit(); } } main();

Debug

Known issues

breakingPeer dependency ioredis ~4.x.x may cause incompatibility with newer ioredis v5+.

fix

Use ioredis v4.x with ioredis-lock v4. For ioredis v5, consider using an alternative like redlock.

affects: >=4.0.0

gotchaThe default timeout of 10000 ms may be too short for long operations; locks expire automatically.

fix

Always set an appropriate timeout matching your critical section duration. Use lock.extend(time) to prolong if needed.

affects: >=0.0.0

gotchaRetries and delay only apply to initial acquisition; extend() does not retry automatically.

fix

Handle extend failures manually: catch LockExtendError and decide whether to retry or abort.

affects: >=0.0.0

deprecatedBluebird promise usage (Promise.bind) shown in documentation is discouraged in modern Node.js; use native async/await instead.

fix

Use async/await syntax with try/catch. The library returns native promises when used with async functions.

affects: >=3.0.0

gotchaLock must be released on the same connection that acquired it; the library does not enforce this, but it's implied.

fix

Always release.lock on the same lock object instance that acquired it. Do not share lock objects across connections.

affects: >=0.0.0

Errors

Common errors & fixes

Error: The lock could not be acquired. (LockAcquisitionError)

All retry attempts exhausted because the key is held by another lock or network issues.

fix

Increase timeout, retries, or delay in createLock options. Check for stale locks previously not released.

TypeError: client.createLock is not a function

Incorrect import: using the function on the ioredis client instead of importing from the library.

fix

Use: import { createLock } from 'ioredis-lock'; then call createLock(client, options).

Error: The lock could not be released. (LockReleaseError)

The lock key does not match the UUID held by this lock instance (e.g., lock expired or was released by another process).

fix

Ensure you only release locks you own. Use try/catch around release() and handle expiration gracefully.

Module not found: Can't resolve 'ioredis-lock'

Package not installed, or using ESM import in a CJS project without proper configuration.

fix

Run npm install ioredis-lock. For ESM, ensure package.json has "type": "module" or use .mjs extension.

Upgrade

Version history

4.0.0latest on npm

Audit

Dependencies

ioredisrequiredPeer dependency: ioredis is the Redis client adapter required for lock operations.

Agent activity

9 hits · last 30 days

node

Resources

githubhttps://github.com/makeomatic/ioredis-lock ↗

packageioredis-lock ↗

homepagehttps://github.com/makeomatic/ioredis-lock ↗