npm

Ready to take your JavaScript development to the next level? Meet npm Enterprise - the ultimate in enterprise JavaScript.Learn more »

@darkobits/cron

0.2.2 • Public • Published

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

Install

npm i -D @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 | boolean>;
 
  /**
   * 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 | boolean>;
 
  /**
   * 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;
  };
}

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

30

version

0.2.2

license

WTFPL

homepage

github.com

repository

Gitgithub

last publish

collaborators

  • avatar
Report a vulnerability