@bian-womp/spark-graph 0.2.46 → 0.2.48

package/lib/cjs/index.cjs

@@ -566,7 +566,7 @@ class GraphRuntime {
         if (!this.paused) {
             // Only schedule if all inbound inputs are present (or there are none)
             if (anyChanged && this.allInboundHaveValue(nodeId))
-                this.scheduleInputsChanged(nodeId);
+                this.scheduleInputsChangedInternal(nodeId);
             // Recompute dynamic handles for this node when its direct inputs change
             if (anyChanged)
                 this.scheduleRecomputeHandles(nodeId);
@@ -639,7 +639,31 @@ class GraphRuntime {
             },
         };
     }
-    scheduleInputsChanged(nodeId) {
+    createExecutionContext(nodeId, node, inputs, runId, abortSignal, options) {
+        const emitHandler = options?.emitHandler ??
+            ((handle, value) => this.propagate(nodeId, handle, value));
+        const reportProgress = options?.reportProgress ??
+            ((p) => {
+                node.stats.progress = Math.max(0, Math.min(1, Number(p) || 0));
+            });
+        return {
+            state: node.state,
+            setState: (next) => Object.assign(node.state, next),
+            emit: emitHandler,
+            invalidateDownstream: () => this.invalidateDownstreamInternal(nodeId),
+            scheduleInputsChanged: () => {
+                if (this.allInboundHaveValue(nodeId)) {
+                    this.scheduleInputsChangedInternal(nodeId);
+                }
+            },
+            getInput: (handle) => inputs[handle],
+            environment: this.environment,
+            runId,
+            abortSignal,
+            reportProgress,
+        };
+    }
+    scheduleInputsChangedInternal(nodeId) {
         const node = this.nodes.get(nodeId);
         if (!node)
             return;
@@ -681,24 +705,13 @@ class GraphRuntime {
             if (policy.timeoutMs && policy.timeoutMs > 0) {
                 timeoutId = setTimeout(() => controller.abort("timeout"), policy.timeoutMs);
             }
-            const ctx = {
-                state: node.state,
-                environment: this.environment,
-                runId,
-                abortSignal: controller.signal,
-                setState: (next) => Object.assign(node.state, next),
-                emit: (handle, value) => {
+            const ctx = this.createExecutionContext(nodeId, node, capturedInputs, runId, controller.signal, {
+                emitHandler: (handle, value) => {
                     const m = policy.asyncConcurrency ?? "switch";
                     if (m !== "merge" && runId !== node.latestRunId)
                         return;
                     this.propagate(nodeId, handle, value);
                 },
-                invalidateDownstream: () => this.invalidateDownstream(nodeId),
-                scheduleInputsChanged: () => {
-                    if (this.allInboundHaveValue(nodeId)) {
-                        this.scheduleInputsChanged(nodeId);
-                    }
-                },
                 reportProgress: (p) => {
                     node.stats.progress = Math.max(0, Math.min(1, Number(p) || 0));
                     this.emit("stats", {
@@ -708,10 +721,11 @@ class GraphRuntime {
                         progress: node.stats.progress,
                     });
                 },
-            };
+            });
             const exec = async (attempt) => {
                 let hadError = false;
                 try {
+                    node.lifecycle?.prepare?.(node.params ?? {}, ctx);
                     await node.runtime.onInputsChanged?.(capturedInputs, ctx);
                 }
                 catch (err) {
@@ -853,7 +867,7 @@ class GraphRuntime {
         }
         return effective;
     }
-    invalidateDownstream(nodeId) {
+    invalidateDownstreamInternal(nodeId) {
         // Notifies dependents; for now we propagate current outputs
         for (const e of this.edges.filter((e) => e.source.nodeId === nodeId)) {
             const value = this.getOutput(nodeId, e.source.handle);
@@ -946,7 +960,7 @@ class GraphRuntime {
                     // Recompute dynamic handles for the destination node on input change
                     this.scheduleRecomputeHandles(e.target.nodeId);
                     if (!this.paused && this.allInboundHaveValue(e.target.nodeId))
-                        this.scheduleInputsChanged(e.target.nodeId);
+                        this.scheduleInputsChangedInternal(e.target.nodeId);
                 }
             };
             if (e.convertAsync) {
@@ -1148,22 +1162,22 @@ class GraphRuntime {
             }
         }
         // Invalidate downstream for this node so UI refreshes
-        this.invalidateDownstream(nodeId);
+        this.invalidateDownstreamInternal(nodeId);
     }
     launch(invalidate = false) {
         // call onActivated for nodes that implement it
         for (const node of this.nodes.values()) {
-            node.lifecycle?.init?.(node.params ?? {}, {
-                state: node.state,
-                setState: (next) => Object.assign(node.state, next),
-            });
+            const effectiveInputs = this.getEffectiveInputs(node.nodeId);
+            const ctrl = new AbortController();
+            const ctx = this.createExecutionContext(node.nodeId, node, effectiveInputs, `${node.nodeId}:init`, ctrl.signal);
+            node.lifecycle?.prepare?.(node.params ?? {}, ctx);
             node.runtime.onActivated?.();
         }
         if (invalidate) {
             // After activation, schedule nodes that have all inbound inputs present
             for (const nodeId of this.nodes.keys()) {
                 if (this.allInboundHaveValue(nodeId))
-                    this.scheduleInputsChanged(nodeId);
+                    this.scheduleInputsChangedInternal(nodeId);
             }
         }
     }
@@ -1176,9 +1190,9 @@ class GraphRuntime {
             typeof event === "object" &&
             event.type === "invalidate") {
             if (this.allInboundHaveValue(nodeId))
-                this.scheduleInputsChanged(nodeId);
+                this.scheduleInputsChangedInternal(nodeId);
             else
-                this.invalidateDownstream(nodeId);
+                this.invalidateDownstreamInternal(nodeId);
         }
         else {
             node.runtime.onExternalEvent?.(event, node.state);
@@ -1281,11 +1295,11 @@ class GraphRuntime {
     resume() {
         this.paused = false;
     }
-    __unsafe_invalidateDownstream(nodeId) {
-        this.invalidateDownstream(nodeId);
+    invalidateDownstream(nodeId) {
+        this.invalidateDownstreamInternal(nodeId);
     }
-    __unsafe_scheduleInputsChanged(nodeId) {
-        this.scheduleInputsChanged(nodeId);
+    scheduleInputsChanged(nodeId) {
+        this.scheduleInputsChangedInternal(nodeId);
     }
     // Hydrate inputs/outputs without triggering computation; optionally re-emit outputs downstream
     hydrate(payload, opts) {
@@ -1399,10 +1413,10 @@ class GraphRuntime {
                 };
                 this.nodes.set(n.nodeId, rn);
                 // Activate new node
-                rn.lifecycle?.init?.(rn.params ?? {}, {
-                    state: rn.state,
-                    setState: (next) => Object.assign(rn.state, next),
-                });
+                const effectiveInputs = this.getEffectiveInputs(rn.nodeId);
+                const ctrl = new AbortController();
+                const ctx = this.createExecutionContext(rn.nodeId, rn, effectiveInputs, `${rn.nodeId}:init`, ctrl.signal);
+                rn.lifecycle?.prepare?.(rn.params ?? {}, ctx);
                 rn.runtime.onActivated?.();
             }
             else {
@@ -1482,7 +1496,7 @@ class GraphRuntime {
                     if (bucketsForNode.size === 0)
                         this.arrayInputBuckets.delete(nodeId);
                 }
-                this.scheduleInputsChanged(nodeId);
+                this.scheduleInputsChangedInternal(nodeId);
             }
         }
         // Re-emit outputs when per-handle target sets change (precise and simple)
@@ -1525,7 +1539,7 @@ class GraphRuntime {
                     if (val !== undefined)
                         this.propagate(nodeId, handle, val);
                     else if (this.allInboundHaveValue(nodeId))
-                        this.scheduleInputsChanged(nodeId);
+                        this.scheduleInputsChangedInternal(nodeId);
                 }
             }
         }
@@ -1905,7 +1919,7 @@ class BatchedEngine extends AbstractEngine {
         this.dirtyNodes.clear();
         this.graphRuntime.resume();
         for (const n of nodes)
-            this.graphRuntime.__unsafe_scheduleInputsChanged(n);
+            this.graphRuntime.scheduleInputsChanged(n);
         await this.graphRuntime.whenIdle();
         this.graphRuntime.pause();
     }
@@ -1926,7 +1940,7 @@ class PullEngine extends AbstractEngine {
     // Pull API
     async computeNode(nodeId) {
         this.graphRuntime.resume();
-        this.graphRuntime.__unsafe_scheduleInputsChanged(nodeId);
+        this.graphRuntime.scheduleInputsChanged(nodeId);
         await this.graphRuntime.whenIdle();
         this.graphRuntime.pause();
     }
@@ -1955,7 +1969,7 @@ class HybridEngine extends AbstractEngine {
                 const nodes = Array.from(this.dirtyNodes);
                 this.dirtyNodes.clear();
                 for (const n of nodes)
-                    this.graphRuntime.__unsafe_scheduleInputsChanged(n);
+                    this.graphRuntime.scheduleInputsChanged(n);
                 if (this.flushTimer) {
                     clearTimeout(this.flushTimer);
                     this.flushTimer = undefined;
@@ -1985,14 +1999,14 @@ class HybridEngine extends AbstractEngine {
                 const nodes = Array.from(this.dirtyNodes);
                 this.dirtyNodes.clear();
                 for (const n of nodes)
-                    this.graphRuntime.__unsafe_scheduleInputsChanged(n);
+                    this.graphRuntime.scheduleInputsChanged(n);
                 this.flushTimer = undefined;
             }, windowMs);
         }
         super.setInputs(nodeId, inputs);
         this.dirtyNodes.add(nodeId);
         if (!this.batching)
-            this.graphRuntime.__unsafe_scheduleInputsChanged(nodeId);
+            this.graphRuntime.scheduleInputsChanged(nodeId);
     }
     triggerExternal(nodeId, event) {
         super.triggerExternal(nodeId, event);
@@ -2029,12 +2043,41 @@ class StepEngine extends AbstractEngine {
         this.dirtyNodes.clear();
         this.graphRuntime.resume();
         for (const n of nodes)
-            this.graphRuntime.__unsafe_scheduleInputsChanged(n);
+            this.graphRuntime.scheduleInputsChanged(n);
         await this.graphRuntime.whenIdle();
         this.graphRuntime.pause();
     }
 }
 
+/**
+ * Creates an Engine instance for the given GraphRuntime based on engine configuration.
+ * This is the single source of truth for engine creation, used by both local and remote runners.
+ */
+function createEngine(runtime, config) {
+    const engineKind = config?.engine ?? "push";
+    const batched = config?.batched ?? { flushIntervalMs: 0 };
+    const hybrid = config?.hybrid ?? { windowMs: 250, batchThreshold: 3 };
+    switch (engineKind) {
+        case "push":
+            return new PushEngine(runtime);
+        case "batched":
+            return new BatchedEngine(runtime, {
+                flushIntervalMs: batched.flushIntervalMs,
+            });
+        case "pull":
+            return new PullEngine(runtime);
+        case "hybrid":
+            return new HybridEngine(runtime, {
+                windowMs: hybrid.windowMs,
+                batchThreshold: hybrid.batchThreshold,
+            });
+        case "step":
+            return new StepEngine(runtime);
+        default:
+            throw new Error(`Unknown engine kind: ${engineKind}`);
+    }
+}
+
 const ComputeCategory = {
     id: "compute",
     displayName: "Compute",
@@ -3446,6 +3489,7 @@ exports.Registry = Registry;
 exports.StepEngine = StepEngine;
 exports.createAsyncGraphDef = createAsyncGraphDef;
 exports.createAsyncGraphRegistry = createAsyncGraphRegistry;
+exports.createEngine = createEngine;
 exports.createProgressGraphDef = createProgressGraphDef;
 exports.createProgressGraphRegistry = createProgressGraphRegistry;
 exports.createSimpleGraphDef = createSimpleGraphDef;