littlewing 0.9.5 → 1.0.0

package/README.md

@@ -3,19 +3,19 @@
 A minimal, high-performance arithmetic expression language for JavaScript. Pure numbers, zero dependencies, built for the browser.
 
 ```typescript
-import { execute, defaultContext } from "littlewing";
+import { evaluate, defaultContext } from "littlewing";
 
 // Simple arithmetic
-execute("2 + 3 * 4"); // → 14
+evaluate("2 + 3 * 4"); // → 14
 
 // Variables and functions
-execute("radius = 5; area = 3.14159 * radius ^ 2", defaultContext); // → 78.54
+evaluate("radius = 5; area = 3.14159 * radius ^ 2", defaultContext); // → 78.54
 
 // Date arithmetic with timestamps
-execute("deadline = NOW() + FROM_DAYS(7)", defaultContext); // → timestamp 7 days from now
+evaluate("deadline = NOW() + FROM_DAYS(7)", defaultContext); // → timestamp 7 days from now
 
 // Conditional logic
-execute("score = 85; grade = score >= 90 ? 100 : 90", {
+evaluate("score = 85; grade = score >= 90 ? 100 : 90", {
 	variables: { score: 85 },
 }); // → 90
 ```
@@ -29,7 +29,7 @@ execute("score = 85; grade = score >= 90 ? 100 : 90", {
 - **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** - 485 tests with 99.45% function coverage, 98.57% line coverage
+- **Excellent test coverage** - 502 tests with 99.45% function coverage, 98.57% line coverage
 
 ## Installation
 
@@ -42,77 +42,77 @@ npm install littlewing
 ### Basic Usage
 
 ```typescript
-import { execute } from "littlewing";
+import { evaluate } from "littlewing";
 
 // Arithmetic expressions
-execute("2 + 3 * 4"); // → 14
-execute("10 ^ 2"); // → 100
-execute("17 % 5"); // → 2
+evaluate("2 + 3 * 4"); // → 14
+evaluate("10 ^ 2"); // → 100
+evaluate("17 % 5"); // → 2
 
 // Variables
-execute("x = 10; y = 20; x + y"); // → 30
+evaluate("x = 10; y = 20; x + y"); // → 30
 
 // Comparisons (return 1 for true, 0 for false)
-execute("5 > 3"); // → 1
-execute("10 == 10"); // → 1
-execute("2 != 2"); // → 0
+evaluate("5 > 3"); // → 1
+evaluate("10 == 10"); // → 1
+evaluate("2 != 2"); // → 0
 
 // Logical operators
-execute("!0"); // → 1 (NOT)
-execute("1 && 1"); // → 1 (AND)
-execute("0 || 1"); // → 1 (OR)
-execute("!(5 > 10)"); // → 1 (negates comparison)
+evaluate("!0"); // → 1 (NOT)
+evaluate("1 && 1"); // → 1 (AND)
+evaluate("0 || 1"); // → 1 (OR)
+evaluate("!(5 > 10)"); // → 1 (negates comparison)
 
 // Ternary conditionals
-execute("age >= 18 ? 100 : 0", { variables: { age: 21 } }); // → 100
-execute("!isBlocked ? 100 : 0", { variables: { isBlocked: 0 } }); // → 100
+evaluate("age >= 18 ? 100 : 0", { variables: { age: 21 } }); // → 100
+evaluate("!isBlocked ? 100 : 0", { variables: { isBlocked: 0 } }); // → 100
 ```
 
 ### With Built-in Functions
 
 ```typescript
-import { execute, defaultContext } from "littlewing";
+import { evaluate, defaultContext } from "littlewing";
 
 // Math functions
-execute("ABS(-42)", defaultContext); // → 42
-execute("SQRT(16)", defaultContext); // → 4
-execute("MAX(3, 7, 2)", defaultContext); // → 7
+evaluate("ABS(-42)", defaultContext); // → 42
+evaluate("SQRT(16)", defaultContext); // → 4
+evaluate("MAX(3, 7, 2)", defaultContext); // → 7
 
 // Current timestamp
-execute("NOW()", defaultContext); // → 1704067200000
+evaluate("NOW()", defaultContext); // → 1704067200000
 
 // Date arithmetic
-execute("NOW() + FROM_HOURS(2)", defaultContext); // → timestamp 2 hours from now
-execute("tomorrow = NOW() + FROM_DAYS(1)", defaultContext); // → tomorrow's timestamp
+evaluate("NOW() + FROM_DAYS(7)", defaultContext); // → timestamp 7 days from now
+evaluate("tomorrow = NOW() + FROM_DAYS(1)", defaultContext); // → tomorrow's timestamp
 
 // Extract date components
 const ctx = { ...defaultContext, variables: { ts: Date.now() } };
-execute("GET_YEAR(ts)", ctx); // → 2024
-execute("GET_MONTH(ts)", ctx); // → 11
-execute("GET_DAY(ts)", ctx); // → 6
+evaluate("GET_YEAR(ts)", ctx); // → 2024
+evaluate("GET_MONTH(ts)", ctx); // → 11
+evaluate("GET_DAY(ts)", ctx); // → 6
 
 // Calculate time differences
 const ts1 = Date.now();
 const ts2 = ts1 + 1000 * 60 * 60 * 5; // 5 hours later
 const context = { ...defaultContext, variables: { ts1, ts2 } };
-execute("DIFFERENCE_IN_HOURS(ts1, ts2)", context); // → 5
+evaluate("DIFFERENCE_IN_HOURS(ts1, ts2)", context); // → 5
 
 // Date arithmetic and comparisons
-execute("ADD_DAYS(NOW(), 7)", defaultContext); // → 7 days from now
-execute("START_OF_DAY(NOW())", defaultContext); // → today at 00:00:00.000
-execute("IS_WEEKEND(NOW())", defaultContext); // → 1 if today is Sat/Sun, else 0
+evaluate("ADD_DAYS(NOW(), 7)", defaultContext); // → 7 days from now
+evaluate("START_OF_DAY(NOW())", defaultContext); // → today at 00:00:00.000
+evaluate("IS_WEEKEND(NOW())", defaultContext); // → 1 if today is Sat/Sun, else 0
 ```
 
 ### Custom Functions and Variables
 
 ```typescript
-import { execute } from "littlewing";
+import { evaluate } from "littlewing";
 
 const context = {
 	functions: {
-		// Custom functions must return numbers
-		fahrenheit: (celsius: number) => (celsius * 9) / 5 + 32,
-		discount: (price: number, percent: number) => price * (1 - percent / 100),
+		// Custom functions should use UPPERCASE naming (like built-in functions)
+		FAHRENHEIT: (celsius: number) => (celsius * 9) / 5 + 32,
+		DISCOUNT: (price: number, percent: number) => price * (1 - percent / 100),
 	},
 	variables: {
 		pi: 3.14159,
@@ -120,9 +120,9 @@ const context = {
 	},
 };
 
-execute("fahrenheit(20)", context); // → 68
-execute("discount(100, 15)", context); // → 85
-execute("100 * (1 + taxRate)", context); // → 108
+evaluate("FAHRENHEIT(20)", context); // → 68
+evaluate("DISCOUNT(100, 15)", context); // → 85
+evaluate("100 * (1 + taxRate)", context); // → 108
 ```
 
 ### External Variables Override Script Defaults
@@ -132,11 +132,11 @@ execute("100 * (1 + taxRate)", context); // → 108
 const formula = "multiplier = 2; value = 100; value * multiplier";
 
 // Without external variables: uses script defaults
-execute(formula); // → 200
+evaluate(formula); // → 200
 
 // External variables override script assignments
-execute(formula, { variables: { multiplier: 3 } }); // → 300
-execute(formula, { variables: { value: 50 } }); // → 100
+evaluate(formula, { variables: { multiplier: 3 } }); // → 300
+evaluate(formula, { variables: { value: 50 } }); // → 100
 
 // Useful for configurable formulas
 const pricing = `
@@ -146,9 +146,9 @@ const pricing = `
   finalPrice = basePrice * (1 - discount) * (1 + taxRate)
 `;
 
-execute(pricing); // → 108 (uses all defaults)
-execute(pricing, { variables: { discount: 0.1 } }); // → 97.2 (10% discount)
-execute(pricing, { variables: { basePrice: 200, discount: 0.2 } }); // → 172.8
+evaluate(pricing); // → 108 (uses all defaults)
+evaluate(pricing, { variables: { discount: 0.1 } }); // → 97.2 (10% discount)
+evaluate(pricing, { variables: { basePrice: 200, discount: 0.2 } }); // → 172.8
 ```
 
 ## Language Reference
@@ -159,51 +159,55 @@ For complete language documentation including all operators, functions, and exam
 
 ### Main Functions
 
-#### `execute(input: string | ASTNode, context?: ExecutionContext): number`
+#### `evaluate(input: string | ASTNode, context?: ExecutionContext): number`
 
-Execute an expression or AST and return the result. Accepts either a source string or a pre-parsed AST node.
+Evaluate 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)
+// Evaluate source string directly
+evaluate("2 + 2"); // → 4
+evaluate("ABS(-5)", { functions: { ABS: Math.abs } }); // → 5
+
+// Evaluate pre-parsed AST (useful for parse-once, evaluate-many scenarios)
+const ast = parse("2 + 2");
+evaluate(ast); // → 4
+evaluate(ast); // → 4 (no re-parsing)
 ```
 
-#### `parseSource(source: string): ASTNode`
+#### `parse(source: string): ASTNode`
 
-Parse source into an Abstract Syntax Tree without executing. Useful for parse-once, execute-many scenarios.
+Parse source into an Abstract Syntax Tree without evaluating. Useful for parse-once, execute-many scenarios.
 
 ```typescript
-const ast = parseSource("2 + 3 * 4");
+const ast = parse("2 + 3 * 4");
 
-// Execute multiple times with different contexts (no re-parsing)
-execute(ast); // → 14
-execute(ast, {
+// Evaluate multiple times with different contexts (no re-parsing)
+evaluate(ast); // → 14
+evaluate(ast, {
 	variables: {
 		/* ... */
 	},
 }); // → 14 (with context)
 
-// Or use with Executor class or optimize() function
+// Or use with optimize() function
 const optimized = optimize(ast);
 ```
 
 #### `optimize(node: ASTNode): ASTNode`
 
-Optimize an AST by folding constants. Safe for use with external variables.
+Optimize an AST with constant folding and dead code elimination. Safe for use with external variables.
 
 ```typescript
-const ast = parseSource("2 + 3 * 4");
+const ast = parse("2 + 3 * 4");
 const optimized = optimize(ast); // → NumberLiteral(14)
 
 // Variables are NOT folded (can be overridden by context)
-const ast2 = parseSource("x = 5; x + 10");
+const ast2 = parse("x = 5; x + 10");
 const opt2 = optimize(ast2); // Still has variable reference
+
+// Dead code elimination removes unused variables
+const ast3 = parse("x = 10; y = 20; z = x * 20");
+const opt3 = optimize(ast3); // Removes unused y assignment
 ```
 
 #### `generate(node: ASTNode): string`
@@ -211,10 +215,36 @@ const opt2 = optimize(ast2); // Still has variable reference
 Convert AST back to source code.
 
 ```typescript
-const ast = parseSource("2 + 3 * 4");
+const ast = parse("2 + 3 * 4");
 generate(ast); // → "2 + 3 * 4"
 ```
 
+#### `humanize(node: ASTNode, options?: HumanizeOptions): string`
+
+Convert AST to human-readable English text.
+
+```typescript
+const ast = parse("x + 10");
+humanize(ast); // → "x plus 10"
+
+// With HTML output
+humanize(ast, { html: true }); // → "<span class='identifier'>x</span> plus <span class='number'>10</span>"
+```
+
+#### `extractInputVariables(ast: ASTNode): string[]`
+
+Extract all variable identifiers that are assigned to constant values (literals, constant expressions, or function calls with constant arguments). Variables computed from other variables are excluded.
+
+```typescript
+const ast = parse("price = 100; tax = price * 0.08");
+extractInputVariables(ast); // → ["price"]
+// 'tax' is excluded because it's computed from 'price'
+
+const ast2 = parse("x = 10; y = 20; sum = x + y");
+extractInputVariables(ast2); // → ["x", "y"]
+// 'sum' is excluded because it's computed from 'x' and 'y'
+```
+
 ### AST Visitor Pattern
 
 The visitor pattern provides a centralized, type-safe way to traverse and transform ASTs. This is useful for implementing custom analyzers, transformers, or code generators.
@@ -224,49 +254,54 @@ The visitor pattern provides a centralized, type-safe way to traverse and transf
 Exhaustively visit every node in an AST. All node types must be handled.
 
 ```typescript
-import { visit, parseSource } from "littlewing";
+import { visit, parse } from "littlewing";
 
-const ast = parseSource("x = 5; x + 10");
+const ast = parse("x = 5; x + 10");
 
 // Count all identifiers in an AST
 const count = visit(ast, {
-	Program: (n, recurse) => n.body.reduce((sum, stmt) => sum + recurse(stmt), 0),
+	Program: (n, recurse) =>
+		n.statements.reduce((sum, stmt) => sum + recurse(stmt), 0),
 	NumberLiteral: () => 0,
 	Identifier: () => 1,
 	BinaryOp: (n, recurse) => recurse(n.left) + recurse(n.right),
-	UnaryOp: (n, recurse) => recurse(n.operand),
+	UnaryOp: (n, recurse) => recurse(n.argument),
 	Assignment: (n, recurse) => 1 + recurse(n.value),
 	FunctionCall: (n, recurse) =>
 		1 + n.arguments.reduce((sum, arg) => sum + recurse(arg), 0),
-	Ternary: (n, recurse) =>
+	ConditionalExpression: (n, recurse) =>
 		recurse(n.condition) + recurse(n.consequent) + recurse(n.alternate),
 }); // → 3 (x appears 3 times)
 ```
 
-#### `visitPartial<T>(node: ASTNode, visitor: Partial<Visitor<T>>): T | undefined`
+#### `visitPartial<T>(node: ASTNode, visitor: Partial<Visitor<T>>, defaultHandler: (node: ASTNode, recurse: (n: ASTNode) => T) => T): T`
 
-Visit only specific node types. Unhandled nodes return `undefined` and stop recursion.
+Visit only specific node types. The `defaultHandler` is called for unhandled node types.
 
 ```typescript
-import { visitPartial, parseSource } from "littlewing";
+import { visitPartial, parse } from "littlewing";
 
-const ast = parseSource("x = 5; y = x + 10; y * 2");
+const ast = parse("x = 5; y = x + 10; y * 2");
 
 // Find first assignment to a specific variable
-const result = visitPartial(ast, {
-	Program: (n, recurse) => {
-		for (const stmt of n.body) {
-			const found = recurse(stmt);
-			if (found !== undefined) return found;
-		}
-		return undefined;
+const result = visitPartial(
+	ast,
+	{
+		Program: (n, recurse) => {
+			for (const stmt of n.statements) {
+				const found = recurse(stmt);
+				if (found !== undefined) return found;
+			}
+			return undefined;
+		},
+		Assignment: (n, recurse) => {
+			if (n.name === "y") return n; // Found it!
+			return recurse(n.value); // Keep searching
+		},
+		BinaryOp: (n, recurse) => recurse(n.left) ?? recurse(n.right),
 	},
-	Assignment: (n, recurse) => {
-		if (n.name === "y") return n; // Found it!
-		return recurse(n.value); // Keep searching
-	},
-	BinaryOp: (n, recurse) => recurse(n.left) ?? recurse(n.right),
-}); // → Assignment node for "y = x + 10"
+	() => undefined,
+); // → Assignment node for "y = x + 10"
 ```
 
 #### Transform Pattern
@@ -274,21 +309,22 @@ const result = visitPartial(ast, {
 Use `visit<ASTNode>` to create AST transformers:
 
 ```typescript
-import { visit, parseSource, ast } from "littlewing";
+import { visit, parse, ast } from "littlewing";
 
 // Double all numeric literals
-const transformed = visit<ASTNode>(parseSource("2 + 3 * 4"), {
-	Program: (n, recurse) => ast.program(n.body.map((stmt) => recurse(stmt))),
+const transformed = visit<ASTNode>(parse("2 + 3 * 4"), {
+	Program: (n, recurse) =>
+		ast.program(n.statements.map((stmt) => recurse(stmt))),
 	NumberLiteral: (n) => ast.number(n.value * 2),
 	Identifier: (n) => n,
 	BinaryOp: (n, recurse) =>
 		ast.binaryOp(recurse(n.left), n.operator, recurse(n.right)),
-	UnaryOp: (n, recurse) => ast.unaryOp(n.operator, recurse(n.operand)),
+	UnaryOp: (n, recurse) => ast.unaryOp(n.operator, recurse(n.argument)),
 	Assignment: (n, recurse) => ast.assignment(n.name, recurse(n.value)),
 	FunctionCall: (n, recurse) =>
 		ast.functionCall(n.name, n.arguments.map(recurse)),
-	Ternary: (n, recurse) =>
-		ast.ternary(
+	ConditionalExpression: (n, recurse) =>
+		ast.conditional(
 			recurse(n.condition),
 			recurse(n.consequent),
 			recurse(n.alternate),
@@ -298,11 +334,34 @@ const transformed = visit<ASTNode>(parseSource("2 + 3 * 4"), {
 generate(transformed); // → "4 + 6 * 8"
 ```
 
+### AST Builder Functions
+
+The `ast` namespace provides builder functions for constructing AST nodes manually:
+
+```typescript
+import { ast, generate } from "littlewing";
+
+// Core builders
+const node = ast.binaryOp(ast.number(2), "+", ast.number(3));
+generate(node); // → "2 + 3"
+
+// Convenience builders
+const expr = ast.add(ast.identifier("x"), ast.number(10));
+generate(expr); // → "x + 10"
+```
+
+**Available builders:**
+
+- Core: `program()`, `number()`, `identifier()`, `binaryOp()`, `unaryOp()`, `functionCall()`, `assignment()`, `conditional()`
+- Arithmetic: `add()`, `subtract()`, `multiply()`, `divide()`, `modulo()`, `exponentiate()`, `negate()`
+- Comparison: `equals()`, `notEquals()`, `lessThan()`, `greaterThan()`, `lessEqual()`, `greaterEqual()`
+- Logical: `logicalAnd()`, `logicalOr()`, `logicalNot()`
+
 ### ExecutionContext
 
 ```typescript
 interface ExecutionContext {
-	functions?: Record<string, (...args: any[]) => number>;
+	functions?: Record<string, (...args: number[]) => number>;
 	variables?: Record<string, number>;
 }
 ```
@@ -311,42 +370,44 @@ interface ExecutionContext {
 
 The `defaultContext` includes these built-in functions:
 
-**Math:** `ABS`, `CEIL`, `FLOOR`, `ROUND`, `SQRT`, `MIN`, `MAX`, `CLAMP`, `SIN`, `COS`, `TAN`, `LOG`, `LOG10`, `EXP`
+**Math (14 functions):** `ABS`, `CEIL`, `FLOOR`, `ROUND`, `SQRT`, `MIN`, `MAX`, `CLAMP`, `SIN`, `COS`, `TAN`, `LOG`, `LOG10`, `EXP`
+
+**Timestamps (2 functions):** `NOW`, `DATE`
+
+**Time converters (4 functions, to milliseconds):** `FROM_DAYS`, `FROM_WEEKS`, `FROM_MONTHS`, `FROM_YEARS`
 
-**Timestamps:** `NOW`, `DATE`
+**Date component extractors (10 functions):** `GET_YEAR`, `GET_MONTH`, `GET_DAY`, `GET_HOUR`, `GET_MINUTE`, `GET_SECOND`, `GET_WEEKDAY`, `GET_MILLISECOND`, `GET_DAY_OF_YEAR`, `GET_QUARTER`
 
-**Time converters (to milliseconds):** `FROM_DAYS`, `FROM_WEEKS`, `FROM_MONTHS`, `FROM_YEARS`
+**Time differences (7 functions, always positive):** `DIFFERENCE_IN_SECONDS`, `DIFFERENCE_IN_MINUTES`, `DIFFERENCE_IN_HOURS`, `DIFFERENCE_IN_DAYS`, `DIFFERENCE_IN_WEEKS`, `DIFFERENCE_IN_MONTHS`, `DIFFERENCE_IN_YEARS`
 
-**Date component extractors:** `GET_YEAR`, `GET_MONTH`, `GET_DAY`, `GET_HOUR`, `GET_MINUTE`, `GET_SECOND`, `GET_WEEKDAY`, `GET_MILLISECOND`, `GET_DAY_OF_YEAR`, `GET_QUARTER`
+**Start/End of period (8 functions):** `START_OF_DAY`, `END_OF_DAY`, `START_OF_WEEK`, `START_OF_MONTH`, `END_OF_MONTH`, `START_OF_YEAR`, `END_OF_YEAR`, `START_OF_QUARTER`
 
-**Time differences (always positive):** `DIFFERENCE_IN_SECONDS`, `DIFFERENCE_IN_MINUTES`, `DIFFERENCE_IN_HOURS`, `DIFFERENCE_IN_DAYS`, `DIFFERENCE_IN_WEEKS`, `DIFFERENCE_IN_MONTHS`, `DIFFERENCE_IN_YEARS`
+**Date arithmetic (3 functions):** `ADD_DAYS`, `ADD_MONTHS`, `ADD_YEARS`
 
-**Start/End of period:** `START_OF_DAY`, `END_OF_DAY`, `START_OF_WEEK`, `START_OF_MONTH`, `END_OF_MONTH`, `START_OF_YEAR`, `END_OF_YEAR`, `START_OF_QUARTER`
+**Date comparisons (3 functions):** `IS_SAME_DAY`, `IS_WEEKEND`, `IS_LEAP_YEAR`
 
-**Date arithmetic:** `ADD_DAYS`, `ADD_MONTHS`, `ADD_YEARS`
+**Note:** For before/after comparisons, use the comparison operators directly: `ts1 < ts2`, `ts1 > ts2`, `ts1 <= ts2`, `ts1 >= ts2`
 
-**Date comparisons:** `IS_SAME_DAY`, `IS_WEEKEND`, `IS_LEAP_YEAR` (use `<`, `>`, `<=`, `>=` operators for before/after comparisons)
+**Total: 54 built-in functions**
 
 ## Performance Optimization
 
 For expressions that are executed multiple times with different contexts, parse once and reuse the AST:
 
 ```typescript
-import { execute, parseSource } from "littlewing";
+import { evaluate, parse } from "littlewing";
 
 // Parse once
-const formula = parseSource(
-	"price * quantity * (1 - discount) * (1 + taxRate)",
-);
+const formula = parse("price * quantity * (1 - discount) * (1 + taxRate)");
 
-// Execute many times with different values (no re-parsing)
-execute(formula, {
+// Evaluate many times with different values (no re-parsing)
+evaluate(formula, {
 	variables: { price: 10, quantity: 5, discount: 0.1, taxRate: 0.08 },
 });
-execute(formula, {
+evaluate(formula, {
 	variables: { price: 20, quantity: 3, discount: 0.15, taxRate: 0.08 },
 });
-execute(formula, {
+evaluate(formula, {
 	variables: { price: 15, quantity: 10, discount: 0.2, taxRate: 0.08 },
 });
 
@@ -371,7 +432,7 @@ Your app needs to evaluate user-provided formulas or dynamic expressions. Using
 
 ### The Solution
 
-Littlewing provides just enough: arithmetic expressions with variables and functions. It's safe (no code execution), fast (linear time), and tiny (5KB gzipped).
+Littlewing provides just enough: arithmetic expressions with variables and functions. It's safe (no code execution), fast (linear time), and tiny (7.8 KB gzipped).
 
 ### What Makes It Different