@object-ui/core 0.3.1 → 2.0.0

package/dist/adapters/resolveDataSource.js

@@ -0,0 +1,59 @@
+/**
+ * ObjectUI — resolveDataSource
+ * 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.
+ *
+ * Factory function to create the right DataSource from a ViewData config.
+ */
+import { ApiDataSource } from './ApiDataSource.js';
+import { ValueDataSource } from './ValueDataSource.js';
+/**
+ * Resolve a ViewData configuration into a concrete DataSource instance.
+ *
+ * - `provider: 'object'` → returns `fallback` (the context DataSource — typically ObjectStackAdapter)
+ * - `provider: 'api'`    → returns a new `ApiDataSource`
+ * - `provider: 'value'`  → returns a new `ValueDataSource`
+ *
+ * @param viewData - The ViewData configuration from the schema
+ * @param fallback - The default DataSource from context (for `provider: 'object'`)
+ * @param options  - Additional options for adapter construction
+ * @returns A DataSource instance, or null if neither viewData nor fallback is available
+ *
+ * @example
+ * ```ts
+ * const ds = resolveDataSource(
+ *   { provider: 'api', read: { url: '/api/users' } },
+ *   contextDataSource,
+ * );
+ * const result = await ds.find('users');
+ * ```
+ */
+export function resolveDataSource(viewData, fallback, options) {
+    if (!viewData) {
+        return fallback ?? null;
+    }
+    switch (viewData.provider) {
+        case 'object':
+            // Delegate to the context DataSource (ObjectStackAdapter, etc.)
+            return fallback ?? null;
+        case 'api': {
+            const config = {
+                read: viewData.read,
+                write: viewData.write,
+                fetch: options?.fetch,
+                defaultHeaders: options?.defaultHeaders,
+            };
+            return new ApiDataSource(config);
+        }
+        case 'value':
+            return new ValueDataSource({
+                items: (viewData.items ?? []),
+                idField: options?.idField,
+            });
+        default:
+            // Unknown provider — fall back to context
+            return fallback ?? null;
+    }
+}

package/dist/data-scope/DataScopeManager.d.ts

@@ -0,0 +1,127 @@
+/**
+ * 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 - DataScope Manager
+ *
+ * Runtime implementation of the DataContext interface for managing
+ * named data scopes. Provides row-level data access control and
+ * reactive data state management within the UI component tree.
+ *
+ * @module data-scope
+ * @packageDocumentation
+ */
+import type { DataScope, DataContext, DataSource } from '@object-ui/types';
+/**
+ * Row-level filter for restricting data access within a scope
+ */
+export interface RowLevelFilter {
+    /** Field to filter on */
+    field: string;
+    /** Filter operator */
+    operator: 'eq' | 'ne' | 'gt' | 'lt' | 'gte' | 'lte' | 'in' | 'nin' | 'contains';
+    /** Filter value */
+    value: any;
+}
+/**
+ * Configuration for creating a data scope
+ */
+export interface DataScopeConfig {
+    /** Data source instance */
+    dataSource?: DataSource;
+    /** Initial data */
+    data?: any;
+    /** Row-level filters to apply */
+    filters?: RowLevelFilter[];
+    /** Whether this scope is read-only */
+    readOnly?: boolean;
+}
+/**
+ * DataScopeManager — Runtime implementation of DataContext.
+ *
+ * Manages named data scopes for the component tree, providing:
+ * - Scope registration and lookup
+ * - Row-level security via filters
+ * - Data state management (data, loading, error)
+ *
+ * @example
+ * ```ts
+ * const manager = new DataScopeManager();
+ * manager.registerScope('contacts', {
+ *   dataSource: myDataSource,
+ *   data: [],
+ * });
+ * const scope = manager.getScope('contacts');
+ * ```
+ */
+export declare class DataScopeManager implements DataContext {
+    scopes: Record<string, DataScope>;
+    private filters;
+    private readOnlyScopes;
+    private listeners;
+    /**
+     * Register a data scope
+     */
+    registerScope(name: string, scope: DataScope): void;
+    /**
+     * Register a data scope with configuration
+     */
+    registerScopeWithConfig(name: string, config: DataScopeConfig): void;
+    /**
+     * Get a data scope by name
+     */
+    getScope(name: string): DataScope | undefined;
+    /**
+     * Remove a data scope
+     */
+    removeScope(name: string): void;
+    /**
+     * Check if a scope is read-only
+     */
+    isReadOnly(name: string): boolean;
+    /**
+     * Get row-level filters for a scope
+     */
+    getFilters(name: string): RowLevelFilter[];
+    /**
+     * Set row-level filters for a scope
+     */
+    setFilters(name: string, filters: RowLevelFilter[]): void;
+    /**
+     * Apply row-level filters to a dataset
+     */
+    applyFilters(name: string, data: any[]): any[];
+    /**
+     * Update data in a scope
+     */
+    updateScopeData(name: string, data: any): void;
+    /**
+     * Update loading state for a scope
+     */
+    updateScopeLoading(name: string, loading: boolean): void;
+    /**
+     * Update error state for a scope
+     */
+    updateScopeError(name: string, error: Error | string | null): void;
+    /**
+     * Subscribe to scope changes
+     */
+    onScopeChange(name: string, listener: (scope: DataScope) => void): () => void;
+    /**
+     * Get all registered scope names
+     */
+    getScopeNames(): string[];
+    /**
+     * Clear all scopes
+     */
+    clear(): void;
+    private notifyListeners;
+}
+/**
+ * Default DataScopeManager instance
+ */
+export declare const defaultDataScopeManager: DataScopeManager;

package/dist/data-scope/DataScopeManager.js

@@ -0,0 +1,229 @@
+/**
+ * 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.
+ */
+/**
+ * DataScopeManager — Runtime implementation of DataContext.
+ *
+ * Manages named data scopes for the component tree, providing:
+ * - Scope registration and lookup
+ * - Row-level security via filters
+ * - Data state management (data, loading, error)
+ *
+ * @example
+ * ```ts
+ * const manager = new DataScopeManager();
+ * manager.registerScope('contacts', {
+ *   dataSource: myDataSource,
+ *   data: [],
+ * });
+ * const scope = manager.getScope('contacts');
+ * ```
+ */
+export class DataScopeManager {
+    constructor() {
+        Object.defineProperty(this, "scopes", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: {}
+        });
+        Object.defineProperty(this, "filters", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: {}
+        });
+        Object.defineProperty(this, "readOnlyScopes", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Set()
+        });
+        Object.defineProperty(this, "listeners", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Map()
+        });
+    }
+    /**
+     * Register a data scope
+     */
+    registerScope(name, scope) {
+        this.scopes[name] = scope;
+        this.notifyListeners(name, scope);
+    }
+    /**
+     * Register a data scope with configuration
+     */
+    registerScopeWithConfig(name, config) {
+        const scope = {
+            dataSource: config.dataSource,
+            data: config.data,
+            loading: false,
+            error: null,
+        };
+        if (config.filters) {
+            this.filters[name] = config.filters;
+        }
+        if (config.readOnly) {
+            this.readOnlyScopes.add(name);
+        }
+        this.scopes[name] = scope;
+        this.notifyListeners(name, scope);
+    }
+    /**
+     * Get a data scope by name
+     */
+    getScope(name) {
+        return this.scopes[name];
+    }
+    /**
+     * Remove a data scope
+     */
+    removeScope(name) {
+        delete this.scopes[name];
+        delete this.filters[name];
+        this.readOnlyScopes.delete(name);
+        this.listeners.delete(name);
+    }
+    /**
+     * Check if a scope is read-only
+     */
+    isReadOnly(name) {
+        return this.readOnlyScopes.has(name);
+    }
+    /**
+     * Get row-level filters for a scope
+     */
+    getFilters(name) {
+        return this.filters[name] || [];
+    }
+    /**
+     * Set row-level filters for a scope
+     */
+    setFilters(name, filters) {
+        this.filters[name] = filters;
+    }
+    /**
+     * Apply row-level filters to a dataset
+     */
+    applyFilters(name, data) {
+        const scopeFilters = this.filters[name];
+        if (!scopeFilters || scopeFilters.length === 0) {
+            return data;
+        }
+        return data.filter(row => {
+            return scopeFilters.every(filter => {
+                const fieldValue = row[filter.field];
+                return evaluateFilter(fieldValue, filter.operator, filter.value);
+            });
+        });
+    }
+    /**
+     * Update data in a scope
+     */
+    updateScopeData(name, data) {
+        const scope = this.scopes[name];
+        if (!scope)
+            return;
+        if (this.readOnlyScopes.has(name)) {
+            throw new Error(`Cannot update read-only scope: ${name}`);
+        }
+        scope.data = data;
+        this.notifyListeners(name, scope);
+    }
+    /**
+     * Update loading state for a scope
+     */
+    updateScopeLoading(name, loading) {
+        const scope = this.scopes[name];
+        if (!scope)
+            return;
+        scope.loading = loading;
+        this.notifyListeners(name, scope);
+    }
+    /**
+     * Update error state for a scope
+     */
+    updateScopeError(name, error) {
+        const scope = this.scopes[name];
+        if (!scope)
+            return;
+        scope.error = error;
+        this.notifyListeners(name, scope);
+    }
+    /**
+     * Subscribe to scope changes
+     */
+    onScopeChange(name, listener) {
+        if (!this.listeners.has(name)) {
+            this.listeners.set(name, []);
+        }
+        this.listeners.get(name).push(listener);
+        return () => {
+            const arr = this.listeners.get(name);
+            if (arr) {
+                const idx = arr.indexOf(listener);
+                if (idx >= 0)
+                    arr.splice(idx, 1);
+            }
+        };
+    }
+    /**
+     * Get all registered scope names
+     */
+    getScopeNames() {
+        return Object.keys(this.scopes);
+    }
+    /**
+     * Clear all scopes
+     */
+    clear() {
+        this.scopes = {};
+        this.filters = {};
+        this.readOnlyScopes.clear();
+        this.listeners.clear();
+    }
+    notifyListeners(name, scope) {
+        const arr = this.listeners.get(name);
+        if (arr) {
+            arr.forEach(listener => listener(scope));
+        }
+    }
+}
+/**
+ * Evaluate a single filter condition against a field value
+ */
+function evaluateFilter(fieldValue, operator, filterValue) {
+    switch (operator) {
+        case 'eq':
+            return fieldValue === filterValue;
+        case 'ne':
+            return fieldValue !== filterValue;
+        case 'gt':
+            return fieldValue > filterValue;
+        case 'lt':
+            return fieldValue < filterValue;
+        case 'gte':
+            return fieldValue >= filterValue;
+        case 'lte':
+            return fieldValue <= filterValue;
+        case 'in':
+            return Array.isArray(filterValue) && filterValue.includes(fieldValue);
+        case 'nin':
+            return Array.isArray(filterValue) && !filterValue.includes(fieldValue);
+        case 'contains':
+            return typeof fieldValue === 'string' && fieldValue.includes(String(filterValue));
+        default:
+            return true;
+    }
+}
+/**
+ * Default DataScopeManager instance
+ */
+export const defaultDataScopeManager = new DataScopeManager();

package/dist/data-scope/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @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/dist/data-scope/index.js

@@ -0,0 +1,10 @@
+/**
+ * @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, } from './DataScopeManager.js';

package/dist/evaluator/ExpressionCache.d.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.
+ */
+/**
+ * @object-ui/core - Expression Cache
+ *
+ * Caches compiled expressions to avoid re-parsing on every render.
+ * Provides significant performance improvement for frequently evaluated expressions.
+ *
+ * @module evaluator
+ * @packageDocumentation
+ */
+/**
+ * A compiled expression function that can be executed with context values
+ */
+export type CompiledExpression = (...args: any[]) => any;
+/**
+ * Expression compilation metadata
+ */
+export interface ExpressionMetadata {
+    /**
+     * The compiled function
+     */
+    fn: CompiledExpression;
+    /**
+     * Variable names used in the expression
+     */
+    varNames: string[];
+    /**
+     * Original expression string
+     */
+    expression: string;
+    /**
+     * Timestamp when the expression was compiled
+     */
+    compiledAt: number;
+    /**
+     * Number of times this expression has been used
+     */
+    hitCount: number;
+}
+/**
+ * Cache for compiled expressions
+ *
+ * @example
+ * ```ts
+ * const cache = new ExpressionCache();
+ * const compiled = cache.compile('data.amount > 1000', ['data']);
+ * const result = compiled.fn({ amount: 1500 }); // true
+ * ```
+ */
+export declare class ExpressionCache {
+    private cache;
+    private maxSize;
+    /**
+     * Create a new expression cache
+     *
+     * @param maxSize Maximum number of expressions to cache (default: 1000)
+     */
+    constructor(maxSize?: number);
+    /**
+     * Compile an expression or retrieve from cache
+     *
+     * @param expr The expression to compile
+     * @param varNames Variable names available in the context
+     * @returns Compiled expression metadata
+     */
+    compile(expr: string, varNames: string[]): ExpressionMetadata;
+    /**
+     * Compile an expression into a function
+     */
+    private compileExpression;
+    /**
+     * Evict the least frequently used expression from cache
+     */
+    private evictLFU;
+    /**
+     * Check if an expression is cached
+     */
+    has(expr: string, varNames: string[]): boolean;
+    /**
+     * Clear the cache
+     */
+    clear(): void;
+    /**
+     * Get cache statistics
+     */
+    getStats(): {
+        size: number;
+        maxSize: number;
+        totalHits: number;
+        entries: Array<{
+            expression: string;
+            hitCount: number;
+        }>;
+    };
+}

package/dist/evaluator/ExpressionCache.js

@@ -0,0 +1,135 @@
+/**
+ * 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.
+ */
+/**
+ * Cache for compiled expressions
+ *
+ * @example
+ * ```ts
+ * const cache = new ExpressionCache();
+ * const compiled = cache.compile('data.amount > 1000', ['data']);
+ * const result = compiled.fn({ amount: 1500 }); // true
+ * ```
+ */
+export class ExpressionCache {
+    /**
+     * Create a new expression cache
+     *
+     * @param maxSize Maximum number of expressions to cache (default: 1000)
+     */
+    constructor(maxSize = 1000) {
+        Object.defineProperty(this, "cache", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Map()
+        });
+        Object.defineProperty(this, "maxSize", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.maxSize = maxSize;
+    }
+    /**
+     * Compile an expression or retrieve from cache
+     *
+     * @param expr The expression to compile
+     * @param varNames Variable names available in the context
+     * @returns Compiled expression metadata
+     */
+    compile(expr, varNames) {
+        // Create a cache key that includes variable names to ensure correct scoping
+        const cacheKey = `${expr}::${varNames.join(',')}`;
+        if (this.cache.has(cacheKey)) {
+            const metadata = this.cache.get(cacheKey);
+            metadata.hitCount++;
+            return metadata;
+        }
+        // Evict least frequently used if cache is full
+        if (this.cache.size >= this.maxSize) {
+            this.evictLFU();
+        }
+        // Compile the expression
+        const fn = this.compileExpression(expr, varNames);
+        const metadata = {
+            fn,
+            varNames: [...varNames],
+            expression: expr,
+            compiledAt: Date.now(),
+            hitCount: 1,
+        };
+        this.cache.set(cacheKey, metadata);
+        return metadata;
+    }
+    /**
+     * Compile an expression into a function
+     */
+    compileExpression(expression, varNames) {
+        // SECURITY NOTE: Using Function constructor for expression evaluation.
+        // This is a controlled use case with:
+        // 1. Sanitization check (isDangerous) performed by caller
+        // 2. Strict mode enabled ("use strict")
+        // 3. Limited scope (only varNames variables available)
+        // 4. No access to global objects (process, window, etc.)
+        return new Function(...varNames, `"use strict"; return (${expression});`);
+    }
+    /**
+     * Evict the least frequently used expression from cache
+     */
+    evictLFU() {
+        let oldestKey = null;
+        let oldestTime = Infinity;
+        let lowestHits = Infinity;
+        // Find the entry with lowest hit count, or oldest if tied
+        for (const [key, metadata] of this.cache.entries()) {
+            if (metadata.hitCount < lowestHits ||
+                (metadata.hitCount === lowestHits && metadata.compiledAt < oldestTime)) {
+                oldestKey = key;
+                oldestTime = metadata.compiledAt;
+                lowestHits = metadata.hitCount;
+            }
+        }
+        if (oldestKey) {
+            this.cache.delete(oldestKey);
+        }
+    }
+    /**
+     * Check if an expression is cached
+     */
+    has(expr, varNames) {
+        const cacheKey = `${expr}::${varNames.join(',')}`;
+        return this.cache.has(cacheKey);
+    }
+    /**
+     * Clear the cache
+     */
+    clear() {
+        this.cache.clear();
+    }
+    /**
+     * Get cache statistics
+     */
+    getStats() {
+        let totalHits = 0;
+        const entries = [];
+        for (const metadata of this.cache.values()) {
+            totalHits += metadata.hitCount;
+            entries.push({
+                expression: metadata.expression,
+                hitCount: metadata.hitCount,
+            });
+        }
+        return {
+            size: this.cache.size,
+            maxSize: this.maxSize,
+            totalHits,
+            entries: entries.sort((a, b) => b.hitCount - a.hitCount),
+        };
+    }
+}