# node-redis-warlock

> Battle-hardened distributed locking using redis

Latest version **1.0.2** (published 2021-10-22) · MIT license · 0 weekly downloads

## Install

```sh
npm install node-redis-warlock
pnpm add node-redis-warlock
yarn add node-redis-warlock
bun add node-redis-warlock
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.2 |
| Published | 2021-10-22 |
| First published | 2014-03-06 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 2 |
| Unpacked size | 12.3 KB |
| Known vulnerabilities | 0 (+1 in 1 direct dependencies) |
| Install scripts | no |
| GitHub stars | 147 |
| Author | Geoff Wagstaff |
| Maintainers | thedeveloper |
| Keywords | node.js, redis, lock |

## Links

- npm: https://www.npmjs.com/package/node-redis-warlock
- Repository: https://github.com/thedeveloper/warlock
- Issues: https://github.com/thedeveloper/warlock/issues
- npm.io page: https://npm.io/package/node-redis-warlock

## Dependencies (2)

- [uuid](https://npm.io/package/uuid.md) ^8.3.2
- [node-redis-script](https://npm.io/package/node-redis-script.md) ^2.0.1

## Alternatives

- [memory-cache](https://npm.io/package/memory-cache.md) — 795.0K weekly downloads
- [@httptoolkit/proxy-agent](https://npm.io/package/@httptoolkit/proxy-agent.md) — 11.2K weekly downloads
- [express-cache-controller](https://npm.io/package/express-cache-controller.md) — 5.3K weekly downloads
- [http-cache-middleware](https://npm.io/package/http-cache-middleware.md) — 4.5K weekly downloads
- [cache2](https://npm.io/package/cache2.md) — 1.5K weekly downloads

## Recent versions

- 1.0.2 (latest) — 2021-10-22
- 1.0.1 — 2021-10-22
- 1.0.0 — 2021-04-02
- 0.2.0 — 2016-01-05
- 0.1.4 — 2015-08-25
- 0.1.3 — 2015-08-25
- 0.1.2 — 2014-12-28
- 0.1.1 — 2014-08-29
- 0.0.7 — 2014-06-19
- 0.0.6 — 2014-03-19
- 0.0.5 — 2014-03-17
- 0.0.4 — 2014-03-08
- 0.0.3 — 2014-03-08
- 0.0.2 — 2014-03-06

## README

warlock
=======

[![Join the chat at https://gitter.im/TheDeveloper/warlock](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/TheDeveloper/warlock?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)

Battle-hardened distributed locking using redis.

## Requirements

* [node-redis](https://github.com/mranney/node_redis) compatible with `v0.10`
* Redis `v2.6.12` or above. If you're running a Redis version from `v2.6.0` to `v2.6.11` inclusive use `v0.0.7` of this module.

## Install

    npm install node-redis-warlock

## Usage

```javascript
const Warlock = require('node-redis-warlock');
const Redis = require('redis');

// Establish a redis client and pass it to warlock
const redis = Redis.createClient();
const warlock = Warlock(redis);

// Set a lock
const key = 'test-lock';
const ttl = 10000; // Lifetime of the lock

warlock.lock(key, ttl, (err, unlock) => {
  if (err) {
    // Something went wrong and we weren't able to set a lock
    return;
  }

  if (typeof unlock === 'function') {
    // If the lock is set successfully by this process, an unlock function is passed to our callback.
    // Do the work that required lock protection, and then unlock() when finished...
    //
    // do stuff...
    //
    unlock();
  } else {
    // Otherwise, the lock was not established by us so we must decide what to do
    // Perhaps wait a bit & retry...
  }
});

// set a lock optimistically
const key = 'opt-lock';
const ttl = 10000;
const maxAttempts = 4; // Max number of times to try setting the lock before erroring
const wait = 1000; // Time to wait before another attempt if lock already in place
warlock.optimistic(key, ttl, maxAttempts, wait, (err, unlock) => {});

// unlock using the lock id
var key = 'test-lock-2';
var ttl = 10000;
let lockId;

warlock.lock(key, ttl, (err, _, id) => {
  lockId = id;
});

// each client who knows the lockId can release the lock
warlock.unlock(key, lockId, (err, result) => {
  if (result == 1) {
    // unlocked successfully
  }
});

// change a lock's ttl
var key = 'touch-lock';
var ttl = 10000;
var ttl2 = 20000;

warlock.lock(key, ttl, function(err, unlock, id) {
  warlock.touch(key, id, ttl2, function(err) {});
});
```

## ProTips

* Read my [Distributed locks using Redis](https://engineering.gosquared.com/distributed-locks-using-redis) article and Redis' author's [A proposal for more reliable locks using Redis](http://antirez.com/news/77) to learn more about the theory of distributed locks using Redis.

---
_Source: https://npm.io/package/node-redis-warlock · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._