@warlock.js/scheduler 5.19.1 → 5.20.0

package/skills/schedule-fluently/SKILL.md

@@ -1,141 +1,141 @@
----
-name: schedule-fluently
-description: "Fluent scheduling API in @warlock.js/scheduler; use when you need to schedule fluently."
----
-
-# Fluent scheduling API
-
-Chainable methods on a `Job` instance. Each method returns `this` for chaining; each call recomputes `job.nextRun` on the spot.
-
-## Preset intervals
-
-| Method               | Equivalent of            | Notes                          |
-| -------------------- | ------------------------ | ------------------------------ |
-| `.everySecond()`     | `.every(1, "second")`    | High frequency — use sparingly |
-| `.everySeconds(N)`   | `.every(N, "second")`    |                                |
-| `.everyMinute()`     | `.every(1, "minute")`    |                                |
-| `.everyMinutes(N)`   | `.every(N, "minute")`    |                                |
-| `.everyHour()`       | `.every(1, "hour")`      |                                |
-| `.everyHours(N)`     | `.every(N, "hour")`      |                                |
-| `.everyDay()`        | `.every(1, "day")`       | Same as `.daily()`             |
-| `.daily()`           | `.every(1, "day")`       |                                |
-| `.twiceDaily()`      | `.every(12, "hour")`     | Every 12 hours                 |
-| `.everyWeek()`       | `.every(1, "week")`      | Same as `.weekly()`            |
-| `.weekly()`          | `.every(1, "week")`      |                                |
-| `.everyMonth()`      | `.every(1, "month")`     | Same as `.monthly()`           |
-| `.monthly()`         | `.every(1, "month")`     |                                |
-| `.everyYear()`       | `.every(1, "year")`      | Same as `.yearly()`            |
-| `.yearly()`          | `.every(1, "year")`      |                                |
-| `.always()`          | `.every(1, "minute")`    | Continuous "tick" jobs         |
-
-## Custom intervals — `.every(value, unit)`
-
-```ts
-job("t", task).every(5, "minute");
-job("t", task).every(2, "hour");
-job("t", task).every(3, "day");
-```
-
-Units: `"second" | "minute" | "hour" | "day" | "week" | "month" | "year"`.
-
-**Validation.** `every(value, unit)` throws at definition time if `value` is `0`, negative, `NaN`, or `Infinity`. This guards against the misconfigured-interval class of bugs that would otherwise spin the scheduler.
-
-## Target a specific time — `.at("HH:mm" | "HH:mm:ss")`
-
-```ts
-job("nightly", fn).daily().at("03:00");
-job("midday",  fn).daily().at("12:30:15");
-```
-
-**Validation.** `.at()` throws if the format is malformed (`"foo"`, `"9-30"`), or any component is out of range (hour > 23, minute > 59, second > 59).
-
-## Target a specific day — `.on(day)`
-
-Day-of-week (string) or day-of-month (number 1–31):
-
-```ts
-job("monday-standup", task).weekly().on("monday");
-job("mid-month-sync", task).monthly().on(15);
-job("end-of-month",   task).monthly().on(31);    // see beginOf/endOf for the right way
-```
-
-Valid day-of-week strings: `"sunday"`, `"monday"`, `"tuesday"`, `"wednesday"`, `"thursday"`, `"friday"`, `"saturday"`.
-
-**Validation.** Numeric `on(N)` throws if `N < 1 || N > 31`.
-
-**Gotcha.** `monthly().on(31)` clamps to the actual month length in dayjs — February runs are unpredictable. Use `endOf("month")` for "last day" semantics instead.
-
-## Boundary shortcuts — `.beginOf(type)` / `.endOf(type)`
-
-Both accept `"day" | "month" | "year"`.
-
-| Method               | Fires at                                          |
-| -------------------- | ------------------------------------------------- |
-| `beginOf("day")`     | 00:00 every day                                   |
-| `endOf("day")`       | 23:59 every day                                   |
-| `beginOf("month")`   | 1st of every month at 00:00                       |
-| `endOf("month")`     | Last day of every month at 23:59 (**dynamic**)    |
-| `beginOf("year")`    | January 1 at 00:00 every year                     |
-| `endOf("year")`      | December 31 at 23:59 every year                   |
-
-**`endOf("month")` is dynamic** — recomputes per cycle, so a job defined in February (28 days) still fires on March 31, April 30, etc. Leap years pick Feb 29 correctly.
-
-**`beginOf("year")` / `endOf("year")` lock the month** — always Jan 1 / Dec 31, never "1st/31st of whatever month the job was defined in."
-
-## Cron is an alternative, not an addition
-
-`.cron("…")` clears any prior interval/`at`/`on`/`beginOf`/`endOf` config — and vice versa. They're mutually exclusive. See [`@warlock.js/scheduler/schedule-with-cron/SKILL.md`](@warlock.js/scheduler/schedule-with-cron/SKILL.md).
-
-## Chaining order doesn't matter (for the most part)
-
-Every fluent method recomputes `nextRun` at the end. Putting `.at()` before `.daily()` produces the same schedule as putting `.daily()` before `.at()` — but for readability, the conventional order is **interval → day → time → timezone → execution options**:
-
-```ts
-job("good", fn)
-  .weekly()              // interval
-  .on("monday")          // day
-  .at("09:00")           // time
-  .inTimezone("UTC")     // timezone
-  .preventOverlap()      // execution
-  .retry(3, 1000);       // execution
-```
-
-## Inline registration — `scheduler.newJob()`
-
-For one-liners, the scheduler exposes a `newJob()` shortcut that creates, registers, and returns the job in one call:
-
-```ts
-scheduler
-  .newJob("cleanup", cleanupFn)
-  .daily()
-  .at("03:00");
-```
-
-To register several pre-built jobs at once, `scheduler.addJobs([...])` is the batch counterpart to `addJob` (both are chainable and preserve insertion order):
-
-```ts
-scheduler.addJobs([
-  job("cleanup", cleanupFn).daily().at("03:00"),
-  job("reports", sendReports).weekly().on("monday").at("09:00"),
-]);
-```
-
-If the scheduler is already running, every job added via `addJob` / `addJobs` is prepared on the spot (its `nextRun` is computed) so it fires on the next tick.
-
-## Reading state at runtime
-
-```ts
-const j = scheduler.getJob("nightly-cleanup");
-
-j?.nextRun?.toISOString();   // next scheduled run (Dayjs)
-j?.lastRun?.toISOString();   // last attempt — success OR failure
-j?.isRunning;                // currently executing?
-j?.intervals;                // { every?, day?, dayOfMonthMode?, month?, time? } (readonly)
-j?.cronExpression;           // null if using fluent API
-```
-
-## See also
-
-- [`@warlock.js/scheduler/schedule-with-cron/SKILL.md`](@warlock.js/scheduler/schedule-with-cron/SKILL.md) — when the fluent API isn't enough
-- [`@warlock.js/scheduler/configure-retry-and-overlap/SKILL.md`](@warlock.js/scheduler/configure-retry-and-overlap/SKILL.md) — `.retry()` and `.preventOverlap()` on the same job
-- [`@warlock.js/scheduler/pin-schedule-timezone/SKILL.md`](@warlock.js/scheduler/pin-schedule-timezone/SKILL.md) — `.inTimezone()`
+---
+name: schedule-fluently
+description: 'Build a job schedule via `every*` / `daily` / `weekly` / `monthly` / `at` / `on` / `beginOf` / `endOf`. Triggers: `.everyMinutes`, `.daily`, `.weekly`, `.monthly`, `.at`, `.on`, `.every`, `.beginOf`, `.endOf`, `.twiceDaily`, `scheduler.newJob`; "run every 5 minutes", "daily at 3am", "monday standup", "first of every month", "last day of month"; typical import `import { job, scheduler } from "@warlock.js/scheduler"`. Skip: cron — `@warlock.js/scheduler/schedule-with-cron/SKILL.md`; timezone — `@warlock.js/scheduler/pin-schedule-timezone/SKILL.md`; retry — `@warlock.js/scheduler/configure-retry-and-overlap/SKILL.md`; competing `node-cron`, `node-schedule`, `agenda`; native `setInterval`.'
+---
+
+# Fluent scheduling API
+
+Chainable methods on a `Job` instance. Each method returns `this` for chaining; each call recomputes `job.nextRun` on the spot.
+
+## Preset intervals
+
+| Method               | Equivalent of            | Notes                          |
+| -------------------- | ------------------------ | ------------------------------ |
+| `.everySecond()`     | `.every(1, "second")`    | High frequency — use sparingly |
+| `.everySeconds(N)`   | `.every(N, "second")`    |                                |
+| `.everyMinute()`     | `.every(1, "minute")`    |                                |
+| `.everyMinutes(N)`   | `.every(N, "minute")`    |                                |
+| `.everyHour()`       | `.every(1, "hour")`      |                                |
+| `.everyHours(N)`     | `.every(N, "hour")`      |                                |
+| `.everyDay()`        | `.every(1, "day")`       | Same as `.daily()`             |
+| `.daily()`           | `.every(1, "day")`       |                                |
+| `.twiceDaily()`      | `.every(12, "hour")`     | Every 12 hours                 |
+| `.everyWeek()`       | `.every(1, "week")`      | Same as `.weekly()`            |
+| `.weekly()`          | `.every(1, "week")`      |                                |
+| `.everyMonth()`      | `.every(1, "month")`     | Same as `.monthly()`           |
+| `.monthly()`         | `.every(1, "month")`     |                                |
+| `.everyYear()`       | `.every(1, "year")`      | Same as `.yearly()`            |
+| `.yearly()`          | `.every(1, "year")`      |                                |
+| `.always()`          | `.every(1, "minute")`    | Continuous "tick" jobs         |
+
+## Custom intervals — `.every(value, unit)`
+
+```ts
+job("t", task).every(5, "minute");
+job("t", task).every(2, "hour");
+job("t", task).every(3, "day");
+```
+
+Units: `"second" | "minute" | "hour" | "day" | "week" | "month" | "year"`.
+
+**Validation.** `every(value, unit)` throws at definition time if `value` is `0`, negative, `NaN`, or `Infinity`. This guards against the misconfigured-interval class of bugs that would otherwise spin the scheduler.
+
+## Target a specific time — `.at("HH:mm" | "HH:mm:ss")`
+
+```ts
+job("nightly", fn).daily().at("03:00");
+job("midday",  fn).daily().at("12:30:15");
+```
+
+**Validation.** `.at()` throws if the format is malformed (`"foo"`, `"9-30"`), or any component is out of range (hour > 23, minute > 59, second > 59).
+
+## Target a specific day — `.on(day)`
+
+Day-of-week (string) or day-of-month (number 1–31):
+
+```ts
+job("monday-standup", task).weekly().on("monday");
+job("mid-month-sync", task).monthly().on(15);
+job("end-of-month",   task).monthly().on(31);    // see beginOf/endOf for the right way
+```
+
+Valid day-of-week strings: `"sunday"`, `"monday"`, `"tuesday"`, `"wednesday"`, `"thursday"`, `"friday"`, `"saturday"`.
+
+**Validation.** Numeric `on(N)` throws if `N < 1 || N > 31`.
+
+**Gotcha.** `monthly().on(31)` clamps to the actual month length in dayjs — February runs are unpredictable. Use `endOf("month")` for "last day" semantics instead.
+
+## Boundary shortcuts — `.beginOf(type)` / `.endOf(type)`
+
+Both accept `"day" | "month" | "year"`.
+
+| Method               | Fires at                                          |
+| -------------------- | ------------------------------------------------- |
+| `beginOf("day")`     | 00:00 every day                                   |
+| `endOf("day")`       | 23:59 every day                                   |
+| `beginOf("month")`   | 1st of every month at 00:00                       |
+| `endOf("month")`     | Last day of every month at 23:59 (**dynamic**)    |
+| `beginOf("year")`    | January 1 at 00:00 every year                     |
+| `endOf("year")`      | December 31 at 23:59 every year                   |
+
+**`endOf("month")` is dynamic** — recomputes per cycle, so a job defined in February (28 days) still fires on March 31, April 30, etc. Leap years pick Feb 29 correctly.
+
+**`beginOf("year")` / `endOf("year")` lock the month** — always Jan 1 / Dec 31, never "1st/31st of whatever month the job was defined in."
+
+## Cron is an alternative, not an addition
+
+`.cron("…")` clears any prior interval/`at`/`on`/`beginOf`/`endOf` config — and vice versa. They're mutually exclusive. See [`@warlock.js/scheduler/schedule-with-cron/SKILL.md`](@warlock.js/scheduler/schedule-with-cron/SKILL.md).
+
+## Chaining order doesn't matter (for the most part)
+
+Every fluent method recomputes `nextRun` at the end. Putting `.at()` before `.daily()` produces the same schedule as putting `.daily()` before `.at()` — but for readability, the conventional order is **interval → day → time → timezone → execution options**:
+
+```ts
+job("good", fn)
+  .weekly()              // interval
+  .on("monday")          // day
+  .at("09:00")           // time
+  .inTimezone("UTC")     // timezone
+  .preventOverlap()      // execution
+  .retry(3, 1000);       // execution
+```
+
+## Inline registration — `scheduler.newJob()`
+
+For one-liners, the scheduler exposes a `newJob()` shortcut that creates, registers, and returns the job in one call:
+
+```ts
+scheduler
+  .newJob("cleanup", cleanupFn)
+  .daily()
+  .at("03:00");
+```
+
+To register several pre-built jobs at once, `scheduler.addJobs([...])` is the batch counterpart to `addJob` (both are chainable and preserve insertion order):
+
+```ts
+scheduler.addJobs([
+  job("cleanup", cleanupFn).daily().at("03:00"),
+  job("reports", sendReports).weekly().on("monday").at("09:00"),
+]);
+```
+
+If the scheduler is already running, every job added via `addJob` / `addJobs` is prepared on the spot (its `nextRun` is computed) so it fires on the next tick.
+
+## Reading state at runtime
+
+```ts
+const j = scheduler.getJob("nightly-cleanup");
+
+j?.nextRun?.toISOString();   // next scheduled run (Dayjs)
+j?.lastRun?.toISOString();   // last attempt — success OR failure
+j?.isRunning;                // currently executing?
+j?.intervals;                // { every?, day?, dayOfMonthMode?, month?, time? } (readonly)
+j?.cronExpression;           // null if using fluent API
+```
+
+## See also
+
+- [`@warlock.js/scheduler/schedule-with-cron/SKILL.md`](@warlock.js/scheduler/schedule-with-cron/SKILL.md) — when the fluent API isn't enough
+- [`@warlock.js/scheduler/configure-retry-and-overlap/SKILL.md`](@warlock.js/scheduler/configure-retry-and-overlap/SKILL.md) — `.retry()` and `.preventOverlap()` on the same job
+- [`@warlock.js/scheduler/pin-schedule-timezone/SKILL.md`](@warlock.js/scheduler/pin-schedule-timezone/SKILL.md) — `.inTimezone()`

package/skills/schedule-with-cron/SKILL.md

@@ -1,123 +1,123 @@
----
-name: schedule-with-cron
-description: "Cron expressions in @warlock.js/scheduler; use when you need to schedule with cron."
----
-
-# Cron expressions
-
-The escape hatch when the fluent API can't express a schedule. Activating `.cron()` clears any prior fluent config — the two are mutually exclusive.
-
-## 5-field syntax
-
-```
-┌───────────── minute        (0-59)
-│ ┌───────────── hour          (0-23)
-│ │ ┌───────────── day-of-month (1-31)
-│ │ │ ┌───────────── month        (1-12)
-│ │ │ │ ┌───────────── day-of-week  (0-6, Sunday = 0)
-│ │ │ │ │
-* * * * *
-```
-
-**Note:** Sunday is `0` only. Some cron dialects also accept `7` for Sunday — this parser does NOT.
-
-## Operators
-
-| Syntax    | Meaning                       | Example          |
-| --------- | ----------------------------- | ---------------- |
-| `*`       | Any value (full range)        | `* * * * *`      |
-| `5`       | Single value                  | `30 14 * * *`    |
-| `1,3,5`   | List                          | `0,30 * * * *`   |
-| `1-5`     | Inclusive range               | `0 9-17 * * *`   |
-| `*/N`     | Step over the wildcard        | `*/5 * * * *`    |
-| `A-B/N`   | Step over a range             | `0 1-10/2 * * *` |
-
-**Not supported (yet):** named tokens (`MON-FRI`, `JAN-DEC`), special strings (`@daily`, `@hourly`, `@reboot`), seconds field (6-field), Quartz modifiers (`L`, `W`, `#`).
-
-## Day-of-month + day-of-week — Vixie OR semantics
-
-When **both** `dayOfMonth` AND `dayOfWeek` are restricted (neither is `*`), the date matches if **either** constraint matches. When one is `*` and the other is restricted, only the restricted one matters.
-
-```ts
-// "1st of month OR any Monday" — fires on the 1st even if not a Monday,
-// AND fires on any Monday even if not the 1st.
-job("digest", sendDigest).cron("0 0 1 * 1");
-
-// "15th of month" — DOW is *, so only DOM applies. Fires only on the 15th.
-job("midmonth", task).cron("0 0 15 * *");
-
-// "Every Monday" — DOM is *, so only DOW applies. Fires only on Mondays.
-job("monday-only", task).cron("0 0 * * 1");
-```
-
-This matches Vixie cron (the de facto standard on Unix). Migrating an existing cron table from `crontab(5)` should "just work" semantically.
-
-## Common recipes
-
-```ts
-// Every 5 minutes
-.cron("*/5 * * * *")
-
-// Top of every hour
-.cron("0 * * * *")
-
-// Every weekday at 9 AM
-.cron("0 9 * * 1-5")
-
-// 2:30 PM on the 15th of every month
-.cron("30 14 15 * *")
-
-// Every 2 hours, on the hour
-.cron("0 */2 * * *")
-
-// First day of each month at midnight
-.cron("0 0 1 * *")
-```
-
-## Validation
-
-`new CronParser(expr)` and `.cron(expr)` both throw at definition time on:
-
-- Wrong field count (must be exactly 5)
-- Non-numeric values, out-of-range values, inverted ranges (`5-1`)
-- Step `<= 0`, non-numeric step
-- Impossible day-of-month / month combinations — a date that can never occur, e.g. `0 0 30 2 *` (Feb 30) or `0 0 31 4 *` (April has 30 days). Rejected with an `Impossible cron expression` error.
-
-```ts
-new CronParser("0 0 30 2 *"); // throws: Impossible cron expression — Feb never has a 30th
-new CronParser("0 0 31 4 *"); // throws: April has only 30 days
-```
-
-**Leap years and the OR escape hatch.** `0 0 29 2 *` (Feb 29) is **accepted** — it occurs in leap years. And when day-of-week is also restricted, Vixie OR semantics keep the schedule alive via the weekday path, so the combo is never rejected: `0 0 30 2 1` (Feb 30 OR any Monday) parses fine and fires on Mondays.
-
-Throws are eager — bad expressions fail fast at construction, not at first tick.
-
-## Standalone preview — `parseCron()`
-
-The `CronParser` class is exported as a utility for ad-hoc next-run calculation, separate from any job:
-
-```ts
-import { parseCron } from "@warlock.js/scheduler";
-import dayjs from "dayjs";
-
-const parser = parseCron("0 9 * * 1-5");
-
-parser.nextRun().toISOString();              // next weekday at 9 AM
-parser.nextRun(dayjs("2026-12-31")).format(); // from a specific anchor
-
-parser.matches(dayjs());                     // is "now" a fire moment?
-
-parser.fields;                                // parsed numeric arrays
-parser.expression;                            // original string
-```
-
-Impossible expressions are rejected eagerly at construction (see Validation), so `nextRun(from?)` always resolves a satisfiable expression within a year — its one-year scan bound is just a defensive backstop, never the path that catches a bad expression.
-
-## Timezone interaction
-
-If the job has `.inTimezone(tz)`, the cron parser receives a timezone-aware `dayjs` object — so `0 9 * * *` with `.inTimezone("Asia/Tokyo")` fires at 09:00 JST. See [`@warlock.js/scheduler/pin-schedule-timezone/SKILL.md`](@warlock.js/scheduler/pin-schedule-timezone/SKILL.md).
-
-## See also
-
-- [`@warlock.js/scheduler/schedule-fluently/SKILL.md`](@warlock.js/scheduler/schedule-fluently/SKILL.md) — the higher-level alternative for human-readable schedules
-- [`@warlock.js/scheduler/pin-schedule-timezone/SKILL.md`](@warlock.js/scheduler/pin-schedule-timezone/SKILL.md) — pinning a cron schedule to a wall-clock timezone
+---
+name: schedule-with-cron
+description: 'Write `.cron(''…'')` expressions — 5-field syntax, operators (`*` `,` `-` `/`), Vixie OR semantics for DOM / DOW, `parseCron()` preview utility. Triggers: `.cron`, `parseCron`, `CronParser`, `*/5 * * * *`, `0 9 * * 1-5`; "write a cron expression", "every weekday at 9am cron", "preview next cron run", "migrate crontab(5) entry"; typical import `import { parseCron } from "@warlock.js/scheduler"`. Skip: human-readable schedules — `@warlock.js/scheduler/schedule-fluently/SKILL.md`; timezone — `@warlock.js/scheduler/pin-schedule-timezone/SKILL.md`; competing libs `node-cron`, `cron`, `croner`, `cronstrue`.'
+---
+
+# Cron expressions
+
+The escape hatch when the fluent API can't express a schedule. Activating `.cron()` clears any prior fluent config — the two are mutually exclusive.
+
+## 5-field syntax
+
+```
+┌───────────── minute        (0-59)
+│ ┌───────────── hour          (0-23)
+│ │ ┌───────────── day-of-month (1-31)
+│ │ │ ┌───────────── month        (1-12)
+│ │ │ │ ┌───────────── day-of-week  (0-6, Sunday = 0)
+│ │ │ │ │
+* * * * *
+```
+
+**Note:** Sunday is `0` only. Some cron dialects also accept `7` for Sunday — this parser does NOT.
+
+## Operators
+
+| Syntax    | Meaning                       | Example          |
+| --------- | ----------------------------- | ---------------- |
+| `*`       | Any value (full range)        | `* * * * *`      |
+| `5`       | Single value                  | `30 14 * * *`    |
+| `1,3,5`   | List                          | `0,30 * * * *`   |
+| `1-5`     | Inclusive range               | `0 9-17 * * *`   |
+| `*/N`     | Step over the wildcard        | `*/5 * * * *`    |
+| `A-B/N`   | Step over a range             | `0 1-10/2 * * *` |
+
+**Not supported (yet):** named tokens (`MON-FRI`, `JAN-DEC`), special strings (`@daily`, `@hourly`, `@reboot`), seconds field (6-field), Quartz modifiers (`L`, `W`, `#`).
+
+## Day-of-month + day-of-week — Vixie OR semantics
+
+When **both** `dayOfMonth` AND `dayOfWeek` are restricted (neither is `*`), the date matches if **either** constraint matches. When one is `*` and the other is restricted, only the restricted one matters.
+
+```ts
+// "1st of month OR any Monday" — fires on the 1st even if not a Monday,
+// AND fires on any Monday even if not the 1st.
+job("digest", sendDigest).cron("0 0 1 * 1");
+
+// "15th of month" — DOW is *, so only DOM applies. Fires only on the 15th.
+job("midmonth", task).cron("0 0 15 * *");
+
+// "Every Monday" — DOM is *, so only DOW applies. Fires only on Mondays.
+job("monday-only", task).cron("0 0 * * 1");
+```
+
+This matches Vixie cron (the de facto standard on Unix). Migrating an existing cron table from `crontab(5)` should "just work" semantically.
+
+## Common recipes
+
+```ts
+// Every 5 minutes
+.cron("*/5 * * * *")
+
+// Top of every hour
+.cron("0 * * * *")
+
+// Every weekday at 9 AM
+.cron("0 9 * * 1-5")
+
+// 2:30 PM on the 15th of every month
+.cron("30 14 15 * *")
+
+// Every 2 hours, on the hour
+.cron("0 */2 * * *")
+
+// First day of each month at midnight
+.cron("0 0 1 * *")
+```
+
+## Validation
+
+`new CronParser(expr)` and `.cron(expr)` both throw at definition time on:
+
+- Wrong field count (must be exactly 5)
+- Non-numeric values, out-of-range values, inverted ranges (`5-1`)
+- Step `<= 0`, non-numeric step
+- Impossible day-of-month / month combinations — a date that can never occur, e.g. `0 0 30 2 *` (Feb 30) or `0 0 31 4 *` (April has 30 days). Rejected with an `Impossible cron expression` error.
+
+```ts
+new CronParser("0 0 30 2 *"); // throws: Impossible cron expression — Feb never has a 30th
+new CronParser("0 0 31 4 *"); // throws: April has only 30 days
+```
+
+**Leap years and the OR escape hatch.** `0 0 29 2 *` (Feb 29) is **accepted** — it occurs in leap years. And when day-of-week is also restricted, Vixie OR semantics keep the schedule alive via the weekday path, so the combo is never rejected: `0 0 30 2 1` (Feb 30 OR any Monday) parses fine and fires on Mondays.
+
+Throws are eager — bad expressions fail fast at construction, not at first tick.
+
+## Standalone preview — `parseCron()`
+
+The `CronParser` class is exported as a utility for ad-hoc next-run calculation, separate from any job:
+
+```ts
+import { parseCron } from "@warlock.js/scheduler";
+import dayjs from "dayjs";
+
+const parser = parseCron("0 9 * * 1-5");
+
+parser.nextRun().toISOString();              // next weekday at 9 AM
+parser.nextRun(dayjs("2026-12-31")).format(); // from a specific anchor
+
+parser.matches(dayjs());                     // is "now" a fire moment?
+
+parser.fields;                                // parsed numeric arrays
+parser.expression;                            // original string
+```
+
+Impossible expressions are rejected eagerly at construction (see Validation), so `nextRun(from?)` always resolves a satisfiable expression within a year — its one-year scan bound is just a defensive backstop, never the path that catches a bad expression.
+
+## Timezone interaction
+
+If the job has `.inTimezone(tz)`, the cron parser receives a timezone-aware `dayjs` object — so `0 9 * * *` with `.inTimezone("Asia/Tokyo")` fires at 09:00 JST. See [`@warlock.js/scheduler/pin-schedule-timezone/SKILL.md`](@warlock.js/scheduler/pin-schedule-timezone/SKILL.md).
+
+## See also
+
+- [`@warlock.js/scheduler/schedule-fluently/SKILL.md`](@warlock.js/scheduler/schedule-fluently/SKILL.md) — the higher-level alternative for human-readable schedules
+- [`@warlock.js/scheduler/pin-schedule-timezone/SKILL.md`](@warlock.js/scheduler/pin-schedule-timezone/SKILL.md) — pinning a cron schedule to a wall-clock timezone