@marianmeres/cron-parser

A small, zero-dependency parser and evaluator for standard 5-field cron expressions, for Deno and Node. Supports IANA timezones (DST-correct) and POSIX / Vixie day-of-month-or-day-of-week semantics.

Installation

deno

deno add jsr:@marianmeres/cron-parser

nodejs

npm i @marianmeres/cron-parser

Usage

import { CronParser } from "@marianmeres/cron-parser";

A cron expression has 5 whitespace-separated fields, in this order:

┌───────────── minute        (0-59)
│ ┌─────────── hour          (0-23)
│ │ ┌───────── day-of-month  (1-31)
│ │ │ ┌─────── month         (1-12)
│ │ │ │ ┌───── day-of-week   (0-6, 0 = Sunday)
│ │ │ │ │
* * * * *

Each field accepts:

| Syntax | Meaning | Example | | ------- | ---------------------------- | ---------------- | | * | every value | * * * * * | | n | a single value | 30 * * * * | | a-b | a range | 0 9-17 * * * | | a,b,c | a list | 0 0 1,15 * * | | */n | every nth value | */15 * * * * | | a-b/n | every nth value in a range | 0 2-10/3 * * * |

No seconds field, no named months/weekdays, no @daily-style macros — this is the plain numeric 5-field syntax.

Examples

Construct a parser and ask for the next run:

import { CronParser } from "@marianmeres/cron-parser";

// at 02:00, Monday–Friday
const parser = new CronParser("0 2 * * 1-5");

parser.getNextRun();
// -> next matching Date, strictly after "now" (host-local time)

parser.getNextRun(new Date("2026-07-03T12:00:00"));
// -> Mon Jul 06 2026 02:00 (host-local time)

Test whether a specific date matches:

const parser = new CronParser("*/15 * * * *"); // every 15 minutes

parser.matches(new Date("2026-07-03T12:15:00")); // true
parser.matches(new Date("2026-07-03T12:16:00")); // false

The expanded field values are exposed as readonly arrays:

const parser = new CronParser("0 2-10/3 * * *");
parser.minute; // [0]
parser.hour; // [2, 5, 8]

Timezones

By default all date math uses the host's local time. Pass an IANA timezone name to evaluate the expression in that zone instead — DST transitions are handled correctly (spring-forward gaps are skipped, fall-back overlaps fire once):

const parser = new CronParser("0 9 * * 1-5", { timezone: "America/New_York" });

// 09:00 New York time, next weekday on/after this instant:
parser.getNextRun(new Date("2026-07-06T00:00:00Z")).toISOString();
// -> "2026-07-06T13:00:00.000Z"  (09:00 EDT)

Day-of-month vs. day-of-week

Following POSIX / Vixie cron: when both the day-of-month and day-of-week fields are restricted (neither is *), a date matches if it satisfies either one. When one of them is *, only the other restricts.

// 1st of the month OR any Monday, at midnight
const parser = new CronParser("0 0 1 * 1");

parser.matches(new Date("2026-07-01T00:00:00")); // true — the 1st
parser.matches(new Date("2026-07-06T00:00:00")); // true — a Monday

Invalid expressions throw at construction time — bad characters, wrong field count, out-of-range values, an unknown timezone, or a calendar combination that can never occur:

new CronParser("0 0 31 2 *");
// throws: describes a date that does not exist (Feb 31)

API

See API.md for complete API documentation.

License

MIT