> ## Documentation Index
> Fetch the complete documentation index at: https://nestcrate.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Locks — `nestrs-locks`

> Distributed lease locks for single-runner cron and critical sections — NestJS @nestjs/locks analogue.

`nestrs-locks` provides lease-based exclusivity (in-memory or Redis). Use it for schedule single-runner jobs, leader election light, and critical sections that must not overlap across processes.

## Install

```toml theme={null}
[dependencies]
nestrs = { version = "1.7.1", features = ["locks"] }
# Redis:
nestrs-locks = { version = "1.7.1", features = ["cache-redis"] }
```

## Usage

```rust theme={null}
use nestrs::locks::{LocksModule, LocksOptions, LocksService};
use std::sync::Arc;

#[module(imports = [LocksModule::register(LocksOptions::default())], providers = [Jobs])]
struct AppModule;

#[injectable]
struct Jobs {
    locks: Arc<LocksService>,
}

impl Jobs {
    async fn run_nightly(&self) {
        let Some(guard) = self.locks.try_acquire("cron:nightly").await else {
            return; // another instance holds the lease
        };
        // … work …
        guard.release().await;
    }

    async fn with_helper(&self) {
        let _ = self
            .locks
            .with_lock("invoice:42", || async {
                // exclusive work
            })
            .await;
    }
}
```

### Options

| Field | Default | Role |
| - | - | - |
| `store` | in-memory | `SharedLockStore` |
| `default_ttl` | 30s | Lease lifetime; must cover worst-case work or extend |

> [!WARNING]
>
> Pick TTL shorter than the duplicate work you can tolerate after a crash, but long enough that healthy work does not lose the lease mid-flight. Extend on long steps.

## Schedule single-runner

Combine with `ScheduleModule` (`schedule` feature): acquire a named lock at the start of `#[cron]` / `#[interval]` handlers so only one replica runs the job.

## See also

* [Workflows](https://nestcrate.dev/ecosystem/workflows.md) (often paired with locks)
* [API reference](https://nestcrate.dev/api/crates/nestrs-locks.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.