Agenda

<p align="center"> <img src="https://cdn.jsdelivr.net/gh/agenda/agenda@main/agenda.svg" alt="Agenda" width="100" height="100"> </p> <p align="center"> A light-weight job scheduling library for Node.js </p>

Migrating from v5? See the Migration Guide for all breaking changes.

What's New in v6

• ESM-only - Modern ES modules (Node.js 18+)
• Pluggable backend system - New AgendaBackend interface for storage and notifications
• Real-time notifications - Optional notification channels for instant job processing
• MongoDB 6 driver - Updated to latest MongoDB driver
• Persistent job logging - Optional structured logging of job lifecycle events to database
• Monorepo - Now includes agenda, agendash, and agenda-rest packages

Key Features

• Complete rewrite in TypeScript (fully typed!)
• Pluggable backend - MongoDB by default, implement your own (see Custom Backend Driver)
• Real-time notifications - Use Redis, PostgreSQL LISTEN/NOTIFY, or custom pub/sub
• MongoDB 6 driver support
• touch() with optional progress parameter (0-100)
• getRunningStats() for monitoring
• Fork mode for sandboxed job execution
• Automatic connection handling
• Creates indexes automatically by default

Agenda offers

• Minimal overhead. Agenda aims to keep its code base small.
• Mongo backed persistence layer.
• Promises based API.
• Scheduling with configurable priority, concurrency, repeating and persistence of job results.
• Scheduling via cron or human readable syntax.
• Event backed job queue that you can hook into.
• Agenda-rest: optional standalone REST API.
• Inversify-agenda - Some utilities for the development of agenda workers with Inversify.
• Agendash: optional standalone web-interface.

Feature Comparison

Since there are a few job queue solutions, here a table comparing them to help you use the one that better suits your needs.

| Feature | BullMQ | Bull | Bee | pg-boss | Agenda | | :------------------------- | :-------------: | :-------------: | :------: | :-----------------: | :---------------------: | | Backend | redis | redis | redis | postgres | mongo, postgres, redis | | Status | Active | Maintenance | Stale | Active | Active | | TypeScript | ✓ | | | ✓ | ✓ | | Priorities | ✓ | ✓ | | ✓ | ✓ | | Concurrency | ✓ | ✓ | ✓ | ✓ | ✓ | | Delayed jobs | ✓ | ✓ | | ✓ | ✓ | | Global events | ✓ | ✓ | | | ✓ | | Rate Limiter | ✓ | ✓ | | ✓ | | | Debouncing | ✓ | | | ✓ | ✓ | | Pause/Resume | ✓ | ✓ | | | ✓ | | Sandboxed worker | ✓ | ✓ | | | ✓ | | Repeatable jobs | ✓ | ✓ | | ✓ | ✓ | | Auto-retry with backoff | ✓ | ✓ | | ✓ | ✓ | | Dead letter queues | ✓ | ✓ | | ✓ | | | Job dependencies | ✓ | | | | | | Atomic ops | ✓ | ✓ | ✓ | ✓ | ~ | | Persistence | ✓ | ✓ | ✓ | ✓ | ✓ | | UI | ✓ | ✓ | | | ✓ | | REST API | | | | | ✓ | | Central (Scalable) Queue | ✓ | | | ✓ | ✓ | | Supports long running jobs | | | | | ✓ | | Human-readable intervals | | | | | ✓ | | Real-time notifications | ✓ | | | ✓ | ✓ | | Optimized for | Jobs / Messages | Jobs / Messages | Messages | Jobs | Jobs |

Kudos for making the comparison chart goes to Bull maintainers.

Installation

Install via NPM

npm install agenda

For MongoDB: Install the official MongoDB backend:

npm install @agendajs/mongo-backend

You will need a working MongoDB database (v4+).

For PostgreSQL: Install the official PostgreSQL backend:

npm install @agendajs/postgres-backend

For Redis: Install the official Redis backend:

npm install @agendajs/redis-backend

Example Usage

import { Agenda } from 'agenda';
import { MongoBackend } from '@agendajs/mongo-backend';

const mongoConnectionString = 'mongodb://127.0.0.1/agenda';

const agenda = new Agenda({
	backend: new MongoBackend({ address: mongoConnectionString })
});

// Or override the default collection name:
// const agenda = new Agenda({
//   backend: new MongoBackend({ address: mongoConnectionString, collection: 'jobCollectionName' })
// });

// or pass in an existing MongoDB Db instance
// const agenda = new Agenda({
//   backend: new MongoBackend({ mongo: myMongoDb })
// });

agenda.define('delete old users', async job => {
	await User.remove({ lastLogIn: { $lt: twoDaysAgo } });
});

(async function () {
	// IIFE to give access to async/await
	await agenda.start();

	await agenda.every('3 minutes', 'delete old users');

	// Alternatively, you could also do:
	await agenda.every('*/3 * * * *', 'delete old users');
})();

agenda.define(
	'send email report',
	async job => {
		const { to } = job.attrs.data;
		await emailClient.send({
			to,
			from: 'example@example.com',
			subject: 'Email Report',
			body: '...'
		});
	},
	{ priority: 'high', concurrency: 10 }
);

(async function () {
	await agenda.start();
	await agenda.schedule('in 20 minutes', 'send email report', { to: 'admin@example.com' });
})();

(async function () {
	const weeklyReport = agenda.create('send email report', { to: 'example@example.com' });
	await agenda.start();
	await weeklyReport.repeatEvery('1 week').save();
})();

Full documentation

See also https://agenda.github.io/agenda/

Agenda's basic control structure is an instance of an agenda. Agenda's are mapped to a database collection and load the jobs from within.

Table of Contents

• Migration Guide (v5 to v6)
• Configuring an agenda
  • Real-Time Notifications
• Agenda Events
• Defining job processors
• Automatic Retry with Backoff
• Job Debouncing
• Auto-Cleanup of Completed Jobs
• Persistent Job Logging
• Creating jobs
• Managing jobs
• Starting the job processor
• Multiple job processors
• Manually working with jobs
• Job Queue Events
• Frequently asked questions
• Example Project structure
• Known Issues
• Debugging Issues
• Acknowledgements

Configuring an agenda

Possible agenda config options:

{
	// Required: Backend for storage (and optionally notifications)
	backend: AgendaBackend;
	// Optional: Override notification channel from backend
	notificationChannel?: NotificationChannel;
	// Agenda instance name (used in lastModifiedBy field)
	name?: string;
	// Job processing options
	defaultConcurrency?: number;
	processEvery?: string | number;
	maxConcurrency?: number;
	defaultLockLimit?: number;
	lockLimit?: number;
	defaultLockLifetime?: number;
	// Auto-remove one-time jobs after successful completion
	removeOnComplete?: boolean;
	// Persistent job logging
	logging?: boolean | JobLogger | { logger?: JobLogger; default?: boolean };
	// Fork mode options
	forkHelper?: { path: string; options?: ForkOptions };
	forkedWorker?: boolean;
}

MongoBackend config options:

{
	// MongoDB connection string
	address?: string;
	// Or existing MongoDB database instance
	mongo?: Db;
	// Collection name (default: 'agendaJobs')
	collection?: string;
	// MongoDB client options
	options?: MongoClientOptions;
	// Create indexes on connect (default: true)
	ensureIndex?: boolean;
	// Sort order for job queries
	sort?: { [key: string]: SortDirection };
	// Name for lastModifiedBy field
	name?: string;
}