@basaltkit/scheduler 1.2.1 → 1.3.0

package/README.md

@@ -257,6 +257,15 @@ 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)`.
 
+## Multiple replicas — `.onOneServer()`
+
+`withoutOverlapping()` guards one process only. On N replicas, mark an entry
+`.onOneServer()` and pass `schedulerPlugin({ lock })` an atomic cross-replica
+lock (`ScheduleLock`: `acquire(key, ttlMs)` — e.g. Redis `SET key v PX ttl NX`).
+Exactly one replica runs the entry per tick; using `.onOneServer()` without a
+`lock` fails loud at boot. Cron expressions are validated at definition time
+(`CronParseError` on unsupported syntax like `MON` or out-of-range values).
+
 ## Common errors and solutions (FAQ)
 
 **My `daily().at('03:00')` task runs at the wrong time.**

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,6 +1,6 @@
 {
   "name": "@basaltkit/scheduler",
-  "version": "1.2.1",
+  "version": "1.3.0",
   "description": "Fluent Basalt scheduler: schedule.job(X).daily().at('03:00'), timezones, withoutOverlapping and @basaltkit/queue integration.",
   "license": "MIT",
   "type": "module",
@@ -14,8 +14,8 @@
     "dist"
   ],
   "dependencies": {
-    "@basaltkit/core": "^1.1.2",
-    "@basaltkit/queue": "^1.2.1"
+    "@basaltkit/core": "^1.3.0",
+    "@basaltkit/queue": "^1.3.1"
   },
   "devDependencies": {
     "@types/node": "^26.3.0",