@typescript-guy/fn-monitor 1.0.0

package/dist/evaluate_n/statement.js

@@ -0,0 +1,301 @@
+import { BREAK, CONTINUE, RETURN } from '../share/const.js';
+import { hoist, ForXHandler, pattern } from './helper.js';
+import Scope from '../scope/index.js';
+import evaluate from './index.js';
+
+function ExpressionStatement(node, scope) {
+  evaluate(node.expression, scope);
+}
+function BlockStatement(block, scope, options = {}) {
+  const {
+    invasived = false,
+    hoisted = false
+  } = options;
+  const subScope = invasived ? scope : new Scope(scope);
+  if (!hoisted) {
+    hoist(block, subScope, { onlyBlock: true });
+  }
+  for (let i = 0; i < block.body.length; i++) {
+    const result = evaluate(block.body[i], subScope);
+    if (result === BREAK) {
+      if (result.LABEL && result.LABEL === options.label) {
+        break;
+      }
+      return result;
+    }
+    if (result === CONTINUE || result === RETURN) {
+      return result;
+    }
+  }
+}
+function EmptyStatement() {
+}
+function DebuggerStatement() {
+  debugger;
+}
+function ReturnStatement(node, scope) {
+  RETURN.RES = node.argument ? evaluate(node.argument, scope) : void 0;
+  return RETURN;
+}
+function BreakStatement(node) {
+  BREAK.LABEL = node.label?.name;
+  return BREAK;
+}
+function ContinueStatement(node) {
+  CONTINUE.LABEL = node.label?.name;
+  return CONTINUE;
+}
+function LabeledStatement(node, scope) {
+  const label = node.label.name;
+  if (node.body.type === "WhileStatement") {
+    return WhileStatement(node.body, scope, { label });
+  }
+  if (node.body.type === "DoWhileStatement") {
+    return DoWhileStatement(node.body, scope, { label });
+  }
+  if (node.body.type === "ForStatement") {
+    return ForStatement(node.body, scope, { label });
+  }
+  if (node.body.type === "ForInStatement") {
+    return ForInStatement(node.body, scope, { label });
+  }
+  if (node.body.type === "ForOfStatement") {
+    return ForOfStatement(node.body, scope, { label });
+  }
+  if (node.body.type === "BlockStatement") {
+    return BlockStatement(node.body, scope, { label });
+  }
+  if (node.body.type === "WithStatement") {
+    return WithStatement(node.body, scope, { label });
+  }
+  if (node.body.type === "IfStatement") {
+    return IfStatement(node.body, scope, { label });
+  }
+  if (node.body.type === "SwitchStatement") {
+    return SwitchStatement(node.body, scope, { label });
+  }
+  if (node.body.type === "TryStatement") {
+    return TryStatement(node.body, scope, { label });
+  }
+  throw new SyntaxError(`${node.body.type} cannot be labeled`);
+}
+function WithStatement(node, scope, options = {}) {
+  const withScope = new Scope(scope);
+  withScope.with(evaluate(node.object, scope));
+  const result = evaluate(node.body, withScope);
+  if (result === BREAK) {
+    if (result.LABEL && result.LABEL === options.label) {
+      return;
+    }
+    return result;
+  }
+  if (result === CONTINUE || result === RETURN) {
+    return result;
+  }
+}
+function IfStatement(node, scope, options = {}) {
+  let result;
+  if (evaluate(node.test, scope)) {
+    result = evaluate(node.consequent, scope);
+  } else {
+    result = evaluate(node.alternate, scope);
+  }
+  if (result === BREAK) {
+    if (result.LABEL && result.LABEL === options.label) {
+      return;
+    }
+    return result;
+  }
+  if (result === CONTINUE || result === RETURN) {
+    return result;
+  }
+}
+function SwitchStatement(node, scope, options = {}) {
+  const discriminant = evaluate(node.discriminant, scope);
+  let matched = false;
+  let defaultIndex = -1;
+  for (let i = 0; i < node.cases.length; i++) {
+    const eachCase = node.cases[i];
+    if (!eachCase.test) {
+      defaultIndex = i;
+    } else if (!matched && evaluate(eachCase.test, scope) === discriminant) {
+      matched = true;
+      defaultIndex = -1;
+    }
+    if (matched) {
+      const result = SwitchCase(eachCase, scope);
+      if (result === BREAK) {
+        if (result.LABEL === options.label) {
+          break;
+        }
+        return result;
+      }
+      if (result === CONTINUE || result === RETURN) {
+        return result;
+      }
+    }
+  }
+  if (!matched && defaultIndex !== -1) {
+    for (let i = defaultIndex; i < node.cases.length; i++) {
+      const result = SwitchCase(node.cases[i], scope);
+      if (result === BREAK) {
+        if (result.LABEL === options.label) {
+          break;
+        }
+        return result;
+      }
+      if (result === CONTINUE || result === RETURN) {
+        return result;
+      }
+    }
+  }
+}
+function SwitchCase(node, scope) {
+  for (let i = 0; i < node.consequent.length; i++) {
+    const result = evaluate(node.consequent[i], scope);
+    if (result === BREAK || result === CONTINUE || result === RETURN) {
+      return result;
+    }
+  }
+}
+function ThrowStatement(node, scope) {
+  throw evaluate(node.argument, scope);
+}
+function TryStatement(node, scope, options = {}) {
+  let result;
+  try {
+    result = BlockStatement(node.block, scope);
+  } catch (err) {
+    if (node.handler) {
+      const subScope = new Scope(scope);
+      const param = node.handler.param;
+      if (param) {
+        if (param.type === "Identifier") {
+          const name = param.name;
+          subScope.var(name, err);
+        } else {
+          pattern(param, scope, { feed: err });
+        }
+      }
+      result = CatchClause(node.handler, subScope);
+    } else {
+      throw err;
+    }
+  } finally {
+    if (node.finalizer) {
+      result = BlockStatement(node.finalizer, scope);
+    }
+  }
+  if (result === BREAK) {
+    if (result.LABEL && result.LABEL === options.label) {
+      return;
+    }
+    return result;
+  }
+  if (result === CONTINUE || result === RETURN) {
+    return result;
+  }
+}
+function CatchClause(node, scope) {
+  return BlockStatement(node.body, scope, { invasived: true });
+}
+function WhileStatement(node, scope, options = {}) {
+  while (evaluate(node.test, scope)) {
+    const result = evaluate(node.body, scope);
+    if (result === BREAK) {
+      if (result.LABEL === options.label) {
+        break;
+      }
+      return result;
+    } else if (result === CONTINUE) {
+      if (result.LABEL === options.label) {
+        continue;
+      }
+      return result;
+    } else if (result === RETURN) {
+      return result;
+    }
+  }
+}
+function DoWhileStatement(node, scope, options = {}) {
+  do {
+    const result = evaluate(node.body, scope);
+    if (result === BREAK) {
+      if (result.LABEL === options.label) {
+        break;
+      }
+      return result;
+    } else if (result === CONTINUE) {
+      if (result.LABEL === options.label) {
+        continue;
+      }
+      return result;
+    } else if (result === RETURN) {
+      return result;
+    }
+  } while (evaluate(node.test, scope));
+}
+function ForStatement(node, scope, options = {}) {
+  const forScope = new Scope(scope);
+  for (node.init ? evaluate(node.init, forScope) : void 0; node.test ? evaluate(node.test, forScope) : true; node.update ? evaluate(node.update, forScope) : void 0) {
+    const subScope = new Scope(forScope);
+    let result;
+    if (node.body.type === "BlockStatement") {
+      result = BlockStatement(node.body, subScope, { invasived: true });
+    } else {
+      result = evaluate(node.body, subScope);
+    }
+    if (result === BREAK) {
+      if (result.LABEL === options.label) {
+        break;
+      }
+      return result;
+    } else if (result === CONTINUE) {
+      if (result.LABEL === options.label) {
+        continue;
+      }
+      return result;
+    } else if (result === RETURN) {
+      return result;
+    }
+  }
+}
+function ForInStatement(node, scope, options = {}) {
+  for (const value in evaluate(node.right, scope)) {
+    const result = ForXHandler(node, scope, { value });
+    if (result === BREAK) {
+      if (result.LABEL === options.label) {
+        break;
+      }
+      return result;
+    } else if (result === CONTINUE) {
+      if (result.LABEL === options.label) {
+        continue;
+      }
+      return result;
+    } else if (result === RETURN) {
+      return result;
+    }
+  }
+}
+function ForOfStatement(node, scope, options = {}) {
+  const right = evaluate(node.right, scope);
+  for (const value of right) {
+    const result = ForXHandler(node, scope, { value });
+    if (result === BREAK) {
+      if (result.LABEL === options.label) {
+        break;
+      }
+      return result;
+    } else if (result === CONTINUE) {
+      if (result.LABEL === options.label) {
+        continue;
+      }
+      return result;
+    } else if (result === RETURN) {
+      return result;
+    }
+  }
+}
+
+export { BlockStatement, BreakStatement, CatchClause, ContinueStatement, DebuggerStatement, DoWhileStatement, EmptyStatement, ExpressionStatement, ForInStatement, ForOfStatement, ForStatement, IfStatement, LabeledStatement, ReturnStatement, SwitchCase, SwitchStatement, ThrowStatement, TryStatement, WhileStatement, WithStatement };

package/dist/examples/example-2.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/examples/example.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/helper-functions.d.ts

@@ -0,0 +1,15 @@
+import { Node as AcornNode } from 'acorn';
+import { default as Scope } from './scope/index.ts';
+import { SvalPlus, Reusables } from './custom-types.ts';
+export declare function isGenerator(obj: unknown): obj is Generator;
+export declare function useModifiedEvaluator(scope: Scope): boolean;
+export declare function callPerExe(interpreter: SvalPlus): void;
+export declare function cleanStack(interpreter: SvalPlus, parentReusables: Reusables): void;
+export declare function pushHandler(interpreter: SvalPlus, result: any, pushedManually: boolean): void;
+export declare function pushResult(interpreter: SvalPlus, result: any): void;
+/**It returns true if it was refreshed and false if it wasnt */
+export declare function refreshExeStack(interpreter: SvalPlus): boolean;
+export declare function callMonitor(acornNode: AcornNode, currentScope: Scope<SvalPlus>, handler: Reusables['handler']): void | import('./custom-types.ts').InspectorGenerator;
+export declare function clearEvalStack(interpreter: SvalPlus): void;
+export declare function captureReusables(interpreter: SvalPlus): Reusables;
+export declare function restoreCapturedReusables(interpreter: SvalPlus, prevReusables: Reusables): void;

package/dist/helper-functions.js

@@ -0,0 +1,104 @@
+import { UNASSIGNED, NOT_ALLOCATED } from './custom-types.js';
+
+function isGenerator(obj) {
+  return Object.prototype.toString.call(obj) === "[object Generator]";
+}
+function useModifiedEvaluator(scope) {
+  const interpreter = scope.interpreter;
+  const inUserCode = scope.scopeDepth >= 2;
+  const availableInspector = typeof interpreter.inspector === "function";
+  const use = interpreter.stage === "MONITORING" && inUserCode && availableInspector;
+  return use;
+}
+function callPerExe(interpreter) {
+  const perExe = interpreter.reusables.shared.perExe;
+  const node = interpreter.reusables.node;
+  if (perExe) {
+    perExe.fn();
+    if (perExe.owner === node) {
+      interpreter.reusables.shared.perExe = null;
+    }
+  }
+}
+function cleanStack(interpreter, parentReusables) {
+  interpreter.reusables.shared.evalStack.value -= 1;
+  const zeroNodesLeft = interpreter.reusables.shared.evalStack.value <= 0;
+  if (zeroNodesLeft) {
+    clearEvalStack(interpreter);
+  } else {
+    restoreCapturedReusables(interpreter, parentReusables);
+  }
+}
+function pushHandler(interpreter, result, pushedManually) {
+  if (!pushedManually) {
+    pushResult(interpreter, result);
+  }
+}
+function pushResult(interpreter, result) {
+  const currentEvent = interpreter.reusables.currentEvent;
+  const node = interpreter.reusables.node;
+  interpreter.reusables.shared.exeStack.unshift({
+    evaluation: result,
+    type: node.type,
+    node,
+    scope: currentEvent === NOT_ALLOCATED ? NOT_ALLOCATED : currentEvent.scope
+  });
+}
+function refreshExeStack(interpreter) {
+  const OneNodeLeft = interpreter.reusables.shared.evalStack.value <= 1;
+  if (OneNodeLeft) {
+    interpreter.reusables.shared.exeStack.clear();
+    return true;
+  }
+  return false;
+}
+function callMonitor(acornNode, currentScope, handler) {
+  const interpreter = currentScope.interpreter;
+  refreshReusables(acornNode, currentScope, handler);
+  return interpreter.inspector(interpreter.visit);
+}
+function refreshReusables(acornNode, currentScope, handler) {
+  const interpreter = currentScope.interpreter;
+  interpreter.reusables.node = acornNode;
+  interpreter.reusables.currentScope = currentScope;
+  interpreter.reusables.handler = handler;
+  interpreter.reusables.result = UNASSIGNED;
+  interpreter.reusables.currentEvent = NOT_ALLOCATED;
+}
+function clearEvalStack(interpreter) {
+  interpreter.reusables.node = null;
+  interpreter.reusables.currentScope = null;
+  interpreter.reusables.handler = null;
+  interpreter.reusables.result = UNASSIGNED;
+  interpreter.reusables.currentEvent = NOT_ALLOCATED;
+  interpreter.reusables.shared.evalStack.value = 0;
+}
+function captureReusables(interpreter) {
+  return {
+    node: interpreter.reusables.node,
+    currentScope: interpreter.reusables.currentScope,
+    handler: interpreter.reusables.handler,
+    result: interpreter.reusables.result,
+    currentEvent: interpreter.reusables.currentEvent,
+    shared: {
+      evalStack: interpreter.reusables.shared.evalStack,
+      //the eval stack variable is a global tracker.so it cant be cleared or reset in local functions.
+      exeStack: interpreter.reusables.shared.exeStack,
+      readonlyExeStack: interpreter.reusables.shared.readonlyExeStack,
+      perExe: interpreter.reusables.shared.perExe
+    }
+  };
+}
+function restoreCapturedReusables(interpreter, prevReusables) {
+  interpreter.reusables.node = prevReusables.node;
+  interpreter.reusables.currentScope = prevReusables.currentScope;
+  interpreter.reusables.handler = prevReusables.handler;
+  interpreter.reusables.result = prevReusables.result;
+  interpreter.reusables.currentEvent = prevReusables.currentEvent;
+  interpreter.reusables.shared.evalStack = prevReusables.shared.evalStack;
+  interpreter.reusables.shared.exeStack = prevReusables.shared.exeStack;
+  interpreter.reusables.shared.readonlyExeStack = prevReusables.shared.readonlyExeStack;
+  interpreter.reusables.shared.perExe = prevReusables.shared.perExe;
+}
+
+export { callMonitor, callPerExe, captureReusables, cleanStack, clearEvalStack, isGenerator, pushHandler, pushResult, refreshExeStack, restoreCapturedReusables, useModifiedEvaluator };

package/dist/index.d.ts

@@ -0,0 +1,55 @@
+import { Inspector, Fn, OnStep } from './custom-types.ts';
+export interface Metadata<T extends Fn> {
+    /**the reference to the function to be included in the interpreter context**/
+    ref: T;
+    /**
+     *Because the function runs in an isolated interpreter context,any data that it uses from the outside scope has to captured by mapping the variable names to their variables and passing the object here.
+     *It is important to keep in mind that the captures object itself follows the semantic of copy primitives by value and copy obects by reference.
+    */
+    captures?: Record<string, any>;
+}
+export interface MonitorFnSetup<T extends Fn> {
+    /**The configuration for the main function to monitor */
+    main: Metadata<T>;
+    /**
+     * If the main function calls another function outside of its scope,this is an alternative to capturing it by reference.
+     * Unlike reference capturing,this directly include a function's source code in the same interpreter context as the main function being monitored.It can also state its own captures as well or use other embedded functions.
+    */
+    embed?: Record<string, Metadata<Fn>>;
+    /**
+     * The main hook that gets fed the interpreter's context as the function executes.The visit object is rich enough to inspect nodes and their scope,modify them before execution and execute nodes manually to see and change their results.
+    */
+    inspector?: Inspector;
+    /**
+     *Like the inspector hook,this is called before each interpreted step.but it does not get the rich visit object to inspect or modify nodes
+     *Using this hook alone without the inspector will make the interpreter significantly faster because it removes all the allocations it will need to create the tools for the visit object
+     *Even without node information,it is useful for setting timers on the interpreted code by checking against a time after a number of steps.
+     *If the use case above is enough,use this hook and leave the inspector as undefined.Else,including the inspector,even as a no-op function,will cause several unnecessary allocations
+    */
+    onStep?: OnStep;
+    /**It takes an object with a value property and overwrites it with the generated code used in the interpreter for a specific monitored function.It includes the code for all embedded functions as well */
+    sourceOut?: {
+        value: string;
+    };
+    /**
+     * The hook that is called before each call to the monitored function
+     * It gets the arguments passed to the function from the caller.It is useful for logging or inspecting the args before execution
+    */
+    beforeEachCall?: (...args: Parameters<T>) => void;
+    /**
+     *The hook that is called after each call to the monitored function
+     *It gets the result returned from the function or an error if an error was thrown in the function.
+     */
+    afterEachCall?: (result: ReturnType<T> | Error) => void;
+}
+/**
+ * This function is the only export you need to get started.It accepts a brief config that includes a function and returns a new function that can be called exactly as the original.But it is executed by a custom interpreter rather than your js engine directly.
+ * The major advantage you get is that you can inject hooks at any part of the function's lifecyle and they are treated as first class citizens by the interpreter.Essentially making it a white-box.
+*/
+export declare function monitor<T extends Fn>(setup: MonitorFnSetup<T>): T & {
+    alreadyMonitored: true;
+};
+export { Var } from './scope/variable.ts';
+export { QList, ReadonlyQList } from './q-list.ts';
+export type { Inspector, OnStep, VariableForEvent, ScopeForEvent, Query, EventMap, Visit, InspectorGenerator, ExeResult, EsNode, } from './custom-types.ts';
+export { NOT_ALLOCATED, LAZY_NODE, LangEvent, BinaryExprEvent, CallExprEvent, AssignmentExprEvent, UpdateExprEvent, LogicalExprEvent, MemberExprEvent, AwaitExprEvent, FuncExprEvent, NewExprEvent, ArrowFnExprEvent, TernaryExprEvent, YieldExprEvent, ExpressionStmtEvent, ArrayExprEvent, ObjectExprEvent, TemplateLiteralEvent, SequenceExprEvent, UnaryExprEvent, ReturnStmtEvent, IfStmtEvent, SwitchStmtEvent, ThrowStmtEvent, TryStmtEvent, CatchClauseEvent, LabeledStmtEvent, BreakStmtEvent, ContinueStmtEvent, VarDeclEvent, FuncDeclEvent, ForStmtEvent, WhileStmtEvent, DoWhileStmtEvent, ForOfStmtEvent, ForInStmtEvent, LiteralEvent } from './custom-types.ts';