jslike 1.4.5 → 1.5.0

package/dist/index.d.ts

@@ -6440,10 +6440,17 @@ class Interpreter {
     this.moduleCache = new Map();  // Cache loaded modules
     this.moduleExports = {};  // Track exports in current module
     this.abortSignal = options.abortSignal;
+    this.executionController = options.executionController;
   }
 
-  // Check if execution should be aborted
+  // Check if execution should be aborted (sync version)
   checkAbortSignal() {
+    // Check controller first if available
+    if (this.executionController) {
+      this.executionController._checkAbortSync();
+      return;
+    }
+    // Fall back to legacy abortSignal
     if (this.abortSignal && this.abortSignal.aborted) {
       const error = new Error('The operation was aborted');
       error.name = 'AbortError';
@@ -6451,12 +6458,26 @@ class Interpreter {
     }
   }
 
+  // Checkpoint that returns a promise only when controller is present
+  // When no controller, returns null to signal no await needed
+  _getCheckpointPromise(node, env) {
+    if (this.executionController) {
+      this.executionController._setEnv(env);
+      return this.executionController._checkpoint(node);
+    } else {
+      this.checkAbortSignal();
+      return null;  // Signal that no await is needed
+    }
+  }
+
   // Async evaluation for async functions - handles await expressions
   async evaluateAsync(node, env) {
     if (!node) return undefined;
 
-    // Check for abort signal before evaluating
-    this.checkAbortSignal();
+    // Checkpoint - yields if paused, throws if aborted
+    // Only await when there's actually a promise (controller present)
+    const checkpointPromise = this._getCheckpointPromise(node, env);
+    if (checkpointPromise) await checkpointPromise;
 
     // Handle await expressions by actually awaiting the promise
     if (node.type === 'AwaitExpression') {
@@ -6693,6 +6714,9 @@ class Interpreter {
         await this.evaluateAsync(node.init, forEnv);
       }
       while (!node.test || await this.evaluateAsync(node.test, forEnv)) {
+        // Checkpoint at each loop iteration (only await if controller present)
+        const cp1 = this._getCheckpointPromise(node, forEnv);
+        if (cp1) await cp1;
         const result = await this.evaluateAsync(node.body, forEnv);
         if (result instanceof BreakSignal) {
           break;
@@ -6721,6 +6745,9 @@ class Interpreter {
       const isConst = node.left.kind === 'const';
 
       for (const value of iterable) {
+        // Checkpoint at each loop iteration (only await if controller present)
+        const cp2 = this._getCheckpointPromise(node, forEnv);
+        if (cp2) await cp2;
         const iterEnv = forEnv.extend();
         if (declarator.id.type === 'Identifier') {
           iterEnv.define(declarator.id.name, value, isConst);
@@ -6754,6 +6781,9 @@ class Interpreter {
       forEnv.define(varName, undefined);
 
       for (const key in obj) {
+        // Checkpoint at each loop iteration (only await if controller present)
+        const cp3 = this._getCheckpointPromise(node, forEnv);
+        if (cp3) await cp3;
         forEnv.set(varName, key);
         const result = await this.evaluateAsync(node.body, forEnv);
         if (result instanceof BreakSignal) {
@@ -6772,6 +6802,9 @@ class Interpreter {
     // For WhileStatement with async body
     if (node.type === 'WhileStatement') {
       while (await this.evaluateAsync(node.test, env)) {
+        // Checkpoint at each loop iteration (only await if controller present)
+        const cp4 = this._getCheckpointPromise(node, env);
+        if (cp4) await cp4;
         const result = await this.evaluateAsync(node.body, env);
         if (result instanceof BreakSignal) {
           break;
@@ -6789,6 +6822,9 @@ class Interpreter {
     // For DoWhileStatement with async body
     if (node.type === 'DoWhileStatement') {
       do {
+        // Checkpoint at each loop iteration (only await if controller present)
+        const cp5 = this._getCheckpointPromise(node, env);
+        if (cp5) await cp5;
         const result = await this.evaluateAsync(node.body, env);
         if (result instanceof BreakSignal) {
           break;
@@ -7592,6 +7628,9 @@ class Interpreter {
     const metadata = func.__metadata || func;
     const funcEnv = new Environment(metadata.closure);
 
+    // Get function name for call stack tracking
+    const funcName = metadata.name || func.name || 'anonymous';
+
     // Bind 'this' if provided (for method calls)
     if (thisContext !== undefined) {
       funcEnv.define('this', thisContext);
@@ -7627,18 +7666,54 @@ class Interpreter {
     // Execute function body
     // If async, use async evaluation and return a promise
     if (metadata.async) {
+      // Track call stack for async functions
+      if (this.executionController) {
+        this.executionController._pushCall(funcName);
+      }
       return (async () => {
+        try {
+          if (metadata.expression) {
+            // Arrow function with expression body
+            const result = await this.evaluateAsync(metadata.body, funcEnv);
+            // If the result is a ThrowSignal, throw the error
+            if (result instanceof ThrowSignal) {
+              throw result.value;
+            }
+            return result;
+          } else {
+            // Block statement body
+            const result = await this.evaluateAsync(metadata.body, funcEnv);
+            if (result instanceof ReturnValue) {
+              return result.value;
+            }
+            // If the result is a ThrowSignal, throw the error
+            if (result instanceof ThrowSignal) {
+              throw result.value;
+            }
+            return undefined;
+          }
+        } finally {
+          if (this.executionController) {
+            this.executionController._popCall();
+          }
+        }
+      })();
+    } else {
+      // Synchronous evaluation for non-async functions
+      // Track call stack for sync functions
+      if (this.executionController) {
+        this.executionController._pushCall(funcName);
+      }
+      try {
         if (metadata.expression) {
-          // Arrow function with expression body
-          const result = await this.evaluateAsync(metadata.body, funcEnv);
+          const result = this.evaluate(metadata.body, funcEnv);
           // If the result is a ThrowSignal, throw the error
           if (result instanceof ThrowSignal) {
             throw result.value;
           }
           return result;
         } else {
-          // Block statement body
-          const result = await this.evaluateAsync(metadata.body, funcEnv);
+          const result = this.evaluate(metadata.body, funcEnv);
           if (result instanceof ReturnValue) {
             return result.value;
           }
@@ -7648,26 +7723,10 @@ class Interpreter {
           }
           return undefined;
         }
-      })();
-    } else {
-      // Synchronous evaluation for non-async functions
-      if (metadata.expression) {
-        const result = this.evaluate(metadata.body, funcEnv);
-        // If the result is a ThrowSignal, throw the error
-        if (result instanceof ThrowSignal) {
-          throw result.value;
-        }
-        return result;
-      } else {
-        const result = this.evaluate(metadata.body, funcEnv);
-        if (result instanceof ReturnValue) {
-          return result.value;
-        }
-        // If the result is a ThrowSignal, throw the error
-        if (result instanceof ThrowSignal) {
-          throw result.value;
+      } finally {
+        if (this.executionController) {
+          this.executionController._popCall();
         }
-        return undefined;
       }
     }
   }
@@ -9228,7 +9287,8 @@ class WangInterpreter {
 
     // Prepare execution options
     const options = {
-      moduleResolver: this.moduleResolver
+      moduleResolver: this.moduleResolver,
+      executionController: userOptions.executionController
       // sourceType will be auto-detected from code
     };
 
@@ -9327,6 +9387,219 @@ class InMemoryModuleResolver {
   }
 }
 
+/**
+ * ExecutionController - Controls and monitors interpreter execution
+ *
+ * Provides pause/resume/abort capabilities and execution status introspection.
+ * Works with async evaluation only - sync evaluation can only abort.
+ */
+class ExecutionController {
+  constructor() {
+    this.state = 'idle';  // 'idle' | 'running' | 'paused' | 'aborted' | 'completed'
+    this.pauseRequested = false;
+    this.abortRequested = false;
+
+    // Debug info
+    this.stepCount = 0;
+    this.currentNode = null;
+    this.callStack = [];
+    this.currentEnv = null;
+
+    this._resolveResume = null;
+  }
+
+  // --- Control methods (called by user) ---
+
+  /**
+   * Request pause at next checkpoint. Only works during async evaluation.
+   */
+  pause() {
+    if (this.state === 'running') {
+      this.pauseRequested = true;
+    }
+  }
+
+  /**
+   * Resume execution after pause.
+   */
+  resume() {
+    if (this.state === 'paused' && this._resolveResume) {
+      this.pauseRequested = false;
+      this._resolveResume();
+      this._resolveResume = null;
+    }
+  }
+
+  /**
+   * Abort execution. Works for both sync and async evaluation.
+   * If paused, will resume and then abort.
+   */
+  abort() {
+    this.abortRequested = true;
+    // Also resume if paused to allow abort to take effect
+    if (this._resolveResume) {
+      this._resolveResume();
+      this._resolveResume = null;
+    }
+  }
+
+  // --- Status (called by user) ---
+
+  /**
+   * Get current execution status with full debug information.
+   * @returns {Object} Status object with state, stepCount, currentNode, callStack, and variables
+   */
+  getStatus() {
+    return {
+      state: this.state,
+      stepCount: this.stepCount,
+      currentNode: this.currentNode?.type || null,
+      callStack: [...this.callStack],
+      variables: this._getEnvironmentVariables()
+    };
+  }
+
+  /**
+   * Check if abort has been requested.
+   * Compatible with AbortSignal interface.
+   */
+  get aborted() {
+    return this.abortRequested;
+  }
+
+  // --- Internal methods (called by interpreter) ---
+
+  /**
+   * Mark execution as started. Called by execute().
+   * @internal
+   */
+  _start() {
+    this.state = 'running';
+    this.stepCount = 0;
+    this.currentNode = null;
+    this.callStack = [];
+    this.pauseRequested = false;
+    // Note: don't reset abortRequested - allow pre-abort
+  }
+
+  /**
+   * Mark execution as completed. Called by execute().
+   * @internal
+   */
+  _complete() {
+    this.state = 'completed';
+  }
+
+  /**
+   * Push a function call onto the call stack.
+   * @internal
+   */
+  _pushCall(name) {
+    this.callStack.push(name);
+  }
+
+  /**
+   * Pop a function call from the call stack.
+   * @internal
+   */
+  _popCall() {
+    this.callStack.pop();
+  }
+
+  /**
+   * Set the current environment for variable introspection.
+   * @internal
+   */
+  _setEnv(env) {
+    this.currentEnv = env;
+  }
+
+  /**
+   * Async checkpoint - yields if paused, throws if aborted.
+   * Called at coarse granularity points (loops, function calls).
+   * @internal
+   */
+  async _checkpoint(node) {
+    this.stepCount++;
+    this.currentNode = node;
+
+    if (this.abortRequested) {
+      this.state = 'aborted';
+      const error = new Error('The operation was aborted');
+      error.name = 'AbortError';
+      throw error;
+    }
+
+    if (this.pauseRequested && this.state === 'running') {
+      this.state = 'paused';
+      await new Promise(resolve => { this._resolveResume = resolve; });
+      this.state = 'running';
+
+      // Check abort after resume (user may have called abort while paused)
+      if (this.abortRequested) {
+        this.state = 'aborted';
+        const error = new Error('The operation was aborted');
+        error.name = 'AbortError';
+        throw error;
+      }
+    }
+  }
+
+  /**
+   * Sync abort check - only throws if aborted, cannot pause.
+   * Used in sync evaluate() path.
+   * @internal
+   */
+  _checkAbortSync() {
+    if (this.abortRequested) {
+      this.state = 'aborted';
+      const error = new Error('The operation was aborted');
+      error.name = 'AbortError';
+      throw error;
+    }
+  }
+
+  /**
+   * Get all variables from current environment chain.
+   * @internal
+   */
+  _getEnvironmentVariables() {
+    if (!this.currentEnv) return {};
+    const vars = {};
+    let env = this.currentEnv;
+    while (env) {
+      if (env.vars) {
+        for (const [key, value] of env.vars) {
+          if (!(key in vars)) {
+            vars[key] = this._serializeValue(value);
+          }
+        }
+      }
+      env = env.parent;
+    }
+    return vars;
+  }
+
+  /**
+   * Serialize a value for status reporting.
+   * @internal
+   */
+  _serializeValue(value) {
+    if (value === undefined) return { type: 'undefined' };
+    if (value === null) return { type: 'null' };
+    if (typeof value === 'function' || (value && value.__isFunction)) {
+      return { type: 'function', name: value.name || 'anonymous' };
+    }
+    if (Array.isArray(value)) {
+      return { type: 'array', length: value.length };
+    }
+    if (typeof value === 'object') {
+      return { type: 'object', preview: Object.keys(value).slice(0, 5) };
+    }
+    return { type: typeof value, value };
+  }
+}
+
 // Use bundled Acorn parser for zero runtime dependencies
 
 // Helper to detect if code contains module syntax or top-level await
@@ -9423,34 +9696,59 @@ function containsTopLevelAwait(node) {
 }
 
 async function execute(code, env = null, options = {}) {
-  // Parse the code
-  const ast = parse(code, options);
+  // Get execution controller if provided
+  const controller = options.executionController;
 
-  // Create global environment if not provided
-  if (!env) {
-    env = createGlobalEnvironment(new Environment());
+  // Mark execution as starting
+  if (controller) {
+    controller._start();
   }
 
-  // Create interpreter with module resolver and abort signal if provided
-  const interpreter = new Interpreter(env, {
-    moduleResolver: options.moduleResolver,
-    abortSignal: options.abortSignal
-  });
+  try {
+    // Parse the code
+    const ast = parse(code, options);
 
-  // Use async evaluation if:
-  // 1. Explicitly requested module mode
-  // 2. AST contains import/export declarations
-  // 3. Code contains top-level await
-  const needsAsync = options.sourceType === 'module' ||
-                     containsModuleDeclarations(ast) ||
-                     containsTopLevelAwait(ast);
-
-  if (needsAsync) {
-    const result = await interpreter.evaluateAsync(ast, env);
-    return result instanceof ReturnValue ? result.value : result;
-  } else {
-    const result = interpreter.evaluate(ast, env);
-    return result instanceof ReturnValue ? result.value : result;
+    // Create global environment if not provided
+    if (!env) {
+      env = createGlobalEnvironment(new Environment());
+    }
+
+    // Create interpreter with module resolver, abort signal, and execution controller
+    const interpreter = new Interpreter(env, {
+      moduleResolver: options.moduleResolver,
+      abortSignal: options.abortSignal,
+      executionController: controller
+    });
+
+    // Use async evaluation if:
+    // 1. Explicitly requested module mode
+    // 2. AST contains import/export declarations
+    // 3. Code contains top-level await
+    // 4. Execution controller provided (needs async for pause/resume)
+    const needsAsync = options.sourceType === 'module' ||
+                       containsModuleDeclarations(ast) ||
+                       containsTopLevelAwait(ast) ||
+                       controller != null;
+
+    if (needsAsync) {
+      const result = await interpreter.evaluateAsync(ast, env);
+      if (controller) {
+        controller._complete();
+      }
+      return result instanceof ReturnValue ? result.value : result;
+    } else {
+      const result = interpreter.evaluate(ast, env);
+      if (controller) {
+        controller._complete();
+      }
+      return result instanceof ReturnValue ? result.value : result;
+    }
+  } catch (e) {
+    // Mark as aborted if that's the error type
+    if (controller && e.name === 'AbortError') {
+      controller.state = 'aborted';
+    }
+    throw e;
   }
 }
 
@@ -9503,4 +9801,4 @@ class ModuleResolver {
  * @property {any} [metadata] - Optional metadata about the module
  */
 
-export { Environment, InMemoryModuleResolver, Interpreter, ModuleResolver, WangInterpreter, createEnvironment, execute, isTopLevelAwait, parse };
+export { Environment, ExecutionController, InMemoryModuleResolver, Interpreter, ModuleResolver, WangInterpreter, createEnvironment, execute, isTopLevelAwait, parse };