Registry / devops / simple-redis-mutex

simple-redis-mutex

library3.0.0jsnpmunverified

simple-redis-mutex is a lightweight distributed mutex lock implementation using Redis, based on the SETNX + EXPIRE pattern described in Redis docs. Version 3.0.0 ships TypeScript types, supports ESM and CJS, and relies on Redis >=5.0.0 as a peer dependency. Unlike the more complex Redlock algorithm, this library focuses on simplicity and uses Redis Pub/Sub for immediate lock release notification, with manual polling as a fallback. It offers two lock acquisition methods: blocking `lock` and non-blocking `tryLock`, both returning a release function with an optional fencing token. The package is actively maintained and suitable for Node.js >=8.2.1.

devops

npm install simple-redis-mutex

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · SIMPLE-REDIS-MUTEX

simple-redis-mutex

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

lock

✓ import { lock } from 'simple-redis-mutex'

✗ const lock = require('simple-redis-mutex').lock

ESM named export; CommonJS users can use destructuring or `const { lock } = require('simple-redis-mutex');`

tryLock

✓ import { tryLock } from 'simple-redis-mutex'

✗ import tryLock from 'simple-redis-mutex'

Named export, not default. CommonJS: `const { tryLock } = require('simple-redis-mutex');`

LockOptions

✓ import type { LockOptions } from 'simple-redis-mutex'

✗ import { LockOptions } from 'simple-redis-mutex'

TypeScript type export; should be imported using `import type` in TypeScript with `isolatedModules`.

Demonstrates acquiring a distributed mutex lock via `lock` with a Redis client, performing critical work, and releasing the lock.

import { createClient } from 'redis'; import { lock } from 'simple-redis-mutex'; async function main() { const redis = await createClient() .on('error', (err) => console.log('Redis Client Error', err)) .connect(); const release = await lock(redis, 'my-resource', { timeout: 10000, pollingInterval: 500, }); // Critical section await new Promise((resolve) => setTimeout(resolve, 1000)); await release(); await redis.quit(); } main().catch(console.error);

Debug

Known issues

breakingsimple-redis-mutex v3 drops support for redis v3/v4; requires redis >=5.0.0.

fix

Upgrade redis to >=5.0.0 as a peer dependency.

affects: >=3.0.0

gotchaThe lock release function returns a Promise that should be awaited to ensure the lock is properly released.

fix

Always `await release()` or return the promise.

affects: >=1.0.0

gotchaIf the Redis client disconnects or the lock times out, pending lock acquisitions may throw an error. Ensure error handling around `lock()` and `tryLock()`.

fix

Wrap lock acquisition in try/catch or handle promise rejections.

affects: >=1.0.0

deprecatedThe option `failAfter` is deprecated in v3 and may be removed in a future major version. Use `timeout` and `pollingInterval` instead.

fix

Replace `failAfter` with explicit `timeout` and `pollingInterval` options.

affects: >=3.0.0

breakingThe `release` function no longer accepts a callback in v3; it returns a Promise.

fix

Use `release().then(() => { ... })` or `await release();`.

affects: >=3.0.0

Errors

Common errors & fixes

Cannot use import statement outside a module

Using ESM `import` in a CommonJS project without proper configuration.

fix

Set `"type": "module"` in package.json or use CommonJS require: `const { lock } = require('simple-redis-mutex');`

TypeError: redis.createClient is not a function

Importing from 'redis' incorrectly or using old version (e.g., v3).

fix

Ensure you have redis >=5.0.0 installed and use `import { createClient } from 'redis';`

ERR wrong number of arguments for 'set' command

Using an outdated Redis server (< 2.6.12) that does not support the NX/EX options required by the lock command.

fix

Upgrade Redis server to version 2.6.12 or later.

The `lock` function is not a function

Trying to call `lock` (uppercase L) instead of `lock` or incorrect import.

fix

Use correct import: `import { lock } from 'simple-redis-mutex';`

Upgrade

Version history

3.0.0latest on npm

Audit

Dependencies

redisrequiredRuntime peer dependency required to connect and issue commands to Redis; must be >=5.0.0.

Agent activity

10 hits · last 30 days

node

Amazon

Resources

githubhttps://github.com/AmrSaber/simple-redis-mutex ↗

packagesimple-redis-mutex ↗

homepagehttps://github.com/AmrSaber/simple-redis-mutex#readme ↗