jslike 1.4.5 → 1.5.0

package/dist/index.cjs

@@ -20,6 +20,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var src_exports = {};
 __export(src_exports, {
   Environment: () => Environment,
+  ExecutionController: () => ExecutionController,
   InMemoryModuleResolver: () => InMemoryModuleResolver,
   Interpreter: () => Interpreter,
   ModuleResolver: () => ModuleResolver,
@@ -5817,19 +5818,36 @@ var Interpreter = class _Interpreter {
     this.moduleCache = /* @__PURE__ */ new Map();
     this.moduleExports = {};
     this.abortSignal = options.abortSignal;
+    this.executionController = options.executionController;
   }
-  // Check if execution should be aborted
+  // Check if execution should be aborted (sync version)
   checkAbortSignal() {
+    if (this.executionController) {
+      this.executionController._checkAbortSync();
+      return;
+    }
     if (this.abortSignal && this.abortSignal.aborted) {
       const error = new Error("The operation was aborted");
       error.name = "AbortError";
       throw error;
     }
   }
+  // 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;
+    }
+  }
   // Async evaluation for async functions - handles await expressions
   async evaluateAsync(node, env) {
     if (!node) return void 0;
-    this.checkAbortSignal();
+    const checkpointPromise = this._getCheckpointPromise(node, env);
+    if (checkpointPromise) await checkpointPromise;
     if (node.type === "AwaitExpression") {
       const promise = await this.evaluateAsync(node.argument, env);
       return await promise;
@@ -6000,6 +6018,8 @@ var Interpreter = class _Interpreter {
         await this.evaluateAsync(node.init, forEnv);
       }
       while (!node.test || await this.evaluateAsync(node.test, forEnv)) {
+        const cp1 = this._getCheckpointPromise(node, forEnv);
+        if (cp1) await cp1;
         const result = await this.evaluateAsync(node.body, forEnv);
         if (result instanceof BreakSignal) {
           break;
@@ -6025,6 +6045,8 @@ var Interpreter = class _Interpreter {
       const declarator = node.left.declarations[0];
       const isConst = node.left.kind === "const";
       for (const value of iterable) {
+        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);
@@ -6055,6 +6077,8 @@ var Interpreter = class _Interpreter {
       const varName = node.left.declarations[0].id.name;
       forEnv.define(varName, void 0);
       for (const key in obj) {
+        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) {
@@ -6071,6 +6095,8 @@ var Interpreter = class _Interpreter {
     }
     if (node.type === "WhileStatement") {
       while (await this.evaluateAsync(node.test, env)) {
+        const cp4 = this._getCheckpointPromise(node, env);
+        if (cp4) await cp4;
         const result = await this.evaluateAsync(node.body, env);
         if (result instanceof BreakSignal) {
           break;
@@ -6086,6 +6112,8 @@ var Interpreter = class _Interpreter {
     }
     if (node.type === "DoWhileStatement") {
       do {
+        const cp5 = this._getCheckpointPromise(node, env);
+        if (cp5) await cp5;
         const result = await this.evaluateAsync(node.body, env);
         if (result instanceof BreakSignal) {
           break;
@@ -6728,6 +6756,7 @@ var Interpreter = class _Interpreter {
   callUserFunction(func, args, callingEnv, thisContext = void 0) {
     const metadata = func.__metadata || func;
     const funcEnv = new Environment(metadata.closure);
+    const funcName = metadata.name || func.name || "anonymous";
     if (thisContext !== void 0) {
       funcEnv.define("this", thisContext);
     }
@@ -6750,15 +6779,46 @@ var Interpreter = class _Interpreter {
       }
     }
     if (metadata.async) {
+      if (this.executionController) {
+        this.executionController._pushCall(funcName);
+      }
       return (async () => {
+        try {
+          if (metadata.expression) {
+            const result = await this.evaluateAsync(metadata.body, funcEnv);
+            if (result instanceof ThrowSignal) {
+              throw result.value;
+            }
+            return result;
+          } else {
+            const result = await this.evaluateAsync(metadata.body, funcEnv);
+            if (result instanceof ReturnValue) {
+              return result.value;
+            }
+            if (result instanceof ThrowSignal) {
+              throw result.value;
+            }
+            return void 0;
+          }
+        } finally {
+          if (this.executionController) {
+            this.executionController._popCall();
+          }
+        }
+      })();
+    } else {
+      if (this.executionController) {
+        this.executionController._pushCall(funcName);
+      }
+      try {
         if (metadata.expression) {
-          const result = await this.evaluateAsync(metadata.body, funcEnv);
+          const result = this.evaluate(metadata.body, funcEnv);
           if (result instanceof ThrowSignal) {
             throw result.value;
           }
           return result;
         } else {
-          const result = await this.evaluateAsync(metadata.body, funcEnv);
+          const result = this.evaluate(metadata.body, funcEnv);
           if (result instanceof ReturnValue) {
             return result.value;
           }
@@ -6767,23 +6827,10 @@ var Interpreter = class _Interpreter {
           }
           return void 0;
         }
-      })();
-    } else {
-      if (metadata.expression) {
-        const result = this.evaluate(metadata.body, funcEnv);
-        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 (result instanceof ThrowSignal) {
-          throw result.value;
+      } finally {
+        if (this.executionController) {
+          this.executionController._popCall();
         }
-        return void 0;
       }
     }
   }
@@ -7926,7 +7973,8 @@ var WangInterpreter = class {
     }
     const hasTopLevelReturn = this.hasTopLevelReturn(code);
     const options = {
-      moduleResolver: this.moduleResolver
+      moduleResolver: this.moduleResolver,
+      executionController: userOptions.executionController
       // sourceType will be auto-detected from code
     };
     let result;
@@ -8005,6 +8053,191 @@ var InMemoryModuleResolver = class {
   }
 };
 
+// src/runtime/execution-controller.js
+var ExecutionController = class {
+  constructor() {
+    this.state = "idle";
+    this.pauseRequested = false;
+    this.abortRequested = false;
+    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;
+    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() {
+    var _a;
+    return {
+      state: this.state,
+      stepCount: this.stepCount,
+      currentNode: ((_a = this.currentNode) == null ? void 0 : _a.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;
+  }
+  /**
+   * 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";
+      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 === void 0) 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 };
+  }
+};
+
 // src/index.js
 function containsModuleSyntax(code) {
   if (/^\s*(import|export)\s+/m.test(code)) {
@@ -8071,21 +8304,39 @@ function containsTopLevelAwait(node) {
   return false;
 }
 async function execute(code, env = null, options = {}) {
-  const ast = parse4(code, options);
-  if (!env) {
-    env = createGlobalEnvironment(new Environment());
+  const controller = options.executionController;
+  if (controller) {
+    controller._start();
   }
-  const interpreter = new Interpreter(env, {
-    moduleResolver: options.moduleResolver,
-    abortSignal: options.abortSignal
-  });
-  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;
+  try {
+    const ast = parse4(code, options);
+    if (!env) {
+      env = createGlobalEnvironment(new Environment());
+    }
+    const interpreter = new Interpreter(env, {
+      moduleResolver: options.moduleResolver,
+      abortSignal: options.abortSignal,
+      executionController: controller
+    });
+    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) {
+    if (controller && e.name === "AbortError") {
+      controller.state = "aborted";
+    }
+    throw e;
   }
 }
 function createEnvironment() {
@@ -8123,6 +8374,7 @@ var ModuleResolver = class {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   Environment,
+  ExecutionController,
   InMemoryModuleResolver,
   Interpreter,
   ModuleResolver,