@mmapp/player-core 0.1.0-alpha.1

package/src/expression/evaluator.ts

@@ -0,0 +1,676 @@
+/**
+ * Expression Evaluator — createEvaluator factory and evaluation engine.
+ *
+ * Parses and evaluates expressions with a safe recursive descent parser.
+ * NO dynamic code compilation (no new Function(), no eval(), no with()).
+ *
+ * Supported syntax:
+ * - Path resolution: `state_data.title`, `$instance.fields.name`
+ * - Function calls: `add(1, 2)`, `if(eq(x, 1), 'yes', 'no')`
+ * - Template interpolation: `"Hello {{name}}, you have {{count}} items"`
+ * - Ternary expressions: `condition ? 'yes' : 'no'`
+ * - Operators: `==`, `!=`, `>`, `<`, `>=`, `<=`, `&&`, `||`, `!`
+ * - Literals: strings, numbers, booleans, null
+ *
+ * Grammar:
+ *   expression  → ternary
+ *   ternary     → logicalOr ('?' expression ':' expression)?
+ *   logicalOr   → logicalAnd ('||' logicalAnd)*
+ *   logicalAnd  → equality ('&&' equality)*
+ *   equality    → comparison (('=='|'!=') comparison)*
+ *   comparison  → unary (('>'|'<'|'>='|'<=') unary)*
+ *   unary       → ('!' unary) | call
+ *   call        → primary ('(' args? ')')? ('.' IDENT ('(' args? ')')?)*
+ *   primary     → NUMBER | STRING | BOOL | NULL | IDENT | '(' expression ')'
+ */
+
+import type {
+  Evaluator,
+  EvaluatorConfig,
+  ExpressionContext,
+  ExpressionResult,
+  FailurePolicy,
+  ExpressionFunction,
+} from './types';
+import { CORE_FUNCTIONS, buildFunctionMap } from './functions';
+
+// =============================================================================
+// AST Node Types
+// =============================================================================
+
+type ASTNode =
+  | { type: 'number'; value: number }
+  | { type: 'string'; value: string }
+  | { type: 'boolean'; value: boolean }
+  | { type: 'null' }
+  | { type: 'identifier'; name: string }
+  | { type: 'path'; segments: string[] }
+  | { type: 'call'; name: string; args: ASTNode[] }
+  | { type: 'method_call'; object: ASTNode; method: string; args: ASTNode[] }
+  | { type: 'member'; object: ASTNode; property: string }
+  | { type: 'unary'; operator: '!'; operand: ASTNode }
+  | { type: 'binary'; operator: string; left: ASTNode; right: ASTNode }
+  | { type: 'ternary'; condition: ASTNode; consequent: ASTNode; alternate: ASTNode };
+
+// =============================================================================
+// Parser
+// =============================================================================
+
+const MAX_DEPTH = 50;
+
+class Parser {
+  private pos = 0;
+  private depth = 0;
+  private readonly input: string;
+
+  constructor(input: string) {
+    this.input = input;
+  }
+
+  parse(): ASTNode {
+    this.skipWhitespace();
+    const node = this.parseExpression();
+    this.skipWhitespace();
+    if (this.pos < this.input.length) {
+      throw new Error(`Unexpected character at position ${this.pos}: '${this.input[this.pos]}'`);
+    }
+    return node;
+  }
+
+  private guardDepth(): void {
+    if (++this.depth > MAX_DEPTH) {
+      throw new Error('Expression too deeply nested');
+    }
+  }
+
+  private parseExpression(): ASTNode {
+    this.guardDepth();
+    try {
+      return this.parseTernary();
+    } finally {
+      this.depth--;
+    }
+  }
+
+  private parseTernary(): ASTNode {
+    let node = this.parseLogicalOr();
+    this.skipWhitespace();
+    if (this.peek() === '?') {
+      this.advance(); // consume '?'
+      const consequent = this.parseExpression();
+      this.skipWhitespace();
+      this.expect(':');
+      const alternate = this.parseExpression();
+      node = { type: 'ternary', condition: node, consequent, alternate };
+    }
+    return node;
+  }
+
+  private parseLogicalOr(): ASTNode {
+    let left = this.parseLogicalAnd();
+    this.skipWhitespace();
+    while (this.match('||')) {
+      const right = this.parseLogicalAnd();
+      left = { type: 'binary', operator: '||', left, right };
+      this.skipWhitespace();
+    }
+    return left;
+  }
+
+  private parseLogicalAnd(): ASTNode {
+    let left = this.parseEquality();
+    this.skipWhitespace();
+    while (this.match('&&')) {
+      const right = this.parseEquality();
+      left = { type: 'binary', operator: '&&', left, right };
+      this.skipWhitespace();
+    }
+    return left;
+  }
+
+  private parseEquality(): ASTNode {
+    let left = this.parseComparison();
+    this.skipWhitespace();
+    while (true) {
+      if (this.match('==')) {
+        const right = this.parseComparison();
+        left = { type: 'binary', operator: '==', left, right };
+      } else if (this.match('!=')) {
+        const right = this.parseComparison();
+        left = { type: 'binary', operator: '!=', left, right };
+      } else {
+        break;
+      }
+      this.skipWhitespace();
+    }
+    return left;
+  }
+
+  private parseComparison(): ASTNode {
+    let left = this.parseUnary();
+    this.skipWhitespace();
+    while (true) {
+      if (this.match('>=')) {
+        const right = this.parseUnary();
+        left = { type: 'binary', operator: '>=', left, right };
+      } else if (this.match('<=')) {
+        const right = this.parseUnary();
+        left = { type: 'binary', operator: '<=', left, right };
+      } else if (this.peek() === '>' && !this.lookAhead('>=')) {
+        this.advance();
+        const right = this.parseUnary();
+        left = { type: 'binary', operator: '>', left, right };
+      } else if (this.peek() === '<' && !this.lookAhead('<=')) {
+        this.advance();
+        const right = this.parseUnary();
+        left = { type: 'binary', operator: '<', left, right };
+      } else {
+        break;
+      }
+      this.skipWhitespace();
+    }
+    return left;
+  }
+
+  private parseUnary(): ASTNode {
+    this.skipWhitespace();
+    if (this.peek() === '!') {
+      this.advance();
+      const operand = this.parseUnary();
+      return { type: 'unary', operator: '!', operand };
+    }
+
+    // Handle unary minus for negative numbers
+    if (this.peek() === '-') {
+      const nextChar = this.input[this.pos + 1];
+      if (nextChar !== undefined && (nextChar >= '0' && nextChar <= '9' || nextChar === '.')) {
+        // Parse as negative number in primary
+        return this.parseCallChain();
+      }
+    }
+
+    return this.parseCallChain();
+  }
+
+  private parseCallChain(): ASTNode {
+    let node = this.parsePrimary();
+
+    // Handle call chains: ident(args), ident.prop, ident.method(args)
+    while (true) {
+      this.skipWhitespace();
+      if (this.peek() === '(') {
+        // Function call — only valid if node is identifier or path
+        this.advance(); // consume '('
+        const args = this.parseArgList();
+        this.expect(')');
+
+        if (node.type === 'identifier') {
+          node = { type: 'call', name: node.name, args };
+        } else if (node.type === 'path') {
+          // e.g. module.fn(args) — treat the last segment as the function name
+          const name = node.segments.join('.');
+          node = { type: 'call', name, args };
+        } else if (node.type === 'member') {
+          node = { type: 'method_call', object: node.object, method: node.property, args };
+        } else {
+          throw new Error('Cannot call non-function');
+        }
+      } else if (this.peek() === '.') {
+        this.advance(); // consume '.'
+        const prop = this.parseIdentifierName();
+        node = { type: 'member', object: node, property: prop };
+      } else {
+        break;
+      }
+    }
+
+    return node;
+  }
+
+  private parsePrimary(): ASTNode {
+    this.skipWhitespace();
+    const ch = this.peek();
+
+    // Parenthesized expression
+    if (ch === '(') {
+      this.advance();
+      const expr = this.parseExpression();
+      this.skipWhitespace();
+      this.expect(')');
+      return expr;
+    }
+
+    // String literal (single or double quoted)
+    if (ch === "'" || ch === '"') {
+      return this.parseString();
+    }
+
+    // Number literal (including negative)
+    if (ch === '-' || (ch >= '0' && ch <= '9')) {
+      return this.parseNumber();
+    }
+
+    // Identifier, boolean, null, or path
+    if (this.isIdentStart(ch)) {
+      return this.parseIdentifierOrPath();
+    }
+
+    throw new Error(
+      `Unexpected character at position ${this.pos}: '${ch || 'EOF'}'`,
+    );
+  }
+
+  private parseString(): ASTNode {
+    const quote = this.advance(); // consume opening quote
+    let value = '';
+    while (this.pos < this.input.length && this.peek() !== quote) {
+      if (this.peek() === '\\') {
+        this.advance(); // consume backslash
+        const esc = this.advance();
+        if (esc === 'n') value += '\n';
+        else if (esc === 't') value += '\t';
+        else if (esc === 'r') value += '\r';
+        else value += esc;
+      } else {
+        value += this.advance();
+      }
+    }
+    if (this.pos >= this.input.length) {
+      throw new Error('Unterminated string literal');
+    }
+    this.advance(); // consume closing quote
+    return { type: 'string', value };
+  }
+
+  private parseNumber(): ASTNode {
+    let numStr = '';
+    if (this.peek() === '-') {
+      numStr += this.advance();
+    }
+    while (this.pos < this.input.length && (this.input[this.pos] >= '0' && this.input[this.pos] <= '9')) {
+      numStr += this.advance();
+    }
+    if (this.peek() === '.' && this.pos + 1 < this.input.length && this.input[this.pos + 1] >= '0' && this.input[this.pos + 1] <= '9') {
+      numStr += this.advance(); // consume '.'
+      while (this.pos < this.input.length && (this.input[this.pos] >= '0' && this.input[this.pos] <= '9')) {
+        numStr += this.advance();
+      }
+    }
+    return { type: 'number', value: Number(numStr) };
+  }
+
+  private parseIdentifierOrPath(): ASTNode {
+    const name = this.parseIdentifierName();
+
+    // Check for keywords
+    if (name === 'true') return { type: 'boolean', value: true };
+    if (name === 'false') return { type: 'boolean', value: false };
+    if (name === 'null') return { type: 'null' };
+    if (name === 'undefined') return { type: 'null' };
+
+    return { type: 'identifier', name };
+  }
+
+  private parseIdentifierName(): string {
+    let name = '';
+    if (this.peek() === '$') name += this.advance();
+    while (this.pos < this.input.length && this.isIdentPart(this.input[this.pos])) {
+      name += this.advance();
+    }
+    if (!name) {
+      throw new Error(`Expected identifier at position ${this.pos}`);
+    }
+    return name;
+  }
+
+  private parseArgList(): ASTNode[] {
+    this.skipWhitespace();
+    if (this.peek() === ')') return [];
+
+    const args: ASTNode[] = [];
+    args.push(this.parseExpression());
+    this.skipWhitespace();
+    while (this.peek() === ',') {
+      this.advance(); // consume ','
+      args.push(this.parseExpression());
+      this.skipWhitespace();
+    }
+    return args;
+  }
+
+  // Character utilities
+
+  private peek(): string {
+    return this.input[this.pos] ?? '';
+  }
+
+  private advance(): string {
+    return this.input[this.pos++] ?? '';
+  }
+
+  private match(str: string): boolean {
+    if (this.input.startsWith(str, this.pos)) {
+      this.pos += str.length;
+      return true;
+    }
+    return false;
+  }
+
+  private lookAhead(str: string): boolean {
+    return this.input.startsWith(str, this.pos);
+  }
+
+  private expect(ch: string): void {
+    this.skipWhitespace();
+    if (this.peek() !== ch) {
+      throw new Error(`Expected '${ch}' at position ${this.pos}, got '${this.peek() || 'EOF'}'`);
+    }
+    this.advance();
+  }
+
+  private skipWhitespace(): void {
+    while (this.pos < this.input.length && ' \t\n\r'.includes(this.input[this.pos])) {
+      this.pos++;
+    }
+  }
+
+  private isIdentStart(ch: string): boolean {
+    return (
+      (ch >= 'a' && ch <= 'z') ||
+      (ch >= 'A' && ch <= 'Z') ||
+      ch === '_' ||
+      ch === '$'
+    );
+  }
+
+  private isIdentPart(ch: string): boolean {
+    return this.isIdentStart(ch) || (ch >= '0' && ch <= '9');
+  }
+}
+
+// =============================================================================
+// AST Evaluator
+// =============================================================================
+
+function evaluateAST(
+  node: ASTNode,
+  context: ExpressionContext,
+  fnMap: Map<string, ExpressionFunction['fn']>,
+): unknown {
+  switch (node.type) {
+    case 'number':
+      return node.value;
+    case 'string':
+      return node.value;
+    case 'boolean':
+      return node.value;
+    case 'null':
+      return null;
+
+    case 'identifier':
+      return resolvePath(node.name, context);
+
+    case 'path':
+      return resolvePath(node.segments.join('.'), context);
+
+    case 'member': {
+      const obj = evaluateAST(node.object, context, fnMap);
+      if (obj == null || typeof obj !== 'object') return undefined;
+      return (obj as Record<string, unknown>)[node.property];
+    }
+
+    case 'call': {
+      const fn = fnMap.get(node.name);
+      if (!fn) return undefined;
+      const args = node.args.map(a => evaluateAST(a, context, fnMap));
+      return fn(...args);
+    }
+
+    case 'method_call': {
+      // Try to resolve as a dotted function name first (e.g., Math.abs)
+      const obj = evaluateAST(node.object, context, fnMap);
+      if (obj != null && typeof obj === 'object') {
+        const method = (obj as Record<string, unknown>)[node.method];
+        if (typeof method === 'function') {
+          const args = node.args.map(a => evaluateAST(a, context, fnMap));
+          return method.apply(obj, args);
+        }
+      }
+      return undefined;
+    }
+
+    case 'unary': {
+      const operand = evaluateAST(node.operand, context, fnMap);
+      return !operand;
+    }
+
+    case 'binary': {
+      // Short-circuit for logical operators
+      if (node.operator === '&&') {
+        const left = evaluateAST(node.left, context, fnMap);
+        if (!left) return left;
+        return evaluateAST(node.right, context, fnMap);
+      }
+      if (node.operator === '||') {
+        const left = evaluateAST(node.left, context, fnMap);
+        if (left) return left;
+        return evaluateAST(node.right, context, fnMap);
+      }
+
+      const left = evaluateAST(node.left, context, fnMap);
+      const right = evaluateAST(node.right, context, fnMap);
+
+      switch (node.operator) {
+        // eslint-disable-next-line eqeqeq
+        case '==': return left == right;
+        // eslint-disable-next-line eqeqeq
+        case '!=': return left != right;
+        case '>': return Number(left) > Number(right);
+        case '<': return Number(left) < Number(right);
+        case '>=': return Number(left) >= Number(right);
+        case '<=': return Number(left) <= Number(right);
+        default: return undefined;
+      }
+    }
+
+    case 'ternary': {
+      const condition = evaluateAST(node.condition, context, fnMap);
+      return condition
+        ? evaluateAST(node.consequent, context, fnMap)
+        : evaluateAST(node.alternate, context, fnMap);
+    }
+  }
+}
+
+// =============================================================================
+// AST Cache
+// =============================================================================
+
+const MAX_CACHE = 500;
+
+/** Parsed AST cache — shared across evaluator instances */
+const astCache = new Map<string, ASTNode>();
+
+function evictIfNeeded(): void {
+  if (astCache.size > MAX_CACHE) {
+    const keys = Array.from(astCache.keys());
+    const evictCount = Math.floor(MAX_CACHE * 0.25);
+    for (let i = 0; i < evictCount; i++) {
+      astCache.delete(keys[i]!);
+    }
+  }
+}
+
+function parseAndCache(expr: string): ASTNode {
+  const cached = astCache.get(expr);
+  if (cached) return cached;
+
+  const parser = new Parser(expr);
+  const ast = parser.parse();
+  astCache.set(expr, ast);
+  evictIfNeeded();
+  return ast;
+}
+
+// =============================================================================
+// Public API (unchanged signatures)
+// =============================================================================
+
+/** Template regex: matches {{expression}} */
+const TEMPLATE_RE = /\{\{(.+?)\}\}/g;
+
+/**
+ * Resolve a dot-path from a context object.
+ * Handles: "state_data.title", "$instance.fields.name"
+ */
+function resolvePath(path: string, context: ExpressionContext): unknown {
+  const parts = path.split('.');
+  let current: unknown = context;
+  for (const part of parts) {
+    if (current == null || typeof current !== 'object') return undefined;
+    current = (current as Record<string, unknown>)[part];
+  }
+  return current;
+}
+
+/**
+ * Evaluate a single expression string against a context.
+ */
+function evaluateExpression(
+  expr: string,
+  context: ExpressionContext,
+  fnMap: Map<string, ExpressionFunction['fn']>,
+): unknown {
+  const trimmed = expr.trim();
+
+  // Fast paths for common patterns
+  if (trimmed === 'true') return true;
+  if (trimmed === 'false') return false;
+  if (trimmed === 'null') return null;
+  if (trimmed === 'undefined') return undefined;
+
+  // Numeric literal
+  const num = Number(trimmed);
+  if (!isNaN(num) && trimmed !== '') return num;
+
+  // String literal (single or double quoted)
+  if (
+    (trimmed.startsWith("'") && trimmed.endsWith("'")) ||
+    (trimmed.startsWith('"') && trimmed.endsWith('"'))
+  ) {
+    return trimmed.slice(1, -1);
+  }
+
+  // Simple path (no operators, no function calls)
+  if (/^[a-zA-Z_$][\w$.]*$/.test(trimmed)) {
+    return resolvePath(trimmed, context);
+  }
+
+  // Parse expression to AST and evaluate
+  const ast = parseAndCache(trimmed);
+  return evaluateAST(ast, context, fnMap);
+}
+
+/**
+ * WEB_FAILURE_POLICIES — predefined failure policies for Web Player contexts.
+ */
+export const WEB_FAILURE_POLICIES: Record<string, FailurePolicy> = {
+  VIEW_BINDING: {
+    on_error: 'return_fallback',
+    fallback_value: '',
+    log_level: 'warn',
+  },
+  EVENT_REACTION: {
+    on_error: 'log_and_skip',
+    fallback_value: undefined,
+    log_level: 'error',
+  },
+  DURING_ACTION: {
+    on_error: 'log_and_skip',
+    fallback_value: undefined,
+    log_level: 'error',
+  },
+  CONDITIONAL_VISIBILITY: {
+    on_error: 'return_fallback',
+    fallback_value: true, // Show by default if condition fails
+    log_level: 'warn',
+  },
+};
+
+/**
+ * createEvaluator — factory function that builds a configured evaluator.
+ *
+ * @param config - Function registry and failure policy
+ * @returns Evaluator instance with evaluate, evaluateTemplate, and validate methods
+ */
+export function createEvaluator(config: EvaluatorConfig): Evaluator {
+  const allFunctions = [...CORE_FUNCTIONS, ...config.functions];
+  const fnMap = buildFunctionMap(allFunctions);
+  const policy = config.failurePolicy;
+
+  function handleError(expr: string, error: unknown): ExpressionResult {
+    const message = error instanceof Error ? error.message : String(error);
+
+    if (policy.log_level === 'error') {
+      console.error(`[player-core] Expression error: "${expr}" — ${message}`);
+    } else if (policy.log_level === 'warn') {
+      console.warn(`[player-core] Expression error: "${expr}" — ${message}`);
+    }
+
+    switch (policy.on_error) {
+      case 'throw':
+        throw error;
+      case 'return_fallback':
+        return { value: policy.fallback_value, status: 'fallback', error: message };
+      case 'log_and_skip':
+      default:
+        return { value: policy.fallback_value, status: 'error', error: message };
+    }
+  }
+
+  return {
+    evaluate<T = unknown>(expression: string, context: ExpressionContext): ExpressionResult<T> {
+      try {
+        const value = evaluateExpression(expression, context, fnMap);
+        return { value: value as T, status: 'ok' };
+      } catch (error) {
+        return handleError(expression, error) as ExpressionResult<T>;
+      }
+    },
+
+    evaluateTemplate(template: string, context: ExpressionContext): ExpressionResult<string> {
+      try {
+        // If no template markers, return as-is
+        if (!template.includes('{{')) {
+          return { value: template, status: 'ok' };
+        }
+
+        const result = template.replace(TEMPLATE_RE, (_match, expr: string) => {
+          const value = evaluateExpression(expr, context, fnMap);
+          return value != null ? String(value) : '';
+        });
+
+        return { value: result, status: 'ok' };
+      } catch (error) {
+        return handleError(template, error) as ExpressionResult<string>;
+      }
+    },
+
+    validate(expression: string): { valid: boolean; errors: string[] } {
+      const errors: string[] = [];
+
+      try {
+        parseAndCache(expression);
+      } catch (e) {
+        errors.push(e instanceof Error ? e.message : String(e));
+      }
+
+      return { valid: errors.length === 0, errors };
+    },
+  };
+}
+
+/** Clear parsed AST cache (for testing) */
+export function clearExpressionCache(): void {
+  astCache.clear();
+}