@stonyx/cron 0.2.1-beta.7 → 0.2.1-beta.70

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,16 +3,53 @@
   "keywords": [
     "stonyx-module"
   ],
-  "version": "0.2.1-beta.7",
+  "version": "0.2.1-beta.70",
   "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",
-    "./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",
@@ -32,14 +69,21 @@
   },
   "homepage": "https://github.com/abofs/stonyx-cron#readme",
   "devDependencies": {
-    "@stonyx/utils": "0.2.3-beta.4",
+    "@stonyx/utils": "0.2.3-beta.25",
+    "@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.3"
+    "stonyx": "0.2.3-beta.68"
   },
   "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'"
   }
 }

package/.claude/architecture.md

@@ -1,215 +0,0 @@
-# Architecture & Core Components
-
-## Core Components Deep Dive
-
-### Cron Class (`stonyx-cron/src/main.js`)
-
-**Properties:**
-```javascript
-jobs = {};          // Object mapping job keys to job objects
-heap = new MinHeap(); // Priority queue of jobs
-timer = null;       // setTimeout handle for next scheduled run
-```
-
-**Job Object Schema:**
-```javascript
-{
-  key: string,           // Unique identifier for the job
-  callback: Function,    // Async function to execute
-  interval: number,      // Interval in seconds
-  nextTrigger: number    // Unix timestamp in seconds when job should run
-}
-```
-
-**Public Methods:**
-
-**`register(key, callback, interval, runOnInit=false)`**
-- Registers a new recurring job
-- `key` (string): Unique job identifier
-- `callback` (Function): Async function to execute on each trigger
-- `interval` (number): Time in seconds between executions
-- `runOnInit` (boolean): Whether to run callback immediately
-
-**`unregister(key)`**
-- Removes a job from the scheduler
-- Deletes from `jobs` object and removes from heap
-- Reschedules next run after removal
-
-**`scheduleNextRun()`**
-- Clears existing timer
-- Peeks at next job in heap
-- Calculates delay: `(nextTrigger - now) * 1000` (converts seconds to milliseconds)
-- Sets setTimeout for next job execution
-
-**`runDueJobs()`**
-- Processes all jobs with `nextTrigger <= now`
-- Executes job callbacks with error handling
-- Reschedules each job after execution
-- Calls `scheduleNextRun()` when done
-
-**`setNextTrigger(job)`**
-- Updates job's `nextTrigger` to `now + interval`
-- Uses `getTimestamp()` which returns **seconds**, not milliseconds
-
-**`log(text, key=null)`**
-- Conditional logging based on `config.cron?.log`
-- Formats messages as `Cron::${key} - ${text}:` or `Cron - ${text}:`
-
-### MinHeap Class (`stonyx-cron/src/min-heap.js`)
-
-**Properties:**
-```javascript
-items = [];  // Array backing the heap
-```
-
-**Public Methods:**
-
-**`push(job)`**
-- Adds job to end of array
-- Bubbles up to maintain heap property
-
-**`pop()`**
-- Removes and returns root (minimum `nextTrigger`)
-- Replaces root with last item
-- Bubbles down to restore heap property
-
-**`peek()`**
-- Returns root without removing it
-- O(1) access to next job to run
-
-**`remove(job)`**
-- Finds job by reference equality (`indexOf`)
-- Replaces with last item
-- Bubbles both up and down to restore heap property
-
-**`isEmpty()`**
-- Returns `true` if `items.length === 0`
-
-**Internal Methods:**
-
-**`bubbleUp()`**
-- Moves last item up tree until heap property is satisfied
-- Compares `nextTrigger` values with parent
-
-**`bubbleDown()`**
-- Moves root down tree, swapping with smallest child
-- Maintains min-heap property
-
----
-
-## Dependencies & Integration
-
-### Stonyx Framework Integration
-```javascript
-import config from 'stonyx/config';  // Configuration system
-import log from 'stonyx/log';        // Logging system
-import { setupIntegrationTests } from "stonyx/test-helpers";  // Test utilities
-```
-
-### External Dependencies
-```javascript
-import { getTimestamp } from "@stonyx/utils/date";  // Time utilities
-import QUnit from 'qunit';                          // Test framework
-import sinon from 'sinon';                          // Test spies/stubs/fake timers
-```
-
-### Critical Time Handling Detail
-**`getTimestamp()` returns Unix timestamps in SECONDS, not milliseconds.**
-
-This affects:
-- Job `interval` values (specified in seconds)
-- Job `nextTrigger` values (stored in seconds)
-- Delay calculation in `scheduleNextRun()`: must multiply by 1000 for `setTimeout`
-
-```javascript
-// CORRECT: Convert seconds to milliseconds for setTimeout
-const delay = Math.max(0, nextJob.nextTrigger - getTimestamp()) * 1000;
-this.timer = setTimeout(() => this.runDueJobs(), delay);
-```
-
----
-
-## Code Patterns & Conventions
-
-### Module System
-All modules use ES Module syntax with default exports:
-```javascript
-export default class Cron { ... }
-export default class MinHeap { ... }
-export default { log: true, logColor: '#888' };  // config
-```
-
-Imports use full package paths:
-```javascript
-import Cron from '@stonyx/cron';
-import MinHeap from '@stonyx/cron/min-heap';
-```
-
-### Logging Patterns
-**Always check config before logging:**
-```javascript
-if (config.debug) this.log('job has been triggered', job.key);
-if (config.cron?.log) log.cron(`${tag} - ${text}:`);
-```
-
-**Use appropriate log methods:**
-- `log.cron()` for informational cron messages
-- `log.error()` for error conditions
-
-### Error Handling
-**Never let errors crash the scheduler:**
-```javascript
-try {
-  await job.callback();
-} catch (err) {
-  log.error(`Cron job "${job.key}" failed:`, err);
-}
-// Always reschedule job, even after error
-this.setNextTrigger(job);
-heap.push(job);
-```
-
-### Time Handling
-**Always use `getTimestamp()` for current time:**
-```javascript
-// CORRECT
-const now = getTimestamp();
-job.nextTrigger = getTimestamp() + parseInt(job.interval, 10);
-
-// WRONG - don't use Date.now() or other time sources
-const now = Date.now(); // WRONG: milliseconds instead of seconds
-```
-
----
-
-## Configuration Reference
-
-### Module Configuration
-**File:** `stonyx-cron/config/environment.js`
-
-```javascript
-const { CRON_LOG } = process;
-
-export default {
-  log: CRON_LOG ?? true,    // Enable/disable cron logging
-  logColor: '#888',         // Color for cron logs
-}
-```
-
-**Environment Variable:**
-- `CRON_LOG`: Set to `false` to disable cron logging
-
-### Using Configuration in Code
-```javascript
-import config from 'stonyx/config';
-
-// Access cron config
-if (config.cron?.log) {
-  log.cron('message');
-}
-
-// Access debug flag (from main Stonyx config)
-if (config.debug) {
-  this.log('debug message');
-}
-```