@dudousxd/nestjs-durable-core 0.39.0 → 0.40.1

package/dist/index.d.cts

@@ -246,6 +246,13 @@ interface WorkflowRun {
     tags?: string[] | undefined;
     /** Typed, queryable run data (e.g. `{ amount: 200, tier: 'pro' }`) — see {@link RunQuery.attributes}. */
     searchAttributes?: SearchAttributes | undefined;
+    /**
+     * The worker-pool partition this run belongs to. Stamped at creation from the creating engine's
+     * `namespace` (default `'default'`). A worker only picks up / recovers / resumes-timers-for /
+     * times-out runs in its own namespace. `undefined` on a run created before this field existed; the
+     * store persists it as `'default'`. Read paths (dashboard, `getRun`) are NOT namespace-scoped.
+     */
+    namespace?: string | undefined;
     /**
      * Dispatch priority for a REMOTE run (one advanced by a {@link WorkflowExecutor} over a broker):
      * carried onto each {@link WorkflowTask} so an urgent child workflow can jump ahead of enqueued
@@ -433,11 +440,11 @@ interface StateStore {
      */
     saveCheckpoint(checkpoint: StepCheckpoint): Promise<void>;
     /** Used by recovery on boot to find runs to resume (crashed, left `running`). */
-    listIncompleteRuns(): Promise<WorkflowRun[]>;
+    listIncompleteRuns(namespace?: string): Promise<WorkflowRun[]>;
     /** The oldest `pending` runs awaiting dispatch (FIFO, by `createdAt`), capped at `limit`. */
-    listPendingRuns(limit: number): Promise<WorkflowRun[]>;
+    listPendingRuns(limit: number, namespace?: string): Promise<WorkflowRun[]>;
     /** Suspended runs whose durable timer is due (`wakeAt <= nowMs`), ready to resume. */
-    listDueTimers(nowMs: number): Promise<WorkflowRun[]>;
+    listDueTimers(nowMs: number, namespace?: string): Promise<WorkflowRun[]>;
     /**
      * Atomically acquire the recovery lease on a run for `owner` until `leaseUntilMs`, but only if
      * it is currently unlocked or its lease has expired (`<= nowMs`). Returns whether it was
@@ -549,6 +556,8 @@ interface RunQuery {
      * `workflow`/`status`/`tag` to bound the scan on large stores.
      */
     attributes?: AttributeFilter[] | undefined;
+    /** Restrict to runs in this namespace (exact match), ANDed with the other predicates. */
+    namespace?: string | undefined;
     limit?: number | undefined;
     offset?: number | undefined;
 }
@@ -565,6 +574,15 @@ interface SignalWaiter {
     token: string;
     runId: string;
     seq: number;
+    /**
+     * The parallel-fan group this waiter belongs to, carried from the awaiting command so the resolving
+     * `signal:<token>` checkpoint (notably `signal:child:<id>` for an awaited child run) can be tagged
+     * with it. A worker's `ctx.gather_children`/`ctx.all` fan-out stamps every `startChild` with the same
+     * group; without threading it through the waiter, the child-await checkpoint comes out untagged and the
+     * dashboard renders the fan as a sequential chain instead of one parallel group. Undefined for an
+     * ordinary (non-fan) signal/child await.
+     */
+    parallelGroup?: string | undefined;
 }
 /** A unit of work dispatched to a remote worker. This is the documented wire payload. */
 interface RemoteTask {
@@ -1336,6 +1354,13 @@ interface WorkflowEngineDeps {
     admission?: AdmissionBackend | undefined;
     /** Unique id for this engine instance, used for recovery leases. Defaults to a random id. */
     instanceId?: string | undefined;
+    /**
+     * Worker-pool partition for this engine. Stamped on every run it creates; the poll paths
+     * (`runPending`/`recoverIncomplete`/`resumeDueTimers`/`sweepTimeouts`) only act on runs in this
+     * namespace. Default `'default'` — byte-identical to a single-pool deployment. Set distinct values
+     * to safely share ONE state store across non-interchangeable pools (e.g. local dev vs a cluster).
+     */
+    namespace?: string | undefined;
     /** Recovery lease duration in ms — how long this instance owns a run it picked up. Default 30s. */
     leaseMs?: number | undefined;
     /**
@@ -1427,6 +1452,7 @@ declare class WorkflowEngine {
     private readonly controlPlane?;
     private readonly clock;
     private readonly instanceId;
+    private readonly namespace;
     private readonly leaseMs;
     private readonly maxRecoveryAttempts?;
     private readonly remoteAdvanceSilenceMs?;
@@ -2146,9 +2172,9 @@ declare class CodecStateStore implements StateStore {
         raw: unknown;
         saveCheckpoint: (cp: StepCheckpoint) => Promise<void>;
     }) => Promise<T>): Promise<T>;
-    listIncompleteRuns(): Promise<WorkflowRun[]>;
-    listPendingRuns(limit: number): Promise<WorkflowRun[]>;
-    listDueTimers(nowMs: number): Promise<WorkflowRun[]>;
+    listIncompleteRuns(namespace?: string): Promise<WorkflowRun[]>;
+    listPendingRuns(limit: number, namespace?: string): Promise<WorkflowRun[]>;
+    listDueTimers(nowMs: number, namespace?: string): Promise<WorkflowRun[]>;
     tryLockRun(runId: string, owner: string, leaseUntilMs: number, nowMs: number): Promise<boolean>;
     releaseRunLock(runId: string): Promise<void>;
     renewRunLock(runId: string, owner: string, leaseUntilMs: number): Promise<boolean>;
@@ -2410,9 +2436,9 @@ declare class InMemoryStateStore implements StateStore {
     deleteRun(runId: string): Promise<void>;
     getCheckpoint(runId: string, seq: number): Promise<StepCheckpoint | null>;
     saveCheckpoint(checkpoint: StepCheckpoint): Promise<void>;
-    listIncompleteRuns(): Promise<WorkflowRun[]>;
-    listPendingRuns(limit: number): Promise<WorkflowRun[]>;
-    listDueTimers(nowMs: number): Promise<WorkflowRun[]>;
+    listIncompleteRuns(namespace?: string): Promise<WorkflowRun[]>;
+    listPendingRuns(limit: number, namespace?: string): Promise<WorkflowRun[]>;
+    listDueTimers(nowMs: number, namespace?: string): Promise<WorkflowRun[]>;
     tryLockRun(runId: string, owner: string, leaseUntilMs: number, nowMs: number): Promise<boolean>;
     releaseRunLock(runId: string): Promise<void>;
     renewRunLock(runId: string, owner: string, leaseUntilMs: number): Promise<boolean>;

package/dist/index.d.ts

@@ -246,6 +246,13 @@ interface WorkflowRun {
     tags?: string[] | undefined;
     /** Typed, queryable run data (e.g. `{ amount: 200, tier: 'pro' }`) — see {@link RunQuery.attributes}. */
     searchAttributes?: SearchAttributes | undefined;
+    /**
+     * The worker-pool partition this run belongs to. Stamped at creation from the creating engine's
+     * `namespace` (default `'default'`). A worker only picks up / recovers / resumes-timers-for /
+     * times-out runs in its own namespace. `undefined` on a run created before this field existed; the
+     * store persists it as `'default'`. Read paths (dashboard, `getRun`) are NOT namespace-scoped.
+     */
+    namespace?: string | undefined;
     /**
      * Dispatch priority for a REMOTE run (one advanced by a {@link WorkflowExecutor} over a broker):
      * carried onto each {@link WorkflowTask} so an urgent child workflow can jump ahead of enqueued
@@ -433,11 +440,11 @@ interface StateStore {
      */
     saveCheckpoint(checkpoint: StepCheckpoint): Promise<void>;
     /** Used by recovery on boot to find runs to resume (crashed, left `running`). */
-    listIncompleteRuns(): Promise<WorkflowRun[]>;
+    listIncompleteRuns(namespace?: string): Promise<WorkflowRun[]>;
     /** The oldest `pending` runs awaiting dispatch (FIFO, by `createdAt`), capped at `limit`. */
-    listPendingRuns(limit: number): Promise<WorkflowRun[]>;
+    listPendingRuns(limit: number, namespace?: string): Promise<WorkflowRun[]>;
     /** Suspended runs whose durable timer is due (`wakeAt <= nowMs`), ready to resume. */
-    listDueTimers(nowMs: number): Promise<WorkflowRun[]>;
+    listDueTimers(nowMs: number, namespace?: string): Promise<WorkflowRun[]>;
     /**
      * Atomically acquire the recovery lease on a run for `owner` until `leaseUntilMs`, but only if
      * it is currently unlocked or its lease has expired (`<= nowMs`). Returns whether it was
@@ -549,6 +556,8 @@ interface RunQuery {
      * `workflow`/`status`/`tag` to bound the scan on large stores.
      */
     attributes?: AttributeFilter[] | undefined;
+    /** Restrict to runs in this namespace (exact match), ANDed with the other predicates. */
+    namespace?: string | undefined;
     limit?: number | undefined;
     offset?: number | undefined;
 }
@@ -565,6 +574,15 @@ interface SignalWaiter {
     token: string;
     runId: string;
     seq: number;
+    /**
+     * The parallel-fan group this waiter belongs to, carried from the awaiting command so the resolving
+     * `signal:<token>` checkpoint (notably `signal:child:<id>` for an awaited child run) can be tagged
+     * with it. A worker's `ctx.gather_children`/`ctx.all` fan-out stamps every `startChild` with the same
+     * group; without threading it through the waiter, the child-await checkpoint comes out untagged and the
+     * dashboard renders the fan as a sequential chain instead of one parallel group. Undefined for an
+     * ordinary (non-fan) signal/child await.
+     */
+    parallelGroup?: string | undefined;
 }
 /** A unit of work dispatched to a remote worker. This is the documented wire payload. */
 interface RemoteTask {
@@ -1336,6 +1354,13 @@ interface WorkflowEngineDeps {
     admission?: AdmissionBackend | undefined;
     /** Unique id for this engine instance, used for recovery leases. Defaults to a random id. */
     instanceId?: string | undefined;
+    /**
+     * Worker-pool partition for this engine. Stamped on every run it creates; the poll paths
+     * (`runPending`/`recoverIncomplete`/`resumeDueTimers`/`sweepTimeouts`) only act on runs in this
+     * namespace. Default `'default'` — byte-identical to a single-pool deployment. Set distinct values
+     * to safely share ONE state store across non-interchangeable pools (e.g. local dev vs a cluster).
+     */
+    namespace?: string | undefined;
     /** Recovery lease duration in ms — how long this instance owns a run it picked up. Default 30s. */
     leaseMs?: number | undefined;
     /**
@@ -1427,6 +1452,7 @@ declare class WorkflowEngine {
     private readonly controlPlane?;
     private readonly clock;
     private readonly instanceId;
+    private readonly namespace;
     private readonly leaseMs;
     private readonly maxRecoveryAttempts?;
     private readonly remoteAdvanceSilenceMs?;
@@ -2146,9 +2172,9 @@ declare class CodecStateStore implements StateStore {
         raw: unknown;
         saveCheckpoint: (cp: StepCheckpoint) => Promise<void>;
     }) => Promise<T>): Promise<T>;
-    listIncompleteRuns(): Promise<WorkflowRun[]>;
-    listPendingRuns(limit: number): Promise<WorkflowRun[]>;
-    listDueTimers(nowMs: number): Promise<WorkflowRun[]>;
+    listIncompleteRuns(namespace?: string): Promise<WorkflowRun[]>;
+    listPendingRuns(limit: number, namespace?: string): Promise<WorkflowRun[]>;
+    listDueTimers(nowMs: number, namespace?: string): Promise<WorkflowRun[]>;
     tryLockRun(runId: string, owner: string, leaseUntilMs: number, nowMs: number): Promise<boolean>;
     releaseRunLock(runId: string): Promise<void>;
     renewRunLock(runId: string, owner: string, leaseUntilMs: number): Promise<boolean>;
@@ -2410,9 +2436,9 @@ declare class InMemoryStateStore implements StateStore {
     deleteRun(runId: string): Promise<void>;
     getCheckpoint(runId: string, seq: number): Promise<StepCheckpoint | null>;
     saveCheckpoint(checkpoint: StepCheckpoint): Promise<void>;
-    listIncompleteRuns(): Promise<WorkflowRun[]>;
-    listPendingRuns(limit: number): Promise<WorkflowRun[]>;
-    listDueTimers(nowMs: number): Promise<WorkflowRun[]>;
+    listIncompleteRuns(namespace?: string): Promise<WorkflowRun[]>;
+    listPendingRuns(limit: number, namespace?: string): Promise<WorkflowRun[]>;
+    listDueTimers(nowMs: number, namespace?: string): Promise<WorkflowRun[]>;
     tryLockRun(runId: string, owner: string, leaseUntilMs: number, nowMs: number): Promise<boolean>;
     releaseRunLock(runId: string): Promise<void>;
     renewRunLock(runId: string, owner: string, leaseUntilMs: number): Promise<boolean>;

package/dist/index.js

@@ -1208,7 +1208,8 @@ function createWorkflowCtx(host, runId, compensations, workflow = "") {
       await store.putSignalWaiter({
         token: `child:${childId}`,
         runId,
-        seq
+        seq,
+        parallelGroup: group
       });
       if (!await store.getRun(childId)) host.startChild(name, inputs[i], childId);
       if (!cp) {
@@ -1440,6 +1441,14 @@ function isNewerVersion(a, b) {
   }) > 0;
 }
 __name(isNewerVersion, "isNewerVersion");
+var NamespaceMismatch = class NamespaceMismatch2 extends Error {
+  static {
+    __name(this, "NamespaceMismatch");
+  }
+  constructor() {
+    super("namespace-mismatch");
+  }
+};
 var WorkflowEngine = class {
   static {
     __name(this, "WorkflowEngine");
@@ -1450,6 +1459,7 @@ var WorkflowEngine = class {
   controlPlane;
   clock;
   instanceId;
+  namespace;
   leaseMs;
   maxRecoveryAttempts;
   remoteAdvanceSilenceMs;
@@ -1516,6 +1526,7 @@ var WorkflowEngine = class {
     this.admission = deps.admission ?? new InMemoryAdmissionBackend(this.clock);
     this.admission.onFreed?.((queue) => this.wakeQueueWaiters(queue));
     this.instanceId = deps.instanceId ?? globalThis.crypto.randomUUID();
+    this.namespace = deps.namespace ?? "default";
     this.leaseMs = deps.leaseMs ?? 3e4;
     this.maxRecoveryAttempts = deps.maxRecoveryAttempts;
     this.remoteAdvanceSilenceMs = deps.remoteAdvanceSilenceMs;
@@ -1836,6 +1847,7 @@ var WorkflowEngine = class {
       workflow: name,
       workflowVersion: registered.version,
       status: "pending",
+      namespace: this.namespace,
       input,
       tags,
       searchAttributes: opts?.searchAttributes,
@@ -1872,6 +1884,10 @@ var WorkflowEngine = class {
         error: run.error
       };
     }
+    if (run.namespace !== void 0 && run.namespace !== this.namespace) {
+      await this.store.releaseRunLock(runId);
+      throw new NamespaceMismatch();
+    }
     const registered = this.workflows.get(versionKey(run.workflow, run.workflowVersion)) ?? await this.findInheritedRegistration(run);
     if (!registered) {
       throw new Error(`workflow ${run.workflow}@${run.workflowVersion} is not registered \u2014 keep the prior version deployed so in-flight runs can drain (skew protection)`);
@@ -1990,11 +2006,13 @@ var WorkflowEngine = class {
       const inflight = [
         ...await this.store.listRuns({
           workflow: reg.name,
-          status: "running"
+          status: "running",
+          namespace: this.namespace
         }),
         ...await this.store.listRuns({
           workflow: reg.name,
-          status: "suspended"
+          status: "suspended",
+          namespace: this.namespace
         })
       ];
       for (const run of inflight) {
@@ -2024,7 +2042,7 @@ var WorkflowEngine = class {
   async recoverIncomplete(nowMs = this.clock()) {
     if (this.draining) return [];
     const results = [];
-    for (const run of await this.store.listIncompleteRuns()) {
+    for (const run of await this.store.listIncompleteRuns(this.namespace)) {
       const acquired = await this.store.tryLockRun(run.id, this.instanceId, nowMs + this.leaseMs, nowMs);
       if (!acquired) continue;
       const settled = await this.countRecovery(run);
@@ -2094,7 +2112,7 @@ var WorkflowEngine = class {
   * boot. A run still not due re-suspends cheaply without running new work.
   */
   async resumeDueTimers(nowMs = this.clock()) {
-    return this.resumeLeased(await this.store.listDueTimers(nowMs), nowMs);
+    return this.resumeLeased(await this.store.listDueTimers(nowMs, this.namespace), nowMs);
   }
   /**
   * Lease and execute one run by id — the worker side of dispatch. Acquires the recovery lease (so
@@ -2107,7 +2125,10 @@ var WorkflowEngine = class {
     const nowMs = this.clock();
     const acquired = await this.store.tryLockRun(runId, this.instanceId, nowMs + this.leaseMs, nowMs);
     if (!acquired) return null;
-    return this.resume(runId);
+    return this.resume(runId).catch((err) => {
+      if (err instanceof NamespaceMismatch) return null;
+      throw err;
+    });
   }
   /**
   * Re-enqueue a run for a worker to (re-)execute — the dispatch-model **retry**. Sets it back to
@@ -2153,7 +2174,7 @@ var WorkflowEngine = class {
   * {@link resumeDueTimers}.
   */
   async runPending(nowMs = this.clock()) {
-    return this.resumeLeased(await this.store.listPendingRuns(100), nowMs);
+    return this.resumeLeased(await this.store.listPendingRuns(100, this.namespace), nowMs);
   }
   /**
   * Resolve once `runId` reaches a settled state — terminal (completed/failed/cancelled/dead) or
@@ -2263,9 +2284,17 @@ var WorkflowEngine = class {
       seq: waiter.seq,
       name: `signal:${token}`,
       kind: "signal",
-      output: payload
+      output: payload,
+      // Carry the awaiting command's fan group (set when a `ctx.gather_children`/`ctx.all` fan-out
+      // registered this waiter) onto the resolving `signal:child:<id>` checkpoint, so the dashboard
+      // groups the child fan-out vertically instead of rendering it as a sequential chain. Undefined
+      // for an ordinary (non-fan) signal/child await.
+      parallelGroup: waiter.parallelGroup
     }));
-    return this.resume(waiter.runId);
+    return this.resume(waiter.runId).catch((err) => {
+      if (err instanceof NamespaceMismatch) return null;
+      throw err;
+    });
   }
   /**
   * Ensure a run exists for `runId`, then deliver a signal to it — atomically race-free thanks to
@@ -3030,7 +3059,12 @@ var WorkflowEngine = class {
         await this.store.putSignalWaiter({
           token: `child:${childId}`,
           runId: run.id,
-          seq: cmd.seq
+          seq: cmd.seq,
+          // A `ctx.gather_children`/`ctx.all` fan-out stamps every `startChild` in the fan with the same
+          // group. Thread it onto the waiter so the child's terminal `signal:child:<id>` checkpoint
+          // (written by engine.signal when the child notifies the parent) carries the group and the
+          // dashboard renders the fan as one parallel group. Undefined for a lone (non-fan) child.
+          parallelGroup: cmd.parallelGroup
         });
         if (!await this.store.getRun(childId)) {
           queueMicrotask(() => void this.start(cmd.workflow, cmd.input, childId).catch(() => void 0));
@@ -3419,7 +3453,10 @@ var WorkflowEngine = class {
       queueMs: startedAt.getTime() - cp.enqueuedAt.getTime(),
       durationMs: finishedAt.getTime() - startedAt.getTime()
     });
-    await this.resume(result.runId);
+    await this.resume(result.runId).catch((err) => {
+      if (err instanceof NamespaceMismatch) return null;
+      throw err;
+    });
   }
   /**
   * A slot freed on `queue` (a fleet-wide signal): resume this instance's runs blocked on it so they
@@ -3717,14 +3754,14 @@ var CodecStateStore = class {
       saveCheckpoint: /* @__PURE__ */ __name((cp) => tx.saveCheckpoint(this.encCp(cp)), "saveCheckpoint")
     }));
   }
-  async listIncompleteRuns() {
-    return (await this.inner.listIncompleteRuns()).map((r) => this.decRun(r));
+  async listIncompleteRuns(namespace) {
+    return (await this.inner.listIncompleteRuns(namespace)).map((r) => this.decRun(r));
   }
-  async listPendingRuns(limit) {
-    return (await this.inner.listPendingRuns(limit)).map((r) => this.decRun(r));
+  async listPendingRuns(limit, namespace) {
+    return (await this.inner.listPendingRuns(limit, namespace)).map((r) => this.decRun(r));
   }
-  async listDueTimers(nowMs) {
-    return (await this.inner.listDueTimers(nowMs)).map((r) => this.decRun(r));
+  async listDueTimers(nowMs, namespace) {
+    return (await this.inner.listDueTimers(nowMs, namespace)).map((r) => this.decRun(r));
   }
   tryLockRun(runId, owner, leaseUntilMs, nowMs) {
     return this.inner.tryLockRun(runId, owner, leaseUntilMs, nowMs);
@@ -4079,7 +4116,8 @@ var InMemoryStateStore = class {
   }
   async createRun(run) {
     this.runs.set(run.id, {
-      ...run
+      ...run,
+      namespace: run.namespace ?? "default"
     });
     this.reindexAttributes(run.id, run.searchAttributes);
   }
@@ -4120,24 +4158,24 @@ var InMemoryStateStore = class {
       ...checkpoint
     });
   }
-  async listIncompleteRuns() {
+  async listIncompleteRuns(namespace) {
     return [
       ...this.runs.values()
-    ].filter((r) => r.status === "running" || r.status === "cancelling").map((r) => ({
+    ].filter((r) => (r.status === "running" || r.status === "cancelling") && (namespace === void 0 || r.namespace === namespace)).map((r) => ({
       ...r
     }));
   }
-  async listPendingRuns(limit) {
+  async listPendingRuns(limit, namespace) {
     return [
       ...this.runs.values()
-    ].filter((r) => r.status === "pending").sort((a, b) => a.createdAt.getTime() - b.createdAt.getTime() || a.id.localeCompare(b.id)).slice(0, limit).map((r) => ({
+    ].filter((r) => r.status === "pending" && (namespace === void 0 || r.namespace === namespace)).sort((a, b) => a.createdAt.getTime() - b.createdAt.getTime() || a.id.localeCompare(b.id)).slice(0, limit).map((r) => ({
       ...r
     }));
   }
-  async listDueTimers(nowMs) {
+  async listDueTimers(nowMs, namespace) {
     return [
       ...this.runs.values()
-    ].filter((r) => r.status === "suspended" && r.wakeAt !== void 0 && r.wakeAt <= nowMs).map((r) => ({
+    ].filter((r) => r.status === "suspended" && r.wakeAt !== void 0 && r.wakeAt <= nowMs && (namespace === void 0 || r.namespace === namespace)).map((r) => ({
       ...r
     }));
   }
@@ -4252,6 +4290,7 @@ var InMemoryStateStore = class {
     if (query.status) runs = runs.filter((r) => r.status === query.status);
     if (query.statuses) runs = runs.filter((r) => query.statuses?.includes(r.status));
     if (query.tag) runs = runs.filter((r) => r.tags?.includes(query.tag));
+    if (query.namespace !== void 0) runs = runs.filter((r) => r.namespace === query.namespace);
     if (query.attributes?.length) {
       let candidates = null;
       for (const f of query.attributes) {