littlewing 1.1.1 → 1.3.0

package/README.md

@@ -25,11 +25,12 @@ evaluate("score = 85; grade = score >= 90 ? 100 : 90", {
 - **Numbers-only** - Every value is a number. Simple, predictable, fast.
 - **Zero dependencies** - 7.8 KB gzipped, perfect for browser bundles
 - **O(n) performance** - Linear time parsing and execution
-- **Safe evaluation** - No eval(), no code generation, no security risks
+- **JIT compiler** - Optional compilation for 3-4x faster repeated execution
+- **Safe evaluation** - Tree-walk interpreter requires no code generation
 - **Timestamp arithmetic** - Built-in date/time functions using numeric timestamps
 - **Extensible** - Add custom functions and variables via context
 - **Type-safe** - Full TypeScript support with strict types
-- **Excellent test coverage** - 502 tests with 99.45% function coverage, 98.57% line coverage
+- **Excellent test coverage** - 607 tests with 99.45% function coverage, 98.57% line coverage
 
 ## Installation
 
@@ -174,6 +175,46 @@ evaluate(ast); // → 4
 evaluate(ast); // → 4 (no re-parsing)
 ```
 
+#### `compile(input: string | ASTNode): CompiledExpression`
+
+Compile source code or AST to a JavaScript function for faster repeated execution. Best for hot paths where the same expression is evaluated many times.
+
+```typescript
+import { compile } from "littlewing";
+
+// Compile once
+const expr = compile("x * 2 + y");
+
+// Execute many times with different contexts (5-10x faster than evaluate)
+expr.execute({ variables: { x: 10, y: 5 } }); // → 25
+expr.execute({ variables: { x: 20, y: 3 } }); // → 43
+expr.execute({ variables: { x: 30, y: 1 } }); // → 61
+
+// Inspect generated JavaScript code
+console.log(expr.source); // Shows generated code for debugging
+```
+
+**Performance (repeated execution after compilation):**
+
+- Small scripts: **22.8x faster** (330.62 ns → 14.50 ns per execution)
+- Medium scripts: **12.3x faster** (1.94 µs → 157.66 ns per execution)
+- Large scripts: **99.9x faster** (9.13 µs → 91.39 ns per execution)
+
+**Important:** Compilation has overhead. For one-time execution, use `evaluate()` instead:
+
+- Small: `evaluate()` is 3.7x faster (1.43 µs vs 5.26 µs including compilation)
+- Medium: `evaluate()` is 2.5x faster (7.13 µs vs 17.76 µs including compilation)
+- Large: `evaluate()` is 1.7x faster (42.80 µs vs 71.73 µs including compilation)
+
+**CompiledExpression interface:**
+
+```typescript
+interface CompiledExpression {
+	execute(context?: ExecutionContext): number;
+	source: string; // Generated JavaScript code
+}
+```
+
 #### `parse(source: string): ASTNode`
 
 Parse source into an Abstract Syntax Tree without evaluating. Useful for parse-once, execute-many scenarios.
@@ -415,7 +456,9 @@ The `defaultContext` includes these built-in functions:
 
 ## Performance Optimization
 
-For expressions that are executed multiple times with different contexts, parse once and reuse the AST:
+### Parse Once, Evaluate Many
+
+For expressions executed multiple times, parse once and reuse the AST:
 
 ```typescript
 import { evaluate, parse } from "littlewing";
@@ -437,6 +480,57 @@ evaluate(formula, {
 // This avoids lexing and parsing overhead on every execution
 ```
 
+### JIT Compilation for Maximum Performance
+
+For hot paths where the same expression is evaluated hundreds or thousands of times, use the JIT compiler:
+
+```typescript
+import { compile } from "littlewing";
+
+// Compile once (generates optimized JavaScript function)
+const formula = compile("price * quantity * (1 - discount) * (1 + taxRate)");
+
+// Execute many times with different contexts (5-10x faster than tree-walk interpreter)
+formula.execute({
+	variables: { price: 10, quantity: 5, discount: 0.1, taxRate: 0.08 },
+});
+formula.execute({
+	variables: { price: 20, quantity: 3, discount: 0.15, taxRate: 0.08 },
+});
+formula.execute({
+	variables: { price: 15, quantity: 10, discount: 0.2, taxRate: 0.08 },
+});
+```
+
+**When to use JIT:**
+
+- ✅ Same expression evaluated 10+ times with different variables
+- ✅ Large scripts (>50 lines)
+- ✅ Performance-critical loops
+- ✅ Long-running applications that amortize compilation cost
+
+**When to use tree-walk interpreter:**
+
+- ✅ One-time or infrequent evaluation
+- ✅ Small scripts (<10 lines)
+- ✅ Compilation time matters more than execution speed
+
+**Performance comparison:**
+
+Execution time only (after compilation):
+
+- Small scripts: JIT is **22.8x faster** (330.62 ns → 14.50 ns per execution)
+- Medium scripts: JIT is **12.3x faster** (1.94 µs → 157.66 ns per execution)
+- Large scripts: JIT is **99.9x faster** (9.13 µs → 91.39 ns per execution)
+
+Full pipeline (including compilation overhead):
+
+- Small scripts: `evaluate()` is **3.7x faster** (1.43 µs vs 5.26 µs)
+- Medium scripts: `evaluate()` is **2.5x faster** (7.13 µs vs 17.76 µs)
+- Large scripts: `evaluate()` is **1.7x faster** (42.80 µs vs 71.73 µs)
+
+See [JIT_IMPLEMENTATION.md](./JIT_IMPLEMENTATION.md) for detailed performance analysis and usage patterns.
+
 ## Use Cases
 
 - **User-defined formulas** - Let users write safe arithmetic expressions

package/dist/index.d.ts

@@ -207,6 +207,22 @@ declare function getNodeName(node: ASTNode): string;
 */
 declare function extractInputVariables(ast: ASTNode): string[];
 /**
+* Extracts the names of all assigned variables from an AST.
+*
+* Walks the AST and collects the left-hand side name from every
+* `Assignment` node. Returns deduplicated names in definition order.
+*
+* @param ast - The AST to analyze (can be a single statement or Program node)
+* @returns Array of assigned variable names in definition order
+*
+* @example
+* ```typescript
+* const node = parse('totalTime = hours * 60; hoursRecovered = saved / 60')
+* extractAssignedVariables(node) // ['totalTime', 'hoursRecovered']
+* ```
+*/
+declare function extractAssignedVariables(ast: ASTNode): string[];
+/**
 * Generate source code from an AST node
 */
 declare function generate(node: ASTNode): string;
@@ -294,6 +310,85 @@ interface ExecutionContext {
 */
 declare function evaluate(input: string | ASTNode, context?: ExecutionContext): RuntimeValue;
 /**
+* Evaluate source code or AST and return the full variable scope.
+*
+* Runs the same interpreter as `evaluate()` but instead of returning
+* the last expression value, returns a record of all variables that
+* exist in scope after execution (both script-assigned and context-provided).
+*
+* @param input - Either a source code string or an AST node
+* @param context - Optional execution context with variables and functions
+* @returns Record of all variable names to their values after execution
+*
+* @example
+* ```typescript
+* const scope = evaluateScope('x = 10; y = x * 2')
+* // scope === { x: 10, y: 20 }
+* ```
+*/
+declare function evaluateScope(input: string | ASTNode, context?: ExecutionContext): Record<string, number>;
+/**
+* Compiled expression that can be executed multiple times
+* Provides faster repeated execution compared to tree-walk interpreter
+*/
+interface CompiledExpression {
+	/**
+	* Execute the compiled expression with optional context
+	* @param context - Execution context with variables and functions
+	* @returns The evaluated result
+	*/
+	execute: (context?: ExecutionContext) => RuntimeValue;
+	/**
+	* Generated JavaScript source code (for debugging and inspection)
+	*/
+	source: string;
+}
+/**
+* Compile source code or AST to a JavaScript function for faster repeated execution
+*
+* JIT compilation trades compilation time for execution speed:
+* - First call: Parse + Optimize + Compile (~10-50µs depending on size)
+* - Subsequent calls: Direct JavaScript execution (~1-5µs, 5-10x faster)
+*
+* The compiler automatically optimizes the AST before code generation:
+* - Constant folding: `2 + 3` → `5` (safe constants only)
+* - Dead code elimination: removes unused variable assignments
+* - Expression simplification: `1 ? x : y` → `x`
+*
+* Optimization is safe because:
+* - Constant folding errors (e.g., division by zero) propagate to compile-time
+* - Variables that could be external are preserved (no unsafe DCE)
+* - The optimizer respects ExecutionContext override semantics
+*
+* The compiler generates optimized JavaScript code:
+* - Uses comma operator instead of IIFEs for better performance
+* - Only initializes variables that are actually used
+* - Pre-declares temporary variables for reuse
+*
+* Best for expressions that are evaluated many times with different contexts.
+*
+* Security: Uses `new Function()` to generate executable code. Safe for trusted
+* input only. For untrusted input, use the tree-walk interpreter instead.
+*
+* @param input - Either a source code string or an AST node
+* @returns Compiled expression that can be executed multiple times
+* @throws {Error} If compilation fails or AST contains invalid operations (e.g., constant division by zero)
+*
+* @example
+* ```typescript
+* const expr = compile('x * 2 + y')
+* expr.execute({ variables: { x: 10, y: 5 } }) // 25
+* expr.execute({ variables: { x: 20, y: 3 } }) // 43
+* ```
+*
+* @example Automatic optimization
+* ```typescript
+* const expr = compile('2 + 3 * 4')  // Automatically optimized to 14
+* expr.execute() // Fast execution of pre-folded constant
+* ```
+*/
+declare function compile(input: string | ASTNode): CompiledExpression;
+/**
 * Optimize an AST using constant folding, expression simplification, and dead code elimination.
 *
 * This optimizer performs SAFE optimizations that preserve program semantics:
@@ -763,4 +858,4 @@ declare function visit<T>(node: ASTNode, visitor: Visitor<T>): T;
 * )
 */
 declare function visitPartial<T>(node: ASTNode, visitor: Partial<Visitor<T>>, defaultHandler: (node: ASTNode, recurse: (n: ASTNode) => T) => T): T;
-export { visitPartial, visit, parse, optimize, exports_math as math, isUnaryOp, isProgram, isNumberLiteral, isIdentifier, isFunctionCall, isConditionalExpression, isBinaryOp, isAssignment, humanize, generate, extractInputVariables, evaluate, defaultContext, exports_datetime as datetime, exports_ast as ast, Visitor, UnaryOp, RuntimeValue, Program, Operator, NumberLiteral, NodeKind, Identifier, HumanizeOptions, FunctionCall, ExecutionContext, ConditionalExpression, BinaryOp, Assignment, ASTNode };
+export { visitPartial, visit, parse, optimize, exports_math as math, isUnaryOp, isProgram, isNumberLiteral, isIdentifier, isFunctionCall, isConditionalExpression, isBinaryOp, isAssignment, humanize, generate, extractInputVariables, extractAssignedVariables, evaluateScope, evaluate, defaultContext, exports_datetime as datetime, compile, exports_ast as ast, Visitor, UnaryOp, RuntimeValue, Program, Operator, NumberLiteral, NodeKind, Identifier, HumanizeOptions, FunctionCall, ExecutionContext, ConditionalExpression, CompiledExpression, BinaryOp, Assignment, ASTNode };

package/dist/index.js

@@ -574,6 +574,26 @@ function extractInputVariables(ast) {
   }
   return Array.from(inputVars);
 }
+function extractAssignedVariables(ast) {
+  const seen = new Set;
+  const names = [];
+  visitPartial(ast, {
+    Program: (n, recurse) => {
+      for (const statement of n[1]) {
+        recurse(statement);
+      }
+    },
+    Assignment: (n, recurse) => {
+      const name = n[1];
+      if (!seen.has(name)) {
+        seen.add(name);
+        names.push(name);
+      }
+      recurse(n[2]);
+    }
+  }, () => {});
+  return names;
+}
 function containsVariableReference(node) {
   return collectAllIdentifiers(node).size > 0;
 }
@@ -1002,13 +1022,13 @@ function evaluateNode(node, context, variables, externalVariables) {
     Assignment: (n, recurse) => {
       const name = n[1];
       const valueNode = n[2];
+      const value = recurse(valueNode);
       if (externalVariables.has(name)) {
         const externalValue = variables.get(name);
         if (externalValue !== undefined) {
           return externalValue;
         }
       }
-      const value = recurse(valueNode);
       variables.set(name, value);
       return value;
     },
@@ -1020,12 +1040,20 @@ function evaluateNode(node, context, variables, externalVariables) {
     }
   });
 }
-function evaluate(input, context = {}) {
+function run(input, context = {}) {
   const node = typeof input === "string" ? parse(input) : input;
   const entries = Object.entries(context.variables || {});
   const variables = new Map(entries);
   const externalVariables = new Set(entries.map(([key]) => key));
-  return evaluateNode(node, context, variables, externalVariables);
+  const value = evaluateNode(node, context, variables, externalVariables);
+  return { value, variables };
+}
+function evaluate(input, context = {}) {
+  return run(input, context).value;
+}
+function evaluateScope(input, context = {}) {
+  const { variables } = run(input, context);
+  return Object.fromEntries(variables);
 }
 // src/optimizer.ts
 function eliminateDeadCode(program2) {
@@ -1039,7 +1067,7 @@ function eliminateDeadCode(program2) {
     if (i === statements.length - 1) {
       keptIndices.push(i);
       const identifiers = collectAllIdentifiers(stmt);
-      for (const id of identifiers) {
+      for (const id of Array.from(identifiers)) {
         liveVars.add(id);
       }
       continue;
@@ -1050,14 +1078,14 @@ function eliminateDeadCode(program2) {
       if (liveVars.has(name)) {
         keptIndices.push(i);
         const identifiers = collectAllIdentifiers(value);
-        for (const id of identifiers) {
+        for (const id of Array.from(identifiers)) {
           liveVars.add(id);
         }
       }
     } else {
       keptIndices.push(i);
       const identifiers = collectAllIdentifiers(stmt);
-      for (const id of identifiers) {
+      for (const id of Array.from(identifiers)) {
         liveVars.add(id);
       }
     }
@@ -1140,6 +1168,248 @@ function optimize(node) {
   }
   return folded;
 }
+
+// src/jit.ts
+function compile(input) {
+  const parsedAst = typeof input === "string" ? parse(input) : input;
+  const ast = optimize(parsedAst);
+  const jsCode = generateJavaScript(ast);
+  const fullCode = `${HELPER_FUNCTIONS}
+
+${jsCode}`;
+  const fn = new Function("__context", fullCode);
+  return {
+    execute: (context = {}) => {
+      return fn(context);
+    },
+    source: fullCode
+  };
+}
+var HELPER_FUNCTIONS = `
+// Helper function for throwing errors (avoids string concatenation overhead)
+function __throw(msg) { throw new Error(msg); }
+
+// Temporary variables for optimized operations
+let __r;      // For division/modulo right operand
+let __fn;     // For function lookup
+let __val;    // For assignment value
+`.trim();
+function generateJavaScript(node) {
+  const lines = [];
+  const assignedVars = collectAssignedVariables(node);
+  const referencedVars = collectAllIdentifiers(node);
+  const literalAssignments = collectLiteralAssignments(node);
+  lines.push("// Context accessors");
+  lines.push("const __ext = __context.variables || {};");
+  lines.push("const __fns = __context.functions || {};");
+  lines.push("const __extKeys = new Set(Object.keys(__ext));");
+  lines.push("");
+  const allVars = new Set([
+    ...Array.from(assignedVars),
+    ...Array.from(referencedVars)
+  ]);
+  if (allVars.size > 0) {
+    lines.push("// Variable declarations");
+    for (const name of Array.from(allVars)) {
+      const literalValue = literalAssignments.get(name);
+      if (literalValue !== undefined) {
+        lines.push(`let ${name} = __ext.${name} ?? ${literalValue};`);
+      } else {
+        lines.push(`let ${name} = __ext.${name};`);
+      }
+    }
+    lines.push("");
+  }
+  lines.push("// Execute program");
+  const code = compileNode(node, literalAssignments);
+  lines.push(`return ${code};`);
+  return lines.join(`
+`);
+}
+function collectAssignedVariables(node) {
+  const names = new Set;
+  visit(node, {
+    Program: (n, recurse) => {
+      for (const stmt of n[1]) {
+        recurse(stmt);
+      }
+    },
+    NumberLiteral: () => {},
+    Identifier: () => {},
+    BinaryOp: (n, recurse) => {
+      recurse(n[1]);
+      recurse(n[3]);
+    },
+    UnaryOp: (n, recurse) => {
+      recurse(n[2]);
+    },
+    FunctionCall: (n, recurse) => {
+      for (const arg of n[2]) {
+        recurse(arg);
+      }
+    },
+    Assignment: (n, recurse) => {
+      names.add(n[1]);
+      recurse(n[2]);
+    },
+    ConditionalExpression: (n, recurse) => {
+      recurse(n[1]);
+      recurse(n[2]);
+      recurse(n[3]);
+    }
+  });
+  return names;
+}
+function collectLiteralAssignments(node) {
+  const literals = new Map;
+  const nonLiterals = new Set;
+  visit(node, {
+    Program: (n, recurse) => {
+      for (const stmt of n[1]) {
+        recurse(stmt);
+      }
+    },
+    NumberLiteral: () => {},
+    Identifier: () => {},
+    BinaryOp: (n, recurse) => {
+      recurse(n[1]);
+      recurse(n[3]);
+    },
+    UnaryOp: (n, recurse) => {
+      recurse(n[2]);
+    },
+    FunctionCall: (n, recurse) => {
+      for (const arg of n[2]) {
+        recurse(arg);
+      }
+    },
+    Assignment: (n, recurse) => {
+      const name = n[1];
+      const value = n[2];
+      if (literals.has(name) || nonLiterals.has(name)) {
+        literals.delete(name);
+        nonLiterals.add(name);
+        return;
+      }
+      if (value[0] === 1 /* NumberLiteral */) {
+        const num = value[1];
+        if (Number.isNaN(num)) {
+          literals.set(name, "NaN");
+        } else if (!Number.isFinite(num)) {
+          literals.set(name, num > 0 ? "Infinity" : "-Infinity");
+        } else {
+          literals.set(name, String(num));
+        }
+      } else {
+        nonLiterals.add(name);
+        recurse(value);
+      }
+    },
+    ConditionalExpression: (n, recurse) => {
+      recurse(n[1]);
+      recurse(n[2]);
+      recurse(n[3]);
+    }
+  });
+  return literals;
+}
+function compileNode(node, literalAssignments = new Map) {
+  const compileIdentifier = (name) => {
+    if (literalAssignments.has(name)) {
+      return name;
+    }
+    return `(${name} !== undefined ? ${name} : __throw('Undefined variable: ${name}'))`;
+  };
+  return visit(node, {
+    Program: (n, recurse) => {
+      const statements = n[1];
+      if (statements.length === 0) {
+        return "0";
+      }
+      if (statements.length === 1) {
+        const stmt = statements[0];
+        return stmt ? recurse(stmt) : "0";
+      }
+      const stmts = statements.map(recurse);
+      return `(${stmts.join(", ")})`;
+    },
+    NumberLiteral: (n) => {
+      const value = n[1];
+      if (Number.isNaN(value))
+        return "NaN";
+      if (!Number.isFinite(value)) {
+        return value > 0 ? "Infinity" : "-Infinity";
+      }
+      return String(value);
+    },
+    Identifier: (n) => {
+      const name = n[1];
+      return compileIdentifier(name);
+    },
+    BinaryOp: (n, recurse) => {
+      const left = recurse(n[1]);
+      const operator = n[2];
+      const right = recurse(n[3]);
+      switch (operator) {
+        case "^":
+          return `(${left} ** ${right})`;
+        case "==":
+          return `(${left} === ${right} ? 1 : 0)`;
+        case "!=":
+          return `(${left} !== ${right} ? 1 : 0)`;
+        case "<":
+          return `(${left} < ${right} ? 1 : 0)`;
+        case ">":
+          return `(${left} > ${right} ? 1 : 0)`;
+        case "<=":
+          return `(${left} <= ${right} ? 1 : 0)`;
+        case ">=":
+          return `(${left} >= ${right} ? 1 : 0)`;
+        case "&&":
+          return `(${left} !== 0 && ${right} !== 0 ? 1 : 0)`;
+        case "||":
+          return `(${left} !== 0 || ${right} !== 0 ? 1 : 0)`;
+        case "/":
+          return `((__r = ${right}) === 0 && __throw('Division by zero'), ${left} / __r)`;
+        case "%":
+          return `((__r = ${right}) === 0 && __throw('Modulo by zero'), ${left} % __r)`;
+        default:
+          return `(${left} ${operator} ${right})`;
+      }
+    },
+    UnaryOp: (n, recurse) => {
+      const operator = n[1];
+      const arg = recurse(n[2]);
+      if (operator === "-") {
+        return `(-${arg})`;
+      }
+      if (operator === "!") {
+        return `(${arg} === 0 ? 1 : 0)`;
+      }
+      throw new Error(`Unknown unary operator: ${operator}`);
+    },
+    FunctionCall: (n, recurse) => {
+      const name = n[1];
+      const args = n[2].map(recurse);
+      const argsStr = args.length > 0 ? args.join(", ") : "";
+      return `((__fn = __fns.${name}) === undefined ? __throw('Undefined function: ${name}') : typeof __fn !== 'function' ? __throw('${name} is not a function') : __fn(${argsStr}))`;
+    },
+    Assignment: (n, recurse) => {
+      const name = n[1];
+      if (literalAssignments.has(name)) {
+        return name;
+      }
+      const value = recurse(n[2]);
+      return `((__val = ${value}), (__extKeys.has('${name}') ? ${name} : (${name} = __val)))`;
+    },
+    ConditionalExpression: (n, recurse) => {
+      const condition = recurse(n[1]);
+      const consequent = recurse(n[2]);
+      const alternate = recurse(n[3]);
+      return `(${condition} !== 0 ? ${consequent} : ${alternate})`;
+    }
+  });
+}
 // src/stdlib/datetime.ts
 var exports_datetime = {};
 __export(exports_datetime, {
@@ -1357,9 +1627,12 @@ export {
   humanize,
   generate,
   extractInputVariables,
+  extractAssignedVariables,
+  evaluateScope,
   evaluate,
   defaultContext,
   exports_datetime as datetime,
+  compile,
   exports_ast as ast,
   NodeKind
 };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "littlewing",
-	"version": "1.1.1",
+	"version": "1.3.0",
 	"description": "A minimal, high-performance arithmetic expression language with lexer, parser, and executor. Optimized for browsers with zero dependencies and type-safe execution.",
 	"keywords": [
 		"arithmetic",