@stonyx/cron 0.2.1-alpha.10 → 0.2.1-alpha.11

package/README.md

@@ -35,6 +35,8 @@ When a job is executed, its next trigger time is updated, and it is re-inserted
 |  `register`  | `key: string, callback: Function, interval: number, runOnInit?: boolean` | Register a new job with a given interval in seconds. If `runOnInit` is true, the job runs immediately upon registration. |
 | `unregister` |                               `key: string`                              | Remove a previously registered job.                                                                                      |
 
+> Callbacks are invoked fire-and-forget: `Cron` never waits for one to settle. Two *different* jobs that fall due on the same tick may therefore overlap, and a job that is still running when it next falls due is skipped for that tick (a warning is logged). Both synchronous throws and asynchronous rejections are caught and logged; neither can stop the scheduler.
+
 > `MinHeap` is also exported as a public subpath (`@stonyx/cron/min-heap`) and can be imported directly for advanced usage.
 
 ## Configuration

package/dist/main.d.ts

@@ -9,10 +9,21 @@ export default class Cron {
     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;
     runDueJobs(): Promise<void>;
+    /**
+     * The one safe way this class invokes a consumer callback.
+     *
+     * Never blocks the caller, catches synchronous throws and asynchronous
+     * rejections alike, and skips the invocation entirely when the job's previous
+     * invocation has not settled yet (fire-and-forget would otherwise let a slow
+     * job stack invocations on itself).
+     */
+    safeInvoke(job: CronJob, runOnInit?: boolean): void;
     register(key: string, callback: () => void | Promise<void>, interval: string, runOnInit?: boolean): void;
     unregister(key: string): void;
     setNextTrigger(job: CronJob): void;

package/dist/main.js

@@ -22,6 +22,8 @@ export default class Cron {
     jobs = {};
     heap = new MinHeap();
     timer = null;
+    /** Keys whose previous invocation has not settled yet. */
+    inFlight = new Set();
     constructor() {
         if (Cron.instance)
             return Cron.instance;
@@ -55,17 +57,47 @@ export default class Cron {
             const job = heap.pop();
             if (config.debug)
                 this.log('job has been triggered', job.key);
-            try {
-                await job.callback();
-            }
-            catch (err) {
-                log.error(`Cron job "${job.key}" failed:`, err);
-            }
+            // Reschedule *before* invoking. The callback's result is not used by this
+            // class (`runDueJobs` returns void), so awaiting it bought nothing and
+            // cost the scheduler: a callback that never settled left the job absent
+            // from the heap and stopped the timer from ever re-arming.
             this.setNextTrigger(job);
             heap.push(job);
+            this.safeInvoke(job);
         }
         this.scheduleNextRun();
     }
+    /**
+     * The one safe way this class invokes a consumer callback.
+     *
+     * Never blocks the caller, catches synchronous throws and asynchronous
+     * rejections alike, and skips the invocation entirely when the job's previous
+     * invocation has not settled yet (fire-and-forget would otherwise let a slow
+     * job stack invocations on itself).
+     */
+    safeInvoke(job, runOnInit = false) {
+        const { key } = job;
+        const context = runOnInit ? 'failed on init:' : 'failed:';
+        if (this.inFlight.has(key)) {
+            log.warn(`Cron job "${key}" is still running; skipping this tick`);
+            return;
+        }
+        this.inFlight.add(key);
+        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));
+                return;
+            }
+            this.inFlight.delete(key);
+        }
+        catch (err) {
+            this.inFlight.delete(key);
+            log.error(`Cron job "${key}" ${context}`, err);
+        }
+    }
     register(key, callback, interval, runOnInit = false) {
         const job = { callback, interval, key, nextTrigger: 0 };
         this.jobs[key] = job;
@@ -74,14 +106,8 @@ export default class Cron {
         if (config.debug) {
             this.log(`job has been registered with interval: ${interval}`, key);
         }
-        if (runOnInit) {
-            try {
-                callback();
-            }
-            catch (err) {
-                log.error(`Cron job "${key}" failed on init:`, err);
-            }
-        }
+        if (runOnInit)
+            this.safeInvoke(job, true);
         this.scheduleNextRun();
     }
     unregister(key) {
@@ -91,6 +117,7 @@ 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();

package/package.json

@@ -3,7 +3,7 @@
   "keywords": [
     "stonyx-module"
   ],
-  "version": "0.2.1-alpha.10",
+  "version": "0.2.1-alpha.11",
   "description": "Cron/job scheduler for Stonyx framework",
   "main": "dist/main.js",
   "types": "dist/main.d.ts",
@@ -69,7 +69,7 @@
   },
   "homepage": "https://github.com/abofs/stonyx-cron#readme",
   "devDependencies": {
-    "@stonyx/utils": "0.2.3-beta.23",
+    "@stonyx/utils": "0.2.3-beta.26",
     "@types/node": "^25.5.2",
     "@types/qunit": "^2.19.13",
     "@types/sinon": "^21.0.1",
@@ -79,7 +79,7 @@
     "typescript": "^5.8.3"
   },
   "dependencies": {
-    "stonyx": "0.2.3-beta.63"
+    "stonyx": "0.2.3-beta.76"
   },
   "scripts": {
     "build": "tsc",