mongoose-cron

MongoDB collection as crontab

MongooseCron is build on top of MongoDB and Mongoose. It offers a simple API for scheduling tasks and running recurring jobs on one or multiple database collections, supporting models and discriminators. It's fast, minimizes processing overhead and it uses atomic commands to ensure safe job executions in cluster environments.

Setup

$ npm install --save mongoose-cron

Quick Start

Let's say we have a simple application like the one below.

import mongoose from 'mongoose';

let db = mongoose.connect('mongodb://localhost:27017/testdb');
let schema = new mongoose.Schema({name: String});
let Task = db.model('Task', schema);

To convert the Task model into a crontab collection, attach the plugin, create a cron worker instance, then call the start method on it to start processing.

import {cronPlugin} from 'mongoose-cron';

let schema = new mongoose.Schema({name: String});
schema.plugin(cronPlugin, {
  handler: doc => console.log('processing', doc) // function or promise
});

let Task = db.model('Task', schema);
let cron = Task.createCron().start(); // call `cron.stop()` to stop processing

We can now create our first job.

Task.create({
  cron: {
    enabled: true,
    startAt: new Date('2015-12-12'),
    stopAt: new Date('2016-12-12'),
    interval: '* * * * * *' // run every second
  }
});

IMPORTANT: Any document in the tasks collection above can become a cron job. We just have to set at least the cron.enabled field to true.

Configuration & Details

The package includes several useful methods and configuration options. We can configure cron functionality by passing the additional options to the plugin or by passing them directly to the Task.createCron method.

schema.plugin(cronPlugin, {
  ...
  // When there are no jobs to process, wait 30s before
  // checking for processable jobs again (default: 0).
  idleDelay: 30000,
  // Wait 60s before processing the same job again in case
  // the job is a recurring job (default: 0).
  nextDelay: 60000,
  // Object or Array of Objects to add to the find query.
  // The value is concatinated with the $and operator.
  // (default: [])
  addToQuery: { version: { $lte: 1 } }
});

We can create recurring or one-time jobs. Every time the job processing starts the cron.startedAt field is replaced with the current date and the cron.locked field is set to true. When the processing ends the cron.processedAt field is updated to the current date and the cron.locked field is removed.

We can create a one-time job which will start processing immediately just by setting the cron.enabled field to true.

model.create({
  cron: {
    enabled: true
  }
});

Job execution can be delayed by setting the cron.startAt field.

model.create({
  cron: {
    ...
    startAt: new Date('2016-01-01')
  }
});

By setting the cron.interval field we define a recurring job.

model.create({
  cron: {
    ...
    interval: '* * * * * *' // every second
  }
});

The interval above consists of 6 values.

*    *    *    *    *    *
┬    ┬    ┬    ┬    ┬    ┬
│    │    │    │    │    |
│    │    │    │    │    └ day of week (0 - 7) (0 or 7 is Sun)
│    │    │    │    └───── month (1 - 12)
│    │    │    └────────── day of month (1 - 31)
│    │    └─────────────── hour (0 - 23)
│    └──────────────────── minute (0 - 59)
└───────────────────────── second (0 - 59)

A recurring job will repeat endlessly unless we limit that by setting the cron.stopAt field. When a job expires it stops repeating. If we also set cron.removeExpired field to true, a job is automatically deleted.

model.create({
  cron: {
    enabled: true,
    startAt: new Date('2016-01-01'),
    interval: '* * * * * *',
    stopAt: new Date('2020-01-01'),
    removeExpired: true
  }
});

Example

You can run the attached example with the npm run example command.

Alternatives

There is a very similar package called mongodb-cron, which uses the officially supported Node.js driver for MongoDB.