@stonyx/cron 0.2.1-alpha.54 → 0.2.1-alpha.56

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (6) hide show
  1. package/README.md +47 -16
  2. package/dist/main.d.ts +0 -45
  3. package/dist/main.js +25 -170
  4. package/dist/service.d.ts +64 -6
  5. package/dist/service.js +388 -45
  6. package/package.json +2 -2
package/README.md CHANGED
@@ -35,34 +35,65 @@ When a job is executed, its next trigger time is updated, and it is re-inserted
35
35
  | `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. |
36
36
  | `unregister` | `key: string` | Remove a previously registered job. |
37
37
 
38
- > **Callback semantics.** Callbacks are invoked fire-and-forget: `Cron` never waits for one to settle, and reschedules a job *before* invoking it. Two *different* jobs that fall due on the same tick may therefore overlap.
39
- >
40
- > A job that is still running when it next falls due is skipped — and **keeps** being skipped until that invocation settles. `Cron` provides no timeout by design, so **bounding your own callback is your responsibility**: a promise that never settles means that job never runs again for the lifetime of the process, even though the scheduler stays healthy and the job stays visible in `jobs` and in the heap. Other jobs are unaffected.
41
- >
42
- > One warning is emitted per stuck run (not per tick), including how long the invocation has been running. That warning goes to `log.warn` and is **not** gated by `config.cron.log` — a dropped execution reported on a channel a config flag can silence would be indistinguishable from a healthy scheduler.
43
- >
44
- > The same-job guarantee holds for the lifetime of a **registration**, not of a key: `unregister` followed by `register` on a key whose invocation is still in flight builds a fresh job object with a fresh guard, so the replacement can run alongside the abandoned invocation. That is also the only way to recover a permanently stuck job.
45
- >
46
- > Synchronous throws and asynchronous rejections are both caught and reported through `log.error`, with the error's stack interpolated into the message. Neither can stop the scheduler. Note that a rejection which previously escaped `register()` as an unhandled rejection — process-fatal under Node's default — is now swallowed into `log.error`.
47
-
48
38
  > `MinHeap` is also exported as a public subpath (`@stonyx/cron/min-heap`) and can be imported directly for advanced usage.
49
39
 
40
+ ## CronService
41
+
42
+ 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.
43
+
44
+ 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.
45
+
46
+ ```js
47
+ import CronService from '@stonyx/cron/service';
48
+
49
+ const service = new CronService();
50
+ service.onJobDue = async (job) => ({ status: 'ok', summary: 'done' });
51
+
52
+ await service.start();
53
+ const job = await service.add({ name: 'Nightly', schedule: { kind: 'every', everyMs: 86_400_000 }, payload: { kind: 'agentTurn', message: 'go' } });
54
+
55
+ const result = await service.run(job.id, 'force');
56
+ ```
57
+
58
+ ### The `run()` contract
59
+
60
+ `run(id, mode)` resolves with an `ExecuteResult`. It **never** invokes the callback twice for one job, and it will refuse rather than queue:
61
+
62
+ | `status` | `reason` | Meaning |
63
+ | :---------- | :------------------ | :----------------------------------------------------------------------------- |
64
+ | `'ok'` | — | The callback resolved. `summary` and `durationMs` are set. |
65
+ | `'error'` | — | The callback threw or rejected. `error` carries the message; backoff is applied. |
66
+ | `'skipped'` | `'not due'` | `mode` was `'due'` and the job's next run time has not arrived. Use `'force'` to run anyway. |
67
+ | `'skipped'` | `'already running'` | A previous invocation of **this** job has not settled. The call is refused, not queued, and nothing is logged. |
68
+ | `'skipped'` | `'removed'` | The job was removed between the lookup and the claim. The callback did not fire. |
69
+
70
+ `run()` throws (rather than returning a result) when `id` is not a registered job: `Error: Job not found: <id>`.
71
+
72
+ **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.
73
+
74
+ ### Breaking changes in this line
75
+
76
+ Four consumer-visible changes landed with the phase split (#34). All are measured against the emitted `dist/service.d.ts`:
77
+
78
+ 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`.
79
+ 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.
80
+ 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.
81
+ 4. **`run()` no longer serializes across jobs** — see the concurrency note above.
82
+
83
+ `SkipReason`, `ExecuteResult`, `JobDueResult`, `ServiceStatus`, `ListOptions` and `OnJobDueCallback` are all exported from `@stonyx/cron/service`, so an exhaustive handler over `reason` is expressible.
84
+
50
85
  ## Configuration
51
86
 
52
- Optionally, informational logging and debugging can be controlled through `config.cron`:
87
+ Optionally, logging and debugging can be enabled through `config.cron`:
53
88
 
54
89
  ```js
55
90
  config.cron = {
56
- log: true // informational cron job logs; defaults to true
91
+ log: true // enable cron job logs
57
92
  };
58
93
 
59
94
  config.debug = true; // optional: debug logs for job registration and execution
60
95
  ```
61
96
 
62
- `config.cron.log` gates **informational** messages only. Error reports and the
63
- stuck-job warning described above are never gated by it, so setting it to `false`
64
- cannot make a dropped execution silent.
65
-
66
97
  ## License
67
98
 
68
99
  Apache — do what you want, just keep attribution.
package/dist/main.d.ts CHANGED
@@ -3,24 +3,6 @@ interface CronJob extends HeapItem {
3
3
  callback: () => void | Promise<void>;
4
4
  interval: string;
5
5
  key: string;
6
- /**
7
- * Timestamp (ms) at which the current invocation started; `undefined` when the
8
- * job is idle. Optional so the emitted `CronJob` stays assignable from a job
9
- * object built by a consumer — `jobs`, `heap` and `setNextTrigger` all expose
10
- * this interface structurally, so a required field is a breaking type change.
11
- *
12
- * A timestamp rather than a boolean, mirroring `job.state.runningAtMs` in the
13
- * service tier (`markRunning` / `applyResult` / `isDue` in `src/job.ts`), and
14
- * carrying the one fact a stuck-job warning needs: how long it has been stuck.
15
- * `CronService.running` is a class-level re-entrancy flag and a different
16
- * concept; reusing that word here would collide.
17
- */
18
- runningAtMs?: number;
19
- /**
20
- * True once a skip has been reported for the *current* invocation. Bounds the
21
- * still-running warning to one line per stuck run instead of one per tick.
22
- */
23
- skipReported?: boolean;
24
6
  }
25
7
  export default class Cron {
26
8
  static instance: Cron | null;
@@ -33,33 +15,6 @@ export default class Cron {
33
15
  runDueJobs(): Promise<void>;
34
16
  register(key: string, callback: () => void | Promise<void>, interval: string, runOnInit?: boolean): void;
35
17
  unregister(key: string): void;
36
- /**
37
- * The one place this class invokes a consumer callback.
38
- *
39
- * Never blocks the caller, catches synchronous throws and asynchronous
40
- * rejections identically, and skips the invocation entirely while the job's
41
- * previous invocation has not settled (fire-and-forget would otherwise let a
42
- * slow job stack invocations on itself).
43
- *
44
- * Everything that touches the callback — including the thenable probe and the
45
- * handler attachment — is inside the `try`. A callback may return an object
46
- * whose `then` is a throwing getter, and reading it outside the guard would
47
- * abort the drain loop before `scheduleNextRun()`, which is defect #36 again.
48
- */
49
- invokeJob(job: CronJob, runOnInit?: boolean): void;
50
- /**
51
- * Report a scheduler-level message without ever letting the logger's own
52
- * failure reach the caller.
53
- *
54
- * `@stonyx/logs` convenience methods return a promise and write to disk
55
- * through an unguarded `mkdirSync` + `fsp.appendFile`. On a read-only or full
56
- * log volume that promise rejects; an unobserved rejection raised from inside
57
- * the handler that exists to prevent unhandled rejections would re-create
58
- * exactly the defect this class was fixed for.
59
- */
60
- report(level: 'error' | 'warn', message: string): void;
61
- /** Release a job's in-flight guard. Only ever called for the job it belongs to. */
62
- release(job: CronJob): void;
63
18
  setNextTrigger(job: CronJob): void;
64
19
  log(text: string, key?: string | null): void;
65
20
  }
package/dist/main.js CHANGED
@@ -17,44 +17,6 @@ import config from 'stonyx/config';
17
17
  import log from 'stonyx/log';
18
18
  import { getTimestamp } from '@stonyx/utils/date';
19
19
  import MinHeap from './min-heap.js';
20
- /**
21
- * Render an unknown thrown value as log text. Total by construction.
22
- *
23
- * `@stonyx/logs` reads a second argument as `logToFile`, not as a format
24
- * argument, so `log.error(message, err)` discards the error entirely *and*
25
- * forces a disk write on every failure. The error has to be interpolated into
26
- * the message instead — the shape `CronService.executeJob` already uses.
27
- *
28
- * Every read below touches a consumer-controlled value and can therefore throw:
29
- * `instanceof` runs a proxy's `getPrototypeOf` trap, `stack`/`name`/`message`
30
- * can be accessor properties, and `String(Object.create(null))` throws outright.
31
- * This function runs *inside* `invokeJob`'s catch — the one place whose job is
32
- * to stop a callback failure from reaching the scheduler — so a throw here
33
- * escapes that catch and skips `scheduleNextRun()`, which is defect #36.
34
- */
35
- function describeError(err) {
36
- try {
37
- if (err instanceof Error)
38
- return err.stack ?? `${err.name}: ${err.message}`;
39
- return String(err);
40
- }
41
- catch {
42
- // Deliberately not re-entrant: describing the failure to describe the error
43
- // would be the same read that just threw.
44
- return '<thrown value could not be rendered>';
45
- }
46
- }
47
- /**
48
- * Render a consumer-supplied job key safely for log output.
49
- *
50
- * Keys reach the log verbatim, so a key containing a newline can forge a
51
- * complete, well-formed log line (`'a:\n[FORGED] Cron::admin - all jobs
52
- * healthy'`). `JSON.stringify` quotes the value and escapes the control
53
- * characters, which is also how the key is rendered one tier up.
54
- */
55
- function describeKey(key) {
56
- return JSON.stringify(key);
57
- }
58
20
  export default class Cron {
59
21
  static instance;
60
22
  jobs = {};
@@ -81,41 +43,28 @@ export default class Cron {
81
43
  if (!nextJob)
82
44
  return;
83
45
  const delay = Math.max(0, nextJob.nextTrigger - getTimestamp()) * 1000;
84
- // Terminal catch: `runDueJobs` is async, so anything that escapes it would
85
- // otherwise become an unhandled rejection raised from a bare timer callback
86
- // — the very failure mode this class was fixed for.
87
- this.timer = setTimeout(() => {
88
- this.runDueJobs().catch((err) => {
89
- this.report('error', `Cron scheduler tick failed: ${describeError(err)}`);
90
- });
91
- }, delay);
46
+ this.timer = setTimeout(() => this.runDueJobs(), delay);
92
47
  }
93
48
  async runDueJobs() {
94
49
  const now = getTimestamp();
95
50
  const { heap } = this;
96
- // `finally`, not a trailing statement: `scheduleNextRun()` running on every
97
- // exit from the drain loop is the invariant this whole fix is about. If
98
- // anything in the loop body ever throws, the scheduler must still re-arm
99
- // rather than stopping silently while `timer` still holds a fired handle.
100
- try {
101
- while (!heap.isEmpty()) {
102
- const next = heap.peek();
103
- if (!next || next.nextTrigger > now)
104
- break;
105
- const job = heap.pop();
106
- if (config.debug)
107
- this.log('job has been triggered', job.key);
108
- // Reschedule before invoking: a consumer callback is never awaited here,
109
- // so a callback that hangs or rejects can no longer starve the drain loop
110
- // or leave the job orphaned outside the heap.
111
- this.setNextTrigger(job);
112
- heap.push(job);
113
- this.invokeJob(job);
51
+ while (!heap.isEmpty()) {
52
+ const next = heap.peek();
53
+ if (!next || next.nextTrigger > now)
54
+ break;
55
+ const job = heap.pop();
56
+ if (config.debug)
57
+ this.log('job has been triggered', job.key);
58
+ try {
59
+ await job.callback();
114
60
  }
61
+ catch (err) {
62
+ log.error(`Cron job "${job.key}" failed:`, err);
63
+ }
64
+ this.setNextTrigger(job);
65
+ heap.push(job);
115
66
  }
116
- finally {
117
- this.scheduleNextRun();
118
- }
67
+ this.scheduleNextRun();
119
68
  }
120
69
  register(key, callback, interval, runOnInit = false) {
121
70
  const job = { callback, interval, key, nextTrigger: 0 };
@@ -125,18 +74,15 @@ export default class Cron {
125
74
  if (config.debug) {
126
75
  this.log(`job has been registered with interval: ${interval}`, key);
127
76
  }
128
- // `finally`, not a trailing statement, for the same reason as `runDueJobs`:
129
- // a job that is registered but never scheduled is defect #36's terminal
130
- // state reached through the other entry point. `invokeJob` is total, so
131
- // this guard should be unreachable — which is exactly why it is a guard and
132
- // not an assumption.
133
- try {
134
- if (runOnInit)
135
- this.invokeJob(job, true);
136
- }
137
- finally {
138
- this.scheduleNextRun();
77
+ if (runOnInit) {
78
+ try {
79
+ callback();
80
+ }
81
+ catch (err) {
82
+ log.error(`Cron job "${key}" failed on init:`, err);
83
+ }
139
84
  }
85
+ this.scheduleNextRun();
140
86
  }
141
87
  unregister(key) {
142
88
  const { heap, jobs } = this;
@@ -149,104 +95,13 @@ export default class Cron {
149
95
  this.log('job has been unregistered', key);
150
96
  this.scheduleNextRun();
151
97
  }
152
- /**
153
- * The one place this class invokes a consumer callback.
154
- *
155
- * Never blocks the caller, catches synchronous throws and asynchronous
156
- * rejections identically, and skips the invocation entirely while the job's
157
- * previous invocation has not settled (fire-and-forget would otherwise let a
158
- * slow job stack invocations on itself).
159
- *
160
- * Everything that touches the callback — including the thenable probe and the
161
- * handler attachment — is inside the `try`. A callback may return an object
162
- * whose `then` is a throwing getter, and reading it outside the guard would
163
- * abort the drain loop before `scheduleNextRun()`, which is defect #36 again.
164
- */
165
- invokeJob(job, runOnInit = false) {
166
- const { key } = job;
167
- const context = runOnInit ? 'failed on init:' : 'failed:';
168
- // The in-flight guard lives on the job object, not in a module-level set
169
- // keyed by string. Object identity is invocation identity: the only thing
170
- // that clears the guard is the settle handler of the invocation that set it,
171
- // and that handler closes over this exact job object, so a stale handler can
172
- // never release a later invocation's guard.
173
- if (job.runningAtMs !== undefined) {
174
- // Bounded to one line per stuck run, not one per tick. A permanently hung
175
- // job is re-pushed and re-skipped every interval forever; at the 1s
176
- // interval this class's own tests use that measures 43,200 lines/day per
177
- // job — a disk-fill and ingest-cost vector whose natural operator response
178
- // is to silence the only signal that the job is dead.
179
- if (!job.skipReported) {
180
- job.skipReported = true;
181
- const runningForSeconds = Math.max(0, Math.round((Date.now() - job.runningAtMs) / 1000));
182
- // Ungated, deliberately, matching the sibling `CronService` handler. A
183
- // skipped run is a *lost* execution, and `runDueJobs`/`register` both
184
- // return `void`, so this is the legacy class's only wedged-job channel.
185
- // Routing it through `this.log` would put it behind `config.cron.log`,
186
- // where a permanently dead job is indistinguishable from a healthy one.
187
- this.report('warn', `Cron job ${describeKey(key)} is still running after ${runningForSeconds}s; skipping this `
188
- + 'tick and any further ticks until it settles (this warning is not repeated for this run)');
189
- }
190
- return;
191
- }
192
- job.runningAtMs = Date.now();
193
- job.skipReported = false;
194
- try {
195
- const result = job.callback();
196
- if (result && typeof result.then === 'function') {
197
- Promise.resolve(result)
198
- .catch((err) => {
199
- // Braces matter: returning `report`'s value would put it back into
200
- // the chain, and `.finally` passes a rejection straight through.
201
- this.report('error', `Cron job ${describeKey(key)} ${context} ${describeError(err)}`);
202
- })
203
- .finally(() => { this.release(job); })
204
- // Backstop: a throw inside the error handler or the release must not
205
- // re-create the unhandled rejection this helper exists to prevent.
206
- .catch(() => { });
207
- return;
208
- }
209
- this.release(job);
210
- }
211
- catch (err) {
212
- this.release(job);
213
- this.report('error', `Cron job ${describeKey(key)} ${context} ${describeError(err)}`);
214
- }
215
- }
216
- /**
217
- * Report a scheduler-level message without ever letting the logger's own
218
- * failure reach the caller.
219
- *
220
- * `@stonyx/logs` convenience methods return a promise and write to disk
221
- * through an unguarded `mkdirSync` + `fsp.appendFile`. On a read-only or full
222
- * log volume that promise rejects; an unobserved rejection raised from inside
223
- * the handler that exists to prevent unhandled rejections would re-create
224
- * exactly the defect this class was fixed for.
225
- */
226
- report(level, message) {
227
- try {
228
- const result = level === 'error' ? log.error(message) : log.warn(message);
229
- void Promise.resolve(result).catch(() => { });
230
- }
231
- catch {
232
- // Nowhere left to report to; the logger must never stop the scheduler.
233
- }
234
- }
235
- /** Release a job's in-flight guard. Only ever called for the job it belongs to. */
236
- release(job) {
237
- job.runningAtMs = undefined;
238
- job.skipReported = false;
239
- }
240
98
  setNextTrigger(job) {
241
99
  job.nextTrigger = getTimestamp() + parseInt(job.interval, 10);
242
100
  }
243
101
  log(text, key = null) {
244
102
  if (!config.cron?.log)
245
103
  return;
246
- // The key is consumer-controlled and reaches the log verbatim. Strip the
247
- // line terminators so a key cannot forge a second, well-formed log line;
248
- // the surrounding format is unchanged.
249
- const tag = key ? `Cron::${key.replace(/[\r\n]+/g, ' ')}` : `Cron`;
104
+ const tag = key ? `Cron::${key}` : `Cron`;
250
105
  log.cron(`${tag} - ${text}:`);
251
106
  }
252
107
  }
package/dist/service.d.ts CHANGED
@@ -4,29 +4,37 @@ import RunLog from './run-log.js';
4
4
  interface HeapEntry extends HeapItem {
5
5
  key: string;
6
6
  }
7
- interface JobDueResult {
7
+ /**
8
+ * Why a `run()` did not invoke the callback. Exported so a consumer can write a
9
+ * total handler over it: the union is closed and narrowed (it was `string`
10
+ * before #34), so an exhaustive `switch` is now both possible and expected.
11
+ */
12
+ export type SkipReason = 'not due' | 'already running' | 'removed';
13
+ export interface JobDueResult {
8
14
  status?: string;
9
15
  error?: string;
10
16
  summary?: string;
11
17
  }
12
- interface ExecuteResult {
18
+ export interface ExecuteResult {
13
19
  status: string;
14
20
  error?: string;
15
21
  summary?: string;
16
22
  durationMs?: number;
17
23
  deleted?: boolean;
18
- reason?: string;
24
+ /** Only set when `status` is `'skipped'`. */
25
+ reason?: SkipReason;
19
26
  }
20
- interface ServiceStatus {
27
+ export interface ServiceStatus {
21
28
  started: boolean;
22
29
  jobCount: number;
23
30
  nextWakeAtMs: number | undefined;
24
31
  }
25
- interface ListOptions {
32
+ export interface ListOptions {
26
33
  includeDisabled?: boolean;
27
34
  }
28
- type OnJobDueCallback = (job: Job) => Promise<JobDueResult | void> | JobDueResult | void;
35
+ export type OnJobDueCallback = (job: Job) => Promise<JobDueResult | void> | JobDueResult | void;
29
36
  export default class CronService {
37
+ #private;
30
38
  jobs: Map<string, Job>;
31
39
  heap: MinHeap<HeapEntry>;
32
40
  timer: ReturnType<typeof setTimeout> | null;
@@ -69,6 +77,37 @@ export default class CronService {
69
77
  remove(id: string): Promise<void>;
70
78
  /**
71
79
  * Manually trigger a job.
80
+ *
81
+ * Returns `{ status: 'skipped', reason }` without invoking the callback when
82
+ * the job is not due (`mode: 'due'`), is already in flight
83
+ * (`'already running'`), or was removed before the claim landed
84
+ * (`'removed'`). Before the phase split, a forced run against an in-flight
85
+ * job launched a second concurrent invocation.
86
+ *
87
+ * THROWS (rather than returning a skip) when `id` is not a registered job:
88
+ * `Error("Job not found: <id>")`. A job that disappears between this lookup
89
+ * and the claim is the `'removed'` skip above, not a throw — the two differ
90
+ * only by the timing of a race, and the second is a legitimate outcome
91
+ * whereas the first is a caller error.
92
+ *
93
+ * CONCURRENCY: the same job is bounded to one in-flight invocation on every
94
+ * path, and the timer path invokes due jobs one at a time. `run()` fan-out
95
+ * across DIFFERENT jobs is deliberately unbounded — N concurrent `run()`
96
+ * calls produce N concurrent consumer callbacks. Before the phase split
97
+ * these serialized behind the module-global lock; that serialization was the
98
+ * bug rather than the feature (one hung callback wedged every other caller),
99
+ * so it is not restored here. The fan-out is caller-driven and the scheduler
100
+ * never produces it on its own. A per-invoke bound belongs above this layer;
101
+ * it is tracked on stonyx-cron#35 alongside the execution timeout.
102
+ *
103
+ * NOT FIXED HERE: the phase split fixes the LOCK wedge, not the TIMER. A
104
+ * callback that never settles still stops `onTimer`'s sequential loop
105
+ * forever — `running` stays true, every later tick early-returns and re-arms,
106
+ * and the hung job's batch siblings stay claimed and off-heap having never
107
+ * been invoked. CRUD still resolves and `status()` still reports
108
+ * `started: true`, so that failure is now silent where it used to be loud.
109
+ * Bounding the callback and releasing batch siblings is stonyx-cron#35. Do
110
+ * not read this method's doc as "the hang is fixed".
72
111
  */
73
112
  run(id: string, mode?: 'due' | 'force'): Promise<ExecuteResult>;
74
113
  /**
@@ -78,6 +117,25 @@ export default class CronService {
78
117
  armTimer(): void;
79
118
  onTimer(): Promise<void>;
80
119
  findDueJobs(nowMs: number): Job[];
120
+ /**
121
+ * Execute a job in three phases:
122
+ *
123
+ * 1. claim (locked) — take ownership of the job, detach it from the heap
124
+ * 2. invoke (UNLOCKED) — await the consumer callback
125
+ * 3. settle (locked) — apply the result, log it, re-insert into the heap
126
+ *
127
+ * The critical section deliberately excludes phase 2. `onJobDue` is
128
+ * arbitrary, unbounded consumer code; awaiting it under the module-global
129
+ * lock is what wedged every subsequent `locked()` call (add/update/remove)
130
+ * when a callback never settled.
131
+ *
132
+ * `onTimer` performs the batch claim (`findDueJobs` + `markRunning`) for all
133
+ * due jobs under a single lock and then enters at phase 2 via
134
+ * `#executeClaimed`. That entry point is `#private` rather than a parameter
135
+ * on this method: as a published `alreadyClaimed` flag it would be a
136
+ * supported way to skip phase 1 entirely, defeating the claim guard and
137
+ * allowing concurrent `onJobDue` invocations for the same job.
138
+ */
81
139
  executeJob(job: Job): Promise<ExecuteResult>;
82
140
  removeFromHeap(id: string): void;
83
141
  log(message: string): void;
package/dist/service.js CHANGED
@@ -2,7 +2,21 @@
2
2
  * CronService - the main API for advanced job scheduling.
3
3
  *
4
4
  * Manages jobs in memory with a min-heap for efficient next-job lookup.
5
- * All state mutations are serialized via async locking.
5
+ *
6
+ * Async locking, but never around the consumer callback. Execution is split
7
+ * into three phases: claim (locked), invoke (UNLOCKED), settle (locked). Only
8
+ * phases 1 and 3 are serialized; the critical section deliberately excludes
9
+ * phase 2, so a consumer callback that never settles cannot wedge the lock
10
+ * chain and block add/update/remove. See `run()` and `#executeClaimed`.
11
+ *
12
+ * CONSUMER NOTE — this class is NOMINALLY typed. It carries ECMAScript hard-
13
+ * private members, so `dist/service.d.ts` emits `#private;` on the class and a
14
+ * structurally-built test double will not assign to `CronService`
15
+ * (`TS2741: Property '#private' is missing`). The break is one-directional and
16
+ * has a zero-cost workaround: `extends CronService` still compiles, and
17
+ * assigning a real `CronService` to your own hand-written interface still
18
+ * compiles. Declare your own interface and depend on that rather than
19
+ * hand-building a `CronService`-typed mock. See README's `CronService` section.
6
20
  */
7
21
  import config from 'stonyx/config';
8
22
  import log from 'stonyx/log';
@@ -12,6 +26,54 @@ import { locked } from './locked.js';
12
26
  import { normalizeJobInput, recoverFlatParams } from './normalize.js';
13
27
  import RunLog from './run-log.js';
14
28
  const MAX_TIMER_DELAY_MS = 60_000;
29
+ /** Longest error text that may reach a log line. Anything past this is truncated. */
30
+ const MAX_LOGGED_ERROR_LENGTH = 512;
31
+ /** Longest job name that may reach a log line. Anything past this is truncated. */
32
+ const MAX_LOGGED_NAME_LENGTH = 120;
33
+ /**
34
+ * Flatten a value for interpolation into a single log line.
35
+ *
36
+ * Chronicle writes `${timestamp} ${content}\n` to a newline-delimited file, so
37
+ * any `\r` or `\n` inside `content` ends the record early and everything after
38
+ * it is read back as a separate, attacker-shaped entry — including a forged
39
+ * `[timestamp] Cron — ...` prefix that is indistinguishable from a real one.
40
+ * Both values that reach these lines are untrusted: `job.name` is passed
41
+ * through `createJob` unvalidated and `normalize.ts` exists specifically to
42
+ * accept AI-shaped input, and an error message is arbitrary consumer-callback
43
+ * text. Newlines become the literal two characters so the content survives for
44
+ * a reader, and the length cap keeps one pathological value from swamping the
45
+ * file.
46
+ */
47
+ function forLog(value, maxLength) {
48
+ const flattened = value.replace(/\r\n|[\r\n\u2028\u2029]/g, '\\n');
49
+ return flattened.length > maxLength ? `${flattened.slice(0, maxLength)}...` : flattened;
50
+ }
51
+ /**
52
+ * Describe a thrown value without ever throwing.
53
+ *
54
+ * `String(err)` is not total: a null-prototype object, or any object whose
55
+ * `toString`/`Symbol.toPrimitive` throws, raises "Cannot convert object to
56
+ * primitive value". Consumer callbacks throw arbitrary values, so the error
57
+ * handler must not become a second failure source of its own.
58
+ *
59
+ * The `instanceof Error` branch needs the same guard as the other one. `Error`
60
+ * is subclassable and `message` is a plain writable property, so a consumer can
61
+ * hand back an `Error` whose `message` is a getter that throws, or one that is
62
+ * an object whose `toString` throws — `Error.prototype.message` is typed
63
+ * `string`, so TypeScript sees nothing wrong and the coercion is deferred to
64
+ * the caller's template literal, outside every guard here. That made `run()`
65
+ * reject instead of returning an `ExecuteResult`: a contract violation in the
66
+ * function written to prevent exactly that. Reading and coercing `message`
67
+ * inside the `try` is what closes it.
68
+ */
69
+ function describeError(err) {
70
+ try {
71
+ return err instanceof Error ? String(err.message) : String(err);
72
+ }
73
+ catch {
74
+ return 'unknown error';
75
+ }
76
+ }
15
77
  export default class CronService {
16
78
  jobs;
17
79
  heap;
@@ -38,15 +100,60 @@ export default class CronService {
38
100
  if (this.started)
39
101
  return;
40
102
  this.started = true;
41
- if (initialJobs) {
42
- for (const job of initialJobs) {
43
- this.jobs.set(job.id, job);
44
- if (job.enabled && job.state.nextRunAtMs) {
45
- this.heap.push({ key: job.id, nextTrigger: job.state.nextRunAtMs });
103
+ // `finally`, not a trailing statement. Reconciled with the same guard #53
104
+ // puts around `register`'s `runOnInit` invocation: a scheduler that is
105
+ // marked started but never armed is the terminal state both fixes exist to
106
+ // remove, reached here through the other entry point. `initialJobs` crosses
107
+ // a serialization boundary — it is whatever the consumer's store handed
108
+ // back — so `Job[]` is a compile-time claim about runtime data, and a row
109
+ // missing `state` throws mid-loop. Without this, `start()` leaves
110
+ // `started: true` (so it is now a no-op), the rows registered before the
111
+ // throw sitting in the heap, and NO timer: measured, `status()` then
112
+ // reports `{ started: true, jobCount: 1, nextWakeAtMs: <real> }` while
113
+ // nothing will ever fire. Silent and healthy-looking, again.
114
+ try {
115
+ if (initialJobs) {
116
+ for (const job of initialJobs) {
117
+ // A `runningAtMs` on a rehydrated job is always stale. The claim it
118
+ // records was taken by a process that is gone, so nothing will ever
119
+ // settle it, and nothing reaps it — there is no lease on the field
120
+ // (tracked on #35). Left in place it is a permanently dead job that
121
+ // still reports healthy: `isDue` returns false forever because of the
122
+ // flag, `run()` answers `'already running'` forever, `update()` never
123
+ // touches `state.runningAtMs`, and `status()` counts it like any other.
124
+ // The consumer's only recovery would be remove() + add(), losing the
125
+ // job id and its run history.
126
+ //
127
+ // Same hazard, same treatment as the hand-release on the `'removed'`
128
+ // path in `#executeClaimed`: a claim with no reachable settle must be
129
+ // released. Assigned directly rather than via `applyResult` for the same
130
+ // reason — this releases the claim and nothing else. The job did not
131
+ // run, so it gets no run-log row, no `lastStatus`, and no recomputed
132
+ // `nextRunAtMs`; it is rescheduled from the store's own value below.
133
+ //
134
+ // Written unconditionally, and deliberately NOT guarded on a
135
+ // `job.state.runningAtMs` read. Guarding it makes `start()` accept a
136
+ // row whose `state` is frozen — `structuredClone` + `Object.freeze`
137
+ // is an ordinary defensive rehydration — and that row is not usable
138
+ // by this class at all: `markRunning` writes the same field on every
139
+ // execution. Measured, the guard moves the failure from a throw out
140
+ // of `start()`, which the consumer's own `await` can catch, to a
141
+ // TypeError raised inside `onTimer`'s batch claim — a bare timer
142
+ // callback, so it surfaces as an unhandled rejection and is
143
+ // process-fatal under Node's default. Failing loudly at the store
144
+ // boundary is the better of the two, and the `finally` above keeps
145
+ // the rows that loaded before it scheduled.
146
+ job.state.runningAtMs = undefined;
147
+ this.jobs.set(job.id, job);
148
+ if (job.enabled && job.state.nextRunAtMs) {
149
+ this.heap.push({ key: job.id, nextTrigger: job.state.nextRunAtMs });
150
+ }
46
151
  }
47
152
  }
48
153
  }
49
- this.armTimer();
154
+ finally {
155
+ this.armTimer();
156
+ }
50
157
  }
51
158
  /**
52
159
  * Stop the service. Clears timer.
@@ -136,6 +243,37 @@ export default class CronService {
136
243
  }
137
244
  /**
138
245
  * Manually trigger a job.
246
+ *
247
+ * Returns `{ status: 'skipped', reason }` without invoking the callback when
248
+ * the job is not due (`mode: 'due'`), is already in flight
249
+ * (`'already running'`), or was removed before the claim landed
250
+ * (`'removed'`). Before the phase split, a forced run against an in-flight
251
+ * job launched a second concurrent invocation.
252
+ *
253
+ * THROWS (rather than returning a skip) when `id` is not a registered job:
254
+ * `Error("Job not found: <id>")`. A job that disappears between this lookup
255
+ * and the claim is the `'removed'` skip above, not a throw — the two differ
256
+ * only by the timing of a race, and the second is a legitimate outcome
257
+ * whereas the first is a caller error.
258
+ *
259
+ * CONCURRENCY: the same job is bounded to one in-flight invocation on every
260
+ * path, and the timer path invokes due jobs one at a time. `run()` fan-out
261
+ * across DIFFERENT jobs is deliberately unbounded — N concurrent `run()`
262
+ * calls produce N concurrent consumer callbacks. Before the phase split
263
+ * these serialized behind the module-global lock; that serialization was the
264
+ * bug rather than the feature (one hung callback wedged every other caller),
265
+ * so it is not restored here. The fan-out is caller-driven and the scheduler
266
+ * never produces it on its own. A per-invoke bound belongs above this layer;
267
+ * it is tracked on stonyx-cron#35 alongside the execution timeout.
268
+ *
269
+ * NOT FIXED HERE: the phase split fixes the LOCK wedge, not the TIMER. A
270
+ * callback that never settles still stops `onTimer`'s sequential loop
271
+ * forever — `running` stays true, every later tick early-returns and re-arms,
272
+ * and the hung job's batch siblings stay claimed and off-heap having never
273
+ * been invoked. CRUD still resolves and `status()` still reports
274
+ * `started: true`, so that failure is now silent where it used to be loud.
275
+ * Bounding the callback and releasing batch siblings is stonyx-cron#35. Do
276
+ * not read this method's doc as "the hang is fixed".
139
277
  */
140
278
  async run(id, mode = 'force') {
141
279
  const job = this.jobs.get(id);
@@ -144,6 +282,10 @@ export default class CronService {
144
282
  if (mode === 'due' && !isDue(job, Date.now())) {
145
283
  return { status: 'skipped', reason: 'not due' };
146
284
  }
285
+ // Deliberately NOT wrapped in locked(): executeJob takes the lock itself,
286
+ // for its claim and settle phases only. Wrapping here would re-create the
287
+ // wedge through a second door, because the consumer callback would once
288
+ // again be awaited while a lock is held.
147
289
  return this.executeJob(job);
148
290
  }
149
291
  /**
@@ -172,16 +314,77 @@ export default class CronService {
172
314
  }
173
315
  this.running = true;
174
316
  try {
175
- await locked(async () => {
317
+ // -- Phase 1: claim (locked), batched --
318
+ // Collecting due jobs pops them off the heap, and marking them running
319
+ // makes them un-claimable by anyone else. Both must happen under the
320
+ // same lock turn, or a concurrent run() could claim a job this batch has
321
+ // already detached.
322
+ //
323
+ // This is the SECOND claim implementation — `#claimJob` is the other, and
324
+ // the two reach the same state by different routes. `#claimJob` guards
325
+ // with an explicit `job.state.runningAtMs` check; this path has no such
326
+ // check and relies entirely on `isDue`'s `!job.state.runningAtMs` clause
327
+ // (`job.ts`) to keep `findDueJobs` from re-claiming a job that `run()`
328
+ // already holds. THAT CLAUSE IS LOAD-BEARING HERE, not an optimisation:
329
+ // drop it and the timer path silently double-invokes a job that `run()`
330
+ // is mid-flight on, while `run()` keeps refusing correctly and looks
331
+ // healthy. The one-in-flight-invocation-per-job invariant this class
332
+ // advertises holds by two independent guards in two files; a change to
333
+ // either has to be checked against the other.
334
+ const dueJobs = await locked(() => {
176
335
  const nowMs = Date.now();
177
- const dueJobs = this.findDueJobs(nowMs);
178
- for (const job of dueJobs) {
336
+ const due = this.findDueJobs(nowMs);
337
+ for (const job of due) {
179
338
  markRunning(job);
180
339
  }
181
- for (const job of dueJobs) {
182
- await this.executeJob(job);
183
- }
340
+ return due;
184
341
  });
342
+ // Phases 2 and 3 run OUTSIDE the claim lock. The consumer callback is
343
+ // awaited here holding no lock at all, so a callback that never settles
344
+ // cannot poison the lock chain and wedge add/update/remove.
345
+ for (const job of dueJobs) {
346
+ try {
347
+ await this.#executeClaimed(job);
348
+ }
349
+ catch (err) {
350
+ // One job's unexpected throw must not abort the batch. Every job in
351
+ // `dueJobs` is already claimed — marked running and detached from
352
+ // the heap — and only its own settle releases it, so aborting here
353
+ // would strand every sibling permanently un-due.
354
+ //
355
+ // Reported on an UNGATED channel. `this.log()` returns early when
356
+ // `config.cron.log` is false, which is a supported production
357
+ // setting, and a failure here permanently unschedules a job while
358
+ // `status()` keeps reporting the service healthy. Silent-and-healthy
359
+ // is exactly the failure class this split exists to remove.
360
+ //
361
+ // This is the outermost handler on the timer path, so it is the one
362
+ // that must not be able to throw: `log` is a shared singleton whose
363
+ // transports can reach the filesystem, so its own failure is
364
+ // swallowed rather than allowed to take the batch down.
365
+ //
366
+ // BOTH halves of that failure have to be caught, and they are caught
367
+ // by different constructs. `log.error` is a chronicle convenience
368
+ // method that returns `logAction(...)` -> `async log(...)`, so its
369
+ // console write, colour lookup, `mkdirSync` and `appendFile` all
370
+ // surface as REJECTIONS, never as synchronous throws. A bare call
371
+ // here escapes this `catch` entirely and terminates the process under
372
+ // Node's default `--unhandled-rejections=throw` — the handler written
373
+ // so it "must not be able to throw" would be the one taking the
374
+ // daemon down. The `try` covers the synchronous half (evaluating the
375
+ // template literal); `Promise.resolve(...).catch()` covers the async
376
+ // half. Deliberately not awaited: the batch must not block on a log
377
+ // transport, and `void` marks the floated promise as intentional.
378
+ try {
379
+ void Promise.resolve(log.error(`Cron — Job "${forLog(job.name, MAX_LOGGED_NAME_LENGTH)}" (${job.id}) execution failed unexpectedly: ${forLog(describeError(err), MAX_LOGGED_ERROR_LENGTH)}`)).catch(() => {
380
+ // Nothing left to report to.
381
+ });
382
+ }
383
+ catch {
384
+ // Nothing left to report to.
385
+ }
386
+ }
387
+ }
185
388
  }
186
389
  finally {
187
390
  this.running = false;
@@ -202,50 +405,190 @@ export default class CronService {
202
405
  }
203
406
  return due;
204
407
  }
408
+ /**
409
+ * Execute a job in three phases:
410
+ *
411
+ * 1. claim (locked) — take ownership of the job, detach it from the heap
412
+ * 2. invoke (UNLOCKED) — await the consumer callback
413
+ * 3. settle (locked) — apply the result, log it, re-insert into the heap
414
+ *
415
+ * The critical section deliberately excludes phase 2. `onJobDue` is
416
+ * arbitrary, unbounded consumer code; awaiting it under the module-global
417
+ * lock is what wedged every subsequent `locked()` call (add/update/remove)
418
+ * when a callback never settled.
419
+ *
420
+ * `onTimer` performs the batch claim (`findDueJobs` + `markRunning`) for all
421
+ * due jobs under a single lock and then enters at phase 2 via
422
+ * `#executeClaimed`. That entry point is `#private` rather than a parameter
423
+ * on this method: as a published `alreadyClaimed` flag it would be a
424
+ * supported way to skip phase 1 entirely, defeating the claim guard and
425
+ * allowing concurrent `onJobDue` invocations for the same job.
426
+ */
205
427
  async executeJob(job) {
428
+ // -- Phase 1: claim (locked) --
429
+ const refusal = await locked(() => this.#claimJob(job));
430
+ if (refusal)
431
+ return { status: 'skipped', reason: refusal };
432
+ return this.#executeClaimed(job);
433
+ }
434
+ /**
435
+ * Phases 2 and 3 for a job that has already been claimed — either by
436
+ * `executeJob` above or by `onTimer`'s batch claim.
437
+ *
438
+ * Private: reaching this without a claim would run the consumer callback for
439
+ * a job nobody owns, and would leave nothing to release the claim.
440
+ */
441
+ async #executeClaimed(job) {
442
+ // Membership re-check. The claim and the invoke are no longer in the same
443
+ // critical section, and sibling callbacks run unlocked, so a `remove()` can
444
+ // now land in between AND RESOLVE — it used to deadlock. A resolved
445
+ // `remove()` must keep meaning "this callback will not fire"; the identity
446
+ // guard in `#settleJob` only cleans up afterwards, by which point the side
447
+ // effect has already happened. Identity, not id, so a removed-then-replaced
448
+ // key is caught too. Deliberately synchronous with the `onJobDue` call
449
+ // below — nothing can interleave between this check and the invocation.
450
+ //
451
+ // This is the one early return after a claim, so it is the one that has to
452
+ // release the claim by hand. Skipping settle is right — re-inserting or
453
+ // run-logging a removed job is the resurrection `#settleJob` refuses, and
454
+ // the heap entry is already gone. But the claim must still come off,
455
+ // because the detached object is NOT unreachable: it is the object `add()`
456
+ // returned and `get()`/`list()` hand out, and `start(initialJobs)`
457
+ // re-registers those objects verbatim, `state` included. A leftover
458
+ // `runningAtMs` rehydrates a permanently dead job — `isDue` false forever,
459
+ // `run()` refused forever, `status()` reporting it healthy.
460
+ //
461
+ // Assigned directly rather than via `applyResult`: this releases the claim
462
+ // and nothing else. No run-log row, no heap entry, no `lastStatus`, no
463
+ // recomputed `nextRunAtMs` — the job did not run.
464
+ if (this.jobs.get(job.id) !== job) {
465
+ job.state.runningAtMs = undefined;
466
+ return { status: 'skipped', reason: 'removed' };
467
+ }
206
468
  const startMs = Date.now();
207
469
  let status = 'ok';
208
470
  let error;
209
471
  let summary;
472
+ let settled;
473
+ // The claim marked the job running and detached it from the heap. Phase 3
474
+ // is the ONLY thing that undoes either, so it must survive every non-local
475
+ // exit from phase 2 — including a throw from the catch handler itself
476
+ // (`this.log` is public and overridable and reaches a transport). A claim
477
+ // with no matching settle is not a degraded state, it is a permanently
478
+ // dead job.
210
479
  try {
211
- if (this.onJobDue) {
212
- const result = await this.onJobDue(job);
213
- if (result) {
214
- status = result.status || 'ok';
215
- error = result.error;
216
- summary = result.summary;
480
+ // -- Phase 2: invoke (NOT locked) --
481
+ try {
482
+ if (this.onJobDue) {
483
+ const result = await this.onJobDue(job);
484
+ if (result) {
485
+ status = result.status || 'ok';
486
+ error = result.error;
487
+ summary = result.summary;
488
+ }
217
489
  }
218
490
  }
491
+ catch (err) {
492
+ status = 'error';
493
+ error = describeError(err);
494
+ this.log(`Job "${forLog(job.name, MAX_LOGGED_NAME_LENGTH)}" (${job.id}) failed: ${forLog(error, MAX_LOGGED_ERROR_LENGTH)}`);
495
+ }
219
496
  }
220
- catch (err) {
221
- status = 'error';
222
- error = err instanceof Error ? err.message : String(err);
223
- this.log(`Job "${job.name}" (${job.id}) failed: ${error}`);
497
+ finally {
498
+ // -- Phase 3: settle (locked) --
499
+ settled = await locked(() => this.#settleJob(job, status, error, summary, startMs, Date.now() - startMs));
224
500
  }
225
- const durationMs = Date.now() - startMs;
226
- const validStatus = (status === 'ok' || status === 'error' || status === 'skipped') ? status : 'error';
227
- applyResult(job, validStatus, error, durationMs);
228
- // Log the run
229
- this.runLog.record({
230
- jobId: job.id,
231
- status,
232
- error,
233
- summary,
234
- runAtMs: startMs,
235
- durationMs,
236
- nextRunAtMs: job.state.nextRunAtMs,
237
- });
238
- // Handle one-shot auto-delete
239
- if (job.deleteAfterRun && status === 'ok' && !job.enabled) {
240
- this.jobs.delete(job.id);
241
- this.runLog.removeJob(job.id);
242
- return { status, summary, deleted: true };
501
+ return settled;
502
+ }
503
+ /**
504
+ * Phase 1 — claim. Must be called while holding the lock (`locked()`, whose
505
+ * chain is module-global and therefore shared across CronService instances).
506
+ *
507
+ * Returns `null` on a successful claim, or the reason the claim was refused.
508
+ * `'already running'` is what makes a second `run()` report a skip instead of
509
+ * launching a concurrent invocation. `'removed'` covers the job being deleted
510
+ * between `run()`'s unlocked lookup and this lock turn — claiming then would
511
+ * `markRunning` an orphan and, worse, `removeFromHeap` an id that may now
512
+ * belong to a replacement.
513
+ *
514
+ * Detaching from the heap here — rather than relying on phase 3 to push a
515
+ * fresh entry — is what stops manual runs permanently duplicating entries.
516
+ *
517
+ * `#private`: published, this would be a supported call performing
518
+ * `markRunning` + `removeFromHeap` with no guaranteed settle and no lease on
519
+ * `runningAtMs`, so a single such call would strand the job forever. The
520
+ * lock-held precondition cannot be expressed in the type system, so the
521
+ * method must not be reachable from outside the class body.
522
+ */
523
+ #claimJob(job) {
524
+ if (this.jobs.get(job.id) !== job)
525
+ return 'removed';
526
+ if (job.state.runningAtMs)
527
+ return 'already running';
528
+ markRunning(job);
529
+ this.removeFromHeap(job.id);
530
+ return null;
531
+ }
532
+ /**
533
+ * Phase 3 — settle. Must be called while holding the lock.
534
+ *
535
+ * `#private` for the same reason as `#claimJob`: unlocked it would run
536
+ * `applyResult`, a `runLog.record`, a full `removeFromHeap` rebuild, a
537
+ * `heap.push` and an `armTimer` with no mutual exclusion — exactly the
538
+ * corruption `locked()` exists to prevent.
539
+ */
540
+ #settleJob(job, status, error, summary, startMs, durationMs) {
541
+ try {
542
+ const validStatus = (status === 'ok' || status === 'error' || status === 'skipped') ? status : 'error';
543
+ applyResult(job, validStatus, error, durationMs);
544
+ // The callback ran unlocked, so this job may have been removed — or
545
+ // removed and re-registered under the same id, the shape
546
+ // `start(initialJobs)` uses — while it was in flight. Identity, not id.
547
+ //
548
+ // Deliberately touch NOTHING here. The claim already detached this job's
549
+ // heap entry and nothing re-added it, so there is nothing to clean up;
550
+ // any entry now filed under this id belongs to the replacement, and
551
+ // removing it by id would silently unschedule a live job. Do not
552
+ // resurrect a removed job's heap entry or run log either.
553
+ if (this.jobs.get(job.id) !== job) {
554
+ return { status, error, summary, durationMs };
555
+ }
556
+ // Log the run
557
+ this.runLog.record({
558
+ jobId: job.id,
559
+ status,
560
+ error,
561
+ summary,
562
+ runAtMs: startMs,
563
+ durationMs,
564
+ nextRunAtMs: job.state.nextRunAtMs,
565
+ });
566
+ // Handle one-shot auto-delete. The callback ran unlocked and may have
567
+ // pushed a heap entry for this job via add()/update(), so drop it — the
568
+ // job is about to stop existing.
569
+ if (job.deleteAfterRun && status === 'ok' && !job.enabled) {
570
+ this.jobs.delete(job.id);
571
+ this.removeFromHeap(job.id);
572
+ this.runLog.removeJob(job.id);
573
+ return { status, summary, deleted: true };
574
+ }
575
+ // Re-insert into the heap if still active. Same reason as above: drop any
576
+ // entry the unlocked callback added for this job first, to preserve
577
+ // one-entry-per-key.
578
+ this.removeFromHeap(job.id);
579
+ if (job.enabled && job.state.nextRunAtMs) {
580
+ this.heap.push({ key: job.id, nextTrigger: job.state.nextRunAtMs });
581
+ }
582
+ return { status, error, summary, durationMs };
243
583
  }
244
- // Re-insert into heap if still active
245
- if (job.enabled && job.state.nextRunAtMs) {
246
- this.heap.push({ key: job.id, nextTrigger: job.state.nextRunAtMs });
584
+ finally {
585
+ // One re-arm covering every exit, rather than one per branch. The claim
586
+ // detached this job from the heap, so a timer that fired during the
587
+ // unlocked invoke would have found nothing to arm — and `run()` has no
588
+ // `finally { armTimer() }` of its own the way `onTimer` does. Without
589
+ // this, a manual run() can leave the scheduler with no pending wake.
590
+ this.armTimer();
247
591
  }
248
- return { status, error, summary, durationMs };
249
592
  }
250
593
  // -- Helpers ---------------------------------------------------------
251
594
  removeFromHeap(id) {
package/package.json CHANGED
@@ -3,7 +3,7 @@
3
3
  "keywords": [
4
4
  "stonyx-module"
5
5
  ],
6
- "version": "0.2.1-alpha.54",
6
+ "version": "0.2.1-alpha.56",
7
7
  "description": "Cron/job scheduler for Stonyx framework",
8
8
  "main": "dist/main.js",
9
9
  "types": "dist/main.d.ts",
@@ -79,7 +79,7 @@
79
79
  "typescript": "^5.8.3"
80
80
  },
81
81
  "dependencies": {
82
- "stonyx": "0.2.3-beta.83"
82
+ "stonyx": "0.2.3-beta.81"
83
83
  },
84
84
  "scripts": {
85
85
  "build": "tsc",