@basaltkit/scheduler 1.2.1 → 1.3.1

package/README.md

@@ -208,10 +208,15 @@ respects each entry's overlap guard and `onFailure` handler.
 
 Registers a `Scheduler` (singleton) under the `SCHEDULER` token; on `boot` it calls `define`, publishes the entries to the container's metadata (key `schedule:entries`, consumed by `basalt schedule:list`), registers the `schedule:run` command, and starts the timer; on `shutdown` it calls `stop()`.
 
-| Option | Type | Required? | Default | Description |
-|---|---|---|---|---|
-| `define` | `(schedule: Scheduler) => void` | No | — | Callback where you declare the schedules (receives the Scheduler at boot). |
-| `autostart` | `boolean` | No | `true` | Starts the timer at boot. Turn off in tests. |
+| Option | Type | Default | Purpose |
+|---|---|---|---|
+| `define` | `(schedule: Scheduler) => void` | — | Callback where you declare the schedules (receives the Scheduler at boot). |
+| `autostart` | `boolean` | `true` | Starts the timer at boot. Turn it off in tests so the process isn't holding a 60 s interval. |
+| `lock` | `ScheduleLock` | — | Cross-replica mutex, **required** as soon as any entry calls `.onOneServer()`. Boot throws without it. See [`ScheduleLock`](#the-schedulelock-contract). |
+| `lockTtlMs` | `number` | `60_000` | TTL of each per-entry, per-tick lock key. The key already embeds the minute, so this only has to outlive clock skew between replicas — one tick window is the right default. |
+
+`SchedulerOptions` (`lock`, `lockTtlMs`) are the same two the `Scheduler` constructor takes, so a
+hand-built `new Scheduler({ lock })` behaves identically.
 
 ### `class Scheduler`
 
@@ -220,9 +225,12 @@ Registers a `Scheduler` (singleton) under the `SCHEDULER` token; on `boot` it ca
 | `call` | `(name: string, task: () => void \| Promise<void>) => ScheduleEntry` | Schedules a function with a name. |
 | `job` | `<T>(job: JobDefinition<T>, payload?) => ScheduleEntry` | Schedules the `dispatch` of an `@basaltkit/queue` job (payload required if the job needs one). |
 | `list` | `() => { name, cron, timezone }[]` | Describes all entries. |
-| `tick` | `(date?: Date) => Promise<void>` | Runs the entries due at that instant (default: now). Aggregates failures without `onFailure` into an `AggregateError`. |
-| `start` | `() => void` | Aligns to the next minute and then `tick()`s every 60s. Idempotent. |
+| `names` | `() => string[]` | Names of every entry — used by the CLI to validate/suggest. |
+| `runNow` | `(name: string) => Promise<boolean>` | Runs one entry on demand, **ignoring its cron and its `.onOneServer()` lock** (a manual trigger is deliberate). `false` if no entry has that name. The overlap guard and `onFailure` still apply. |
+| `tick` | `(date?: Date) => Promise<void>` | Runs the entries due at that instant (default: now), concurrently. Aggregates failures without `onFailure` into an `AggregateError`. |
+| `start` | `() => void` | Aligns to the next minute and then `tick()`s every 60s. Idempotent; the timers are `unref`'d. |
 | `stop` | `() => void` | Stops the timers. |
+| `skippedByLock` | `number` | Ticks skipped because another replica held the lock — for observability and tests. |
 
 ### `class ScheduleEntry` (returned by `call`/`job`)
 
@@ -231,7 +239,8 @@ Frequency methods (all return `this`): `everyMinute()`, `everyMinutes(n)`, `hour
 | Method/property | Type | Default | Description |
 |---|---|---|---|
 | `timezone(tz)` | `(tz: string) => this` | `'UTC'` | IANA timezone in which the time is interpreted. |
-| `withoutOverlapping()` | `() => this` | off | Skips the run if the previous one is still in progress. |
+| `withoutOverlapping()` | `() => this` | off | Skips the run if the previous one is still in progress — **in this process only**. |
+| `onOneServer()` | `() => this` | off | Runs the entry on exactly ONE replica per tick instead of on every pod. Requires `schedulerPlugin({ lock })`; boot throws without one. |
 | `onFailure(handler)` | `((error: unknown) => void) => this` | — | Receives the error instead of propagating it. |
 | `describe()` | `() => { name, cron, timezone }` | — | Description of the entry. |
 | `isDue(date)` | `(date: Date) => boolean` | — | Is the entry due at this instant? |
@@ -257,6 +266,112 @@ Exported for tooling and tests; you don't usually need them:
 
 - `SCHEDULER: Token<Scheduler>` — to get the Scheduler from the container: `app.container.get(SCHEDULER)`.
 
+### Errors
+
+| Error | Code | When |
+|---|---|---|
+| `CronParseError` | `CRON_INVALID` | An expression passed to `.cron()` (or built internally) isn't 5 fields, uses unsupported syntax (`MON`, `@daily`, `?`, `L`), has a reversed range (`5-1`), a step below 1, or a value outside its field's bounds. Extends `BasaltError`; raised at **definition** time, so a typo fails at boot rather than becoming a task that silently never fires. |
+| `Error` (plain) | — | At `boot`, when an entry uses `.onOneServer()` but no `lock` was configured. See [Boot-time enforcement](#boot-time-enforcement). |
+| `AggregateError` | — (built-in) | From `tick()`, when one or more due entries failed without an `onFailure` handler — or when a `.onOneServer()` entry's `lock.acquire` rejected. All due entries still ran; `error.errors` holds each failure. Swallowed by the automatic timer path so a failing task can't kill the process. |
+
+### Hooks & callbacks
+
+The scheduler has no hook bus. Two per-entry callbacks and one injected collaborator:
+
+| Callback | Where | Receives | Default when unset |
+|---|---|---|---|
+| `onFailure(handler)` | `ScheduleEntry` | `(error: unknown)` | The error propagates — aggregated into the tick's `AggregateError`, then **swallowed** by the automatic timer. Set it, or a failure in production is invisible. |
+| `lock.acquire` | `SchedulerOptions` | `(key: string, ttlMs: number) => Promise<boolean>` | No lock. Boot throws if any entry needs one. |
+
+## Multiple replicas — `.onOneServer()`
+
+`withoutOverlapping()` guards one process. It does nothing about the real production problem:
+you run four pods, every pod boots the scheduler, and at 03:00 the nightly billing job runs
+**four times**. Mark the entry `.onOneServer()` and give the plugin a lock:
+
+```ts
+import Redis from 'ioredis'
+import { schedulerPlugin, type ScheduleLock } from '@basaltkit/scheduler'
+
+const redis = new Redis(process.env.REDIS_URL!)
+
+const lock: ScheduleLock = {
+  async acquire(key, ttlMs) {
+    return (await redis.set(key, '1', 'PX', ttlMs, 'NX')) === 'OK'
+  },
+}
+
+schedulerPlugin({
+  lock,
+  define: (schedule) => {
+    schedule.job(ReconcileBilling, { mode: 'full' }).daily().at('03:00').onOneServer()
+  },
+})
+```
+
+### The `ScheduleLock` contract
+
+```ts
+interface ScheduleLock {
+  acquire(key: string, ttlMs: number): Promise<boolean>
+}
+```
+
+One method, and the guarantees it must provide are the whole point:
+
+- **`acquire` must be atomic across processes.** For a given `key`, exactly one caller anywhere
+  in the fleet may get `true` until the TTL expires. Redis `SET key value PX ttl NX` is the
+  canonical implementation. A check-then-set (`GET` then `SET`) is **not** atomic and silently
+  reintroduces the duplicate runs you added the lock to prevent.
+- **The key must actually expire.** The scheduler never deletes it. A store without TTL support
+  would let the first tick's key block that entry forever.
+- **There is deliberately no `release`.** The key covers the whole tick window, so a fast first
+  run cannot be followed by a late replica acquiring the freed key and running the same minute a
+  second time. The TTL is the release.
+
+The key the scheduler builds is `basalt:schedule:<entry name>:<minute, ISO, seconds zeroed>` —
+one key per entry per minute. `lockTtlMs` (default `60_000`) only has to outlive clock skew
+between replicas.
+
+### What happens when acquisition fails
+
+Two distinct cases, and they are treated very differently:
+
+| Case | Behaviour |
+|---|---|
+| `acquire` resolves `false` — another replica won this tick | The entry is skipped on this replica and `scheduler.skippedByLock` increments. This is the normal path on N−1 of your N pods, every tick. Not an error. |
+| `acquire` **rejects** — the lock store is down, times out, or the credentials expired | Treated as a **task failure**: the rejection is collected into the tick's `AggregateError` exactly like a thrown task, so it is visible. The entry does **not** run. It is *not* treated as permission to proceed. |
+
+That last row is the deliberate design choice. Failing open — running everywhere when the lock
+store is unreachable — would mean a Redis outage silently turns one nightly billing run into
+four. Failing closed means a Redis outage skips a tick, which a subsequent tick or a manual
+`basalt schedule:run <name>` can recover.
+
+### Boot-time enforcement
+
+If any entry calls `.onOneServer()` and no `lock` was configured, `boot` **throws**:
+
+```
+schedulerPlugin: an entry uses .onOneServer() but no `lock` was configured.
+Pass `schedulerPlugin({ lock })` with an atomic cross-replica lock (e.g. Redis SET NX PX) — see ScheduleLock.
+```
+
+Failing the deploy is the point: silently running the entry on every replica is exactly the
+failure mode `.onOneServer()` exists to prevent, and it is invisible until the duplicate charges
+land.
+
+### What the lock does not cover
+
+- **`runNow()` / `basalt schedule:run <name>`** bypass the lock entirely — a manual trigger is
+  deliberate, and you asked *this* process to run it.
+- **Entries without `.onOneServer()`** are untouched and still run on every replica.
+- **The lock is per tick, not per run.** If a task overruns its minute, the next minute's key is
+  a different key. Combine with `.withoutOverlapping()` if the same replica must not stack runs,
+  and prefer `schedule.job(...)` so a queue worker (with its own idempotency) does the work.
+
+Cron expressions are validated at definition time — `CronParseError` on unsupported syntax like
+`MON` or out-of-range values, so a typo fails at boot instead of becoming a job that never fires.
+
 ## Common errors and solutions (FAQ)
 
 **My `daily().at('03:00')` task runs at the wrong time.**
@@ -266,7 +381,16 @@ Times are UTC by default. Add `.timezone('Europe/Lisbon')` (or your IANA timezon
 `cron()` only accepts the classic 5-field format (`min hour day month day-of-week`). 6-field formats (with seconds) are not supported.
 
 **The task runs twice (two servers).**
-The scheduler runs in every process where the plugin starts. If you have multiple replicas, enable the scheduler on only one (e.g. via an environment variable) or schedule `schedule.job(...)` with idempotent jobs.
+The scheduler runs in every process where the plugin starts. Mark the entry `.onOneServer()` and pass `schedulerPlugin({ lock })` an atomic cross-replica lock — see the *Multiple replicas* section above. `withoutOverlapping()` will not help: it guards one process only.
+
+**Boot fails with "an entry uses .onOneServer() but no `lock` was configured".**
+Exactly as intended — booting without the lock would run that entry on every replica. Supply a `ScheduleLock` (Redis `SET key v PX ttl NX`), or drop `.onOneServer()`.
+
+**An `.onOneServer()` entry stopped running everywhere at once.**
+Its lock store is unreachable. A rejecting `acquire` is treated as a task failure (visible in the tick's `AggregateError`), never as permission to run on every replica. Fix the store; a later tick or `basalt schedule:run <name>` recovers the missed run.
+
+**`skippedByLock` keeps climbing.**
+Normal. On N replicas, N−1 of them skip each `.onOneServer()` tick. Only worry if it climbs on *every* replica — that means nobody is acquiring, i.e. a stale key without a TTL.
 
 **A task failed and I didn't see anything.**
 In automatic mode, failures without `onFailure` are silenced so as not to crash the process. Set `onFailure` on each entry (or log inside it).

package/dist/cron.js

@@ -4,12 +4,58 @@ export class CronParseError extends BasaltError {
         super('CRON_INVALID', `Invalid cron expression "${expression}": ${detail}`);
     }
 }
+const FIELD_BOUNDS = [
+    ['minute', 0, 59],
+    ['hour', 0, 23],
+    ['day-of-month', 1, 31],
+    ['month', 1, 12],
+    ['day-of-week', 0, 6],
+];
+/**
+ * Validates one cron field against the syntax {@link fieldMatches} actually
+ * supports: asterisk, asterisk-slash-n steps, single values, `a-b` ranges and comma lists.
+ * Anything else (names like MON, out-of-range values, `5-1`) previously became
+ * NaN comparisons — a job that silently NEVER fires. Fail at parse time instead.
+ */
+function assertField(expression, field, name, min, max) {
+    const invalid = (detail) => {
+        throw new CronParseError(expression, `${name} field "${field}": ${detail}`);
+    };
+    if (field === '*')
+        return;
+    for (const part of field.split(',')) {
+        const step = /^\*\/(\d+)$/.exec(part);
+        if (step) {
+            if (Number(step[1]) < 1)
+                invalid('step must be >= 1');
+            continue;
+        }
+        const range = /^(\d+)-(\d+)$/.exec(part);
+        if (range) {
+            const [from, to] = [Number(range[1]), Number(range[2])];
+            if (from > to)
+                invalid(`range ${from}-${to} is reversed`);
+            if (from < min || to > max)
+                invalid(`range ${from}-${to} outside ${min}-${max}`);
+            continue;
+        }
+        if (!/^\d+$/.test(part))
+            invalid(`"${part}" is not supported (use *, */n, n, a-b or comma lists; names like MON are not)`);
+        const value = Number(part);
+        if (value < min || value > max)
+            invalid(`${value} outside ${min}-${max}`);
+    }
+}
 export function parseCron(expression) {
     const parts = expression.trim().split(/\s+/);
     if (parts.length !== 5) {
         throw new CronParseError(expression, `expected 5 fields, received ${parts.length}`);
     }
     const [minute, hour, dayOfMonth, month, dayOfWeek] = parts;
+    parts.forEach((field, i) => {
+        const [name, min, max] = FIELD_BOUNDS[i];
+        assertField(expression, field, name, min, max);
+    });
     return { minute, hour, dayOfMonth, month, dayOfWeek };
 }
 export function cronToString(fields) {

package/dist/index.d.ts

@@ -2,6 +2,24 @@ import type { JobDefinition } from '@basaltkit/queue';
 export { CronParseError, cronMatches, parseCron, fieldMatches, zonedParts } from './cron.js';
 export type { CronFields, ZonedParts } from './cron.js';
 type Task = () => void | Promise<void>;
+/**
+ * Cross-replica mutex for `.onOneServer()` entries. `acquire` must be ATOMIC
+ * across processes (e.g. Redis `SET key value PX ttl NX`): it returns true for
+ * exactly one caller per key until the TTL expires. There is deliberately no
+ * `release` — the key covers the tick window, so a fast first run cannot be
+ * followed by a late replica re-acquiring and running the same minute again.
+ *
+ * ioredis example:
+ *
+ *     const lock: ScheduleLock = {
+ *       async acquire(key, ttlMs) {
+ *         return (await redis.set(key, '1', 'PX', ttlMs, 'NX')) === 'OK'
+ *       },
+ *     }
+ */
+export interface ScheduleLock {
+    acquire(key: string, ttlMs: number): Promise<boolean>;
+}
 /**
  * A scheduled entry, built fluently:
  *
@@ -14,6 +32,7 @@ export declare class ScheduleEntry {
     private fields;
     private tz;
     private noOverlap;
+    private oneServer;
     private failureHandler;
     private running;
     /** count of executions skipped due to overlap — visible for observability/tests */
@@ -39,6 +58,16 @@ export declare class ScheduleEntry {
     timezone(tz: string): this;
     /** If the previous execution is still running, the new one is skipped. */
     withoutOverlapping(): this;
+    /**
+     * On a horizontally-scaled deployment, run this entry on ONE replica per tick
+     * instead of on every pod. Requires a `lock` on the Scheduler (see
+     * {@link ScheduleLock}) — without one, boot fails loud rather than silently
+     * running the job N times. `runNow()`/`schedule:run` bypass the lock (a manual
+     * trigger is deliberate).
+     */
+    onOneServer(): this;
+    /** @internal whether this entry asked for cross-replica locking. */
+    get wantsOneServer(): boolean;
     onFailure(handler: (error: unknown) => void): this;
     /** Entry description — consumed by `basalt schedule list`. */
     describe(): {
@@ -51,10 +80,28 @@ export declare class ScheduleEntry {
     run(): Promise<void>;
     private onDayOfWeek;
 }
+export interface SchedulerOptions {
+    /** Cross-replica lock for `.onOneServer()` entries. */
+    lock?: ScheduleLock;
+    /**
+     * TTL for each per-entry, per-tick lock key. Default 60_000 (one tick window
+     * — the key embeds the minute, so it only needs to outlive clock skew).
+     */
+    lockTtlMs?: number;
+}
 export declare class Scheduler {
     private readonly entries;
     private timer;
     private interval;
+    private readonly lock;
+    private readonly lockTtlMs;
+    /** ticks skipped because another replica held the lock — for observability/tests */
+    skippedByLock: number;
+    constructor(options?: SchedulerOptions);
+    /** @internal true when any entry requested `.onOneServer()`. */
+    get needsLock(): boolean;
+    /** @internal whether a lock was configured. */
+    get hasLock(): boolean;
     /** Schedules the dispatch of a @basaltkit/queue job. */
     job<T>(job: JobDefinition<T>, ...payload: T extends void ? [] : [T]): ScheduleEntry;
     /** Schedules a named function. */
@@ -85,7 +132,7 @@ export declare class Scheduler {
     private add;
 }
 export declare const SCHEDULER: import("@basaltkit/core").Token<Scheduler>;
-export interface SchedulerPluginOptions {
+export interface SchedulerPluginOptions extends SchedulerOptions {
     /** Callback that defines the schedules — receives the Scheduler at boot. */
     define?: (schedule: Scheduler) => void;
     /** Starts the timer at boot. Default: true (turn off in tests). */

package/dist/index.js

@@ -19,6 +19,7 @@ export class ScheduleEntry {
     };
     tz = 'UTC';
     noOverlap = false;
+    oneServer = false;
     failureHandler;
     running = false;
     /** count of executions skipped due to overlap — visible for observability/tests */
@@ -84,6 +85,21 @@ export class ScheduleEntry {
         this.noOverlap = true;
         return this;
     }
+    /**
+     * On a horizontally-scaled deployment, run this entry on ONE replica per tick
+     * instead of on every pod. Requires a `lock` on the Scheduler (see
+     * {@link ScheduleLock}) — without one, boot fails loud rather than silently
+     * running the job N times. `runNow()`/`schedule:run` bypass the lock (a manual
+     * trigger is deliberate).
+     */
+    onOneServer() {
+        this.oneServer = true;
+        return this;
+    }
+    /** @internal whether this entry asked for cross-replica locking. */
+    get wantsOneServer() {
+        return this.oneServer;
+    }
     onFailure(handler) {
         this.failureHandler = handler;
         return this;
@@ -123,6 +139,22 @@ export class Scheduler {
     entries = [];
     timer;
     interval;
+    lock;
+    lockTtlMs;
+    /** ticks skipped because another replica held the lock — for observability/tests */
+    skippedByLock = 0;
+    constructor(options = {}) {
+        this.lock = options.lock;
+        this.lockTtlMs = options.lockTtlMs ?? 60_000;
+    }
+    /** @internal true when any entry requested `.onOneServer()`. */
+    get needsLock() {
+        return this.entries.some((entry) => entry.wantsOneServer);
+    }
+    /** @internal whether a lock was configured. */
+    get hasLock() {
+        return this.lock !== undefined;
+    }
     /** Schedules the dispatch of a @basaltkit/queue job. */
     job(job, ...payload) {
         return this.add(new ScheduleEntry(job.name, () => job.dispatch(payload[0])));
@@ -160,6 +192,19 @@ export class Scheduler {
         const errors = [];
         await Promise.all(due.map(async (entry) => {
             try {
+                if (entry.wantsOneServer && this.lock) {
+                    // One key per entry per tick window: exactly one replica acquires
+                    // it; the others skip this minute's run. A lock-store failure is
+                    // treated as a task failure (visible), not as permission to run on
+                    // every replica at once.
+                    const minute = new Date(date);
+                    minute.setSeconds(0, 0);
+                    const key = `basalt:schedule:${entry.name}:${minute.toISOString()}`;
+                    if (!(await this.lock.acquire(key, this.lockTtlMs))) {
+                        this.skippedByLock++;
+                        return;
+                    }
+                }
                 await entry.run();
             }
             catch (error) {
@@ -209,12 +254,21 @@ export function schedulerPlugin(options = {}) {
     return definePlugin({
         name: 'basalt:scheduler',
         register({ container }) {
-            container.singleton(SCHEDULER, () => new Scheduler());
+            container.singleton(SCHEDULER, () => new Scheduler({
+                ...(options.lock ? { lock: options.lock } : {}),
+                ...(options.lockTtlMs !== undefined ? { lockTtlMs: options.lockTtlMs } : {}),
+            }));
             registerScheduleRunCommand(container);
         },
         boot({ container }) {
             const scheduler = container.get(SCHEDULER);
             options.define?.(scheduler);
+            if (scheduler.needsLock && !scheduler.hasLock) {
+                // Fail closed at boot: silently running the entry on every replica is
+                // exactly the failure mode .onOneServer() exists to prevent.
+                throw new Error('schedulerPlugin: an entry uses .onOneServer() but no `lock` was configured. ' +
+                    'Pass `schedulerPlugin({ lock })` with an atomic cross-replica lock (e.g. Redis SET NX PX) — see ScheduleLock.');
+            }
             // Expose entries to tooling (CLI `basalt schedule:list`).
             const metadata = ensureMetadata(container);
             for (const entry of scheduler.list())

package/package.json

@@ -1,9 +1,13 @@
 {
   "name": "@basaltkit/scheduler",
-  "version": "1.2.1",
+  "version": "1.3.1",
+  "engines": {
+    "node": ">=22.5.0"
+  },
   "description": "Fluent Basalt scheduler: schedule.job(X).daily().at('03:00'), timezones, withoutOverlapping and @basaltkit/queue integration.",
   "license": "MIT",
   "type": "module",
+  "sideEffects": false,
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -14,8 +18,8 @@
     "dist"
   ],
   "dependencies": {
-    "@basaltkit/core": "^1.1.2",
-    "@basaltkit/queue": "^1.2.1"
+    "@basaltkit/core": "^1.3.1",
+    "@basaltkit/queue": "^1.4.1"
   },
   "devDependencies": {
     "@types/node": "^26.3.0",