@object-ui/core 3.3.0 → 3.3.1

package/src/evaluator/ExpressionCache.ts

@@ -1,206 +0,0 @@
-/**
- * ObjectUI
- * Copyright (c) 2024-present ObjectStack Inc.
- *
- * This source code is licensed under the MIT license found in the
- * LICENSE file in the root directory of this source tree.
- */
-
-/**
- * @object-ui/core - Expression Cache
- *
- * Caches compiled expressions to avoid re-parsing on every render.
- * Provides significant performance improvement for frequently evaluated expressions.
- *
- * @module evaluator
- * @packageDocumentation
- */
-
-import { SafeExpressionParser } from './SafeExpressionParser.js';
-
-/**
- * A compiled expression function that can be executed with context values
- */
-export type CompiledExpression = (...args: any[]) => any;
-
-/**
- * Expression compilation metadata
- */
-export interface ExpressionMetadata {
-  /**
-   * The compiled function
-   */
-  fn: CompiledExpression;
-  
-  /**
-   * Variable names used in the expression
-   */
-  varNames: string[];
-  
-  /**
-   * Original expression string
-   */
-  expression: string;
-  
-  /**
-   * Timestamp when the expression was compiled
-   */
-  compiledAt: number;
-  
-  /**
-   * Number of times this expression has been used
-   */
-  hitCount: number;
-}
-
-/**
- * Cache for compiled expressions
- * 
- * @example
- * ```ts
- * const cache = new ExpressionCache();
- * const compiled = cache.compile('data.amount > 1000', ['data']);
- * const result = compiled.fn({ amount: 1500 }); // true
- * ```
- */
-export class ExpressionCache {
-  private cache = new Map<string, ExpressionMetadata>();
-  private maxSize: number;
-  
-  /**
-   * Create a new expression cache
-   * 
-   * @param maxSize Maximum number of expressions to cache (default: 1000)
-   */
-  constructor(maxSize = 1000) {
-    this.maxSize = maxSize;
-  }
-  
-  /**
-   * Compile an expression or retrieve from cache
-   * 
-   * @param expr The expression to compile
-   * @param varNames Variable names available in the context
-   * @returns Compiled expression metadata
-   */
-  compile(expr: string, varNames: string[]): ExpressionMetadata {
-    // Create a cache key that includes variable names to ensure correct scoping
-    const cacheKey = `${expr}::${varNames.join(',')}`;
-    
-    if (this.cache.has(cacheKey)) {
-      const metadata = this.cache.get(cacheKey)!;
-      metadata.hitCount++;
-      return metadata;
-    }
-    
-    // Evict least frequently used if cache is full
-    if (this.cache.size >= this.maxSize) {
-      this.evictLFU();
-    }
-    
-    // Compile the expression
-    const fn = this.compileExpression(expr, varNames);
-    
-    const metadata: ExpressionMetadata = {
-      fn,
-      varNames: [...varNames],
-      expression: expr,
-      compiledAt: Date.now(),
-      hitCount: 1,
-    };
-    
-    this.cache.set(cacheKey, metadata);
-    return metadata;
-  }
-  
-  /**
-   * Compile an expression into a CSP-safe callable function.
-   *
-   * Uses `SafeExpressionParser` — a recursive-descent interpreter — instead of
-   * `new Function()` so that the expression engine works under strict
-   * Content Security Policy headers that forbid `'unsafe-eval'`.
-   *
-   * A single parser instance is created per compiled expression and reused
-   * across all invocations of the returned closure (`evaluate()` resets all
-   * internal state on every call), avoiding repeated allocations on hot paths.
-   */
-  private compileExpression(expression: string, varNames: string[]): CompiledExpression {
-    // One parser per compiled expression — reused across hot-path calls.
-    const parser = new SafeExpressionParser();
-
-    return (...args: unknown[]) => {
-      // Reconstruct the named variable context from positional arguments.
-      const context: Record<string, unknown> = {};
-      for (let i = 0; i < varNames.length; i++) {
-        context[varNames[i]] = args[i];
-      }
-      return parser.evaluate(expression, context);
-    };
-  }
-  
-  /**
-   * Evict the least frequently used expression from cache
-   */
-  private evictLFU(): void {
-    let oldestKey: string | null = null;
-    let oldestTime = Infinity;
-    let lowestHits = Infinity;
-    
-    // Find the entry with lowest hit count, or oldest if tied
-    for (const [key, metadata] of this.cache.entries()) {
-      if (metadata.hitCount < lowestHits || 
-          (metadata.hitCount === lowestHits && metadata.compiledAt < oldestTime)) {
-        oldestKey = key;
-        oldestTime = metadata.compiledAt;
-        lowestHits = metadata.hitCount;
-      }
-    }
-    
-    if (oldestKey) {
-      this.cache.delete(oldestKey);
-    }
-  }
-  
-  /**
-   * Check if an expression is cached
-   */
-  has(expr: string, varNames: string[]): boolean {
-    const cacheKey = `${expr}::${varNames.join(',')}`;
-    return this.cache.has(cacheKey);
-  }
-  
-  /**
-   * Clear the cache
-   */
-  clear(): void {
-    this.cache.clear();
-  }
-  
-  /**
-   * Get cache statistics
-   */
-  getStats(): {
-    size: number;
-    maxSize: number;
-    totalHits: number;
-    entries: Array<{ expression: string; hitCount: number }>;
-  } {
-    let totalHits = 0;
-    const entries: Array<{ expression: string; hitCount: number }> = [];
-    
-    for (const metadata of this.cache.values()) {
-      totalHits += metadata.hitCount;
-      entries.push({
-        expression: metadata.expression,
-        hitCount: metadata.hitCount,
-      });
-    }
-    
-    return {
-      size: this.cache.size,
-      maxSize: this.maxSize,
-      totalHits,
-      entries: entries.sort((a, b) => b.hitCount - a.hitCount),
-    };
-  }
-}

package/src/evaluator/ExpressionContext.ts

@@ -1,118 +0,0 @@
-/**
- * ObjectUI
- * Copyright (c) 2024-present ObjectStack Inc.
- *
- * This source code is licensed under the MIT license found in the
- * LICENSE file in the root directory of this source tree.
- */
-
-/**
- * @object-ui/core - Expression Context
- * 
- * Manages variable scope and data context for expression evaluation.
- * 
- * @module evaluator
- * @packageDocumentation
- */
-
-/**
- * Expression context for variable resolution
- */
-export class ExpressionContext {
-  private scopes: Map<string, any>[] = [];
-
-  constructor(initialData: Record<string, any> = {}) {
-    this.scopes.push(new Map(Object.entries(initialData)));
-  }
-
-  /**
-   * Push a new scope onto the context stack
-   */
-  pushScope(data: Record<string, any>): void {
-    this.scopes.push(new Map(Object.entries(data)));
-  }
-
-  /**
-   * Pop the current scope from the context stack
-   */
-  popScope(): void {
-    if (this.scopes.length > 1) {
-      this.scopes.pop();
-    }
-  }
-
-  /**
-   * Get a variable value from the context
-   * Searches from innermost to outermost scope
-   */
-  get(path: string): any {
-    // Split path by dots for nested access
-    const parts = path.split('.');
-    const varName = parts[0];
-
-    // Search scopes from innermost to outermost
-    for (let i = this.scopes.length - 1; i >= 0; i--) {
-      if (this.scopes[i].has(varName)) {
-        let value = this.scopes[i].get(varName);
-        
-        // Navigate nested path
-        for (let j = 1; j < parts.length; j++) {
-          if (value && typeof value === 'object') {
-            value = value[parts[j]];
-          } else {
-            return undefined;
-          }
-        }
-        
-        return value;
-      }
-    }
-
-    return undefined;
-  }
-
-  /**
-   * Set a variable value in the current scope
-   */
-  set(name: string, value: any): void {
-    if (this.scopes.length > 0) {
-      this.scopes[this.scopes.length - 1].set(name, value);
-    }
-  }
-
-  /**
-   * Check if a variable exists in any scope
-   */
-  has(name: string): boolean {
-    const varName = name.split('.')[0];
-    for (let i = this.scopes.length - 1; i >= 0; i--) {
-      if (this.scopes[i].has(varName)) {
-        return true;
-      }
-    }
-    return false;
-  }
-
-  /**
-   * Get all variables from all scopes as a flat object
-   */
-  toObject(): Record<string, any> {
-    const result: Record<string, any> = {};
-    // Merge from outermost to innermost (later scopes override earlier ones)
-    for (const scope of this.scopes) {
-      for (const [key, value] of scope.entries()) {
-        result[key] = value;
-      }
-    }
-    return result;
-  }
-
-  /**
-   * Create a child context with additional data
-   */
-  createChild(data: Record<string, any> = {}): ExpressionContext {
-    const child = new ExpressionContext();
-    child.scopes = [...this.scopes, new Map(Object.entries(data))];
-    return child;
-  }
-}

package/src/evaluator/ExpressionEvaluator.ts

@@ -1,315 +0,0 @@
-/**
- * ObjectUI
- * Copyright (c) 2024-present ObjectStack Inc.
- *
- * This source code is licensed under the MIT license found in the
- * LICENSE file in the root directory of this source tree.
- */
-
-/**
- * @object-ui/core - Expression Evaluator
- * 
- * Evaluates template string expressions like ${data.amount > 1000} for dynamic UI behavior.
- * Supports variable substitution, comparison operators, and basic JavaScript expressions.
- * 
- * @module evaluator
- * @packageDocumentation
- */
-
-import { ExpressionContext } from './ExpressionContext.js';
-import { ExpressionCache } from './ExpressionCache.js';
-import { FormulaFunctions } from './FormulaFunctions.js';
-
-/**
- * Options for expression evaluation
- */
-export interface EvaluationOptions {
-  /**
-   * Default value to return if evaluation fails
-   */
-  defaultValue?: any;
-  
-  /**
-   * Whether to throw errors on evaluation failure
-   * @default false
-   */
-  throwOnError?: boolean;
-  
-  /**
-   * Whether to sanitize the expression before evaluation
-   * @default true
-   */
-  sanitize?: boolean;
-}
-
-/**
- * Expression evaluator for dynamic UI expressions
- */
-export class ExpressionEvaluator {
-  private context: ExpressionContext;
-  private cache: ExpressionCache;
-  private formulas: FormulaFunctions;
-
-  constructor(
-    context?: ExpressionContext | Record<string, any>,
-    cache?: ExpressionCache,
-    formulas?: FormulaFunctions,
-  ) {
-    if (context instanceof ExpressionContext) {
-      this.context = context;
-    } else {
-      this.context = new ExpressionContext(context || {});
-    }
-    
-    // Use provided cache or create a new one
-    this.cache = cache || new ExpressionCache();
-    this.formulas = formulas || new FormulaFunctions();
-  }
-
-  /**
-   * Evaluate a string that may contain template expressions like ${...}
-   * 
-   * @example
-   * ```ts
-   * const evaluator = new ExpressionEvaluator({ data: { amount: 1500 } });
-   * evaluator.evaluate('${data.amount > 1000}'); // Returns: true
-   * evaluator.evaluate('Amount is ${data.amount}'); // Returns: "Amount is 1500"
-   * ```
-   */
-  evaluate(expression: string | boolean | number | null | undefined, options: EvaluationOptions = {}): any {
-    // Handle non-string primitives
-    if (typeof expression !== 'string') {
-      return expression;
-    }
-
-    const { defaultValue, throwOnError = false, sanitize = true } = options;
-
-    try {
-      // Check if string contains template expressions
-      const hasTemplates = expression.includes('${');
-      
-      if (!hasTemplates) {
-        // No templates, return as-is
-        return expression;
-      }
-
-      // Special case: if the entire string is a single template expression, return the value directly
-      const singleTemplateMatch = expression.match(/^\$\{([^}]+)\}$/);
-      if (singleTemplateMatch) {
-        return this.evaluateExpression(singleTemplateMatch[1].trim(), { sanitize });
-      }
-
-      // Replace all ${...} expressions in a string with multiple parts
-      return expression.replace(/\$\{([^}]+)\}/g, (match, expr) => {
-        try {
-          const result = this.evaluateExpression(expr.trim(), { sanitize });
-          return String(result ?? '');
-        } catch (error) {
-          if (throwOnError) {
-            throw error;
-          }
-          console.warn(`Expression evaluation failed for: ${expr}`, error);
-          return match; // Return original if evaluation fails
-        }
-      });
-    } catch (error) {
-      if (throwOnError) {
-        throw error;
-      }
-      console.warn(`Failed to evaluate expression: ${expression}`, error);
-      return defaultValue ?? expression;
-    }
-  }
-
-  /**
-   * Evaluate a single expression (without ${} wrapper)
-   * 
-   * @example
-   * ```ts
-   * evaluator.evaluateExpression('data.amount > 1000'); // Returns: true
-   * evaluator.evaluateExpression('data.user.name'); // Returns: "John"
-   * ```
-   */
-  evaluateExpression(expression: string, options: { sanitize?: boolean } = {}): any {
-    const { sanitize = true } = options;
-
-    if (!expression || expression.trim() === '') {
-      return undefined;
-    }
-
-    // Sanitize expression to prevent dangerous code execution
-    if (sanitize && this.isDangerous(expression)) {
-      throw new Error(`Potentially dangerous expression detected: ${expression}`);
-    }
-
-    try {
-      // Create a safe evaluation function
-      const contextObj = this.context.toObject();
-      
-      // Inject formula functions into the evaluation context
-      const formulaObj = this.formulas.toObject();
-      const mergedContext = { ...formulaObj, ...contextObj };
-      
-      // Build safe function with context variables
-      const varNames = Object.keys(mergedContext);
-      const varValues = Object.values(mergedContext);
-      
-      // Use cached compilation
-      const compiled = this.cache.compile(expression, varNames);
-      
-      // Execute with context values
-      return compiled.fn(...varValues);
-    } catch (error) {
-      throw new Error(`Failed to evaluate expression "${expression}": ${(error as Error).message}`);
-    }
-  }
-
-  /**
-   * Check if expression contains potentially dangerous code
-   */
-  private isDangerous(expression: string): boolean {
-    const dangerousPatterns = [
-      /eval\s*\(/i,
-      /Function\s*\(/i,
-      /setTimeout\s*\(/i,
-      /setInterval\s*\(/i,
-      /import\s*\(/i,
-      /require\s*\(/i,
-      /process\./i,
-      /global\./i,
-      /window\./i,
-      /document\./i,
-      /__proto__/i,
-      /constructor\s*\(/i,
-      /prototype\./i,
-    ];
-
-    return dangerousPatterns.some(pattern => pattern.test(expression));
-  }
-
-  /**
-   * Evaluate a conditional expression and return boolean
-   * 
-   * @example
-   * ```ts
-   * evaluator.evaluateCondition('${data.age >= 18}'); // Returns: true/false
-   * ```
-   */
-  evaluateCondition(condition: string | boolean | undefined, options: EvaluationOptions = {}): boolean {
-    if (typeof condition === 'boolean') {
-      return condition;
-    }
-
-    if (!condition) {
-      return true; // Default to visible/enabled if no condition
-    }
-
-    const result = this.evaluate(condition, options);
-    
-    // Convert result to boolean
-    return Boolean(result);
-  }
-
-  /**
-   * Update the context with new data
-   */
-  updateContext(data: Record<string, any>): void {
-    Object.entries(data).forEach(([key, value]) => {
-      this.context.set(key, value);
-    });
-  }
-
-  /**
-   * Get the current context
-   */
-  getContext(): ExpressionContext {
-    return this.context;
-  }
-
-  /**
-   * Create a new evaluator with additional context data
-   */
-  withContext(data: Record<string, any>): ExpressionEvaluator {
-    // Share the cache and formulas with the new evaluator for maximum efficiency
-    return new ExpressionEvaluator(this.context.createChild(data), this.cache, this.formulas);
-  }
-  
-  /**
-   * Get cache statistics (useful for debugging and optimization)
-   */
-  getCacheStats() {
-    return this.cache.getStats();
-  }
-  
-  /**
-   * Clear the expression cache
-   */
-  clearCache(): void {
-    this.cache.clear();
-  }
-
-  /**
-   * Get the formula functions registry
-   */
-  getFormulas(): FormulaFunctions {
-    return this.formulas;
-  }
-
-  /**
-   * Register a custom formula function
-   */
-  registerFunction(name: string, fn: (...args: any[]) => any): void {
-    this.formulas.register(name, fn);
-  }
-}
-
-/**
- * Shared global cache and formulas for convenience functions
- */
-const globalCache = new ExpressionCache();
-const globalFormulas = new FormulaFunctions();
-
-/**
- * Convenience function to quickly evaluate an expression
- */
-export function evaluateExpression(
-  expression: string | boolean | number | null | undefined,
-  context: Record<string, any> = {},
-  options: EvaluationOptions = {}
-): any {
-  const evaluator = new ExpressionEvaluator(context, globalCache, globalFormulas);
-  return evaluator.evaluate(expression, options);
-}
-
-/**
- * Convenience function to evaluate a condition
- */
-export function evaluateCondition(
-  condition: string | boolean | undefined,
-  context: Record<string, any> = {}
-): boolean {
-  const evaluator = new ExpressionEvaluator(context, globalCache, globalFormulas);
-  return evaluator.evaluateCondition(condition);
-}
-
-/**
- * Convenience function to evaluate a plain condition string against a data record.
- * Supports both template expressions (e.g., '${data.amount > 1000}') and
- * plain expressions (e.g., "status == 'overdue'").
- * Record fields are available both directly (status) and namespaced (data.status).
- */
-export function evaluatePlainCondition(
-  condition: string,
-  record: Record<string, any>
-): boolean {
-  const evaluator = new ExpressionEvaluator({ ...record, data: record }, globalCache, globalFormulas);
-  try {
-    const isTemplate = /\$\{/.test(condition);
-    const result = isTemplate
-      ? evaluator.evaluate(condition, { throwOnError: true })
-      : evaluator.evaluateExpression(condition);
-    return result === true;
-  } catch {
-    return false;
-  }
-}