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.

1. PR with changes
2. Merge PR into main
3. Checkout main
4. git pull
5. bun release: '' | alpha | beta optionally add -- --release-as minor | major | 0.0.1
6. Make sure everything looks good (e.g. in CHANGELOG.md)
7. Lastly run bun release:pub
8. Done

License

This package is licensed under the MIT License - see the LICENSE file for details.