@object-ui/core 0.5.0 → 3.0.0

package/src/data-scope/index.ts

@@ -0,0 +1,16 @@
+/**
+ * @object-ui/core - DataScope Module
+ *
+ * Runtime data scope management for row-level security and
+ * reactive data state within the UI component tree.
+ *
+ * @module data-scope
+ * @packageDocumentation
+ */
+
+export {
+  DataScopeManager,
+  defaultDataScopeManager,
+  type RowLevelFilter,
+  type DataScopeConfig,
+} from './DataScopeManager.js';

package/src/errors/__tests__/errors.test.ts

@@ -0,0 +1,292 @@
+/**
+ * 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 {
+  ObjectUIError,
+  SchemaError,
+  RegistryError,
+  ExpressionError,
+  PluginError,
+  FieldValidationError,
+  ERROR_CODES,
+  createError,
+  formatErrorMessage,
+  isObjectUIError,
+  isErrorCode,
+} from '../index';
+
+// ---------------------------------------------------------------------------
+// ObjectUIError base class
+// ---------------------------------------------------------------------------
+
+describe('ObjectUIError', () => {
+  it('should create an error with code and message', () => {
+    const err = new ObjectUIError('something broke', 'OBJUI-001');
+
+    expect(err).toBeInstanceOf(Error);
+    expect(err).toBeInstanceOf(ObjectUIError);
+    expect(err.name).toBe('ObjectUIError');
+    expect(err.message).toBe('something broke');
+    expect(err.code).toBe('OBJUI-001');
+    expect(err.details).toBeUndefined();
+  });
+
+  it('should accept optional details', () => {
+    const details = { type: 'fancy-button' };
+    const err = new ObjectUIError('oops', 'OBJUI-001', details);
+
+    expect(err.details).toEqual(details);
+  });
+
+  it('should serialize to JSON', () => {
+    const err = new ObjectUIError('oops', 'OBJUI-001', { a: 1 });
+    const json = err.toJSON();
+
+    expect(json).toEqual(
+      expect.objectContaining({
+        name: 'ObjectUIError',
+        message: 'oops',
+        code: 'OBJUI-001',
+        details: { a: 1 },
+      }),
+    );
+    expect(json.stack).toBeDefined();
+  });
+
+  it('should have a proper stack trace', () => {
+    const err = new ObjectUIError('trace me', 'OBJUI-001');
+    expect(err.stack).toBeDefined();
+    expect(err.stack).toContain('trace me');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// ERROR_CODES registry
+// ---------------------------------------------------------------------------
+
+describe('ERROR_CODES', () => {
+  it('should contain all 10 defined error codes', () => {
+    const expectedCodes = [
+      'OBJUI-001',
+      'OBJUI-002',
+      'OBJUI-003',
+      'OBJUI-004',
+      'OBJUI-005',
+      'OBJUI-006',
+      'OBJUI-007',
+      'OBJUI-008',
+      'OBJUI-009',
+      'OBJUI-010',
+    ];
+
+    for (const code of expectedCodes) {
+      expect(ERROR_CODES[code]).toBeDefined();
+      expect(ERROR_CODES[code].code).toBe(code);
+      expect(ERROR_CODES[code].message).toBeTruthy();
+      expect(ERROR_CODES[code].suggestion).toBeTruthy();
+      expect(ERROR_CODES[code].docUrl).toContain(code);
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// isErrorCode type guard
+// ---------------------------------------------------------------------------
+
+describe('isErrorCode', () => {
+  it('should return true for known codes', () => {
+    expect(isErrorCode('OBJUI-001')).toBe(true);
+    expect(isErrorCode('OBJUI-010')).toBe(true);
+  });
+
+  it('should return false for unknown codes', () => {
+    expect(isErrorCode('OBJUI-999')).toBe(false);
+    expect(isErrorCode(42)).toBe(false);
+    expect(isErrorCode(null)).toBe(false);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// isObjectUIError type guard
+// ---------------------------------------------------------------------------
+
+describe('isObjectUIError', () => {
+  it('should return true for ObjectUIError instances', () => {
+    expect(isObjectUIError(new ObjectUIError('a', 'OBJUI-001'))).toBe(true);
+  });
+
+  it('should return true for subclass instances', () => {
+    expect(isObjectUIError(new SchemaError('bad schema'))).toBe(true);
+    expect(isObjectUIError(new ExpressionError('bad expr'))).toBe(true);
+  });
+
+  it('should return false for plain errors', () => {
+    expect(isObjectUIError(new Error('plain'))).toBe(false);
+    expect(isObjectUIError('string')).toBe(false);
+    expect(isObjectUIError(null)).toBe(false);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Specialized error classes
+// ---------------------------------------------------------------------------
+
+describe('SchemaError', () => {
+  it('should default to OBJUI-002', () => {
+    const err = new SchemaError('bad schema');
+    expect(err.name).toBe('SchemaError');
+    expect(err.code).toBe('OBJUI-002');
+    expect(err).toBeInstanceOf(ObjectUIError);
+  });
+});
+
+describe('RegistryError', () => {
+  it('should accept a custom code', () => {
+    const err = new RegistryError('not found', 'OBJUI-001');
+    expect(err.name).toBe('RegistryError');
+    expect(err.code).toBe('OBJUI-001');
+    expect(err).toBeInstanceOf(ObjectUIError);
+  });
+});
+
+describe('ExpressionError', () => {
+  it('should default to OBJUI-003', () => {
+    const err = new ExpressionError('eval failed');
+    expect(err.name).toBe('ExpressionError');
+    expect(err.code).toBe('OBJUI-003');
+  });
+});
+
+describe('PluginError', () => {
+  it('should accept a custom code', () => {
+    const err = new PluginError('missing dep', 'OBJUI-004');
+    expect(err.name).toBe('PluginError');
+    expect(err.code).toBe('OBJUI-004');
+  });
+});
+
+describe('FieldValidationError', () => {
+  it('should default to OBJUI-009', () => {
+    const err = new FieldValidationError('invalid field');
+    expect(err.name).toBe('FieldValidationError');
+    expect(err.code).toBe('OBJUI-009');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// createError factory
+// ---------------------------------------------------------------------------
+
+describe('createError', () => {
+  it('should create a RegistryError for OBJUI-001', () => {
+    const err = createError('OBJUI-001', { type: 'fancy-button' });
+    expect(err).toBeInstanceOf(RegistryError);
+    expect(err.message).toBe('Unknown component type: "fancy-button"');
+    expect(err.code).toBe('OBJUI-001');
+  });
+
+  it('should create a SchemaError for OBJUI-002', () => {
+    const err = createError('OBJUI-002', { reason: 'missing type' });
+    expect(err).toBeInstanceOf(SchemaError);
+    expect(err.message).toContain('missing type');
+  });
+
+  it('should create an ExpressionError for OBJUI-003', () => {
+    const err = createError('OBJUI-003', { expression: '${bad}' });
+    expect(err).toBeInstanceOf(ExpressionError);
+  });
+
+  it('should create a PluginError for OBJUI-004', () => {
+    const err = createError('OBJUI-004', { dependency: 'chart-lib' });
+    expect(err).toBeInstanceOf(PluginError);
+    expect(err.message).toContain('chart-lib');
+  });
+
+  it('should create a PluginError for OBJUI-005', () => {
+    const err = createError('OBJUI-005', { plugin: 'grid' });
+    expect(err).toBeInstanceOf(PluginError);
+  });
+
+  it('should create a PluginError for OBJUI-006', () => {
+    const err = createError('OBJUI-006', { plugin: 'kanban' });
+    expect(err).toBeInstanceOf(PluginError);
+  });
+
+  it('should create a RegistryError for OBJUI-007', () => {
+    const err = createError('OBJUI-007', { namespace: 'old-ns' });
+    expect(err).toBeInstanceOf(RegistryError);
+  });
+
+  it('should create a FieldValidationError for OBJUI-009', () => {
+    const err = createError('OBJUI-009', { field: 'email' });
+    expect(err).toBeInstanceOf(FieldValidationError);
+  });
+
+  it('should create a base ObjectUIError for OBJUI-008', () => {
+    const err = createError('OBJUI-008', { scope: 'readOnlyScope' });
+    expect(err).toBeInstanceOf(ObjectUIError);
+    expect(err.message).toContain('readOnlyScope');
+  });
+
+  it('should create a base ObjectUIError for OBJUI-010', () => {
+    const err = createError('OBJUI-010', { action: 'save' });
+    expect(err).toBeInstanceOf(ObjectUIError);
+    expect(err.message).toContain('save');
+  });
+
+  it('should handle unknown error codes gracefully', () => {
+    const err = createError('OBJUI-999');
+    expect(err).toBeInstanceOf(ObjectUIError);
+    expect(err.message).toContain('Unknown error code');
+  });
+
+  it('should pass through details', () => {
+    const err = createError('OBJUI-001', { type: 'x' }, { extra: true });
+    expect(err.details).toEqual({ extra: true });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// formatErrorMessage
+// ---------------------------------------------------------------------------
+
+describe('formatErrorMessage', () => {
+  it('should include code and message', () => {
+    const err = new ObjectUIError('something broke', 'OBJUI-001');
+    const formatted = formatErrorMessage(err, false);
+
+    expect(formatted).toBe('[OBJUI-001] something broke');
+  });
+
+  it('should include suggestion and docs in dev mode', () => {
+    const err = createError('OBJUI-001', { type: 'magic-box' });
+    const formatted = formatErrorMessage(err, true);
+
+    expect(formatted).toContain('[OBJUI-001]');
+    expect(formatted).toContain('💡 Suggestion:');
+    expect(formatted).toContain('📖 Docs:');
+    expect(formatted).toContain('https://objectui.dev/docs/errors/OBJUI-001');
+  });
+
+  it('should not include suggestion in production mode', () => {
+    const err = createError('OBJUI-002', { reason: 'bad' });
+    const formatted = formatErrorMessage(err, false);
+
+    expect(formatted).not.toContain('💡 Suggestion:');
+    expect(formatted).not.toContain('📖 Docs:');
+  });
+
+  it('should handle errors with unknown codes gracefully', () => {
+    const err = new ObjectUIError('custom', 'CUSTOM-001');
+    const formatted = formatErrorMessage(err, true);
+
+    // No entry in ERROR_CODES so no suggestion appended
+    expect(formatted).toBe('[CUSTOM-001] custom');
+  });
+});

package/src/errors/index.ts

@@ -0,0 +1,270 @@
+/**
+ * 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.
+ */
+
+// ---------------------------------------------------------------------------
+// Error Code Registry
+// ---------------------------------------------------------------------------
+
+export interface ErrorCodeEntry {
+  code: string;
+  message: string;
+  suggestion: string;
+  docUrl: string;
+}
+
+const BASE_DOC_URL = 'https://objectui.dev/docs/errors';
+
+export const ERROR_CODES: Record<string, ErrorCodeEntry> = {
+  'OBJUI-001': {
+    code: 'OBJUI-001',
+    message: 'Unknown component type: "${type}"',
+    suggestion:
+      'Ensure the component is registered via registry.register() before rendering. Check for typos in the component type name.',
+    docUrl: `${BASE_DOC_URL}/OBJUI-001`,
+  },
+  'OBJUI-002': {
+    code: 'OBJUI-002',
+    message: 'Schema validation failed: ${reason}',
+    suggestion:
+      'Verify the schema against the ObjectUI JSON spec. Run the built-in schema validator for details.',
+    docUrl: `${BASE_DOC_URL}/OBJUI-002`,
+  },
+  'OBJUI-003': {
+    code: 'OBJUI-003',
+    message: 'Expression evaluation failed: ${expression}',
+    suggestion:
+      'Check the expression syntax and ensure all referenced variables exist in the current data scope.',
+    docUrl: `${BASE_DOC_URL}/OBJUI-003`,
+  },
+  'OBJUI-004': {
+    code: 'OBJUI-004',
+    message: 'Plugin dependency missing: "${dependency}"',
+    suggestion:
+      'Install the required dependency and register it before loading this plugin.',
+    docUrl: `${BASE_DOC_URL}/OBJUI-004`,
+  },
+  'OBJUI-005': {
+    code: 'OBJUI-005',
+    message: 'Plugin already loaded: "${plugin}"',
+    suggestion:
+      'A plugin with the same name is already registered. Remove the duplicate or use a unique plugin name.',
+    docUrl: `${BASE_DOC_URL}/OBJUI-005`,
+  },
+  'OBJUI-006': {
+    code: 'OBJUI-006',
+    message: 'Plugin not found: "${plugin}"',
+    suggestion:
+      'Verify the plugin name and ensure it has been registered before access.',
+    docUrl: `${BASE_DOC_URL}/OBJUI-006`,
+  },
+  'OBJUI-007': {
+    code: 'OBJUI-007',
+    message: 'Registry namespace deprecated: "${namespace}"',
+    suggestion:
+      'Migrate to the new namespace format. See the migration guide for details.',
+    docUrl: `${BASE_DOC_URL}/OBJUI-007`,
+  },
+  'OBJUI-008': {
+    code: 'OBJUI-008',
+    message: 'Read-only scope violation: "${scope}"',
+    suggestion:
+      'You are trying to mutate a read-only data scope. Use a writable scope or clone the data before modifying.',
+    docUrl: `${BASE_DOC_URL}/OBJUI-008`,
+  },
+  'OBJUI-009': {
+    code: 'OBJUI-009',
+    message: 'Invalid field configuration: "${field}"',
+    suggestion:
+      'Check the field schema for required properties (type, name). Ensure the field widget is registered.',
+    docUrl: `${BASE_DOC_URL}/OBJUI-009`,
+  },
+  'OBJUI-010': {
+    code: 'OBJUI-010',
+    message: 'Action execution failed: "${action}"',
+    suggestion:
+      'Verify the action handler is registered and that all required parameters are provided.',
+    docUrl: `${BASE_DOC_URL}/OBJUI-010`,
+  },
+} as const;
+
+// ---------------------------------------------------------------------------
+// Type Guards
+// ---------------------------------------------------------------------------
+
+/**
+ * Check whether a string is a known ObjectUI error code.
+ */
+export function isErrorCode(code: unknown): code is keyof typeof ERROR_CODES {
+  return typeof code === 'string' && code in ERROR_CODES;
+}
+
+// ---------------------------------------------------------------------------
+// Base Error Class
+// ---------------------------------------------------------------------------
+
+/**
+ * Base error class for all ObjectUI errors.
+ */
+export class ObjectUIError extends Error {
+  constructor(
+    message: string,
+    public code: string,
+    public details?: Record<string, unknown>,
+  ) {
+    super(message);
+    this.name = 'ObjectUIError';
+
+    // Maintains proper stack trace for where error was thrown (only in V8)
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, this.constructor);
+    }
+  }
+
+  /**
+   * Convert error to JSON for logging / debugging.
+   */
+  toJSON() {
+    return {
+      name: this.name,
+      message: this.message,
+      code: this.code,
+      details: this.details,
+      stack: this.stack,
+    };
+  }
+}
+
+/**
+ * Type guard to check if an error is an ObjectUIError.
+ */
+export function isObjectUIError(error: unknown): error is ObjectUIError {
+  return error instanceof ObjectUIError;
+}
+
+// ---------------------------------------------------------------------------
+// Specialized Error Classes
+// ---------------------------------------------------------------------------
+
+/** Thrown when a schema is invalid or fails validation. */
+export class SchemaError extends ObjectUIError {
+  constructor(message: string, details?: Record<string, unknown>) {
+    super(message, 'OBJUI-002', details);
+    this.name = 'SchemaError';
+  }
+}
+
+/** Thrown when a registry operation fails. */
+export class RegistryError extends ObjectUIError {
+  constructor(message: string, code: string, details?: Record<string, unknown>) {
+    super(message, code, details);
+    this.name = 'RegistryError';
+  }
+}
+
+/** Thrown when expression evaluation fails. */
+export class ExpressionError extends ObjectUIError {
+  constructor(message: string, details?: Record<string, unknown>) {
+    super(message, 'OBJUI-003', details);
+    this.name = 'ExpressionError';
+  }
+}
+
+/** Thrown when a plugin operation fails. */
+export class PluginError extends ObjectUIError {
+  constructor(message: string, code: string, details?: Record<string, unknown>) {
+    super(message, code, details);
+    this.name = 'PluginError';
+  }
+}
+
+/** Thrown when validation of user input / field config fails. */
+export class FieldValidationError extends ObjectUIError {
+  constructor(message: string, details?: Record<string, unknown>) {
+    super(message, 'OBJUI-009', details);
+    this.name = 'FieldValidationError';
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Factory & Formatting Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Interpolate a template string with the given params.
+ * Template variables use the `${key}` syntax.
+ */
+function interpolate(
+  template: string,
+  params: Record<string, string>,
+): string {
+  return template.replace(/\$\{(\w+)\}/g, (_match, key: string) => {
+    if (!(key in params) && typeof process !== 'undefined' && process.env?.NODE_ENV !== 'production') {
+      console.warn(`[ObjectUI] Missing interpolation parameter "${key}" in error message template.`);
+    }
+    return params[key] ?? `\${${key}}`;
+  });
+}
+
+/**
+ * Create an `ObjectUIError` (or subclass) from a known error code.
+ *
+ * @param code   - A registered error code (e.g. `"OBJUI-001"`).
+ * @param params - Values to interpolate into the message template.
+ * @param details - Optional extra details attached to the error.
+ */
+export function createError(
+  code: string,
+  params: Record<string, string> = {},
+  details?: Record<string, unknown>,
+): ObjectUIError {
+  const entry = ERROR_CODES[code];
+  const message = entry
+    ? interpolate(entry.message, params)
+    : `Unknown error code: ${code}`;
+
+  switch (code) {
+    case 'OBJUI-002':
+      return new SchemaError(message, details);
+    case 'OBJUI-003':
+      return new ExpressionError(message, details);
+    case 'OBJUI-004':
+    case 'OBJUI-005':
+    case 'OBJUI-006':
+      return new PluginError(message, code, details);
+    case 'OBJUI-007':
+    case 'OBJUI-001':
+      return new RegistryError(message, code, details);
+    case 'OBJUI-009':
+      return new FieldValidationError(message, details);
+    default:
+      return new ObjectUIError(message, code, details);
+  }
+}
+
+/**
+ * Format an error message with actionable fix suggestions in development mode.
+ *
+ * @param error - The `ObjectUIError` to format.
+ * @param isDev - When `true`, appends the suggestion and documentation link.
+ */
+export function formatErrorMessage(
+  error: ObjectUIError,
+  isDev: boolean = typeof process !== 'undefined' &&
+    process.env?.NODE_ENV !== 'production',
+): string {
+  const entry = ERROR_CODES[error.code];
+
+  let formatted = `[${error.code}] ${error.message}`;
+
+  if (isDev && entry) {
+    formatted += `\n\n💡 Suggestion: ${entry.suggestion}`;
+    formatted += `\n📖 Docs: ${entry.docUrl}`;
+  }
+
+  return formatted;
+}

package/src/evaluator/ExpressionEvaluator.ts

@@ -18,6 +18,7 @@
 
 import { ExpressionContext } from './ExpressionContext.js';
 import { ExpressionCache } from './ExpressionCache.js';
+import { FormulaFunctions } from './FormulaFunctions.js';
 
 /**
  * Options for expression evaluation
@@ -47,8 +48,13 @@ export interface EvaluationOptions {
 export class ExpressionEvaluator {
   private context: ExpressionContext;
   private cache: ExpressionCache;
+  private formulas: FormulaFunctions;
 
-  constructor(context?: ExpressionContext | Record<string, any>, cache?: ExpressionCache) {
+  constructor(
+    context?: ExpressionContext | Record<string, any>,
+    cache?: ExpressionCache,
+    formulas?: FormulaFunctions,
+  ) {
     if (context instanceof ExpressionContext) {
       this.context = context;
     } else {
@@ -57,6 +63,7 @@ export class ExpressionEvaluator {
     
     // Use provided cache or create a new one
     this.cache = cache || new ExpressionCache();
+    this.formulas = formulas || new FormulaFunctions();
   }
 
   /**
@@ -139,9 +146,13 @@ export class ExpressionEvaluator {
       // Create a safe evaluation function
       const contextObj = this.context.toObject();
       
+      // Inject formula functions into the evaluation context
+      const formulaObj = this.formulas.toObject();
+      const mergedContext = { ...formulaObj, ...contextObj };
+      
       // Build safe function with context variables
-      const varNames = Object.keys(contextObj);
-      const varValues = Object.values(contextObj);
+      const varNames = Object.keys(mergedContext);
+      const varValues = Object.values(mergedContext);
       
       // Use cached compilation
       const compiled = this.cache.compile(expression, varNames);
@@ -219,8 +230,8 @@ export class ExpressionEvaluator {
    * 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);
+    // Share the cache and formulas with the new evaluator for maximum efficiency
+    return new ExpressionEvaluator(this.context.createChild(data), this.cache, this.formulas);
   }
   
   /**
@@ -236,12 +247,27 @@ export class ExpressionEvaluator {
   clearCache(): void {
     this.cache.clear();
   }
+
+  /**
+   * Get the formula functions registry
+   */
+  getFormulas(): FormulaFunctions {
+    return this.formulas;
+  }
+
+  /**
+   * Register a custom formula function
+   */
+  registerFunction(name: string, fn: (...args: any[]) => any): void {
+    this.formulas.register(name, fn);
+  }
 }
 
 /**
- * Shared global cache for convenience functions
+ * Shared global cache and formulas for convenience functions
  */
 const globalCache = new ExpressionCache();
+const globalFormulas = new FormulaFunctions();
 
 /**
  * Convenience function to quickly evaluate an expression
@@ -251,7 +277,7 @@ export function evaluateExpression(
   context: Record<string, any> = {},
   options: EvaluationOptions = {}
 ): any {
-  const evaluator = new ExpressionEvaluator(context, globalCache);
+  const evaluator = new ExpressionEvaluator(context, globalCache, globalFormulas);
   return evaluator.evaluate(expression, options);
 }
 
@@ -262,6 +288,6 @@ export function evaluateCondition(
   condition: string | boolean | undefined,
   context: Record<string, any> = {}
 ): boolean {
-  const evaluator = new ExpressionEvaluator(context, globalCache);
+  const evaluator = new ExpressionEvaluator(context, globalCache, globalFormulas);
   return evaluator.evaluateCondition(condition);
 }