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

package/README.md

@@ -35,8 +35,6 @@ 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

@@ -3,12 +3,6 @@ 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;
@@ -19,26 +13,8 @@ export default class Cron {
     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;
-    /** 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,15 +17,6 @@ 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 = {};
@@ -64,80 +55,18 @@ export default class Cron {
             const job = heap.pop();
             if (config.debug)
                 this.log('job has been triggered', job.key);
-            // 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.
+            try {
+                await job.callback();
+            }
+            catch (err) {
+                log.error(`Cron job "${job.key}" failed:`, err);
+            }
             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:';
-        // 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;
-        }
-        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.release(job));
-                return;
-            }
-            this.release(job);
-        }
-        catch (err) {
-            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);
@@ -145,8 +74,14 @@ export default class Cron {
         if (config.debug) {
             this.log(`job has been registered with interval: ${interval}`, key);
         }
-        if (runOnInit)
-            this.safeInvoke(job, true);
+        if (runOnInit) {
+            try {
+                callback();
+            }
+            catch (err) {
+                log.error(`Cron job "${key}" failed on init:`, err);
+            }
+        }
         this.scheduleNextRun();
     }
     unregister(key) {
@@ -160,24 +95,8 @@ export default class Cron {
             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) {
-        // `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);
+        job.nextTrigger = getTimestamp() + parseInt(job.interval, 10);
     }
     log(text, key = null) {
         if (!config.cron?.log)

package/dist/service.d.ts

@@ -15,7 +15,8 @@ interface ExecuteResult {
     summary?: string;
     durationMs?: number;
     deleted?: boolean;
-    reason?: string;
+    /** Only set when `status` is `'skipped'`. */
+    reason?: 'not due' | 'already running' | 'removed';
 }
 interface ServiceStatus {
     started: boolean;
@@ -78,7 +79,41 @@ export default class CronService {
     armTimer(): void;
     onTimer(): Promise<void>;
     findDueJobs(nowMs: number): Job[];
-    executeJob(job: Job): Promise<ExecuteResult>;
+    /**
+     * Execute a job in three phases:
+     *
+     *   1. claim  (locked)   - take ownership of the job, detach it from the heap
+     *   2. invoke (UNLOCKED) - await the consumer callback
+     *   3. settle (locked)   - apply the result, log it, re-insert into the heap
+     *
+     * The critical section deliberately excludes phase 2. `onJobDue` is
+     * arbitrary, unbounded consumer code; awaiting it under the module-global
+     * lock is what wedged every subsequent `locked()` call (add/update/remove)
+     * when a callback never settled.
+     *
+     * `alreadyClaimed` is passed by `onTimer`, which performs the batch claim
+     * (findDueJobs + markRunning) for all due jobs under a single lock.
+     */
+    executeJob(job: Job, alreadyClaimed?: boolean): Promise<ExecuteResult>;
+    /**
+     * Phase 1 - claim. Must be called while holding the lock.
+     *
+     * Returns `null` on a successful claim, or the reason the claim was refused.
+     * "already running" is what makes a second `run()` report a skip instead of
+     * launching a concurrent invocation. "removed" covers the job being deleted
+     * between `run()`'s unlocked lookup and this lock turn - claiming then would
+     * `markRunning` an orphan and, worse, `removeFromHeap` an id that may now
+     * belong to a replacement.
+     *
+     * Detaching from the heap here (rather than relying on phase 3 to push a
+     * fresh entry) is what keeps manual runs from permanently duplicating heap
+     * entries.
+     */
+    claimJob(job: Job): 'already running' | 'removed' | null;
+    /**
+     * Phase 3 - settle. Must be called while holding the lock.
+     */
+    settleJob(job: Job, status: string, error: string | undefined, summary: string | undefined, startMs: number, durationMs: number): ExecuteResult;
     removeFromHeap(id: string): void;
     log(message: string): void;
 }

package/dist/service.js

@@ -12,6 +12,24 @@ import { locked } from './locked.js';
 import { normalizeJobInput, recoverFlatParams } from './normalize.js';
 import RunLog from './run-log.js';
 const MAX_TIMER_DELAY_MS = 60_000;
+/**
+ * Describe a thrown value without ever throwing.
+ *
+ * `String(err)` is not total: a null-prototype object, or any object whose
+ * `toString`/`Symbol.toPrimitive` throws, raises "Cannot convert object to
+ * primitive value". Consumer callbacks throw arbitrary values, so the error
+ * handler itself must not be a second failure source.
+ */
+function describeError(err) {
+    if (err instanceof Error)
+        return err.message;
+    try {
+        return String(err);
+    }
+    catch {
+        return 'unknown error';
+    }
+}
 export default class CronService {
     jobs;
     heap;
@@ -144,6 +162,10 @@ export default class CronService {
         if (mode === 'due' && !isDue(job, Date.now())) {
             return { status: 'skipped', reason: 'not due' };
         }
+        // Deliberately NOT wrapped in locked(): executeJob takes the lock itself
+        // for its claim and settle phases only. Wrapping here would re-create the
+        // wedge through a second door, since the callback would again be awaited
+        // while a lock is held.
         return this.executeJob(job);
     }
     /**
@@ -172,16 +194,42 @@ export default class CronService {
         }
         this.running = true;
         try {
-            await locked(async () => {
+            // Phase 1 - claim (locked). Collecting due jobs pops them off the heap
+            // and marking them running makes them un-collectable by anyone else, so
+            // both must happen under the same lock.
+            const dueJobs = await locked(() => {
                 const nowMs = Date.now();
-                const dueJobs = this.findDueJobs(nowMs);
-                for (const job of dueJobs) {
+                const due = this.findDueJobs(nowMs);
+                for (const job of due) {
                     markRunning(job);
                 }
-                for (const job of dueJobs) {
-                    await this.executeJob(job);
-                }
+                return due;
             });
+            // Phases 2 and 3 run outside the claim lock. The consumer callback is
+            // awaited here holding no lock at all, so a callback that never settles
+            // cannot poison the lock chain.
+            for (const job of dueJobs) {
+                try {
+                    await this.executeJob(job, true);
+                }
+                catch (err) {
+                    // One job's unexpected throw must not abort the batch. Every job in
+                    // `dueJobs` is already claimed - marked running and detached from the
+                    // heap - and only its own settle releases it, so aborting here would
+                    // strand every sibling permanently un-due.
+                    //
+                    // This is the outermost handler on the timer path, so it is the one
+                    // that must not be able to throw. `log()` is public, overridable and
+                    // can reach a file transport, so its own failure is swallowed here
+                    // rather than being allowed to take the batch down.
+                    try {
+                        this.log(`Job "${job.name}" (${job.id}) execution failed unexpectedly: ${describeError(err)}`);
+                    }
+                    catch {
+                        // Nothing left to report to.
+                    }
+                }
+            }
         }
         finally {
             this.running = false;
@@ -202,29 +250,109 @@ export default class CronService {
         }
         return due;
     }
-    async executeJob(job) {
+    /**
+     * Execute a job in three phases:
+     *
+     *   1. claim  (locked)   - take ownership of the job, detach it from the heap
+     *   2. invoke (UNLOCKED) - await the consumer callback
+     *   3. settle (locked)   - apply the result, log it, re-insert into the heap
+     *
+     * The critical section deliberately excludes phase 2. `onJobDue` is
+     * arbitrary, unbounded consumer code; awaiting it under the module-global
+     * lock is what wedged every subsequent `locked()` call (add/update/remove)
+     * when a callback never settled.
+     *
+     * `alreadyClaimed` is passed by `onTimer`, which performs the batch claim
+     * (findDueJobs + markRunning) for all due jobs under a single lock.
+     */
+    async executeJob(job, alreadyClaimed = false) {
+        // -- Phase 1: claim (locked) --
+        if (!alreadyClaimed) {
+            const refusal = await locked(() => this.claimJob(job));
+            if (refusal)
+                return { status: 'skipped', reason: refusal };
+        }
+        // Membership re-check. The claim and the invoke are no longer in the same
+        // critical section, and sibling callbacks run unlocked, so a `remove()` can
+        // land in between AND RESOLVE - it used to deadlock. A resolved `remove()`
+        // must keep meaning "this callback will not fire": settleJob's identity
+        // guard only cleans up afterwards, by which point the side effect has
+        // already happened. Identity, not id, so a removed-then-replaced key is
+        // caught too. Deliberately synchronous with the `onJobDue` call below -
+        // nothing can interleave between this check and the invocation.
+        if (this.jobs.get(job.id) !== job)
+            return { status: 'skipped', reason: 'removed' };
         const startMs = Date.now();
         let status = 'ok';
         let error;
         let summary;
+        let settled;
+        // The claim above marked the job running and detached it from the heap.
+        // Phase 3 is the ONLY thing that undoes either, so it must survive every
+        // non-local exit from phase 2 - including a throw from the catch handler
+        // itself. A claim with no matching settle is not a degraded state, it is a
+        // permanently dead job: `runningAtMs` set, no heap entry, `isDue` false
+        // forever and `run()` refused forever.
         try {
-            if (this.onJobDue) {
-                const result = await this.onJobDue(job);
-                if (result) {
-                    status = result.status || 'ok';
-                    error = result.error;
-                    summary = result.summary;
+            // -- Phase 2: invoke (NOT locked) --
+            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 = describeError(err);
+                this.log(`Job "${job.name}" (${job.id}) failed: ${error}`);
+            }
         }
-        catch (err) {
-            status = 'error';
-            error = err instanceof Error ? err.message : String(err);
-            this.log(`Job "${job.name}" (${job.id}) failed: ${error}`);
+        finally {
+            // -- Phase 3: settle (locked) --
+            settled = await locked(() => this.settleJob(job, status, error, summary, startMs, Date.now() - startMs));
         }
-        const durationMs = Date.now() - startMs;
+        return settled;
+    }
+    /**
+     * Phase 1 - claim. Must be called while holding the lock.
+     *
+     * Returns `null` on a successful claim, or the reason the claim was refused.
+     * "already running" is what makes a second `run()` report a skip instead of
+     * launching a concurrent invocation. "removed" covers the job being deleted
+     * between `run()`'s unlocked lookup and this lock turn - claiming then would
+     * `markRunning` an orphan and, worse, `removeFromHeap` an id that may now
+     * belong to a replacement.
+     *
+     * Detaching from the heap here (rather than relying on phase 3 to push a
+     * fresh entry) is what keeps manual runs from permanently duplicating heap
+     * entries.
+     */
+    claimJob(job) {
+        if (this.jobs.get(job.id) !== job)
+            return 'removed';
+        if (job.state.runningAtMs)
+            return 'already running';
+        markRunning(job);
+        this.removeFromHeap(job.id);
+        return null;
+    }
+    /**
+     * Phase 3 - settle. Must be called while holding the lock.
+     */
+    settleJob(job, status, error, summary, startMs, durationMs) {
         const validStatus = (status === 'ok' || status === 'error' || status === 'skipped') ? status : 'error';
         applyResult(job, validStatus, error, durationMs);
+        // The callback ran unlocked, so it may have removed this job while it was
+        // in flight. Do not resurrect a removed job's heap entry or run log.
+        if (this.jobs.get(job.id) !== job) {
+            this.removeFromHeap(job.id);
+            this.armTimer();
+            return { status, error, summary, durationMs };
+        }
         // Log the run
         this.runLog.record({
             jobId: job.id,
@@ -238,13 +366,22 @@ export default class CronService {
         // Handle one-shot auto-delete
         if (job.deleteAfterRun && status === 'ok' && !job.enabled) {
             this.jobs.delete(job.id);
+            this.removeFromHeap(job.id);
             this.runLog.removeJob(job.id);
+            this.armTimer();
             return { status, summary, deleted: true };
         }
-        // Re-insert into heap if still active
+        // Re-insert into heap if still active. The callback ran unlocked, so it
+        // may itself have added a heap entry for this job (via add/update); drop
+        // any such entry first to preserve one-entry-per-key.
+        this.removeFromHeap(job.id);
         if (job.enabled && job.state.nextRunAtMs) {
             this.heap.push({ key: job.id, nextTrigger: job.state.nextRunAtMs });
         }
+        // The claim phase detached this job from the heap, so a timer that fired
+        // during the unlocked invoke would have seen it missing. Re-arm here so a
+        // manual run() can never leave the scheduler without a pending wake.
+        this.armTimer();
         return { status, error, summary, durationMs };
     }
     // -- Helpers ---------------------------------------------------------
@@ -266,6 +403,19 @@ export default class CronService {
     log(message) {
         if (!config.cron?.log)
             return;
-        log.cron(`Cron — ${message}`);
+        // `log.cron` is created by `log.defineType`, which runs in `Cron.init()`
+        // (src/main.ts) - a DIFFERENT class. A consumer wiring CronService directly
+        // never runs it, while `config/environment.js` defaults `cron.log` to true,
+        // so an unguarded call throws `log.cron is not a function`. That throw
+        // escapes executeJob's catch, and the error-reporting path must never be
+        // the thing that kills the scheduler. `src/types/stonyx.d.ts:19` declares
+        // `cron()` unconditionally, so the type system will not catch this.
+        const { logColor = '#888', logMethod = 'cron' } = config.cron ?? {};
+        if (typeof log[logMethod] !== 'function')
+            log.defineType(logMethod, logColor);
+        const method = log[logMethod];
+        if (typeof method !== 'function')
+            return;
+        method.call(log, `Cron — ${message}`);
     }
 }

package/package.json

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