stacks-cron

# Stacks Cron Low-level cron expression parser and OS-level job registration. For most scheduling tasks, use `@stacksjs/scheduler` instead. ## Key Paths - Core package: `storage/framework/core/cron/src/` - Package: `@stacksjs/cron` ## Source Files ``` cron/src/ ├── index.ts # Re-exports ├── parser.ts # Cron expression parser (parseCron) ├── types.ts # Type definitions └── bun-cron.d.ts # Bun.cron type declarations ``` ## API ### parse ```typescript import { parse } from '@stacksjs/cron' function parse(expression: string, relativeDate?: Date | number): Date | null ``` Parses a cron expression and returns the next matching UTC date. Falls back to native `Bun.cron.parse()` if available. ```typescript parse('0 0 * * *') // Next midnight UTC parse('*/5 * * * *') // Next 5-minute mark parse('0 9 * * MON-FRI') // Next weekday at 9 AM parse('0 0 1 * *', new Date()) // Next 1st of month from now ``` ### parseCron (Native Implementation) ```typescript import { parseCron } from '@stacksjs/cron' function parseCron(expression: string, relativeDate?: Date | number): Date | null ``` Full 5-field cron parser supporting: | Field | Values | Special Characters | |-------|--------|--------------------| | Minute | 0-59 | `*` `,` `-` `/` | | Hour | 0-23 | `*` `,` `-` `/` | | Day of Month | 1-31 | `*` `,` `-` `/` | | Month | 1-12 or JAN-DEC | `*` `,` `-` `/` | | Day of Week | 0-6 or SUN-SAT | `*` `,` `-` `/` | ### Nicknames | Nickname | Equivalent | |----------|-----------| | `@yearly` / `@annually` | `0 0 1 1 *` | | `@monthly` | `0 0 1 * *` | | `@weekly` | `0 0 * * 0` | | `@daily` / `@midnight` | `0 0 * * *` | | `@hourly` | `0 * * * *` | ### register ```typescript import { register } from '@stacksjs/cron' async function register(path: string, schedule: string, title: string): Promise<void> ``` Registers an OS-level cron job. Requires Bun.cron support. - `path` — path to the script (must export `scheduled(controller)` handler) - `schedule` — cron expression - `title` — job identifier (alphanumeric, hyphens, underscores only) ### remove ```typescript import { remove } from '@stacksjs/cron' async function remove(title: string): Promise<void> ``` Removes a registered cron job by title. ## Types ```typescript type CatchCallbackFn = (error: Error) => void type ProtectCallbackFn = () => void type IntRange<Min, Max> // TypeScript utility for bounded integer ranges ``` ## Cron Expression Examples ```typescript parse('*/5 * * * *') // Every 5 minutes parse('0 */2 * * *') // Every 2 hours parse('0 9,17 * * *') // At 9 AM and 5 PM parse('0 0 * * MON') // Every Monday at midnight parse('0 0 1,15 * *') // 1st and 15th of each month parse('30 4 * * SUN') // Sundays at 4:30 AM ``` ## Gotchas - **Low-level primitive** — for most use cases, prefer `@stacksjs/scheduler` which provides `.daily()`, `.hourly()`, etc. - **UTC dates** — `parse()` returns UTC dates, not local time - **POSIX OR logic** — when both dayOfMonth and dayOfWeek are specified (not `*`), matches if EITHER matches - **Named values** — supports JAN-DEC and SUN-SAT (case-insensitive) - **Searches up to ~4 years** — parser iterates forward to find the next match, stops after ~4 years - **OS-level registration** — `register()` requires Bun.cron support (not available in all environments) - **`register()` scripts must export `scheduled()`** — the target file must have a `scheduled(controller)` handler