@object-ui/core 0.5.0 → 3.0.0

package/src/utils/__tests__/debug.test.ts

@@ -0,0 +1,83 @@
+/**
+ * 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, beforeEach, afterEach } from 'vitest';
+import { debugLog, debugTime, debugTimeEnd } from '../debug';
+
+describe('Debug Utilities', () => {
+  let consoleSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    consoleSpy.mockRestore();
+    (globalThis as any).OBJECTUI_DEBUG = undefined;
+  });
+
+  describe('debugLog', () => {
+    it('should not log when debug is disabled', () => {
+      (globalThis as any).OBJECTUI_DEBUG = false;
+      debugLog('schema', 'test message');
+      expect(consoleSpy).not.toHaveBeenCalled();
+    });
+
+    it('should log when OBJECTUI_DEBUG is true', () => {
+      (globalThis as any).OBJECTUI_DEBUG = true;
+      debugLog('schema', 'Resolving component');
+      expect(consoleSpy).toHaveBeenCalledWith('[ObjectUI Debug][schema] Resolving component');
+    });
+
+    it('should log with data when provided', () => {
+      (globalThis as any).OBJECTUI_DEBUG = true;
+      debugLog('registry', 'Registered', { type: 'Button' });
+      expect(consoleSpy).toHaveBeenCalledWith(
+        '[ObjectUI Debug][registry] Registered',
+        { type: 'Button' }
+      );
+    });
+
+    it('should not log when debug is undefined', () => {
+      debugLog('action', 'test');
+      expect(consoleSpy).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('debugTime / debugTimeEnd', () => {
+    it('should not log timing when debug is disabled', () => {
+      (globalThis as any).OBJECTUI_DEBUG = false;
+      debugTime('test-timer');
+      debugTimeEnd('test-timer');
+      expect(consoleSpy).not.toHaveBeenCalled();
+    });
+
+    it('should measure and log elapsed time when debug is enabled', () => {
+      (globalThis as any).OBJECTUI_DEBUG = true;
+      debugTime('render-test');
+
+      // Simulate some delay via a busy loop
+      const start = performance.now();
+      while (performance.now() - start < 5) {
+        // wait ~5ms
+      }
+
+      debugTimeEnd('render-test');
+      expect(consoleSpy).toHaveBeenCalledTimes(1);
+      expect(consoleSpy).toHaveBeenCalledWith(
+        expect.stringMatching(/^\[ObjectUI Debug\]\[perf\] render-test: \d+\.\d{2}ms$/)
+      );
+    });
+
+    it('should not log if debugTimeEnd is called without debugTime', () => {
+      (globalThis as any).OBJECTUI_DEBUG = true;
+      debugTimeEnd('nonexistent');
+      expect(consoleSpy).not.toHaveBeenCalled();
+    });
+  });
+});

package/src/utils/debug.ts

@@ -0,0 +1,66 @@
+/**
+ * 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.
+ */
+
+type DebugCategory = 'schema' | 'registry' | 'expression' | 'action' | 'plugin' | 'render';
+
+function isDebugEnabled(): boolean {
+  try {
+    const g = typeof globalThis !== 'undefined' && (globalThis as any).OBJECTUI_DEBUG;
+    return (
+      (g === true || g === 'true') ||
+      (typeof process !== 'undefined' && process.env?.OBJECTUI_DEBUG === 'true')
+    );
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Log a debug message when OBJECTUI_DEBUG is enabled.
+ * No-op in production or when debug mode is off.
+ *
+ * @example
+ * ```ts
+ * // Enable debug mode
+ * globalThis.OBJECTUI_DEBUG = true;
+ *
+ * debugLog('schema', 'Resolving component', { type: 'Button' });
+ * // [ObjectUI Debug][schema] Resolving component { type: 'Button' }
+ * ```
+ */
+export function debugLog(category: DebugCategory, message: string, data?: unknown): void {
+  if (!isDebugEnabled()) return;
+  if (data !== undefined) {
+    console.log(`[ObjectUI Debug][${category}] ${message}`, data);
+  } else {
+    console.log(`[ObjectUI Debug][${category}] ${message}`);
+  }
+}
+
+const timers = new Map<string, number>();
+
+/**
+ * Start a debug timer. Pair with {@link debugTimeEnd}.
+ */
+export function debugTime(label: string): void {
+  if (!isDebugEnabled()) return;
+  timers.set(label, performance.now());
+}
+
+/**
+ * End a debug timer and log the elapsed time.
+ */
+export function debugTimeEnd(label: string): void {
+  if (!isDebugEnabled()) return;
+  const start = timers.get(label);
+  if (start !== undefined) {
+    const elapsed = (performance.now() - start).toFixed(2);
+    console.log(`[ObjectUI Debug][perf] ${label}: ${elapsed}ms`);
+    timers.delete(label);
+  }
+}

package/src/validation/__tests__/object-validation-engine.test.ts

@@ -9,7 +9,7 @@
 /**
  * @object-ui/core - Object Validation Engine Tests
  * 
- * Tests for ObjectStack Spec v0.7.1 object-level validation
+ * Tests for ObjectStack Spec v2.0.1 object-level validation
  */
 
 import { describe, it, expect, vi } from 'vitest';

package/src/validation/__tests__/schema-validator.test.ts

@@ -0,0 +1,118 @@
+import { describe, it, expect } from 'vitest';
+import {
+  validateSchema,
+  assertValidSchema,
+  isValidSchema,
+  formatValidationErrors,
+} from '../../validation/schema-validator';
+
+describe('schema-validator', () => {
+  describe('validateSchema', () => {
+    it('validates a minimal valid schema', () => {
+      const result = validateSchema({ type: 'form' });
+      expect(result.valid).toBe(true);
+      expect(result.errors).toHaveLength(0);
+    });
+
+    it('rejects schema without type', () => {
+      const result = validateSchema({} as any);
+      expect(result.valid).toBe(false);
+      expect(result.errors.length).toBeGreaterThan(0);
+    });
+
+    it('validates CRUD schema with columns', () => {
+      const result = validateSchema({
+        type: 'crud',
+        columns: [{ name: 'id', label: 'ID' }],
+        api: '/api/users',
+      });
+      expect(result.valid).toBe(true);
+    });
+
+    it('warns about CRUD without columns', () => {
+      const result = validateSchema({ type: 'crud' });
+      const hasColumnsIssue = [...result.errors, ...result.warnings].some(
+        (e) => e.message.toLowerCase().includes('column'),
+      );
+      expect(hasColumnsIssue).toBe(true);
+    });
+
+    it('validates form with fields', () => {
+      const result = validateSchema({
+        type: 'form',
+        fields: [
+          { name: 'email', label: 'Email', type: 'string' },
+        ],
+      });
+      expect(result.valid).toBe(true);
+    });
+
+    it('detects duplicate field names in forms', () => {
+      const result = validateSchema({
+        type: 'form',
+        fields: [
+          { name: 'email', label: 'Email', type: 'string' },
+          { name: 'email', label: 'Email 2', type: 'string' },
+        ],
+      });
+      const hasDuplicateWarning = [...result.errors, ...result.warnings].some(
+        (e) => e.message.toLowerCase().includes('duplicate'),
+      );
+      expect(hasDuplicateWarning).toBe(true);
+    });
+
+    it('validates nested children', () => {
+      const result = validateSchema({
+        type: 'grid',
+        children: [
+          { type: 'button', label: 'OK' },
+        ],
+      });
+      expect(result.valid).toBe(true);
+    });
+  });
+
+  describe('isValidSchema', () => {
+    it('returns true for valid schema', () => {
+      expect(isValidSchema({ type: 'form' })).toBe(true);
+    });
+
+    it('returns false for invalid schema', () => {
+      expect(isValidSchema({})).toBe(false);
+    });
+
+    it('returns false for empty object', () => {
+      expect(isValidSchema({} as any)).toBe(false);
+    });
+
+    it('returns false for non-object values', () => {
+      expect(isValidSchema('string' as any)).toBe(false);
+      expect(isValidSchema(42 as any)).toBe(false);
+    });
+  });
+
+  describe('assertValidSchema', () => {
+    it('does not throw for valid schema', () => {
+      expect(() => assertValidSchema({ type: 'form' })).not.toThrow();
+    });
+
+    it('throws for invalid schema', () => {
+      expect(() => assertValidSchema({} as any)).toThrow();
+    });
+  });
+
+  describe('formatValidationErrors', () => {
+    it('formats validation errors', () => {
+      const result = validateSchema({} as any);
+      const formatted = formatValidationErrors(result);
+      expect(typeof formatted).toBe('string');
+      expect(formatted.length).toBeGreaterThan(0);
+    });
+
+    it('returns empty string for valid schemas', () => {
+      const result = validateSchema({ type: 'form' });
+      const formatted = formatValidationErrors(result);
+      expect(formatted).toBe('');
+    });
+  });
+});

package/src/validation/index.ts

@@ -2,7 +2,7 @@
  * @object-ui/core - Validation Module
  * 
  * Phase 3.5: Validation engine
- * ObjectStack Spec v0.7.1: Object-level validation
+ * ObjectStack Spec v2.0.1: Object-level validation
  */
 
 export * from './validation-engine.js';

package/src/validation/validation-engine.ts

@@ -34,6 +34,39 @@ import type {
  * Validation Engine - Executes validation rules
  */
 export class ValidationEngine {
+  private customValidators = new Map<string, ValidationFunction>();
+  private customAsyncValidators = new Map<string, AsyncValidationFunction>();
+
+  /**
+   * Register a custom synchronous validator by name
+   */
+  registerValidator(name: string, fn: ValidationFunction): void {
+    this.customValidators.set(name, fn);
+  }
+
+  /**
+   * Register a custom asynchronous validator by name
+   */
+  registerAsyncValidator(name: string, fn: AsyncValidationFunction): void {
+    this.customAsyncValidators.set(name, fn);
+  }
+
+  /**
+   * Check if a custom validator is registered
+   */
+  hasValidator(name: string): boolean {
+    return this.customValidators.has(name) || this.customAsyncValidators.has(name);
+  }
+
+  /**
+   * Get all registered custom validator names
+   */
+  getValidatorNames(): string[] {
+    return [
+      ...Array.from(this.customValidators.keys()),
+      ...Array.from(this.customAsyncValidators.keys()),
+    ];
+  }
   /**
    * Validate a value against validation schema
    */
@@ -80,7 +113,7 @@ export class ValidationEngine {
     rule: AdvancedValidationRule,
     context?: ValidationContext
   ): Promise<string | null> {
-    // Custom async validator
+    // Custom async validator (inline)
     if (rule.async_validator) {
       const result = await rule.async_validator(value, context);
       if (result === false) {
@@ -92,7 +125,7 @@ export class ValidationEngine {
       return null;
     }
 
-    // Custom sync validator
+    // Custom sync validator (inline)
     if (rule.validator) {
       const result = rule.validator(value, context);
       if (result === false) {
@@ -104,6 +137,32 @@ export class ValidationEngine {
       return null;
     }
 
+    // Registered custom async validator (by name)
+    const registeredAsync = this.customAsyncValidators.get(rule.type);
+    if (registeredAsync) {
+      const result = await registeredAsync(value, context);
+      if (result === false) {
+        return rule.message || 'Async validation failed';
+      }
+      if (typeof result === 'string') {
+        return result;
+      }
+      return null;
+    }
+
+    // Registered custom sync validator (by name)
+    const registeredSync = this.customValidators.get(rule.type);
+    if (registeredSync) {
+      const result = registeredSync(value, context);
+      if (result === false) {
+        return rule.message || 'Validation failed';
+      }
+      if (typeof result === 'string') {
+        return result;
+      }
+      return null;
+    }
+
     // Built-in validators
     return this.validateBuiltInRule(value, rule, context);
   }
@@ -342,7 +401,15 @@ export class ValidationEngine {
    */
   private evaluateCondition(condition: any, values: Record<string, any>): boolean {
     if (typeof condition === 'function') {
-      console.warn('Function-based conditions are deprecated and will be removed. Use declarative conditions instead.');
+      console.warn(
+        'Function-based conditions are deprecated and will be removed. Use declarative conditions instead.\n\n' +
+        '  Migration:\n' +
+        '  // Before (deprecated):\n' +
+        '  { condition: (values) => values.age > 18 }\n\n' +
+        '  // After:\n' +
+        '  { condition: { field: "age", operator: ">", value: 18 } }\n\n' +
+        '  See: https://github.com/objectstack-ai/objectui/blob/main/MIGRATION_GUIDE.md'
+      );
       return false; // Security: reject function-based conditions
     }
     

package/src/validation/validators/index.ts

@@ -9,7 +9,7 @@
 /**
  * @object-ui/core - Validators
  * 
- * ObjectStack Spec v0.7.1 compliant validators
+ * ObjectStack Spec v2.0.1 compliant validators
  * 
  * @module validators
  * @packageDocumentation

package/src/validation/validators/object-validation-engine.ts

@@ -9,7 +9,7 @@
 /**
  * @object-ui/core - Object-Level Validation Engine
  * 
- * ObjectStack Spec v0.7.1 compliant validation engine for object-level validation rules.
+ * ObjectStack Spec v2.0.1 compliant validation engine for object-level validation rules.
  * Supports all 9 validation types from the specification:
  * - ScriptValidation
  * - UniquenessValidation
@@ -256,7 +256,7 @@ class SimpleExpressionEvaluator implements ValidationExpressionEvaluator {
 
 /**
  * Object-Level Validation Engine
- * Implements ObjectStack Spec v0.7.1 validation framework
+ * Implements ObjectStack Spec v2.0.1 validation framework
  */
 export class ObjectValidationEngine {
   private expressionEvaluator: ValidationExpressionEvaluator;