@stonyx/cron 0.2.1-alpha.29 → 0.2.1-alpha.30

package/dist/service.d.ts

@@ -119,26 +119,6 @@ export default class CronService {
      * for and allows concurrent `onJobDue` invocations for the same job.
      */
     executeJob(job: Job): Promise<ExecuteResult>;
-    /**
-     * Phase 1 - claim. Must be called while holding the lock (`locked()`, whose
-     * chain is module-global and therefore shared across CronService instances).
-     *
-     * 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

@@ -290,7 +290,7 @@ export default class CronService {
      */
     async executeJob(job) {
         // -- Phase 1: claim (locked) --
-        const refusal = await locked(() => this.claimJob(job));
+        const refusal = await locked(() => this.#claimJob(job));
         if (refusal)
             return { status: 'skipped', reason: refusal };
         return this.#executeClaimed(job);
@@ -306,7 +306,7 @@ export default class CronService {
         // 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
+        // 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 -
@@ -315,7 +315,7 @@ export default class CronService {
         // This is the ONE early return in the phase-2/3 control flow that happens
         // after a claim, so it is the one that has to release the claim by hand.
         // (`executeJob`'s refusal return at the call site is pre-claim; `onTimer`'s
-        // re-entrancy return never claims; every return inside `settleJob` is
+        // re-entrancy return never claims; every return inside `#settleJob` is
         // already past phase 3.)
         //
         // Skipping settle entirely here is right - re-inserting or run-logging a
@@ -368,7 +368,7 @@ export default class CronService {
         }
         finally {
             // -- Phase 3: settle (locked) --
-            settled = await locked(() => this.settleJob(job, status, error, summary, startMs, Date.now() - startMs));
+            settled = await locked(() => this.#settleJob(job, status, error, summary, startMs, Date.now() - startMs));
         }
         return settled;
     }
@@ -376,6 +376,15 @@ export default class CronService {
      * Phase 1 - claim. Must be called while holding the lock (`locked()`, whose
      * chain is module-global and therefore shared across CronService instances).
      *
+     * `#private`, like `#executeClaimed` and for the same reason. Published, this
+     * was a supported call performing `markRunning` + `removeFromHeap` with no
+     * guaranteed settle - the claim-without-settle shape the try/finally in
+     * `#executeClaimed` exists to prevent, and with no lease on `runningAtMs` a
+     * single such call permanently strands the job: off the heap, marked running,
+     * with nothing that will ever release it. The precondition below cannot be
+     * expressed in the type system, so the method must not be reachable from
+     * outside the class body.
+     *
      * 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
@@ -387,7 +396,7 @@ export default class CronService {
      * fresh entry) is what keeps manual runs from permanently duplicating heap
      * entries.
      */
-    claimJob(job) {
+    #claimJob(job) {
         if (this.jobs.get(job.id) !== job)
             return 'removed';
         if (job.state.runningAtMs)
@@ -398,8 +407,13 @@ export default class CronService {
     }
     /**
      * Phase 3 - settle. Must be called while holding the lock.
+     *
+     * `#private` for the same reason as `#claimJob`: unlocked it would run
+     * `applyResult`, a `runLog.record`, a full `removeFromHeap` rebuild, a
+     * `heap.push` and an `armTimer` with no mutual exclusion - exactly the
+     * corruption `locked()` exists to prevent.
      */
-    settleJob(job, status, error, summary, startMs, durationMs) {
+    #settleJob(job, status, error, summary, startMs, durationMs) {
         try {
             const validStatus = (status === 'ok' || status === 'error' || status === 'skipped') ? status : 'error';
             applyResult(job, validStatus, error, durationMs);

package/package.json

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