@object-ui/core 0.3.0 → 0.3.1

package/src/evaluator/ExpressionEvaluator.ts

@@ -0,0 +1,248 @@
+/**
+ * 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';
+
+/**
+ * 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;
+
+  constructor(context?: ExpressionContext | Record<string, any>) {
+    if (context instanceof ExpressionContext) {
+      this.context = context;
+    } else {
+      this.context = new ExpressionContext(context || {});
+    }
+  }
+
+  /**
+   * 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);
+      
+      // 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});`);
+      
+      // Execute with context values
+      return 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 {
+    return new ExpressionEvaluator(this.context.createChild(data));
+  }
+}
+
+/**
+ * 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);
+  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);
+  return evaluator.evaluateCondition(condition);
+}

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,10 @@
+/**
+ * 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';
+export * from './ExpressionEvaluator';

package/src/index.d.ts

@@ -1,4 +1,13 @@
+/**
+ * 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 './types';
 export * from './registry/Registry';
 export * from './validation/schema-validator';
 export * from './builder/schema-builder';
+export * from './adapters';
+export * from './utils/filter-converter';

package/src/index.js

@@ -1,7 +1,16 @@
+/**
+ * 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 './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 * from './data-scope'; // TODO
-// export * from './evaluator'; // TODO
 // export * from './validators'; // TODO

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,18 @@
+/**
+ * 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 './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 * from './data-scope'; // TODO
-// export * from './evaluator'; // TODO
 // export * from './validators'; // TODO
 

package/src/registry/Registry.d.ts

@@ -1,3 +1,10 @@
+/**
+ * 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 type { SchemaNode } from '../types';
 export type ComponentRenderer<T = any> = T;
 export type ComponentInput = {

package/src/registry/Registry.js

@@ -1,3 +1,10 @@
+/**
+ * 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 class Registry {
     constructor() {
         Object.defineProperty(this, "components", {

package/src/registry/Registry.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 type { SchemaNode } from '../types';
 
 export type ComponentRenderer<T = any> = T;

package/src/types/index.d.ts

@@ -1,3 +1,10 @@
+/**
+ * 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 interface SchemaNode {
     type: string;
     id?: string;

package/src/types/index.js

@@ -1 +1,8 @@
+/**
+ * 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 {};

package/src/types/index.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.
+ */
+
 export interface SchemaNode {
   type: string;
   id?: string;

package/src/utils/__tests__/filter-converter.test.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.
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+import { convertFiltersToAST, convertOperatorToAST, type FilterNode } from '../filter-converter';
+
+describe('Filter Converter Utilities', () => {
+  describe('convertOperatorToAST', () => {
+    it('should convert known operators', () => {
+      expect(convertOperatorToAST('$eq')).toBe('=');
+      expect(convertOperatorToAST('$ne')).toBe('!=');
+      expect(convertOperatorToAST('$gt')).toBe('>');
+      expect(convertOperatorToAST('$gte')).toBe('>=');
+      expect(convertOperatorToAST('$lt')).toBe('<');
+      expect(convertOperatorToAST('$lte')).toBe('<=');
+      expect(convertOperatorToAST('$in')).toBe('in');
+      expect(convertOperatorToAST('$nin')).toBe('notin');
+      expect(convertOperatorToAST('$notin')).toBe('notin');
+      expect(convertOperatorToAST('$contains')).toBe('contains');
+      expect(convertOperatorToAST('$startswith')).toBe('startswith');
+      expect(convertOperatorToAST('$between')).toBe('between');
+    });
+
+    it('should return null for unknown operators', () => {
+      expect(convertOperatorToAST('$unknown')).toBe(null);
+      expect(convertOperatorToAST('$exists')).toBe(null);
+    });
+  });
+
+  describe('convertFiltersToAST', () => {
+    it('should convert simple equality filter', () => {
+      const result = convertFiltersToAST({ status: 'active' });
+      expect(result).toEqual(['status', '=', 'active']);
+    });
+
+    it('should convert single operator filter', () => {
+      const result = convertFiltersToAST({ age: { $gte: 18 } });
+      expect(result).toEqual(['age', '>=', 18]);
+    });
+
+    it('should convert multiple operators on same field', () => {
+      const result = convertFiltersToAST({ age: { $gte: 18, $lte: 65 } }) as FilterNode;
+      expect(result[0]).toBe('and');
+      expect(result.slice(1)).toContainEqual(['age', '>=', 18]);
+      expect(result.slice(1)).toContainEqual(['age', '<=', 65]);
+    });
+
+    it('should convert multiple fields with and logic', () => {
+      const result = convertFiltersToAST({
+        age: { $gte: 18 },
+        status: 'active'
+      }) as FilterNode;
+      expect(result[0]).toBe('and');
+      expect(result.slice(1)).toContainEqual(['age', '>=', 18]);
+      expect(result.slice(1)).toContainEqual(['status', '=', 'active']);
+    });
+
+    it('should handle $in operator', () => {
+      const result = convertFiltersToAST({
+        status: { $in: ['active', 'pending'] }
+      });
+      expect(result).toEqual(['status', 'in', ['active', 'pending']]);
+    });
+
+    it('should handle $nin operator', () => {
+      const result = convertFiltersToAST({
+        status: { $nin: ['archived'] }
+      });
+      expect(result).toEqual(['status', 'notin', ['archived']]);
+    });
+
+    it('should warn on $regex operator and convert to contains', () => {
+      const consoleSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+      
+      const result = convertFiltersToAST({
+        name: { $regex: '^John' }
+      });
+      
+      expect(result).toEqual(['name', 'contains', '^John']);
+      expect(consoleSpy).toHaveBeenCalledWith(
+        expect.stringContaining('[ObjectUI] Warning: $regex operator is not fully supported')
+      );
+      
+      consoleSpy.mockRestore();
+    });
+
+    it('should throw error on unknown operator', () => {
+      expect(() => {
+        convertFiltersToAST({ age: { $unknown: 18 } });
+      }).toThrow('[ObjectUI] Unknown filter operator');
+    });
+
+    it('should skip null and undefined values', () => {
+      const result = convertFiltersToAST({
+        name: 'John',
+        age: null,
+        email: undefined
+      });
+      expect(result).toEqual(['name', '=', 'John']);
+    });
+
+    it('should return original filter if empty after filtering', () => {
+      const result = convertFiltersToAST({
+        age: null,
+        email: undefined
+      });
+      expect(result).toEqual({
+        age: null,
+        email: undefined
+      });
+    });
+  });
+});

package/src/utils/filter-converter.d.ts

@@ -0,0 +1,57 @@
+/**
+ * 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.
+ */
+/**
+ * Filter Converter Utilities
+ *
+ * Shared utilities for converting MongoDB-like filter operators
+ * to ObjectStack FilterNode AST format.
+ */
+/**
+ * FilterNode AST type definition
+ * Represents a filter condition or a logical combination of conditions
+ *
+ * @example
+ * // Simple condition
+ * ['status', '=', 'active']
+ *
+ * // Logical combination
+ * ['and', ['age', '>=', 18], ['status', '=', 'active']]
+ */
+export type FilterNode = [string, string, any] | [string, ...FilterNode[]];
+/**
+ * Map MongoDB-like operators to ObjectStack filter operators.
+ *
+ * @param operator - MongoDB-style operator (e.g., '$gte', '$in')
+ * @returns ObjectStack operator or null if not recognized
+ */
+export declare function convertOperatorToAST(operator: string): string | null;
+/**
+ * Convert object-based filters to ObjectStack FilterNode AST format.
+ * Converts MongoDB-like operators to ObjectStack filter expressions.
+ *
+ * @param filter - Object-based filter with optional operators
+ * @returns FilterNode AST array
+ *
+ * @example
+ * // Simple filter - converted to AST
+ * convertFiltersToAST({ status: 'active' })
+ * // => ['status', '=', 'active']
+ *
+ * @example
+ * // Complex filter with operators
+ * convertFiltersToAST({ age: { $gte: 18 } })
+ * // => ['age', '>=', 18]
+ *
+ * @example
+ * // Multiple conditions
+ * convertFiltersToAST({ age: { $gte: 18, $lte: 65 }, status: 'active' })
+ * // => ['and', ['age', '>=', 18], ['age', '<=', 65], ['status', '=', 'active']]
+ *
+ * @throws {Error} If an unknown operator is encountered
+ */
+export declare function convertFiltersToAST(filter: Record<string, any>): FilterNode | Record<string, any>;