@apiratorjs/locking-redis

An extension to the core @apiratorjs/locking library, providing Redis-based implementations of distributed mutexes and semaphores for true cross-process concurrency control in Node.js.

Note: Requires Node.js version >=16.4.0

A running Redis instance (version 5+ recommended).

Why Use Redis for Distributed Locking?

• Multi-instance deployments: If you have multiple Node.js processes or servers behind a load balancer, an in-memory lock is insufficient. Redis provides a single, centralized coordination point.
• Fault tolerance: Configurable timeouts (TTLs) prevent indefinite locks if a process crashes.
• Scalability: Redis can handle many simultaneous locking requests at scale.

Features

• Redis-Powered Distributed Mutex and Semaphore. Enables multi-process or multi-instance synchronization across a shared Redis server.
• Compatible API: Same DistributedMutex and DistributedSemaphore interface as @apiratorjs/locking, so you can swap in Redis without changing the rest of your code.
• Time-limited locks (TTL). Prevents deadlocks if processes crash without releasing.
• Cancellation, Timeouts, and FIFO. Cancel blocked acquisitions, specify timeouts, and queue waiters in a first-in-first-out manner.

Installation

Install with npm:

npm install @apiratorjs/locking @apiratorjs/locking-redis

Or with yarn:

yarn add @apiratorjs/locking @apiratorjs/locking-redis

Usage

import { DistributedMutex, DistributedSemaphore } from "@apiratorjs/locking";
import { createRedisLockFactory } from "@apiratorjs/locking-redis";

async function setupRedisBackedLocks() {
  const lockFactory = await createRedisLockFactory({ url: "redis://localhost:6379" });

  // Override the default in-memory factory:
  DistributedMutex.factory = lockFactory.createDistributedMutex;
  DistributedSemaphore.factory = lockFactory.createDistributedSemaphore;
}

// Then anywhere else in your code:
const mutex = new DistributedMutex({ name: "global-mutex" });
// This will now automatically use Redis under the hood

Contributing

Contributions, issues, and feature requests are welcome! Please open an issue or submit a pull request on GitHub.