@dudousxd/nestjs-durable-core 0.85.0 → 0.85.2

package/dist/index.d.cts

@@ -7038,6 +7038,8 @@ interface ScheduledWorkflow<W extends WorkflowRef = WorkflowRef> {
     /**
      * Randomly delay the dispatch by up to this many ms BEFORE firing, to spread load when many
      * instances tick on the same boundary (avoids a thundering herd). Opt-in; absent = fire immediately.
+     * The window is deferred to a later tick, never waited for inside one, so a jittered schedule does
+     * not hold up any other schedule or the rest of the timer poll.
      *
      * This is dispatch-path jitter only — it does NOT affect the run id (still the time bucket), so
      * idempotency is unchanged: two instances jittering the same window still start it exactly once.
@@ -7066,9 +7068,13 @@ interface ScheduledWorkflow<W extends WorkflowRef = WorkflowRef> {
     namespace?: string;
 }
 /** Injectable dispatch-path effects (kept out of the deterministic run-id logic). Defaults to real
- *  `Math.random` + `setTimeout`; overridden in tests so jitter is deterministic and instant. */
+ *  `Math.random`; overridden in tests so jitter is deterministic. */
 interface RunSchedulesOptions {
     random?: () => number;
+    /**
+     * @deprecated No longer called: jitter defers a window to a later tick instead of sleeping inside
+     * this one. Kept so existing callers still type-check.
+     */
     sleep?: (ms: number) => Promise<void>;
 }
 /** Deterministic run id for a fixed-interval schedule's current time window. */
@@ -7096,10 +7102,14 @@ declare function scheduleRunIdAt(s: ScheduledWorkflow, nowMs: number): string;
  * Start each schedule's current-window run. The run id is the time bucket (a fixed-interval index,
  * or the cron fire time) and `engine.start` is idempotent, so firing this on an interval — or
  * racing two instances on the same tick — starts **each window exactly once**. Wire it to a
- * `setInterval`, the durable timer poller, or `@nestjs/schedule`. Returns the run ids this call
+ * `setInterval`, the durable timer poller, or `@nestjs/schedule`.
+ *
+ * Pass the SAME `engine` object on every call: which windows already fired, and the jittered fire
+ * time of each deferred window, are remembered per engine object. A fresh wrapper per call would
+ * redraw a deferred window's fire time on every tick, so it might never fire. Returns the run ids this call
  * started: a window that already has a run is not started or returned again, and once this process
- * has seen a window's run exist, later calls in that window skip it without a store read or a
- * jitter sleep.
+ * has seen a window's run exist, later calls in that window skip it without a store read. A
+ * jittered window is deferred to a later call, never slept on.
  */
 declare function runSchedules(engine: Pick<WorkflowEngine, 'start' | 'getRun'> & Partial<Pick<WorkflowEngine, 'isDraining'>>, schedules: readonly ScheduledWorkflow[], nowMs: number, opts?: RunSchedulesOptions): Promise<string[]>;
 

package/dist/index.d.ts

@@ -7038,6 +7038,8 @@ interface ScheduledWorkflow<W extends WorkflowRef = WorkflowRef> {
     /**
      * Randomly delay the dispatch by up to this many ms BEFORE firing, to spread load when many
      * instances tick on the same boundary (avoids a thundering herd). Opt-in; absent = fire immediately.
+     * The window is deferred to a later tick, never waited for inside one, so a jittered schedule does
+     * not hold up any other schedule or the rest of the timer poll.
      *
      * This is dispatch-path jitter only — it does NOT affect the run id (still the time bucket), so
      * idempotency is unchanged: two instances jittering the same window still start it exactly once.
@@ -7066,9 +7068,13 @@ interface ScheduledWorkflow<W extends WorkflowRef = WorkflowRef> {
     namespace?: string;
 }
 /** Injectable dispatch-path effects (kept out of the deterministic run-id logic). Defaults to real
- *  `Math.random` + `setTimeout`; overridden in tests so jitter is deterministic and instant. */
+ *  `Math.random`; overridden in tests so jitter is deterministic. */
 interface RunSchedulesOptions {
     random?: () => number;
+    /**
+     * @deprecated No longer called: jitter defers a window to a later tick instead of sleeping inside
+     * this one. Kept so existing callers still type-check.
+     */
     sleep?: (ms: number) => Promise<void>;
 }
 /** Deterministic run id for a fixed-interval schedule's current time window. */
@@ -7096,10 +7102,14 @@ declare function scheduleRunIdAt(s: ScheduledWorkflow, nowMs: number): string;
  * Start each schedule's current-window run. The run id is the time bucket (a fixed-interval index,
  * or the cron fire time) and `engine.start` is idempotent, so firing this on an interval — or
  * racing two instances on the same tick — starts **each window exactly once**. Wire it to a
- * `setInterval`, the durable timer poller, or `@nestjs/schedule`. Returns the run ids this call
+ * `setInterval`, the durable timer poller, or `@nestjs/schedule`.
+ *
+ * Pass the SAME `engine` object on every call: which windows already fired, and the jittered fire
+ * time of each deferred window, are remembered per engine object. A fresh wrapper per call would
+ * redraw a deferred window's fire time on every tick, so it might never fire. Returns the run ids this call
  * started: a window that already has a run is not started or returned again, and once this process
- * has seen a window's run exist, later calls in that window skip it without a store read or a
- * jitter sleep.
+ * has seen a window's run exist, later calls in that window skip it without a store read. A
+ * jittered window is deferred to a later call, never slept on.
  */
 declare function runSchedules(engine: Pick<WorkflowEngine, 'start' | 'getRun'> & Partial<Pick<WorkflowEngine, 'isDraining'>>, schedules: readonly ScheduledWorkflow[], nowMs: number, opts?: RunSchedulesOptions): Promise<string[]>;
 

package/dist/index.js

@@ -2417,7 +2417,31 @@ __name(resolveCronParse, "resolveCronParse");
 
 // src/scheduler.ts
 var nodeRequire = createRequire(import.meta.url);
-var defaultSleep = /* @__PURE__ */ __name((ms) => new Promise((r) => setTimeout(r, ms)), "defaultSleep");
+var jitterFireAt = /* @__PURE__ */ new WeakMap();
+function deferredWindows(engine, key) {
+  return [
+    ...jitterFireAt.get(engine)?.get(key)?.keys() ?? []
+  ];
+}
+__name(deferredWindows, "deferredWindows");
+function jitterDue(engine, s, candidates, nowMs, random) {
+  let byKey = jitterFireAt.get(engine);
+  if (byKey === void 0) {
+    byKey = /* @__PURE__ */ new Map();
+    jitterFireAt.set(engine, byKey);
+  }
+  const previous = byKey.get(s.key);
+  const current = /* @__PURE__ */ new Map();
+  const due = [];
+  for (const runId of candidates) {
+    const at = previous?.get(runId) ?? nowMs + Math.floor(random() * s.jitter);
+    if (nowMs >= at) due.push(runId);
+    else current.set(runId, at);
+  }
+  byKey.set(s.key, current);
+  return due;
+}
+__name(jitterDue, "jitterDue");
 function scheduledRunId(key, everyMs, nowMs) {
   return `sched:${key}:${Math.floor(nowMs / everyMs)}`;
 }
@@ -2487,13 +2511,19 @@ function scheduleRunIdsAt(s, nowMs) {
 __name(scheduleRunIdsAt, "scheduleRunIdsAt");
 async function runSchedules(engine, schedules, nowMs, opts) {
   const random = opts?.random ?? Math.random;
-  const sleep = opts?.sleep ?? defaultSleep;
   const settled = settledIdsFor(engine);
   const ids = [];
   for (const s of schedules) {
     if (engine.isDraining?.()) break;
     if (s.paused) continue;
-    const candidates = scheduleRunIdsAt(s, nowMs).filter((id) => !settled.get(s.key)?.has(id));
+    const due = scheduleRunIdsAt(s, nowMs);
+    const windows = s.jitter && s.jitter > 0 ? [
+      .../* @__PURE__ */ new Set([
+        ...deferredWindows(engine, s.key),
+        ...due
+      ])
+    ] : due;
+    const candidates = windows.filter((id) => !settled.get(s.key)?.has(id));
     if (candidates.length === 0) continue;
     if (s.overlap === "skip" && s.everyMs) {
       const prevBucket = Math.floor(nowMs / s.everyMs) - 1;
@@ -2502,8 +2532,10 @@ async function runSchedules(engine, schedules, nowMs, opts) {
         if (prev && (prev.status === "running" || prev.status === "suspended")) continue;
       }
     }
-    if (s.jitter && s.jitter > 0) await sleep(Math.floor(random() * s.jitter));
-    for (const runId of candidates) {
+    if (!(s.jitter && s.jitter > 0)) jitterFireAt.get(engine)?.delete(s.key);
+    const firing = s.jitter && s.jitter > 0 ? jitterDue(engine, s, candidates, nowMs, random) : candidates;
+    if (firing.length === 0) continue;
+    for (const runId of firing) {
       if (engine.isDraining?.()) break;
       const existing = await engine.getRun(runId);
       remember(settled, s.key, runId);