@bian-womp/spark-graph 0.3.16 → 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();
@@ -2019,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 {
@@ -2574,7 +2761,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 +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;