@dudousxd/nestjs-durable-core 0.30.0 → 0.31.0

package/dist/index.cjs

@@ -28,6 +28,7 @@ __export(index_exports, {
   Entities: () => Entities,
   EventAccumulators: () => EventAccumulators,
   FatalError: () => FatalError,
+  InMemoryAdmissionBackend: () => InMemoryAdmissionBackend,
   InMemoryStateStore: () => InMemoryStateStore,
   InMemoryTransport: () => InMemoryTransport,
   NonDeterminismError: () => NonDeterminismError,
@@ -65,6 +66,161 @@ __export(index_exports, {
 });
 module.exports = __toCommonJS(index_exports);
 
+// src/queue.ts
+var QueueController = class {
+  static {
+    __name(this, "QueueController");
+  }
+  config;
+  clock;
+  inFlight = 0;
+  windowStart = 0;
+  windowCount = 0;
+  /** Registered waiters by id (only used when priority/fairness ordering is in play). */
+  waiters = /* @__PURE__ */ new Map();
+  /** Monotonic counter stamping each newly-seen waiter for a stable FIFO tiebreak. */
+  waiterSeq = 0;
+  /** Per-key "last served" order for round-robin fairness — higher = more recently served. */
+  keyServed = /* @__PURE__ */ new Map();
+  servedTick = 0;
+  constructor(config, clock) {
+    this.config = config;
+    this.clock = clock;
+  }
+  /** Whether this controller does any priority/fairness ordering (else it's a plain FIFO gate). */
+  get ordered() {
+    return this.config.fairness === "key" || this.config.order === "lifo";
+  }
+  /**
+  * Try to admit one unit of work. On `ok`, the caller has taken a concurrency slot and must call
+  * {@link release} when the step settles. On block, `retryAt` is when admission may next succeed.
+  *
+  * `item` carries optional priority/fairness hints; omitting it is the legacy FIFO path. When
+  * ordering is configured (or a priority is given), a blocked call REGISTERS as a waiter and is only
+  * admitted on a later retry once it is the rightful next under (priority desc, fairness, FIFO).
+  */
+  tryAdmit(item) {
+    const now = this.clock();
+    const rl = this.config.rateLimit;
+    if (rl) {
+      if (now - this.windowStart >= rl.periodMs) {
+        this.windowStart = now;
+        this.windowCount = 0;
+      }
+      if (this.windowCount >= rl.limit) return {
+        ok: false,
+        retryAt: this.windowStart + rl.periodMs
+      };
+    }
+    const usingOrder = this.ordered || item?.priority != null || item?.waiterId != null;
+    const waiterId = item?.waiterId;
+    const full = this.config.concurrency != null && this.inFlight >= this.config.concurrency;
+    if (full) {
+      if (usingOrder && waiterId != null) this.register(waiterId, item);
+      return {
+        ok: false,
+        retryAt: now + (this.config.retryMs ?? 1e3)
+      };
+    }
+    if (usingOrder && this.waiters.size > 0) {
+      if (waiterId != null) this.register(waiterId, item);
+      if (!this.isNext(waiterId, item)) {
+        return {
+          ok: false,
+          retryAt: now + (this.config.retryMs ?? 1e3)
+        };
+      }
+    }
+    if (rl) this.windowCount += 1;
+    this.inFlight += 1;
+    if (waiterId != null) this.waiters.delete(waiterId);
+    if (item?.key != null) this.keyServed.set(item.key, ++this.servedTick);
+    return {
+      ok: true
+    };
+  }
+  /** Release a concurrency slot taken by a successful {@link tryAdmit}. */
+  release() {
+    if (this.inFlight > 0) this.inFlight -= 1;
+  }
+  /** Track (or refresh) a blocked call as a waiter; its FIFO seq is stamped only on first sight. */
+  register(waiterId, item) {
+    const existing = this.waiters.get(waiterId);
+    if (existing) {
+      existing.priority = item?.priority ?? 0;
+      existing.key = item?.key;
+      return;
+    }
+    this.waiters.set(waiterId, {
+      priority: item?.priority ?? 0,
+      key: item?.key,
+      seq: this.waiterSeq++
+    });
+  }
+  /**
+  * Is the calling item the best candidate among all registered waiters? Ordering, best first:
+  *   1. higher `priority`;
+  *   2. fairness: with `fairness: 'key'`, the least-recently-served key wins (round-robin);
+  *   3. earliest registration (FIFO) — stable tiebreak.
+  * A bare item (no waiterId) is compared on its hints directly.
+  */
+  isNext(waiterId, item) {
+    const self = (waiterId != null ? this.waiters.get(waiterId) : void 0) ?? {
+      priority: item?.priority ?? 0,
+      key: item?.key,
+      seq: Number.POSITIVE_INFINITY
+    };
+    let best = self;
+    for (const w of this.waiters.values()) {
+      if (this.better(w, best)) best = w;
+    }
+    return best === self;
+  }
+  /** Strict "a should be admitted before b" comparison under the active policy. */
+  better(a, b) {
+    if (a.priority !== b.priority) return a.priority > b.priority;
+    if (this.config.fairness === "key") {
+      const sa = this.servedOf(a.key);
+      const sb = this.servedOf(b.key);
+      if (sa !== sb) return sa < sb;
+    }
+    return this.config.order === "lifo" ? a.seq > b.seq : a.seq < b.seq;
+  }
+  /** Last-served tick for a key (0 = never served, so an unseen key is admitted before a busy one). */
+  servedOf(key) {
+    if (key == null) return 0;
+    return this.keyServed.get(key) ?? 0;
+  }
+};
+
+// src/admission.ts
+var InMemoryAdmissionBackend = class {
+  static {
+    __name(this, "InMemoryAdmissionBackend");
+  }
+  clock;
+  controllers = /* @__PURE__ */ new Map();
+  constructor(clock) {
+    this.clock = clock;
+  }
+  register(config) {
+    this.controllers.set(config.name, new QueueController(config, this.clock));
+  }
+  handles(queue) {
+    return this.controllers.has(queue);
+  }
+  async tryAdmit(queue, item) {
+    const controller = this.controllers.get(queue);
+    if (!controller) return {
+      ok: true
+    };
+    return controller.tryAdmit(item);
+  }
+  async release(queue, _slotId) {
+    this.controllers.get(queue)?.release();
+  }
+};
+
 // src/duration.ts
 var UNIT_MS = {
   ms: 1,
@@ -581,133 +737,6 @@ function eventMatches(payload, match) {
 }
 __name(eventMatches, "eventMatches");
 
-// src/queue.ts
-var QueueController = class {
-  static {
-    __name(this, "QueueController");
-  }
-  config;
-  clock;
-  inFlight = 0;
-  windowStart = 0;
-  windowCount = 0;
-  /** Registered waiters by id (only used when priority/fairness ordering is in play). */
-  waiters = /* @__PURE__ */ new Map();
-  /** Monotonic counter stamping each newly-seen waiter for a stable FIFO tiebreak. */
-  waiterSeq = 0;
-  /** Per-key "last served" order for round-robin fairness — higher = more recently served. */
-  keyServed = /* @__PURE__ */ new Map();
-  servedTick = 0;
-  constructor(config, clock) {
-    this.config = config;
-    this.clock = clock;
-  }
-  /** Whether this controller does any priority/fairness ordering (else it's a plain FIFO gate). */
-  get ordered() {
-    return this.config.fairness === "key";
-  }
-  /**
-  * Try to admit one unit of work. On `ok`, the caller has taken a concurrency slot and must call
-  * {@link release} when the step settles. On block, `retryAt` is when admission may next succeed.
-  *
-  * `item` carries optional priority/fairness hints; omitting it is the legacy FIFO path. When
-  * ordering is configured (or a priority is given), a blocked call REGISTERS as a waiter and is only
-  * admitted on a later retry once it is the rightful next under (priority desc, fairness, FIFO).
-  */
-  tryAdmit(item) {
-    const now = this.clock();
-    const rl = this.config.rateLimit;
-    if (rl) {
-      if (now - this.windowStart >= rl.periodMs) {
-        this.windowStart = now;
-        this.windowCount = 0;
-      }
-      if (this.windowCount >= rl.limit) return {
-        ok: false,
-        retryAt: this.windowStart + rl.periodMs
-      };
-    }
-    const usingOrder = this.ordered || item?.priority != null || item?.waiterId != null;
-    const waiterId = item?.waiterId;
-    const full = this.config.concurrency != null && this.inFlight >= this.config.concurrency;
-    if (full) {
-      if (usingOrder && waiterId != null) this.register(waiterId, item);
-      return {
-        ok: false,
-        retryAt: now + (this.config.retryMs ?? 1e3)
-      };
-    }
-    if (usingOrder && this.waiters.size > 0) {
-      if (waiterId != null) this.register(waiterId, item);
-      if (!this.isNext(waiterId, item)) {
-        return {
-          ok: false,
-          retryAt: now + (this.config.retryMs ?? 1e3)
-        };
-      }
-    }
-    if (rl) this.windowCount += 1;
-    this.inFlight += 1;
-    if (waiterId != null) this.waiters.delete(waiterId);
-    if (item?.key != null) this.keyServed.set(item.key, ++this.servedTick);
-    return {
-      ok: true
-    };
-  }
-  /** Release a concurrency slot taken by a successful {@link tryAdmit}. */
-  release() {
-    if (this.inFlight > 0) this.inFlight -= 1;
-  }
-  /** Track (or refresh) a blocked call as a waiter; its FIFO seq is stamped only on first sight. */
-  register(waiterId, item) {
-    const existing = this.waiters.get(waiterId);
-    if (existing) {
-      existing.priority = item?.priority ?? 0;
-      existing.key = item?.key;
-      return;
-    }
-    this.waiters.set(waiterId, {
-      priority: item?.priority ?? 0,
-      key: item?.key,
-      seq: this.waiterSeq++
-    });
-  }
-  /**
-  * Is the calling item the best candidate among all registered waiters? Ordering, best first:
-  *   1. higher `priority`;
-  *   2. fairness: with `fairness: 'key'`, the least-recently-served key wins (round-robin);
-  *   3. earliest registration (FIFO) — stable tiebreak.
-  * A bare item (no waiterId) is compared on its hints directly.
-  */
-  isNext(waiterId, item) {
-    const self = (waiterId != null ? this.waiters.get(waiterId) : void 0) ?? {
-      priority: item?.priority ?? 0,
-      key: item?.key,
-      seq: Number.POSITIVE_INFINITY
-    };
-    let best = self;
-    for (const w of this.waiters.values()) {
-      if (this.better(w, best)) best = w;
-    }
-    return best === self;
-  }
-  /** Strict "a should be admitted before b" comparison under the active policy. */
-  better(a, b) {
-    if (a.priority !== b.priority) return a.priority > b.priority;
-    if (this.config.fairness === "key") {
-      const sa = this.servedOf(a.key);
-      const sb = this.servedOf(b.key);
-      if (sa !== sb) return sa < sb;
-    }
-    return a.seq < b.seq;
-  }
-  /** Last-served tick for a key (0 = never served, so an unseen key is admitted before a busy one). */
-  servedOf(key) {
-    if (key == null) return 0;
-    return this.keyServed.get(key) ?? 0;
-  }
-};
-
 // src/singleton-gate.ts
 var SINGLETON_RETRY_MS = 1e3;
 var SINGLETON_RETRY_JITTER_MS = 250;
@@ -901,6 +930,12 @@ function workflowName(ref) {
 __name(workflowName, "workflowName");
 
 // src/workflow-ctx.ts
+function normalizeChildOptions(options) {
+  return typeof options === "string" ? {
+    childId: options
+  } : options ?? {};
+}
+__name(normalizeChildOptions, "normalizeChildOptions");
 var Position = class Position2 {
   static {
     __name(this, "Position");
@@ -1150,7 +1185,8 @@ function createWorkflowCtx(host, runId, compensations, workflow = "") {
     await step(`task:dispatch:${name}`, dispatch, options);
     return unwrapCompletion(await waitForSignal(`task:${runId}:${name}`), `task "${name}"`);
   }, "task");
-  const child = /* @__PURE__ */ __name(async (workflow2, input, childId) => {
+  const child = /* @__PURE__ */ __name(async (workflow2, input, options) => {
+    const { childId, priority } = normalizeChildOptions(options);
     const current = pos.next();
     const id = childId ?? `${runId}.child.${current}`;
     const existing = await readCheckpoint(current);
@@ -1162,7 +1198,7 @@ function createWorkflowCtx(host, runId, compensations, workflow = "") {
       runId,
       seq: current
     });
-    if (!await store.getRun(id)) host.startChild(workflowName(workflow2), input, id);
+    if (!await store.getRun(id)) host.startChild(workflowName(workflow2), input, id, priority);
     if (!existing) {
       await writeCheckpoint(instantCheckpoint({
         runId,
@@ -1174,12 +1210,13 @@ function createWorkflowCtx(host, runId, compensations, workflow = "") {
     }
     throw new WorkflowSuspended();
   }, "child");
-  const startChild = /* @__PURE__ */ __name(async (workflow2, input, childId) => {
+  const startChild = /* @__PURE__ */ __name(async (workflow2, input, options) => {
+    const { childId, priority } = normalizeChildOptions(options);
     const current = pos.next();
     const id = childId ?? `${runId}.child.${current}`;
     const existing = await readCheckpoint(current);
     if (existing && existing.status === "completed") return existing.output;
-    if (!await store.getRun(id)) host.startChild(workflowName(workflow2), input, id);
+    if (!await store.getRun(id)) host.startChild(workflowName(workflow2), input, id, priority);
     await writeCheckpoint(instantCheckpoint({
       runId,
       seq: current,
@@ -1403,8 +1440,10 @@ var WorkflowEngine = class {
   updateValidators = /* @__PURE__ */ new Map();
   /** Runs being cancelled WITH saga compensation — see `cancel({ compensate: true })`. */
   cancelRequested = /* @__PURE__ */ new Set();
-  /** Flow-control queues for remote steps, keyed by name (see {@link registerQueue}). */
-  queues = /* @__PURE__ */ new Map();
+  /** Flow-control admission backend for remote steps (see {@link registerQueue}). */
+  admission;
+  /** Runs on THIS instance blocked on admission, by queue — woken early on a freed-slot signal. */
+  queueWaiters = /* @__PURE__ */ new Map();
   /** Which queue a dispatched step took a slot from, by stepId — so the result can release it. */
   stepQueue = /* @__PURE__ */ new Map();
   /** Executions currently in flight, so a graceful shutdown can wait for them to settle. */
@@ -1420,6 +1459,8 @@ var WorkflowEngine = class {
     ] : []));
     this.controlPlane = deps.controlPlane;
     this.clock = deps.clock ?? Date.now;
+    this.admission = deps.admission ?? new InMemoryAdmissionBackend(this.clock);
+    this.admission.onFreed?.((queue) => this.wakeQueueWaiters(queue));
     this.instanceId = deps.instanceId ?? globalThis.crypto.randomUUID();
     this.leaseMs = deps.leaseMs ?? 3e4;
     this.maxRecoveryAttempts = deps.maxRecoveryAttempts;
@@ -1583,7 +1624,7 @@ var WorkflowEngine = class {
   * durable. Per engine instance (see {@link QueueConfig}). Registering the same name replaces it.
   */
   registerQueue(config) {
-    this.queues.set(config.name, new QueueController(config, this.clock));
+    this.admission.register(config);
   }
   /** Subscribe to lifecycle events. Returns an unsubscribe function. */
   subscribe(listener) {
@@ -1704,6 +1745,7 @@ var WorkflowEngine = class {
       input,
       tags,
       searchAttributes: opts?.searchAttributes,
+      priority: opts?.priority,
       createdAt: now,
       updatedAt: now
     };
@@ -2930,8 +2972,10 @@ var WorkflowEngine = class {
       failStep: /* @__PURE__ */ __name((s) => this.failStep(s), "failStep"),
       callRemote: /* @__PURE__ */ __name((runId, seq, step, input, queue, transport, admission) => this.callRemote(runId, seq, step, input, queue, transport, replay, admission), "callRemote"),
       // Defer so a fast child can't reentrantly resume a still-running parent.
-      startChild: /* @__PURE__ */ __name((workflow, input, id) => {
-        queueMicrotask(() => void this.start(workflow, input, id).catch(() => void 0));
+      startChild: /* @__PURE__ */ __name((workflow, input, id, priority) => {
+        queueMicrotask(() => void this.start(workflow, input, id, {
+          priority
+        }).catch(() => void 0));
       }, "startChild"),
       signalEntity: /* @__PURE__ */ __name((name, key, op, arg, reply) => {
         queueMicrotask(() => void this.entities.dispatch(name, key, op, arg, reply).catch(() => void 0));
@@ -3032,14 +3076,19 @@ var WorkflowEngine = class {
       attempt = existing.attempts + 1;
     }
     const id = stepId(runId, seq);
-    const controller = queue ? this.queues.get(queue) : void 0;
-    if (controller) {
-      const decision = controller.tryAdmit({
+    if (queue && this.admission.handles(queue)) {
+      const decision = await this.admission.tryAdmit(queue, {
         priority: admission?.priority,
         key: admission?.fairnessKey ?? runId,
         waiterId: id
       });
-      if (!decision.ok) throw new WorkflowSuspended(decision.retryAt);
+      if (!decision.ok) {
+        const waiters = this.queueWaiters.get(queue) ?? /* @__PURE__ */ new Set();
+        waiters.add(runId);
+        this.queueWaiters.set(queue, waiters);
+        throw new WorkflowSuspended(decision.retryAt);
+      }
+      this.queueWaiters.get(queue)?.delete(runId);
       this.stepQueue.set(id, queue);
     }
     const validInput = step.input.parse(input);
@@ -3067,6 +3116,7 @@ var WorkflowEngine = class {
       input: validInput,
       traceparent: this.traceparent?.(),
       context: this.context?.(),
+      priority: admission?.priority,
       attempt
     }, transport);
     this.emit({
@@ -3086,7 +3136,7 @@ var WorkflowEngine = class {
   async completeRemoteResult(result) {
     const cp = await this.store.getCheckpoint(result.runId, result.seq);
     if (!cp || cp.status !== "pending") return;
-    this.releaseQueueSlot(cp.stepId);
+    void this.releaseQueueSlot(cp.stepId).catch(() => void 0);
     const run = await this.store.getRun(result.runId);
     if (run && (run.status === "cancelled" || run.status === "completed")) return;
     const finishedAt = /* @__PURE__ */ new Date();
@@ -3113,12 +3163,26 @@ var WorkflowEngine = class {
     });
     await this.resume(result.runId);
   }
+  /**
+  * A slot freed on `queue` (a fleet-wide signal): resume this instance's runs blocked on it so they
+  * re-contend now instead of at their retry tick. Snapshot-and-clear — a run still blocked after the
+  * retry re-registers itself, and one that's gone (cancelled/admitted) is dropped. Best-effort.
+  */
+  wakeQueueWaiters(queue) {
+    const waiters = this.queueWaiters.get(queue);
+    if (!waiters || waiters.size === 0) return;
+    const runIds = [
+      ...waiters
+    ];
+    waiters.clear();
+    for (const runId of runIds) void this.resume(runId).catch(() => void 0);
+  }
   /** Release the flow-control slot a dispatched step held (if any), by its stepId. */
-  releaseQueueSlot(id) {
+  async releaseQueueSlot(id) {
     const queue = this.stepQueue.get(id);
     if (queue === void 0) return;
     this.stepQueue.delete(id);
-    this.queues.get(queue)?.release();
+    await this.admission.release(queue, id);
   }
   /** In-memory await path for a remote step with a liveness `timeoutMs` (re-dispatch on timeout). */
   async callRemoteInMemory(runId, seq, step, input, transport) {
@@ -3279,6 +3343,7 @@ var RemoteWorkflowExecutor = class {
       input: run.input,
       history,
       group: this.group,
+      priority: run.priority,
       attempt: 1
     };
     const decision = new Promise((resolve, reject) => {
@@ -4011,6 +4076,7 @@ var InMemoryTransport = class {
   Entities,
   EventAccumulators,
   FatalError,
+  InMemoryAdmissionBackend,
   InMemoryStateStore,
   InMemoryTransport,
   NonDeterminismError,