@bian-womp/spark-graph 0.3.15 → 0.3.17

package/lib/cjs/index.cjs

@@ -932,15 +932,166 @@ class EventEmitter {
     }
 }
 
+const LOG_LEVEL_VALUES = {
+    debug: 0,
+    info: 1,
+    warn: 2,
+    error: 3,
+    silent: 4,
+};
+
+/**
+ * Shared utility functions for runtime components
+ */
+/**
+ * Type guard to check if a value is a Promise
+ */
+function isPromise(value) {
+    return !!value && typeof value.then === "function";
+}
+/**
+ * Unwrap a value that might be a Promise
+ */
+async function unwrapMaybePromise(value) {
+    return isPromise(value) ? await value : value;
+}
+/**
+ * Shallow/deep-ish equality check to avoid unnecessary runs on identical values
+ */
+function valuesEqual(a, b) {
+    if (a === b)
+        return true;
+    if (typeof a !== typeof b)
+        return false;
+    if (a && b && typeof a === "object") {
+        try {
+            return JSON.stringify(a) === JSON.stringify(b);
+        }
+        catch {
+            return false;
+        }
+    }
+    return false;
+}
+/**
+ * A reusable logger class that supports configurable log levels and prefixes.
+ * Can be instantiated with a default log level and optionally override per call.
+ */
+class LevelLogger {
+    constructor(defaultLevel = "info", prefix = "") {
+        this.defaultLevel = defaultLevel;
+        this.prefix = prefix;
+    }
+    /**
+     * Sets the prefix for log messages
+     */
+    setPrefix(prefix) {
+        this.prefix = prefix;
+    }
+    /**
+     * Gets the current prefix
+     */
+    getPrefix() {
+        return this.prefix;
+    }
+    /**
+     * Sets the default log level for this logger instance
+     */
+    setLevel(level) {
+        this.defaultLevel = level;
+    }
+    /**
+     * Gets the current default log level
+     */
+    getLevel() {
+        return this.defaultLevel;
+    }
+    getLevelValue() {
+        return LevelLogger.levelValues[this.defaultLevel];
+    }
+    /**
+     * Logs a debug message
+     */
+    debug(message, context, overrideLevel) {
+        this.log("debug", message, context, overrideLevel);
+    }
+    /**
+     * Logs an info message
+     */
+    info(message, context, overrideLevel) {
+        this.log("info", message, context, overrideLevel);
+    }
+    /**
+     * Logs a warning message
+     */
+    warn(message, context, overrideLevel) {
+        this.log("warn", message, context, overrideLevel);
+    }
+    /**
+     * Logs an error message
+     */
+    error(message, context, overrideLevel) {
+        this.log("error", message, context, overrideLevel);
+    }
+    /**
+     * Core logging method that respects the log level and applies prefix
+     */
+    log(requestedLevel, message, context, overrideLevel) {
+        const effectiveLevel = overrideLevel ?? this.defaultLevel;
+        // Silent level suppresses all logs
+        if (effectiveLevel === "silent") {
+            return;
+        }
+        const requestedValue = LevelLogger.levelValues[requestedLevel] ?? 1;
+        const effectiveValue = LevelLogger.levelValues[effectiveLevel] ?? 1;
+        // Only log if the requested level is >= effective level
+        if (requestedValue >= effectiveValue) {
+            const contextStr = context
+                ? ` ${Object.entries(context)
+                    .map(([k, v]) => `${k}=${JSON.stringify(v)}`)
+                    .join(" ")}`
+                : "";
+            const prefixedMessage = this.prefix
+                ? `${this.prefix} ${message}${contextStr}`
+                : `${message}${contextStr}`;
+            switch (requestedLevel) {
+                case "debug":
+                    console.info(prefixedMessage);
+                    break;
+                case "info":
+                    console.info(prefixedMessage);
+                    break;
+                case "warn":
+                    console.warn(prefixedMessage);
+                    break;
+                case "error":
+                    console.error(prefixedMessage);
+                    break;
+            }
+        }
+    }
+}
+/**
+ * Maps log levels to numeric values for comparison
+ */
+LevelLogger.levelValues = LOG_LEVEL_VALUES;
+
 /**
  * RunContextManager component - manages run-context lifecycle
  */
 class RunContextManager {
-    constructor(graph) {
+    constructor(graph, logLevel) {
         this.graph = graph;
         this.runContexts = new Map();
         this.runContextCounter = 0;
         this.graph = graph;
+        this.logger = new LevelLogger(logLevel ?? "info", "[RunContextManager]");
+    }
+    /**
+     * Set the log level for this manager
+     */
+    setLogLevel(logLevel) {
+        this.logger.setLevel(logLevel);
     }
     /**
      * Create a new run-context for runFromHere
@@ -959,6 +1110,12 @@ class RunContextManager {
             resolve,
         };
         this.runContexts.set(id, ctx);
+        this.logger.info("create-run-context", {
+            id,
+            startNodeId,
+            skipPropagateValues: ctx.skipPropagateValues,
+            propagate: ctx.propagate,
+        });
         return id;
     }
     /**
@@ -981,41 +1138,101 @@ class RunContextManager {
     }
     startNodeRun(id, nodeId) {
         const ctx = this.runContexts.get(id);
-        if (!ctx)
+        if (!ctx) {
+            this.logger.debug("start-node-run-context-not-found", {
+                runContextId: id,
+                nodeId,
+            });
             return;
+        }
         ctx.pendingNodes++;
+        this.logger.debug("start-node-run", {
+            runContextId: id,
+            nodeId,
+            pendingNodes: ctx.pendingNodes,
+        });
     }
     finishNodeRun(id, nodeId) {
         const ctx = this.runContexts.get(id);
-        if (!ctx)
+        if (!ctx) {
+            this.logger.debug("finish-node-run-context-not-found", {
+                runContextId: id,
+                nodeId,
+            });
             return;
+        }
         ctx.pendingNodes--;
+        this.logger.debug("finish-node-run", {
+            runContextId: id,
+            nodeId,
+            pendingNodes: ctx.pendingNodes,
+        });
         this.finishRunContextIfPossible(id);
     }
     startEdgeConversion(id, edgeId) {
         const ctx = this.runContexts.get(id);
-        if (!ctx)
+        if (!ctx) {
+            this.logger.debug("start-edge-conversion-context-not-found", {
+                runContextId: id,
+                edgeId,
+            });
             return;
+        }
         ctx.pendingEdges++;
+        this.logger.debug("start-edge-conversion", {
+            runContextId: id,
+            edgeId,
+            pendingEdges: ctx.pendingEdges,
+        });
     }
     finishEdgeConversion(id, edgeId) {
         const ctx = this.runContexts.get(id);
-        if (!ctx)
+        if (!ctx) {
+            this.logger.debug("finish-edge-conversion-context-not-found", {
+                runContextId: id,
+                edgeId,
+            });
             return;
+        }
         ctx.pendingEdges--;
+        this.logger.debug("finish-edge-conversion", {
+            runContextId: id,
+            edgeId,
+            pendingEdges: ctx.pendingEdges,
+        });
         this.finishRunContextIfPossible(id);
     }
     startHandleResolution(id, nodeId) {
         const ctx = this.runContexts.get(id);
-        if (!ctx)
+        if (!ctx) {
+            this.logger.debug("start-handle-resolution-context-not-found", {
+                runContextId: id,
+                nodeId,
+            });
             return;
+        }
         ctx.pendingResolvers++;
+        this.logger.debug("start-handle-resolution", {
+            runContextId: id,
+            nodeId,
+            pendingResolvers: ctx.pendingResolvers,
+        });
     }
     finishHandleResolution(id, nodeId) {
         const ctx = this.runContexts.get(id);
-        if (!ctx)
+        if (!ctx) {
+            this.logger.debug("finish-handle-resolution-context-not-found", {
+                runContextId: id,
+                nodeId,
+            });
             return;
+        }
         ctx.pendingResolvers--;
+        this.logger.debug("finish-handle-resolution", {
+            runContextId: id,
+            nodeId,
+            pendingResolvers: ctx.pendingResolvers,
+        });
         this.finishRunContextIfPossible(id);
     }
     /**
@@ -1023,13 +1240,22 @@ class RunContextManager {
      */
     finishRunContextIfPossible(id) {
         const ctx = this.runContexts.get(id);
-        if (!ctx)
+        if (!ctx) {
+            this.logger.debug("finish-run-context-not-found", {
+                runContextId: id,
+            });
             return;
+        }
         if (ctx.pendingNodes > 0 ||
             ctx.pendingEdges > 0 ||
             ctx.pendingResolvers > 0) {
             return; // Still has pending work
         }
+        this.logger.info("finish-run-context", {
+            runContextId: id,
+            startNodes: Array.from(ctx.startNodes),
+            cancelledNodes: Array.from(ctx.cancelledNodes),
+        });
         // Clean up activeRunContexts from all nodes
         this.graph.forEachNode((node) => {
             this.graph.removeNodeRunContextId(node.nodeId, id);
@@ -1067,6 +1293,12 @@ class RunContextManager {
                 });
             }
         }
+        this.logger.debug("cancel-node-in-run-contexts", {
+            nodeId,
+            includeDownstream,
+            cancelledNodes: Array.from(toCancel),
+            affectedRunContexts: Array.from(this.runContexts.keys()),
+        });
         // Mark nodes as cancelled in all run-contexts
         for (const ctx of this.runContexts.values()) {
             for (const id of toCancel) {
@@ -1082,6 +1314,11 @@ class RunContextManager {
      * Resolve all pending run-context promises (for cleanup)
      */
     resolveAll() {
+        const count = this.runContexts.size;
+        this.logger.info("resolve-all-run-contexts", {
+            count,
+            runContextIds: Array.from(this.runContexts.keys()),
+        });
         for (const ctx of this.runContexts.values()) {
             if (ctx.resolve)
                 ctx.resolve();
@@ -1091,52 +1328,12 @@ class RunContextManager {
      * Clear all run-contexts
      */
     clear() {
+        const count = this.runContexts.size;
+        this.logger.info("clear-all-run-contexts", { count });
         this.runContexts.clear();
     }
 }
 
-const LOG_LEVEL_VALUES = {
-    debug: 0,
-    info: 1,
-    warn: 2,
-    error: 3,
-    silent: 4,
-};
-
-/**
- * Shared utility functions for runtime components
- */
-/**
- * Type guard to check if a value is a Promise
- */
-function isPromise(value) {
-    return !!value && typeof value.then === "function";
-}
-/**
- * Unwrap a value that might be a Promise
- */
-async function unwrapMaybePromise(value) {
-    return isPromise(value) ? await value : value;
-}
-/**
- * Shallow/deep-ish equality check to avoid unnecessary runs on identical values
- */
-function valuesEqual(a, b) {
-    if (a === b)
-        return true;
-    if (typeof a !== typeof b)
-        return false;
-    if (a && b && typeof a === "object") {
-        try {
-            return JSON.stringify(a) === JSON.stringify(b);
-        }
-        catch {
-            return false;
-        }
-    }
-    return false;
-}
-
 function tryHandleResolving(def, registry, environment) {
     const out = new Map();
     const pending = new Set();
@@ -1334,6 +1531,8 @@ class HandleResolver {
         this.registry = registry;
         this.recomputeTokenByNode = new Map();
         this.environment = {};
+        this.pendingResolutions = new Map();
+        this.pendingResolutionRunContexts = new Map();
         this.environment = environment ?? {};
     }
     setRegistry(registry) {
@@ -1342,6 +1541,33 @@ class HandleResolver {
     setEnvironment(environment) {
         this.environment = environment;
     }
+    /**
+     * Check if handle resolution is pending for a node
+     */
+    isResolvingHandles(nodeId) {
+        return this.pendingResolutions.has(nodeId);
+    }
+    /**
+     * Get the promise for pending handle resolution, or null if none
+     */
+    getPendingResolution(nodeId) {
+        return this.pendingResolutions.get(nodeId) || null;
+    }
+    /**
+     * Track additional run contexts for a pending resolution
+     */
+    trackRunContextsForPendingResolution(nodeId, runContextIds) {
+        if (!this.pendingResolutions.has(nodeId))
+            return;
+        const tracked = this.pendingResolutionRunContexts.get(nodeId) ?? new Set();
+        for (const runContextId of runContextIds) {
+            if (!tracked.has(runContextId)) {
+                this.runContextManager.startHandleResolution(runContextId, nodeId);
+                tracked.add(runContextId);
+            }
+        }
+        this.pendingResolutionRunContexts.set(nodeId, tracked);
+    }
     /**
      * Schedule async recomputation of handles for a node
      */
@@ -1354,14 +1580,25 @@ class HandleResolver {
             return;
         // Track resolver start for all active run-contexts
         const activeRunContextIds = this.graph.getNodeRunContextIds(nodeId);
+        const trackedRunContextIds = new Set(activeRunContextIds);
         if (activeRunContextIds.size > 0) {
             for (const runContextId of activeRunContextIds) {
                 this.runContextManager.startHandleResolution(runContextId, nodeId);
             }
         }
-        setTimeout(() => {
-            void this.recomputeHandlesForNode(nodeId, activeRunContextIds.size > 0 ? activeRunContextIds : undefined);
-        }, 0);
+        // Create and track the resolution promise
+        const resolutionPromise = new Promise((resolve) => {
+            setTimeout(async () => {
+                // Get all tracked run contexts (including any added during pending state)
+                const allTracked = this.pendingResolutionRunContexts.get(nodeId) ?? trackedRunContextIds;
+                await this.recomputeHandlesForNode(nodeId, allTracked.size > 0 ? allTracked : undefined);
+                this.pendingResolutions.delete(nodeId);
+                this.pendingResolutionRunContexts.delete(nodeId);
+                resolve();
+            }, 0);
+        });
+        this.pendingResolutions.set(nodeId, resolutionPromise);
+        this.pendingResolutionRunContexts.set(nodeId, trackedRunContextIds);
     }
     // Update resolved handles for a single node and refresh edge converters/types that touch it
     updateNodeHandles(nodeId, handles) {
@@ -1906,10 +2143,11 @@ class EdgePropagator {
  * NodeExecutor component - handles node execution scheduling and lifecycle
  */
 class NodeExecutor {
-    constructor(graph, eventEmitter, runContextManager, edgePropagator, runtime, environment) {
+    constructor(graph, eventEmitter, runContextManager, handleResolver, edgePropagator, runtime, environment) {
         this.graph = graph;
         this.eventEmitter = eventEmitter;
         this.runContextManager = runContextManager;
+        this.handleResolver = handleResolver;
         this.edgePropagator = edgePropagator;
         this.runtime = runtime;
         this.environment = {};
@@ -1978,33 +2216,23 @@ class NodeExecutor {
                     progress: Math.max(0, Math.min(1, Number(p) || 0)),
                 });
             });
-        // Create log function that respects node's logLevel
+        // Create log function that respects node's logLevel using LevelLogger
+        const nodeLogLevel = node.logLevel ?? "info";
+        const logger = new LevelLogger(nodeLogLevel, `[node:${runId || nodeId}:${node.typeId}]`);
         const log = (level, message, context) => {
-            const nodeLogLevel = node.logLevel ?? "info";
-            const nodeLogValue = LOG_LEVEL_VALUES[nodeLogLevel] ?? 1;
-            const requestedValue = LOG_LEVEL_VALUES[level] ?? 1;
-            // Only log if requested level >= node's logLevel
-            if (requestedValue >= nodeLogValue && nodeLogLevel !== "silent") {
-                const contextStr = context
-                    ? ` ${Object.entries(context)
-                        .map(([k, v]) => `${k}=${JSON.stringify(v)}`)
-                        .join(" ")}`
-                    : "";
-                const fullMessage = `[node:${runId || nodeId}:${node.typeId}] ${message}${contextStr}`;
-                switch (level) {
-                    case "debug":
-                        console.info(fullMessage);
-                        break;
-                    case "info":
-                        console.info(fullMessage);
-                        break;
-                    case "warn":
-                        console.warn(fullMessage);
-                        break;
-                    case "error":
-                        console.error(fullMessage);
-                        break;
-                }
+            switch (level) {
+                case "debug":
+                    logger.debug(message, context);
+                    break;
+                case "info":
+                    logger.info(message, context);
+                    break;
+                case "warn":
+                    logger.warn(message, context);
+                    break;
+                case "error":
+                    logger.error(message, context);
+                    break;
             }
         };
         return {
@@ -2069,10 +2297,31 @@ class NodeExecutor {
         // Early validation for auto-mode paused state
         if (this.runtime.isPaused())
             return;
-        // Attach run-context IDs if provided
+        // Attach run-context IDs if provided - do this BEFORE checking for pending resolution
+        // so that handle resolution can track these run contexts
         if (runContextIds) {
             this.graph.addNodeRunContextIds(nodeId, runContextIds);
         }
+        // Check if handles are being resolved - wait for resolution before executing
+        // Do this AFTER setting up run contexts so handle resolution can track them
+        if (this.handleResolver && this.handleResolver.isResolvingHandles(nodeId)) {
+            // Track run contexts for the pending resolution
+            if (runContextIds && runContextIds.size > 0) {
+                this.handleResolver.trackRunContextsForPendingResolution(nodeId, runContextIds);
+            }
+            const pendingResolution = this.handleResolver.getPendingResolution(nodeId);
+            if (pendingResolution) {
+                // Wait for resolution to complete, then re-execute
+                pendingResolution.then(() => {
+                    // Re-check node still exists and conditions
+                    const nodeAfter = this.graph.getNode(nodeId);
+                    if (nodeAfter) {
+                        this.execute(nodeId, runContextIds);
+                    }
+                });
+                return;
+            }
+        }
         // Handle debouncing
         const now = Date.now();
         if (this.shouldDebounce(nodeId, node, now)) {
@@ -2512,11 +2761,11 @@ class GraphRuntime {
         // Initialize components
         this.graph = new Graph();
         this.eventEmitter = new EventEmitter();
-        this.runContextManager = new RunContextManager(this.graph);
+        this.runContextManager = new RunContextManager(this.graph, "debug");
         this.handleResolver = new HandleResolver(this.graph, this.eventEmitter, this.runContextManager, this);
         this.edgePropagator = new EdgePropagator(this.graph, this.eventEmitter, this.runContextManager, this.handleResolver, this);
-        // Create NodeExecutor with EdgePropagator
-        this.nodeExecutor = new NodeExecutor(this.graph, this.eventEmitter, this.runContextManager, this, this);
+        // Create NodeExecutor with EdgePropagator and HandleResolver
+        this.nodeExecutor = new NodeExecutor(this.graph, this.eventEmitter, this.runContextManager, this.handleResolver, this, this);
     }
     static create(def, registry, opts) {
         const gr = new GraphRuntime();
@@ -2829,19 +3078,30 @@ class GraphRuntime {
         const releasePause = this.requestPause();
         try {
             const ins = payload?.inputs || {};
+            const nodesWithChangedInputs = new Set();
             for (const [nodeId, map] of Object.entries(ins)) {
                 if (!this.graph.hasNode(nodeId))
                     continue;
+                let nodeChanged = false;
                 for (const [h, v] of Object.entries(map || {})) {
+                    const node = this.graph.getNode(nodeId);
+                    const prev = node?.inputs[h];
                     const clonedValue = structuredClone(v);
-                    this.graph.updateNodeInput(nodeId, h, clonedValue);
-                    this.eventEmitter.emit("value", {
-                        nodeId,
-                        handle: h,
-                        value: clonedValue,
-                        io: "input",
-                        runtimeTypeId: getTypedOutputTypeId(clonedValue),
-                    });
+                    const same = valuesEqual(prev, clonedValue);
+                    if (!same) {
+                        this.graph.updateNodeInput(nodeId, h, clonedValue);
+                        this.eventEmitter.emit("value", {
+                            nodeId,
+                            handle: h,
+                            value: clonedValue,
+                            io: "input",
+                            runtimeTypeId: getTypedOutputTypeId(clonedValue),
+                        });
+                        nodeChanged = true;
+                    }
+                }
+                if (nodeChanged) {
+                    nodesWithChangedInputs.add(nodeId);
                 }
             }
             const outs = payload?.outputs || {};
@@ -2860,6 +3120,10 @@ class GraphRuntime {
                     });
                 }
             }
+            // Trigger handle resolution for nodes with changed inputs
+            for (const nodeId of nodesWithChangedInputs) {
+                this.handleResolver.scheduleRecomputeHandles(nodeId);
+            }
             if (opts?.invalidate) {
                 for (const nodeId of this.graph.getNodeIds()) {
                     this.invalidateDownstream(nodeId);
@@ -3042,6 +3306,8 @@ class GraphRuntime {
                     }
                     if (changed) {
                         this.edgePropagator.clearArrayBuckets(nodeId);
+                        // Trigger handle resolution when inputs are removed
+                        this.handleResolver.scheduleRecomputeHandles(nodeId);
                         if (this.runMode === "auto" &&
                             this.graph.allInboundHaveValue(nodeId)) {
                             this.execute(nodeId);
@@ -3162,6 +3428,17 @@ class GraphBuilder {
             const arr = Array.isArray(from) ? from : [from];
             return arr.every((s) => s === to || !!this.registry.canCoerce(s, to));
         };
+        // Helper to validate enum value
+        const validateEnumValue = (typeId, value, nodeId, handle) => {
+            if (!typeId.startsWith("enum:"))
+                return true; // Not an enum type
+            const enumDef = this.registry.enums.get(typeId);
+            if (!enumDef)
+                return true; // Enum not registered, skip validation
+            if (typeof value !== "number")
+                return false; // Enum values must be numbers
+            return enumDef.valueToLabel.has(value);
+        };
         const pushIssue = (level, code, message, data) => {
             issues.push({ level, code, message, data });
         };
@@ -3185,6 +3462,51 @@ class GraphBuilder {
             if (!this.registry.categories.has(nodeType.categoryId)) {
                 pushIssue("error", "CATEGORY_MISSING", `Unknown category ${nodeType.categoryId} for node type ${n.typeId}`);
             }
+            // Validate enum values in node params
+            if (n.params) {
+                const effectiveHandles = getEffectiveHandles(n);
+                for (const [paramKey, paramValue] of Object.entries(n.params)) {
+                    // Skip policy and other non-input params
+                    if (paramKey === "policy")
+                        continue;
+                    // Check if this param corresponds to an input handle
+                    const inputTypeId = getInputTypeId(effectiveHandles.inputs, paramKey);
+                    if (inputTypeId && inputTypeId.startsWith("enum:")) {
+                        if (!validateEnumValue(inputTypeId, paramValue, n.nodeId)) {
+                            const enumDef = this.registry.enums.get(inputTypeId);
+                            const validValues = enumDef
+                                ? Array.from(enumDef.valueToLabel.keys()).join(", ")
+                                : "unknown";
+                            pushIssue("error", "ENUM_VALUE_INVALID", `Node ${n.nodeId} param ${paramKey} has invalid enum value ${paramValue}. Valid values: ${validValues}`, {
+                                nodeId: n.nodeId,
+                                input: paramKey,
+                                typeId: inputTypeId,
+                            });
+                        }
+                    }
+                }
+            }
+            // Validate enum values in input defaults
+            const resolved = n.resolvedHandles;
+            if (resolved?.inputDefaults) {
+                const effectiveHandles = getEffectiveHandles(n);
+                for (const [handle, defaultValue] of Object.entries(resolved.inputDefaults)) {
+                    const inputTypeId = getInputTypeId(effectiveHandles.inputs, handle);
+                    if (inputTypeId && inputTypeId.startsWith("enum:")) {
+                        if (!validateEnumValue(inputTypeId, defaultValue, n.nodeId)) {
+                            const enumDef = this.registry.enums.get(inputTypeId);
+                            const validValues = enumDef
+                                ? Array.from(enumDef.valueToLabel.keys()).join(", ")
+                                : "unknown";
+                            pushIssue("warning", "ENUM_DEFAULT_INVALID", `Node ${n.nodeId} input default ${handle} has invalid enum value ${defaultValue}. Valid values: ${validValues}`, {
+                                nodeId: n.nodeId,
+                                input: handle,
+                                typeId: inputTypeId,
+                            });
+                        }
+                    }
+                }
+            }
         }
         // edges validation: nodes exist, handles exist, type exists
         const inboundCounts = new Map();
@@ -5574,6 +5896,7 @@ exports.CompositeCategory = CompositeCategory;
 exports.ComputeCategory = ComputeCategory;
 exports.GraphBuilder = GraphBuilder;
 exports.GraphRuntime = GraphRuntime;
+exports.LevelLogger = LevelLogger;
 exports.LocalEngine = LocalEngine;
 exports.Registry = Registry;
 exports.buildValueConverter = buildValueConverter;