@basaltkit/scheduler 1.2.0 → 1.3.0

package/README.md

@@ -1,3 +1,9 @@
+<p align="center">
+  <a href="https://basaltkit-docs.pages.dev">
+    <img src="https://basaltkit-docs.pages.dev/social-card.png" alt="Basalt" width="440">
+  </a>
+</p>
+
 # @basaltkit/scheduler
 
 Task scheduler for Basalt applications: define, with a fluent, readable API (`daily().at('03:00')`), tasks that run automatically at set times — backups, reports, cleanups, billing.
@@ -251,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.d.ts

@@ -0,0 +1,25 @@
+import { BasaltError } from '@basaltkit/core';
+export declare class CronParseError extends BasaltError {
+    constructor(expression: string, detail: string);
+}
+export interface CronFields {
+    minute: string;
+    hour: string;
+    dayOfMonth: string;
+    month: string;
+    dayOfWeek: string;
+}
+export declare function parseCron(expression: string): CronFields;
+export declare function cronToString(fields: CronFields): string;
+/** Supports: asterisk, steps (asterisk/n), single value, a-b ranges and a,b,c lists. */
+export declare function fieldMatches(field: string, value: number): boolean;
+export interface ZonedParts {
+    minute: number;
+    hour: number;
+    dayOfMonth: number;
+    month: number;
+    dayOfWeek: number;
+}
+/** Decomposes an instant into the cron fields, in the requested time zone (default UTC). */
+export declare function zonedParts(date: Date, timeZone?: string): ZonedParts;
+export declare function cronMatches(fields: CronFields, date: Date, timeZone?: string): boolean;

package/dist/cron.js

@@ -0,0 +1,118 @@
+import { BasaltError } from '@basaltkit/core';
+export class CronParseError extends BasaltError {
+    constructor(expression, detail) {
+        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) {
+    return [fields.minute, fields.hour, fields.dayOfMonth, fields.month, fields.dayOfWeek].join(' ');
+}
+/** Supports: asterisk, steps (asterisk/n), single value, a-b ranges and a,b,c lists. */
+export function fieldMatches(field, value) {
+    if (field === '*')
+        return true;
+    return field.split(',').some((part) => {
+        const step = /^\*\/(\d+)$/.exec(part);
+        if (step)
+            return value % Number(step[1]) === 0;
+        const range = /^(\d+)-(\d+)$/.exec(part);
+        if (range)
+            return value >= Number(range[1]) && value <= Number(range[2]);
+        return Number(part) === value;
+    });
+}
+const WEEKDAYS = {
+    Sun: 0,
+    Mon: 1,
+    Tue: 2,
+    Wed: 3,
+    Thu: 4,
+    Fri: 5,
+    Sat: 6,
+};
+/** Decomposes an instant into the cron fields, in the requested time zone (default UTC). */
+export function zonedParts(date, timeZone = 'UTC') {
+    const formatter = new Intl.DateTimeFormat('en-US', {
+        timeZone,
+        minute: 'numeric',
+        hour: 'numeric',
+        day: 'numeric',
+        month: 'numeric',
+        weekday: 'short',
+        hour12: false,
+    });
+    const parts = {};
+    for (const part of formatter.formatToParts(date)) {
+        parts[part.type] = part.value;
+    }
+    return {
+        minute: Number(parts['minute']),
+        // Intl with hour12:false may emit 24 for midnight
+        hour: Number(parts['hour']) % 24,
+        dayOfMonth: Number(parts['day']),
+        month: Number(parts['month']),
+        dayOfWeek: WEEKDAYS[parts['weekday']],
+    };
+}
+export function cronMatches(fields, date, timeZone) {
+    const parts = zonedParts(date, timeZone);
+    return (fieldMatches(fields.minute, parts.minute) &&
+        fieldMatches(fields.hour, parts.hour) &&
+        fieldMatches(fields.dayOfMonth, parts.dayOfMonth) &&
+        fieldMatches(fields.month, parts.month) &&
+        fieldMatches(fields.dayOfWeek, parts.dayOfWeek));
+}

package/dist/index.d.ts

@@ -1,44 +1,38 @@
-import * as _basaltkit_core from '@basaltkit/core';
-import { BasaltError } from '@basaltkit/core';
-import { JobDefinition } from '@basaltkit/queue';
-
-declare class CronParseError extends BasaltError {
-    constructor(expression: string, detail: string);
-}
-interface CronFields {
-    minute: string;
-    hour: string;
-    dayOfMonth: string;
-    month: string;
-    dayOfWeek: string;
-}
-declare function parseCron(expression: string): CronFields;
-/** Supports: asterisk, steps (asterisk/n), single value, a-b ranges and a,b,c lists. */
-declare function fieldMatches(field: string, value: number): boolean;
-interface ZonedParts {
-    minute: number;
-    hour: number;
-    dayOfMonth: number;
-    month: number;
-    dayOfWeek: number;
-}
-/** Decomposes an instant into the cron fields, in the requested time zone (default UTC). */
-declare function zonedParts(date: Date, timeZone?: string): ZonedParts;
-declare function cronMatches(fields: CronFields, date: Date, timeZone?: string): boolean;
-
+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:
  *
  * schedule.job(ReconcileBilling).daily().at('03:00').timezone('UTC')
  * schedule.call('purge-cache', () => cache.flush()).everyMinute().withoutOverlapping()
  */
-declare class ScheduleEntry {
+export declare class ScheduleEntry {
     readonly name: string;
     private readonly task;
     private fields;
     private tz;
     private noOverlap;
+    private oneServer;
     private failureHandler;
     private running;
     /** count of executions skipped due to overlap — visible for observability/tests */
@@ -64,6 +58,16 @@ 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(): {
@@ -76,10 +80,28 @@ declare class ScheduleEntry {
     run(): Promise<void>;
     private onDayOfWeek;
 }
-declare class Scheduler {
+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. */
@@ -109,13 +131,11 @@ declare class Scheduler {
     private safeTick;
     private add;
 }
-declare const SCHEDULER: _basaltkit_core.Token<Scheduler>;
-interface SchedulerPluginOptions {
+export declare const SCHEDULER: import("@basaltkit/core").Token<Scheduler>;
+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). */
     autostart?: boolean;
 }
-declare function schedulerPlugin(options?: SchedulerPluginOptions): _basaltkit_core.BasaltPlugin<unknown>;
-
-export { type CronFields, CronParseError, SCHEDULER, ScheduleEntry, Scheduler, type SchedulerPluginOptions, type ZonedParts, cronMatches, fieldMatches, parseCron, schedulerPlugin, zonedParts };
+export declare function schedulerPlugin(options?: SchedulerPluginOptions): import("@basaltkit/core").BasaltPlugin<unknown>;

package/dist/index.js

@@ -1,332 +1,314 @@
-// src/index.ts
-import { createToken, definePlugin, ensureMetadata } from "@basaltkit/core";
-
-// src/cron.ts
-import { BasaltError } from "@basaltkit/core";
-var CronParseError = class extends BasaltError {
-  constructor(expression, detail) {
-    super("CRON_INVALID", `Invalid cron expression "${expression}": ${detail}`);
-  }
-};
-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;
-  return { minute, hour, dayOfMonth, month, dayOfWeek };
-}
-function cronToString(fields) {
-  return [fields.minute, fields.hour, fields.dayOfMonth, fields.month, fields.dayOfWeek].join(" ");
-}
-function fieldMatches(field, value) {
-  if (field === "*") return true;
-  return field.split(",").some((part) => {
-    const step = /^\*\/(\d+)$/.exec(part);
-    if (step) return value % Number(step[1]) === 0;
-    const range = /^(\d+)-(\d+)$/.exec(part);
-    if (range) return value >= Number(range[1]) && value <= Number(range[2]);
-    return Number(part) === value;
-  });
-}
-var WEEKDAYS = {
-  Sun: 0,
-  Mon: 1,
-  Tue: 2,
-  Wed: 3,
-  Thu: 4,
-  Fri: 5,
-  Sat: 6
-};
-function zonedParts(date, timeZone = "UTC") {
-  const formatter = new Intl.DateTimeFormat("en-US", {
-    timeZone,
-    minute: "numeric",
-    hour: "numeric",
-    day: "numeric",
-    month: "numeric",
-    weekday: "short",
-    hour12: false
-  });
-  const parts = {};
-  for (const part of formatter.formatToParts(date)) {
-    parts[part.type] = part.value;
-  }
-  return {
-    minute: Number(parts["minute"]),
-    // Intl with hour12:false may emit 24 for midnight
-    hour: Number(parts["hour"]) % 24,
-    dayOfMonth: Number(parts["day"]),
-    month: Number(parts["month"]),
-    dayOfWeek: WEEKDAYS[parts["weekday"]]
-  };
-}
-function cronMatches(fields, date, timeZone) {
-  const parts = zonedParts(date, timeZone);
-  return fieldMatches(fields.minute, parts.minute) && fieldMatches(fields.hour, parts.hour) && fieldMatches(fields.dayOfMonth, parts.dayOfMonth) && fieldMatches(fields.month, parts.month) && fieldMatches(fields.dayOfWeek, parts.dayOfWeek);
-}
-
-// src/index.ts
-var ScheduleEntry = class {
-  constructor(name, task) {
-    this.name = name;
-    this.task = task;
-  }
-  name;
-  task;
-  fields = {
-    minute: "*",
-    hour: "*",
-    dayOfMonth: "*",
-    month: "*",
-    dayOfWeek: "*"
-  };
-  tz = "UTC";
-  noOverlap = false;
-  failureHandler;
-  running = false;
-  /** count of executions skipped due to overlap — visible for observability/tests */
-  skippedOverlaps = 0;
-  everyMinute() {
-    this.fields = { minute: "*", hour: "*", dayOfMonth: "*", month: "*", dayOfWeek: "*" };
-    return this;
-  }
-  everyMinutes(n) {
-    this.everyMinute();
-    this.fields.minute = `*/${n}`;
-    return this;
-  }
-  hourly() {
-    this.everyMinute();
-    this.fields.minute = "0";
-    return this;
-  }
-  daily() {
-    this.hourly();
-    this.fields.hour = "0";
-    return this;
-  }
-  weekly() {
-    this.daily();
-    this.fields.dayOfWeek = "0";
-    return this;
-  }
-  monthly() {
-    this.daily();
-    this.fields.dayOfMonth = "1";
-    return this;
-  }
-  /** 'HH:mm' time — combines with daily/weekly/monthly. */
-  at(time) {
-    const [hour, minute] = time.split(":");
-    this.fields.hour = String(Number(hour));
-    this.fields.minute = String(Number(minute ?? 0));
-    return this;
-  }
-  /** Raw cron expression (5 fields) — escape hatch. */
-  cron(expression) {
-    this.fields = parseCron(expression);
-    return this;
-  }
-  sundays() {
-    return this.onDayOfWeek(0);
-  }
-  mondays() {
-    return this.onDayOfWeek(1);
-  }
-  tuesdays() {
-    return this.onDayOfWeek(2);
-  }
-  wednesdays() {
-    return this.onDayOfWeek(3);
-  }
-  thursdays() {
-    return this.onDayOfWeek(4);
-  }
-  fridays() {
-    return this.onDayOfWeek(5);
-  }
-  saturdays() {
-    return this.onDayOfWeek(6);
-  }
-  timezone(tz) {
-    this.tz = tz;
-    return this;
-  }
-  /** If the previous execution is still running, the new one is skipped. */
-  withoutOverlapping() {
-    this.noOverlap = true;
-    return this;
-  }
-  onFailure(handler) {
-    this.failureHandler = handler;
-    return this;
-  }
-  /** Entry description — consumed by `basalt schedule list`. */
-  describe() {
-    return { name: this.name, cron: cronToString(this.fields), timezone: this.tz };
-  }
-  isDue(date) {
-    return cronMatches(this.fields, date, this.tz);
-  }
-  /** @internal runs the task with the overlap guard and failure handling. */
-  async run() {
-    if (this.noOverlap && this.running) {
-      this.skippedOverlaps++;
-      return;
+import { createToken, definePlugin, ensureMetadata } from '@basaltkit/core';
+import { cronMatches, cronToString, parseCron } from './cron.js';
+export { CronParseError, cronMatches, parseCron, fieldMatches, zonedParts } from './cron.js';
+/**
+ * A scheduled entry, built fluently:
+ *
+ * schedule.job(ReconcileBilling).daily().at('03:00').timezone('UTC')
+ * schedule.call('purge-cache', () => cache.flush()).everyMinute().withoutOverlapping()
+ */
+export class ScheduleEntry {
+    name;
+    task;
+    fields = {
+        minute: '*',
+        hour: '*',
+        dayOfMonth: '*',
+        month: '*',
+        dayOfWeek: '*',
+    };
+    tz = 'UTC';
+    noOverlap = false;
+    oneServer = false;
+    failureHandler;
+    running = false;
+    /** count of executions skipped due to overlap — visible for observability/tests */
+    skippedOverlaps = 0;
+    constructor(name, task) {
+        this.name = name;
+        this.task = task;
+    }
+    everyMinute() {
+        this.fields = { minute: '*', hour: '*', dayOfMonth: '*', month: '*', dayOfWeek: '*' };
+        return this;
+    }
+    everyMinutes(n) {
+        this.everyMinute();
+        this.fields.minute = `*/${n}`;
+        return this;
+    }
+    hourly() {
+        this.everyMinute();
+        this.fields.minute = '0';
+        return this;
+    }
+    daily() {
+        this.hourly();
+        this.fields.hour = '0';
+        return this;
+    }
+    weekly() {
+        this.daily();
+        this.fields.dayOfWeek = '0';
+        return this;
+    }
+    monthly() {
+        this.daily();
+        this.fields.dayOfMonth = '1';
+        return this;
     }
-    this.running = true;
-    try {
-      await this.task();
-    } catch (error) {
-      if (!this.failureHandler) throw error;
-      this.failureHandler(error);
-    } finally {
-      this.running = false;
+    /** 'HH:mm' time — combines with daily/weekly/monthly. */
+    at(time) {
+        const [hour, minute] = time.split(':');
+        this.fields.hour = String(Number(hour));
+        this.fields.minute = String(Number(minute ?? 0));
+        return this;
     }
-  }
-  onDayOfWeek(day) {
-    this.fields.dayOfWeek = String(day);
-    return this;
-  }
-};
-var Scheduler = class {
-  entries = [];
-  timer;
-  interval;
-  /** Schedules the dispatch of a @basaltkit/queue job. */
-  job(job, ...payload) {
-    return this.add(new ScheduleEntry(job.name, () => job.dispatch(payload[0])));
-  }
-  /** Schedules a named function. */
-  call(name, task) {
-    return this.add(new ScheduleEntry(name, task));
-  }
-  list() {
-    return this.entries.map((entry) => entry.describe());
-  }
-  /** Names of every scheduled entry — for CLI validation/listing. */
-  names() {
-    return this.entries.map((entry) => entry.name);
-  }
-  /**
-   * Runs a single entry by name on demand, ignoring its cron (for `schedule:run`
-   * and manual triggers). Returns false if no entry has that name. The entry's
-   * own overlap guard and failure handler still apply.
-   */
-  async runNow(name) {
-    const entry = this.entries.find((candidate) => candidate.name === name);
-    if (!entry) return false;
-    await entry.run();
-    return true;
-  }
-  /**
-   * Runs the entries due at the given instant. Deterministic — this is what
-   * the tests call directly and what the timer calls every minute.
-   * Failures (without onFailure) are aggregated; all due entries run.
-   */
-  async tick(date = /* @__PURE__ */ new Date()) {
-    const due = this.entries.filter((entry) => entry.isDue(date));
-    const errors = [];
-    await Promise.all(
-      due.map(async (entry) => {
+    /** Raw cron expression (5 fields) — escape hatch. */
+    cron(expression) {
+        this.fields = parseCron(expression);
+        return this;
+    }
+    sundays() { return this.onDayOfWeek(0); }
+    mondays() { return this.onDayOfWeek(1); }
+    tuesdays() { return this.onDayOfWeek(2); }
+    wednesdays() { return this.onDayOfWeek(3); }
+    thursdays() { return this.onDayOfWeek(4); }
+    fridays() { return this.onDayOfWeek(5); }
+    saturdays() { return this.onDayOfWeek(6); }
+    timezone(tz) {
+        this.tz = tz;
+        return this;
+    }
+    /** If the previous execution is still running, the new one is skipped. */
+    withoutOverlapping() {
+        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;
+    }
+    /** Entry description — consumed by `basalt schedule list`. */
+    describe() {
+        return { name: this.name, cron: cronToString(this.fields), timezone: this.tz };
+    }
+    isDue(date) {
+        return cronMatches(this.fields, date, this.tz);
+    }
+    /** @internal runs the task with the overlap guard and failure handling. */
+    async run() {
+        if (this.noOverlap && this.running) {
+            this.skippedOverlaps++;
+            return;
+        }
+        this.running = true;
         try {
-          await entry.run();
-        } catch (error) {
-          errors.push(error);
+            await this.task();
+        }
+        catch (error) {
+            if (!this.failureHandler)
+                throw error;
+            this.failureHandler(error);
         }
-      })
-    );
-    if (errors.length > 0) {
-      throw new AggregateError(errors, `Failure in ${errors.length} scheduled task(s)`);
+        finally {
+            this.running = false;
+        }
+    }
+    onDayOfWeek(day) {
+        this.fields.dayOfWeek = String(day);
+        return this;
+    }
+}
+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])));
+    }
+    /** Schedules a named function. */
+    call(name, task) {
+        return this.add(new ScheduleEntry(name, task));
+    }
+    list() {
+        return this.entries.map((entry) => entry.describe());
+    }
+    /** Names of every scheduled entry — for CLI validation/listing. */
+    names() {
+        return this.entries.map((entry) => entry.name);
     }
-  }
-  /** Aligns to the next minute and then runs tick() every 60s. */
-  start() {
-    if (this.timer || this.interval) return;
-    const msToNextMinute = 6e4 - Date.now() % 6e4;
-    this.timer = setTimeout(() => {
-      void this.safeTick();
-      this.interval = setInterval(() => void this.safeTick(), 6e4);
-      this.interval.unref?.();
-    }, msToNextMinute);
-    this.timer.unref?.();
-  }
-  stop() {
-    if (this.timer) clearTimeout(this.timer);
-    if (this.interval) clearInterval(this.interval);
-    this.timer = void 0;
-    this.interval = void 0;
-  }
-  async safeTick() {
-    try {
-      await this.tick();
-    } catch {
+    /**
+     * Runs a single entry by name on demand, ignoring its cron (for `schedule:run`
+     * and manual triggers). Returns false if no entry has that name. The entry's
+     * own overlap guard and failure handler still apply.
+     */
+    async runNow(name) {
+        const entry = this.entries.find((candidate) => candidate.name === name);
+        if (!entry)
+            return false;
+        await entry.run();
+        return true;
     }
-  }
-  add(entry) {
-    this.entries.push(entry);
-    return entry;
-  }
-};
-var SCHEDULER = createToken("scheduler");
-function schedulerPlugin(options = {}) {
-  return definePlugin({
-    name: "basalt:scheduler",
-    register({ container }) {
-      container.singleton(SCHEDULER, () => new Scheduler());
-      registerScheduleRunCommand(container);
-    },
-    boot({ container }) {
-      const scheduler = container.get(SCHEDULER);
-      options.define?.(scheduler);
-      const metadata = ensureMetadata(container);
-      for (const entry of scheduler.list()) metadata.add("schedule:entries", entry);
-      if (options.autostart !== false) scheduler.start();
-    },
-    shutdown({ container }) {
-      container.get(SCHEDULER).stop();
+    /**
+     * Runs the entries due at the given instant. Deterministic — this is what
+     * the tests call directly and what the timer calls every minute.
+     * Failures (without onFailure) are aggregated; all due entries run.
+     */
+    async tick(date = new Date()) {
+        const due = this.entries.filter((entry) => entry.isDue(date));
+        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) {
+                errors.push(error);
+            }
+        }));
+        if (errors.length > 0) {
+            throw new AggregateError(errors, `Failure in ${errors.length} scheduled task(s)`);
+        }
+    }
+    /** Aligns to the next minute and then runs tick() every 60s. */
+    start() {
+        if (this.timer || this.interval)
+            return;
+        const msToNextMinute = 60_000 - (Date.now() % 60_000);
+        this.timer = setTimeout(() => {
+            void this.safeTick();
+            this.interval = setInterval(() => void this.safeTick(), 60_000);
+            this.interval.unref?.();
+        }, msToNextMinute);
+        this.timer.unref?.();
+    }
+    stop() {
+        if (this.timer)
+            clearTimeout(this.timer);
+        if (this.interval)
+            clearInterval(this.interval);
+        this.timer = undefined;
+        this.interval = undefined;
+    }
+    async safeTick() {
+        try {
+            await this.tick();
+        }
+        catch {
+            // failures without onFailure were already aggregated; here we only avoid
+            // bringing down the process — each entry must handle its own failure
+        }
+    }
+    add(entry) {
+        this.entries.push(entry);
+        return entry;
     }
-  });
 }
+export const SCHEDULER = createToken('scheduler');
+export function schedulerPlugin(options = {}) {
+    return definePlugin({
+        name: 'basalt:scheduler',
+        register({ container }) {
+            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())
+                metadata.add('schedule:entries', entry);
+            if (options.autostart !== false)
+                scheduler.start();
+        },
+        shutdown({ container }) {
+            container.get(SCHEDULER).stop();
+        },
+    });
+}
+/**
+ * Registers `schedule:run` into the CLI command bucket. Runs a scheduled task on
+ * demand by name (ignoring its cron), or `--due` to run everything due right now.
+ * Registered structurally to avoid a hard @basaltkit/cli dependency.
+ */
 function registerScheduleRunCommand(container) {
-  ensureMetadata(container).add("commands", {
-    name: "schedule:run",
-    description: "Run a scheduled task on demand (by name), or --due for all due now",
-    async handle({
-      io,
-      args,
-      flags
-    }) {
-      const scheduler = container.get(SCHEDULER);
-      if (flags["due"] === true) {
-        await scheduler.tick();
-        io.log("Ran all due scheduled tasks.");
-        return;
-      }
-      const name = args[0];
-      if (!name) {
-        io.error("Usage: basalt schedule:run <name> | --due");
-        return 1;
-      }
-      const ran = await scheduler.runNow(name);
-      if (!ran) {
-        const available = scheduler.names().join(", ") || "(none)";
-        io.error(`Unknown scheduled task "${name}". Available: ${available}.`);
-        return 1;
-      }
-      io.log(`Ran scheduled task "${name}".`);
-    }
-  });
+    ensureMetadata(container).add('commands', {
+        name: 'schedule:run',
+        description: 'Run a scheduled task on demand (by name), or --due for all due now',
+        async handle({ io, args, flags, }) {
+            const scheduler = container.get(SCHEDULER);
+            if (flags['due'] === true) {
+                await scheduler.tick();
+                io.log('Ran all due scheduled tasks.');
+                return;
+            }
+            const name = args[0];
+            if (!name) {
+                io.error('Usage: basalt schedule:run <name> | --due');
+                return 1;
+            }
+            const ran = await scheduler.runNow(name);
+            if (!ran) {
+                const available = scheduler.names().join(', ') || '(none)';
+                io.error(`Unknown scheduled task "${name}". Available: ${available}.`);
+                return 1;
+            }
+            io.log(`Ran scheduled task "${name}".`);
+        },
+    });
 }
-export {
-  CronParseError,
-  SCHEDULER,
-  ScheduleEntry,
-  Scheduler,
-  cronMatches,
-  fieldMatches,
-  parseCron,
-  schedulerPlugin,
-  zonedParts
-};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@basaltkit/scheduler",
-  "version": "1.2.0",
+  "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,15 +14,14 @@
     "dist"
   ],
   "dependencies": {
-    "@basaltkit/core": "^1.0.0",
-    "@basaltkit/queue": "^1.2.0"
+    "@basaltkit/core": "^1.3.0",
+    "@basaltkit/queue": "^1.3.1"
   },
   "devDependencies": {
-    "@types/node": "^22.15.0",
-    "tsup": "^8.4.0",
-    "typescript": "^5.8.0",
-    "vitest": "^3.1.0",
-    "zod": "^3.24.0",
+    "@types/node": "^26.3.0",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.11",
+    "zod": "^3.24.0 || ^4.0.0",
     "@basaltkit/tsconfig": "^0.24.0"
   },
   "publishConfig": {
@@ -30,11 +29,11 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/Zebedeu/basalt.git",
+    "url": "git+https://github.com/basaltkit/basalt.git",
     "directory": "packages/scheduler"
   },
-  "homepage": "https://github.com/Zebedeu/basalt/tree/main/packages/scheduler#readme",
-  "bugs": "https://github.com/Zebedeu/basalt/issues",
+  "homepage": "https://github.com/basaltkit/basalt/tree/main/packages/scheduler#readme",
+  "bugs": "https://github.com/basaltkit/basalt/issues",
   "keywords": [
     "basalt",
     "typescript",
@@ -42,7 +41,7 @@
     "cron"
   ],
   "scripts": {
-    "build": "tsup src/index.ts --format esm --dts --clean",
+    "build": "tsc -p tsconfig.build.json",
     "test": "vitest run",
     "typecheck": "tsc --noEmit"
   }