@warlock.js/scheduler 5.19.1 → 5.20.0

package/skills/observe-scheduler/SKILL.md

@@ -1,153 +1,153 @@
----
-name: observe-scheduler
-description: "Observability and lifecycle in @warlock.js/scheduler; use when you need to observe scheduler."
----
-
-# Observability and lifecycle
-
-The `Scheduler` extends Node's `EventEmitter` with a fully-typed surface. Wire listeners before calling `.start()`.
-
-## All seven events
-
-```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];
-  "scheduler:started": [];
-  "scheduler:stopped": [];
-  "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) |
-
-**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.
-
-## `JobResult` shape
-
-```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` is wall-clock from the first attempt's start to the final settlement — useful for both p50 metrics and capacity planning.
-
-## Subscribing
-
-```ts
-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: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"));
-```
-
-`.on()`, `.once()`, `.off()` are all type-narrowed via `SchedulerEvents`.
-
-## Lifecycle methods
-
-### `.start()`
-
-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."`)
-
-### `.stop()`
-
-Immediately clears the next-tick timer. Does NOT wait for jobs currently mid-execution. Emits `scheduler:stopped`. **No-op if not running** — calling `.stop()` on a never-started or already-stopped scheduler is safe and silent.
-
-### `.shutdown(timeout = 30000)`
-
-Graceful equivalent of `.stop()`:
-
-1. Marks the scheduler as shutting down (no new ticks scheduled).
-2. Calls `.stop()` internally (so `scheduler:stopped` fires).
-3. Awaits every currently-running job's `waitForCompletion()`, capped by `timeout`.
-4. Resolves either when all jobs finish or when the timeout elapses.
-
-```ts
-process.on("SIGTERM", async () => {
-  await scheduler.shutdown(30_000);
-  process.exit(0);
-});
-```
-
-The timeout is a HARD cap — jobs still running after it are abandoned (their promises keep resolving in the background, but the scheduler doesn't await them). The package does not currently support per-job timeouts or `AbortSignal` cancellation.
-
-## Production observer pattern
-
-Wire all observers before `start()`, in one place:
-
-```ts
-import { scheduler } from "@warlock.js/scheduler";
-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:complete", (name, result) => {
-  metrics.increment(`job.success.${name}`);
-  metrics.timing(`job.duration.${name}`, result.duration);
-  if (result.retries) metrics.increment(`job.retries.${name}`, result.retries);
-});
-
-scheduler.on("job:error", (name, error) => {
-  logger.error({ name, error }, "Job failed permanently");
-  alerts.critical(`Scheduler job "${name}" failed`, error);
-});
-
-scheduler.on("job:skip", (name, reason) => {
-  logger.warn({ name, reason }, "Job skipped — likely external invocation in flight");
-});
-
-scheduler.on("scheduler:started", () => logger.info("scheduler up"));
-scheduler.on("scheduler:stopped", () => logger.info("scheduler down"));
-
-// Register jobs, then:
-scheduler.start();
-```
-
-## Inspection at runtime
-
-```ts
-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
-```
-
-## See also
-
-- [`@warlock.js/scheduler/configure-retry-and-overlap/SKILL.md`](@warlock.js/scheduler/configure-retry-and-overlap/SKILL.md) — what triggers each event in detail
-- [`@warlock.js/scheduler/schedule-fluently/SKILL.md`](@warlock.js/scheduler/schedule-fluently/SKILL.md) — the methods that mutate the state these getters expose
+---
+name: observe-scheduler
+description: 'Subscribe to scheduler lifecycle and job events for logging / metrics / alerting / graceful shutdown — seven typed `SchedulerEvents`, `JobResult` payload, `start()` / `stop()` / `shutdown()`. Triggers: `scheduler.on`, `scheduler.shutdown`, `JobResult`, `job:complete`, `job:error`, `scheduler:started`, `scheduler.getJob`; "graceful SIGTERM shutdown", "did this job run", "scheduler metrics and alerts", "subscribe to job events"; typical import `import { scheduler, type JobResult } from "@warlock.js/scheduler"`. Skip: retry / overlap — `@warlock.js/scheduler/configure-retry-and-overlap/SKILL.md`; building schedules — `@warlock.js/scheduler/schedule-fluently/SKILL.md`; native `EventEmitter`, `process.on`.'
+---
+
+# Observability and lifecycle
+
+The `Scheduler` extends Node's `EventEmitter` with a fully-typed surface. Wire listeners before calling `.start()`.
+
+## All seven events
+
+```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];
+  "scheduler:started": [];
+  "scheduler:stopped": [];
+  "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) |
+
+**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.
+
+## `JobResult` shape
+
+```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` is wall-clock from the first attempt's start to the final settlement — useful for both p50 metrics and capacity planning.
+
+## Subscribing
+
+```ts
+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: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"));
+```
+
+`.on()`, `.once()`, `.off()` are all type-narrowed via `SchedulerEvents`.
+
+## Lifecycle methods
+
+### `.start()`
+
+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."`)
+
+### `.stop()`
+
+Immediately clears the next-tick timer. Does NOT wait for jobs currently mid-execution. Emits `scheduler:stopped`. **No-op if not running** — calling `.stop()` on a never-started or already-stopped scheduler is safe and silent.
+
+### `.shutdown(timeout = 30000)`
+
+Graceful equivalent of `.stop()`:
+
+1. Marks the scheduler as shutting down (no new ticks scheduled).
+2. Calls `.stop()` internally (so `scheduler:stopped` fires).
+3. Awaits every currently-running job's `waitForCompletion()`, capped by `timeout`.
+4. Resolves either when all jobs finish or when the timeout elapses.
+
+```ts
+process.on("SIGTERM", async () => {
+  await scheduler.shutdown(30_000);
+  process.exit(0);
+});
+```
+
+The timeout is a HARD cap — jobs still running after it are abandoned (their promises keep resolving in the background, but the scheduler doesn't await them). The package does not currently support per-job timeouts or `AbortSignal` cancellation.
+
+## Production observer pattern
+
+Wire all observers before `start()`, in one place:
+
+```ts
+import { scheduler } from "@warlock.js/scheduler";
+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:complete", (name, result) => {
+  metrics.increment(`job.success.${name}`);
+  metrics.timing(`job.duration.${name}`, result.duration);
+  if (result.retries) metrics.increment(`job.retries.${name}`, result.retries);
+});
+
+scheduler.on("job:error", (name, error) => {
+  logger.error({ name, error }, "Job failed permanently");
+  alerts.critical(`Scheduler job "${name}" failed`, error);
+});
+
+scheduler.on("job:skip", (name, reason) => {
+  logger.warn({ name, reason }, "Job skipped — likely external invocation in flight");
+});
+
+scheduler.on("scheduler:started", () => logger.info("scheduler up"));
+scheduler.on("scheduler:stopped", () => logger.info("scheduler down"));
+
+// Register jobs, then:
+scheduler.start();
+```
+
+## Inspection at runtime
+
+```ts
+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
+```
+
+## See also
+
+- [`@warlock.js/scheduler/configure-retry-and-overlap/SKILL.md`](@warlock.js/scheduler/configure-retry-and-overlap/SKILL.md) — what triggers each event in detail
+- [`@warlock.js/scheduler/schedule-fluently/SKILL.md`](@warlock.js/scheduler/schedule-fluently/SKILL.md) — the methods that mutate the state these getters expose

package/skills/pin-schedule-timezone/SKILL.md

@@ -1,114 +1,114 @@
----
-name: pin-schedule-timezone
-description: "Per-job timezones in @warlock.js/scheduler; use when you need to pin schedule timezone."
----
-
-# Per-job timezones
-
-Every `Job` has its own timezone. The default is **UTC** — `.daily().at("09:00")` fires at 09:00 UTC, regardless of the server's locale or system timezone. Pin to wall-clock time with `.inTimezone(IANA string)`.
-
-## Basic usage
-
-```ts
-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.
-
-## Why the default is UTC
-
-A server runs wherever ops put it (Frankfurt, Virginia, GCP us-central1, …). System-local time is unpredictable; UTC is stable. The framework picks the stable default so that `daily().at("09:00")` without further config is reproducible across deployments. Pin to wall-clock time when business hours actually matter.
-
-## Multi-region fan-out
-
-Same logical task, three regions:
-
-```ts
-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" },
-];
-
-for (const { name, tz } of regions) {
-  scheduler.addJob(
-    job(`morning-report-${name}`, () => sendReport(name))
-      .daily()
-      .at("09:00")
-      .inTimezone(tz)
-  );
-}
-
-scheduler.start();
-```
-
-Three separate `Job` instances, three separate `nextRun` calculations. Each fires once per day at its region's 09:00.
-
-## DST is automatic
-
-dayjs handles transitions correctly. A daily 09:00 job in `America/New_York` shifts between 13:00 UTC (EST winter) and 14:00 UTC (EDT summer) without intervention. The same job in a fixed-offset region (`Asia/Tokyo`, `Africa/Algiers`) stays at a constant UTC offset.
-
-## 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`              |
-
-Full list: [IANA Time Zone Database](https://www.iana.org/time-zones).
-
-## Interaction with `at()`, `on()`, cron
-
-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");
-// "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");
-// "0 3 * * *" interpreted in Tokyo local time → 03:00 JST = 18:00 UTC.
-```
-
-## Validation
-
-`.inTimezone()` stores the string as-is, then immediately recomputes `nextRun` — and that recompute calls dayjs with the zone. An invalid IANA string makes dayjs throw a `RangeError: Invalid time zone specified` **synchronously, at that point in the chain**:
-
-```ts
-// Throws right here — the .inTimezone() call recomputes nextRun, which
-// hits dayjs().tz("Asia/Whatever") and raises RangeError immediately.
-const j = job("t", task).daily().at("09:00").inTimezone("Asia/Whatever");
-```
-
-A valid zone computes `nextRun` on the spot (non-null after the chain). So a typo fails fast at definition time, not at the first tick — no special unit test needed to surface it.
-
-## Server-side caveats
-
-Node ships full ICU on most platforms, so all IANA zones work out of the box. If you're running a small-ICU build (alpine without full ICU, or old Node versions with `--icu=small`), only a limited set of zones is recognized. Set the `NODE_ICU_DATA` env var or use the `full-icu` package in that case.
-
-## See also
-
-- [`@warlock.js/scheduler/schedule-fluently/SKILL.md`](@warlock.js/scheduler/schedule-fluently/SKILL.md) — `at()`, `on()`, `daily()`, etc.
-- [`@warlock.js/scheduler/schedule-with-cron/SKILL.md`](@warlock.js/scheduler/schedule-with-cron/SKILL.md) — cron schedules are timezone-aware too
-- [`@warlock.js/scheduler/observe-scheduler/SKILL.md`](@warlock.js/scheduler/observe-scheduler/SKILL.md) — `job.nextRun.toISOString()` always renders in UTC; format with `.tz(zone)` to see local time
+---
+name: pin-schedule-timezone
+description: 'Pin a job to a specific IANA timezone via `.inTimezone(zone)` so its wall-clock fire time stays correct regardless of server location / DST. Triggers: `.inTimezone`, `America/New_York`, `Europe/Berlin`, `Asia/Tokyo`, `NODE_ICU_DATA`; "schedule job in a timezone", "DST drift on non-UTC server", "multi-region fan-out scheduling", "fire at 9am ET regardless of server"; typical import `import { job, scheduler } from "@warlock.js/scheduler"`. Skip: fluent interval methods — `@warlock.js/scheduler/schedule-fluently/SKILL.md`; cron syntax — `@warlock.js/scheduler/schedule-with-cron/SKILL.md`; competing libs `dayjs-timezone`, `luxon`, `date-fns-tz`.'
+---
+
+# Per-job timezones
+
+Every `Job` has its own timezone. The default is **UTC** — `.daily().at("09:00")` fires at 09:00 UTC, regardless of the server's locale or system timezone. Pin to wall-clock time with `.inTimezone(IANA string)`.
+
+## Basic usage
+
+```ts
+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.
+
+## Why the default is UTC
+
+A server runs wherever ops put it (Frankfurt, Virginia, GCP us-central1, …). System-local time is unpredictable; UTC is stable. The framework picks the stable default so that `daily().at("09:00")` without further config is reproducible across deployments. Pin to wall-clock time when business hours actually matter.
+
+## Multi-region fan-out
+
+Same logical task, three regions:
+
+```ts
+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" },
+];
+
+for (const { name, tz } of regions) {
+  scheduler.addJob(
+    job(`morning-report-${name}`, () => sendReport(name))
+      .daily()
+      .at("09:00")
+      .inTimezone(tz)
+  );
+}
+
+scheduler.start();
+```
+
+Three separate `Job` instances, three separate `nextRun` calculations. Each fires once per day at its region's 09:00.
+
+## DST is automatic
+
+dayjs handles transitions correctly. A daily 09:00 job in `America/New_York` shifts between 13:00 UTC (EST winter) and 14:00 UTC (EDT summer) without intervention. The same job in a fixed-offset region (`Asia/Tokyo`, `Africa/Algiers`) stays at a constant UTC offset.
+
+## 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`              |
+
+Full list: [IANA Time Zone Database](https://www.iana.org/time-zones).
+
+## Interaction with `at()`, `on()`, cron
+
+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");
+// "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");
+// "0 3 * * *" interpreted in Tokyo local time → 03:00 JST = 18:00 UTC.
+```
+
+## Validation
+
+`.inTimezone()` stores the string as-is, then immediately recomputes `nextRun` — and that recompute calls dayjs with the zone. An invalid IANA string makes dayjs throw a `RangeError: Invalid time zone specified` **synchronously, at that point in the chain**:
+
+```ts
+// Throws right here — the .inTimezone() call recomputes nextRun, which
+// hits dayjs().tz("Asia/Whatever") and raises RangeError immediately.
+const j = job("t", task).daily().at("09:00").inTimezone("Asia/Whatever");
+```
+
+A valid zone computes `nextRun` on the spot (non-null after the chain). So a typo fails fast at definition time, not at the first tick — no special unit test needed to surface it.
+
+## Server-side caveats
+
+Node ships full ICU on most platforms, so all IANA zones work out of the box. If you're running a small-ICU build (alpine without full ICU, or old Node versions with `--icu=small`), only a limited set of zones is recognized. Set the `NODE_ICU_DATA` env var or use the `full-icu` package in that case.
+
+## See also
+
+- [`@warlock.js/scheduler/schedule-fluently/SKILL.md`](@warlock.js/scheduler/schedule-fluently/SKILL.md) — `at()`, `on()`, `daily()`, etc.
+- [`@warlock.js/scheduler/schedule-with-cron/SKILL.md`](@warlock.js/scheduler/schedule-with-cron/SKILL.md) — cron schedules are timezone-aware too
+- [`@warlock.js/scheduler/observe-scheduler/SKILL.md`](@warlock.js/scheduler/observe-scheduler/SKILL.md) — `job.nextRun.toISOString()` always renders in UTC; format with `.tz(zone)` to see local time