@warlock.js/scheduler 5.30.0 → 5.31.0

package/llms-full.txt

@@ -18,18 +18,11 @@ Two independent execution-control concerns on a single `Job`. They compose clean
 ## `.retry(maxRetries, delay?, backoffMultiplier?)`
 
 ```ts
-job("send-report", sendReport)
-  .daily()
-  .at("08:00")
-  .retry(3);                  // 3 retries, 1000ms apart (default delay)
+job("send-report", sendReport).daily().at("08:00").retry(3); // 3 retries, 1000ms apart (default delay)
 
-job("sync", syncInventory)
-  .everyHour()
-  .retry(5, 2000);             // 5 retries, 2000ms each
+job("sync", syncInventory).everyHour().retry(5, 2000); // 5 retries, 2000ms each
 
-job("queue", processQueue)
-  .everyMinutes(10)
-  .retry(5, 1000, 2);          // exponential: 1s → 2s → 4s → 8s → 16s
+job("queue", processQueue).everyMinutes(10).retry(5, 1000, 2); // exponential: 1s → 2s → 4s → 8s → 16s
 ```
 
 **Signature:** `retry(maxRetries: number, delay = 1000, backoffMultiplier?: number): this`
@@ -54,6 +47,7 @@ scheduler.on("job:error", (name, error) => {
 ```
 
 `JobResult.retries`:
+
 - On **success**: the number of failed attempts before the eventual success (0 if first attempt succeeded).
 - On **failure**: equals the configured `maxRetries` (all of them were used).
 
@@ -76,7 +70,7 @@ To **stop** firing after N consecutive failures, do it in user code:
 
 ```ts
 let consecutiveFailures = 0;
-scheduler.on("job:error", name => {
+scheduler.on("job:error", (name) => {
   if (name !== "flaky") return;
   consecutiveFailures++;
   if (consecutiveFailures >= 5) {
@@ -84,7 +78,7 @@ scheduler.on("job:error", name => {
     alert.critical("flaky disabled after 5 failures");
   }
 });
-scheduler.on("job:complete", name => {
+scheduler.on("job:complete", (name) => {
   if (name === "flaky") consecutiveFailures = 0;
 });
 ```
@@ -94,9 +88,7 @@ scheduler.on("job:complete", name => {
 Tells the scheduler to skip a tick if the job is already running.
 
 ```ts
-job("queue", processQueue)
-  .everyMinutes(5)
-  .preventOverlap();
+job("queue", processQueue).everyMinutes(5).preventOverlap();
 ```
 
 **Important nuance.** The scheduler awaits each tick's jobs before scheduling the next tick — so **concurrent same-job runs from the scheduler's own loop are structurally impossible**, regardless of `preventOverlap()`. Where it actually matters: jobs whose callbacks ALSO get invoked outside the scheduler.
@@ -107,7 +99,7 @@ Real-world shapes that benefit:
 // 1) Boot-time recovery sweep before normal scheduling.
 const queueJob = job("queue", processQueueOnce).everyMinutes(5).preventOverlap();
 scheduler.addJob(queueJob);
-queueJob.run().catch(err => log.error({ err }, "boot sweep failed"));
+queueJob.run().catch((err) => log.error({ err }, "boot sweep failed"));
 scheduler.start();
 
 // 2) Admin-triggered manual re-run from a dashboard endpoint.
@@ -121,6 +113,7 @@ app.post("/admin/jobs/:name/run", async (req, res) => {
 ```
 
 If a tick lands while one of these external runs is mid-flight:
+
 - Scheduler emits `job:skip` with reason `"Job is already running"`
 - The tick proceeds without re-entering the job
 
@@ -131,10 +124,7 @@ For a single-process app where the callback is only ever invoked via the schedul
 They compose cleanly. Retry happens WITHIN one fire — if all retries fail, the tick ends and `nextRun` advances. `preventOverlap` matters only between fires.
 
 ```ts
-job("long-flaky", processQueue)
-  .everyMinutes(5)
-  .preventOverlap()
-  .retry(3, 1000, 2);   // up to 1 + 2 + 4 = 7 s of retry delay per fire
+job("long-flaky", processQueue).everyMinutes(5).preventOverlap().retry(3, 1000, 2); // up to 1 + 2 + 4 = 7 s of retry delay per fire
 ```
 
 If retries push the total work past the next interval, `preventOverlap()` ensures the next scheduled tick skips instead of stacking.
@@ -175,25 +165,25 @@ The `Scheduler` extends Node's `EventEmitter` with a fully-typed surface. Wire l
 
 ```ts
 type SchedulerEvents = {
-  "job:start":         [jobName: string];
-  "job:complete":      [jobName: string, result: JobResult];
-  "job:error":         [jobName: string, error: unknown];
-  "job:skip":          [jobName: string, reason: string];
+  "job:start": [jobName: string];
+  "job:complete": [jobName: string, result: JobResult];
+  "job:error": [jobName: string, error: unknown];
+  "job:skip": [jobName: string, reason: string];
   "scheduler:started": [];
   "scheduler:stopped": [];
-  "scheduler:tick":    [timestamp: Date];
+  "scheduler:tick": [timestamp: Date];
 };
 ```
 
-| Event                | When it fires                                                                          |
-| -------------------- | -------------------------------------------------------------------------------------- |
-| `scheduler:started`  | Once, after `.start()` enters the tick loop                                            |
-| `scheduler:stopped`  | When `.stop()` halts the loop. Not emitted if `.stop()` was a no-op (never started)    |
-| `scheduler:tick`     | Every tick — once per `runEvery()` interval (default 1 s). Keep handlers lightweight.  |
-| `job:start`          | Just before a job's callback is first invoked (NOT once per retry)                     |
-| `job:complete`       | When a job finishes successfully (possibly after retries)                              |
-| `job:error`          | When a job exhausts all retries and the final attempt still throws                     |
-| `job:skip`           | When a tick finds the job already running (see retry-and-overlap for when this occurs) |
+| Event               | When it fires                                                                          |
+| ------------------- | -------------------------------------------------------------------------------------- |
+| `scheduler:started` | Once, after `.start()` enters the tick loop                                            |
+| `scheduler:stopped` | When `.stop()` halts the loop. Not emitted if `.stop()` was a no-op (never started)    |
+| `scheduler:tick`    | Every tick — once per `runEvery()` interval (default 1 s). Keep handlers lightweight.  |
+| `job:start`         | Just before a job's callback is first invoked (NOT once per retry)                     |
+| `job:complete`      | When a job finishes successfully (possibly after retries)                              |
+| `job:error`         | When a job exhausts all retries and the final attempt still throws                     |
+| `job:skip`          | When a tick finds the job already running (see retry-and-overlap for when this occurs) |
 
 **Contract for retries.** `job:start` and `job:complete`/`job:error` fire **once per fire**, not once per retry attempt. The retry count surfaces inside the `JobResult` passed to `job:complete`, or as `result.retries === maxRetries` on the failure path.
 
@@ -202,9 +192,9 @@ type SchedulerEvents = {
 ```ts
 type JobResult = {
   success: boolean;
-  duration: number;    // milliseconds, end-to-end including retry waits
-  error?: unknown;     // present when success === false
-  retries?: number;    // attempts that failed before the final outcome
+  duration: number; // milliseconds, end-to-end including retry waits
+  error?: unknown; // present when success === false
+  retries?: number; // attempts that failed before the final outcome
 };
 ```
 
@@ -216,12 +206,12 @@ type JobResult = {
 import type { JobResult } from "@warlock.js/scheduler";
 import { scheduler } from "@warlock.js/scheduler";
 
-scheduler.on("job:start",    name           => log.debug({ name }, "job start"));
+scheduler.on("job:start", (name) => log.debug({ name }, "job start"));
 scheduler.on("job:complete", (name, result: JobResult) => {
   log.info({ name, duration: result.duration, retries: result.retries }, "job complete");
 });
-scheduler.on("job:error",    (name, error)  => log.error({ name, error }, "job failed"));
-scheduler.on("job:skip",     (name, reason) => log.warn({ name, reason }, "job skipped"));
+scheduler.on("job:error", (name, error) => log.error({ name, error }, "job failed"));
+scheduler.on("job:skip", (name, reason) => log.warn({ name, reason }, "job skipped"));
 ```
 
 `.on()`, `.once()`, `.off()` are all type-narrowed via `SchedulerEvents`.
@@ -233,6 +223,7 @@ scheduler.on("job:skip",     (name, reason) => log.warn({ name, reason }, "job s
 Prepares every registered job (computes initial `nextRun`) and enters the tick loop. Emits `scheduler:started`.
 
 Throws if:
+
 - already running (`"Scheduler is already running."`)
 - zero jobs registered (`"Cannot start scheduler with no jobs."`)
 
@@ -268,7 +259,7 @@ import { logger } from "./logger";
 import { metrics } from "./metrics";
 import { alerts } from "./alerts";
 
-scheduler.on("job:start", name => metrics.increment(`job.start.${name}`));
+scheduler.on("job:start", (name) => metrics.increment(`job.start.${name}`));
 
 scheduler.on("job:complete", (name, result) => {
   metrics.increment(`job.success.${name}`);
@@ -295,20 +286,20 @@ scheduler.start();
 ## Inspection at runtime
 
 ```ts
-scheduler.isRunning;             // boolean
-scheduler.jobCount;              // number of registered jobs
-scheduler.list();                // readonly Job[]
-scheduler.getJob("name");        // Job | undefined
+scheduler.isRunning; // boolean
+scheduler.jobCount; // number of registered jobs
+scheduler.list(); // readonly Job[]
+scheduler.getJob("name"); // Job | undefined
 ```
 
 And on each `Job`:
 
 ```ts
-job.nextRun;                     // Dayjs | null
-job.lastRun;                     // Dayjs | null — success OR failure
-job.isRunning;                   // boolean
-job.intervals;                   // readonly schedule config
-job.cronExpression;              // string | null
+job.nextRun; // Dayjs | null
+job.lastRun; // Dayjs | null — success OR failure
+job.isRunning; // boolean
+job.intervals; // readonly schedule config
+job.cronExpression; // string | null
 ```
 
 ## See also
@@ -351,27 +342,33 @@ Six task skills cover the full surface. Most callers only need `scheduler-basics
 ### Foundations
 
 #### `scheduler-basics`
+
 Start here. The `job(name, fn)` factory, the `scheduler` singleton, the 2-primitive surface, UTC default, why the API is factory-first.
 
 ### Scheduling
 
 #### `schedule-fluently`
+
 Build schedules without writing cron: `.everyMinutes(N)`, `.daily().at("03:00")`, `.weekly().on("monday")`, `.monthly()`, `.beginOf("month")`, `.endOf("year")`, and friends. Reach for this 80% of the time.
 
 #### `schedule-with-cron`
+
 Drop down to `.cron("0 9 * * 1-5")` when the fluent API can't express it (Vixie OR semantics for DOM/DOW, complex multi-value lists). Includes `parseCron()` for previewing next-run times before deploy.
 
 ### Production concerns
 
 #### `configure-retry-and-overlap`
+
 `.retry(maxRetries, delay?, backoffMultiplier?)` for fixed or exponential backoff; `.preventOverlap()` so a slow run never collides with the next tick. Reach for both anytime a job calls external services.
 
 #### `pin-schedule-timezone`
+
 `.inTimezone("America/New_York")` pins wall-clock fire times across DST and across servers. The default is UTC — if your job description includes "9 AM," you almost certainly want this skill.
 
 ### Observability + shutdown
 
 #### `observe-scheduler`
+
 The seven typed `SchedulerEvents` (`job:start` / `complete` / `error` / `skip`, `scheduler:started` / `stopped` / `tick`), the `JobResult` payload, `start()` / `stop()` / `shutdown()`. Wire this for logging, metrics, alerting, and graceful SIGTERM handling.
 
 ## Quick taste
@@ -431,10 +428,7 @@ Every `Job` has its own timezone. The default is **UTC** — `.daily().at("09:00
 ## Basic usage
 
 ```ts
-job("morning-digest", sendDailyDigest)
-  .daily()
-  .at("08:00")
-  .inTimezone("America/New_York");   // 8 AM ET, not 8 AM UTC
+job("morning-digest", sendDailyDigest).daily().at("08:00").inTimezone("America/New_York"); // 8 AM ET, not 8 AM UTC
 ```
 
 `.inTimezone()` is chainable — typically placed after the time/day methods.
@@ -451,9 +445,9 @@ Same logical task, three regions:
 import { scheduler, job } from "@warlock.js/scheduler";
 
 const regions = [
-  { name: "us-east",   tz: "America/New_York" },
-  { name: "eu-west",   tz: "Europe/Berlin" },
-  { name: "asia",      tz: "Asia/Tokyo" },
+  { name: "us-east", tz: "America/New_York" },
+  { name: "eu-west", tz: "Europe/Berlin" },
+  { name: "asia", tz: "Asia/Tokyo" },
 ];
 
 for (const { name, tz } of regions) {
@@ -461,7 +455,7 @@ for (const { name, tz } of regions) {
     job(`morning-report-${name}`, () => sendReport(name))
       .daily()
       .at("09:00")
-      .inTimezone(tz)
+      .inTimezone(tz),
   );
 }
 
@@ -476,20 +470,20 @@ dayjs handles transitions correctly. A daily 09:00 job in `America/New_York` shi
 
 ## Common IANA strings
 
-| Region              | TZ string                   |
-| ------------------- | --------------------------- |
-| UTC                 | `UTC`                       |
-| US Eastern          | `America/New_York`          |
-| US Central          | `America/Chicago`           |
-| US Mountain         | `America/Denver`            |
-| US Pacific          | `America/Los_Angeles`       |
-| UK / Ireland        | `Europe/London`             |
-| Central Europe      | `Europe/Berlin`             |
-| Eastern Europe      | `Europe/Kyiv`               |
-| India               | `Asia/Kolkata`              |
-| Japan               | `Asia/Tokyo`                |
-| Australia (Sydney)  | `Australia/Sydney`          |
-| Egypt               | `Africa/Cairo`              |
+| Region             | TZ string             |
+| ------------------ | --------------------- |
+| UTC                | `UTC`                 |
+| US Eastern         | `America/New_York`    |
+| US Central         | `America/Chicago`     |
+| US Mountain        | `America/Denver`      |
+| US Pacific         | `America/Los_Angeles` |
+| UK / Ireland       | `Europe/London`       |
+| Central Europe     | `Europe/Berlin`       |
+| Eastern Europe     | `Europe/Kyiv`         |
+| India              | `Asia/Kolkata`        |
+| Japan              | `Asia/Tokyo`          |
+| Australia (Sydney) | `Australia/Sydney`    |
+| Egypt              | `Africa/Cairo`        |
 
 Full list: [IANA Time Zone Database](https://www.iana.org/time-zones).
 
@@ -498,17 +492,11 @@ Full list: [IANA Time Zone Database](https://www.iana.org/time-zones).
 The timezone applies to every interpretation of "now" and every constraint:
 
 ```ts
-job("monday-standup", task)
-  .weekly()
-  .on("monday")
-  .at("09:00")
-  .inTimezone("Europe/Berlin");
+job("monday-standup", task).weekly().on("monday").at("09:00").inTimezone("Europe/Berlin");
 // "Monday in Berlin local time" + "09:00 Berlin local time"
 // — automatically shifts CET ↔ CEST as DST changes.
 
-job("nightly-cron", task)
-  .cron("0 3 * * *")
-  .inTimezone("Asia/Tokyo");
+job("nightly-cron", task).cron("0 3 * * *").inTimezone("Asia/Tokyo");
 // "0 3 * * *" interpreted in Tokyo local time → 03:00 JST = 18:00 UTC.
 ```
 
@@ -548,24 +536,24 @@ Chainable methods on a `Job` instance. Each method returns `this` for chaining;
 
 ## 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         |
+| 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)`
 
@@ -583,7 +571,7 @@ Units: `"second" | "minute" | "hour" | "day" | "week" | "month" | "year"`.
 
 ```ts
 job("nightly", fn).daily().at("03:00");
-job("midday",  fn).daily().at("12:30:15");
+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).
@@ -595,7 +583,7 @@ 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
+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"`.
@@ -608,14 +596,14 @@ Valid day-of-week strings: `"sunday"`, `"monday"`, `"tuesday"`, `"wednesday"`, `
 
 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                   |
+| 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.
 
@@ -631,12 +619,12 @@ Every fluent method recomputes `nextRun` at the end. Putting `.at()` before `.da
 
 ```ts
 job("good", fn)
-  .weekly()              // interval
-  .on("monday")          // day
-  .at("09:00")           // time
-  .inTimezone("UTC")     // timezone
-  .preventOverlap()      // execution
-  .retry(3, 1000);       // execution
+  .weekly() // interval
+  .on("monday") // day
+  .at("09:00") // time
+  .inTimezone("UTC") // timezone
+  .preventOverlap() // execution
+  .retry(3, 1000); // execution
 ```
 
 ## Inline registration — `scheduler.newJob()`
@@ -644,10 +632,7 @@ job("good", fn)
 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");
+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):
@@ -666,11 +651,11 @@ If the scheduler is already running, every job added via `addJob` / `addJobs` is
 ```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
+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
@@ -707,14 +692,14 @@ The escape hatch when the fluent API can't express a schedule. Activating `.cron
 
 ## 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 * * *` |
+| 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`, `#`).
 
@@ -786,13 +771,13 @@ import dayjs from "dayjs";
 
 const parser = parseCron("0 9 * * 1-5");
 
-parser.nextRun().toISOString();              // next weekday at 9 AM
+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.matches(dayjs()); // is "now" a fire moment?
 
-parser.fields;                                // parsed numeric arrays
-parser.expression;                            // original string
+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.
@@ -847,7 +832,7 @@ The 9 things that are true in every scheduler use:
 6. **Validation throws at definition time.** `every(0)`, `at("24:00")`, `on(32)`, `retry(-1)`, malformed cron — all throw immediately when you wire the job, not at runtime.
 7. **`Job.run()` returns a `JobResult`, never throws.** Errors funnel into `result.error`. The scheduler emits `job:error` after all retries are exhausted.
 8. **Parallel mode is within a tick, not across.** Even with `runInParallel(true)`, the NEXT tick waits for the current tick's jobs to all settle.
-9. **Tick interval is drift-compensated.** A tick that takes 200 ms is followed by an 800 ms delay so the cadence between tick *starts* averages `tickInterval`, not `tickInterval + work-time`.
+9. **Tick interval is drift-compensated.** A tick that takes 200 ms is followed by an 800 ms delay so the cadence between tick _starts_ averages `tickInterval`, not `tickInterval + work-time`.
 
 ## 30-second example
 
@@ -864,7 +849,7 @@ scheduler.addJob(
     .at("03:00")
     .inTimezone("America/New_York")
     .preventOverlap()
-    .retry(3, 1000)
+    .retry(3, 1000),
 );
 
 scheduler.start();
@@ -890,13 +875,13 @@ scheduler.around((job, run) => storage.run({ job: job.name }, run));
 
 ## Pick a skill
 
-| If the task is about… | Load |
-| --- | --- |
-| Building schedules via `every*`/`daily`/`weekly`/`monthly`/`at`/`on`/`beginOf`/`endOf` | the `schedule-fluently` topic |
-| Writing `.cron("…")` expressions, debugging DOM/DOW behavior, using `parseCron()` for preview | the `schedule-with-cron` topic |
+| If the task is about…                                                                                 | Load                                    |
+| ----------------------------------------------------------------------------------------------------- | --------------------------------------- |
+| Building schedules via `every*`/`daily`/`weekly`/`monthly`/`at`/`on`/`beginOf`/`endOf`                | the `schedule-fluently` topic           |
+| Writing `.cron("…")` expressions, debugging DOM/DOW behavior, using `parseCron()` for preview         | the `schedule-with-cron` topic          |
 | Configuring `.retry()` / exponential backoff, `.preventOverlap()`, understanding failure rescheduling | the `configure-retry-and-overlap` topic |
-| Subscribing to scheduler events, reading `JobResult`, lifecycle, graceful shutdown | the `observe-scheduler` topic |
-| Per-job `.inTimezone()`, multi-region patterns, DST handling | the `pin-schedule-timezone` topic |
+| Subscribing to scheduler events, reading `JobResult`, lifecycle, graceful shutdown                    | the `observe-scheduler` topic           |
+| Per-job `.inTimezone()`, multi-region patterns, DST handling                                          | the `pin-schedule-timezone` topic       |
 
 ## When NOT to use this skill
 

package/package.json

@@ -8,7 +8,7 @@
     "dayjs": "^1.11.19"
   },
   "peerDependencies": {
-    "@warlock.js/cache": "5.30.0"
+    "@warlock.js/cache": "5.31.0"
   },
   "peerDependenciesMeta": {
     "@warlock.js/cache": {
@@ -34,7 +34,7 @@
   ],
   "author": "hassanzohdy",
   "license": "MIT",
-  "version": "5.30.0",
+  "version": "5.31.0",
   "main": "./cjs/index.cjs",
   "module": "./esm/index.mjs",
   "types": "./esm/index.d.mts",

package/skills/configure-retry-and-overlap/SKILL.md

@@ -10,18 +10,11 @@ Two independent execution-control concerns on a single `Job`. They compose clean
 ## `.retry(maxRetries, delay?, backoffMultiplier?)`
 
 ```ts
-job("send-report", sendReport)
-  .daily()
-  .at("08:00")
-  .retry(3);                  // 3 retries, 1000ms apart (default delay)
-
-job("sync", syncInventory)
-  .everyHour()
-  .retry(5, 2000);             // 5 retries, 2000ms each
-
-job("queue", processQueue)
-  .everyMinutes(10)
-  .retry(5, 1000, 2);          // exponential: 1s → 2s → 4s → 8s → 16s
+job("send-report", sendReport).daily().at("08:00").retry(3); // 3 retries, 1000ms apart (default delay)
+
+job("sync", syncInventory).everyHour().retry(5, 2000); // 5 retries, 2000ms each
+
+job("queue", processQueue).everyMinutes(10).retry(5, 1000, 2); // exponential: 1s → 2s → 4s → 8s → 16s
 ```
 
 **Signature:** `retry(maxRetries: number, delay = 1000, backoffMultiplier?: number): this`
@@ -46,6 +39,7 @@ scheduler.on("job:error", (name, error) => {
 ```
 
 `JobResult.retries`:
+
 - On **success**: the number of failed attempts before the eventual success (0 if first attempt succeeded).
 - On **failure**: equals the configured `maxRetries` (all of them were used).
 
@@ -68,7 +62,7 @@ To **stop** firing after N consecutive failures, do it in user code:
 
 ```ts
 let consecutiveFailures = 0;
-scheduler.on("job:error", name => {
+scheduler.on("job:error", (name) => {
   if (name !== "flaky") return;
   consecutiveFailures++;
   if (consecutiveFailures >= 5) {
@@ -76,7 +70,7 @@ scheduler.on("job:error", name => {
     alert.critical("flaky disabled after 5 failures");
   }
 });
-scheduler.on("job:complete", name => {
+scheduler.on("job:complete", (name) => {
   if (name === "flaky") consecutiveFailures = 0;
 });
 ```
@@ -86,9 +80,7 @@ scheduler.on("job:complete", name => {
 Tells the scheduler to skip a tick if the job is already running.
 
 ```ts
-job("queue", processQueue)
-  .everyMinutes(5)
-  .preventOverlap();
+job("queue", processQueue).everyMinutes(5).preventOverlap();
 ```
 
 **Important nuance.** The scheduler awaits each tick's jobs before scheduling the next tick — so **concurrent same-job runs from the scheduler's own loop are structurally impossible**, regardless of `preventOverlap()`. Where it actually matters: jobs whose callbacks ALSO get invoked outside the scheduler.
@@ -99,7 +91,7 @@ Real-world shapes that benefit:
 // 1) Boot-time recovery sweep before normal scheduling.
 const queueJob = job("queue", processQueueOnce).everyMinutes(5).preventOverlap();
 scheduler.addJob(queueJob);
-queueJob.run().catch(err => log.error({ err }, "boot sweep failed"));
+queueJob.run().catch((err) => log.error({ err }, "boot sweep failed"));
 scheduler.start();
 
 // 2) Admin-triggered manual re-run from a dashboard endpoint.
@@ -113,6 +105,7 @@ app.post("/admin/jobs/:name/run", async (req, res) => {
 ```
 
 If a tick lands while one of these external runs is mid-flight:
+
 - Scheduler emits `job:skip` with reason `"Job is already running"`
 - The tick proceeds without re-entering the job
 
@@ -123,10 +116,7 @@ For a single-process app where the callback is only ever invoked via the schedul
 They compose cleanly. Retry happens WITHIN one fire — if all retries fail, the tick ends and `nextRun` advances. `preventOverlap` matters only between fires.
 
 ```ts
-job("long-flaky", processQueue)
-  .everyMinutes(5)
-  .preventOverlap()
-  .retry(3, 1000, 2);   // up to 1 + 2 + 4 = 7 s of retry delay per fire
+job("long-flaky", processQueue).everyMinutes(5).preventOverlap().retry(3, 1000, 2); // up to 1 + 2 + 4 = 7 s of retry delay per fire
 ```
 
 If retries push the total work past the next interval, `preventOverlap()` ensures the next scheduled tick skips instead of stacking.