mongo-lead ~ Leader Election backed by MongoDB
A lightweight leader election implementation using MongoDB as the coordination backend. This package enables distributed systems to elect a single leader among multiple instances, ensuring that only one instance holds the leadership role at any given time.
The leader election process works by:
- Using MongoDB's atomic operations to maintain leadership records
- Implementing a heartbeat mechanism with TTL (Time To Live) indexes
- Automatically handling failover if the leader becomes unavailable
- Providing event-driven leadership status notifications
Perfect for scenarios where you need:
- Distributed cron jobs that should only run on one instance
- Primary/backup system coordination
- Cluster coordination tasks
- Preventing duplicate processing in distributed systems
Summary
A MongoDB-backed leader election package that provides reliable distributed coordination through atomic operations and TTL-based heartbeats. Built and maintained by mguleryuz, inspired by mongo-leader by Andrew Molyuk.
Check out the Changelog to see what changed in the last releases.
Install
bun add mongo-lead
Usage
import mongoose from 'mongoose'
import Leader from 'mongo-lead'
// Plese note that prior to using the Leader class you need to have a MongoDB instance connected
const leader = new Leader(mongoose.connection.db, {
groupName: 'all-cron-jobs',
ttl: 10000,
wait: 1000,
})
leader.start()
leader.on('elected', () => {
console.log('Starting all cron jobs')
// ...Rest of the code
})
leader.on('revoked', () => {
console.log('Stopping all cron jobs')
// ...Rest of the code
})
Developing
Install Dependencies
bun i
Watching TS Problems
bun watch
How to make a release
For the Maintainer: Add NPM_TOKEN to the GitHub Secrets.
- PR with changes
- Merge PR into main
- Checkout main
git pullbun release: '' | alpha | beta optionally add -- --release-as minor | major | 0.0.1- Make sure everything looks good (e.g. in CHANGELOG.md)
- Lastly run
bun release:pub
- Done
License
This package is licensed under the MIT License - see the LICENSE file for details.
