@stonyx/cron 0.2.1-alpha.61 → 0.2.1-alpha.62

package/README.md

@@ -51,7 +51,7 @@ When a job is executed, its next trigger time is updated, and it is re-inserted
 
 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 as an ungated `log.warn` line, one per stuck run, never as a value. `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. The two therefore agree on one more thing than the contrast suggests: neither can be made silent by `config.cron.log`.
+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 as an ungated `log.warn` line, one per stuck run, never as a value. `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. The two therefore agree on one more thing than the contrast suggests: neither can have a *refused* run made silent by `config.cron.log` — `Cron`'s skip warning is ungated, and `CronService`'s refusal is a return value rather than a log line. A job *failure* is the opposite case, and there the two classes genuinely diverge; see [Configuration](#configuration).
 
 ```js
 import CronService from '@stonyx/cron/service';
@@ -81,14 +81,31 @@ const result = await service.run(job.id, 'force');
 
 **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.
 
+**The residual, stated plainly.** Taking the callback out of the lock fixes
+`add`/`update`/`remove`; it does **not** bound the callback. A callback that
+never settles still holds its job's claim forever, and because the timer's
+re-entrancy latch is only released when the batch settles, it also **stops the
+timer loop for every other job** — silently, with `status()` still reporting
+`started: true`. There is no execution timeout by design, so bounding your own
+callback is your responsibility, exactly as it is for `Cron`. Only a real
+process restart recovers it: `start()` releases a claim whose owner is provably
+gone, but an object still held in this process is deliberately left alone.
+Tracked as #35.
+
 ### 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`:
+Five consumer-visible changes landed with the phase split (#34). Only the first
+two are visible in the emitted `dist/service.d.ts`; the rest are runtime
+behaviour and a type-checker will not find them for you. The measured
+`dist/service.d.ts` delta against the previous release is exactly three things:
+the class gained `#private;`, `reason` narrowed, and six type declarations
+gained `export`. `dist/main.d.ts` is unchanged.
 
 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.
+3. **`claimJob`, `settleJob` and `executeClaimed` are not published.** Not a change against the previous release — these members did not exist there at all. Listed because they are new internals that look like API and are deliberately unreachable: a claim taken without its matching settle strands the job permanently in-process. Guarded by `test/unit/publish-surface-test.ts`.
+4. **`run()` no longer serializes across jobs** — a runtime change, not a d.ts one. See the concurrency note above.
+5. **`start()` now throws on a row it cannot use.** A `Job` whose `state` is missing or frozen — `structuredClone` + `Object.freeze` is an ordinary defensive rehydration — makes `start()` reject where the previous release resolved and carried on. Measured: previous release resolves and leaves the stale claim in place; this line throws `TypeError: Cannot assign to read only property 'runningAtMs'`. The timer is still armed for the rows loaded before the throw, so this surfaces at your `await` instead of as an unhandled rejection from inside a timer callback later. **Migration:** if your store hands back frozen rows, thaw `state` before passing them, or catch at the `start()` call site.
 
 `SkipReason`, `ExecuteResult`, `JobDueResult`, `ServiceStatus`, `ListOptions` and `OnJobDueCallback` are all exported from `@stonyx/cron/service`, so an exhaustive handler over `reason` is expressible.
 
@@ -104,9 +121,28 @@ config.cron = {
 config.debug = true; // optional: debug logs for job registration and execution
 ```
 
-`config.cron.log` gates **informational** messages only. Error reports and the
-stuck-job warning described above are never gated by it, so setting it to `false`
-cannot make a dropped execution silent.
+`config.cron.log` gates the `log.cron` channel only. **The two classes route job
+failures differently, so what `log: false` costs you depends on which one you are
+running.** Measured on this build, with a callback that throws:
+
+| | Failure channel | Records with `log: false` |
+| :--- | :--- | :--- |
+| `Cron` (default export) | ungated `log.error` | emitted — unchanged |
+| `CronService` | **gated** `log.cron` | **none** |
+
+- **`Cron`** reports a callback's throw or rejection through `log.error`, and the
+  stuck-job warning described above through `log.warn`. Neither is gated, so
+  setting `log` to `false` cannot make a dropped or failed execution silent.
+- **`CronService`** reports a job whose `onJobDue` callback throws through the
+  **gated** channel, so `log: false` yields **zero** log records for that
+  failure. It stays observable as `ExecuteResult.error` and as a run-log row —
+  but a job driven off the timer rather than `run()` has no caller to read that
+  return value, so the failure is visible only in the run log. Only the timer
+  path's *unexpected* internal throw (a fault in the scheduler itself, not in
+  your callback) is reported on the ungated `log.error` channel.
+
+If you set `log: false` in production and rely on `CronService`, read failures
+from the run log or from `ExecuteResult`, not from the log file.
 
 ## License
 

package/dist/main.js

@@ -29,12 +29,28 @@ const MAX_LOGGED_ERROR_LENGTH = 512;
  * become the literal two characters so the content survives for a reader, and
  * the length cap keeps one pathological value from swamping the file.
  *
- * Kept byte-identical to the `forLog` landing in `src/service.ts` on #34: the
- * two tiers render the same untrusted values into the same log file, and a
- * reader diagnosing a forged record should not have to know which tier wrote
- * it. Duplicated rather than shared because the two land on separate branches;
- * folding them into one helper is a follow-up once both are on `dev`, not a
- * cross-PR dependency that would make either unmergeable alone.
+ * DIVERGED from the `forLog` in `src/service.ts`, deliberately — this copy is
+ * NOT byte-identical to it and must not be folded into it by assuming it is.
+ * (An earlier version of this docblock claimed byte-identity; #34's `fac09cb`
+ * falsified that, and the two bodies now measure unequal.) `service.ts`'s is
+ * TOTAL: it wraps the coercion in `String(value)` and a `try`, returning
+ * `'<unrenderable value>'` rather than throwing. This one is not.
+ *
+ * The divergence is correct on the merits, and the reason is the call site, not
+ * the helper. Both of this copy's callers are the two `forLog(...)` calls in
+ * `describeError` directly below (`:82`, `:85`), and both are INSIDE that
+ * function's own `try`, so a `TypeError` from `value.replace` on a
+ * non-string degrades to `'<thrown value could not be rendered>'` and the log
+ * record is still produced. `service.ts`'s callers are not so contained: `:692`
+ * sits in a bare `catch` with nothing above it, and `:571`'s enclosing `catch`
+ * has nothing left to report to — so a throw there destroyed the failure
+ * record outright (measured: 0 records for a job that failed). That is why
+ * totality was a live defect there and is not one here.
+ *
+ * Duplicated rather than shared because the two landed on separate branches.
+ * The fold is still wanted, but whoever performs it MUST adopt `service.ts`'s
+ * total version as the survivor: folding to this one would silently revert
+ * `fac09cb`. See #66, which carries the consolidation.
  */
 function forLog(value, maxLength) {
     const flattened = value.replace(/\r\n|[\r\n\u2028\u2029]/g, '\\n');

package/dist/service.d.ts

@@ -73,9 +73,17 @@ export default class CronService {
      *    (so a retry is a no-op) with jobs in the heap and no timer: nothing ever
      *    fires and `status()` still reports healthy.
      *
-     * Hand it deserialized rows and all three are invisible. Hand it live `Job`
-     * objects this service is currently executing and only 1 is observable, by
-     * design.
+     * Which of the three you can observe depends on the CONTENT of the rows, not
+     * on whether they were deserialized — 1 fires only on a row that already
+     * carries a claim, and 2/3 only on a row this class cannot use. Hand it
+     * well-formed deserialized rows with no claim set and none of the three is
+     * observable. Hand it a deserialized row that DOES carry one and 1 and 2 are
+     * exactly what you get: measured, a stale `state.runningAtMs` of 1 comes back
+     * `undefined`, and a `structuredClone` + `Object.freeze` row makes `start()`
+     * throw `TypeError: Cannot assign to read only property 'runningAtMs'` with
+     * the timer still armed behind it. Hand it live `Job` objects this service is
+     * currently executing and only 1 is in play, by design — and on those it
+     * deliberately does nothing.
      */
     start(initialJobs?: Job[]): Promise<void>;
     /**

package/dist/service.js

@@ -49,13 +49,13 @@ const MAX_LOGGED_NAME_LENGTH = 120;
  * that is a compile-time claim about runtime data: `normalize.ts` only
  * GENERATES a name when the field is falsy, so `add({ name: 12345 })` stores a
  * number through the public API, and `start(initialJobs)` takes names verbatim
- * from the consumer's store \u2014 the same untrusted boundary `start()` already
+ * from the consumer's store — the same untrusted boundary `start()` already
  * hardens `state` against.
  *
  * Fixed HERE rather than by coercing in `normalize`, deliberately. Coercing at
  * `normalize` closes the `add()` path only; the rehydration path bypasses both
  * `normalize` and `createJob` entirely, and that is the path this class already
- * treats as hostile. And this helper is on the ERROR path \u2014 a helper that
+ * treats as hostile. And this helper is on the ERROR path — a helper that
  * throws while building an error report destroys the report it exists to
  * produce. Measured pre-fix: `run()` rejected with `TypeError: value.replace is
  * not a function` instead of returning an `ExecuteResult`, and on the timer
@@ -190,9 +190,17 @@ export default class CronService {
      *    (so a retry is a no-op) with jobs in the heap and no timer: nothing ever
      *    fires and `status()` still reports healthy.
      *
-     * Hand it deserialized rows and all three are invisible. Hand it live `Job`
-     * objects this service is currently executing and only 1 is observable, by
-     * design.
+     * Which of the three you can observe depends on the CONTENT of the rows, not
+     * on whether they were deserialized — 1 fires only on a row that already
+     * carries a claim, and 2/3 only on a row this class cannot use. Hand it
+     * well-formed deserialized rows with no claim set and none of the three is
+     * observable. Hand it a deserialized row that DOES carry one and 1 and 2 are
+     * exactly what you get: measured, a stale `state.runningAtMs` of 1 comes back
+     * `undefined`, and a `structuredClone` + `Object.freeze` row makes `start()`
+     * throw `TypeError: Cannot assign to read only property 'runningAtMs'` with
+     * the timer still armed behind it. Hand it live `Job` objects this service is
+     * currently executing and only 1 is in play, by design — and on those it
+     * deliberately does nothing.
      */
     async start(initialJobs) {
         if (this.started)

package/package.json

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