@typescript-guy/fn-monitor 1.0.0

package/dist/index.js

@@ -0,0 +1,312 @@
+import Sval from './sval.js';
+import { parse } from 'meriyah';
+import ansis from 'ansis';
+import { LRUCache } from 'lru-cache';
+import { sha256 } from 'js-sha256';
+import { UNASSIGNED, NOT_ALLOCATED, createEvent, LAZY_NODE } from './custom-types.js';
+export { ArrayExprEvent, ArrowFnExprEvent, AssignmentExprEvent, AwaitExprEvent, BinaryExprEvent, BreakStmtEvent, CallExprEvent, CatchClauseEvent, ContinueStmtEvent, DoWhileStmtEvent, ExpressionStmtEvent, ForInStmtEvent, ForOfStmtEvent, ForStmtEvent, FuncDeclEvent, FuncExprEvent, IfStmtEvent, LabeledStmtEvent, LangEvent, LiteralEvent, LogicalExprEvent, MemberExprEvent, NewExprEvent, ObjectExprEvent, ReturnStmtEvent, SequenceExprEvent, SwitchStmtEvent, TemplateLiteralEvent, TernaryExprEvent, ThrowStmtEvent, TryStmtEvent, UnaryExprEvent, UpdateExprEvent, VarDeclEvent, WhileStmtEvent, YieldExprEvent } from './custom-types.js';
+import { isGenerator, pushResult } from './helper-functions.js';
+import { ReadonlyQList, QList } from './q-list.js';
+import jsBeatutify from 'js-beautify';
+export { Var } from './scope/variable.js';
+
+class EventScope {
+  #scope;
+  parent;
+  depth;
+  variables;
+  constructor(interpreter) {
+    this.#scope = interpreter.reusables.currentScope;
+    this.parent = this.#scope.scopeParent;
+    this.depth = this.#scope.scopeDepth;
+    this.variables = {
+      search: (name) => {
+        const variable = this.#scope.find(name);
+        if (variable === null) return null;
+        const variableForEvent = { value: () => variable.get() };
+        return variableForEvent;
+      },
+      local: this.#scope.scopeContext
+    };
+  }
+}
+class Visit {
+  #interpreter;
+  constructor(interpreter) {
+    this.#interpreter = interpreter;
+  }
+  localExeStack = () => {
+    return this.#interpreter.reusables.shared.readonlyExeStack;
+  };
+  is = (query, cb) => {
+    const node = this.#interpreter.reusables.node;
+    if (query === "Any" || node.type === query) {
+      const event = createEvent(query, this.#interpreter);
+      cb(event);
+      this.#interpreter.reusables.currentEvent = event;
+    }
+  };
+  execute = () => {
+    const handler = this.#interpreter.reusables.handler;
+    if (handler !== null) {
+      if (this.#interpreter.reusables.result !== UNASSIGNED) {
+        throw new Error(ansis.red(`A node can only be executed once`));
+      }
+      this.#interpreter.reusables.result = handler(this.#interpreter.reusables.node, this.#interpreter.reusables.currentScope);
+      if (isGenerator(this.#interpreter.reusables.result)) {
+        return LAZY_NODE;
+      } else {
+        pushResult(this.#interpreter, this.#interpreter.reusables.result);
+        return this.#interpreter.reusables.result;
+      }
+    }
+  };
+  set perExecution(perExe) {
+    this.#interpreter.reusables.shared.perExe = {
+      fn: perExe,
+      owner: this.#interpreter.reusables.node
+    };
+  }
+}
+class SvalPlus extends Sval {
+  inspector = null;
+  onStep = null;
+  fnBeforeEachCall = void 0;
+  fnAfterEachCall = void 0;
+  static resultExport = SvalPlus.sha256Key("result");
+  static argsVar = SvalPlus.sha256Key("args");
+  //this can safely be static because its just used as a common name for the passed arguments.Its used in a per-instance object to ensure isolation
+  static capturesVar = SvalPlus.sha256Key("captures");
+  static fnAstCache = new LRUCache({ max: 400 });
+  astInUse = null;
+  reusables;
+  visit = new Visit(this);
+  //Even if each inspector gets a shared visit object that reflects the latest values for performance,i wont freeze its properties to allow possible external wrappers to customize it
+  stage = "IDLE";
+  static meriyahParseOptions = {
+    module: false,
+    //Since im just parsing functions,i dont need the extra overhead of a module parser
+    next: true,
+    // Modern ES support
+    loc: true,
+    // Essential for your shop.demand tracking
+    ranges: true,
+    // Good for error reporting
+    lexical: true
+    // Helps Sval understand 'let/const' vs 'var'
+  };
+  static defaultOptions = {
+    sourceType: "script",
+    //use the normalized and faster evaluator at the cost of not using esm import syntax which i dont even need anyway in a function.And some of the monitor's generated code wont even work with the modules option.This also means that the interpreter cant utilize top level await to handle async functions.It has to be done carefully in the evaluator
+    ecmaVer: 2024,
+    sandBox: true
+  };
+  constructor(args) {
+    super(args.options);
+    this.fnBeforeEachCall = args.fnBeforeEachCall;
+    this.fnAfterEachCall = args.fnAfterEachCall;
+    this.inspector = args.inspector || null;
+    this.onStep = args.onStep || null;
+    this.reusables = {
+      currentEvent: NOT_ALLOCATED,
+      currentScope: null,
+      node: null,
+      result: UNASSIGNED,
+      handler: null,
+      shared: {
+        evalStack: { value: 0 },
+        exeStack: new QList(),
+        readonlyExeStack: new ReadonlyQList(),
+        perExe: null
+      }
+    };
+    this.reusables.shared.readonlyExeStack.swapSrc(this.reusables.shared.exeStack);
+  }
+  createEventScope = () => {
+    return new EventScope(this);
+  };
+  getFnSrc(fn, capturesVar) {
+    const fnString = fn.toString();
+    const hash = SvalPlus.sha256Key(fnString);
+    const isDeclaration = /^(async\s+)?function(\s*\*|\s+|$)/.test(fnString);
+    const intermediateFn = "intermediateFn_" + hash;
+    let intermediateFnCode = "";
+    if (isDeclaration) {
+      intermediateFnCode = `
+const ${intermediateFn} = (()=>{
+                ${fnString};
+                return ${fn.name}
+            })();`;
+    } else {
+      intermediateFnCode = `
+const ${intermediateFn} = ${fnString};`;
+    }
+    const capturedKeys = capturesVar !== null ? Object.keys(this.exports[capturesVar]).sort() : [];
+    const storeCaptures = capturedKeys.length > 0 ? `
+const {${capturedKeys.join(",")}} = exports.${capturesVar};` : "";
+    const finalFnName = fn.name.length > 0 ? fn.name : "anonymousFn_" + hash;
+    const finalFnCode = `
+const ${finalFnName} = (()=>{
+            ${storeCaptures}
+            ${intermediateFnCode}
+            return ${intermediateFn};
+        })();`;
+    return {
+      fnCode: finalFnCode,
+      fnName: finalFnName
+    };
+  }
+  getFnSources(functions) {
+    let fnCode = "";
+    if (functions !== void 0) {
+      let declarations = "";
+      let assignments = "";
+      for (const [index, name] of Object.keys(functions).sort().entries()) {
+        const fn = functions[name];
+        const capturesVar = SvalPlus.sha256Key(`embeddedCaptures_${index}`);
+        this.exports[capturesVar] = fn.captures || /* @__PURE__ */ Object.create(null);
+        const fnSrc = this.getFnSrc(fn.ref, capturesVar);
+        const scopedFn = `(()=>{ 
+                    ${fnSrc.fnCode}
+                    return ${fnSrc.fnName};
+                })();`;
+        declarations += `
+var ${name};`;
+        assignments += `
+${name} = ${scopedFn};`;
+      }
+      fnCode = declarations + assignments;
+    }
+    return fnCode;
+  }
+  static sha256Key(str) {
+    return "generated_" + sha256.create().update(str).hex();
+  }
+  static getFnAst(fnSrc) {
+    const fnCodeHash = SvalPlus.sha256Key(fnSrc.fnCode);
+    const cached = SvalPlus.fnAstCache.get(fnCodeHash);
+    if (cached) {
+      return cached;
+    }
+    const fnCallString = `
+
+//This is the code that is ran each time the monitored function is called and the result is returned through the exports variable.
+
+exports.${SvalPlus.resultExport} = ${fnSrc.fnName}(...${SvalPlus.argsVar});`;
+    const fnCodeAst = parse(fnSrc.fnCode, SvalPlus.meriyahParseOptions);
+    const fnCallAst = parse(fnCallString, SvalPlus.meriyahParseOptions);
+    const ast = {
+      fnCode: fnCodeAst,
+      fnCall: fnCallAst,
+      fnCallString
+    };
+    SvalPlus.fnAstCache.set(fnCodeHash, ast);
+    return ast;
+  }
+  static refErrMsg(err) {
+    return ansis.red.underline(`
+Reference Error`) + Colors.orange(`
+-Monitored functions cannot access data outside the isolated interpreter.
+
+-The data must be either be passed as an argument on each call,captured into the monitored fn upon creation or embedded through the embed property when calling monitor.fn(). (inlining only works for functions).
+
+-Captured variables are handled outside the interpreter and thus,outside the monitor's tracking system but embedded functions can be monitored.`) + ansis.red.underline(`
+
+Trace`) + `
+${err}`;
+  }
+  argImports = {
+    [SvalPlus.argsVar]: null
+    //we firstly set it to null to prevent creating a wasted empty object
+  };
+  normalizeErr(err) {
+    if (err instanceof ReferenceError) {
+      err.message = SvalPlus.refErrMsg(err);
+      return err;
+    } else {
+      const error = err instanceof Error ? err : new Error(String(err));
+      error.message = ansis.red.underline(`
+Error in Monitored Function:`) + `
+${error.message}`;
+      return error;
+    }
+  }
+  runMonitoredFn = (...args) => {
+    this.stage = "MONITORING";
+    let result;
+    if (this.fnBeforeEachCall !== void 0) {
+      this.fnBeforeEachCall(...args);
+    }
+    this.argImports[SvalPlus.argsVar] = args;
+    this.import(this.argImports);
+    try {
+      this.run(this.astInUse.fnCall);
+      result = this.exports[SvalPlus.resultExport];
+    } catch (err) {
+      result = this.normalizeErr(err);
+    }
+    if (result instanceof Promise) {
+      return result.then((res) => {
+        if (this.fnAfterEachCall) this.fnAfterEachCall(res);
+        return res;
+      }).catch((err) => {
+        const error = this.normalizeErr(err);
+        if (this.fnAfterEachCall) this.fnAfterEachCall(error);
+        throw error;
+      }).finally(() => {
+        this.stage = "IDLE";
+      });
+    } else {
+      try {
+        if (this.fnAfterEachCall !== void 0) this.fnAfterEachCall(result);
+        if (result instanceof Error) throw result;
+        return result;
+      } finally {
+        this.stage = "IDLE";
+      }
+    }
+  };
+}
+const Colors = {
+  orange: ansis.hex("#f6c098")
+};
+function monitor(setup) {
+  const { ref: mainFn, captures } = setup.main;
+  if ("alreadyMonitored" in mainFn) {
+    throw new Error(ansis.red(`
+A monitored function cannot be monitored.`));
+  }
+  const {
+    embed: functionsToEmbed,
+    inspector,
+    onStep,
+    beforeEachCall,
+    afterEachCall,
+    sourceOut
+  } = setup;
+  const interpreter = new SvalPlus({
+    inspector,
+    onStep,
+    fnBeforeEachCall: beforeEachCall,
+    fnAfterEachCall: afterEachCall,
+    options: SvalPlus.defaultOptions
+  });
+  interpreter.stage = "PRE-PROCESSING";
+  interpreter.exports[SvalPlus.capturesVar] = captures || /* @__PURE__ */ Object.create(null);
+  const fnSrc = interpreter.getFnSrc(mainFn, SvalPlus.capturesVar);
+  fnSrc.fnCode += interpreter.getFnSources(functionsToEmbed);
+  const ast = SvalPlus.getFnAst(fnSrc);
+  interpreter.run(ast.fnCode);
+  if (sourceOut) {
+    sourceOut.value = jsBeatutify(
+      fnSrc.fnCode + ast.fnCallString,
+      { indent_size: 4 }
+    );
+  }
+  interpreter.astInUse = ast;
+  const newFn = interpreter.runMonitoredFn;
+  newFn["alreadyMonitored"] = true;
+  return newFn;
+}
+
+export { LAZY_NODE, NOT_ALLOCATED, QList, ReadonlyQList, monitor };

package/dist/q-list.d.ts

@@ -0,0 +1,39 @@
+/**A custom optimized dequeue with the random access of an array in one data structure */
+export declare class QList<T> {
+    private static readonly EDGE_OF_HEAD;
+    private static readonly LEFT_SHIFT;
+    private static readonly RIGHT_SHIFT;
+    private static readonly LEAST_ARRAY_LENGTH;
+    private static readonly MAX_HEAD_TO_TAIL_RATIO;
+    private static readonly MEDIUM_ARRAY_SIZE;
+    private arr;
+    private start;
+    constructor(init?: T[]);
+    private tailSize;
+    private expand;
+    push(element: T): void;
+    unshift(element: T): void;
+    private minimize;
+    pop(): T | undefined;
+    shift(): T | undefined;
+    clear(): void;
+    private validateIndex;
+    /**Get the element at the specified index.It can accept negative indices like the at method of an array */
+    get(i: number): T;
+    /**Setthe specified index to an element.It can accept negative indices*/
+    set(i: number, element: T): undefined;
+    [Symbol.iterator](): Generator<T, void, unknown>;
+    entries(): Generator<[number, T], void, unknown>;
+    get length(): number;
+}
+/**A sub-version of the QList that removes mutation. */
+export declare class ReadonlyQList<T> {
+    private qList;
+    constructor(qList?: QList<T>);
+    private getQList;
+    swapSrc(newQList: QList<T>): void;
+    get(i: number): T;
+    [Symbol.iterator](): Generator<T, void, unknown>;
+    entries(): Generator<[number, T], void, unknown>;
+    get length(): number;
+}

package/dist/q-list.js

@@ -0,0 +1,146 @@
+import ansis from 'ansis';
+
+class QList {
+  static EDGE_OF_HEAD = 0;
+  static LEFT_SHIFT = -1;
+  static RIGHT_SHIFT = 1;
+  static LEAST_ARRAY_LENGTH = 5;
+  static MAX_HEAD_TO_TAIL_RATIO = 2;
+  static MEDIUM_ARRAY_SIZE = 50;
+  arr = [];
+  start = QList.EDGE_OF_HEAD;
+  constructor(init) {
+    if (init) {
+      for (const element of init) {
+        this.push(element);
+      }
+    }
+  }
+  //HELPERS
+  tailSize() {
+    return this.arr.length - this.start;
+  }
+  //ADDING ITEMS
+  expand(size) {
+    const TAIL_SIZE = this.tailSize();
+    const newArrSize = size + TAIL_SIZE;
+    const newArr = new Array(newArrSize);
+    for (let i = 0; i < TAIL_SIZE; i++) {
+      newArr[size + i] = this.arr[this.start + i];
+    }
+    this.arr = newArr;
+    this.start = size;
+  }
+  push(element) {
+    this.arr[this.arr.length] = element;
+  }
+  unshift(element) {
+    if (this.start === QList.EDGE_OF_HEAD) {
+      const HALF_THE_TAIL_SIZE = this.tailSize() / 2;
+      const EXPANSION_SIZE = Math.max(Math.ceil(HALF_THE_TAIL_SIZE), QList.LEAST_ARRAY_LENGTH);
+      this.expand(EXPANSION_SIZE);
+    }
+    this.start += QList.LEFT_SHIFT;
+    this.arr[this.start] = element;
+  }
+  //REMOVING ITEMS
+  minimize() {
+    if (this.arr.length > QList.MEDIUM_ARRAY_SIZE) {
+      const HEAD_SIZE = this.start;
+      const TAIL_SIZE = Math.max(this.tailSize(), 1);
+      if (HEAD_SIZE / TAIL_SIZE >= QList.MAX_HEAD_TO_TAIL_RATIO) {
+        const NEW_EDGE_OF_HEAD = HEAD_SIZE - TAIL_SIZE;
+        this.arr = this.arr.slice(NEW_EDGE_OF_HEAD);
+        this.start = HEAD_SIZE - NEW_EDGE_OF_HEAD;
+      }
+    }
+  }
+  pop() {
+    if (this.tailSize() === 0) return void 0;
+    const element = this.arr[this.arr.length - 1];
+    this.arr.length = this.arr.length - 1;
+    this.minimize();
+    return element;
+  }
+  shift() {
+    if (this.tailSize() === 0) return void 0;
+    const element = this.arr[this.start];
+    this.arr[this.start] = void 0;
+    this.start += QList.RIGHT_SHIFT;
+    this.minimize();
+    return element;
+  }
+  clear() {
+    this.arr = new Array(QList.LEAST_ARRAY_LENGTH);
+    this.start = QList.LEAST_ARRAY_LENGTH;
+  }
+  //RANDOM ACCESS
+  validateIndex(i) {
+    const TAIL_SIZE = this.tailSize();
+    if (i < 0 || i >= TAIL_SIZE || TAIL_SIZE === 0) {
+      throw new Error(ansis.red(`
+Invalid random access in QList. Index ${i} not available (length: ${this.tailSize()})`));
+    }
+  }
+  /**Get the element at the specified index.It can accept negative indices like the at method of an array */
+  get(i) {
+    i = i < 0 ? this.length + i : i;
+    this.validateIndex(i);
+    const index = this.start + i;
+    return this.arr[index];
+  }
+  /**Setthe specified index to an element.It can accept negative indices*/
+  set(i, element) {
+    i = i < 0 ? this.length + i : i;
+    this.validateIndex(i);
+    const index = this.start + i;
+    this.arr[index] = element;
+  }
+  //GETTERS
+  *[Symbol.iterator]() {
+    for (let i = 0; i < this.tailSize(); i++) {
+      yield this.get(i);
+    }
+  }
+  *entries() {
+    for (let i = 0; i < this.tailSize(); i++) {
+      yield [i, this.get(i)];
+    }
+  }
+  get length() {
+    return this.tailSize();
+  }
+}
+class ReadonlyQList {
+  qList;
+  constructor(qList) {
+    this.qList = qList;
+  }
+  getQList() {
+    if (this.qList === void 0) {
+      throw new Error(ansis.red(`ReadonlyQList Error:Cannot use this method because the object was not given a src qList.`));
+    }
+    return this.qList;
+  }
+  swapSrc(newQList) {
+    this.qList = newQList;
+  }
+  get(i) {
+    const qList = this.getQList();
+    return qList.get(i);
+  }
+  *[Symbol.iterator]() {
+    const qList = this.getQList();
+    yield* qList;
+  }
+  *entries() {
+    const qList = this.getQList();
+    yield* qList.entries();
+  }
+  get length() {
+    const qList = this.getQList();
+    return qList.length;
+  }
+}
+
+export { QList, ReadonlyQList };

package/dist/scope/index.d.ts

@@ -0,0 +1,81 @@
+import { Variable, Var } from './variable.ts';
+/**
+ * Scope simulation class
+ */
+export default class Scope<T = any> {
+    /**
+     * The parent scope along the scope chain
+     * @private
+     * @readonly
+     */
+    private readonly parent;
+    /**
+     * To distinguish function scope and block scope
+     * The value is true for function scope or false for block scope
+     * @private
+     * @readonly
+     */
+    private readonly isolated;
+    /**
+     * Context simulation object
+     * @private
+     * @readonly
+     */
+    private readonly context;
+    /**
+     * To memoize the object for with-statement context
+     * @private
+     */
+    private withContext;
+    /**
+     * Create a simulated scope
+     * @param parent the parent scope along the scope chain (default: null)
+     * @param isolated true for function scope or false for block scope (default: false)
+     */
+    interpreter: T | undefined;
+    constructor(parent: Scope | null, isolated?: boolean, interpreter?: T);
+    hasParent(): boolean;
+    get scopeContext(): {
+        [key: string]: Var;
+    };
+    get scopeParent(): Scope<any>;
+    get scopeDepth(): number;
+    /**
+     * Get global scope
+     */
+    global(): Scope;
+    /**
+     * Find a variable along scope chain
+     * @param name variable identifier name
+     */
+    find(name: string): Variable | null;
+    /**
+     * Declare a var variable
+     * @param name variable identifier name
+     * @param value variable value
+     */
+    var(name: string, value?: any): void;
+    /**
+     * Declare a let variable
+     * @param name variable identifier name
+     * @param value variable value
+     */
+    let(name: string, value: any): void;
+    /**
+     * Declare a const variable
+     * @param name variable identifier name
+     * @param value variable value
+     */
+    const(name: string, value: any): void;
+    /**
+     * Declare a function
+     * @param name function name
+     * @param value function
+     */
+    func(name: string, value: any): void;
+    /**
+     * Memoize the object for with-statement context
+     * @param value object
+     */
+    with(value: any): void;
+}