@bian-womp/spark-graph 0.3.16 → 0.3.18

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();
@@ -1335,7 +1532,7 @@ class HandleResolver {
         this.recomputeTokenByNode = new Map();
         this.environment = {};
         this.pendingResolutions = new Map();
-        this.pendingResolutionRunContexts = new Map();
+        this.isRecomputing = new Map();
         this.environment = environment ?? {};
     }
     setRegistry(registry) {
@@ -1344,33 +1541,12 @@ 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
      */
@@ -1381,27 +1557,43 @@ class HandleResolver {
         const node = this.graph.getNode(nodeId);
         if (!node)
             return;
+        // If already recomputing, increment token to mark that a new recompute is needed
+        // but don't schedule another concurrent execution
+        if (this.isRecomputing.get(nodeId)) {
+            const currentToken = this.recomputeTokenByNode.get(nodeId) ?? 0;
+            this.recomputeTokenByNode.set(nodeId, currentToken + 1);
+            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);
             }
         }
+        // Mark as recomputing
+        this.isRecomputing.set(nodeId, true);
+        // Capture initial token before starting (will be incremented in recomputeHandlesForNode)
+        const initialToken = this.recomputeTokenByNode.get(nodeId) ?? 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);
+                await this.recomputeHandlesForNode(nodeId, activeRunContextIds);
                 this.pendingResolutions.delete(nodeId);
-                this.pendingResolutionRunContexts.delete(nodeId);
+                this.isRecomputing.delete(nodeId);
+                // Check if a new recompute was requested while we were running
+                // (token was incremented by another scheduleRecomputeHandles call)
+                const finalToken = this.recomputeTokenByNode.get(nodeId) ?? 0;
+                // After recomputeHandlesForNode, token should be initialToken + 1
+                // If finalToken > initialToken + 1, a new recompute was requested
+                if (finalToken > initialToken + 1) {
+                    // A new recompute was requested, schedule it now
+                    this.scheduleRecomputeHandles(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) {
@@ -2019,33 +2211,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 {
@@ -2117,23 +2299,27 @@ class NodeExecutor {
         }
         // 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
+        const pendingResolution = this.handleResolver.getPendingResolution(nodeId);
+        if (pendingResolution) {
             if (runContextIds && runContextIds.size > 0) {
-                this.handleResolver.trackRunContextsForPendingResolution(nodeId, runContextIds);
+                for (const id of runContextIds) {
+                    this.runContextManager.startHandleResolution(id, nodeId);
+                }
             }
-            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);
+            // 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);
+                }
+                if (runContextIds && runContextIds.size > 0) {
+                    for (const id of runContextIds) {
+                        this.runContextManager.finishHandleResolution(id, nodeId);
                     }
-                });
-                return;
-            }
+                }
+            });
+            return;
         }
         // Handle debouncing
         const now = Date.now();
@@ -2574,7 +2760,7 @@ 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 and HandleResolver
@@ -5709,6 +5895,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;