safe-redis-leader

library0.0.6jsnpmunverified

A safe leader election implementation for Node.js using Redis, designed to eliminate race conditions present in the original 'redis-leader' package (v0.0.6, latest). It uses async/await, removes CommonJS callback patterns, and provides a factory function 'createSafeRedisLeader' instead of requiring 'new'. The library is a rewrite that fixes known bugs in prior implementations, includes a test suite with Docker Compose, and focuses on correctness without external dependencies beyond ioredis. It offers events like 'elected' and methods 'elect' and 'stop', suitable for distributed systems needing reliable single-leader guarantees.

database

npm install safe-redis-leader

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · SAFE-REDIS-LEADER

safe-redis-leader

databasejavascriptv0.0.6

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

createSafeRedisLeader

✓ import { createSafeRedisLeader } from 'safe-redis-leader';

✗ const createSafeRedisLeader = require('safe-redis-leader');

Default export does not exist. Must use named import. CJS require works but with destructuring.

SafeRedisLeader

✓ import type { SafeRedisLeader } from 'safe-redis-leader';

✗ import { SafeRedisLeader } from 'safe-redis-leader';

SafeRedisLeader is a type only, not a runtime export. Do not attempt to instantiate it.

Events

✓ leader.on('elected', handler);

✗ leader.on('elected', handler);

Events are not exported as constants; use string literals.

Creates a safe Redis leader election instance and starts the election process.

import { createSafeRedisLeader } from 'safe-redis-leader'; import Redis from 'ioredis'; const redis = new Redis({ host: 'localhost', port: 6379 }); async function main() { const leader = await createSafeRedisLeader({ asyncRedis: redis, ttl: 1500, wait: 3000, key: 'my-election', }); leader.on('elected', () => { console.log('I am the leader'); }); leader.on('start', () => { console.log('Leader election started'); }); leader.on('stop', () => { console.log('Leader election stopped'); }); await leader.elect(); } main().catch(console.error);

Debug

Known issues

gotchacreateSafeRedisLeader is async and returns a Promise; you must await it.

fix

Use await createSafeRedisLeader(...) or .then() to get the leader instance.

affects: >=0.0.1

gotchaThe TTL must be shorter than wait; otherwise election may never complete due to lock expiration.

fix

Set TTL (e.g., 1500ms) less than wait (e.g., 3000ms) to allow re-election.

affects: >=0.0.1

breakingVersion 0.0.5 contained a bug where the 'elected' event could fire multiple times; fixed in 0.0.6.

fix

Upgrade to 0.0.6 or later.

affects: 0.0.5

deprecatedThe method 'start()' was never part of the public API; only use 'elect()' and 'stop()'.

fix

Call elect() to begin the election process.

affects: >=0.0.1

gotchaIf Redis connection is lost, leader election stops and 'stop' event fires. No auto-reconnect.

fix

Implement retry logic externally or ensure Redis connection is stable.

affects: >=0.0.1

Errors

Common errors & fixes

TypeError: createSafeRedisLeader is not a function

Imported the package incorrectly, e.g., using default import or wrong require.

fix

Use named import: import { createSafeRedisLeader } from 'safe-redis-leader';

Error: key option is required

Called createSafeRedisLeader without providing the 'key' option.

fix

Include 'key' in options object.

Error: asyncRedis must be an ioredis instance

Passed a Redis client that is not from ioredis (e.g., node-redis).

fix

Use ioredis as the Redis client.

Leader election never completes; no events fired

TTL is set too large compared to wait, or Redis is unreachable.

fix

Ensure TTL < wait and Redis connection is valid.

Upgrade

Version history

0.0.6latest on npm

Audit

Dependencies

ioredisrequiredRequired for connecting to Redis; the library expects an ioredis instance as input.

Agent activity

13 hits · last 30 days

node