Quickstart

Getting started with @nhtio/millicron is quick and easy. Just follow the steps below and you'll be up and running in no time.

Prerequisites

This library requires Luxon.

Installation

You can install @nhtio/millicron directly from your preferred package manager

npm

npm i @nhtio/millicron

pnpm

pnpm add @nhtio/millicron

yarn

yarn add @nhtio/millicron

Usage

Import the MilliCron Class from the package:

import { MilliCron } from '@nhtio/millicron'

Create a new instance of the client

const daemon = new MilliCron()
daemon.start() // optional. you can delay starting until you've added jobs too.

Add cron jobs

daemon.$on('* * * * *', () => {
  // this runs once per minute
})

cron.$once("1704067200", () => {
  // This is set to run at midnight on January 1st, 2024
  console.log('Happy New Year!');
});

cron.$once(DateTime.now().toUTC().plus({ seconds: 10 }).toUnixInteger().toString(), () => {
  // This is set to run 10 seconds from now
  console.log("10 seconds later");
});

Utility Methods

The MilliCron class and its instances expose the following utility methods:

Method	Description
crontabMatchesDateTime	Check if the crontab expression matches the current time
getNextRunTimeForCrontab	Calculate the next run time for a crontab expression
getNextRunTimeForParsedCrontab	Calculate the next run time for a parsed crontab expression
getParsedCronExpression	Parses the given cron expression and returns either a DateTime object representing the next time the cron expression will match, or a CronTabObject containing the parsed cron expression.

Supported cron expressions

Crontab format

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

Important Note: While the millisecond field accepts values of 0-999, the resolution of the cron daemon is limited to 10ms, meaning that the job may trigger up to 10ms before or 10ms after the expressions's defined time.

Additionally, the library also accepts mixed use of ranges and range increments (except for W). The parsing on the cron-parser library, with modifications to allow supporting of milisecond expressions.

Examples

• * * * * * * * - Every 10ms
• */2 * * * * * * - Every 10ms (due to the 10ms resolution)
• */100 * * * * * - Every 100ms
• 0 * * * * * * - Every second
• 0 0 * * * * * - Every minute

For more information on the crontab format, see crontab.guru or cronjob.xyz. Note that these don't accept the exact same syntax as this library, as they do not accept the millisecond or seconds fields.

Crontab aliases

• @yearly - Once a year, at midnight on the morning of January 1st
• @monthly - Once a month, at midnight on the morning of the first day of the month
• @weekly - Once a week, at midnight on Sunday morning
• @daily - Once a day, at midnight
• @hourly - Once an hour, at the beginning of the hour

Unix Timestamp (seconds)

A unix timestamp in seconds can be used to specify a single time to run the job. Important Note: It is highly recommended to use the $once method with unix timestamps instead of $on in order to clear the callback after the job has run.

FAQ's

Q: Why is the resolution limited to 10ms? This is mostly a limitation of the setTimeout function which is used to handle the ticks. As noted in MDN's Documentation, most browsers will enforce a minimum timeout of 4ms once a nested call to setTimeout has been scheduled 5 times. Ticks can also be delayed if the OS / browser is busy with other tasks. While there can be cases where 10ms is not sufficient, it is a reasonable compromise between performance and accuracy.

Credits and Acknowledgements

This library leverages the capabilities of the Luxon library for proficient parsing and matching of date and time. The foundation of the cron parsing functionality is built upon the cron-parser library, albeit with custom modifications to accommodate millisecond expressions. The design and functionality of this library owe a significant debt to the inspiration derived from node-cron.