@object-ui/core 0.3.1 → 0.5.0

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,8 @@
  * @packageDocumentation
  */
 
-import { ExpressionContext } from './ExpressionContext';
+import { ExpressionContext } from './ExpressionContext.js';
+import { ExpressionCache } from './ExpressionCache.js';
 
 /**
  * Options for expression evaluation
@@ -45,13 +46,17 @@ export interface EvaluationOptions {
  */
 export class ExpressionEvaluator {
   private context: ExpressionContext;
+  private cache: ExpressionCache;
 
-  constructor(context?: ExpressionContext | Record<string, any>) {
+  constructor(context?: ExpressionContext | Record<string, any>, cache?: ExpressionCache) {
     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();
   }
 
   /**
@@ -138,17 +143,11 @@ export class ExpressionEvaluator {
       const varNames = Object.keys(contextObj);
       const varValues = Object.values(contextObj);
       
-      // 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 +219,30 @@ 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 with the new evaluator for maximum efficiency
+    return new ExpressionEvaluator(this.context.createChild(data), this.cache);
+  }
+  
+  /**
+   * Get cache statistics (useful for debugging and optimization)
+   */
+  getCacheStats() {
+    return this.cache.getStats();
+  }
+  
+  /**
+   * Clear the expression cache
+   */
+  clearCache(): void {
+    this.cache.clear();
   }
 }
 
+/**
+ * Shared global cache for convenience functions
+ */
+const globalCache = new ExpressionCache();
+
 /**
  * Convenience function to quickly evaluate an expression
  */
@@ -232,7 +251,7 @@ export function evaluateExpression(
   context: Record<string, any> = {},
   options: EvaluationOptions = {}
 ): any {
-  const evaluator = new ExpressionEvaluator(context);
+  const evaluator = new ExpressionEvaluator(context, globalCache);
   return evaluator.evaluate(expression, options);
 }
 
@@ -243,6 +262,6 @@ export function evaluateCondition(
   condition: string | boolean | undefined,
   context: Record<string, any> = {}
 ): boolean {
-  const evaluator = new ExpressionEvaluator(context);
+  const evaluator = new ExpressionEvaluator(context, globalCache);
   return evaluator.evaluateCondition(condition);
 }

package/src/evaluator/__tests__/ExpressionCache.test.ts

@@ -0,0 +1,135 @@
+/**
+ * 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.
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest';
+import { ExpressionCache } from '../ExpressionCache';
+
+describe('ExpressionCache', () => {
+  let cache: ExpressionCache;
+
+  beforeEach(() => {
+    cache = new ExpressionCache();
+  });
+
+  it('should compile and cache an expression', () => {
+    const expr = 'data.amount > 1000';
+    const varNames = ['data'];
+    
+    const compiled = cache.compile(expr, varNames);
+    
+    expect(compiled).toBeDefined();
+    expect(compiled.expression).toBe(expr);
+    expect(compiled.varNames).toEqual(varNames);
+    expect(compiled.hitCount).toBe(1);
+  });
+
+  it('should return cached expression on second call', () => {
+    const expr = 'data.amount > 1000';
+    const varNames = ['data'];
+    
+    const first = cache.compile(expr, varNames);
+    const second = cache.compile(expr, varNames);
+    
+    expect(first).toBe(second);
+    expect(second.hitCount).toBe(2);
+  });
+
+  it('should execute compiled expression correctly', () => {
+    const expr = 'data.amount > 1000';
+    const varNames = ['data'];
+    
+    const compiled = cache.compile(expr, varNames);
+    const result = compiled.fn({ amount: 1500 });
+    
+    expect(result).toBe(true);
+  });
+
+  it('should handle multiple expressions', () => {
+    const expr1 = 'data.amount > 1000';
+    const expr2 = 'data.name === "John"';
+    const varNames = ['data'];
+    
+    const compiled1 = cache.compile(expr1, varNames);
+    const compiled2 = cache.compile(expr2, varNames);
+    
+    expect(compiled1).not.toBe(compiled2);
+    expect(compiled1.fn({ amount: 1500 })).toBe(true);
+    expect(compiled2.fn({ name: 'John' })).toBe(true);
+  });
+
+  it('should differentiate between different variable contexts', () => {
+    const expr = 'x + y';
+    
+    const compiled1 = cache.compile(expr, ['x', 'y']);
+    const compiled2 = cache.compile(expr, ['x', 'y', 'z']);
+    
+    // Different variable contexts should create different cache entries
+    expect(compiled1).not.toBe(compiled2);
+  });
+
+  it('should provide cache statistics', () => {
+    cache.compile('data.amount > 1000', ['data']);
+    cache.compile('data.amount > 1000', ['data']); // Second call, increment hit
+    cache.compile('data.name === "John"', ['data']);
+    
+    const stats = cache.getStats();
+    
+    expect(stats.size).toBe(2);
+    expect(stats.totalHits).toBe(3);
+    expect(stats.entries).toHaveLength(2);
+    expect(stats.entries[0].hitCount).toBe(2); // Most frequently used
+  });
+
+  it('should evict LRU when cache is full', () => {
+    const smallCache = new ExpressionCache(3);
+    
+    smallCache.compile('expr1', ['x']);
+    smallCache.compile('expr2', ['x']);
+    smallCache.compile('expr3', ['x']);
+    
+    // Access expr1 multiple times to increase hit count
+    smallCache.compile('expr1', ['x']);
+    smallCache.compile('expr1', ['x']);
+    
+    // Add a 4th expression, should evict least used (expr2 or expr3)
+    smallCache.compile('expr4', ['x']);
+    
+    const stats = smallCache.getStats();
+    expect(stats.size).toBe(3);
+    
+    // expr1 should still be cached (highest hit count)
+    expect(smallCache.has('expr1', ['x'])).toBe(true);
+  });
+
+  it('should clear cache', () => {
+    cache.compile('data.amount > 1000', ['data']);
+    cache.compile('data.name === "John"', ['data']);
+    
+    expect(cache.getStats().size).toBe(2);
+    
+    cache.clear();
+    
+    expect(cache.getStats().size).toBe(0);
+  });
+
+  it('should handle complex expressions', () => {
+    const expr = 'data.items.filter(item => item.price > 100).length';
+    const varNames = ['data'];
+    
+    const compiled = cache.compile(expr, varNames);
+    const result = compiled.fn({
+      items: [
+        { price: 50 },
+        { price: 150 },
+        { price: 200 },
+      ],
+    });
+    
+    expect(result).toBe(2);
+  });
+});

package/src/evaluator/index.ts

@@ -6,5 +6,6 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-export * from './ExpressionContext';
-export * from './ExpressionEvaluator';
+export * from './ExpressionContext.js';
+export * from './ExpressionEvaluator.js';
+export * from './ExpressionCache.js';

package/src/index.ts

@@ -6,13 +6,16 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-export * from './types';
-export * from './registry/Registry';
-export * from './validation/schema-validator';
-export * from './builder/schema-builder';
-export * from './utils/filter-converter';
-export * from './evaluator';
-export * from './actions';
+export type { SchemaNode, ComponentRendererProps } from './types/index.js';
+export * from './registry/Registry.js';
+export * from './registry/PluginSystem.js';
+export * from './registry/PluginScopeImpl.js';
+export * from './validation/index.js';
+export * from './builder/schema-builder.js';
+export * from './utils/filter-converter.js';
+export * from './evaluator/index.js';
+export * from './actions/index.js';
+export * from './query/index.js';
 // export * from './data-scope'; // TODO
 // export * from './validators'; // TODO
 

package/src/query/__tests__/query-ast.test.ts

@@ -0,0 +1,211 @@
+/**
+ * @object-ui/core - Query AST Builder Tests
+ */
+
+import { describe, it, expect } from 'vitest';
+import { QueryASTBuilder } from '../query-ast';
+import type { QuerySchema } from '@object-ui/types';
+
+describe('QueryASTBuilder', () => {
+  const builder = new QueryASTBuilder();
+
+  describe('Basic Query Building', () => {
+    it('should build simple SELECT query', () => {
+      const query: QuerySchema = {
+        object: 'users',
+        fields: ['id', 'name', 'email'],
+      };
+
+      const ast = builder.build(query);
+
+      expect(ast.select.type).toBe('select');
+      expect(ast.select.fields).toHaveLength(3);
+      expect(ast.from.table).toBe('users');
+    });
+
+    it('should build SELECT * when no fields specified', () => {
+      const query: QuerySchema = {
+        object: 'users',
+      };
+
+      const ast = builder.build(query);
+
+      expect(ast.select.fields).toHaveLength(1);
+      expect(ast.select.fields[0]).toMatchObject({
+        type: 'field',
+        name: '*',
+      });
+    });
+
+    it('should build query with WHERE clause', () => {
+      const query: QuerySchema = {
+        object: 'users',
+        fields: ['id', 'name'],
+        filter: {
+          conditions: [
+            {
+              field: 'status',
+              operator: 'equals',
+              value: 'active',
+            },
+          ],
+        },
+      };
+
+      const ast = builder.build(query);
+
+      expect(ast.where).toBeDefined();
+      expect(ast.where?.type).toBe('where');
+      expect(ast.where?.condition.type).toBe('operator');
+    });
+
+    it('should build query with ORDER BY', () => {
+      const query: QuerySchema = {
+        object: 'users',
+        fields: ['id', 'name'],
+        sort: [
+          { field: 'created_at', order: 'desc' },
+          { field: 'name', order: 'asc' },
+        ],
+      };
+
+      const ast = builder.build(query);
+
+      expect(ast.order_by).toBeDefined();
+      expect(ast.order_by?.fields).toHaveLength(2);
+      expect(ast.order_by?.fields[0].direction).toBe('desc');
+    });
+
+    it('should build query with LIMIT and OFFSET', () => {
+      const query: QuerySchema = {
+        object: 'users',
+        fields: ['id', 'name'],
+        limit: 10,
+        offset: 20,
+      };
+
+      const ast = builder.build(query);
+
+      expect(ast.limit).toBeDefined();
+      expect(ast.limit?.value).toBe(10);
+      expect(ast.offset).toBeDefined();
+      expect(ast.offset?.value).toBe(20);
+    });
+  });
+
+  describe('Advanced Query Building', () => {
+    it('should build query with JOIN', () => {
+      const query: QuerySchema = {
+        object: 'users',
+        fields: ['id', 'name', 'orders.total'],
+        joins: [
+          {
+            type: 'left',
+            object: 'orders',
+            on: {
+              local_field: 'id',
+              foreign_field: 'user_id',
+            },
+          },
+        ],
+      };
+
+      const ast = builder.build(query);
+
+      expect(ast.joins).toBeDefined();
+      expect(ast.joins).toHaveLength(1);
+      expect(ast.joins?.[0].join_type).toBe('left');
+      expect(ast.joins?.[0].table).toBe('orders');
+    });
+
+    it('should build query with aggregations', () => {
+      const query: QuerySchema = {
+        object: 'orders',
+        aggregations: [
+          {
+            function: 'count',
+            alias: 'total_count',
+          },
+          {
+            function: 'sum',
+            field: 'amount',
+            alias: 'total_amount',
+          },
+        ],
+      };
+
+      const ast = builder.build(query);
+
+      expect(ast.select.fields).toHaveLength(2);
+      expect(ast.select.fields[0]).toMatchObject({
+        type: 'aggregate',
+        function: 'count',
+        alias: 'total_count',
+      });
+    });
+
+    it('should build query with GROUP BY', () => {
+      const query: QuerySchema = {
+        object: 'orders',
+        fields: ['user_id'],
+        group_by: ['user_id'],
+        aggregations: [
+          {
+            function: 'count',
+            alias: 'order_count',
+          },
+        ],
+      };
+
+      const ast = builder.build(query);
+
+      expect(ast.group_by).toBeDefined();
+      expect(ast.group_by?.fields).toHaveLength(1);
+      expect(ast.group_by?.fields[0]).toMatchObject({
+        type: 'field',
+        name: 'user_id',
+      });
+    });
+  });
+
+  describe('Complex Filters', () => {
+    it('should build query with nested AND/OR filters', () => {
+      const query: QuerySchema = {
+        object: 'users',
+        filter: {
+          operator: 'and',
+          conditions: [
+            {
+              field: 'status',
+              operator: 'equals',
+              value: 'active',
+            },
+          ],
+          groups: [
+            {
+              operator: 'or',
+              conditions: [
+                {
+                  field: 'role',
+                  operator: 'equals',
+                  value: 'admin',
+                },
+                {
+                  field: 'role',
+                  operator: 'equals',
+                  value: 'moderator',
+                },
+              ],
+            },
+          ],
+        },
+      };
+
+      const ast = builder.build(query);
+
+      expect(ast.where).toBeDefined();
+      expect(ast.where?.condition.operator).toBe('and');
+      expect(ast.where?.condition.operands.length).toBeGreaterThan(0);
+    });
+  });
+});