cron-fast

Fast and tiny JavaScript/TypeScript cron parser with timezone support. Works everywhere: Node.js, Deno, Bun, Cloudflare Workers, and browsers. Zero dependencies.

Features

• Parse & validate - Convert cron expressions to structured data and check validity
• Get execution times - Calculate next, previous, or multiple scheduled runs
• Match dates - Check if a date matches a cron expression
• Describe - Convert cron expressions to human-readable text (e.g., "Every 5 minutes")
• Timezone support - Full IANA timezone support using native Intl API

Why cron-fast?

• Universal - Works in Node.js, Deno, Bun, Cloudflare Workers, and browsers
• Zero dependencies - Lightweight and secure
• Fast - Optimal field increment algorithm with 10x+ performance vs alternatives
• Tree-shakeable - Import only what you need
• Modern - ESM + CJS, TypeScript-first
• Fully tested - Comprehensive test coverage across all runtimes
• ISO 8601 compatible - Works with all standard date formats

Installation

# Node.js (npm)
npm install cron-fast

# Node.js (pnpm)
pnpm add cron-fast

# Node.js (yarn)
yarn add cron-fast

# Deno (JSR)
deno add jsr:@kbilkis/cron-fast

# Bun
bun add cron-fast

# Any runtime (JSR)
npx jsr add @kbilkis/cron-fast

Quick Start

import { nextRun, previousRun, isValid, describe } from "cron-fast";

// Get next execution time (UTC)
const next = nextRun("0 9 * * *");
console.log(next); // Next 9:00 AM UTC

// With timezone
const nextNY = nextRun("0 9 * * *", { timezone: "America/New_York" });
console.log(nextNY); // Next 9:00 AM Eastern Time

// Get previous execution
const prev = previousRun("*/15 * * * *");

// Validate expression
if (isValid("0 9 * * *")) {
  console.log("Valid cron expression!");
}

// Get human-readable description
console.log(describe("*/5 * * * *")); // "Every 5 minutes"

API

nextRun(expression: string, options?: CronOptions): Date

Get the next execution time for a cron expression. Throws if the expression or timezone is invalid.

nextRun("0 9 * * *"); // Next 9:00 AM UTC
nextRun("0 9 * * *", { timezone: "Europe/London" }); // Next 9:00 AM London time
nextRun("0 9 * * *", { from: new Date("2026-03-15") }); // Next after Mar 15, 2026

previousRun(expression: string, options?: CronOptions): Date

Get the previous execution time. Throws if the expression or timezone is invalid.

previousRun("0 9 * * *"); // Last 9:00 AM UTC
previousRun("0 9 * * *", { timezone: "Asia/Tokyo" });

nextRuns(expression: string, count: number, options?: CronOptions): Date[]

Get next N execution times. Throws if the expression or timezone is invalid.

nextRuns("0 9 * * *", 5); // Next 5 occurrences

isValid(expression: string): boolean

Validate a cron expression.

isValid("0 9 * * *"); // true
isValid("invalid"); // false

isMatch(expression: string, date: Date, options?: CronOptions): boolean

Check if a date matches the cron expression. Throws if the expression or timezone is invalid.

isMatch("0 9 * * *", new Date("2026-03-15T09:00:00Z")); // true

parse(expression: string): ParsedCron

Parse a cron expression into its components. Throws if the expression is invalid.

parse("0 9 * * 1-5");
// Returns: { minute: [0], hour: [9], day: [1, 2, ..., 31], month: [0, 1, 2, ..., 11], weekday: [1,2,3,4,5] }

describe(expression: string): string

Get a human-readable description of a cron expression. Returns "Invalid cron expression" if the expression is invalid.

describe("*/5 * * * *"); // "Every 5 minutes"
describe("0 9 * * 1-5"); // "At 9:00 AM, on weekdays"
describe("*/15 3,4 1-4 */3 6"); // Every 15 minutes, at 3 AM or 4 AM, on the 1st through 4th or on Saturdays every 3 months
describe("invalid"); // "Invalid cron expression"

Types

interface CronOptions {
  timezone?: string; // IANA timezone string (e.g., 'America/New_York')
  from?: Date; // Reference date (defaults to now)
}

interface ParsedCron {
  minute: number[]; // 0-59
  hour: number[]; // 0-23
  day: number[]; // 1-31
  month: number[]; // 0-11 (0 = January)
  weekday: number[]; // 0-6 (0 = Sunday)
  dayIsWildcard: boolean;
  weekdayIsWildcard: boolean;
}

Cron Expression Format

* * * * *
│ │ │ │ │
│ │ │ │ └─ Day of Week (0-7, SUN-SAT)
│ │ │ └─── Month (1-12, JAN-DEC)
│ │ └───── Day of Month (1-31)
│ └─────── Hour (0-23)
└───────── Minute (0-59)

Supported Special Characters

• * - Any value
• , - Value list (e.g., 1,3,5)
• - - Range (e.g., 1-5)
• / - Step values (e.g., */5)

ISO 8601 Date Support

cron-fast fully supports ISO 8601 date formats for input:

// All these formats work:
nextRun("0 9 * * *", { from: new Date("2026-03-15T14:30:00Z") }); // UTC
nextRun("0 9 * * *", { from: new Date("2026-03-15T09:30:00-05:00") }); // With offset
nextRun("0 9 * * *", { from: new Date("2026-03-15T14:30:00.500Z") }); // With milliseconds

// Different representations of the same moment produce identical results
const utc = new Date("2026-03-15T14:30:00Z");
const est = new Date("2026-03-15T09:30:00-05:00"); // Same moment
nextRun("0 9 * * *", { from: utc }).getTime() === nextRun("0 9 * * *", { from: est }).getTime(); // true

Note: All returned Date objects are in UTC (ending with Z in .toISOString()). Use .toLocaleString() to display in any timezone.

Bundle Size

cron-fast is extremely lightweight and fully tree-shakeable. Here are the actual bundle sizes for different import scenarios (tested with v3.0.0):

| Import | Raw | Minified | Gzipped | | ------------------------------------------------------ | -------- | -------- | ----------- | | Full bundle (all exports) | 21.47 KB | 9.88 KB | 3.55 KB | | nextRun only | 12.73 KB | 5.79 KB | 2.14 KB | | previousRun only | 12.73 KB | 5.79 KB | 2.14 KB | | nextRuns only | 13.11 KB | 5.94 KB | 2.21 KB | | isValid only | 4.44 KB | 2.22 KB | 984 B | | parse only | 4.32 KB | 2.18 KB | 961 B | | describe only | 11.54 KB | 5.57 KB | 2.11 KB | | isMatch only | 6.04 KB | 2.96 KB | 1.26 KB | | Validation only (isValid + parse) | 4.45 KB | 2.23 KB | 986 B | | Scheduling only (nextRun + previousRun + nextRuns) | 13.51 KB | 6.12 KB | 2.22 KB |

Import only what you need:

// Small bundle - only validation
import { isValid } from "cron-fast";

// Medium bundle - one function + dependencies
import { nextRun } from "cron-fast";

// Full bundle - everything
import * as cron from "cron-fast";

Advanced Usage

Working with Timezones

// Cron expression is interpreted in the specified timezone
const next = nextRun("0 9 * * *", { timezone: "America/New_York" });

// The returned Date is always UTC internally
console.log(next.toISOString()); // "2026-03-15T13:00:00.000Z" (9 AM EDT = 1 PM UTC)

// Display in any timezone
console.log(next.toLocaleString("en-US", { timeZone: "America/New_York" }));
// "3/15/2026, 9:00:00 AM"

Multiple Executions

// Get next 10 runs
const runs = nextRuns("0 */6 * * *", 10); // Every 6 hours

// With timezone
const runsNY = nextRuns("0 9 * * 1-5", 5, { timezone: "America/New_York" });
// Next 5 weekday mornings in New York

Validation and Parsing

// Functions throw on invalid input, but you can pre-validate user input
if (!isValid(userInput)) {
  console.log("Invalid cron expression");
  return;
}

// Or use try/catch
try {
  const next = nextRun(userInput);
} catch (e) {
  console.log("Invalid cron expression");
}

// Parse to see what it means
const parsed = parse("*/15 9-17 * * 1-5");
console.log(parsed);
// {
//   minute: [0, 15, 30, 45],
//   hour: [9, 10, 11, 12, 13, 14, 15, 16, 17],
//   day: [1-31],
//   month: [1-12],
//   weekday: [1, 2, 3, 4, 5]
// }

Check if Date Matches

const now = new Date();

if (isMatch("0 9 * * 1-5", now)) {
  console.log("It's 9 AM on a weekday!");
}

// With timezone
if (isMatch("0 9 * * *", now, { timezone: "America/New_York" })) {
  console.log("It's 9 AM in New York!");
}

Tips & Gotchas

• Invalid input throws: Most functions (nextRun, previousRun, nextRuns, isMatch, parse) throw an error for invalid cron expressions. nextRun, previousRun, nextRuns, and isMatch also throw for invalid timezones. Use isValid() to pre-validate user input, or wrap calls in try/catch. Note: describe() returns "Invalid cron expression" instead of throwing.
• 5-field format only: cron-fast does not support 6-field cron (with seconds). Use standard 5-field format.
• Month indexing: Input uses cron convention (1-12), but ParsedCron.month uses JavaScript convention (0-11)
• Impossible dates are invalid: Expressions like 0 0 31 2 * (February 31st) are treated as invalid since they can never match.
• Timezone handling: The cron expression is interpreted in the timezone you specify, but the returned Date is always in UTC
• Daylight saving time: Use IANA timezone names (like "America/New_York") instead of abbreviations (like "EST")
• Day 0 and 7: Both represent Sunday in the day-of-week field
• Ranges are inclusive: 1-5 includes both 1 and 5

Performance

cron-fast is designed for speed and efficiency. Here's how it compares to popular alternatives:

Tested with cron-fast v3.0.0, croner v10.0.1, cron-parser v5.5.0, cron-schedule v6.0.0 on Node.js v22.18.0

| Operation | cron-fast | croner | cron-parser | cron-schedule | | ------------ | --------------- | --------- | ----------- | ------------- | | Next run | 911k ops/s | 31k ops/s | 34k ops/s | 352k ops/s | | Previous run | 1003k ops/s | 32k ops/s | 39k ops/s | 399k ops/s | | Validation | 1958k ops/s | 34k ops/s | 97k ops/s | 462k ops/s | | Parsing | 1982k ops/s | 35k ops/s | 98k ops/s | 469k ops/s |

See detailed benchmarks and feature comparison (including Deno and Bun runtimes) for more information.

Run benchmarks yourself: pnpm benchmark

Contributing

Contributions are welcome! Please read our Contributing Guide for details on our code of conduct and the process for submitting pull requests.

Contributors

• Kasparas Bilkis - Creator and maintainer

License

MIT - see LICENSE for details.