@workglow/task-graph 0.2.15 → 0.2.17

package/README.md

@@ -138,7 +138,8 @@ console.log(second); // { result: 60 }
 Tasks are the fundamental units of work. Each task:
 
 - Defines input/output schemas using JSON Schema (from `@workglow/util`), TypeBox, or Zod
-- Implements `execute()` for main logic or `executeReactive()` for UI updates
+- Implements `execute()` for main logic; optionally `executePreview()` for fast UI previews
+  (called only by `runPreview()`, never as part of `run()`)
 - Has a unique type identifier and category
 - Can be cached based on inputs
 - Emits lifecycle events
@@ -1109,9 +1110,13 @@ Format is also used on array types, e.g., `format: 'Float64Array'` on arrays con
 
 #### Task
 
-- `run(overrides?)`: Execute the task with optional input overrides
-- `runReactive(overrides?)`: Execute in reactive mode
+- `run(overrides?)`: Execute the task with optional input overrides (calls `execute()` / `executeStream()`)
+- `runPreview(overrides?)`: Run the preview-only path (calls `executePreview()` only)
 - `abort()`: Cancel execution
+
+`run()` and `runPreview()` are strictly orthogonal: `run()` never invokes `executePreview()`,
+and `runPreview()` never invokes `execute()` or `executeStream()`. There is no post-execute
+overlay; cache hits during `run()` return the cached value verbatim.
 - `setInput(input)`: Set input values
 - `validateInput(input)`: Validate input against schema
 

package/dist/browser.js

@@ -1354,7 +1354,7 @@ function hasRunConfig(i) {
 
 class TaskRunner {
   running = false;
-  reactiveRunning = false;
+  previewRunning = false;
   task;
   abortController;
   outputCache;
@@ -1372,6 +1372,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();
@@ -1408,9 +1412,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;
           }
         }
       }
@@ -1432,7 +1435,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;
     }
@@ -1445,18 +1448,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;
     }
@@ -1490,11 +1496,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());
@@ -1613,8 +1618,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)
@@ -1677,8 +1681,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) {
@@ -1710,8 +1714,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)
@@ -1730,8 +1734,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)
@@ -1778,8 +1782,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;
@@ -1827,8 +1831,8 @@ class Task {
     }
     return;
   }
-  async executeReactive(_input, output, _context) {
-    return output;
+  async executePreview(_input, _context) {
+    return;
   }
   _runner;
   get runner() {
@@ -1840,8 +1844,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();
@@ -2802,9 +2806,9 @@ var GRAPH_RESULT_ARRAY = "GRAPH_RESULT_ARRAY";
 
 class TaskGraphRunner {
   processScheduler;
-  reactiveScheduler;
+  previewScheduler;
   running = false;
-  reactiveRunning = false;
+  previewRunning = false;
   graph;
   outputCache;
   accumulateLeafOutputs = true;
@@ -2818,9 +2822,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);
@@ -2888,16 +2892,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
         }
@@ -2907,7 +2911,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();
@@ -2916,13 +2920,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,
@@ -2931,7 +2935,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({
@@ -2942,35 +2946,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
@@ -3381,7 +3385,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;
@@ -3455,9 +3459,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;
@@ -3468,8 +3472,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) {
@@ -3488,8 +3492,8 @@ class TaskGraphRunner {
     }
     this.graph.emit("complete");
   }
-  async handleCompleteReactive() {
-    this.reactiveRunning = false;
+  async handleCompletePreview() {
+    this.previewRunning = false;
   }
   async handleError(error) {
     this.clearGraphTimeout();
@@ -3508,8 +3512,8 @@ class TaskGraphRunner {
     }
     this.graph.emit("error", error);
   }
-  async handleErrorReactive() {
-    this.reactiveRunning = false;
+  async handleErrorPreview() {
+    this.previewRunning = false;
   }
   async handleAbort() {
     this.clearGraphTimeout();
@@ -3528,8 +3532,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) => {
@@ -3572,8 +3576,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
     });
@@ -3594,15 +3598,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;
   }
 }
 
@@ -4030,8 +4037,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);
@@ -5921,9 +5928,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();
@@ -5943,7 +5949,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;
@@ -5985,7 +5991,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;
@@ -6213,15 +6219,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;
@@ -6888,9 +6892,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 });
   }
 }
 
@@ -8934,4 +8937,4 @@ export {
   BROWSER_GRANTS
 };
 
-//# debugId=B2CBA2397CBCF51264756E2164756E21
+//# debugId=8B5B3A49FDB4C28B64756E2164756E21