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).

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, as agenda.begin() is not going to resolve till indices have been created.
  In case you’re utilizing the db choices, or name database, then you should still must hear for the prepared 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