@trellisorg/distributed-lock

This library provides a simple way to implement distributed locks using Redis. It is designed to be easy to use and integrate with your existing Node.js applications.

Installation

npm install @trellisorg/distributed-lock ioredis

Setup

Standalone TypeScript

import { RedisMutex } from '@trellisorg/distributed-lock/redis-mutex';
import Redis from 'ioredis';

const redisClient = new Redis({
    host: 'localhost',
    port: 6379,
});

const redisMutex = new RedisMutex({
    client: redisClient,
    lockPrefix: 'my-app',
    lockTimeout: 10_000,
    fifo: false,
});

// Acquire a lock on the resource 'my-resource'
const lock = await redisMutex.lock('my-resource');

// Do some work that requires the lock
console.log('Working with the resource...');

// Release the lock
await lock.unlock();

NestJS

import { Module } from '@nestjs/common';
import { DistributedLockModule } from '@trellisorg/distributed-lock/nest';
import { redisMutexLockAdapter } from '@trellisorg/distributed-lock/redis-mutex';

@Module({
    imports: [
        DistributedLockModule.register([
            {
                config: {
                    lockPrefix: 'my-app',
                    client: {
                        host: 'localhost',
                        port: 6379,
                    },
                    retryOptions: {},
                    lockTimeout: 10_000,
                    fifo: false,
                },
                adapter: redisMutexLockAdapter,
                name: 'redis',
            },
        ]),
    ],
})
export class AppModule {}

Configuration Options

| Option | Type | Default | Description | | -------------- | -------------- | ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------- | | client | RedisOptions | - | The connection options for Redis. See the ioredis documentation for more information. | | lockPrefix | string | @trellisorg/distributed-lock | A prefix for the lock keys. This helps to avoid collisions with other applications using Redis. | | lockTimeout | number | 10_000 | The time it takes for a lock to expire after acquisition. This is in milliseconds. | | retryOptions | RetryOptions | {} | Options for retrying lock acquisition. See the promise-retry documentation for more information. | | fifo | boolean | false | Whether to use FIFO ordering for lock acquisition. If true, locks will be acquired and released in the order they were requested. |

Usage

Standalone TypeScript

import { RedisMutex } from '@trellisorg/distributed-lock/redis-mutex';
import Redis from 'ioredis';

const redisClient = new Redis({
    host: 'localhost',
    port: 6379,
});

const redisMutex = new RedisMutex({
    client: redisClient,
    lockPrefix: 'my-app',
    lockTimeout: 10_000,
    fifo: false,
});

// Acquire a lock on the resource 'my-resource'
const lock = await redisMutex.lock('my-resource');

// Do some work that requires the lock
console.log('Working with the resource...');

// Release the lock
await lock.unlock();

NestJS

import { Injectable } from '@nestjs/common';
import { DistributedLock } from '@trellisorg/distributed-lock';
import { InjectLock } from '@trellisorg/distributed-lock/nest';

@Injectable()
export class MyService {
    constructor(@InjectLock('redis') private readonly redisLock: DistributedLock) {}

    async doSomething() {
        await this.redisLock.withLock('my-resource', async () => {
            // Do some work that requires the lock
            console.log('Working with the resource...');
        });
    }
}

Contributing

Contributions are welcome! Please open an issue or submit a pull request.

License

This project is licensed under the MIT License.