Get unlimited public & private packages + team-based management with npm Teams.Learn more »

@darkobits/cron

0.2.5 • Public • Published

Cron is a utility that will run a function on an interval or according to a cron expression.

Install

npm i @darkobits/cron

Use

This package's default export is a factory function that accepts an options object of the following shape:

interface CronOptions {
  /**
   * Accepts either a simple interval expressed in milliseconds (ex: 10000) or a
   * string describing an interval (ex: '10 seconds') or a cron expression
   * (ex: '0 22 * * 1-5').
   */
  delay: string | number;
 
  /**
   * Function that will be called for each task run.
   */
  task: (...args: Array<any>) => Promise<any> | any;
}

The object returned by Cron has the following shape:

interface CronInstance {
  /**
   * Registers a listener for an event emitted by Cron.
   */
  on(eventName: CronEvent, listener: (eventData?: any) => any): void;
 
  /**
   * If the Cron is suspended, starts the Cron, emits the "start" event, and
   * resolves when all "start" event handlers have finished running.
   *
   * If the Cron is already running, resolves with `false`.
   */
  start(): Promise<void | false>;
 
  /**
   * If the Cron is running, suspends the Cron, emits the "suspend" event, and
   * resolves when all "suspend" event handlers have finished running.
   *
   * If the Cron is already suspended, resolves with `false`.
   */
  suspend(): Promise<void | false>;
 
  /**
   * When using a simple interval, returns the number of milliseconds between
   * intervals.
   *
   * When using a cron expression, returns -1, as intervals between runs may be
   * variable.
   */
  getInterval: {
    (): number;
 
    /**
     * Returns a string describing when tasks will run in humanized form.
     *
     * @example
     *
     * 'Every 30 minutes on Wednesdays.'
     */
    humanized(): string;
  };
 
  /**
   * Returns the time remaining until the next task run begins in milliseconds.
   */
  getTimeToNextRun: {
    (): number;
 
    /**
     * Returns a string describing when the next task will run in humanized
     * form.
     *
     * @example
     *
     * 'In 10 minutes.'
     */
    humanized(): string;
  };
}

Simple Intervals vs. Cron Expressions

When using a simple interval with Cron (ex: 10 seconds), Cron will run its task, and then wait 10 seconds before running its task again. Therefore, if a task takes on average 20 seconds to complete, Cron will start new task runs approximately every 30 seconds. This prevents concurrent task runs that may lead to race conditions or unintended side-effects.

However, when using a cron expression (ex: 0 * * * *, or every hour), Cron will always begin a new task run at the top of the hour, whether or not the last task run has finished. It is therefore up to the developer to understand approximately how long their tasks take and how often to execute them to avoid concurrent task runs.

Events

Cron emits the following events:

start

Emitted when the Cron is started.

task.start

Emitted when a task is about to run.

task.end

Emitted after a task finishes running. This callback will receive the return value of the task function.

suspend

Emitted when the Cron is suspended.

error

Emitted when the Cron (or a task) encounters an error. This callback will receive the error thrown.

Example

Using a simple interval:

import Cron from '@darkobits/cron';
 
const task = async () => {
  // Make the world a better place here.
};
 
const cron = Cron({delay: '10 seconds', task});
 
cron.start();

Using a cron expression:

import Cron from '@darkobits/cron';
 
const task = async () => {
  // Save the whales here.
};
 
// Run at 12:00 on Wednesdays during every third month.
const cron = Cron({delay: '0 12 * */3 3', task});
 
cron.start();

Setting up event handlers:

import Cron from '@darkobits/cron';
 
const task = async () => {
  // Prevent forest fires here.
};
 
const cron = Cron({delay: '10 seconds', task});
 
cron.on('start', () => {
  console.log('Cron was started.');
});
 
cron.on('task.start', () => {
  console.log('Task was started');
});
 
cron.on('task.end', result => {
  console.log('Task finished. Result:', result);
  const nextRun = cron.getTimeToNextRun.humanized();
  console.log(`Next run: ${nextRun}.`);
});
 
cron.on('error', err => {
  console.log('Suspending Cron due to error:', err);
  cron.suspend();
});
 
cron.on('suspend', () => {
  console.log('Cron was suspended.');
});
 
cron.start();

 


Install

npm i @darkobits/cron

DownloadsWeekly Downloads

33

Version

0.2.5

License

WTFPL

Unpacked Size

28.2 kB

Total Files

19

Last publish

Collaborators

  • avatar