@xopcai/xopc 0.0.110 → 0.0.112

package/dist/src/cron/schedule.d.ts

@@ -0,0 +1,10 @@
+import type { CronSchedule, JobData } from './types.js';
+export declare const DEFAULT_TOP_OF_HOUR_STAGGER_MS: number;
+export declare function normalizeCronStaggerMs(value: unknown): number | undefined;
+export declare function isRecurringTopOfHourCronExpr(expr: string): boolean;
+export declare function resolveDefaultCronStaggerMs(expr: string): number | undefined;
+export declare function resolveCronStaggerMs(schedule: CronSchedule): number;
+export declare function computeNextRunAtMs(job: Pick<JobData, 'id' | 'enabled' | 'schedule'>, nowMs?: number): number | undefined;
+export declare function computePreviousRunAtMs(job: Pick<JobData, 'id' | 'schedule'>, nowMs?: number): number | undefined;
+export declare function describeSchedule(schedule: CronSchedule): string;
+export declare function timerDelayUntil(targetMs: number, nowMs?: number): number;

package/dist/src/cron/schedule.js

@@ -0,0 +1,85 @@
+import crypto from "node:crypto";
+import { CronExpressionParser } from "cron-parser";
+//#region src/cron/schedule.ts
+const MAX_TIMER_DELAY_MS = 2147483647;
+const DEFAULT_TOP_OF_HOUR_STAGGER_MS = 5 * 6e4;
+function normalizeCronStaggerMs(value) {
+	if (typeof value !== "number" || !Number.isFinite(value) || value < 0) return;
+	return Math.floor(value);
+}
+function isRecurringTopOfHourCronExpr(expr) {
+	const parts = expr.trim().split(/\s+/);
+	if (parts.length !== 5) return false;
+	return parts[0] === "0" && parts[1] !== "*" && parts[2] === "*" && parts[3] === "*" && parts[4] === "*";
+}
+function resolveDefaultCronStaggerMs(expr) {
+	return isRecurringTopOfHourCronExpr(expr) ? DEFAULT_TOP_OF_HOUR_STAGGER_MS : void 0;
+}
+function resolveCronStaggerMs(schedule) {
+	if (schedule.kind !== "cron") return 0;
+	const explicit = normalizeCronStaggerMs(schedule.staggerMs);
+	if (explicit !== void 0) return explicit;
+	return resolveDefaultCronStaggerMs(schedule.expr) ?? 0;
+}
+function stableOffsetMs(jobId, windowMs) {
+	if (windowMs <= 1) return 0;
+	return crypto.createHash("sha256").update(jobId).digest().readUInt32BE(0) % windowMs;
+}
+function parseAtMs(at) {
+	const ms = Date.parse(at);
+	if (!Number.isFinite(ms)) throw new Error(`Invalid at schedule timestamp: ${at}`);
+	return ms;
+}
+function parseCron(schedule, currentDate) {
+	return CronExpressionParser.parse(schedule.expr, {
+		currentDate,
+		...schedule.tz ? { tz: schedule.tz } : {}
+	});
+}
+function computeNextRunAtMs(job, nowMs = Date.now()) {
+	if (!job.enabled) return void 0;
+	const schedule = job.schedule;
+	if (schedule.kind === "at") {
+		const atMs = parseAtMs(schedule.at);
+		return atMs >= nowMs ? atMs : void 0;
+	}
+	if (schedule.kind === "every") {
+		const everyMs = Math.max(1, Math.floor(schedule.everyMs));
+		const anchorMs = Math.max(0, Math.floor(schedule.anchorMs ?? nowMs));
+		if (anchorMs >= nowMs) return anchorMs;
+		const elapsed = nowMs - anchorMs;
+		return anchorMs + (Math.floor(elapsed / everyMs) + 1) * everyMs;
+	}
+	const staggerMs = resolveCronStaggerMs(schedule);
+	const offsetMs = stableOffsetMs(job.id, staggerMs);
+	return parseCron(schedule, new Date(Math.max(0, nowMs - offsetMs))).next().getTime() + offsetMs;
+}
+function computePreviousRunAtMs(job, nowMs = Date.now()) {
+	const schedule = job.schedule;
+	if (schedule.kind === "at") {
+		const atMs = parseAtMs(schedule.at);
+		return atMs <= nowMs ? atMs : void 0;
+	}
+	if (schedule.kind === "every") {
+		const everyMs = Math.max(1, Math.floor(schedule.everyMs));
+		const anchorMs = Math.max(0, Math.floor(schedule.anchorMs ?? nowMs));
+		if (anchorMs > nowMs) return void 0;
+		const elapsed = nowMs - anchorMs;
+		return anchorMs + Math.floor(elapsed / everyMs) * everyMs;
+	}
+	const staggerMs = resolveCronStaggerMs(schedule);
+	const offsetMs = stableOffsetMs(job.id, staggerMs);
+	return parseCron(schedule, new Date(Math.max(0, nowMs - offsetMs))).prev().getTime() + offsetMs;
+}
+function describeSchedule(schedule) {
+	if (schedule.kind === "at") return `at ${schedule.at}`;
+	if (schedule.kind === "every") return `every ${schedule.everyMs}ms`;
+	return `cron ${schedule.expr}${schedule.tz ? ` (${schedule.tz})` : ""}`;
+}
+function timerDelayUntil(targetMs, nowMs = Date.now()) {
+	return Math.max(0, Math.min(MAX_TIMER_DELAY_MS, targetMs - nowMs));
+}
+//#endregion
+export { DEFAULT_TOP_OF_HOUR_STAGGER_MS, computeNextRunAtMs, computePreviousRunAtMs, describeSchedule, isRecurringTopOfHourCronExpr, normalizeCronStaggerMs, resolveCronStaggerMs, resolveDefaultCronStaggerMs, timerDelayUntil };
+
+//# sourceMappingURL=schedule.js.map

package/dist/src/cron/schedule.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schedule.js","names":[],"sources":["../../../src/cron/schedule.ts"],"sourcesContent":["import crypto from 'node:crypto';\n\nimport { CronExpressionParser } from 'cron-parser';\n\nimport type { CronSchedule, JobData } from './types.js';\n\nconst MAX_TIMER_DELAY_MS = 2_147_483_647;\nexport const DEFAULT_TOP_OF_HOUR_STAGGER_MS = 5 * 60_000;\n\nexport function normalizeCronStaggerMs(value: unknown): number | undefined {\n  if (typeof value !== 'number' || !Number.isFinite(value) || value < 0) {\n    return undefined;\n  }\n  return Math.floor(value);\n}\n\nexport function isRecurringTopOfHourCronExpr(expr: string): boolean {\n  const parts = expr.trim().split(/\\s+/);\n  if (parts.length !== 5) return false;\n  return parts[0] === '0' && parts[1] !== '*' && parts[2] === '*' && parts[3] === '*' && parts[4] === '*';\n}\n\nexport function resolveDefaultCronStaggerMs(expr: string): number | undefined {\n  return isRecurringTopOfHourCronExpr(expr) ? DEFAULT_TOP_OF_HOUR_STAGGER_MS : undefined;\n}\n\nexport function resolveCronStaggerMs(schedule: CronSchedule): number {\n  if (schedule.kind !== 'cron') return 0;\n  const explicit = normalizeCronStaggerMs(schedule.staggerMs);\n  if (explicit !== undefined) return explicit;\n  return resolveDefaultCronStaggerMs(schedule.expr) ?? 0;\n}\n\nfunction stableOffsetMs(jobId: string, windowMs: number): number {\n  if (windowMs <= 1) return 0;\n  const digest = crypto.createHash('sha256').update(jobId).digest();\n  return digest.readUInt32BE(0) % windowMs;\n}\n\nfunction parseAtMs(at: string): number {\n  const ms = Date.parse(at);\n  if (!Number.isFinite(ms)) {\n    throw new Error(`Invalid at schedule timestamp: ${at}`);\n  }\n  return ms;\n}\n\nfunction parseCron(schedule: Extract<CronSchedule, { kind: 'cron' }>, currentDate: Date) {\n  return CronExpressionParser.parse(schedule.expr, {\n    currentDate,\n    ...(schedule.tz ? { tz: schedule.tz } : {}),\n  });\n}\n\nexport function computeNextRunAtMs(job: Pick<JobData, 'id' | 'enabled' | 'schedule'>, nowMs = Date.now()): number | undefined {\n  if (!job.enabled) return undefined;\n  const schedule = job.schedule;\n  if (schedule.kind === 'at') {\n    const atMs = parseAtMs(schedule.at);\n    return atMs >= nowMs ? atMs : undefined;\n  }\n  if (schedule.kind === 'every') {\n    const everyMs = Math.max(1, Math.floor(schedule.everyMs));\n    const anchorMs = Math.max(0, Math.floor(schedule.anchorMs ?? nowMs));\n    if (anchorMs >= nowMs) return anchorMs;\n    const elapsed = nowMs - anchorMs;\n    return anchorMs + (Math.floor(elapsed / everyMs) + 1) * everyMs;\n  }\n\n  const staggerMs = resolveCronStaggerMs(schedule);\n  const offsetMs = stableOffsetMs(job.id, staggerMs);\n  const interval = parseCron(schedule, new Date(Math.max(0, nowMs - offsetMs)));\n  return interval.next().getTime() + offsetMs;\n}\n\nexport function computePreviousRunAtMs(job: Pick<JobData, 'id' | 'schedule'>, nowMs = Date.now()): number | undefined {\n  const schedule = job.schedule;\n  if (schedule.kind === 'at') {\n    const atMs = parseAtMs(schedule.at);\n    return atMs <= nowMs ? atMs : undefined;\n  }\n  if (schedule.kind === 'every') {\n    const everyMs = Math.max(1, Math.floor(schedule.everyMs));\n    const anchorMs = Math.max(0, Math.floor(schedule.anchorMs ?? nowMs));\n    if (anchorMs > nowMs) return undefined;\n    const elapsed = nowMs - anchorMs;\n    return anchorMs + Math.floor(elapsed / everyMs) * everyMs;\n  }\n\n  const staggerMs = resolveCronStaggerMs(schedule);\n  const offsetMs = stableOffsetMs(job.id, staggerMs);\n  const interval = parseCron(schedule, new Date(Math.max(0, nowMs - offsetMs)));\n  return interval.prev().getTime() + offsetMs;\n}\n\nexport function describeSchedule(schedule: CronSchedule): string {\n  if (schedule.kind === 'at') return `at ${schedule.at}`;\n  if (schedule.kind === 'every') return `every ${schedule.everyMs}ms`;\n  return `cron ${schedule.expr}${schedule.tz ? ` (${schedule.tz})` : ''}`;\n}\n\nexport function timerDelayUntil(targetMs: number, nowMs = Date.now()): number {\n  return Math.max(0, Math.min(MAX_TIMER_DELAY_MS, targetMs - nowMs));\n}\n"],"mappings":"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"}

package/dist/src/cron/service.d.ts

@@ -1,101 +1,58 @@
-import { Config } from '../config/index.js';
-import type { JobData, JobExecution, JobExecutorDeps, CronMetrics, CronHealth, AddJobOptions, JobWithNextRun, CronRunHistoryRow } from './types.js';
+import type { Config } from '../config/schema.js';
+import type { AddJobOptions, CronHealth, CronJobPatch, CronMetrics, CronRunHistoryRow, JobData, JobExecution, JobExecutorDeps } from './types.js';
 export interface CronServiceConfig {
-    filePath?: string;
-    agentService?: any;
-    messageBus?: any;
-    /** Override SQLite database path (tests). */
     dbPath?: string;
+    agentService?: unknown;
+    messageBus?: unknown;
+    maxConcurrentJobs?: number;
+    missedJobStaggerMs?: number;
+}
+export declare class CronJobAlreadyRunningError extends Error {
+    readonly jobId: string;
+    readonly runningSessionKey?: string;
+    constructor(jobId: string, runningSessionKey?: string);
+}
+export interface CronJobRunNowResult {
+    job: JobData;
+    history: JobExecution[];
 }
 export declare class CronService {
-    private persistence;
     private executor;
     private runLogStore;
-    private tasks;
     private initialized;
-    private agentService;
-    private messageBus;
+    private stopped;
+    private running;
+    private timer;
+    private deps;
+    private maxConcurrentJobs;
+    private missedJobStaggerMs;
     constructor(config?: CronServiceConfig);
-    /**
-     * Set dependencies for the executor
-     */
     setDeps(deps: JobExecutorDeps): void;
-    /**
-     * Initialize the service and load all jobs
-     */
     initialize(): Promise<void>;
-    /**
-     * Add a new job
-     */
-    addJob(schedule: string, options: AddJobOptions): Promise<{
+    addJob(scheduleOrInput: AddJobOptions['schedule'], options?: Omit<AddJobOptions, 'schedule'>): Promise<{
         id: string;
-        schedule: string;
+        schedule: AddJobOptions['schedule'];
     }>;
-    /**
-     * List all jobs with next run time
-     */
-    listJobs(): Promise<JobWithNextRun[]>;
-    /**
-     * Get a single job
-     */
+    listJobs(): Promise<JobData[]>;
     getJob(id: string): Promise<JobData | null>;
-    /**
-     * Update a job
-     */
-    updateJob(id: string, updates: Partial<Omit<JobData, 'id' | 'created_at' | 'updated_at'>>): Promise<boolean>;
-    /**
-     * Remove a job
-     */
+    updateJob(id: string, updates: CronJobPatch): Promise<boolean>;
     removeJob(id: string): Promise<boolean>;
-    /**
-     * Toggle job enabled state
-     */
     toggleJob(id: string, enabled: boolean): Promise<boolean>;
-    /**
-     * Execution history for one job: merged in-memory (incl. running) + persisted SQLite rows.
-     */
     getJobHistory(jobId: string, limit?: number): Promise<JobExecution[]>;
-    /**
-     * Latest runs across all jobs (persisted rows + optional job name).
-     */
     getAllRunsHistory(limit?: number): Promise<CronRunHistoryRow[]>;
-    /**
-     * Get service metrics
-     */
     getMetrics(): Promise<CronMetrics>;
-    /**
-     * Update config (hot reload)
-     */
-    updateConfig(_config: Config): void;
-    /**
-     * Health check
-     */
+    updateConfig(config: Config): void;
     healthCheck(): Promise<CronHealth>;
-    /**
-     * Run a job immediately (manual trigger)
-     */
-    runJobNow(id: string): Promise<void>;
-    /**
-     * Stop all jobs and cleanup
-     */
+    runJobNow(id: string): Promise<CronJobRunNowResult>;
     stop(options?: {
         waitForRunning?: boolean;
         timeout?: number;
     }): Promise<void>;
-    /**
-     * Load and schedule all enabled jobs
-     */
-    private loadAllJobs;
-    /**
-     * Schedule a job with node-cron
-     */
-    private scheduleJob;
-    /**
-     * Execute a job with retry logic
-     */
-    private executeJob;
-    /**
-     * Cancel a scheduled task
-     */
-    private cancelTask;
+    private recomputeAllNextRuns;
+    private armTimer;
+    private onTimer;
+    private startSingleJob;
+    private runSingleJob;
+    private runReservedJob;
+    private maybeEmitFailureAlert;
 }