A light-weight-weight job scheduling library for Node.js
Agenda affords
- Minimal overhead. Agenda goals to maintain its code base small.
- Mongo backed persistence layer.
- Guarantees primarily based API.
- Scheduling with configurable precedence, concurrency, and repeating.
- Scheduling through cron or human readable syntax.
- Occasion backed job queue that you would be able to hook into.
- Agenda-rest: non-compulsory standalone REST API.
- Inversify-agenda – Some utilities for the event of agenda staff with Inversify.
- Agendash: non-compulsory standalone web-interface.
Characteristic Comparability
Since there are just a few job queue options, right here a desk evaluating them that will help you use the one which
higher fits your wants.
Agenda is nice in case you want a MongoDB job scheduler, however strive Bree in case you want one thing less complicated (constructed by a earlier maintainer).
Characteristic | Bull | Bee | Agenda |
---|---|---|---|
Backend | redis | redis | mongo |
Priorities | ✓ | ✓ | |
Concurrency | ✓ | ✓ | ✓ |
Delayed jobs | ✓ | ✓ | |
International occasions | ✓ | ||
Price Limiter | ✓ | ||
Pause/Resume | ✓ | ||
Sandboxed employee | ✓ | ||
Repeatable jobs | ✓ | ✓ | |
Atomic ops | ✓ | ✓ | |
Persistence | ✓ | ✓ | ✓ |
UI | ✓ | ✓ | |
REST API | ✓ | ||
Optimized for | Jobs / Messages | Messages | Jobs |
Kudos for making the comparability chart goes to Bull maintainers.
Set up
Set up through NPM
npm set up agenda
Additionally, you will want a working Mongo database (v3) to level it to.
CJS / Module Imports
for normal javascript code, simply use the default entrypoint
const Agenda = require('agenda');
For Typescript, Webpack or different module imports, use agenda/es
entrypoint:
e.g.
import { Agenda } from 'agenda/es';
NOTE: In case you’re migrating from @varieties/agenda
you additionally ought to change imports to agenda/es
.
As a substitute of import Agenda from 'agenda'
use import Agenda from 'agenda/es'
.
Instance Utilization
const mongoConnectionString = "mongodb://127.0.0.1/agenda";
const agenda = new Agenda({ db: { handle: mongoConnectionString } });
// Or override the default assortment identify:
// const agenda = new Agenda({db: {handle: mongoConnectionString, assortment: 'jobCollectionName'}});
// or move extra connection choices:
// const agenda = new Agenda({db: {handle: mongoConnectionString, assortment: 'jobCollectionName', choices: {ssl: true}}});
// or move in an present mongodb-native MongoClient occasion
// const agenda = new Agenda({mongo: myMongoClient});
agenda.outline("delete old users", async (job) => {
await Person.take away({ lastLogIn: { $lt: twoDaysAgo } });
});
(async operate () {
// IIFE to present entry to async/await
await agenda.start();
await agenda.each("3 minutes", "delete previous customers");
// Alternatively, you might additionally do:
await agenda.each("*/3 * * * *", "delete previous customers");
})();
agenda.outline(
"send email report",
{ precedence: "high", concurrency: 10 },
async (job) => {
const { to } = job.attrs.knowledge;
await emailClient.ship({
to,
from: "example@example.com",
topic: "Email Report",
physique: "...",
});
}
);
(async operate () {
await agenda.start();
await agenda.schedule("in 20 minutes", "send email report", {
to: "admin@example.com",
});
})();
(async operate () {
const weeklyReport = agenda.create("send email report", {
to: "example@example.com",
});
await agenda.start();
await weeklyReport.repeatEvery("1 week").save();
})();
Full documentation
Agenda’s primary management construction is an occasion of an agenda. Agenda’s are
mapped to a database assortment and cargo the roles from inside.
Desk of Contents
- Configuring an agenda
- Agenda Occasions
- Defining job processors
- Creating jobs
- Managing jobs
- Beginning the job processor
- A number of job processors
- Manually working with jobs
- Job Queue Occasions
- Often requested questions
- Instance Venture construction
- Identified Points
- Debugging Points
- Acknowledgements
Configuring an agenda
All configuration strategies are chainable, which means you are able to do one thing like:
const agenda = new Agenda();
agenda
.database(...)
.processEvery('3 minutes')
...;
Agenda makes use of Human Interval for specifying the intervals. It helps the next items:
seconds
, minutes
, hours
, days
,weeks
, months
— assumes 30 days, years
— assumes three hundred and sixty five days
Extra subtle examples
agenda.processEvery("one minute");
agenda.processEvery("1.5 minutes");
agenda.processEvery("3 days and 4 hours");
agenda.processEvery("3 days, 4 hours and 36 seconds");
database(url, [collectionName])
Specifies the database on the url
specified. If no assortment identify is given,
agendaJobs
is used.
agenda.database("localhost:27017/agenda-test", "agendaJobs");
It’s also possible to specify it throughout instantiation.
const agenda = new Agenda({
db: { handle: "localhost:27017/agenda-test", assortment: "agendaJobs" },
});
Agenda will emit a prepared
occasion (see Agenda Occasions) when correctly related to the database.
It’s secure to name agenda.begin()
with out ready for this occasion, as that is dealt with internally.
In case you’re utilizing the db
choices, or name database
, then you should still must hear for prepared
earlier than saving jobs.
mongo(dbInstance)
Use an present mongodb-native MongoClient/Db occasion. This may help consolidate connections to a
database. You’ll be able to as a substitute use .database
to have agenda deal with connecting for you.
It’s also possible to specify it throughout instantiation:
const agenda = new Agenda({ mongo: mongoClientInstance.db("agenda-test") });
Notice that MongoClient.join() returns a mongoClientInstance since node-mongodb-native 3.0.0, whereas it used to return a dbInstance that might then be immediately handed to agenda.
identify(identify)
Units the lastModifiedBy
subject to identify
within the jobs assortment.
Helpful when you have a number of job processors (agendas) and wish to see which
job queue final ran the job.
agenda.identify(os.hostname + "-" + course of.pid);
It’s also possible to specify it throughout instantiation
const agenda = new Agenda({ identify: "test queue" });
processEvery(interval)
Takes a string interval
which might be both a conventional javascript quantity,
or a string akin to 3 minutes
Specifies the frequency at which agenda will question the database on the lookout for jobs
that have to be processed. Agenda internally makes use of setTimeout
to ensure that
jobs run at (near ~3ms) the appropriate time.
Lowering the frequency will lead to fewer database queries, however extra jobs
being saved in reminiscence.
Additionally price noting is that if the job queue is shutdown, any jobs saved in reminiscence
that have not run will nonetheless be locked, which means that you will have to attend for the
lock to run out. By default it’s '5 seconds'
.
agenda.processEvery("1 minute");
It’s also possible to specify it throughout instantiation
const agenda = new Agenda({ processEvery: "30 seconds" });
maxConcurrency(quantity)
Takes a quantity
which specifies the max variety of jobs that may be working at
any given second. By default it’s 20
.
agenda.maxConcurrency(20);
It’s also possible to specify it throughout instantiation
const agenda = new Agenda({ maxConcurrency: 20 });
defaultConcurrency(quantity)
Takes a quantity
which specifies the default variety of a selected job that may be working at
any given second. By default it’s 5
.
agenda.defaultConcurrency(5);
It’s also possible to specify it throughout instantiation
const agenda = new Agenda({ defaultConcurrency: 5 });
lockLimit(quantity)
Takes a quantity
which specifies the max quantity jobs that may be locked at any given second. By default it’s for no max.
agenda.lockLimit();
It’s also possible to specify it throughout instantiation
const agenda = new Agenda({ lockLimit: });
defaultLockLimit(quantity)
Takes a quantity
which specifies the default variety of a selected job that may be locked at any given second. By default it’s for no max.
agenda.defaultLockLimit();
It’s also possible to specify it throughout instantiation
const agenda = new Agenda({ defaultLockLimit: });
defaultLockLifetime(quantity)
Takes a quantity
which specifies the default lock lifetime in milliseconds. By
default it’s 10 minutes. This may be overridden by specifying the
lockLifetime
choice to an outlined job.
A job will unlock whether it is completed (ie. the returned Promise resolves/rejects
or accomplished
is specified within the params and accomplished()
is known as) earlier than the
lockLifetime
. The lock is helpful if the job crashes or instances out.
agenda.defaultLockLifetime(10000);
It’s also possible to specify it throughout instantiation
const agenda = new Agenda({ defaultLockLifetime: 10000 });
type(question)
Takes a question
which specifies the kind question for use for locating and locking the following job.
By default it’s { nextRunAt: 1, precedence: -1 }
, which obeys a primary in first out method, with respect to precedence.
Agenda Occasions
An occasion of an agenda will emit the next occasions:
prepared
– known as when Agenda mongo connection is efficiently opened and indices created.
In case you’re passing agenda an present connection, you should not must hear for this, asagenda.begin()
is not going to resolve till indices have been created.
In case you’re utilizing thedb
choices, or namedatabase
, then you should still must hear for theprepared
occasion earlier than saving jobs.agenda.begin()
will nonetheless look ahead to the connection to be opened.error
– known as when Agenda mongo connection course of has thrown an error
await agenda.start();
Defining Job Processors
Earlier than you should use a job, you will need to outline its processing conduct.
outline(jobName, [options], handler)
Defines a job with the identify of jobName
. When a job of jobName
will get run, it
shall be handed to handler(job, accomplished)
. To take care of asynchronous conduct, you might
both present a Promise-returning operate in handler
or present accomplished
as a
second parameter to handler
. If accomplished
is specified within the operate signature, you
should name accomplished()
if you end up processing the job. In case your operate is
synchronous or returns a Promise, you might omit accomplished
from the signature.
choices
is an non-compulsory argument which may overwrite the defaults. It may possibly take
the next:
con