@stonyx/cron 0.2.1-alpha.2 → 0.2.1-alpha.20

package/dist/schedule.js

@@ -0,0 +1,65 @@
+/**
+ * Schedule types and next-run computation.
+ *
+ * Three schedule kinds:
+ *   - "at": One-shot at an absolute ISO-8601 timestamp
+ *   - "every": Recurring interval in milliseconds
+ *   - "cron": 5-field cron expression with optional timezone
+ */
+import { nextOccurrence, validateCronExpression } from './cron-parser.js';
+/**
+ * Compute the next run time for a schedule.
+ */
+export function computeNextRunAtMs(schedule, nowMs) {
+    if (schedule.kind === 'at') {
+        const atMs = typeof schedule.at === 'number' ? schedule.at : Date.parse(schedule.at);
+        if (!Number.isFinite(atMs))
+            return undefined;
+        return atMs > nowMs ? atMs : undefined;
+    }
+    if (schedule.kind === 'every') {
+        const everyMs = Math.max(1, Math.floor(schedule.everyMs));
+        const anchor = Math.max(0, Math.floor(schedule.anchorMs ?? nowMs));
+        if (nowMs < anchor)
+            return anchor;
+        const elapsed = nowMs - anchor;
+        const steps = Math.max(1, Math.floor((elapsed + everyMs - 1) / everyMs));
+        return anchor + steps * everyMs;
+    }
+    if (schedule.kind === 'cron') {
+        const tz = schedule.tz?.trim() || undefined;
+        // Round nowMs down to the current second to avoid sub-second drift
+        const nowSecondMs = Math.floor(nowMs / 1000) * 1000;
+        return nextOccurrence(schedule.expr.trim(), nowSecondMs, tz);
+    }
+    throw new Error(`Unknown schedule kind: "${schedule.kind}"`);
+}
+/**
+ * Validate a schedule definition.
+ */
+export function validateSchedule(schedule) {
+    if (!schedule || typeof schedule !== 'object') {
+        throw new Error('Schedule must be an object');
+    }
+    if (schedule.kind === 'at') {
+        const atMs = typeof schedule.at === 'number' ? schedule.at : Date.parse(schedule.at);
+        if (!Number.isFinite(atMs)) {
+            throw new Error(`Invalid "at" timestamp: "${schedule.at}"`);
+        }
+        return;
+    }
+    if (schedule.kind === 'every') {
+        if (typeof schedule.everyMs !== 'number' || schedule.everyMs < 1) {
+            throw new Error(`"every" schedule requires everyMs >= 1, got: ${schedule.everyMs}`);
+        }
+        return;
+    }
+    if (schedule.kind === 'cron') {
+        if (typeof schedule.expr !== 'string' || !schedule.expr.trim()) {
+            throw new Error('"cron" schedule requires a non-empty expr string');
+        }
+        validateCronExpression(schedule.expr.trim());
+        return;
+    }
+    throw new Error(`Unknown schedule kind: "${schedule.kind}"`);
+}

package/dist/service.d.ts

@@ -0,0 +1,85 @@
+import MinHeap, { type HeapItem } from './min-heap.js';
+import { type Job, type JobPatch } from './job.js';
+import RunLog from './run-log.js';
+interface HeapEntry extends HeapItem {
+    key: string;
+}
+interface JobDueResult {
+    status?: string;
+    error?: string;
+    summary?: string;
+}
+interface ExecuteResult {
+    status: string;
+    error?: string;
+    summary?: string;
+    durationMs?: number;
+    deleted?: boolean;
+    reason?: string;
+}
+interface ServiceStatus {
+    started: boolean;
+    jobCount: number;
+    nextWakeAtMs: number | undefined;
+}
+interface ListOptions {
+    includeDisabled?: boolean;
+}
+type OnJobDueCallback = (job: Job) => Promise<JobDueResult | void> | JobDueResult | void;
+export default class CronService {
+    jobs: Map<string, Job>;
+    heap: MinHeap<HeapEntry>;
+    timer: ReturnType<typeof setTimeout> | null;
+    running: boolean;
+    runLog: RunLog;
+    started: boolean;
+    onJobDue: OnJobDueCallback | null;
+    constructor();
+    /**
+     * Start the service. Loads jobs from store (if any), arms timer.
+     */
+    start(initialJobs?: Job[]): Promise<void>;
+    /**
+     * Stop the service. Clears timer.
+     */
+    stop(): void;
+    /**
+     * Get service status.
+     */
+    status(): ServiceStatus;
+    /**
+     * List jobs, optionally including disabled ones.
+     */
+    list(opts?: ListOptions): Job[];
+    /**
+     * Get a single job by ID.
+     */
+    get(id: string): Job | null;
+    /**
+     * Add a new job. Input is normalized for AI compatibility.
+     */
+    add(rawInput: Record<string, unknown>): Promise<Job>;
+    /**
+     * Update an existing job.
+     */
+    update(id: string, patch: JobPatch): Promise<Job>;
+    /**
+     * Remove a job.
+     */
+    remove(id: string): Promise<void>;
+    /**
+     * Manually trigger a job.
+     */
+    run(id: string, mode?: 'due' | 'force'): Promise<ExecuteResult>;
+    /**
+     * Get run history for a job.
+     */
+    runs(id: string, limit?: number): ReturnType<RunLog['get']>;
+    armTimer(): void;
+    onTimer(): Promise<void>;
+    findDueJobs(nowMs: number): Job[];
+    executeJob(job: Job): Promise<ExecuteResult>;
+    removeFromHeap(id: string): void;
+    log(message: string): void;
+}
+export {};

package/dist/service.js

@@ -0,0 +1,271 @@
+/**
+ * CronService - the main API for advanced job scheduling.
+ *
+ * Manages jobs in memory with a min-heap for efficient next-job lookup.
+ * All state mutations are serialized via async locking.
+ */
+import config from 'stonyx/config';
+import log from 'stonyx/log';
+import MinHeap from './min-heap.js';
+import { createJob, updateJob, markRunning, applyResult, isDue } from './job.js';
+import { locked } from './locked.js';
+import { normalizeJobInput, recoverFlatParams } from './normalize.js';
+import RunLog from './run-log.js';
+const MAX_TIMER_DELAY_MS = 60_000;
+export default class CronService {
+    jobs;
+    heap;
+    timer;
+    running;
+    runLog;
+    started;
+    // Pluggable callbacks for consumers
+    onJobDue;
+    constructor() {
+        this.jobs = new Map();
+        this.heap = new MinHeap();
+        this.timer = null;
+        this.running = false;
+        this.runLog = new RunLog();
+        this.started = false;
+        this.onJobDue = null;
+    }
+    // -- Lifecycle -------------------------------------------------------
+    /**
+     * Start the service. Loads jobs from store (if any), arms timer.
+     */
+    async start(initialJobs) {
+        if (this.started)
+            return;
+        this.started = true;
+        if (initialJobs) {
+            for (const job of initialJobs) {
+                this.jobs.set(job.id, job);
+                if (job.enabled && job.state.nextRunAtMs) {
+                    this.heap.push({ key: job.id, nextTrigger: job.state.nextRunAtMs });
+                }
+            }
+        }
+        this.armTimer();
+    }
+    /**
+     * Stop the service. Clears timer.
+     */
+    stop() {
+        this.started = false;
+        if (this.timer)
+            clearTimeout(this.timer);
+        this.timer = null;
+    }
+    // -- CRUD ------------------------------------------------------------
+    /**
+     * Get service status.
+     */
+    status() {
+        const peek = this.heap.peek();
+        return {
+            started: this.started,
+            jobCount: this.jobs.size,
+            nextWakeAtMs: peek ? peek.nextTrigger : undefined,
+        };
+    }
+    /**
+     * List jobs, optionally including disabled ones.
+     */
+    list(opts) {
+        const includeDisabled = opts?.includeDisabled ?? false;
+        const jobs = [...this.jobs.values()];
+        const filtered = includeDisabled ? jobs : jobs.filter(j => j.enabled);
+        return filtered.sort((a, b) => (a.state.nextRunAtMs ?? Infinity) - (b.state.nextRunAtMs ?? Infinity));
+    }
+    /**
+     * Get a single job by ID.
+     */
+    get(id) {
+        return this.jobs.get(id) || null;
+    }
+    /**
+     * Add a new job. Input is normalized for AI compatibility.
+     */
+    async add(rawInput) {
+        return locked(() => {
+            const input = normalizeJobInput(recoverFlatParams(rawInput));
+            const job = createJob(input);
+            this.jobs.set(job.id, job);
+            if (job.enabled && job.state.nextRunAtMs) {
+                this.heap.push({ key: job.id, nextTrigger: job.state.nextRunAtMs });
+                this.armTimer();
+            }
+            return job;
+        });
+    }
+    /**
+     * Update an existing job.
+     */
+    async update(id, patch) {
+        return locked(() => {
+            const job = this.jobs.get(id);
+            if (!job)
+                throw new Error(`Job not found: ${id}`);
+            const oldNextRun = job.state.nextRunAtMs;
+            updateJob(job, patch);
+            // Update heap entry
+            this.removeFromHeap(id);
+            if (job.enabled && job.state.nextRunAtMs) {
+                this.heap.push({ key: id, nextTrigger: job.state.nextRunAtMs });
+            }
+            if (job.state.nextRunAtMs !== oldNextRun) {
+                this.armTimer();
+            }
+            return job;
+        });
+    }
+    /**
+     * Remove a job.
+     */
+    async remove(id) {
+        return locked(() => {
+            const job = this.jobs.get(id);
+            if (!job)
+                throw new Error(`Job not found: ${id}`);
+            this.jobs.delete(id);
+            this.removeFromHeap(id);
+            this.runLog.removeJob(id);
+            this.armTimer();
+        });
+    }
+    /**
+     * Manually trigger a job.
+     */
+    async run(id, mode = 'force') {
+        const job = this.jobs.get(id);
+        if (!job)
+            throw new Error(`Job not found: ${id}`);
+        if (mode === 'due' && !isDue(job, Date.now())) {
+            return { status: 'skipped', reason: 'not due' };
+        }
+        return this.executeJob(job);
+    }
+    /**
+     * Get run history for a job.
+     */
+    runs(id, limit) {
+        return this.runLog.get(id, limit);
+    }
+    // -- Timer Engine ----------------------------------------------------
+    armTimer() {
+        if (this.timer)
+            clearTimeout(this.timer);
+        if (!this.started)
+            return;
+        const peek = this.heap.peek();
+        if (!peek)
+            return;
+        const delay = Math.min(Math.max(peek.nextTrigger - Date.now(), 0), MAX_TIMER_DELAY_MS);
+        this.timer = setTimeout(() => this.onTimer(), delay);
+    }
+    async onTimer() {
+        if (this.running) {
+            // Already processing - re-arm at max delay to prevent scheduler death
+            this.timer = setTimeout(() => this.onTimer(), MAX_TIMER_DELAY_MS);
+            return;
+        }
+        this.running = true;
+        try {
+            await locked(async () => {
+                const nowMs = Date.now();
+                const dueJobs = this.findDueJobs(nowMs);
+                for (const job of dueJobs) {
+                    markRunning(job);
+                }
+                for (const job of dueJobs) {
+                    await this.executeJob(job);
+                }
+            });
+        }
+        finally {
+            this.running = false;
+            this.armTimer();
+        }
+    }
+    findDueJobs(nowMs) {
+        const due = [];
+        while (!this.heap.isEmpty()) {
+            const peek = this.heap.peek();
+            if (!peek || peek.nextTrigger > nowMs)
+                break;
+            this.heap.pop();
+            const job = this.jobs.get(peek.key);
+            if (job && isDue(job, nowMs)) {
+                due.push(job);
+            }
+        }
+        return due;
+    }
+    async executeJob(job) {
+        const startMs = Date.now();
+        let status = 'ok';
+        let error;
+        let summary;
+        try {
+            if (this.onJobDue) {
+                const result = await this.onJobDue(job);
+                if (result) {
+                    status = result.status || 'ok';
+                    error = result.error;
+                    summary = result.summary;
+                }
+            }
+        }
+        catch (err) {
+            status = 'error';
+            error = err instanceof Error ? err.message : String(err);
+            this.log(`Job "${job.name}" (${job.id}) failed: ${error}`);
+        }
+        const durationMs = Date.now() - startMs;
+        const validStatus = (status === 'ok' || status === 'error' || status === 'skipped') ? status : 'error';
+        applyResult(job, validStatus, error, durationMs);
+        // Log the run
+        this.runLog.record({
+            jobId: job.id,
+            status,
+            error,
+            summary,
+            runAtMs: startMs,
+            durationMs,
+            nextRunAtMs: job.state.nextRunAtMs,
+        });
+        // Handle one-shot auto-delete
+        if (job.deleteAfterRun && status === 'ok' && !job.enabled) {
+            this.jobs.delete(job.id);
+            this.runLog.removeJob(job.id);
+            return { status, summary, deleted: true };
+        }
+        // Re-insert into heap if still active
+        if (job.enabled && job.state.nextRunAtMs) {
+            this.heap.push({ key: job.id, nextTrigger: job.state.nextRunAtMs });
+        }
+        return { status, error, summary, durationMs };
+    }
+    // -- Helpers ---------------------------------------------------------
+    removeFromHeap(id) {
+        // MinHeap doesn't support remove-by-key efficiently,
+        // so we rebuild. Fine for typical job counts (< 1000).
+        const remaining = [];
+        while (!this.heap.isEmpty()) {
+            const item = this.heap.pop();
+            if (!item)
+                break;
+            if (item.key !== id)
+                remaining.push(item);
+        }
+        for (const item of remaining) {
+            this.heap.push(item);
+        }
+    }
+    log(message) {
+        if (!config.cron?.log)
+            return;
+        log.cron(`Cron — ${message}`);
+    }
+}

package/package.json

@@ -3,23 +3,53 @@
   "keywords": [
     "stonyx-module"
   ],
-  "version": "0.2.1-alpha.2",
+  "version": "0.2.1-alpha.20",
   "description": "Cron/job scheduler for Stonyx framework",
-  "main": "src/main.js",
+  "main": "dist/main.js",
+  "types": "dist/main.d.ts",
   "type": "module",
   "files": [
-    "*"
+    "dist",
+    "config",
+    "README.md"
   ],
   "exports": {
-    ".": "./src/main.js",
-    "./service": "./src/service.js",
-    "./cron-parser": "./src/cron-parser.js",
-    "./schedule": "./src/schedule.js",
-    "./job": "./src/job.js",
-    "./normalize": "./src/normalize.js",
-    "./locked": "./src/locked.js",
-    "./run-log": "./src/run-log.js",
-    "./min-heap": "./src/min-heap.js"
+    ".": {
+      "types": "./dist/main.d.ts",
+      "default": "./dist/main.js"
+    },
+    "./service": {
+      "types": "./dist/service.d.ts",
+      "default": "./dist/service.js"
+    },
+    "./cron-parser": {
+      "types": "./dist/cron-parser.d.ts",
+      "default": "./dist/cron-parser.js"
+    },
+    "./schedule": {
+      "types": "./dist/schedule.d.ts",
+      "default": "./dist/schedule.js"
+    },
+    "./job": {
+      "types": "./dist/job.d.ts",
+      "default": "./dist/job.js"
+    },
+    "./normalize": {
+      "types": "./dist/normalize.d.ts",
+      "default": "./dist/normalize.js"
+    },
+    "./locked": {
+      "types": "./dist/locked.d.ts",
+      "default": "./dist/locked.js"
+    },
+    "./run-log": {
+      "types": "./dist/run-log.d.ts",
+      "default": "./dist/run-log.js"
+    },
+    "./min-heap": {
+      "types": "./dist/min-heap.d.ts",
+      "default": "./dist/min-heap.js"
+    }
   },
   "publishConfig": {
     "access": "public",
@@ -39,14 +69,21 @@
   },
   "homepage": "https://github.com/abofs/stonyx-cron#readme",
   "devDependencies": {
-    "@stonyx/utils": "0.2.3-beta.7",
+    "@stonyx/utils": "0.2.3-beta.26",
+    "@types/node": "^25.5.2",
+    "@types/qunit": "^2.19.13",
+    "@types/sinon": "^21.0.1",
     "qunit": "^2.24.1",
-    "sinon": "^21.0.0"
+    "sinon": "^21.0.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.8.3"
   },
   "dependencies": {
-    "stonyx": "0.2.3-beta.11"
+    "stonyx": "0.2.3-beta.76"
   },
   "scripts": {
-    "test": "stonyx test"
+    "build": "tsc",
+    "build:test": "tsc -p tsconfig.test.json",
+    "test": "pnpm build && NODE_ENV=test node --import tsx/esm --import ./test/setup.ts node_modules/qunit/bin/qunit.js 'test/**/*-test.ts'"
   }
 }