mongo-leader

library1.6.7jsnpmunverified

A Node.js library for MongoDB-backed leader election, inspired by redis-leader. Current stable version is 1.6.7, with regular releases. It extends EventEmitter to emit 'elected' and 'revoked' events when leadership status changes. Key differentiators: automatic TTL index handling (since 1.5.0) avoids IndexOptionsConflict on config changes; supports lazy start and polling; minimal dependencies. Compared to alternatives like node-zookeeper-leader or redis-leader, it leverages MongoDB's existing infrastructure.

database

npm install mongo-leader

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · MONGO-LEADER

mongo-leader

databasejavascriptv1.6.7

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.

Leader

✓ import { Leader } from 'mongo-leader'

✗ const Leader = require('mongo-leader')

ESM-only. The package does not support CommonJS require.

LeaderOptions

✓ import type { LeaderOptions } from 'mongo-leader'

TypeScript type export for configuring Leader constructor options.

LeaderEvent

✓ import { LeaderEvent } from 'mongo-leader'

✗ import { Event } from 'mongo-leader'

Enum of event names ('elected' | 'revoked'). Must use the exported LeaderEvent symbol.

Shows basic setup: connect to MongoDB, create Leader instance with TTL/wait options, listen for events, start leader election, poll status, and graceful shutdown.

import { MongoClient } from 'mongodb'; import { Leader } from 'mongo-leader'; const url = process.env.MONGO_URL ?? 'mongodb://localhost:27017'; const client = new MongoClient(url); await client.connect(); const db = client.db('leader_election'); const leader = new Leader(db, { ttl: 1000, wait: 500 }); leader.on('elected', () => console.log('Became leader')); leader.on('revoked', () => console.log('Lost leadership')); await leader.start(); // Check leadership status periodically setInterval(async () => { const isLeader = await leader.isLeader(); console.log(`Am I leader? ${isLeader}`); }, 100); // Graceful shutdown process.on('SIGINT', async () => { await leader.stop(); await client.close(); process.exit(0); });

Debug

Known issues

breakingPackage is ESM-only since v1.0.0 - cannot be used with CommonJS require().

fix

Use import { Leader } from 'mongo-leader' instead of require()

affects: >=1.0.0

gotchaThe Leader constructor requires a Db object, not a MongoClient or collection. Passing the wrong object causes runtime error.

fix

Ensure you pass db = await client.db('name') to the Leader constructor

affects: >=1.0.0

deprecatedUsing auto-start constructor option is deprecated in favor of explicit start() call.

fix

Call leader.start() explicitly after constructing the Leader instance

affects: <1.5.0

Errors

Common errors & fixes

TypeError: Cannot read properties of undefined (reading 'collection')

Leader constructor received a MongoClient instead of a Db object.

fix

const db = client.db('myapp'); const leader = new Leader(db);

Error: MongoError: E11000 duplicate key error dup key: { : ObjectId('...') }

Two instances with same leaderId (default is hostname) tried to become leader simultaneously.

fix

Set unique leaderId option: new Leader(db, { leaderId: 'instance-1' })

Error: IndexOptionsConflict: TTL index with different options already exists

TTL value changed between application restarts (versions < 1.5.0).

fix

Upgrade to version >= 1.5.0 which automatically handles TTL index changes.

Upgrade

Version history

1.6.7latest on npm

Audit

Dependencies

mongodbrequiredPeer dependency for MongoDB client - must be installed separately as it provides the database instance

Agent activity

11 hits · last 30 days

Bingbot

node

Resources

githubhttps://github.com/andrewmolyuk/mongo-leader ↗

packagemongo-leader ↗

homepagehttps://github.com/andrewmolyuk/mongo-leader#readme ↗