@webmate-studio/builder 0.2.110 → 0.2.113

package/src/expression-evaluator.js

@@ -0,0 +1,1234 @@
+/**
+ * Expression Evaluator - Safe AST-based Expression Parser
+ *
+ * Universal (isomorphic) module for Browser and Node.js.
+ * Supports a safe subset of JavaScript expressions:
+ *
+ * - Math: +, -, *, /, %
+ * - Comparison: >, <, >=, <=, ===, !==, ==, !=
+ * - Logical: &&, ||, !
+ * - Ternary: condition ? a : b
+ * - Nullish coalescing: a ?? b
+ * - Property access: obj.prop, obj?.prop, obj[index]
+ * - Function calls (whitelisted): items.filter(x => x.active)
+ * - Arrow functions: (x) => x.active, x => x + 1
+ * - Array literals: [1, 2, 3]
+ * - Object literals: { key: value }
+ * - Template literals: `hello ${name}`
+ * - Spread: ...items
+ * - typeof operator
+ *
+ * Security:
+ * - No eval(), no Function constructor
+ * - No access to window, document, globalThis, process
+ * - No assignments (=, +=, etc.)
+ * - No import/require
+ * - Method calls only on whitelisted prototypes
+ *
+ * @module expression-evaluator
+ */
+
+// ============================================================
+// Token Types
+// ============================================================
+
+const T = {
+	NUMBER: 1,
+	STRING: 2,
+	IDENTIFIER: 3,
+	TRUE: 4,
+	FALSE: 5,
+	NULL: 6,
+	UNDEFINED: 7,
+	PLUS: 8,
+	MINUS: 9,
+	STAR: 10,
+	SLASH: 11,
+	PERCENT: 12,
+	GT: 13,
+	LT: 14,
+	GTE: 15,
+	LTE: 16,
+	EQ_STRICT: 17,
+	NEQ_STRICT: 18,
+	EQ_LOOSE: 19,
+	NEQ_LOOSE: 20,
+	AND: 21,
+	OR: 22,
+	NOT: 23,
+	QUESTION: 24,
+	COLON: 25,
+	DOT: 26,
+	OPTIONAL_CHAIN: 27,
+	LPAREN: 28,
+	RPAREN: 29,
+	LBRACKET: 30,
+	RBRACKET: 31,
+	LBRACE: 32,
+	RBRACE: 33,
+	COMMA: 34,
+	ARROW: 35,
+	SPREAD: 36,
+	TYPEOF: 37,
+	NULLISH: 38,
+	TEMPLATE: 39,
+	EOF: 40,
+};
+
+// ============================================================
+// Whitelisted methods for safe execution
+// ============================================================
+
+const ALLOWED_ARRAY_METHODS = new Set([
+	'filter', 'map', 'find', 'findIndex', 'some', 'every',
+	'includes', 'indexOf', 'lastIndexOf',
+	'slice', 'concat', 'flat', 'flatMap',
+	'join', 'reverse', 'sort',
+	'reduce', 'reduceRight',
+	'fill', 'from', 'isArray', 'of',
+	'at', 'entries', 'keys', 'values',
+	'forEach',
+]);
+
+const ALLOWED_STRING_METHODS = new Set([
+	'toLowerCase', 'toUpperCase', 'trim', 'trimStart', 'trimEnd',
+	'startsWith', 'endsWith', 'includes', 'indexOf', 'lastIndexOf',
+	'split', 'replace', 'replaceAll', 'substring', 'slice',
+	'charAt', 'charCodeAt', 'padStart', 'padEnd', 'repeat',
+	'match', 'search', 'at',
+]);
+
+const ALLOWED_NUMBER_METHODS = new Set([
+	'toFixed', 'toPrecision', 'toString',
+]);
+
+const ALLOWED_OBJECT_STATIC = new Set([
+	'keys', 'values', 'entries', 'assign', 'fromEntries',
+]);
+
+const ALLOWED_MATH_PROPS = new Set([
+	'floor', 'ceil', 'round', 'abs', 'min', 'max',
+	'pow', 'sqrt', 'sign', 'trunc', 'random',
+	'PI', 'E',
+]);
+
+const ALLOWED_JSON_METHODS = new Set([
+	'stringify', 'parse',
+]);
+
+const ALLOWED_GLOBALS = new Set([
+	'parseInt', 'parseFloat', 'isNaN', 'isFinite',
+	'Number', 'String', 'Boolean', 'Array', 'Object',
+	'Math', 'JSON', 'Date', 'console',
+]);
+
+const BLOCKED_IDENTIFIERS = new Set([
+	'window', 'document', 'globalThis', 'self',
+	'process', 'require', 'import', 'module', 'exports',
+	'eval', 'Function', 'setTimeout', 'setInterval',
+	'fetch', 'XMLHttpRequest', 'WebSocket',
+	'__proto__', 'constructor', 'prototype',
+]);
+
+// ============================================================
+// Lexer
+// ============================================================
+
+class Lexer {
+	constructor(input) {
+		this.input = input;
+		this.pos = 0;
+		this.length = input.length;
+	}
+
+	peek(offset = 0) {
+		const p = this.pos + offset;
+		return p < this.length ? this.input[p] : null;
+	}
+
+	advance(n = 1) {
+		this.pos += n;
+	}
+
+	skipWhitespace() {
+		while (this.pos < this.length && /\s/.test(this.input[this.pos])) {
+			this.pos++;
+		}
+	}
+
+	readNumber() {
+		const start = this.pos;
+		// Handle hex: 0x...
+		if (this.input[this.pos] === '0' && (this.input[this.pos + 1] === 'x' || this.input[this.pos + 1] === 'X')) {
+			this.pos += 2;
+			while (this.pos < this.length && /[0-9a-fA-F]/.test(this.input[this.pos])) this.pos++;
+			return { type: T.NUMBER, value: parseInt(this.input.slice(start, this.pos), 16) };
+		}
+		while (this.pos < this.length && /[0-9]/.test(this.input[this.pos])) this.pos++;
+		if (this.pos < this.length && this.input[this.pos] === '.' && /[0-9]/.test(this.input[this.pos + 1] || '')) {
+			this.pos++;
+			while (this.pos < this.length && /[0-9]/.test(this.input[this.pos])) this.pos++;
+		}
+		// Scientific notation
+		if (this.pos < this.length && (this.input[this.pos] === 'e' || this.input[this.pos] === 'E')) {
+			this.pos++;
+			if (this.pos < this.length && (this.input[this.pos] === '+' || this.input[this.pos] === '-')) this.pos++;
+			while (this.pos < this.length && /[0-9]/.test(this.input[this.pos])) this.pos++;
+		}
+		return { type: T.NUMBER, value: parseFloat(this.input.slice(start, this.pos)) };
+	}
+
+	readString(quote) {
+		this.pos++; // skip opening quote
+		let str = '';
+		while (this.pos < this.length && this.input[this.pos] !== quote) {
+			if (this.input[this.pos] === '\\') {
+				this.pos++;
+				if (this.pos >= this.length) break;
+				const c = this.input[this.pos];
+				switch (c) {
+					case 'n': str += '\n'; break;
+					case 't': str += '\t'; break;
+					case 'r': str += '\r'; break;
+					case '\\': str += '\\'; break;
+					case "'": str += "'"; break;
+					case '"': str += '"'; break;
+					case '`': str += '`'; break;
+					default: str += c;
+				}
+			} else {
+				str += this.input[this.pos];
+			}
+			this.pos++;
+		}
+		this.pos++; // skip closing quote
+		return str;
+	}
+
+	readTemplateLiteral() {
+		this.pos++; // skip opening backtick
+		const parts = []; // Array of { type: 'text', value } or { type: 'expr', value }
+		let text = '';
+
+		while (this.pos < this.length && this.input[this.pos] !== '`') {
+			if (this.input[this.pos] === '\\') {
+				this.pos++;
+				if (this.pos >= this.length) break;
+				const c = this.input[this.pos];
+				switch (c) {
+					case 'n': text += '\n'; break;
+					case 't': text += '\t'; break;
+					case '`': text += '`'; break;
+					case '$': text += '$'; break;
+					case '\\': text += '\\'; break;
+					default: text += c;
+				}
+				this.pos++;
+			} else if (this.input[this.pos] === '$' && this.input[this.pos + 1] === '{') {
+				// Template expression
+				if (text) {
+					parts.push({ type: 'text', value: text });
+					text = '';
+				}
+				this.pos += 2; // skip ${
+
+				// Find matching } (handle nesting)
+				let depth = 1;
+				let exprStart = this.pos;
+				while (this.pos < this.length && depth > 0) {
+					if (this.input[this.pos] === '{') depth++;
+					else if (this.input[this.pos] === '}') depth--;
+					if (depth > 0) this.pos++;
+				}
+				parts.push({ type: 'expr', value: this.input.slice(exprStart, this.pos) });
+				this.pos++; // skip }
+			} else {
+				text += this.input[this.pos];
+				this.pos++;
+			}
+		}
+		this.pos++; // skip closing backtick
+
+		if (text) {
+			parts.push({ type: 'text', value: text });
+		}
+
+		return { type: T.TEMPLATE, parts };
+	}
+
+	readIdentifier() {
+		const start = this.pos;
+		while (this.pos < this.length && /[a-zA-Z0-9_$]/.test(this.input[this.pos])) {
+			this.pos++;
+		}
+		return this.input.slice(start, this.pos);
+	}
+
+	getNextToken() {
+		this.skipWhitespace();
+		if (this.pos >= this.length) return { type: T.EOF };
+
+		const ch = this.input[this.pos];
+		const next = this.pos + 1 < this.length ? this.input[this.pos + 1] : null;
+		const next2 = this.pos + 2 < this.length ? this.input[this.pos + 2] : null;
+
+		// Numbers
+		if (/[0-9]/.test(ch)) return this.readNumber();
+
+		// Strings
+		if (ch === '"' || ch === "'") return { type: T.STRING, value: this.readString(ch) };
+
+		// Template literals
+		if (ch === '`') return this.readTemplateLiteral();
+
+		// Spread operator
+		if (ch === '.' && next === '.' && next2 === '.') {
+			this.advance(3);
+			return { type: T.SPREAD };
+		}
+
+		// Identifiers and keywords
+		if (/[a-zA-Z_$]/.test(ch)) {
+			const id = this.readIdentifier();
+			switch (id) {
+				case 'true': return { type: T.TRUE, value: true };
+				case 'false': return { type: T.FALSE, value: false };
+				case 'null': return { type: T.NULL, value: null };
+				case 'undefined': return { type: T.UNDEFINED, value: undefined };
+				case 'typeof': return { type: T.TYPEOF };
+				default: return { type: T.IDENTIFIER, value: id };
+			}
+		}
+
+		// Multi-character operators
+		switch (ch) {
+			case '=':
+				if (next === '=' && next2 === '=') { this.advance(3); return { type: T.EQ_STRICT }; }
+				if (next === '=') { this.advance(2); return { type: T.EQ_LOOSE }; }
+				if (next === '>') { this.advance(2); return { type: T.ARROW }; }
+				throw new Error(`Assignment operator = not allowed in expressions`);
+			case '!':
+				if (next === '=' && next2 === '=') { this.advance(3); return { type: T.NEQ_STRICT }; }
+				if (next === '=') { this.advance(2); return { type: T.NEQ_LOOSE }; }
+				this.advance(); return { type: T.NOT };
+			case '>':
+				if (next === '=') { this.advance(2); return { type: T.GTE }; }
+				this.advance(); return { type: T.GT };
+			case '<':
+				if (next === '=') { this.advance(2); return { type: T.LTE }; }
+				this.advance(); return { type: T.LT };
+			case '&':
+				if (next === '&') { this.advance(2); return { type: T.AND }; }
+				throw new Error('Bitwise & not supported, use &&');
+			case '|':
+				if (next === '|') { this.advance(2); return { type: T.OR }; }
+				throw new Error('Bitwise | not supported, use ||');
+			case '?':
+				if (next === '?') { this.advance(2); return { type: T.NULLISH }; }
+				if (next === '.') { this.advance(2); return { type: T.OPTIONAL_CHAIN }; }
+				this.advance(); return { type: T.QUESTION };
+			case '+': this.advance(); return { type: T.PLUS };
+			case '-': this.advance(); return { type: T.MINUS };
+			case '*': this.advance(); return { type: T.STAR };
+			case '/': this.advance(); return { type: T.SLASH };
+			case '%': this.advance(); return { type: T.PERCENT };
+			case '(': this.advance(); return { type: T.LPAREN };
+			case ')': this.advance(); return { type: T.RPAREN };
+			case '[': this.advance(); return { type: T.LBRACKET };
+			case ']': this.advance(); return { type: T.RBRACKET };
+			case '{': this.advance(); return { type: T.LBRACE };
+			case '}': this.advance(); return { type: T.RBRACE };
+			case ',': this.advance(); return { type: T.COMMA };
+			case '.': this.advance(); return { type: T.DOT };
+			case ':': this.advance(); return { type: T.COLON };
+		}
+
+		throw new Error(`Unexpected character: ${ch} at position ${this.pos}`);
+	}
+}
+
+// ============================================================
+// Parser — Builds AST from token stream
+// ============================================================
+
+class Parser {
+	constructor(lexer) {
+		this.lexer = lexer;
+		this.current = this.lexer.getNextToken();
+	}
+
+	eat(type) {
+		if (this.current.type === type) {
+			const token = this.current;
+			this.current = this.lexer.getNextToken();
+			return token;
+		}
+		throw new Error(`Expected token type ${type}, got ${this.current.type}`);
+	}
+
+	// Entry point
+	parse() {
+		const node = this.expression();
+		if (this.current.type !== T.EOF) {
+			throw new Error(`Unexpected token after expression`);
+		}
+		return node;
+	}
+
+	// expression: assignment-level (we don't allow assignment, so this is ternary/nullish)
+	expression() {
+		return this.ternary();
+	}
+
+	// ternary: nullishCoalescing (? expression : expression)?
+	ternary() {
+		let node = this.nullishCoalescing();
+
+		if (this.current.type === T.QUESTION) {
+			this.eat(T.QUESTION);
+			const consequent = this.expression();
+			this.eat(T.COLON);
+			const alternate = this.expression();
+			return { type: 'Conditional', test: node, consequent, alternate };
+		}
+
+		return node;
+	}
+
+	// nullishCoalescing: logicalOr (?? logicalOr)*
+	nullishCoalescing() {
+		let node = this.logicalOr();
+
+		while (this.current.type === T.NULLISH) {
+			this.eat(T.NULLISH);
+			node = { type: 'Nullish', left: node, right: this.logicalOr() };
+		}
+
+		return node;
+	}
+
+	// logicalOr: logicalAnd (|| logicalAnd)*
+	logicalOr() {
+		let node = this.logicalAnd();
+
+		while (this.current.type === T.OR) {
+			this.eat(T.OR);
+			node = { type: 'Logical', op: '||', left: node, right: this.logicalAnd() };
+		}
+
+		return node;
+	}
+
+	// logicalAnd: comparison (&& comparison)*
+	logicalAnd() {
+		let node = this.comparison();
+
+		while (this.current.type === T.AND) {
+			this.eat(T.AND);
+			node = { type: 'Logical', op: '&&', left: node, right: this.comparison() };
+		}
+
+		return node;
+	}
+
+	// comparison: additive (comp_op additive)*
+	comparison() {
+		let node = this.additive();
+
+		const compTypes = [T.GT, T.LT, T.GTE, T.LTE, T.EQ_STRICT, T.NEQ_STRICT, T.EQ_LOOSE, T.NEQ_LOOSE];
+		while (compTypes.includes(this.current.type)) {
+			const opMap = {
+				[T.GT]: '>', [T.LT]: '<', [T.GTE]: '>=', [T.LTE]: '<=',
+				[T.EQ_STRICT]: '===', [T.NEQ_STRICT]: '!==',
+				[T.EQ_LOOSE]: '==', [T.NEQ_LOOSE]: '!=',
+			};
+			const op = opMap[this.current.type];
+			this.eat(this.current.type);
+			node = { type: 'Binary', op, left: node, right: this.additive() };
+		}
+
+		return node;
+	}
+
+	// additive: multiplicative ((+|-) multiplicative)*
+	additive() {
+		let node = this.multiplicative();
+
+		while (this.current.type === T.PLUS || this.current.type === T.MINUS) {
+			const op = this.current.type === T.PLUS ? '+' : '-';
+			this.eat(this.current.type);
+			node = { type: 'Binary', op, left: node, right: this.multiplicative() };
+		}
+
+		return node;
+	}
+
+	// multiplicative: unary ((*|/|%) unary)*
+	multiplicative() {
+		let node = this.unary();
+
+		while (this.current.type === T.STAR || this.current.type === T.SLASH || this.current.type === T.PERCENT) {
+			const opMap = { [T.STAR]: '*', [T.SLASH]: '/', [T.PERCENT]: '%' };
+			const op = opMap[this.current.type];
+			this.eat(this.current.type);
+			node = { type: 'Binary', op, left: node, right: this.unary() };
+		}
+
+		return node;
+	}
+
+	// unary: (!|+|-|typeof|...) unary | postfix
+	unary() {
+		if (this.current.type === T.NOT) {
+			this.eat(T.NOT);
+			return { type: 'Unary', op: '!', argument: this.unary() };
+		}
+		if (this.current.type === T.MINUS) {
+			this.eat(T.MINUS);
+			return { type: 'Unary', op: '-', argument: this.unary() };
+		}
+		if (this.current.type === T.PLUS) {
+			this.eat(T.PLUS);
+			return { type: 'Unary', op: '+', argument: this.unary() };
+		}
+		if (this.current.type === T.TYPEOF) {
+			this.eat(T.TYPEOF);
+			return { type: 'Typeof', argument: this.unary() };
+		}
+		if (this.current.type === T.SPREAD) {
+			this.eat(T.SPREAD);
+			return { type: 'Spread', argument: this.unary() };
+		}
+
+		return this.callOrMember();
+	}
+
+	// callOrMember: primary (. prop | ?. prop | [expr] | (args))*
+	callOrMember() {
+		let node = this.primary();
+
+		while (true) {
+			if (this.current.type === T.DOT) {
+				this.eat(T.DOT);
+				const prop = this.eat(T.IDENTIFIER).value;
+				node = { type: 'Member', object: node, property: prop, computed: false, optional: false };
+			} else if (this.current.type === T.OPTIONAL_CHAIN) {
+				this.eat(T.OPTIONAL_CHAIN);
+				if (this.current.type === T.LBRACKET) {
+					// ?.[ computed access
+					this.eat(T.LBRACKET);
+					const expr = this.expression();
+					this.eat(T.RBRACKET);
+					node = { type: 'Member', object: node, property: expr, computed: true, optional: true };
+				} else if (this.current.type === T.LPAREN) {
+					// ?.( optional call
+					const args = this.parseArguments();
+					node = { type: 'Call', callee: node, arguments: args, optional: true };
+				} else {
+					const prop = this.eat(T.IDENTIFIER).value;
+					node = { type: 'Member', object: node, property: prop, computed: false, optional: true };
+				}
+			} else if (this.current.type === T.LBRACKET) {
+				this.eat(T.LBRACKET);
+				const expr = this.expression();
+				this.eat(T.RBRACKET);
+				node = { type: 'Member', object: node, property: expr, computed: true, optional: false };
+			} else if (this.current.type === T.LPAREN) {
+				const args = this.parseArguments();
+				node = { type: 'Call', callee: node, arguments: args, optional: false };
+			} else {
+				break;
+			}
+		}
+
+		return node;
+	}
+
+	parseArguments() {
+		this.eat(T.LPAREN);
+		const args = [];
+		while (this.current.type !== T.RPAREN) {
+			if (this.current.type === T.SPREAD) {
+				this.eat(T.SPREAD);
+				args.push({ type: 'Spread', argument: this.expression() });
+			} else {
+				args.push(this.expression());
+			}
+			if (this.current.type === T.COMMA) {
+				this.eat(T.COMMA);
+			}
+		}
+		this.eat(T.RPAREN);
+		return args;
+	}
+
+	// primary: literals, identifiers, grouped, arrays, objects, arrow functions
+	primary() {
+		const tok = this.current;
+
+		// Number
+		if (tok.type === T.NUMBER) {
+			this.eat(T.NUMBER);
+			return { type: 'Literal', value: tok.value };
+		}
+
+		// String
+		if (tok.type === T.STRING) {
+			this.eat(T.STRING);
+			return { type: 'Literal', value: tok.value };
+		}
+
+		// Template literal
+		if (tok.type === T.TEMPLATE) {
+			this.eat(T.TEMPLATE);
+			return { type: 'TemplateLiteral', parts: tok.parts };
+		}
+
+		// Boolean / null / undefined
+		if (tok.type === T.TRUE || tok.type === T.FALSE) {
+			this.eat(tok.type);
+			return { type: 'Literal', value: tok.value };
+		}
+		if (tok.type === T.NULL) {
+			this.eat(T.NULL);
+			return { type: 'Literal', value: null };
+		}
+		if (tok.type === T.UNDEFINED) {
+			this.eat(T.UNDEFINED);
+			return { type: 'Literal', value: undefined };
+		}
+
+		// Identifier (might be start of arrow function: ident => ...)
+		if (tok.type === T.IDENTIFIER) {
+			this.eat(T.IDENTIFIER);
+			// Check for arrow function: ident => body
+			if (this.current.type === T.ARROW) {
+				this.eat(T.ARROW);
+				const body = this.expression();
+				return { type: 'Arrow', params: [tok.value], body };
+			}
+			return { type: 'Identifier', name: tok.value };
+		}
+
+		// Grouped expression or arrow function params: (a, b) => ...
+		if (tok.type === T.LPAREN) {
+			return this.parseParenOrArrow();
+		}
+
+		// Array literal: [a, b, c]
+		if (tok.type === T.LBRACKET) {
+			return this.parseArray();
+		}
+
+		// Object literal: { key: value }
+		if (tok.type === T.LBRACE) {
+			return this.parseObject();
+		}
+
+		throw new Error(`Unexpected token: ${tok.type} (value: ${JSON.stringify(tok.value)})`);
+	}
+
+	parseParenOrArrow() {
+		this.eat(T.LPAREN);
+
+		// Empty parens: () => ...
+		if (this.current.type === T.RPAREN) {
+			this.eat(T.RPAREN);
+			this.eat(T.ARROW);
+			const body = this.expression();
+			return { type: 'Arrow', params: [], body };
+		}
+
+		// Try to parse as arrow function params
+		// Save position for backtracking
+		const savedPos = this.lexer.pos;
+		const savedCurrent = { ...this.current };
+
+		// Collect potential params
+		const params = [];
+		let isArrow = true;
+		let firstExpr = null;
+
+		try {
+			// First item
+			if (this.current.type === T.SPREAD) {
+				// Rest parameter: (...args) => ...
+				this.eat(T.SPREAD);
+				params.push({ type: 'rest', name: this.eat(T.IDENTIFIER).value });
+			} else if (this.current.type === T.IDENTIFIER) {
+				params.push(this.current.value);
+				this.eat(T.IDENTIFIER);
+			} else {
+				// Not a simple param list — it's a grouped expression
+				isArrow = false;
+			}
+
+			if (isArrow) {
+				while (this.current.type === T.COMMA) {
+					this.eat(T.COMMA);
+					if (this.current.type === T.SPREAD) {
+						this.eat(T.SPREAD);
+						params.push({ type: 'rest', name: this.eat(T.IDENTIFIER).value });
+					} else if (this.current.type === T.IDENTIFIER) {
+						params.push(this.current.value);
+						this.eat(T.IDENTIFIER);
+					} else {
+						isArrow = false;
+						break;
+					}
+				}
+			}
+
+			if (isArrow && this.current.type === T.RPAREN) {
+				this.eat(T.RPAREN);
+				if (this.current.type === T.ARROW) {
+					this.eat(T.ARROW);
+					const body = this.expression();
+					return { type: 'Arrow', params: params.map(p => typeof p === 'string' ? p : p), body };
+				}
+				// It was (identifier) but no arrow — treat as grouped expression
+				if (params.length === 1 && typeof params[0] === 'string') {
+					return { type: 'Identifier', name: params[0] };
+				}
+			}
+		} catch (e) {
+			isArrow = false;
+		}
+
+		// Backtrack and parse as grouped expression
+		if (!isArrow || (isArrow && this.current.type !== T.EOF)) {
+			// We can't easily backtrack with our lexer, so re-lex
+			this.lexer.pos = savedPos;
+			this.current = savedCurrent;
+
+			// It's just a regular grouped expression if we get here with a single non-arrow identifier
+			// But we already consumed LPAREN, so parse the expression
+		}
+
+		// Parse as grouped expression
+		const expr = this.expression();
+		this.eat(T.RPAREN);
+
+		// Check if this is actually arrow: (expr) =>
+		if (this.current.type === T.ARROW) {
+			this.eat(T.ARROW);
+			const body = this.expression();
+			// expr should be an Identifier
+			if (expr.type === 'Identifier') {
+				return { type: 'Arrow', params: [expr.name], body };
+			}
+		}
+
+		return expr;
+	}
+
+	parseArray() {
+		this.eat(T.LBRACKET);
+		const elements = [];
+		while (this.current.type !== T.RBRACKET) {
+			if (this.current.type === T.SPREAD) {
+				this.eat(T.SPREAD);
+				elements.push({ type: 'Spread', argument: this.expression() });
+			} else {
+				elements.push(this.expression());
+			}
+			if (this.current.type === T.COMMA) {
+				this.eat(T.COMMA);
+			}
+		}
+		this.eat(T.RBRACKET);
+		return { type: 'ArrayLiteral', elements };
+	}
+
+	parseObject() {
+		this.eat(T.LBRACE);
+		const properties = [];
+		while (this.current.type !== T.RBRACE) {
+			if (this.current.type === T.SPREAD) {
+				this.eat(T.SPREAD);
+				properties.push({ type: 'SpreadProperty', argument: this.expression() });
+			} else {
+				let key;
+				let computed = false;
+
+				if (this.current.type === T.LBRACKET) {
+					// Computed key: { [expr]: value }
+					this.eat(T.LBRACKET);
+					key = this.expression();
+					this.eat(T.RBRACKET);
+					computed = true;
+				} else if (this.current.type === T.STRING) {
+					key = this.eat(T.STRING).value;
+				} else if (this.current.type === T.NUMBER) {
+					key = String(this.eat(T.NUMBER).value);
+				} else {
+					key = this.eat(T.IDENTIFIER).value;
+				}
+
+				if (this.current.type === T.COLON) {
+					this.eat(T.COLON);
+					const value = this.expression();
+					properties.push({ type: 'Property', key, value, computed });
+				} else {
+					// Shorthand: { foo } is { foo: foo }
+					properties.push({
+						type: 'Property',
+						key,
+						value: { type: 'Identifier', name: key },
+						computed: false,
+					});
+				}
+			}
+			if (this.current.type === T.COMMA) {
+				this.eat(T.COMMA);
+			}
+		}
+		this.eat(T.RBRACE);
+		return { type: 'ObjectLiteral', properties };
+	}
+}
+
+// ============================================================
+// Evaluator — Evaluates AST with a context
+// ============================================================
+
+class Evaluator {
+	constructor(context) {
+		this.context = context;
+	}
+
+	evaluate(node) {
+		if (!node) return undefined;
+
+		switch (node.type) {
+			case 'Literal':
+				return node.value;
+
+			case 'Identifier':
+				return this.resolveIdentifier(node.name);
+
+			case 'TemplateLiteral':
+				return this.evaluateTemplateLiteral(node);
+
+			case 'Binary':
+				return this.evaluateBinary(node);
+
+			case 'Logical':
+				return this.evaluateLogical(node);
+
+			case 'Unary':
+				return this.evaluateUnary(node);
+
+			case 'Typeof':
+				return this.evaluateTypeof(node);
+
+			case 'Conditional':
+				return this.evaluate(node.test) ? this.evaluate(node.consequent) : this.evaluate(node.alternate);
+
+			case 'Nullish': {
+				const left = this.evaluate(node.left);
+				return left != null ? left : this.evaluate(node.right);
+			}
+
+			case 'Member':
+				return this.evaluateMember(node);
+
+			case 'Call':
+				return this.evaluateCall(node);
+
+			case 'Arrow':
+				return this.evaluateArrow(node);
+
+			case 'ArrayLiteral':
+				return this.evaluateArray(node);
+
+			case 'ObjectLiteral':
+				return this.evaluateObject(node);
+
+			case 'Spread':
+				return this.evaluate(node.argument);
+
+			default:
+				throw new Error(`Unknown AST node type: ${node.type}`);
+		}
+	}
+
+	resolveIdentifier(name) {
+		if (BLOCKED_IDENTIFIERS.has(name)) {
+			throw new Error(`Access to '${name}' is not allowed`);
+		}
+
+		// Built-in globals
+		if (name === 'Math') return Math;
+		if (name === 'JSON') return JSON;
+		if (name === 'parseInt') return parseInt;
+		if (name === 'parseFloat') return parseFloat;
+		if (name === 'isNaN') return isNaN;
+		if (name === 'isFinite') return isFinite;
+		if (name === 'Number') return Number;
+		if (name === 'String') return String;
+		if (name === 'Boolean') return Boolean;
+		if (name === 'Array') return Array;
+		if (name === 'Object') return Object;
+		if (name === 'Date') return Date;
+		if (name === 'Infinity') return Infinity;
+		if (name === 'NaN') return NaN;
+
+		// Context lookup
+		if (name in this.context) {
+			return this.context[name];
+		}
+
+		return undefined;
+	}
+
+	evaluateTemplateLiteral(node) {
+		return node.parts.map(part => {
+			if (part.type === 'text') return part.value;
+			// Parse and evaluate the expression inside ${}
+			const innerAst = new Parser(new Lexer(part.value)).parse();
+			return String(this.evaluate(innerAst) ?? '');
+		}).join('');
+	}
+
+	evaluateBinary(node) {
+		const left = this.evaluate(node.left);
+		const right = this.evaluate(node.right);
+
+		switch (node.op) {
+			case '+': return left + right;
+			case '-': return left - right;
+			case '*': return left * right;
+			case '/': return left / right;
+			case '%': return left % right;
+			case '>': return left > right;
+			case '<': return left < right;
+			case '>=': return left >= right;
+			case '<=': return left <= right;
+			case '===': return left === right;
+			case '!==': return left !== right;
+			case '==': return left == right;
+			case '!=': return left != right;
+			default: throw new Error(`Unknown binary operator: ${node.op}`);
+		}
+	}
+
+	evaluateLogical(node) {
+		const left = this.evaluate(node.left);
+		if (node.op === '&&') return left ? this.evaluate(node.right) : left;
+		if (node.op === '||') return left ? left : this.evaluate(node.right);
+		throw new Error(`Unknown logical operator: ${node.op}`);
+	}
+
+	evaluateUnary(node) {
+		const arg = this.evaluate(node.argument);
+		switch (node.op) {
+			case '!': return !arg;
+			case '-': return -arg;
+			case '+': return +arg;
+			default: throw new Error(`Unknown unary operator: ${node.op}`);
+		}
+	}
+
+	evaluateTypeof(node) {
+		try {
+			const val = this.evaluate(node.argument);
+			return typeof val;
+		} catch {
+			return 'undefined';
+		}
+	}
+
+	evaluateMember(node) {
+		const object = this.evaluate(node.object);
+
+		if (node.optional && (object == null)) {
+			return undefined;
+		}
+
+		if (object == null) {
+			return undefined;
+		}
+
+		if (node.computed) {
+			const key = this.evaluate(node.property);
+			return object[key];
+		}
+
+		const prop = node.property;
+
+		// Block dangerous properties
+		if (prop === '__proto__' || prop === 'constructor' || prop === 'prototype') {
+			return undefined;
+		}
+
+		return object[prop];
+	}
+
+	evaluateCall(node) {
+		// Handle method calls: obj.method(args)
+		if (node.callee.type === 'Member') {
+			const obj = this.evaluate(node.callee.object);
+
+			if (node.optional && (obj == null)) {
+				return undefined;
+			}
+
+			if (obj == null) {
+				return undefined;
+			}
+
+			const methodName = node.callee.computed
+				? this.evaluate(node.callee.property)
+				: node.callee.property;
+
+			// Validate method call is allowed
+			this.validateMethodCall(obj, methodName);
+
+			const method = obj[methodName];
+			if (typeof method !== 'function') {
+				throw new Error(`${methodName} is not a function`);
+			}
+
+			const args = this.evaluateArgList(node.arguments);
+			return method.apply(obj, args);
+		}
+
+		// Handle direct function calls: fn(args) or Array.isArray(x)
+		const callee = this.evaluate(node.callee);
+
+		if (typeof callee !== 'function') {
+			throw new Error('Not a function');
+		}
+
+		const args = this.evaluateArgList(node.arguments);
+		return callee(...args);
+	}
+
+	validateMethodCall(obj, methodName) {
+		if (Array.isArray(obj)) {
+			if (!ALLOWED_ARRAY_METHODS.has(methodName)) {
+				throw new Error(`Array method '${methodName}' is not allowed`);
+			}
+			return;
+		}
+
+		if (typeof obj === 'string') {
+			if (!ALLOWED_STRING_METHODS.has(methodName)) {
+				throw new Error(`String method '${methodName}' is not allowed`);
+			}
+			return;
+		}
+
+		if (typeof obj === 'number') {
+			if (!ALLOWED_NUMBER_METHODS.has(methodName)) {
+				throw new Error(`Number method '${methodName}' is not allowed`);
+			}
+			return;
+		}
+
+		if (obj === Math) {
+			if (!ALLOWED_MATH_PROPS.has(methodName)) {
+				throw new Error(`Math.${methodName} is not allowed`);
+			}
+			return;
+		}
+
+		if (obj === JSON) {
+			if (!ALLOWED_JSON_METHODS.has(methodName)) {
+				throw new Error(`JSON.${methodName} is not allowed`);
+			}
+			return;
+		}
+
+		if (obj === Object) {
+			if (!ALLOWED_OBJECT_STATIC.has(methodName)) {
+				throw new Error(`Object.${methodName} is not allowed`);
+			}
+			return;
+		}
+
+		if (obj === Array) {
+			if (!ALLOWED_ARRAY_METHODS.has(methodName) && methodName !== 'from' && methodName !== 'isArray' && methodName !== 'of') {
+				throw new Error(`Array.${methodName} is not allowed`);
+			}
+			return;
+		}
+
+		// For plain objects, allow calling methods that are own properties (user-defined functions)
+		if (typeof obj === 'object' && obj !== null) {
+			if (typeof obj[methodName] === 'function') {
+				// Allow if it's an own property or from a safe prototype
+				return;
+			}
+		}
+
+		throw new Error(`Method call '${methodName}' is not allowed on this object type`);
+	}
+
+	evaluateArgList(args) {
+		const result = [];
+		for (const arg of args) {
+			if (arg.type === 'Spread') {
+				const spreadVal = this.evaluate(arg.argument);
+				if (Array.isArray(spreadVal)) {
+					result.push(...spreadVal);
+				} else {
+					result.push(spreadVal);
+				}
+			} else {
+				result.push(this.evaluate(arg));
+			}
+		}
+		return result;
+	}
+
+	evaluateArrow(node) {
+		const outerContext = this.context;
+
+		return (...args) => {
+			const innerContext = { ...outerContext };
+
+			for (let i = 0; i < node.params.length; i++) {
+				const param = node.params[i];
+				if (typeof param === 'object' && param.type === 'rest') {
+					innerContext[param.name] = args.slice(i);
+				} else {
+					innerContext[param] = args[i];
+				}
+			}
+
+			const innerEval = new Evaluator(innerContext);
+			return innerEval.evaluate(node.body);
+		};
+	}
+
+	evaluateArray(node) {
+		const result = [];
+		for (const el of node.elements) {
+			if (el.type === 'Spread') {
+				const val = this.evaluate(el.argument);
+				if (Array.isArray(val)) {
+					result.push(...val);
+				}
+			} else {
+				result.push(this.evaluate(el));
+			}
+		}
+		return result;
+	}
+
+	evaluateObject(node) {
+		const result = {};
+		for (const prop of node.properties) {
+			if (prop.type === 'SpreadProperty') {
+				const val = this.evaluate(prop.argument);
+				if (typeof val === 'object' && val !== null) {
+					Object.assign(result, val);
+				}
+			} else {
+				const key = prop.computed ? this.evaluate(prop.key) : prop.key;
+				result[key] = this.evaluate(prop.value);
+			}
+		}
+		return result;
+	}
+}
+
+// ============================================================
+// Expression Cache (LRU)
+// ============================================================
+
+class ExpressionCache {
+	constructor(maxSize = 500) {
+		this.maxSize = maxSize;
+		this.cache = new Map();
+	}
+
+	get(key) {
+		if (!this.cache.has(key)) return null;
+		// Move to end (most recently used)
+		const value = this.cache.get(key);
+		this.cache.delete(key);
+		this.cache.set(key, value);
+		return value;
+	}
+
+	set(key, value) {
+		if (this.cache.has(key)) {
+			this.cache.delete(key);
+		} else if (this.cache.size >= this.maxSize) {
+			// Delete oldest entry
+			const firstKey = this.cache.keys().next().value;
+			this.cache.delete(firstKey);
+		}
+		this.cache.set(key, value);
+	}
+
+	clear() {
+		this.cache.clear();
+	}
+}
+
+// ============================================================
+// Public API
+// ============================================================
+
+class ExpressionEvaluator {
+	constructor() {
+		this.cache = new ExpressionCache(500);
+	}
+
+	/**
+	 * Parse and evaluate an expression
+	 * @param {string} expression - Expression string
+	 * @param {Object} context - Variable context
+	 * @returns {*} Result
+	 */
+	evaluate(expression, context = {}) {
+		if (!expression || typeof expression !== 'string') return undefined;
+		expression = expression.trim();
+		if (expression === '') return undefined;
+
+		try {
+			// Get or parse AST (cached)
+			let ast = this.cache.get(expression);
+			if (!ast) {
+				const lexer = new Lexer(expression);
+				const parser = new Parser(lexer);
+				ast = parser.parse();
+				this.cache.set(expression, ast);
+			}
+
+			// Evaluate with context
+			const evaluator = new Evaluator(context);
+			return evaluator.evaluate(ast);
+		} catch (error) {
+			// Silent fail in production — return undefined
+			return undefined;
+		}
+	}
+
+	/**
+	 * Evaluate and return boolean
+	 * @param {string} expression
+	 * @param {Object} context
+	 * @returns {boolean}
+	 */
+	isTruthy(expression, context = {}) {
+		return Boolean(this.evaluate(expression, context));
+	}
+
+	/**
+	 * Clear the AST cache
+	 */
+	clearCache() {
+		this.cache.clear();
+	}
+}
+
+// Singleton instance
+const expressionEvaluator = new ExpressionEvaluator();
+
+export { ExpressionEvaluator, ExpressionCache, Lexer, Parser, Evaluator };
+export default expressionEvaluator;