@object-ui/core 0.3.0 → 0.5.0

package/src/evaluator/ExpressionContext.ts

@@ -0,0 +1,118 @@
+/**
+ * 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

@@ -0,0 +1,267 @@
+/**
+ * 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';
+
+/**
+ * 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;
+
+  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();
+  }
+
+  /**
+   * 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();
+      
+      // Build safe function with context variables
+      const varNames = Object.keys(contextObj);
+      const varValues = Object.values(contextObj);
+      
+      // 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 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
+ */
+export function evaluateExpression(
+  expression: string | boolean | number | null | undefined,
+  context: Record<string, any> = {},
+  options: EvaluationOptions = {}
+): any {
+  const evaluator = new ExpressionEvaluator(context, globalCache);
+  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);
+  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/__tests__/ExpressionEvaluator.test.ts

@@ -0,0 +1,101 @@
+/**
+ * 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 } from 'vitest';
+import { ExpressionEvaluator, evaluateExpression, evaluateCondition } from '../ExpressionEvaluator';
+import { ExpressionContext } from '../ExpressionContext';
+
+describe('ExpressionContext', () => {
+  it('should create context with initial data', () => {
+    const ctx = new ExpressionContext({ name: 'John', age: 30 });
+    expect(ctx.get('name')).toBe('John');
+    expect(ctx.get('age')).toBe(30);
+  });
+
+  it('should support nested property access', () => {
+    const ctx = new ExpressionContext({
+      user: {
+        name: 'John',
+        profile: {
+          email: 'john@example.com'
+        }
+      }
+    });
+    
+    expect(ctx.get('user.name')).toBe('John');
+    expect(ctx.get('user.profile.email')).toBe('john@example.com');
+  });
+
+  it('should support scope stacking', () => {
+    const ctx = new ExpressionContext({ x: 10 });
+    expect(ctx.get('x')).toBe(10);
+    
+    ctx.pushScope({ x: 20, y: 30 });
+    expect(ctx.get('x')).toBe(20);
+    expect(ctx.get('y')).toBe(30);
+    
+    ctx.popScope();
+    expect(ctx.get('x')).toBe(10);
+    expect(ctx.get('y')).toBeUndefined();
+  });
+});
+
+describe('ExpressionEvaluator', () => {
+  describe('evaluate', () => {
+    it('should evaluate simple template expressions', () => {
+      const evaluator = new ExpressionEvaluator({ name: 'John' });
+      expect(evaluator.evaluate('Hello ${name}!')).toBe('Hello John!');
+    });
+
+    it('should evaluate nested property access', () => {
+      const evaluator = new ExpressionEvaluator({
+        data: { amount: 1500 }
+      });
+      expect(evaluator.evaluate('Amount: ${data.amount}')).toBe('Amount: 1500');
+    });
+
+    it('should handle non-string values', () => {
+      const evaluator = new ExpressionEvaluator({});
+      expect(evaluator.evaluate(true)).toBe(true);
+      expect(evaluator.evaluate(42)).toBe(42);
+      expect(evaluator.evaluate(null)).toBe(null);
+    });
+  });
+
+  describe('evaluateExpression', () => {
+    it('should evaluate comparison operators', () => {
+      const evaluator = new ExpressionEvaluator({ data: { amount: 1500 } });
+      
+      expect(evaluator.evaluateExpression('data.amount > 1000')).toBe(true);
+      expect(evaluator.evaluateExpression('data.amount < 1000')).toBe(false);
+    });
+
+    it('should block dangerous expressions', () => {
+      const evaluator = new ExpressionEvaluator({});
+      
+      expect(() => evaluator.evaluateExpression('eval("malicious")')).toThrow();
+      expect(() => evaluator.evaluateExpression('process.exit()')).toThrow();
+    });
+  });
+
+  describe('evaluateCondition', () => {
+    it('should return boolean for condition expressions', () => {
+      const evaluator = new ExpressionEvaluator({ data: { age: 25 } });
+      
+      expect(evaluator.evaluateCondition('${data.age >= 18}')).toBe(true);
+      expect(evaluator.evaluateCondition('${data.age < 18}')).toBe(false);
+    });
+
+    it('should handle boolean values directly', () => {
+      const evaluator = new ExpressionEvaluator({});
+      
+      expect(evaluator.evaluateCondition(true)).toBe(true);
+      expect(evaluator.evaluateCondition(false)).toBe(false);
+    });
+  });
+});

package/src/evaluator/index.ts

@@ -0,0 +1,11 @@
+/**
+ * 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.
+ */
+
+export * from './ExpressionContext.js';
+export * from './ExpressionEvaluator.js';
+export * from './ExpressionCache.js';

package/src/index.test.ts

@@ -1,3 +1,11 @@
+/**
+ * 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 } from 'vitest';
 
 describe('core', () => {

package/src/index.ts

@@ -1,8 +1,21 @@
-export * from './types';
-export * from './registry/Registry';
-export * from './validation/schema-validator';
-export * from './builder/schema-builder';
+/**
+ * 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.
+ */
+
+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 './evaluator'; // TODO
 // export * from './validators'; // TODO