@workglow/task-graph 0.2.16 → 0.2.17

package/dist/bun.js

@@ -1355,7 +1355,7 @@ function hasRunConfig(i) {
 
 class TaskRunner {
   running = false;
-  reactiveRunning = false;
+  previewRunning = false;
   task;
   abortController;
   outputCache;
@@ -1373,6 +1373,10 @@ class TaskRunner {
   }
   async run(overrides = {}, config = {}) {
     await this.handleStart(config);
+    const proto = Object.getPrototypeOf(this.task);
+    if (proto.execute === Task.prototype.execute && typeof proto.executeStream !== "function" && proto.executePreview !== Task.prototype.executePreview) {
+      throw new TaskConfigurationError(`Task "${this.task.type}" implements only executePreview() and cannot be run via run(). ` + `After the run/runPreview split, run() requires execute() (or executeStream()). ` + `See docs/technical/02-dual-mode-execution.md.`);
+    }
     try {
       this.task.setInput(overrides);
       const configSchema = this.task.constructor.configSchema();
@@ -1409,9 +1413,8 @@ class TaskRunner {
             this.task.emit("stream_start");
             this.task.emit("stream_chunk", { type: "finish", data: outputs });
             this.task.emit("stream_end", outputs);
-            this.task.runOutputData = await this.executeTaskReactive(inputs, outputs);
           } else {
-            this.task.runOutputData = await this.executeTaskReactive(inputs, outputs);
+            this.task.runOutputData = outputs;
           }
         }
       }
@@ -1433,7 +1436,7 @@ class TaskRunner {
       throw this.task.error instanceof TaskTimeoutError ? this.task.error : err;
     }
   }
-  async runReactive(overrides = {}) {
+  async runPreview(overrides = {}) {
     if (this.task.status === TaskStatus.PROCESSING) {
       return this.task.runOutputData;
     }
@@ -1446,18 +1449,21 @@ class TaskRunner {
     }
     const schema = this.task.constructor.inputSchema();
     this.task.runInputData = await resolveSchemaInputs(this.task.runInputData, schema, { registry: this.registry });
-    await this.handleStartReactive();
+    await this.handleStartPreview();
     try {
       const inputs = this.task.runInputData;
       const isValid = await this.task.validateInput(inputs);
       if (!isValid) {
         throw new TaskInvalidInputError("Invalid input data");
       }
-      const resultReactive = await this.executeTaskReactive(inputs, this.task.runOutputData);
-      this.task.runOutputData = resultReactive;
-      await this.handleCompleteReactive();
+      const resultPreview = await this.executeTaskPreview(inputs);
+      if (resultPreview !== undefined) {
+        this.task.runOutputData = resultPreview;
+      }
+      await this.handleCompletePreview();
     } catch (err) {
-      await this.handleErrorReactive();
+      getLogger().debug("runPreview failed", { taskId: this.task.config?.id, error: err });
+      await this.handleErrorPreview();
     } finally {
       return this.task.runOutputData;
     }
@@ -1491,11 +1497,10 @@ class TaskRunner {
       registry: this.registry,
       resourceScope: this.resourceScope
     });
-    return await this.executeTaskReactive(input, result || {});
+    return result;
   }
-  async executeTaskReactive(input, output) {
-    const reactiveResult = await this.task.executeReactive(input, output, { own: this.own });
-    return Object.assign({}, output, reactiveResult ?? {});
+  async executeTaskPreview(input) {
+    return this.task.executePreview?.(input, { own: this.own });
   }
   async executeStreamingTask(input) {
     const streamMode = getOutputStreamMode(this.task.outputSchema());
@@ -1614,8 +1619,7 @@ class TaskRunner {
       this.task.runOutputData = finalOutput;
     }
     this.task.emit("stream_end", this.task.runOutputData);
-    const reactiveResult = await this.executeTaskReactive(input, this.task.runOutputData || {});
-    return reactiveResult;
+    return this.task.runOutputData;
   }
   async handleStart(config = {}) {
     if (this.task.status === TaskStatus.PROCESSING)
@@ -1678,8 +1682,8 @@ class TaskRunner {
     this.task.emit("status", this.task.status);
   }
   updateProgress = async (_task, _progress, _message, ..._args) => {};
-  async handleStartReactive() {
-    this.reactiveRunning = true;
+  async handleStartPreview() {
+    this.previewRunning = true;
   }
   clearTimeoutTimer() {
     if (this.timeoutTimer !== undefined) {
@@ -1711,8 +1715,8 @@ class TaskRunner {
     this.task.emit("abort", this.task.error);
     this.task.emit("status", this.task.status);
   }
-  async handleAbortReactive() {
-    this.reactiveRunning = false;
+  async handleAbortPreview() {
+    this.previewRunning = false;
   }
   async handleComplete() {
     if (this.task.status === TaskStatus.COMPLETED)
@@ -1731,8 +1735,8 @@ class TaskRunner {
     this.task.emit("complete");
     this.task.emit("status", this.task.status);
   }
-  async handleCompleteReactive() {
-    this.reactiveRunning = false;
+  async handleCompletePreview() {
+    this.previewRunning = false;
   }
   async handleDisable() {
     if (this.task.status === TaskStatus.DISABLED)
@@ -1779,8 +1783,8 @@ class TaskRunner {
     this.task.emit("error", this.task.error);
     this.task.emit("status", this.task.status);
   }
-  async handleErrorReactive() {
-    this.reactiveRunning = false;
+  async handleErrorPreview() {
+    this.previewRunning = false;
   }
   async handleProgress(progress, message, ...args) {
     this.task.progress = progress;
@@ -1828,8 +1832,8 @@ class Task {
     }
     return;
   }
-  async executeReactive(_input, output, _context) {
-    return output;
+  async executePreview(_input, _context) {
+    return;
   }
   _runner;
   get runner() {
@@ -1841,8 +1845,8 @@ class Task {
   async run(overrides = {}, runConfig = {}) {
     return this.runner.run(overrides, { ...this.runConfig, ...runConfig });
   }
-  async runReactive(overrides = {}) {
-    return this.runner.runReactive(overrides);
+  async runPreview(overrides = {}) {
+    return this.runner.runPreview(overrides);
   }
   abort() {
     this.runner.abort();
@@ -2803,9 +2807,9 @@ var GRAPH_RESULT_ARRAY = "GRAPH_RESULT_ARRAY";
 
 class TaskGraphRunner {
   processScheduler;
-  reactiveScheduler;
+  previewScheduler;
   running = false;
-  reactiveRunning = false;
+  previewRunning = false;
   graph;
   outputCache;
   accumulateLeafOutputs = true;
@@ -2819,9 +2823,9 @@ class TaskGraphRunner {
   graphTimeoutTimer;
   pendingGraphTimeoutError;
   activeEnforcer;
-  constructor(graph, outputCache, processScheduler = new DependencyBasedScheduler(graph), reactiveScheduler = new TopologicalScheduler(graph)) {
+  constructor(graph, outputCache, processScheduler = new DependencyBasedScheduler(graph), previewScheduler = new TopologicalScheduler(graph)) {
     this.processScheduler = processScheduler;
-    this.reactiveScheduler = reactiveScheduler;
+    this.previewScheduler = previewScheduler;
     this.graph = graph;
     graph.outputCache = outputCache;
     this.handleProgress = this.handleProgress.bind(this);
@@ -2889,16 +2893,16 @@ class TaskGraphRunner {
     await this.handleComplete();
     return this.filterLeafResults(results);
   }
-  async runGraphReactive(input = {}, config) {
-    await this.handleStartReactive(config);
+  async runGraphPreview(input = {}, config) {
+    await this.handleStartPreview(config);
     const telemetry = getTelemetryProvider2();
     const telemetryEnabled = telemetry.isEnabled;
-    const reactiveRunId = telemetryEnabled ? uuid43() : "";
-    let reactiveSpan;
+    const previewRunId = telemetryEnabled ? uuid43() : "";
+    let previewSpan;
     if (telemetryEnabled) {
-      reactiveSpan = telemetry.startSpan("workglow.graph.runReactive", {
+      previewSpan = telemetry.startSpan("workglow.graph.runPreview", {
         attributes: {
-          "workglow.graph.reactive.run_id": reactiveRunId,
+          "workglow.graph.preview.run_id": previewRunId,
           "workglow.graph.task_count": this.graph.getTasks().length,
           "workglow.graph.dataflow_count": this.graph.getDataflows().length
         }
@@ -2908,7 +2912,7 @@ class TaskGraphRunner {
     const taskTimings = [];
     const results = [];
     try {
-      for await (const task of this.reactiveScheduler.tasks()) {
+      for await (const task of this.previewScheduler.tasks()) {
         const isRootTask = this.graph.getSourceDataflows(task.id).length === 0;
         if (task.status === TaskStatus.PENDING) {
           task.resetInputData();
@@ -2917,13 +2921,13 @@ class TaskGraphRunner {
         const taskInput = isRootTask ? input : {};
         if (telemetryEnabled) {
           const taskType = String(task.constructor.runtype || task.constructor.type || "?");
-          const tReactive = performance.now();
-          const taskResult = await task.runReactive(taskInput);
-          const runReactiveMs = performance.now() - tReactive;
+          const tPreview = performance.now();
+          const taskResult = await task.runPreview(taskInput);
+          const runPreviewMs = performance.now() - tPreview;
           const tPush = performance.now();
           await this.pushOutputFromNodeToEdges(task, taskResult);
           const pushOutputMs = performance.now() - tPush;
-          taskTimings.push({ id: task.id, type: taskType, runReactiveMs, pushOutputMs });
+          taskTimings.push({ id: task.id, type: taskType, runPreviewMs, pushOutputMs });
           if (this.graph.getTargetDataflows(task.id).length === 0) {
             results.push({
               id: task.id,
@@ -2932,7 +2936,7 @@ class TaskGraphRunner {
             });
           }
         } else {
-          const taskResult = await task.runReactive(taskInput);
+          const taskResult = await task.runPreview(taskInput);
           await this.pushOutputFromNodeToEdges(task, taskResult);
           if (this.graph.getTargetDataflows(task.id).length === 0) {
             results.push({
@@ -2943,35 +2947,35 @@ class TaskGraphRunner {
           }
         }
       }
-      await this.handleCompleteReactive();
-      if (reactiveSpan) {
+      await this.handleCompletePreview();
+      if (previewSpan) {
         const totalMs = performance.now() - t0;
-        reactiveSpan.setAttributes({
-          "workglow.graph.reactive.duration_ms": Math.round(totalMs * 1000) / 1000,
-          "workglow.graph.reactive.tasks_executed": taskTimings.length
+        previewSpan.setAttributes({
+          "workglow.graph.preview.duration_ms": Math.round(totalMs * 1000) / 1000,
+          "workglow.graph.preview.tasks_executed": taskTimings.length
         });
-        reactiveSpan.setStatus(SpanStatusCode2.OK);
-        reactiveSpan.end();
-        getLogger3().debug("task graph runReactive timings", {
-          reactiveRunId,
+        previewSpan.setStatus(SpanStatusCode2.OK);
+        previewSpan.end();
+        getLogger3().debug("task graph runPreview timings", {
+          previewRunId,
           totalMs: Math.round(totalMs * 1000) / 1000,
           taskTimings
         });
       }
       return this.filterLeafResults(results);
     } catch (error) {
-      await this.handleErrorReactive();
-      if (reactiveSpan) {
+      await this.handleErrorPreview();
+      if (previewSpan) {
         const totalMs = performance.now() - t0;
         const message = error instanceof Error ? error.message : String(error);
-        reactiveSpan.setAttributes({
-          "workglow.graph.reactive.duration_ms": Math.round(totalMs * 1000) / 1000,
-          "workglow.graph.reactive.tasks_executed": taskTimings.length
+        previewSpan.setAttributes({
+          "workglow.graph.preview.duration_ms": Math.round(totalMs * 1000) / 1000,
+          "workglow.graph.preview.tasks_executed": taskTimings.length
         });
-        reactiveSpan.setStatus(SpanStatusCode2.ERROR, message);
-        reactiveSpan.end();
-        getLogger3().debug("task graph runReactive failed", {
-          reactiveRunId,
+        previewSpan.setStatus(SpanStatusCode2.ERROR, message);
+        previewSpan.end();
+        getLogger3().debug("task graph runPreview failed", {
+          previewRunId,
           totalMs: Math.round(totalMs * 1000) / 1000,
           taskTimings,
           error
@@ -3382,7 +3386,7 @@ class TaskGraphRunner {
       }
       this.graph.outputCache = this.outputCache;
     }
-    if (this.running || this.reactiveRunning) {
+    if (this.running || this.previewRunning) {
       throw new TaskConfigurationError("Graph is already running");
     }
     this.running = true;
@@ -3456,9 +3460,9 @@ class TaskGraphRunner {
     }
     this.graph.emit("start");
   }
-  async handleStartReactive(config) {
-    if (this.reactiveRunning) {
-      throw new TaskConfigurationError("Graph is already running reactively");
+  async handleStartPreview(config) {
+    if (this.previewRunning) {
+      throw new TaskConfigurationError("Graph is already running in preview");
     }
     if (config?.registry !== undefined) {
       this.registry = config.registry;
@@ -3469,8 +3473,8 @@ class TaskGraphRunner {
         throw new TaskConfigurationError(`Graph has ${taskCount} tasks, exceeding the limit of ${config.maxTasks}`);
       }
     }
-    this.reactiveScheduler.reset();
-    this.reactiveRunning = true;
+    this.previewScheduler.reset();
+    this.previewRunning = true;
   }
   clearGraphTimeout() {
     if (this.graphTimeoutTimer !== undefined) {
@@ -3489,8 +3493,8 @@ class TaskGraphRunner {
     }
     this.graph.emit("complete");
   }
-  async handleCompleteReactive() {
-    this.reactiveRunning = false;
+  async handleCompletePreview() {
+    this.previewRunning = false;
   }
   async handleError(error) {
     this.clearGraphTimeout();
@@ -3509,8 +3513,8 @@ class TaskGraphRunner {
     }
     this.graph.emit("error", error);
   }
-  async handleErrorReactive() {
-    this.reactiveRunning = false;
+  async handleErrorPreview() {
+    this.previewRunning = false;
   }
   async handleAbort() {
     this.clearGraphTimeout();
@@ -3529,8 +3533,8 @@ class TaskGraphRunner {
     }
     this.graph.emit("abort");
   }
-  async handleAbortReactive() {
-    this.reactiveRunning = false;
+  async handleAbortPreview() {
+    this.previewRunning = false;
   }
   async handleDisable() {
     await Promise.allSettled(this.graph.getTasks().map(async (task) => {
@@ -3573,8 +3577,8 @@ class GraphAsTaskRunner extends TaskRunner {
     unsubscribe();
     return results;
   }
-  async executeTaskChildrenReactive() {
-    return this.task.subGraph.runReactive(this.task.runInputData, {
+  async executeTaskChildrenPreview() {
+    return this.task.subGraph.runPreview(this.task.runInputData, {
       registry: this.registry,
       resourceScope: this.resourceScope
     });
@@ -3595,15 +3599,18 @@ class GraphAsTaskRunner extends TaskRunner {
     }
     return this.task.runOutputData;
   }
-  async executeTaskReactive(input, output) {
+  async executeTaskPreview(input) {
     if (this.task.hasChildren()) {
-      const reactiveResults = await this.executeTaskChildrenReactive();
-      this.task.runOutputData = this.task.subGraph.mergeExecuteOutputsToRunOutput(reactiveResults, this.task.compoundMerge);
+      const previewResults = await this.executeTaskChildrenPreview();
+      this.task.runOutputData = this.task.subGraph.mergeExecuteOutputsToRunOutput(previewResults, this.task.compoundMerge);
+      return this.task.runOutputData;
     } else {
-      const reactiveResults = await super.executeTaskReactive(input, output);
-      this.task.runOutputData = Object.assign({}, output, reactiveResults ?? {});
+      const previewResult = await super.executeTaskPreview(input);
+      if (previewResult !== undefined) {
+        this.task.runOutputData = previewResult;
+      }
+      return this.task.runOutputData;
     }
-    return this.task.runOutputData;
   }
 }
 
@@ -4031,8 +4038,8 @@ class TaskGraph {
       resourceScope: config?.resourceScope
     });
   }
-  runReactive(input = {}, config = {}) {
-    return this.runner.runGraphReactive(input, config);
+  runPreview(input = {}, config = {}) {
+    return this.runner.runGraphPreview(input, config);
   }
   mergeExecuteOutputsToRunOutput(results, compoundMerge) {
     return this.runner.mergeExecuteOutputsToRunOutput(results, compoundMerge);
@@ -5922,9 +5929,8 @@ class FallbackTaskRunner extends GraphAsTaskRunner {
     }
     return this.executeTaskFallback(input);
   }
-  async executeTaskReactive(input, output) {
-    const reactiveResult = await this.task.executeReactive(input, output, { own: this.own });
-    return Object.assign({}, output, reactiveResult ?? {});
+  async executeTaskPreview(input) {
+    return this.task.executePreview?.(input, { own: this.own });
   }
   async executeTaskFallback(input) {
     const tasks = this.task.subGraph.getTasks();
@@ -5944,7 +5950,7 @@ class FallbackTaskRunner extends GraphAsTaskRunner {
         this.resetTask(alternativeTask);
         const result = await alternativeTask.run(input);
         await this.handleProgress(100, `Alternative ${attemptNumber}/${totalAttempts} succeeded: ${alternativeTask.type}`);
-        return await this.executeTaskReactive(input, result);
+        return result;
       } catch (error) {
         if (error instanceof TaskAbortedError && !(error instanceof TaskTimeoutError)) {
           throw error;
@@ -5986,7 +5992,7 @@ class FallbackTaskRunner extends GraphAsTaskRunner {
           });
           const mergedOutput = this.task.subGraph.mergeExecuteOutputsToRunOutput(results, this.task.compoundMerge);
           await this.handleProgress(100, `Data alternative ${attemptNumber}/${totalAttempts} succeeded`);
-          return await this.executeTaskReactive(input, mergedOutput);
+          return mergedOutput;
         } catch (error) {
           if (error instanceof TaskAbortedError && !(error instanceof TaskTimeoutError)) {
             throw error;
@@ -6214,15 +6220,13 @@ class IteratorTaskRunner extends GraphAsTaskRunner {
       analysis = { ...analysis, iterationCount: maxIterations };
     }
     if (analysis.iterationCount === 0) {
-      const emptyResult = this.task.getEmptyResult();
-      return this.executeTaskReactive(input, emptyResult);
+      return this.task.getEmptyResult();
     }
     const result = this.task.isReduceTask() ? await this.executeReduceIterations(analysis) : await this.executeCollectIterations(analysis);
-    return this.executeTaskReactive(input, result);
+    return result;
   }
-  async executeTaskReactive(input, output) {
-    const reactiveResult = await this.task.executeReactive(input, output, { own: this.own });
-    return Object.assign({}, output, reactiveResult ?? {});
+  async executeTaskPreview(input) {
+    return this.task.executePreview?.(input, { own: this.own });
   }
   async executeCollectIterations(analysis) {
     const iterationCount = analysis.iterationCount;
@@ -6889,9 +6893,8 @@ class WhileTaskRunner extends GraphAsTaskRunner {
     });
     return result;
   }
-  async executeTaskReactive(input, output) {
-    const reactiveResult = await this.task.executeReactive(input, output, { own: this.own });
-    return Object.assign({}, output, reactiveResult ?? {});
+  async executeTaskPreview(input) {
+    return this.task.executePreview?.(input, { own: this.own });
   }
 }
 
@@ -8298,4 +8301,4 @@ export {
   BROWSER_GRANTS
 };
 
-//# debugId=2328438A94292C4964756E2164756E21
+//# debugId=6F0C663FBE6F199E64756E2164756E21