littlewing 0.8.3 → 0.9.1

package/README.md

@@ -156,22 +156,38 @@ For complete language documentation including all operators, functions, and exam
 
 ### Main Functions
 
-#### `execute(source: string, context?: ExecutionContext): number`
+#### `execute(input: string | ASTNode, context?: ExecutionContext): number`
 
-Execute an expression and return the result.
+Execute an expression or AST and return the result. Accepts either a source string or a pre-parsed AST node.
 
 ```typescript
+// Execute source string directly
 execute("2 + 2"); // → 4
 execute("ABS(-5)", { functions: { ABS: Math.abs } }); // → 5
+
+// Execute pre-parsed AST (useful for parse-once, execute-many scenarios)
+const ast = parseSource("2 + 2");
+execute(ast); // → 4
+execute(ast); // → 4 (no re-parsing)
 ```
 
 #### `parseSource(source: string): ASTNode`
 
-Parse source into an Abstract Syntax Tree without executing.
+Parse source into an Abstract Syntax Tree without executing. Useful for parse-once, execute-many scenarios.
 
 ```typescript
 const ast = parseSource("2 + 3 * 4");
-// Use with Executor class or optimize() function
+
+// Execute multiple times with different contexts (no re-parsing)
+execute(ast); // → 14
+execute(ast, {
+	variables: {
+		/* ... */
+	},
+}); // → 14 (with context)
+
+// Or use with Executor class or optimize() function
+const optimized = optimize(ast);
 ```
 
 #### `optimize(node: ASTNode): ASTNode`
@@ -225,6 +241,32 @@ The `defaultContext` includes these built-in functions:
 
 **Date comparisons:** `IS_SAME_DAY`, `IS_WEEKEND`, `IS_LEAP_YEAR` (use `<`, `>`, `<=`, `>=` operators for before/after comparisons)
 
+## Performance Optimization
+
+For expressions that are executed multiple times with different contexts, parse once and reuse the AST:
+
+```typescript
+import { execute, parseSource } from "littlewing";
+
+// Parse once
+const formula = parseSource(
+	"price * quantity * (1 - discount) * (1 + taxRate)",
+);
+
+// Execute many times with different values (no re-parsing)
+execute(formula, {
+	variables: { price: 10, quantity: 5, discount: 0.1, taxRate: 0.08 },
+});
+execute(formula, {
+	variables: { price: 20, quantity: 3, discount: 0.15, taxRate: 0.08 },
+});
+execute(formula, {
+	variables: { price: 15, quantity: 10, discount: 0.2, taxRate: 0.08 },
+});
+
+// This avoids lexing and parsing overhead on every execution
+```
+
 ## Use Cases
 
 - **User-defined formulas** - Let users write safe arithmetic expressions

package/dist/index.d.ts

@@ -585,9 +585,11 @@ declare class Executor {
 	private executeConditionalExpression;
 }
 /**
-* Execute source code with given context
+* Execute source code or AST with given context
+* @param input - Either a source code string or an AST node
+* @param context - Optional execution context with variables and functions
 */
-declare function execute(source: string, context?: ExecutionContext): RuntimeValue;
+declare function execute(input: string | ASTNode, context?: ExecutionContext): RuntimeValue;
 /**
 * Lexer - converts source code into tokens
 * Implements a single-pass O(n) tokenization algorithm
@@ -659,11 +661,12 @@ declare function optimize(node: ASTNode): ASTNode;
 /**
 * Parser using Pratt parsing (top-down operator precedence)
 * Implements an efficient O(n) parsing algorithm
+* Uses lazy lexing - calls lexer on-demand instead of receiving all tokens upfront
 */
 declare class Parser {
-	private tokens;
-	private current;
-	constructor(tokens: Token[]);
+	private lexer;
+	private currentToken;
+	constructor(lexer: Lexer);
 	/**
 	* Parse tokens into an AST
 	* Supports multiple statements separated by semicolons or newlines
@@ -684,9 +687,11 @@ declare class Parser {
 	private parseFunctionArguments;
 	/**
 	* Get unary operator precedence
-	* Returns 6 which is higher than add/sub (6) but lower than exponentiation (8)
-	* This means: -2^2 parses as -(2^2) = -4, not (-2)^2 = 4
-	* Matches the behavior of Python, Ruby, and most languages
+	* Returns 7 which is higher than add/sub (6) but lower than exponentiation (8)
+	* This means:
+	* - Binds tighter than addition: -2 + 3 parses as (-2) + 3 = 1
+	* - Binds looser than exponentiation: -2^2 parses as -(2^2) = -4, not (-2)^2 = 4
+	* Matches the behavior of Python, JavaScript, and most languages
 	*/
 	private getUnaryPrecedence;
 	/**
@@ -698,7 +703,7 @@ declare class Parser {
 	*/
 	private peek;
 	/**
-	* Advance to next token
+	* Advance to next token by calling lexer
 	*/
 	private advance;
 }

package/dist/index.js

@@ -353,7 +353,7 @@ class CodeGenerator {
   generateBinaryOp(node) {
     const left = this.generate(node.left);
     const right = this.generate(node.right);
-    const leftNeedsParens = this.needsParensLeft(node.left, node.operator);
+    const leftNeedsParens = this.needsParensLeft(node.left, node.operator) || node.operator === "^" && isUnaryOp(node.left);
     const leftCode = leftNeedsParens ? `(${left})` : left;
     const rightNeedsParens = this.needsParensRight(node.right, node.operator);
     const rightCode = rightNeedsParens ? `(${right})` : right;
@@ -806,10 +806,11 @@ var BINARY_OPERATOR_TOKENS = new Set([
 ]);
 
 class Parser {
-  tokens;
-  current = 0;
-  constructor(tokens) {
-    this.tokens = tokens;
+  lexer;
+  currentToken;
+  constructor(lexer) {
+    this.lexer = lexer;
+    this.currentToken = lexer.nextToken();
   }
   parse() {
     const statements = [];
@@ -856,7 +857,8 @@ class Parser {
       } else if (this.isBinaryOperator(token.type)) {
         const operator = token.value;
         this.advance();
-        const right = this.parseExpression(precedence + 1);
+        const isRightAssociative = operator === "^";
+        const right = this.parseExpression(isRightAssociative ? precedence : precedence + 1);
         left = binaryOp(left, operator, right);
       } else {
         break;
@@ -913,29 +915,21 @@ class Parser {
     return args;
   }
   getUnaryPrecedence() {
-    return 6;
+    return 7;
   }
   isBinaryOperator(type) {
     return BINARY_OPERATOR_TOKENS.has(type);
   }
   peek() {
-    if (this.current >= this.tokens.length) {
-      return { type: "EOF" /* EOF */, value: "", position: -1 };
-    }
-    const token = this.tokens[this.current];
-    if (token === undefined) {
-      return { type: "EOF" /* EOF */, value: "", position: -1 };
-    }
-    return token;
+    return this.currentToken;
   }
   advance() {
-    this.current++;
+    this.currentToken = this.lexer.nextToken();
   }
 }
 function parseSource(source) {
   const lexer = new Lexer(source);
-  const tokens = lexer.tokenize();
-  const parser = new Parser(tokens);
+  const parser = new Parser(lexer);
   return parser.parse();
 }
 
@@ -1024,10 +1018,10 @@ class Executor {
     return condition !== 0 ? this.execute(node.consequent) : this.execute(node.alternate);
   }
 }
-function execute(source, context) {
-  const ast = parseSource(source);
+function execute(input, context) {
+  const node = typeof input === "string" ? parseSource(input) : input;
   const executor = new Executor(context);
-  return executor.execute(ast);
+  return executor.execute(node);
 }
 // src/optimizer.ts
 function optimize(node) {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "littlewing",
-	"version": "0.8.3",
+	"version": "0.9.1",
 	"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",