@warlock.js/scheduler 5.19.1 → 5.21.0

package/llms.txt

@@ -6,10 +6,10 @@
 
 ## Skills
 
-- [configure-retry-and-overlap](@warlock.js/scheduler/configure-retry-and-overlap/SKILL.md): Retry, backoff, and overlap in @warlock.js/scheduler; use when you need to configure retry and overlap.
-- [observe-scheduler](@warlock.js/scheduler/observe-scheduler/SKILL.md): Observability and lifecycle in @warlock.js/scheduler; use when you need to observe scheduler.
+- [configure-retry-and-overlap](@warlock.js/scheduler/configure-retry-and-overlap/SKILL.md): (no description)
+- [observe-scheduler](@warlock.js/scheduler/observe-scheduler/SKILL.md): (no description)
 - [overview](@warlock.js/scheduler/overview/SKILL.md): @warlock.js/scheduler overview for orientation and choosing the focused skill for the task.
-- [pin-schedule-timezone](@warlock.js/scheduler/pin-schedule-timezone/SKILL.md): Per-job timezones in @warlock.js/scheduler; use when you need to pin schedule timezone.
-- [schedule-fluently](@warlock.js/scheduler/schedule-fluently/SKILL.md): Fluent scheduling API in @warlock.js/scheduler; use when you need to schedule fluently.
-- [schedule-with-cron](@warlock.js/scheduler/schedule-with-cron/SKILL.md): Cron expressions in @warlock.js/scheduler; use when you need to schedule with cron.
+- [pin-schedule-timezone](@warlock.js/scheduler/pin-schedule-timezone/SKILL.md): (no description)
+- [schedule-fluently](@warlock.js/scheduler/schedule-fluently/SKILL.md): (no description)
+- [schedule-with-cron](@warlock.js/scheduler/schedule-with-cron/SKILL.md): (no description)
 - [scheduler-basics](@warlock.js/scheduler/scheduler-basics/SKILL.md): Start here for @warlock.js/scheduler recurring jobs, schedules, worker configuration, and job lifecycle.

package/package.json

@@ -7,6 +7,14 @@
   "dependencies": {
     "dayjs": "^1.11.19"
   },
+  "peerDependencies": {
+    "@warlock.js/cache": "5.21.0"
+  },
+  "peerDependenciesMeta": {
+    "@warlock.js/cache": {
+      "optional": true
+    }
+  },
   "repository": {
     "type": "git",
     "url": "https://github.com/warlockjs/scheduler"
@@ -25,7 +33,7 @@
   ],
   "author": "hassanzohdy",
   "license": "MIT",
-  "version": "5.19.1",
+  "version": "5.21.0",
   "main": "./cjs/index.cjs",
   "module": "./esm/index.mjs",
   "types": "./esm/index.d.mts",

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

@@ -1,137 +1,152 @@
----
-name: configure-retry-and-overlap
-description: "Retry, backoff, and overlap in @warlock.js/scheduler; use when you need to configure retry and overlap."
----
-
-# Retry, backoff, and overlap
-
-Two independent execution-control concerns on a single `Job`. They compose cleanly.
-
-## `.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
-```
-
-**Signature:** `retry(maxRetries: number, delay = 1000, backoffMultiplier?: number): this`
-
-**Formula:** delay before attempt `N+1` = `delay × backoffMultiplier^(N-1)`. Without a multiplier, all retries wait `delay` ms.
-
-**Validation.** Throws at definition time on negative `maxRetries`, negative `delay`, or zero/negative `backoffMultiplier`. `retry(0)` is valid — means "no retries, single attempt."
-
-## Retry count surfaces in `JobResult`
-
-```ts
-scheduler.on("job:complete", (name, result) => {
-  if (result.retries && result.retries > 0) {
-    log.warn({ name, retries: result.retries }, "succeeded after retries");
-  }
-});
-
-scheduler.on("job:error", (name, error) => {
-  // Fires once, AFTER all retries are exhausted.
-  log.error({ name, error }, "failed permanently");
-});
-```
-
-`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).
-
-## After permanent failure — `nextRun` advances normally
-
-This is load-bearing: a job that exhausts every retry and still throws does **not** re-fire on the next tick. The scheduler:
-
-1. Emits `job:error` once with the final error.
-2. Advances `nextRun` by the job's interval, same as success.
-
-Both branches go through the same `finally`-block path in `Job.run()`. There is no "stuck on retry" mode.
-
-```ts
-// Fires every 10 minutes, retries 3 times per fire.
-// If the 10:00 run exhausts all retries, next run is at 10:10. NOT at 10:00:00.001.
-job("flaky", fn).everyMinutes(10).retry(3, 1000);
-```
-
-To **stop** firing after N consecutive failures, do it in user code:
-
-```ts
-let consecutiveFailures = 0;
-scheduler.on("job:error", name => {
-  if (name !== "flaky") return;
-  consecutiveFailures++;
-  if (consecutiveFailures >= 5) {
-    scheduler.removeJob("flaky");
-    alert.critical("flaky disabled after 5 failures");
-  }
-});
-scheduler.on("job:complete", name => {
-  if (name === "flaky") consecutiveFailures = 0;
-});
-```
-
-## `.preventOverlap(skip = true)`
-
-Tells the scheduler to skip a tick if the job is already running.
-
-```ts
-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.
-
-Real-world shapes that benefit:
-
-```ts
-// 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"));
-scheduler.start();
-
-// 2) Admin-triggered manual re-run from a dashboard endpoint.
-app.post("/admin/jobs/:name/run", async (req, res) => {
-  const j = scheduler.getJob(req.params.name);
-  await j?.run();
-  res.sendStatus(204);
-});
-
-// 3) Multiple scheduler instances pointed at the same Job (rare).
-```
-
-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
-
-For a single-process app where the callback is only ever invoked via the scheduler, `preventOverlap()` is a no-op — but it's free, defensive documentation. Keep it on for any job that touches shared state.
-
-## Combining retry + preventOverlap
-
-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
-```
-
-If retries push the total work past the next interval, `preventOverlap()` ensures the next scheduled tick skips instead of stacking.
-
-## See also
-
-- [`@warlock.js/scheduler/observe-scheduler/SKILL.md`](@warlock.js/scheduler/observe-scheduler/SKILL.md) — full event reference, `JobResult` shape, lifecycle
-- [`@warlock.js/scheduler/schedule-fluently/SKILL.md`](@warlock.js/scheduler/schedule-fluently/SKILL.md) — the scheduling methods these compose with
+---
+name: configure-retry-and-overlap
+description: 'Configure `.retry(maxRetries, delay?, backoffMultiplier?)` for fixed / exponential backoff and `.preventOverlap()` for external-invocation safety. Triggers: `.retry`, `.preventOverlap`, `maxRetries`, `backoffMultiplier`, `JobResult.retries`, `job:error`, `job:skip`; "how do I retry a failed job", "exponential backoff for scheduled job", "prevent concurrent job runs", "stop firing after N consecutive failures"; typical import `import { job, scheduler } from "@warlock.js/scheduler"`. Skip: events / shutdown — `@warlock.js/scheduler/observe-scheduler/SKILL.md`; building the schedule itself — `@warlock.js/scheduler/schedule-fluently/SKILL.md`; competing libs `p-retry`, `async-retry`, `bullmq`.'
+---
+
+# Retry, backoff, and overlap
+
+Two independent execution-control concerns on a single `Job`. They compose cleanly.
+
+## `.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
+```
+
+**Signature:** `retry(maxRetries: number, delay = 1000, backoffMultiplier?: number): this`
+
+**Formula:** delay before attempt `N+1` = `delay × backoffMultiplier^(N-1)`. Without a multiplier, all retries wait `delay` ms.
+
+**Validation.** Throws at definition time on negative `maxRetries`, negative `delay`, or zero/negative `backoffMultiplier`. `retry(0)` is valid — means "no retries, single attempt."
+
+## Retry count surfaces in `JobResult`
+
+```ts
+scheduler.on("job:complete", (name, result) => {
+  if (result.retries && result.retries > 0) {
+    log.warn({ name, retries: result.retries }, "succeeded after retries");
+  }
+});
+
+scheduler.on("job:error", (name, error) => {
+  // Fires once, AFTER all retries are exhausted.
+  log.error({ name, error }, "failed permanently");
+});
+```
+
+`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).
+
+## After permanent failure — `nextRun` advances normally
+
+This is load-bearing: a job that exhausts every retry and still throws does **not** re-fire on the next tick. The scheduler:
+
+1. Emits `job:error` once with the final error.
+2. Advances `nextRun` by the job's interval, same as success.
+
+Both branches go through the same `finally`-block path in `Job.run()`. There is no "stuck on retry" mode.
+
+```ts
+// Fires every 10 minutes, retries 3 times per fire.
+// If the 10:00 run exhausts all retries, next run is at 10:10. NOT at 10:00:00.001.
+job("flaky", fn).everyMinutes(10).retry(3, 1000);
+```
+
+To **stop** firing after N consecutive failures, do it in user code:
+
+```ts
+let consecutiveFailures = 0;
+scheduler.on("job:error", name => {
+  if (name !== "flaky") return;
+  consecutiveFailures++;
+  if (consecutiveFailures >= 5) {
+    scheduler.removeJob("flaky");
+    alert.critical("flaky disabled after 5 failures");
+  }
+});
+scheduler.on("job:complete", name => {
+  if (name === "flaky") consecutiveFailures = 0;
+});
+```
+
+## `.preventOverlap(skip = true)`
+
+Tells the scheduler to skip a tick if the job is already running.
+
+```ts
+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.
+
+Real-world shapes that benefit:
+
+```ts
+// 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"));
+scheduler.start();
+
+// 2) Admin-triggered manual re-run from a dashboard endpoint.
+app.post("/admin/jobs/:name/run", async (req, res) => {
+  const j = scheduler.getJob(req.params.name);
+  await j?.run();
+  res.sendStatus(204);
+});
+
+// 3) Multiple scheduler instances pointed at the same Job (rare).
+```
+
+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
+
+For a single-process app where the callback is only ever invoked via the scheduler, `preventOverlap()` is a no-op — but it's free, defensive documentation. Keep it on for any job that touches shared state.
+
+## Combining retry + preventOverlap
+
+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
+```
+
+If retries push the total work past the next interval, `preventOverlap()` ensures the next scheduled tick skips instead of stacking.
+
+## See also
+
+- [`@warlock.js/scheduler/observe-scheduler/SKILL.md`](@warlock.js/scheduler/observe-scheduler/SKILL.md) — full event reference, `JobResult` shape, lifecycle
+- [`@warlock.js/scheduler/schedule-fluently/SKILL.md`](@warlock.js/scheduler/schedule-fluently/SKILL.md) — the scheduling methods these compose with
+
+## Running on one server only: `onOneServer()`
+
+`preventOverlap()` is in-process. With several app instances, add `onOneServer()` so only one instance runs each tick:
+
+```ts
+job("nightly-report", buildReport).daily().at("02:00").onOneServer().preventOverlap();
+job("sync", sync).everyMinutes(5).onOneServer({ lockTtl: "10m", key: "sync-v2" });
+```
+
+- Claim key: `scheduler.<key ?? name>.<scheduledTickEpochMs>` (scheduled tick time truncated to the second, so every server derives the same key). Losers skip the tick and the scheduler emits `job:skip`.
+- It is a **claim, not a lock**: a create-only, TTL-bounded cache entry that is never released, only expires. That guarantees one run per tick even if another server's timer fires late, after the winner finished.
+- Default claim TTL: `min(interval, 1h)` with a 60s floor (1h for cron jobs). Override with `lockTtl`.
+- Needs the optional `@warlock.js/cache` peer and a shared driver (redis/pg). On the memory driver it only dedupes within one process.
+- Throws at call time if the job has no name/key.

package/skills/index.md

@@ -0,0 +1,20 @@
+---
+description: "In-process job scheduler for Warlock.js with fluent and cron scheduling, retries, overlap prevention and timezones. Exports `Scheduler`, `scheduler`, `Job`, `job`, `CronParser`, `parseCron`, plus types `RetryConfig`, `JobResult`, `SchedulerEvents`. Use for: \"run this every day at 3am\", \"run a cron expression on weekdays\", \"retry a failing job 3 times\", \"stop a job overlapping itself\", \"run in New York time\", \"log job failures\". Not this package: durable queues and background workers are not scheduling; per-run locking across instances uses @warlock.js/cache."
+---
+# @warlock.js/scheduler
+
+Build a `job(name, fn)`, describe when it runs with the fluent API (`.daily().at("03:00")`) or `.cron("...")`, add it to a `Scheduler`, then `start()`. Events (`job:error` and others) provide observability; `shutdown()` stops gracefully.
+
+## The 80% path
+1. Orient: `overview.md`, `scheduler-basics.md`.
+2. Define the schedule fluently: `schedule-fluently.md`, or by cron: `schedule-with-cron.md`.
+3. Make it resilient: `configure-retry-and-overlap.md`.
+4. Fix wall-clock semantics: `pin-schedule-timezone.md`.
+5. Watch it run: `observe-scheduler.md`.
+
+## Conventions and pitfalls
+- It is in-memory and per-process: each app instance runs its own copy. With multiple instances, guard jobs with a lock (for example `@warlock.js/cache`) or run the scheduler in one instance only.
+- Missed runs while the process was down are not replayed.
+- Set a timezone explicitly for jobs tied to business hours; otherwise the host's applies.
+- Call `scheduler.shutdown()` on SIGTERM so running jobs finish.
+- Use `preventOverlap()` for jobs that can outlast their interval.