seneca-scheduler

An email plugin for the Seneca toolkit

This module is a plugin for the Seneca framework. It provides scheduling capability for actions.

With this module you can:

• Schedule a task to happen at a set future date
• Schedule a recurring task to that happens at prescribed intervals

The default implementation uses the node-schedule module to handle the event scheduling

You can customize this by overriding the appropriate actions.

Support

If you're using this module, feel free to contact me on twitter if you have any questions! :) @davidmarkclem

Current Version: 0.0.0

Tested on: node 0.10.26, seneca 0.5.15

Quick examples

Schedule a single future event:

var seneca = require('seneca')();

seneca.use('scheduler');

seneca.ready(function(err){
  if( err ) return console.log(err);

  seneca.act({
    role:'scheduler',
    cmd:'register',
    for: '22/10/15 17:24:02',
    task: function () {
      //do things
      console.log('doing things');
    },
  })

})

The for argument can also be a Date object or an object literal, as well as being a string.

Schedule a recurring event:

var seneca = require('seneca')();

seneca.use('scheduler');

seneca.ready(function(err){
  if( err ) return console.log(err);

  seneca.act({
    role:'scheduler',
    cmd:'register',
    every: {
      minute: 30,
      hour: 4,
      day: 5
    },
    task: function () {
      //do things
      console.log('doing things');
    },
  })

})

This will schedule an event for the 30th minute, of the 4th hour of 5th day of the month (for days of the week we use dayOfWeek).

There's also an alternative way to express recurrence:

var seneca = require('seneca')();

seneca.use('scheduler');

seneca.ready(function(err){
  if( err ) return console.log(err);

  seneca.act({
    role:'scheduler',
    cmd:'register',
    every: {
      '30th': 'minute',
      '4th': 'hour',
      '5th': 'day'
    },
    task: function () {
      //do things
      console.log('doing things');
    },
  })

})

Install

npm install seneca
npm install seneca-scheduler

You'll need the seneca module to use this module - it's just a plugin.

Usage

To load the plugin:

seneca.use('scheduler', { ... options ... })

To isolate logging output from the plugin, use:

node your-app.js --seneca.log=plugin:scheduler

For more logging options, see the Seneca logging tutorial. You may, for example, wish to log task output to a separate file for audit purposes.

Options

• locale: Defaults to en_gb, can be set to any language supported by moment.js
• endianness: Date endianness, defaults to L. Can be L, M or B (little, medium, big). L is DD MM YY, M is MM DD YY and B is YY MM DD

Actions

All actions provide results via the standard callback format: function(error,data){ ... }.

ACTION: role:scheduler, cmd:register

Register a task with the scheduler

Arguments:

• for: Must not appear alongside every. Used to schedule a future one off event, can be a
  • Date object
  • String - with a valid formatted date
  • Object - for instance {day: 14, month: 12, year:15} would be midnight on December 14th 2015
• every: Must not appear alongside for. Used to schedule recurring events, must be an object. Can take two forms:
  • Period properties: Same as the for object literal, can contain day, month, year, hour, minute, second, but unlike the for object, it can also have a dayOfWeek property to schedule events to occur weekly. dayOfWeek begins with 0 for Sunday, running to 6 for Saturday.
  • Suffixed Number properties: for easier reading, properties can describe the "Nth" interval of a period, e.g {'4th':'hour', '3rd day'} would be 4am every 3rd day of the month.
• task: A function to call when the time is right

Provides:

Object with properties:

• job: The original registered task
• id: The task id, used for retrieving and removing tasks
• name: The tasks name (as used by node-scheduler).
• pattern: The pattern used to determine scheduling, as set by for or every.
• cancel: Method which cancels the task
• cancelNext: Method which cancels the next calling of the task
• nextInvocation: Method which returns a Date object referring to the time of the next calling of the task
• trackInvocation: Used internally by node-schedule
• stopTrackingInvocation: Used internally by node-schedule
• _events: Used internally by node-schedule

Sub Actions:

None.

Hooks:

None.

ACTION: role:scheduler, cmd:list

Outputs an array of all the job id's currently scheduled

Arguments:

None.

Provides:

Array containing ID strings.

Sub Actions:

None.

Hooks:

None.

ACTION: role:scheduler, cmd:retrieve

Returns a task object when passed an id.

Arguments:

id: The id of the task to fetch

Provides:

Object with properties:

• job: The original registered task
• id: The task id, used for retrieving and removing tasks
• name: The tasks name (as used by node-scheduler).
• pattern: The pattern used to determine scheduling, as set by for or every.
• cancel: Method which cancels the task
• cancelNext: Method which cancels the next calling of the task
• nextInvocation: Method which returns a Date object referring to the time of the next calling of the task
• trackInvocation: Used internally by node-schedule
• stopTrackingInvocation: Used internally by node-schedule
• _events: Used internally by node-schedule

Sub Actions:

None.

Hooks:

None.

ACTION: role:scheduler, cmd:remove

Removes a task from the scheduler.

Arguments:

id: The id of the task to remove. Can also be an array of id's to remove. ids: An array of id's to remove.

Provides:

Nothing.

Sub Actions:

None.

Hooks:

None.

ACTION: role:scheduler, cmd:clear

Clears all scheduled tasks

Arguments:

None.

Provides:

Nothing

Sub Actions:

None.

Hooks:

None.

Logging

To see what this plugin is doing, try:

node your-app.js --seneca.log=plugin:scheduler

This will print action logs and plugin logs for the user plugin. To skip the action logs, use:

node your-app.js --seneca.log=type:plugin,plugin:scheduler

You can also set up the logging programmatically:

var seneca = require('seneca')({
  log:{
    map:[
      {plugin:'scheduler',handler:'print'}
    ]
  }
})

For more on logging, see the seneca logging example.

Test

Run tests with:

npm test

If debugging tests:

npm run debug-test

Then go to http://localhost:8080/debug?port=5858 in Chrome to use dev-tools to debug. Awesome sauce.

Todo

• update action (update a task)
• pause (pause a recurring task)
• executable tasks (command line strings)
• fuzzy date matching ('next Tuesday', 'every Wednesday at 5')
• cron strings
• tests for error cases