@stonyx/cron 0.2.1-alpha.24 → 0.2.1-alpha.26

package/dist/service.d.ts

@@ -71,6 +71,25 @@ export default class CronService {
     remove(id: string): Promise<void>;
     /**
      * Manually trigger a job.
+     *
+     * Returns `{ status: 'skipped', reason }` without invoking the callback when
+     * the job is not due (`mode: 'due'`), is already in flight
+     * (`'already running'`), or was removed before the claim landed
+     * (`'removed'`). Before the phase split a forced run against an in-flight job
+     * launched a second concurrent invocation; refusing it is AC4 of #34.
+     *
+     * CONCURRENCY: the same job is bounded to one in-flight invocation on every
+     * path, and the timer path invokes due jobs one at a time. `run()` fan-out
+     * across DIFFERENT jobs is deliberately unbounded - N concurrent `run()`
+     * calls produce N concurrent consumer callbacks. Before the phase split
+     * these serialized behind the module-global lock; that serialization was the
+     * bug, not the feature (one hung callback wedged every other caller), so it
+     * is not being restored here. The fan-out is caller-driven: it is bounded by
+     * how many times the consumer chooses to call `run()`, exactly like any other
+     * async API, and the scheduler never produces it on its own. A consumer that
+     * exposes `run()` over HTTP or a CLI owns that bound the same way it owns
+     * request concurrency for every other handler. A per-invoke bound inside the
+     * service is tracked separately (#35).
      */
     run(id: string, mode?: 'due' | 'force'): Promise<ExecuteResult>;
     /**
@@ -101,7 +120,8 @@ export default class CronService {
      */
     executeJob(job: Job): Promise<ExecuteResult>;
     /**
-     * Phase 1 - claim. Must be called while holding the lock.
+     * 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

package/dist/service.js

@@ -154,6 +154,25 @@ export default class CronService {
     }
     /**
      * Manually trigger a job.
+     *
+     * Returns `{ status: 'skipped', reason }` without invoking the callback when
+     * the job is not due (`mode: 'due'`), is already in flight
+     * (`'already running'`), or was removed before the claim landed
+     * (`'removed'`). Before the phase split a forced run against an in-flight job
+     * launched a second concurrent invocation; refusing it is AC4 of #34.
+     *
+     * CONCURRENCY: the same job is bounded to one in-flight invocation on every
+     * path, and the timer path invokes due jobs one at a time. `run()` fan-out
+     * across DIFFERENT jobs is deliberately unbounded - N concurrent `run()`
+     * calls produce N concurrent consumer callbacks. Before the phase split
+     * these serialized behind the module-global lock; that serialization was the
+     * bug, not the feature (one hung callback wedged every other caller), so it
+     * is not being restored here. The fan-out is caller-driven: it is bounded by
+     * how many times the consumer chooses to call `run()`, exactly like any other
+     * async API, and the scheduler never produces it on its own. A consumer that
+     * exposes `run()` over HTTP or a CLI owns that bound the same way it owns
+     * request concurrency for every other handler. A per-invoke bound inside the
+     * service is tracked separately (#35).
      */
     async run(id, mode = 'force') {
         const job = this.jobs.get(id);
@@ -292,6 +311,12 @@ export default class CronService {
         // 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.
+        //
+        // Returning here without a settle is NOT the claim-without-settle hazard
+        // the try/finally below exists for: the job is already out of `this.jobs`,
+        // so the object holding `runningAtMs` is unreachable, its heap entry was
+        // removed by `remove()`, and re-inserting or run-logging it is exactly the
+        // resurrection `settleJob`'s identity guard refuses.
         if (this.jobs.get(job.id) !== job)
             return { status: 'skipped', reason: 'removed' };
         const startMs = Date.now();
@@ -330,7 +355,8 @@ export default class CronService {
         return settled;
     }
     /**
-     * Phase 1 - claim. Must be called while holding the lock.
+     * 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

package/package.json

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