@gobing-ai/ts-infra 0.4.49 → 0.4.51

package/src/scheduler/cron.ts

@@ -0,0 +1,203 @@
+/**
+ * Internal cron expression grammar + matching (task 0734).
+ *
+ * This module is deliberately NOT exported from package.json — it is a shared
+ * internal seam between `application-node.ts` (SchedulerJobConfig validation)
+ * and `scheduler/node.ts` (adapter matching), so both consume the same grammar.
+ * The public surface remains `NodeSchedulerAdapter` and `SchedulerJobConfig`.
+ *
+ * Supported grammar (five fields, whitespace-separated):
+ *   minute       0-59
+ *   hour         0-23
+ *   day-of-month 1-31
+ *   month        1-12
+ *   day-of-week  0-7  (0 and 7 are both Sunday)
+ *
+ * Each field accepts a wildcard, a step-N wildcard form, a comma-separated list
+ * of numbers or inclusive non-wrapping ranges, or a single number. Names/macros
+ * (`MON`, `JAN`, `@daily`) and operators (`?`, `L`, `W`, `#`) are rejected.
+ *
+ * Matching uses local wall-clock fields (ADR / task 0734 R2): the fall-back hour
+ * can fire twice at two distinct instants; a nonexistent spring-forward minute
+ * never fires. No per-job timezone.
+ */
+
+/** A single cron field: either a wildcard (whole range) or an explicit value set. */
+export interface CronFieldSpec {
+    /** True when the whole field is `*` (matches every value in its range). */
+    readonly wildcard: boolean;
+    /** Allowed values when restricted. Day-of-week 7 is normalized into 0. */
+    readonly values: ReadonlySet<number>;
+}
+
+/** A parsed five-field cron expression. */
+export interface CronExpression {
+    readonly minute: CronFieldSpec;
+    readonly hour: CronFieldSpec;
+    readonly dayOfMonth: CronFieldSpec;
+    readonly month: CronFieldSpec;
+    readonly dayOfWeek: CronFieldSpec;
+    /** The original expression, for error messages and metrics. */
+    readonly source: string;
+}
+
+/** Upper bound on the forward minute scan (8 calendar years, upper-capped at 366 days). */
+const MAX_SCAN_MINUTES = 8 * 366 * 24 * 60;
+
+const DAYS_OF_WEEK = 7; // 0-7 accepted on input, 7 aliases to 0
+
+/**
+ * Parse a single cron field into its wildcard/values spec.
+ *
+ * Throws `RangeError` for anything outside the supported grammar: names/macros,
+ * operators, zero steps, empty list members, descending ranges, non-integer
+ * values, or out-of-range values. Nothing silently falls back (task 0060 F7).
+ */
+function parseField(raw: string, min: number, max: number): CronFieldSpec {
+    const trimmed = raw.trim();
+    if (trimmed === '*') {
+        return { wildcard: true, values: new Set<number>() };
+    }
+
+    // Names ('MON', 'JAN'), macros ('@daily'), and '?' are unsupported operators.
+    if (/^[A-Za-z@?]/.test(trimmed)) {
+        throw new RangeError(`unsupported cron field "${raw}": names/macros are not supported`);
+    }
+
+    // Whole-field step form: */N
+    const stepMatch = trimmed.match(/^\*\/(\d+)$/);
+    if (stepMatch) {
+        const step = Number(stepMatch[1]);
+        if (step <= 0) {
+            throw new RangeError(`unsupported cron field "${raw}": step must be a positive integer`);
+        }
+        const values = new Set<number>();
+        for (let v = min; v <= max; v += step) {
+            values.add(v);
+        }
+        return { wildcard: false, values };
+    }
+
+    // Comma-separated list of numbers or inclusive non-wrapping ranges.
+    const members = trimmed.split(',');
+    if (members.some((m) => m.trim() === '')) {
+        throw new RangeError(`unsupported cron field "${raw}": empty list member`);
+    }
+
+    const values = new Set<number>();
+    for (const rawMember of members) {
+        const member = rawMember.trim();
+        if (member.includes('-')) {
+            const rangeParts = member.split('-');
+            if (rangeParts.length !== 2 || rangeParts.some((p) => p === '' || !/^\d+$/.test(p))) {
+                throw new RangeError(`unsupported cron field "${raw}": invalid range "${rawMember}"`);
+            }
+            const lo = Number(rangeParts[0]);
+            const hi = Number(rangeParts[1]);
+            if (lo > hi) {
+                throw new RangeError(`unsupported cron field "${raw}": descending range "${rawMember}"`);
+            }
+            if (lo < min || hi > max) {
+                throw new RangeError(`cron field "${raw}" value out of range [${min}-${max}] in range "${rawMember}"`);
+            }
+            for (let v = lo; v <= hi; v++) {
+                values.add(v);
+            }
+        } else {
+            if (!/^\d+$/.test(member)) {
+                throw new RangeError(`unsupported cron field "${raw}": invalid value "${rawMember}"`);
+            }
+            const v = Number(member);
+            if (v < min || v > max) {
+                throw new RangeError(`cron field "${raw}" value out of range [${min}-${max}]: ${rawMember}`);
+            }
+            values.add(v);
+        }
+    }
+
+    return { wildcard: false, values };
+}
+
+/**
+ * Parse a five-field cron expression into its spec.
+ *
+ * Throws `RangeError` on a wrong field count, any unsupported field grammar, or
+ * out-of-range values. Day-of-week `7` normalizes to `0` (Sunday).
+ */
+export function parseCronExpression(source: string): CronExpression {
+    const trimmed = source.trim();
+    const parts = trimmed.split(/\s+/);
+    if (parts.length !== 5) {
+        throw new RangeError(`unsupported cron expression "${source}": expected exactly 5 fields, got ${parts.length}`);
+    }
+
+    const [rawMinute, rawHour, rawDom, rawMonth, rawDow] = parts as [string, string, string, string, string];
+
+    const minute = parseField(rawMinute, 0, 59);
+    const hour = parseField(rawHour, 0, 23);
+    const dayOfMonth = parseField(rawDom, 1, 31);
+    const month = parseField(rawMonth, 1, 12);
+    let dayOfWeek = parseField(rawDow, 0, DAYS_OF_WEEK);
+
+    // Standard cron: 7 is an alias for 0 (Sunday).
+    if (!dayOfWeek.wildcard && dayOfWeek.values.has(DAYS_OF_WEEK)) {
+        const values = new Set(dayOfWeek.values);
+        values.delete(DAYS_OF_WEEK);
+        values.add(0);
+        dayOfWeek = { wildcard: false, values };
+    }
+
+    return { minute, hour, dayOfMonth, month, dayOfWeek, source: trimmed };
+}
+
+/**
+ * Whether the instant matches the expression (local wall-clock fields).
+ *
+ * Day semantics follow standard cron: when both day fields are wildcards both
+ * pass; when one is a wildcard the restricted field must match; when both are
+ * restricted, either may match (OR).
+ */
+export function matchesCron(date: Date, expr: CronExpression): boolean {
+    const minute = date.getMinutes();
+    if (!expr.minute.wildcard && !expr.minute.values.has(minute)) return false;
+    const hour = date.getHours();
+    if (!expr.hour.wildcard && !expr.hour.values.has(hour)) return false;
+    const month = date.getMonth() + 1;
+    if (!expr.month.wildcard && !expr.month.values.has(month)) return false;
+
+    const domWild = expr.dayOfMonth.wildcard;
+    const dowWild = expr.dayOfWeek.wildcard;
+    if (domWild && dowWild) return true;
+    const domMatch = domWild || expr.dayOfMonth.values.has(date.getDate());
+    const dowMatch = dowWild || expr.dayOfWeek.values.has(date.getDay());
+    if (domWild) return dowMatch;
+    if (dowWild) return domMatch;
+    return domMatch || dowMatch;
+}
+
+/**
+ * Compute the next matching minute strictly after `nowMs`, in local time.
+ *
+ * Starts at the next epoch-minute boundary and scans forward in one-minute
+ * steps (fixed epoch increments, local wall-clock fields read per instant), so
+ * DST fall-back selects both distinct instants and spring-forward skips
+ * nonexistent minutes. Bounded to eight calendar years so an unsatisfiable
+ * expression fails here (at registration) rather than silently never firing.
+ *
+ * # ponytail: O(minutes-to-next) forward scan, fine for small job counts; a
+ * field-jumping search would matter only if startup cost with hundreds of jobs
+ * ever shows up in measurements.
+ */
+export function nextCronTime(expr: CronExpression, nowMs: number): Date {
+    // Next epoch-minute boundary strictly after now (never the current minute).
+    let candidate = Math.floor(nowMs / 60_000) * 60_000 + 60_000;
+    const limit = candidate + MAX_SCAN_MINUTES * 60_000;
+    while (candidate < limit) {
+        const instant = new Date(candidate);
+        if (matchesCron(instant, expr)) {
+            return instant;
+        }
+        candidate += 60_000;
+    }
+    throw new RangeError(`unsupported cron expression "${expr.source}": no matching time within 8 years`);
+}

package/src/scheduler/index.ts

@@ -12,5 +12,5 @@ export {
 } from './action';
 export { initScheduler } from './factory';
 export { NoopSchedulerAdapter } from './noop';
-export type { ScheduledAction, SchedulerAdapter } from './types';
+export type { ScheduledAction, SchedulerAdapter, SchedulerJobConfig } from './types';
 export { wrapScheduledHandler } from './wrap-handler';

package/src/scheduler/node.ts

@@ -1,6 +1,9 @@
 /**
- * Node.js scheduler adapter using a simple setInterval-based approach.
- * No external cron library dependency — cron expressions are parsed minimally.
+ * Node.js scheduler adapter — interval-based for the three legacy cadence
+ * forms, self-rescheduling setTimeout for real five-field cron (task 0734).
+ *
+ * No external cron library dependency — cron expressions are parsed by the
+ * internal `scheduler/cron.ts` grammar shared with `application-node.ts`.
  */
 
 import { settleWithin } from '../internals/drain';
@@ -9,49 +12,65 @@ import {
     getSchedulerJobExecutedTotal,
     getSchedulerJobFailedTotal,
 } from '../telemetry/metrics';
+import { type CronExpression, nextCronTime, parseCronExpression } from './cron';
 import type { ScheduledAction, SchedulerAdapter } from './types';
 
-/** Simple helper to parse cron-like interval strings into milliseconds. */
-function parseInterval(cron: string): number {
-    // Support simple patterns: "* * * * *" (every minute), "*/5 * * * *" (every 5 min)
-    // Also support direct ms strings like "60000"
+/** Platform timer maximum for `setTimeout` (2^31 - 1 ms). Longer delays are chunked. */
+const MAX_TIMEOUT = 2_147_483_647;
+
+/**
+ * Parse the three legacy interval cadences, returning milliseconds, or
+ * `undefined` when the string is real cron (or invalid) and must route to the
+ * cron grammar instead.
+ *
+ * Legacy forms preserved verbatim (task 0734 R2): a positive millisecond
+ * number, `* * * * *` (60s), and the step-N wildcard form (N*60s) — all
+ * measured from adapter start as setInterval cadences.
+ */
+function parseInterval(cron: string): number | undefined {
     const trimmed = cron.trim();
     const num = Number(trimmed);
     if (trimmed !== '' && !Number.isNaN(num)) {
         // Guard against 0/negative intervals — setInterval would spin hot.
-        if (num > 0) return num;
-    } else {
-        const parts = trimmed.split(/\s+/);
-        // Only the documented 5-field forms are every-N-minutes: "* * * * *" and
-        // "*/N * * * *". A first-field wildcard alone ("* 3 * * *") is real cron
-        // and must not silently fire every 60s (task 0060 F7).
-        const restWild =
-            parts.length === 5 && parts[1] === '*' && parts[2] === '*' && parts[3] === '*' && parts[4] === '*';
-        if (restWild && parts[0] === '*') {
-            return 60_000;
-        }
+        return num > 0 ? num : undefined;
+    }
 
-        const nField = restWild ? parts[0] : parts.length === 1 ? parts[0] : undefined;
-        const match = nField?.match(/^\*\/(\d+)$/);
-        if (match && Number(match[1]) > 0) {
-            return Number(match[1]) * 60_000;
-        }
+    const parts = trimmed.split(/\s+/);
+    // Only the documented 5-field forms are every-N-minutes: "* * * * *" and
+    // "*/N * * * *". A first-field wildcard alone ("* 3 * * *") is real cron
+    // and must not silently fire every 60s (task 0060 F7).
+    const restWild = parts.length === 5 && parts[1] === '*' && parts[2] === '*' && parts[3] === '*' && parts[4] === '*';
+    if (restWild && parts[0] === '*') {
+        return 60_000;
     }
 
-    // Real cron field expressions ("0 3 * * *") are NOT supported — silently running
-    // them every minute would badly misfire. 0032 made that a warn; task 0060 F7 makes
-    // it a hard error so an unsupported schedule can never fire at the wrong cadence.
-    throw new RangeError(
-        `Unsupported cron expression: "${cron}" — supported forms are a positive millisecond number, "* * * * *", or "*/N * * * *" with N > 0`,
-    );
-}
+    const nField = restWild ? parts[0] : parts.length === 1 ? parts[0] : undefined;
+    const match = nField?.match(/^\*\/(\d+)$/);
+    if (match && Number(match[1]) > 0) {
+        return Number(match[1]) * 60_000;
+    }
 
-interface ScheduledEntry {
-    cron: string;
-    action: ScheduledAction;
-    timer?: ReturnType<typeof setInterval>;
+    return undefined;
 }
 
+/** A registered entry: an interval cadence or a self-rescheduling cron tick. */
+type ScheduledEntry =
+    | {
+          kind: 'interval';
+          cron: string;
+          action: ScheduledAction;
+          intervalMs: number;
+          timer?: ReturnType<typeof setInterval>;
+      }
+    | {
+          kind: 'cron';
+          cron: string;
+          action: ScheduledAction;
+          expr: CronExpression;
+          target: number;
+          timer?: ReturnType<typeof setTimeout>;
+      };
+
 /** Constructor options for {@link NodeSchedulerAdapter}. */
 export interface NodeSchedulerAdapterConfig {
     /**
@@ -60,11 +79,17 @@ export interface NodeSchedulerAdapterConfig {
      * Defaults to 30000 (matching `DBQueueConsumer`).
      */
     readonly drainTimeoutMs?: number;
+    /**
+     * Deterministic clock seam (task 0734 R2). Returns epoch milliseconds;
+     * defaults to `Date.now`. Used for cron target computation and re-checks.
+     */
+    readonly now?: () => number;
 }
 
 /**
- * Scheduler adapter for Node.js using a setInterval-based approach.
- * No external cron library dependency — cron expressions are parsed minimally.
+ * Scheduler adapter for Node.js. Interval entries use `setInterval`; real cron
+ * entries self-reschedule with `setTimeout` so ticks never overlap and
+ * occurrences missed while a tick runs are skipped (task 0734 R2).
  *
  * `stop()` drains in-flight ticks, bounded by `drainTimeoutMs` (ADR-024): an
  * action already running when `stop()` is called is awaited rather than torn
@@ -73,32 +98,44 @@ export interface NodeSchedulerAdapterConfig {
 export class NodeSchedulerAdapter implements SchedulerAdapter {
     private readonly entries: ScheduledEntry[] = [];
     private readonly drainTimeoutMs: number;
+    private readonly now: () => number;
     private running = false;
     private readonly inflight = new Set<Promise<void>>();
 
     constructor(config: NodeSchedulerAdapterConfig = {}) {
-        const { drainTimeoutMs } = config;
+        const { drainTimeoutMs, now } = config;
         if (drainTimeoutMs !== undefined && (!Number.isFinite(drainTimeoutMs) || drainTimeoutMs < 0)) {
             throw new RangeError(
                 `NodeSchedulerAdapter drainTimeoutMs must be a non-negative finite number; received ${drainTimeoutMs}`,
             );
         }
         this.drainTimeoutMs = drainTimeoutMs ?? 30_000;
+        this.now = now ?? (() => Date.now());
     }
 
     register(cron: string, action: ScheduledAction): void {
-        // Fail at registration time: an unsupported expression must never reach start(),
-        // where it would otherwise create a silently-wrong interval (task 0060 F7).
-        parseInterval(cron);
-        this.entries.push({ cron, action });
+        // Fail at registration time: an unsupported expression must never reach
+        // start(), where it would otherwise create a silently-wrong interval
+        // (task 0060 F7) or a never-firing cron (task 0734 R1).
+        const entry = this.parseEntry(cron, action);
+        this.entries.push(entry);
         if (this.running) {
-            const last = this.entries[this.entries.length - 1];
-            if (last) {
-                this.startEntry(last);
-            }
+            this.startEntry(entry);
         }
     }
 
+    private parseEntry(cron: string, action: ScheduledAction): ScheduledEntry {
+        const intervalMs = parseInterval(cron);
+        if (intervalMs !== undefined) {
+            return { kind: 'interval', cron, action, intervalMs };
+        }
+        // Real five-field cron. Validate and verify a next occurrence exists at
+        // registration (bounded scan) so an unsatisfiable expression fails here.
+        const expr = parseCronExpression(cron);
+        const target = nextCronTime(expr, this.now()).getTime();
+        return { kind: 'cron', cron, action, expr, target };
+    }
+
     async start(): Promise<void> {
         if (this.running) return;
 
@@ -111,16 +148,21 @@ export class NodeSchedulerAdapter implements SchedulerAdapter {
     async stop(): Promise<void> {
         this.running = false;
         for (const entry of this.entries) {
-            if (entry.timer) {
-                clearInterval(entry.timer);
+            if (entry.timer !== undefined) {
+                if (entry.kind === 'interval') {
+                    clearInterval(entry.timer);
+                } else {
+                    clearTimeout(entry.timer);
+                }
                 entry.timer = undefined;
             }
         }
 
-        // Drain in-flight ticks, bounded by a shared absolute deadline. clearInterval
-        // cancels future ticks but not one already executing; without this wait a tick
-        // mid-action when stop() is called would keep running after stop() resolves,
-        // tearing down a half-written row or half-flushed batch (ADR-024).
+        // Drain in-flight ticks, bounded by a shared absolute deadline. Clearing
+        // timers cancels future ticks but not one already executing; without this
+        // wait a tick mid-action when stop() is called would keep running after
+        // stop() resolves, tearing down a half-written row or half-flushed batch
+        // (ADR-024).
         const deadline = Date.now() + this.drainTimeoutMs;
         for (const p of [...this.inflight]) {
             await settleWithin(p, deadline);
@@ -128,20 +170,77 @@ export class NodeSchedulerAdapter implements SchedulerAdapter {
     }
 
     private startEntry(entry: ScheduledEntry): void {
-        if (entry.timer) return;
-
-        const interval = parseInterval(entry.cron);
-        // setInterval discards the async handler's returned promise, so capture it
-        // here for stop() to drain. _onScheduledTick never rejects (try/catch),
-        // so the cleanup runs on both paths with no unhandled-rejection risk.
-        entry.timer = setInterval(() => {
-            const tick = this._onScheduledTick(entry);
-            this.inflight.add(tick);
-            const cleanup = (): void => {
-                this.inflight.delete(tick);
-            };
-            tick.then(cleanup, cleanup);
-        }, interval);
+        if (entry.timer !== undefined) return;
+
+        if (entry.kind === 'interval') {
+            entry.timer = setInterval(() => {
+                const tick = this._onScheduledTick(entry);
+                this.inflight.add(tick);
+                const cleanup = (): void => {
+                    this.inflight.delete(tick);
+                };
+                tick.then(cleanup, cleanup);
+            }, entry.intervalMs);
+        } else {
+            this.armCron(entry);
+        }
+    }
+
+    /**
+     * Arm the cron entry's next `setTimeout`, chunking any delay beyond the
+     * platform timer maximum. On a chunk wake the wall clock is re-checked
+     * before firing, so an injected/real clock shift never fires early.
+     */
+    private armCron(entry: Extract<ScheduledEntry, { kind: 'cron' }>): void {
+        if (!this.running) return;
+
+        let delay = entry.target - this.now();
+        if (delay <= 0) {
+            // Target already passed (clock shift): recompute strictly after now.
+            entry.target = nextCronTime(entry.expr, this.now()).getTime();
+            delay = entry.target - this.now();
+        }
+
+        if (delay > MAX_TIMEOUT) {
+            // Delay exceeds the platform maximum — arm a safe chunk; on wake,
+            // re-check now() before firing.
+            entry.timer = setTimeout(() => {
+                this.armCron(entry);
+            }, MAX_TIMEOUT);
+            return;
+        }
+
+        entry.timer = setTimeout(() => {
+            void this.fireCron(entry);
+        }, delay);
+    }
+
+    /**
+     * Fire a cron tick: re-check the wall clock against the target, run the
+     * action once, then recompute the next occurrence strictly from `now()` and
+     * re-arm only while still running. Ticks never overlap and occurrences
+     * missed while a tick runs are skipped (task 0734 R2).
+     */
+    private async fireCron(entry: Extract<ScheduledEntry, { kind: 'cron' }>): Promise<void> {
+        entry.timer = undefined;
+
+        if (this.now() < entry.target) {
+            // Not actually time yet (early chunk wake / clock shift) — re-arm.
+            this.armCron(entry);
+            return;
+        }
+
+        const tick = this._onScheduledTick(entry);
+        this.inflight.add(tick);
+        const cleanup = (): void => {
+            this.inflight.delete(tick);
+        };
+        await tick.then(cleanup, cleanup);
+
+        if (this.running) {
+            entry.target = nextCronTime(entry.expr, this.now()).getTime();
+            this.armCron(entry);
+        }
     }
 
     private async _onScheduledTick(entry: ScheduledEntry): Promise<void> {

package/src/scheduler/types.ts

@@ -17,3 +17,16 @@ export interface SchedulerAdapter {
     start(): Promise<void>;
     stop(): Promise<void>;
 }
+
+/**
+ * A declarative scheduler job (task 0734). Exactly one of `intervalMinutes` or
+ * `cron` is present — the schedule XOR is enforced by the Node subpath's
+ * `normalizeSchedulerJobs` before the user `start` callback runs.
+ *
+ * The `command` is declarative data: ts-infra validates and exposes it but
+ * never executes it. The consuming application binds it to a queue-backed
+ * command handler.
+ */
+export type SchedulerJobConfig =
+    | { readonly name: string; readonly command: string; readonly intervalMinutes: number; readonly cron?: never }
+    | { readonly name: string; readonly command: string; readonly cron: string; readonly intervalMinutes?: never };