@dudousxd/nestjs-durable-core 0.42.0 → 0.43.0

package/dist/index.d.cts

@@ -1636,6 +1636,29 @@ declare class WorkflowEngine {
         executionTimeout?: string | number;
         validateInput?: (input: unknown) => void | Promise<void>;
     }): void;
+    /**
+     * The convenience form of {@link registerRemote}: register a workflow whose body runs on a worker
+     * `group` (e.g. the Python `durable-worker`, or a separate TS worker), without hand-building a
+     * {@link RemoteWorkflowExecutor}. It wires the standard broker executor — a `RemoteWorkflowExecutor`
+     * over the engine's own transport, dispatching to `opts.group` — for you, so you write
+     * `engine.remote('processing', { group: 'processing' })` instead of
+     * `engine.registerRemote('processing', '1', { group: 'processing', executor: new RemoteWorkflowExecutor(transport, 'processing') })`.
+     *
+     * Defaults the version to `'1'`. All the other {@link registerRemote} options
+     * (`tags` / `singleton` / `executionTimeout` / `validateInput`) pass straight through. Reach for the
+     * low-level {@link registerRemote} when you need a custom {@link WorkflowExecutor} (a different
+     * transport, a fixed `timeoutMs`, a polyglot stub) — `remote()` is the standard wiring on the rails.
+     */
+    remote(name: string, opts: {
+        /** Worker group this workflow's turns are dispatched to (also the executor's target group). */
+        group: string;
+        /** Workflow version. Defaults to `'1'`. */
+        version?: string;
+        tags?: string[];
+        singleton?: SingletonConfig;
+        executionTimeout?: string | number;
+        validateInput?: (input: unknown) => void | Promise<void>;
+    }): void;
     /**
      * Register a flow-control queue referenced by `ctx.call(step, input, { queue })`. Caps concurrent
      * in-flight steps and/or the admission rate; blocked calls re-suspend and retry, so the limit is

package/dist/index.d.ts

@@ -1636,6 +1636,29 @@ declare class WorkflowEngine {
         executionTimeout?: string | number;
         validateInput?: (input: unknown) => void | Promise<void>;
     }): void;
+    /**
+     * The convenience form of {@link registerRemote}: register a workflow whose body runs on a worker
+     * `group` (e.g. the Python `durable-worker`, or a separate TS worker), without hand-building a
+     * {@link RemoteWorkflowExecutor}. It wires the standard broker executor — a `RemoteWorkflowExecutor`
+     * over the engine's own transport, dispatching to `opts.group` — for you, so you write
+     * `engine.remote('processing', { group: 'processing' })` instead of
+     * `engine.registerRemote('processing', '1', { group: 'processing', executor: new RemoteWorkflowExecutor(transport, 'processing') })`.
+     *
+     * Defaults the version to `'1'`. All the other {@link registerRemote} options
+     * (`tags` / `singleton` / `executionTimeout` / `validateInput`) pass straight through. Reach for the
+     * low-level {@link registerRemote} when you need a custom {@link WorkflowExecutor} (a different
+     * transport, a fixed `timeoutMs`, a polyglot stub) — `remote()` is the standard wiring on the rails.
+     */
+    remote(name: string, opts: {
+        /** Worker group this workflow's turns are dispatched to (also the executor's target group). */
+        group: string;
+        /** Workflow version. Defaults to `'1'`. */
+        version?: string;
+        tags?: string[];
+        singleton?: SingletonConfig;
+        executionTimeout?: string | number;
+        validateInput?: (input: unknown) => void | Promise<void>;
+    }): void;
     /**
      * Register a flow-control queue referenced by `ctx.call(step, input, { queue })`. Caps concurrent
      * in-flight steps and/or the admission rate; blocked calls re-suspend and retry, so the limit is

package/dist/index.js

@@ -700,6 +700,70 @@ function eventMatches(payload, match) {
 }
 __name(eventMatches, "eventMatches");
 
+// src/remote-workflow-executor.ts
+var taskCounter = 0;
+var RemoteWorkflowExecutor = class {
+  static {
+    __name(this, "RemoteWorkflowExecutor");
+  }
+  transport;
+  group;
+  opts;
+  pending = /* @__PURE__ */ new Map();
+  subscribed = false;
+  constructor(transport, group, opts = {}) {
+    this.transport = transport;
+    this.group = group;
+    this.opts = opts;
+  }
+  ensureSubscribed() {
+    if (this.subscribed) return;
+    if (!this.transport.onDecision) {
+      throw new Error("transport does not support workflow decisions (onDecision)");
+    }
+    this.subscribed = true;
+    this.transport.onDecision(async (decision) => {
+      const resolve = this.pending.get(decision.taskId);
+      if (resolve) {
+        this.pending.delete(decision.taskId);
+        resolve(decision);
+      }
+    });
+  }
+  async advance(run, history) {
+    if (!this.transport.dispatchWorkflowTask) {
+      throw new Error("transport does not support workflow tasks (dispatchWorkflowTask)");
+    }
+    this.ensureSubscribed();
+    taskCounter += 1;
+    const taskId = `${run.id}:wf:${taskCounter}`;
+    const task = {
+      taskId,
+      runId: run.id,
+      workflow: run.workflow,
+      workflowVersion: run.workflowVersion,
+      input: run.input,
+      history,
+      group: this.group,
+      priority: run.priority,
+      attempt: 1
+    };
+    const decision = new Promise((resolve, reject) => {
+      this.pending.set(taskId, resolve);
+      const { timeoutMs } = this.opts;
+      if (timeoutMs) {
+        const timer = setTimeout(() => {
+          this.pending.delete(taskId);
+          reject(new RemoteWorkflowTimeout(taskId, timeoutMs));
+        }, timeoutMs);
+        timer.unref?.();
+      }
+    });
+    await this.transport.dispatchWorkflowTask(task);
+    return decision;
+  }
+};
+
 // src/singleton-gate.ts
 var SINGLETON_RETRY_MS = 1e3;
 var SINGLETON_RETRY_JITTER_MS = 250;
@@ -801,6 +865,19 @@ var TransportPool = class {
   get size() {
     return this.transports.length;
   }
+  /**
+  * The primary (first) transport — the one `dispatch` prefers when no `preferId` is pinned. A
+  * {@link RemoteWorkflowExecutor} built by `engine.remote()` rides it (it needs a single
+  * `dispatchWorkflowTask`/`onDecision` Transport, not the whole failover pool). Throws if the pool
+  * is empty — there is nothing to dispatch a remote workflow over.
+  */
+  get primary() {
+    const first = this.transports[0];
+    if (!first) {
+      throw new Error("no transport configured \u2014 engine.remote() needs a transport (or transports)");
+    }
+    return first.transport;
+  }
   /** Register the engine's result/heartbeat/step-event handlers on EVERY transport — a result can come
   *  back on whichever one delivered the task, so failover stays symmetric. `onStepEvent` is wired only
   *  on transports that carry streamed workflow step lifecycle (BullMQ); others simply skip it. */
@@ -1720,6 +1797,28 @@ var WorkflowEngine = class {
     if (!current || isNewerVersion(version, current.version)) this.latest.set(name, registered);
   }
   /**
+  * The convenience form of {@link registerRemote}: register a workflow whose body runs on a worker
+  * `group` (e.g. the Python `durable-worker`, or a separate TS worker), without hand-building a
+  * {@link RemoteWorkflowExecutor}. It wires the standard broker executor — a `RemoteWorkflowExecutor`
+  * over the engine's own transport, dispatching to `opts.group` — for you, so you write
+  * `engine.remote('processing', { group: 'processing' })` instead of
+  * `engine.registerRemote('processing', '1', { group: 'processing', executor: new RemoteWorkflowExecutor(transport, 'processing') })`.
+  *
+  * Defaults the version to `'1'`. All the other {@link registerRemote} options
+  * (`tags` / `singleton` / `executionTimeout` / `validateInput`) pass straight through. Reach for the
+  * low-level {@link registerRemote} when you need a custom {@link WorkflowExecutor} (a different
+  * transport, a fixed `timeoutMs`, a polyglot stub) — `remote()` is the standard wiring on the rails.
+  */
+  remote(name, opts) {
+    const { group, version, ...rest } = opts;
+    const executor = new RemoteWorkflowExecutor(this.pool.primary, group);
+    this.registerRemote(name, version ?? "1", {
+      group,
+      executor,
+      ...rest
+    });
+  }
+  /**
   * Register a flow-control queue referenced by `ctx.call(step, input, { queue })`. Caps concurrent
   * in-flight steps and/or the admission rate; blocked calls re-suspend and retry, so the limit is
   * durable. Per engine instance (see {@link QueueConfig}). Registering the same name replaces it.
@@ -3615,70 +3714,6 @@ function remoteStep(config) {
 }
 __name(remoteStep, "remoteStep");
 
-// src/remote-workflow-executor.ts
-var taskCounter = 0;
-var RemoteWorkflowExecutor = class {
-  static {
-    __name(this, "RemoteWorkflowExecutor");
-  }
-  transport;
-  group;
-  opts;
-  pending = /* @__PURE__ */ new Map();
-  subscribed = false;
-  constructor(transport, group, opts = {}) {
-    this.transport = transport;
-    this.group = group;
-    this.opts = opts;
-  }
-  ensureSubscribed() {
-    if (this.subscribed) return;
-    if (!this.transport.onDecision) {
-      throw new Error("transport does not support workflow decisions (onDecision)");
-    }
-    this.subscribed = true;
-    this.transport.onDecision(async (decision) => {
-      const resolve = this.pending.get(decision.taskId);
-      if (resolve) {
-        this.pending.delete(decision.taskId);
-        resolve(decision);
-      }
-    });
-  }
-  async advance(run, history) {
-    if (!this.transport.dispatchWorkflowTask) {
-      throw new Error("transport does not support workflow tasks (dispatchWorkflowTask)");
-    }
-    this.ensureSubscribed();
-    taskCounter += 1;
-    const taskId = `${run.id}:wf:${taskCounter}`;
-    const task = {
-      taskId,
-      runId: run.id,
-      workflow: run.workflow,
-      workflowVersion: run.workflowVersion,
-      input: run.input,
-      history,
-      group: this.group,
-      priority: run.priority,
-      attempt: 1
-    };
-    const decision = new Promise((resolve, reject) => {
-      this.pending.set(taskId, resolve);
-      const { timeoutMs } = this.opts;
-      if (timeoutMs) {
-        const timer = setTimeout(() => {
-          this.pending.delete(taskId);
-          reject(new RemoteWorkflowTimeout(taskId, timeoutMs));
-        }, timeoutMs);
-        timer.unref?.();
-      }
-    });
-    await this.transport.dispatchWorkflowTask(task);
-    return decision;
-  }
-};
-
 // src/codec-state-store.ts
 var CodecStateStore = class {
   static {