dpa-distributed-lock-cron


Distributed Lock decorator for NestJS cron jobs using Redis. Prevents duplicate cron job execution in multi-replica environments (Docker Swarm, Kubernetes, PM2 cluster).

✨ Features

- 🔒 Atomic Locking - Uses Redis SET NX PX for race-condition-free locking
- 🎯 Simple Decorator - Just add @DistributedLock() to your cron method
- 🔄 Auto Release - Lock is automatically released after method execution
- 🛡️ Fail-Open - Allows execution if Redis is unavailable (configurable)
- 📦 Zero Config - Works out of the box with environment variables

📦 Installation

``bash
npm install dpa-distributed-lock-cron ioredis
`

🚀 Quick Start

$3

`typescript
// app.module.ts
import { Module } from '@nestjs/common';
import { ConfigModule } from '@nestjs/config';
import { DistributedLockModule, distributedLockConfig } from 'dpa-distributed-lock-cron';

@Module({
imports: [
ConfigModule.forRoot({
isGlobal: true,
load: [distributedLockConfig],
}),
DistributedLockModule,
],
})
export class AppModule {}
`

$3

`bash
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD= # optional
REDIS_DB=0 # optional, default: 0
REDIS_KEY_PREFIX= # optional, e.g., "myapp:"
`

$3

`typescript
import { Injectable } from '@nestjs/common';
import { Cron, CronExpression } from '@nestjs/schedule';
import { DistributedLock } from 'dpa-distributed-lock-cron';

@Injectable()
export class MyService {
@Cron(CronExpression.EVERY_DAY_AT_6AM)
@DistributedLock('cron:daily-sync', 300000) // key, TTL 5 minutes
async dailySync(): Promise {
// ✅ Only ONE replica will execute this
console.log('Running daily sync...');
}
}
`

📖 API Reference

$3

Decorator to wrap your cron method with distributed locking.

| Parameter | Type | Description |
|-----------|------|-------------|
| keyName | string | Unique lock key (e.g., 'cron:my-job') |
| ttlMs | number | Lock TTL in milliseconds (safety timeout) |

$3

Injectable service for manual lock management.

`typescript
import { DistributedLockService } from 'dpa-distributed-lock-cron';

@Injectable()
export class MyService {
constructor(private readonly lockService: DistributedLockService) {}

async manualLockExample() {
const acquired = await this.lockService.acquireLock('my-lock', 60000);
if (acquired) {
try {
// do work
} finally {
await this.lockService.releaseLock('my-lock');
}
}
}
}
`

| Method | Returns | Description |
|--------|---------|-------------|
| acquireLock(key, ttlMs) | Promise | Acquire lock, returns true if acquired |
| releaseLock(key) | Promise | Release lock (only if owned) |
| isConnected() | boolean | Check Redis connection status |

⚙️ How It Works

`
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Replica 1 │ │ Replica 2 │ │ Replica 3 │
└──────┬──────┘ └──────┬──────┘ └──────┬──────┘
│ │ │
│ SET lock NX PX │ SET lock NX PX │ SET lock NX PX
│ │ │
▼ ▼ ▼
┌───────────────────────────────────────────────┐
│ REDIS │
│ lock:cron:daily-sync = "replica-1-uuid" │
└───────────────────────────────────────────────┘
│ │ │
▼ ▼ ▼
✅ Execute ❌ Skip ❌ Skip
`

1. Before method execution, decorator tries to acquire lock using Redis SET key NX PX ttl
2. If lock acquired (OK): method executes, then lock is released
3. If lock not acquired (null`): method is skipped silently
4. Lock uses Lua script for safe release (only the owner can release)

🛡️ Fail-Open Behavior

If Redis is unavailable, the decorator allows execution (fail-open) to prevent blocking all replicas. This ensures your cron jobs continue to run even during Redis outages.

📋 Requirements

- Node.js >= 18.0.0
- NestJS >= 10.0.0
- Redis >= 6.0

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

MIT © DPA Team