@stonyx/cron 0.2.1-alpha.13 → 0.2.1-alpha.15

package/dist/main.d.ts

@@ -3,14 +3,18 @@ interface CronJob extends HeapItem {
     callback: () => void | Promise<void>;
     interval: string;
     key: string;
+    /**
+     * Timestamp (ms) at which the current invocation started; `undefined` when the
+     * job is idle. Mirrors `job.state.runningAtMs` in the service tier
+     * (`src/job.ts` `markRunning`/`applyResult`/`isDue`).
+     */
+    runningAtMs?: number;
 }
 export default class Cron {
     static instance: Cron | null;
     jobs: Record<string, CronJob>;
     heap: MinHeap<CronJob>;
     timer: ReturnType<typeof setTimeout> | null;
-    /** Keys whose previous invocation has not settled yet. */
-    inFlight: Set<string>;
     constructor();
     init(): Promise<void>;
     scheduleNextRun(): void;
@@ -24,8 +28,17 @@ export default class Cron {
      * job stack invocations on itself).
      */
     safeInvoke(job: CronJob, runOnInit?: boolean): void;
+    /** Release a job's in-flight guard. Only ever called for the job it belongs to. */
+    release(job: CronJob): void;
     register(key: string, callback: () => void | Promise<void>, interval: string, runOnInit?: boolean): void;
     unregister(key: string): void;
+    /**
+     * Parse a job interval (whole seconds, as a string) into a positive integer.
+     *
+     * Returns `null` when the value cannot be parsed at all, so callers can choose
+     * between failing fast (`register`) and falling back (`setNextTrigger`).
+     */
+    parseInterval(interval: string): number | null;
     setNextTrigger(job: CronJob): void;
     log(text: string, key?: string | null): void;
 }

package/dist/main.js

@@ -17,13 +17,20 @@ import config from 'stonyx/config';
 import log from 'stonyx/log';
 import { getTimestamp } from '@stonyx/utils/date';
 import MinHeap from './min-heap.js';
+/**
+ * Floor for a job interval, in whole seconds.
+ *
+ * `runDueJobs` no longer awaits the callback, so `next.nextTrigger > now` is the
+ * drain loop's only exit condition *and* the loop has no suspension point left.
+ * An interval that fails to advance `nextTrigger` therefore spins the loop
+ * forever and blocks the event loop, rather than merely scheduling too often.
+ */
+const MIN_INTERVAL_SECONDS = 1;
 export default class Cron {
     static instance;
     jobs = {};
     heap = new MinHeap();
     timer = null;
-    /** Keys whose previous invocation has not settled yet. */
-    inFlight = new Set();
     constructor() {
         if (Cron.instance)
             return Cron.instance;
@@ -78,27 +85,59 @@ export default class Cron {
     safeInvoke(job, runOnInit = false) {
         const { key } = job;
         const context = runOnInit ? 'failed on init:' : 'failed:';
-        if (this.inFlight.has(key)) {
+        // The in-flight guard lives on the job object, not in a module-level set
+        // keyed by string. That is what gives each invocation an identity: the only
+        // thing that ever clears the flag is the settle handler of the invocation
+        // that set it, and that handler closes over this exact job object. A stale
+        // handler therefore cannot release a *later* invocation's guard. It also
+        // matches the in-repo idiom one tier up (`job.state.runningAtMs`).
+        //
+        // `unregister` needs no explicit clear as a result: the flag is dropped with
+        // the job object, so a re-registered key gets a fresh object and runs
+        // immediately, while the abandoned invocation can only ever release itself.
+        if (job.runningAtMs !== undefined) {
             log.warn(`Cron job "${key}" is still running; skipping this tick`);
             return;
         }
-        this.inFlight.add(key);
+        job.runningAtMs = Date.now();
         try {
             const result = job.callback();
             if (result && typeof result.then === 'function') {
                 Promise.resolve(result)
                     .catch(err => log.error(`Cron job "${key}" ${context}`, err))
-                    .finally(() => this.inFlight.delete(key));
+                    .finally(() => this.release(job));
                 return;
             }
-            this.inFlight.delete(key);
+            this.release(job);
         }
         catch (err) {
-            this.inFlight.delete(key);
+            this.release(job);
             log.error(`Cron job "${key}" ${context}`, err);
         }
     }
+    /** Release a job's in-flight guard. Only ever called for the job it belongs to. */
+    release(job) {
+        job.runningAtMs = undefined;
+    }
     register(key, callback, interval, runOnInit = false) {
+        const seconds = this.parseInterval(interval);
+        // Fail fast rather than clamp. An unparseable interval is a programming
+        // error with exactly one likely cause — a cron expression handed to the
+        // legacy class, which takes whole seconds — and clamping it would silently
+        // run a job intended for every 5 minutes once per second, hammering whatever
+        // the callback talks to. Throwing surfaces it at the call site, at boot,
+        // before anything is scheduled. A degenerate-but-parseable interval (`'0'`,
+        // `'-5'`) is a different case: it is interpretable as "as often as possible"
+        // and is clamped to the floor with one warning.
+        if (seconds === null) {
+            throw new TypeError(`Cron job ${JSON.stringify(key)} has an invalid interval ${JSON.stringify(interval)}: `
+                + 'expected whole seconds (e.g. \'30\'). The legacy Cron class does not accept cron '
+                + 'expressions — use CronService for those.');
+        }
+        if (parseInt(interval, 10) < MIN_INTERVAL_SECONDS) {
+            log.warn(`Cron job ${JSON.stringify(key)} interval ${JSON.stringify(interval)} is below the `
+                + `${MIN_INTERVAL_SECONDS}s floor; clamping to ${MIN_INTERVAL_SECONDS}s`);
+        }
         const job = { callback, interval, key, nextTrigger: 0 };
         this.jobs[key] = job;
         this.setNextTrigger(job);
@@ -117,13 +156,28 @@ export default class Cron {
             return;
         delete jobs[key];
         heap.remove(job);
-        this.inFlight.delete(key);
         if (config.debug)
             this.log('job has been unregistered', key);
         this.scheduleNextRun();
     }
+    /**
+     * Parse a job interval (whole seconds, as a string) into a positive integer.
+     *
+     * Returns `null` when the value cannot be parsed at all, so callers can choose
+     * between failing fast (`register`) and falling back (`setNextTrigger`).
+     */
+    parseInterval(interval) {
+        const seconds = parseInt(interval, 10);
+        if (!Number.isFinite(seconds))
+            return null;
+        return Math.max(MIN_INTERVAL_SECONDS, seconds);
+    }
     setNextTrigger(job) {
-        job.nextTrigger = getTimestamp() + parseInt(job.interval, 10);
+        // `register` rejects an unparseable interval up front; this floor is the
+        // backstop for a job object mutated after registration (`cron.jobs` is
+        // public, mutable state) and is what actually guarantees the drain loop
+        // terminates. Never let `nextTrigger` land on `NaN` or on `now`.
+        job.nextTrigger = getTimestamp() + (this.parseInterval(job.interval) ?? MIN_INTERVAL_SECONDS);
     }
     log(text, key = null) {
         if (!config.cron?.log)

package/package.json

@@ -3,7 +3,7 @@
   "keywords": [
     "stonyx-module"
   ],
-  "version": "0.2.1-alpha.13",
+  "version": "0.2.1-alpha.15",
   "description": "Cron/job scheduler for Stonyx framework",
   "main": "dist/main.js",
   "types": "dist/main.d.ts",