mirror of https://github.com/oven-sh/bun synced 2026-02-17 14:22:01 +00:00

Files

Jarred Sumner c674cc644f feat(cron): add Bun.cron API for OS-level cron jobs and expression parsing

Adds `Bun.cron()`, `Bun.cron.remove()`, and `Bun.cron.parse()` — a
complete API for registering OS-level cron jobs and parsing cron
expressions from JavaScript.

**Bun.cron(path, schedule, title)** registers a cron job that runs a
JS/TS module on a schedule, using the platform's native scheduler:
- Linux: crontab
- macOS: launchd (plist + StartCalendarInterval)
- Windows: Task Scheduler (schtasks)

The target module exports a `scheduled(controller)` handler following
the Cloudflare Workers Cron Triggers API.

**Bun.cron.parse(expression, relativeDate?)** parses a cron expression
and returns the next matching UTC Date. Supports:
- Standard 5-field expressions (minute hour day month weekday)
- Named days: SUN-SAT, Sunday-Saturday (case-insensitive)
- Named months: JAN-DEC, January-December (case-insensitive)
- Sunday as 7 (normalized to 0)
- Predefined nicknames: @yearly, @annually, @monthly, @weekly, @daily,
  @midnight, @hourly
- POSIX OR logic: when both day-of-month and day-of-week are specified
  (neither is *), either matching is sufficient

The parser uses a bitset representation (u64/u32/u16/u8 per field) for
efficient matching. The next-occurrence algorithm advances by the
largest non-matching unit (month > day > hour > minute) and normalizes
via JSC's UTC date functions on each iteration.

Expressions are normalized to numeric form before platform registration,
so named values like "Monday" or "@daily" produce valid crontab entries.

Also fixes a pre-existing bug in filterCrontab where substring matching
(indexOf) could cause removing job "test" to also remove "test-cleanup".
Changed to exact line matching.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

2026-02-13 22:45:03 +01:00