@object-ui/core 2.0.0 → 3.0.1

package/src/__benchmarks__/core.bench.ts

@@ -0,0 +1,64 @@
+/**
+ * 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.
+ */
+
+/**
+ * Performance benchmark suite for @object-ui/core.
+ *
+ * Part of Q1 2026 roadmap §1.4 Test Coverage Improvement.
+ *
+ * Run with: npx vitest bench packages/core/src/__benchmarks__/
+ */
+
+import { bench, describe } from 'vitest';
+import { ExpressionEvaluator } from '@object-ui/core';
+import { ComponentRegistry } from '@object-ui/core';
+import { contrastRatio, meetsContrastLevel, hexToHSL } from '@object-ui/core';
+
+describe('ExpressionEvaluator performance', () => {
+  const evaluator = new ExpressionEvaluator({ data: { name: 'Alice', age: 30, active: true } });
+
+  bench('evaluate simple string', () => {
+    evaluator.evaluate('Hello ${data.name}');
+  });
+
+  bench('evaluate 100 expressions', () => {
+    for (let i = 0; i < 100; i++) {
+      evaluator.evaluate('Hello ${data.name}');
+    }
+  });
+});
+
+describe('ComponentRegistry performance', () => {
+  bench('get registered component', () => {
+    ComponentRegistry.get('button');
+  });
+
+  bench('has check', () => {
+    ComponentRegistry.has('button');
+  });
+});
+
+describe('Theme utilities performance', () => {
+  bench('hexToHSL conversion', () => {
+    hexToHSL('#336699');
+  });
+
+  bench('contrastRatio calculation', () => {
+    contrastRatio('#000000', '#ffffff');
+  });
+
+  bench('meetsContrastLevel check', () => {
+    meetsContrastLevel('#000000', '#ffffff', 'AA');
+  });
+
+  bench('100 contrast checks', () => {
+    for (let i = 0; i < 100; i++) {
+      meetsContrastLevel('#336699', '#ffffff', 'AA');
+    }
+  });
+});

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/index.ts

@@ -20,3 +20,5 @@ export * from './query/index.js';
 export * from './adapters/index.js';
 export * from './theme/index.js';
 export * from './data-scope/index.js';
+export * from './errors/index.js';
+export * from './utils/debug.js';

package/src/registry/Registry.ts

@@ -86,7 +86,13 @@ export class Registry<T = any> {
     if (!meta?.namespace) {
       console.warn(
         `Registering component "${type}" without a namespace is deprecated. ` +
-        `Please provide a namespace in the meta parameter.`
+        `Please provide a namespace in the meta parameter.\n\n` +
+        `  Migration:\n` +
+        `  // Before (deprecated):\n` +
+        `  registry.register('${type}', MyComponent);\n\n` +
+        `  // After:\n` +
+        `  registry.register('${type}', MyComponent, { namespace: 'my-plugin' });\n\n` +
+        `  See: https://github.com/objectstack-ai/objectui/blob/main/MIGRATION_GUIDE.md`
       );
     }