@object-ui/core 0.5.0 → 3.0.0

package/dist/errors/index.js

@@ -0,0 +1,224 @@
+/**
+ * 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.
+ */
+const BASE_DOC_URL = 'https://objectui.dev/docs/errors';
+export const ERROR_CODES = {
+    '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`,
+    },
+};
+// ---------------------------------------------------------------------------
+// Type Guards
+// ---------------------------------------------------------------------------
+/**
+ * Check whether a string is a known ObjectUI error code.
+ */
+export function isErrorCode(code) {
+    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, code, details) {
+        super(message);
+        Object.defineProperty(this, "code", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: code
+        });
+        Object.defineProperty(this, "details", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: details
+        });
+        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) {
+    return error instanceof ObjectUIError;
+}
+// ---------------------------------------------------------------------------
+// Specialized Error Classes
+// ---------------------------------------------------------------------------
+/** Thrown when a schema is invalid or fails validation. */
+export class SchemaError extends ObjectUIError {
+    constructor(message, details) {
+        super(message, 'OBJUI-002', details);
+        this.name = 'SchemaError';
+    }
+}
+/** Thrown when a registry operation fails. */
+export class RegistryError extends ObjectUIError {
+    constructor(message, code, details) {
+        super(message, code, details);
+        this.name = 'RegistryError';
+    }
+}
+/** Thrown when expression evaluation fails. */
+export class ExpressionError extends ObjectUIError {
+    constructor(message, details) {
+        super(message, 'OBJUI-003', details);
+        this.name = 'ExpressionError';
+    }
+}
+/** Thrown when a plugin operation fails. */
+export class PluginError extends ObjectUIError {
+    constructor(message, code, details) {
+        super(message, code, details);
+        this.name = 'PluginError';
+    }
+}
+/** Thrown when validation of user input / field config fails. */
+export class FieldValidationError extends ObjectUIError {
+    constructor(message, details) {
+        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, params) {
+    return template.replace(/\$\{(\w+)\}/g, (_match, key) => {
+        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, params = {}, details) {
+    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, isDev = typeof process !== 'undefined' &&
+    process.env?.NODE_ENV !== 'production') {
+    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/dist/evaluator/ExpressionEvaluator.d.ts

@@ -16,6 +16,7 @@
  */
 import { ExpressionContext } from './ExpressionContext.js';
 import { ExpressionCache } from './ExpressionCache.js';
+import { FormulaFunctions } from './FormulaFunctions.js';
 /**
  * Options for expression evaluation
  */
@@ -41,7 +42,8 @@ export interface EvaluationOptions {
 export declare class ExpressionEvaluator {
     private context;
     private cache;
-    constructor(context?: ExpressionContext | Record<string, any>, cache?: ExpressionCache);
+    private formulas;
+    constructor(context?: ExpressionContext | Record<string, any>, cache?: ExpressionCache, formulas?: FormulaFunctions);
     /**
      * Evaluate a string that may contain template expressions like ${...}
      *
@@ -106,6 +108,14 @@ export declare class ExpressionEvaluator {
      * Clear the expression cache
      */
     clearCache(): void;
+    /**
+     * Get the formula functions registry
+     */
+    getFormulas(): FormulaFunctions;
+    /**
+     * Register a custom formula function
+     */
+    registerFunction(name: string, fn: (...args: any[]) => any): void;
 }
 /**
  * Convenience function to quickly evaluate an expression

package/dist/evaluator/ExpressionEvaluator.js

@@ -16,11 +16,12 @@
  */
 import { ExpressionContext } from './ExpressionContext.js';
 import { ExpressionCache } from './ExpressionCache.js';
+import { FormulaFunctions } from './FormulaFunctions.js';
 /**
  * Expression evaluator for dynamic UI expressions
  */
 export class ExpressionEvaluator {
-    constructor(context, cache) {
+    constructor(context, cache, formulas) {
         Object.defineProperty(this, "context", {
             enumerable: true,
             configurable: true,
@@ -33,6 +34,12 @@ export class ExpressionEvaluator {
             writable: true,
             value: void 0
         });
+        Object.defineProperty(this, "formulas", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
         if (context instanceof ExpressionContext) {
             this.context = context;
         }
@@ -41,6 +48,7 @@ export class ExpressionEvaluator {
         }
         // Use provided cache or create a new one
         this.cache = cache || new ExpressionCache();
+        this.formulas = formulas || new FormulaFunctions();
     }
     /**
      * Evaluate a string that may contain template expressions like ${...}
@@ -114,9 +122,12 @@ export class ExpressionEvaluator {
         try {
             // 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);
             // Execute with context values
@@ -184,8 +195,8 @@ export class ExpressionEvaluator {
      * Create a new evaluator with additional context data
      */
     withContext(data) {
-        // 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);
     }
     /**
      * Get cache statistics (useful for debugging and optimization)
@@ -199,22 +210,35 @@ export class ExpressionEvaluator {
     clearCache() {
         this.cache.clear();
     }
+    /**
+     * Get the formula functions registry
+     */
+    getFormulas() {
+        return this.formulas;
+    }
+    /**
+     * Register a custom formula function
+     */
+    registerFunction(name, fn) {
+        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
  */
 export function evaluateExpression(expression, context = {}, options = {}) {
-    const evaluator = new ExpressionEvaluator(context, globalCache);
+    const evaluator = new ExpressionEvaluator(context, globalCache, globalFormulas);
     return evaluator.evaluate(expression, options);
 }
 /**
  * Convenience function to evaluate a condition
  */
 export function evaluateCondition(condition, context = {}) {
-    const evaluator = new ExpressionEvaluator(context, globalCache);
+    const evaluator = new ExpressionEvaluator(context, globalCache, globalFormulas);
     return evaluator.evaluateCondition(condition);
 }

package/dist/evaluator/FormulaFunctions.d.ts

@@ -0,0 +1,58 @@
+/**
+ * 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 declare class FormulaFunctions {
+    private functions;
+    constructor();
+    /**
+     * Register a custom formula function
+     */
+    register(name: string, fn: FormulaFunction): void;
+    /**
+     * Get a formula function by name
+     */
+    get(name: string): FormulaFunction | undefined;
+    /**
+     * Check if a function is registered
+     */
+    has(name: string): boolean;
+    /**
+     * Get all registered function names
+     */
+    getNames(): string[];
+    /**
+     * Get all functions as a plain object (for injection into expression context)
+     */
+    toObject(): Record<string, FormulaFunction>;
+    /**
+     * Register all default built-in functions
+     */
+    private registerDefaults;
+    private registerAggregationFunctions;
+    private registerDateFunctions;
+    private registerLogicFunctions;
+    private registerStringFunctions;
+    private registerStringSearchFunctions;
+    private registerStatisticalFunctions;
+}