@object-ui/core 0.3.1 → 2.0.0

package/src/evaluator/FormulaFunctions.ts

@@ -0,0 +1,398 @@
+/**
+ * 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 - Formula Functions
+ *
+ * Built-in formula functions for the expression engine.
+ * Provides aggregation, date, logic, and string functions
+ * compatible with low-code platform expression evaluation.
+ *
+ * @module evaluator
+ * @packageDocumentation
+ */
+
+/**
+ * A formula function that can be registered with the expression evaluator
+ */
+export type FormulaFunction = (...args: any[]) => any;
+
+/**
+ * Registry of built-in formula functions
+ */
+export class FormulaFunctions {
+  private functions = new Map<string, FormulaFunction>();
+
+  constructor() {
+    this.registerDefaults();
+  }
+
+  /**
+   * Register a custom formula function
+   */
+  register(name: string, fn: FormulaFunction): void {
+    this.functions.set(name.toUpperCase(), fn);
+  }
+
+  /**
+   * Get a formula function by name
+   */
+  get(name: string): FormulaFunction | undefined {
+    return this.functions.get(name.toUpperCase());
+  }
+
+  /**
+   * Check if a function is registered
+   */
+  has(name: string): boolean {
+    return this.functions.has(name.toUpperCase());
+  }
+
+  /**
+   * Get all registered function names
+   */
+  getNames(): string[] {
+    return Array.from(this.functions.keys());
+  }
+
+  /**
+   * Get all functions as a plain object (for injection into expression context)
+   */
+  toObject(): Record<string, FormulaFunction> {
+    const result: Record<string, FormulaFunction> = {};
+    for (const [name, fn] of this.functions) {
+      result[name] = fn;
+    }
+    return result;
+  }
+
+  /**
+   * Register all default built-in functions
+   */
+  private registerDefaults(): void {
+    this.registerAggregationFunctions();
+    this.registerDateFunctions();
+    this.registerLogicFunctions();
+    this.registerStringFunctions();
+    this.registerStringSearchFunctions();
+    this.registerStatisticalFunctions();
+  }
+
+  // ==========================================================================
+  // Aggregation Functions
+  // ==========================================================================
+
+  private registerAggregationFunctions(): void {
+    this.register('SUM', (...args: any[]): number => {
+      const values = flattenNumericArgs(args);
+      return values.reduce((sum, v) => sum + v, 0);
+    });
+
+    this.register('AVG', (...args: any[]): number => {
+      const values = flattenNumericArgs(args);
+      if (values.length === 0) return 0;
+      return values.reduce((sum, v) => sum + v, 0) / values.length;
+    });
+
+    this.register('COUNT', (...args: any[]): number => {
+      const values = flattenArgs(args);
+      return values.filter(v => v != null).length;
+    });
+
+    this.register('MIN', (...args: any[]): number => {
+      const values = flattenNumericArgs(args);
+      if (values.length === 0) return 0;
+      return Math.min(...values);
+    });
+
+    this.register('MAX', (...args: any[]): number => {
+      const values = flattenNumericArgs(args);
+      if (values.length === 0) return 0;
+      return Math.max(...values);
+    });
+  }
+
+  // ==========================================================================
+  // Date Functions
+  // ==========================================================================
+
+  private registerDateFunctions(): void {
+    this.register('TODAY', (): string => {
+      const now = new Date();
+      return now.toISOString().split('T')[0];
+    });
+
+    this.register('NOW', (): string => {
+      return new Date().toISOString();
+    });
+
+    this.register('DATEADD', (dateStr: string, amount: number, unit: string): string => {
+      const date = new Date(dateStr);
+      if (isNaN(date.getTime())) {
+        throw new Error(`DATEADD: Invalid date "${dateStr}"`);
+      }
+      const normalizedUnit = String(unit).toLowerCase();
+      switch (normalizedUnit) {
+        case 'day':
+        case 'days':
+          date.setDate(date.getDate() + amount);
+          break;
+        case 'month':
+        case 'months':
+          date.setMonth(date.getMonth() + amount);
+          break;
+        case 'year':
+        case 'years':
+          date.setFullYear(date.getFullYear() + amount);
+          break;
+        case 'hour':
+        case 'hours':
+          date.setHours(date.getHours() + amount);
+          break;
+        case 'minute':
+        case 'minutes':
+          date.setMinutes(date.getMinutes() + amount);
+          break;
+        default:
+          throw new Error(`DATEADD: Unsupported unit "${unit}"`);
+      }
+      return date.toISOString();
+    });
+
+    this.register('DATEDIFF', (dateStr1: string, dateStr2: string, unit: string): number => {
+      const date1 = new Date(dateStr1);
+      const date2 = new Date(dateStr2);
+      if (isNaN(date1.getTime())) {
+        throw new Error(`DATEDIFF: Invalid date "${dateStr1}"`);
+      }
+      if (isNaN(date2.getTime())) {
+        throw new Error(`DATEDIFF: Invalid date "${dateStr2}"`);
+      }
+      const diffMs = date2.getTime() - date1.getTime();
+      const normalizedUnit = String(unit).toLowerCase();
+      switch (normalizedUnit) {
+        case 'day':
+        case 'days':
+          return Math.floor(diffMs / (1000 * 60 * 60 * 24));
+        case 'month':
+        case 'months':
+          return (date2.getFullYear() - date1.getFullYear()) * 12 + (date2.getMonth() - date1.getMonth());
+        case 'year':
+        case 'years':
+          return date2.getFullYear() - date1.getFullYear();
+        case 'hour':
+        case 'hours':
+          return Math.floor(diffMs / (1000 * 60 * 60));
+        case 'minute':
+        case 'minutes':
+          return Math.floor(diffMs / (1000 * 60));
+        default:
+          throw new Error(`DATEDIFF: Unsupported unit "${unit}"`);
+      }
+    });
+
+    this.register('DATEFORMAT', (dateStr: string, format: string): string => {
+      const date = new Date(dateStr);
+      if (isNaN(date.getTime())) {
+        throw new Error(`DATEFORMAT: Invalid date "${dateStr}"`);
+      }
+      const pad = (n: number, len = 2) => String(n).padStart(len, '0');
+      return format
+        .replace('YYYY', String(date.getFullYear()))
+        .replace('YY', String(date.getFullYear()).slice(-2))
+        .replace('MM', pad(date.getMonth() + 1))
+        .replace('DD', pad(date.getDate()))
+        .replace('HH', pad(date.getHours()))
+        .replace('mm', pad(date.getMinutes()))
+        .replace('ss', pad(date.getSeconds()));
+    });
+  }
+
+  // ==========================================================================
+  // Logic Functions
+  // ==========================================================================
+
+  private registerLogicFunctions(): void {
+    this.register('IF', (condition: any, trueValue: any, falseValue: any): any => {
+      return condition ? trueValue : falseValue;
+    });
+
+    this.register('AND', (...args: any[]): boolean => {
+      return args.every(Boolean);
+    });
+
+    this.register('OR', (...args: any[]): boolean => {
+      return args.some(Boolean);
+    });
+
+    this.register('NOT', (value: any): boolean => {
+      return !value;
+    });
+
+    this.register('SWITCH', (expr: any, ...cases: any[]): any => {
+      // SWITCH(expr, val1, result1, val2, result2, ..., defaultResult)
+      for (let i = 0; i < cases.length - 1; i += 2) {
+        if (expr === cases[i]) {
+          return cases[i + 1];
+        }
+      }
+      // Return default value if odd number of case args
+      if (cases.length % 2 === 1) {
+        return cases[cases.length - 1];
+      }
+      return undefined;
+    });
+  }
+
+  // ==========================================================================
+  // String Functions
+  // ==========================================================================
+
+  private registerStringFunctions(): void {
+    this.register('CONCAT', (...args: any[]): string => {
+      return args.map(a => String(a ?? '')).join('');
+    });
+
+    this.register('LEFT', (text: string, count: number): string => {
+      return String(text ?? '').substring(0, count);
+    });
+
+    this.register('RIGHT', (text: string, count: number): string => {
+      const str = String(text ?? '');
+      return str.substring(Math.max(0, str.length - count));
+    });
+
+    this.register('TRIM', (text: string): string => {
+      return String(text ?? '').trim();
+    });
+
+    this.register('UPPER', (text: string): string => {
+      return String(text ?? '').toUpperCase();
+    });
+
+    this.register('LOWER', (text: string): string => {
+      return String(text ?? '').toLowerCase();
+    });
+  }
+
+  // ==========================================================================
+  // String Search Functions
+  // ==========================================================================
+
+  private registerStringSearchFunctions(): void {
+    this.register('FIND', (search: string, text: string, startPos?: number): number => {
+      const str = String(text ?? '');
+      const idx = str.indexOf(String(search ?? ''), startPos ?? 0);
+      return idx;
+    });
+
+    this.register('REPLACE', (text: string, search: string, replacement: string): string => {
+      const str = String(text ?? '');
+      return str.split(String(search ?? '')).join(String(replacement ?? ''));
+    });
+
+    this.register('SUBSTRING', (text: string, start: number, length?: number): string => {
+      const str = String(text ?? '');
+      if (length !== undefined) {
+        return str.substring(start, start + length);
+      }
+      return str.substring(start);
+    });
+
+    this.register('REGEX', (text: string, pattern: string, flags?: string): boolean => {
+      const str = String(text ?? '');
+      const regex = new RegExp(pattern, flags);
+      return regex.test(str);
+    });
+
+    this.register('LEN', (text: string): number => {
+      return String(text ?? '').length;
+    });
+  }
+
+  // ==========================================================================
+  // Statistical Functions
+  // ==========================================================================
+
+  private registerStatisticalFunctions(): void {
+    this.register('MEDIAN', (...args: any[]): number => {
+      const values = flattenNumericArgs(args).sort((a, b) => a - b);
+      if (values.length === 0) return 0;
+      const mid = Math.floor(values.length / 2);
+      return values.length % 2 !== 0
+        ? values[mid]
+        : (values[mid - 1] + values[mid]) / 2;
+    });
+
+    this.register('STDEV', (...args: any[]): number => {
+      const values = flattenNumericArgs(args);
+      if (values.length < 2) return 0;
+      const mean = values.reduce((sum, v) => sum + v, 0) / values.length;
+      const squaredDiffs = values.map(v => (v - mean) ** 2);
+      const variance = squaredDiffs.reduce((sum, v) => sum + v, 0) / (values.length - 1);
+      return Math.sqrt(variance);
+    });
+
+    this.register('VARIANCE', (...args: any[]): number => {
+      const values = flattenNumericArgs(args);
+      if (values.length < 2) return 0;
+      const mean = values.reduce((sum, v) => sum + v, 0) / values.length;
+      const squaredDiffs = values.map(v => (v - mean) ** 2);
+      return squaredDiffs.reduce((sum, v) => sum + v, 0) / (values.length - 1);
+    });
+
+    this.register('PERCENTILE', (percentile: number, ...args: any[]): number => {
+      const values = flattenNumericArgs(args).sort((a, b) => a - b);
+      if (values.length === 0) return 0;
+      const p = Math.max(0, Math.min(100, percentile)) / 100;
+      const index = p * (values.length - 1);
+      const lower = Math.floor(index);
+      const upper = Math.ceil(index);
+      if (lower === upper) return values[lower];
+      const fraction = index - lower;
+      return values[lower] + fraction * (values[upper] - values[lower]);
+    });
+  }
+}
+
+// ==========================================================================
+// Helpers
+// ==========================================================================
+
+/**
+ * Flatten nested arrays and extract numeric values
+ */
+function flattenNumericArgs(args: any[]): number[] {
+  const result: number[] = [];
+  for (const arg of args) {
+    if (Array.isArray(arg)) {
+      result.push(...flattenNumericArgs(arg));
+    } else {
+      const num = Number(arg);
+      if (!isNaN(num)) {
+        result.push(num);
+      }
+    }
+  }
+  return result;
+}
+
+/**
+ * Flatten nested arrays
+ */
+function flattenArgs(args: any[]): any[] {
+  const result: any[] = [];
+  for (const arg of args) {
+    if (Array.isArray(arg)) {
+      result.push(...flattenArgs(arg));
+    } else {
+      result.push(arg);
+    }
+  }
+  return result;
+}

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__/ExpressionContext.test.ts

@@ -0,0 +1,110 @@
+import { describe, it, expect } from 'vitest';
+import { ExpressionContext } from '../../evaluator/ExpressionContext';
+
+describe('ExpressionContext', () => {
+  it('creates a context with initial data', () => {
+    const ctx = new ExpressionContext({ name: 'Alice', age: 30 });
+    expect(ctx.get('name')).toBe('Alice');
+    expect(ctx.get('age')).toBe(30);
+  });
+
+  it('creates an empty context', () => {
+    const ctx = new ExpressionContext();
+    expect(ctx.get('anything')).toBeUndefined();
+  });
+
+  it('sets and gets values', () => {
+    const ctx = new ExpressionContext();
+    ctx.set('key', 'value');
+    expect(ctx.get('key')).toBe('value');
+  });
+
+  it('checks existence with has()', () => {
+    const ctx = new ExpressionContext({ x: 1 });
+    expect(ctx.has('x')).toBe(true);
+    expect(ctx.has('y')).toBe(false);
+  });
+
+  it('supports dot notation for nested access', () => {
+    const ctx = new ExpressionContext({ user: { name: 'Bob', address: { city: 'NYC' } } });
+    expect(ctx.get('user.name')).toBe('Bob');
+    expect(ctx.get('user.address.city')).toBe('NYC');
+  });
+
+  it('returns undefined for non-existent nested paths', () => {
+    const ctx = new ExpressionContext({ user: { name: 'Bob' } });
+    expect(ctx.get('user.email')).toBeUndefined();
+    expect(ctx.get('user.address.city')).toBeUndefined();
+  });
+
+  describe('scope management', () => {
+    it('pushScope adds a new scope', () => {
+      const ctx = new ExpressionContext({ base: 'value' });
+      ctx.pushScope({ scoped: 'data' });
+      expect(ctx.get('scoped')).toBe('data');
+      expect(ctx.get('base')).toBe('value');
+    });
+
+    it('popScope removes the latest scope', () => {
+      const ctx = new ExpressionContext({ base: 'value' });
+      ctx.pushScope({ temp: 'data' });
+      expect(ctx.get('temp')).toBe('data');
+      ctx.popScope();
+      expect(ctx.get('temp')).toBeUndefined();
+      expect(ctx.get('base')).toBe('value');
+    });
+
+    it('inner scope shadows outer scope', () => {
+      const ctx = new ExpressionContext({ name: 'outer' });
+      ctx.pushScope({ name: 'inner' });
+      expect(ctx.get('name')).toBe('inner');
+      ctx.popScope();
+      expect(ctx.get('name')).toBe('outer');
+    });
+
+    it('supports multiple nested scopes', () => {
+      const ctx = new ExpressionContext({ level: 0 });
+      ctx.pushScope({ level: 1 });
+      ctx.pushScope({ level: 2 });
+      expect(ctx.get('level')).toBe(2);
+      ctx.popScope();
+      expect(ctx.get('level')).toBe(1);
+      ctx.popScope();
+      expect(ctx.get('level')).toBe(0);
+    });
+  });
+
+  describe('toObject', () => {
+    it('flattens all scopes into one object', () => {
+      const ctx = new ExpressionContext({ a: 1 });
+      ctx.pushScope({ b: 2 });
+      const obj = ctx.toObject();
+      expect(obj.a).toBe(1);
+      expect(obj.b).toBe(2);
+    });
+
+    it('inner scope values take precedence in flattened object', () => {
+      const ctx = new ExpressionContext({ x: 'outer' });
+      ctx.pushScope({ x: 'inner' });
+      const obj = ctx.toObject();
+      expect(obj.x).toBe('inner');
+    });
+  });
+
+  describe('createChild', () => {
+    it('creates a child context with additional data', () => {
+      const parent = new ExpressionContext({ parent: 'value' });
+      const child = parent.createChild({ child: 'data' });
+      expect(child.get('parent')).toBe('value');
+      expect(child.get('child')).toBe('data');
+    });
+
+    it('child modifications do not affect parent', () => {
+      const parent = new ExpressionContext({ shared: 'original' });
+      const child = parent.createChild({});
+      child.set('shared', 'modified');
+      expect(child.get('shared')).toBe('modified');
+      expect(parent.get('shared')).toBe('original');
+    });
+  });
+});