@stonyx/cron 0.2.1-alpha.50 → 0.2.1-alpha.52

package/README.md

@@ -37,6 +37,51 @@ When a job is executed, its next trigger time is updated, and it is re-inserted
 
 > `MinHeap` is also exported as a public subpath (`@stonyx/cron/min-heap`) and can be imported directly for advanced usage.
 
+## CronService
+
+The default export above is `Cron`: a fire-and-forget interval registry. `@stonyx/cron/service` is a separate, heavier class for jobs that need CRUD, persistence, a run log and error backoff. It is not a drop-in replacement and the two do not share a scheduler.
+
+The two classes agree on the guarantee — the same job is never run concurrently with itself, and different jobs may overlap — but not on the mechanism or on what you can observe. `Cron` invokes callbacks fire-and-forget and reports a skipped run only through the `config.cron`-gated log. `CronService` **awaits** `onJobDue`, its return value shapes `status`/`error`/`summary`, and a refused run comes back to the caller as a value that no log setting can suppress — it is not logged.
+
+```js
+import CronService from '@stonyx/cron/service';
+
+const service = new CronService();
+service.onJobDue = async (job) => ({ status: 'ok', summary: 'done' });
+
+await service.start();
+const job = await service.add({ name: 'Nightly', schedule: { kind: 'every', everyMs: 86_400_000 }, payload: { kind: 'agentTurn', message: 'go' } });
+
+const result = await service.run(job.id, 'force');
+```
+
+### The `run()` contract
+
+`run(id, mode)` resolves with an `ExecuteResult`. It **never** invokes the callback twice for one job, and it will refuse rather than queue:
+
+| `status`    | `reason`            | Meaning                                                                        |
+| :---------- | :------------------ | :----------------------------------------------------------------------------- |
+| `'ok'`      | —                   | The callback resolved. `summary` and `durationMs` are set.                     |
+| `'error'`   | —                   | The callback threw or rejected. `error` carries the message; backoff is applied. |
+| `'skipped'` | `'not due'`         | `mode` was `'due'` and the job's next run time has not arrived. Use `'force'` to run anyway. |
+| `'skipped'` | `'already running'`  | A previous invocation of **this** job has not settled. The call is refused, not queued, and nothing is logged. |
+| `'skipped'` | `'removed'`         | The job was removed between the lookup and the claim. The callback did not fire. |
+
+`run()` throws (rather than returning a result) when `id` is not a registered job: `Error: Job not found: <id>`.
+
+**Concurrency.** A job is bounded to one in-flight invocation on every path — manual `run()` and the timer both claim it first. **Different** jobs are not bounded: the callback is deliberately invoked outside the internal lock, so N concurrent `run()` calls on N distinct jobs produce N concurrent callbacks. The scheduler itself never generates that fan-out (its timer path invokes a due batch sequentially); only a caller can. If you drive `run()` from a request handler, bound it on your side. Taking the callback out of the lock is what stops a callback that never settles from blocking `add`/`update`/`remove`; restoring the bound by putting it back would restore that deadlock.
+
+### Breaking changes in this line
+
+Four consumer-visible changes landed with the phase split (#34). All are measured against the emitted `dist/service.d.ts`:
+
+1. **`ExecuteResult.reason` narrowed** from `string` to `'not due' | 'already running' | 'removed'`, and gained the `'removed'` member. Comparing it against a literal outside the union, or `switch`ing on one, is now a compile error (`TS2367` / `TS2678`). Assigning it into `string | undefined` and spreading it are unaffected. The type is exported as `SkipReason`.
+2. **`CronService` is nominally typed.** It carries ECMAScript hard-private members, so the declarations emit `#private;` and a structurally hand-built test double no longer assigns to `CronService` (`TS2741: Property '#private' is missing`). The break is one-directional: `class X extends CronService` still compiles, and assigning a real `CronService` to your own hand-written interface still compiles. **Migration:** declare your own interface and depend on that instead of a `CronService`-typed mock.
+3. **`claimJob`, `settleJob` and `executeClaimed` are not published.** They were never a supported API; a claim taken without its matching settle strands the job permanently.
+4. **`run()` no longer serializes across jobs** — see the concurrency note above.
+
+`SkipReason`, `ExecuteResult`, `JobDueResult`, `ServiceStatus`, `ListOptions` and `OnJobDueCallback` are all exported from `@stonyx/cron/service`, so an exhaustive handler over `reason` is expressible.
+
 ## Configuration
 
 Optionally, logging and debugging can be enabled through `config.cron`:

package/dist/service.d.ts

@@ -84,6 +84,12 @@ export default class CronService {
      * (`'removed'`). Before the phase split, a forced run against an in-flight
      * job launched a second concurrent invocation.
      *
+     * THROWS (rather than returning a skip) when `id` is not a registered job:
+     * `Error("Job not found: <id>")`. A job that disappears between this lookup
+     * and the claim is the `'removed'` skip above, not a throw — the two differ
+     * only by the timing of a race, and the second is a legitimate outcome
+     * whereas the first is a caller error.
+     *
      * 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()`
@@ -91,7 +97,17 @@ export default class CronService {
      * these serialized behind the module-global lock; that serialization was the
      * bug rather than the feature (one hung callback wedged every other caller),
      * so it is not restored here. The fan-out is caller-driven and the scheduler
-     * never produces it on its own.
+     * never produces it on its own. A per-invoke bound belongs above this layer;
+     * it is tracked on stonyx-cron#35 alongside the execution timeout.
+     *
+     * NOT FIXED HERE: the phase split fixes the LOCK wedge, not the TIMER. A
+     * callback that never settles still stops `onTimer`'s sequential loop
+     * forever — `running` stays true, every later tick early-returns and re-arms,
+     * and the hung job's batch siblings stay claimed and off-heap having never
+     * been invoked. CRUD still resolves and `status()` still reports
+     * `started: true`, so that failure is now silent where it used to be loud.
+     * Bounding the callback and releasing batch siblings is stonyx-cron#35. Do
+     * not read this method's doc as "the hang is fixed".
      */
     run(id: string, mode?: 'due' | 'force'): Promise<ExecuteResult>;
     /**

package/dist/service.js

@@ -222,6 +222,12 @@ export default class CronService {
      * (`'removed'`). Before the phase split, a forced run against an in-flight
      * job launched a second concurrent invocation.
      *
+     * THROWS (rather than returning a skip) when `id` is not a registered job:
+     * `Error("Job not found: <id>")`. A job that disappears between this lookup
+     * and the claim is the `'removed'` skip above, not a throw — the two differ
+     * only by the timing of a race, and the second is a legitimate outcome
+     * whereas the first is a caller error.
+     *
      * 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()`
@@ -229,7 +235,17 @@ export default class CronService {
      * these serialized behind the module-global lock; that serialization was the
      * bug rather than the feature (one hung callback wedged every other caller),
      * so it is not restored here. The fan-out is caller-driven and the scheduler
-     * never produces it on its own.
+     * never produces it on its own. A per-invoke bound belongs above this layer;
+     * it is tracked on stonyx-cron#35 alongside the execution timeout.
+     *
+     * NOT FIXED HERE: the phase split fixes the LOCK wedge, not the TIMER. A
+     * callback that never settles still stops `onTimer`'s sequential loop
+     * forever — `running` stays true, every later tick early-returns and re-arms,
+     * and the hung job's batch siblings stay claimed and off-heap having never
+     * been invoked. CRUD still resolves and `status()` still reports
+     * `started: true`, so that failure is now silent where it used to be loud.
+     * Bounding the callback and releasing batch siblings is stonyx-cron#35. Do
+     * not read this method's doc as "the hang is fixed".
      */
     async run(id, mode = 'force') {
         const job = this.jobs.get(id);

package/package.json

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