@gobing-ai/ts-infra 0.4.49 → 0.4.51

package/dist/scheduler/node.js

@@ -1,43 +1,50 @@
 /**
- * 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.js';
 import { getSchedulerJobDuration, getSchedulerJobExecutedTotal, getSchedulerJobFailedTotal, } from '../telemetry/metrics.js';
-/** Simple helper to parse cron-like interval strings into milliseconds. */
+import { nextCronTime, parseCronExpression } from './cron.js';
+/** 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) {
-    // Support simple patterns: "* * * * *" (every minute), "*/5 * * * *" (every 5 min)
-    // Also support direct ms strings like "60000"
     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;
+        return num > 0 ? num : undefined;
     }
-    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;
-        }
-        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;
+    }
+    return undefined;
 }
 /**
- * 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
@@ -46,27 +53,38 @@ function parseInterval(cron) {
 export class NodeSchedulerAdapter {
     entries = [];
     drainTimeoutMs;
+    now;
     running = false;
     inflight = new Set();
     constructor(config = {}) {
-        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, action) {
-        // 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);
         }
     }
+    parseEntry(cron, action) {
+        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() {
         if (this.running)
             return;
@@ -78,35 +96,92 @@ export class NodeSchedulerAdapter {
     async stop() {
         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);
         }
     }
     startEntry(entry) {
-        if (entry.timer)
+        if (entry.timer !== undefined)
             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 = () => {
-                this.inflight.delete(tick);
-            };
-            tick.then(cleanup, cleanup);
-        }, interval);
+        if (entry.kind === 'interval') {
+            entry.timer = setInterval(() => {
+                const tick = this._onScheduledTick(entry);
+                this.inflight.add(tick);
+                const cleanup = () => {
+                    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.
+     */
+    armCron(entry) {
+        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).
+     */
+    async fireCron(entry) {
+        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 = () => {
+            this.inflight.delete(tick);
+        };
+        await tick.then(cleanup, cleanup);
+        if (this.running) {
+            entry.target = nextCronTime(entry.expr, this.now()).getTime();
+            this.armCron(entry);
+        }
     }
     async _onScheduledTick(entry) {
         const startMs = performance.now();

package/dist/scheduler/types.d.ts

@@ -15,4 +15,24 @@ 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;
+};
 //# sourceMappingURL=types.d.ts.map

package/dist/scheduler/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/scheduler/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,+CAA+C;AAC/C,MAAM,MAAM,eAAe,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;AAElD;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,eAAe,GAAG,IAAI,CAAC;IACtD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACzB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/scheduler/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,+CAA+C;AAC/C,MAAM,MAAM,eAAe,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;AAElD;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,eAAe,GAAG,IAAI,CAAC;IACtD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACzB;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,kBAAkB,GACxB;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,KAAK,CAAA;CAAE,GAC5G;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,eAAe,CAAC,EAAE,KAAK,CAAA;CAAE,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gobing-ai/ts-infra",
-    "version": "0.4.49",
+    "version": "0.4.51",
     "description": "@gobing-ai/ts-infra — Infrastructure backbone: event bus, job queue, scheduler, telemetry, API client, and logging.",
     "keywords": [
         "typescript",
@@ -78,12 +78,12 @@
         "release": "echo 'Manual publish is disabled. Releases go through GitHub Actions via Trusted Publishing — push a tag: git tag @gobing-ai/ts-infra-v<version> && git push --tags' && exit 1"
     },
     "dependencies": {
-        "@gobing-ai/ts-utils": "^0.4.49",
+        "@gobing-ai/ts-utils": "^0.4.51",
         "@logtape/logtape": "^2.0.0"
     },
     "peerDependencies": {
-        "@gobing-ai/ts-db": "^0.4.49",
-        "@gobing-ai/ts-runtime": "^0.4.49",
+        "@gobing-ai/ts-db": "^0.4.51",
+        "@gobing-ai/ts-runtime": "^0.4.51",
         "@opentelemetry/api": "^1.9.0",
         "@opentelemetry/sdk-trace-node": "^2.0.0",
         "@opentelemetry/sdk-metrics": "^2.0.0",
@@ -116,8 +116,8 @@
         }
     },
     "devDependencies": {
-        "@gobing-ai/ts-db": "^0.4.49",
-        "@gobing-ai/ts-runtime": "^0.4.49",
+        "@gobing-ai/ts-db": "^0.4.51",
+        "@gobing-ai/ts-runtime": "^0.4.51",
         "@types/bun": "1.3.14",
         "@opentelemetry/api": "^1.9.0",
         "@opentelemetry/sdk-trace-node": "^2.0.0",

package/src/application/index.ts

@@ -125,6 +125,7 @@ export async function runApplication<TAppConfig = unknown, TEvents extends Event
     const schedulerConfig: ApplicationBootstrapConfig['scheduler'] = {
         enabled: schedOpts?.enabled ?? false,
         autoStart: schedOpts?.autoStart ?? true,
+        jobs: schedOpts?.jobs ?? [],
     };
     const eventsEnabled = options.config?.events?.enabled ?? true;
     const eventsLifecycle = options.config?.events?.lifecycle ?? true;
@@ -259,6 +260,7 @@ export async function runApplication<TAppConfig = unknown, TEvents extends Event
 
 export type { BusLifecycleEvents, EventMap } from '../event-bus/types';
 export type { InfraEvents } from '../events';
+export type { SchedulerJobConfig } from '../scheduler/types';
 export type { PluginHost } from './plugins/host';
 export type { Plugin, PluginSummary } from './plugins/types';
 // Re-export types

package/src/application/types.ts

@@ -13,7 +13,7 @@ import type { FileObserverWriter } from '../event-bus/file-observer';
 import type { BusLifecycleEvents, EventMap } from '../event-bus/types';
 import type { InfraEvents } from '../events';
 import type { Logger, LogLevel } from '../logger';
-import type { SchedulerAdapter } from '../scheduler/types';
+import type { SchedulerAdapter, SchedulerJobConfig } from '../scheduler/types';
 import type { PluginHost } from './plugins/host';
 import type { Plugin } from './plugins/types';
 
@@ -84,6 +84,13 @@ export interface SchedulerOptions {
     entries?: Array<[string, () => Promise<void>]>;
     /** Start scheduler immediately after registration. Default `true` when enabled. */
     autoStart?: boolean;
+    /**
+     * Declarative scheduler jobs (task 0734). Validated and normalized by the
+     * Node subpath (`runNodeApplication`) before the user `start` callback;
+     * forwarded as data into the resolved config. ts-infra never executes the
+     * job `command` itself.
+     */
+    jobs?: readonly SchedulerJobConfig[];
 }
 
 // ── Resolved bootstrap config ─────────────────────────────────────────────
@@ -106,7 +113,7 @@ export interface ApplicationBootstrapConfig {
         filePath?: string;
     };
     readonly telemetry: { enabled: boolean; serviceName: string; environment: string; dbStatementDebug: boolean };
-    readonly scheduler: { enabled: boolean; autoStart: boolean };
+    readonly scheduler: { enabled: boolean; autoStart: boolean; jobs: readonly SchedulerJobConfig[] };
 }
 
 // ── Injected services ─────────────────────────────────────────────────────

package/src/application-node.ts

@@ -39,6 +39,8 @@ import type {
     SchedulerOptions,
     TelemetryOptions,
 } from './application/types';
+import { parseCronExpression } from './scheduler/cron';
+import type { SchedulerJobConfig } from './scheduler/types';
 import { NodeSchedulerAdapter } from './scheduler-node';
 import { initNodeTelemetry, shutdownNodeTelemetry } from './telemetry/otel-node';
 
@@ -52,6 +54,9 @@ export class ConfigValidationError extends Error {
     }
 }
 
+/** Platform timer maximum for `setTimeout` (2^31 - 1 ms). */
+const MAX_TIMEOUT_MS = 2_147_483_647;
+
 // ── Config validation helper ──────────────────────────────────────────────
 
 /**
@@ -92,6 +97,92 @@ function validateAppConfig<TAppConfig>(
     throw new ConfigValidationError(`Unsupported validator shape for section "${section}"`);
 }
 
+// ── Scheduler job validation (task 0734) ────────────────────────────────────
+
+/** Max `intervalMinutes` so that `intervalMinutes * 60_000` fits in the platform timer maximum. */
+const MAX_INTERVAL_MINUTES = Math.floor(MAX_TIMEOUT_MS / 60_000);
+
+/**
+ * Validate and normalize a raw `bootstrap.scheduler.jobs` array.
+ *
+ * Accepts only object entries, trims `name`/`command`/`cron`, enforces the
+ * schedule XOR and `intervalMinutes` bounds, validates cron through the shared
+ * internal parser, and rejects duplicate post-trim names case-sensitively.
+ * Runs whether the scheduler is enabled or disabled; a disabled scheduler may
+ * retain validated job definitions but creates no adapter (R4).
+ *
+ * Throws `ConfigValidationError` with a `bootstrap.scheduler.jobs.<index>.<field>`
+ * path so a bad job aborts startup before the user `start` callback.
+ */
+function normalizeSchedulerJobs(raw: unknown): readonly SchedulerJobConfig[] {
+    if (raw === undefined || raw === null) return [];
+    if (!Array.isArray(raw)) {
+        throw new ConfigValidationError('bootstrap.scheduler.jobs must be an array');
+    }
+
+    const seen = new Set<string>();
+    const jobs: SchedulerJobConfig[] = [];
+    raw.forEach((item, index) => {
+        if (typeof item !== 'object' || item === null || Array.isArray(item)) {
+            throw new ConfigValidationError(`bootstrap.scheduler.jobs.${index} must be an object`);
+        }
+        const entry = item as Record<string, unknown>;
+        const name = typeof entry.name === 'string' ? entry.name.trim() : '';
+        const command = typeof entry.command === 'string' ? entry.command.trim() : '';
+        const cron = typeof entry.cron === 'string' ? entry.cron.trim() : '';
+        const interval = entry.intervalMinutes;
+
+        if (name === '') {
+            throw new ConfigValidationError(`bootstrap.scheduler.jobs.${index}.name must be a non-empty string`);
+        }
+        if (command === '') {
+            throw new ConfigValidationError(`bootstrap.scheduler.jobs.${index}.command must be a non-empty string`);
+        }
+
+        const hasCron = entry.cron !== undefined && entry.cron !== null;
+        const hasInterval = interval !== undefined && interval !== null;
+        if (hasCron === hasInterval) {
+            throw new ConfigValidationError(
+                `bootstrap.scheduler.jobs.${index} must have exactly one of intervalMinutes or cron`,
+            );
+        }
+
+        if (seen.has(name)) {
+            throw new ConfigValidationError(
+                `bootstrap.scheduler.jobs.${index}.name duplicates the name of an earlier job: "${name}"`,
+            );
+        }
+        seen.add(name);
+
+        if (hasInterval) {
+            if (
+                typeof interval !== 'number' ||
+                !Number.isInteger(interval) ||
+                (interval as number) < 1 ||
+                (interval as number) > MAX_INTERVAL_MINUTES
+            ) {
+                throw new ConfigValidationError(
+                    `bootstrap.scheduler.jobs.${index}.intervalMinutes must be an integer in 1..${MAX_INTERVAL_MINUTES}`,
+                );
+            }
+            jobs.push({ name, command, intervalMinutes: interval as number });
+        } else {
+            if (cron === '') {
+                throw new ConfigValidationError(`bootstrap.scheduler.jobs.${index}.cron must be a non-empty string`);
+            }
+            try {
+                parseCronExpression(cron);
+            } catch (error) {
+                const detail = error instanceof Error ? error.message : String(error);
+                throw new ConfigValidationError(`bootstrap.scheduler.jobs.${index}.cron: ${detail}`);
+            }
+            jobs.push({ name, command, cron });
+        }
+    });
+
+    return jobs;
+}
+
 // ── File sink helper ──────────────────────────────────────────────────────
 
 function createFileSink(filePath: string): (line: string) => void {
@@ -264,16 +355,22 @@ export async function runNodeApplication<TAppConfig = unknown, TEvents extends E
     const loggingConfig: Partial<LoggingOptions> =
         typeof logFilePath === 'string' ? { ...loggingOpts, fileSink: createFileSink(logFilePath) } : loggingOpts;
 
-    // ── Scheduler adapter ───────────────────────────────────────────────
+    // ── Scheduler adapter + jobs ────────────────────────────────────────
     // Honour a caller-supplied `SchedulerOptions.adapter` (documented injection
     // point, application/types.ts:82) instead of unconditionally overwriting
     // it. Only default-construct a NodeSchedulerAdapter when none was provided.
     // `drainTimeoutMs` (ADR-024) is reachable by passing a pre-built adapter;
     // the auto-wired default keeps the 30000 ms bound (CHANGELOG.md:16).
-    const schedulerConfig: SchedulerOptions = {};
-    if (schedulerOpts.enabled === true) {
-        schedulerConfig.enabled = true;
-        schedulerConfig.autoStart = schedulerOpts.autoStart;
+    //
+    // Declarative jobs (task 0734) are validated and normalized whether or not
+    // the scheduler is enabled — a disabled scheduler may retain validated job
+    // definitions but creates no adapter and runs nothing (R4).
+    const schedulerConfig: SchedulerOptions = {
+        enabled: schedulerOpts.enabled === true,
+        autoStart: schedulerOpts.autoStart,
+        jobs: normalizeSchedulerJobs((schedulerOpts as Partial<SchedulerOptions>).jobs),
+    };
+    if (schedulerConfig.enabled) {
         schedulerConfig.adapter = schedulerOpts.adapter ?? new NodeSchedulerAdapter();
         if (schedulerOpts.entries) {
             schedulerConfig.entries = schedulerOpts.entries;