@object-ui/core 0.3.1 → 2.0.0

package/src/data-scope/index.ts

@@ -0,0 +1,16 @@
+/**
+ * @object-ui/core - DataScope Module
+ *
+ * Runtime data scope management for row-level security and
+ * reactive data state within the UI component tree.
+ *
+ * @module data-scope
+ * @packageDocumentation
+ */
+
+export {
+  DataScopeManager,
+  defaultDataScopeManager,
+  type RowLevelFilter,
+  type DataScopeConfig,
+} from './DataScopeManager.js';

package/src/evaluator/ExpressionCache.ts

@@ -0,0 +1,192 @@
+/**
+ * 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
+ */
+
+/**
+ * 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 function
+   */
+  private compileExpression(expression: string, varNames: string[]): CompiledExpression {
+    // SECURITY NOTE: Using Function constructor for expression evaluation.
+    // This is a controlled use case with:
+    // 1. Sanitization check (isDangerous) performed by caller
+    // 2. Strict mode enabled ("use strict")
+    // 3. Limited scope (only varNames variables available)
+    // 4. No access to global objects (process, window, etc.)
+    return new Function(...varNames, `"use strict"; return (${expression});`) as CompiledExpression;
+  }
+  
+  /**
+   * 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/ExpressionEvaluator.ts

@@ -16,7 +16,9 @@
  * @packageDocumentation
  */
 
-import { ExpressionContext } from './ExpressionContext';
+import { ExpressionContext } from './ExpressionContext.js';
+import { ExpressionCache } from './ExpressionCache.js';
+import { FormulaFunctions } from './FormulaFunctions.js';
 
 /**
  * Options for expression evaluation
@@ -45,13 +47,23 @@ export interface EvaluationOptions {
  */
 export class ExpressionEvaluator {
   private context: ExpressionContext;
+  private cache: ExpressionCache;
+  private formulas: FormulaFunctions;
 
-  constructor(context?: ExpressionContext | Record<string, any>) {
+  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();
   }
 
   /**
@@ -134,21 +146,19 @@ export class ExpressionEvaluator {
       // 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(contextObj);
-      const varValues = Object.values(contextObj);
+      const varNames = Object.keys(mergedContext);
+      const varValues = Object.values(mergedContext);
       
-      // SECURITY NOTE: Using Function constructor for expression evaluation.
-      // This is a controlled use case with:
-      // 1. Sanitization check (isDangerous) blocks dangerous patterns
-      // 2. Strict mode enabled ("use strict")
-      // 3. Limited scope (only contextObj variables available)
-      // 4. No access to global objects (process, window, etc.)
-      // For production use, consider: expr-eval, safe-eval, or a custom parser
-      const fn = new Function(...varNames, `"use strict"; return (${expression});`);
+      // Use cached compilation
+      const compiled = this.cache.compile(expression, varNames);
       
       // Execute with context values
-      return fn(...varValues);
+      return compiled.fn(...varValues);
     } catch (error) {
       throw new Error(`Failed to evaluate expression "${expression}": ${(error as Error).message}`);
     }
@@ -220,10 +230,45 @@ export class ExpressionEvaluator {
    * Create a new evaluator with additional context data
    */
   withContext(data: Record<string, any>): ExpressionEvaluator {
-    return new ExpressionEvaluator(this.context.createChild(data));
+    // 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
  */
@@ -232,7 +277,7 @@ export function evaluateExpression(
   context: Record<string, any> = {},
   options: EvaluationOptions = {}
 ): any {
-  const evaluator = new ExpressionEvaluator(context);
+  const evaluator = new ExpressionEvaluator(context, globalCache, globalFormulas);
   return evaluator.evaluate(expression, options);
 }
 
@@ -243,6 +288,6 @@ export function evaluateCondition(
   condition: string | boolean | undefined,
   context: Record<string, any> = {}
 ): boolean {
-  const evaluator = new ExpressionEvaluator(context);
+  const evaluator = new ExpressionEvaluator(context, globalCache, globalFormulas);
   return evaluator.evaluateCondition(condition);
 }