@object-ui/core 3.1.5 → 3.3.1

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @object-ui/core
 
+## 3.3.1
+
+### Patch Changes
+
+- @object-ui/types@3.3.1
+
+## 3.3.0
+
+### Patch Changes
+
+- @object-ui/types@3.3.0
+
+## 3.2.0
+
+### Patch Changes
+
+- @object-ui/types@3.2.0
+
 ## 3.1.5
 
 ### Patch Changes

package/README.md

@@ -79,6 +79,25 @@ This allows the core types and logic to be used in:
 
 See [full documentation](https://objectui.org/api/core) for detailed API reference.
 
+<!-- release-metadata:v3.3.0 -->
+
+## Compatibility
+
+- **Node.js:** ≥ 18
+- **TypeScript:** ≥ 5.0 (strict mode)
+- **`@objectstack/spec`:** ^3.3.0
+- **`@objectstack/client`:** ^3.3.0
+- **Tailwind CSS:** ≥ 3.4 (for packages with UI)
+
+## Links
+
+- 📚 [Documentation](https://www.objectui.org/docs/core)
+- 📦 [npm package](https://www.npmjs.com/package/@object-ui/core)
+- 📝 [Changelog](./CHANGELOG.md)
+- 🐛 [Report an issue](https://github.com/objectstack-ai/objectui/issues)
+- 🤝 [Contributing Guide](https://github.com/objectstack-ai/objectui/blob/main/CONTRIBUTING.md)
+- 🗺️ [Roadmap](https://github.com/objectstack-ai/objectui/blob/main/ROADMAP.md)
+
 ## License
 
-MIT
+MIT — see [LICENSE](./LICENSE).

package/dist/actions/ActionRunner.d.ts

@@ -178,6 +178,7 @@ export interface ActionParamDef {
 }
 export declare class ActionRunner {
     private handlers;
+    private scripts;
     private evaluator;
     private context;
     private confirmHandler;
@@ -209,6 +210,14 @@ export declare class ActionRunner {
     setParamCollectionHandler(handler: ParamCollectionHandler): void;
     registerHandler(actionName: string, handler: ActionHandler): void;
     unregisterHandler(actionName: string): void;
+    /**
+     * Register a named script handler. When a `script` action's
+     * `target`/`execute` matches the registered name, the handler runs
+     * instead of the expression evaluator. Lets dashboards/views wire
+     * symbolic action names (e.g. 'export_dashboard_pdf') to JS callbacks.
+     */
+    registerScript(scriptName: string, handler: ActionHandler): void;
+    unregisterScript(scriptName: string): void;
     execute(action: ActionDef): Promise<ActionResult>;
     /**
      * Execute multiple actions in sequence or parallel.

package/dist/actions/ActionRunner.js

@@ -22,6 +22,12 @@ export class ActionRunner {
             writable: true,
             value: new Map()
         });
+        Object.defineProperty(this, "scripts", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Map()
+        });
         Object.defineProperty(this, "evaluator", {
             enumerable: true,
             configurable: true,
@@ -110,6 +116,18 @@ export class ActionRunner {
     unregisterHandler(actionName) {
         this.handlers.delete(actionName);
     }
+    /**
+     * Register a named script handler. When a `script` action's
+     * `target`/`execute` matches the registered name, the handler runs
+     * instead of the expression evaluator. Lets dashboards/views wire
+     * symbolic action names (e.g. 'export_dashboard_pdf') to JS callbacks.
+     */
+    registerScript(scriptName, handler) {
+        this.scripts.set(scriptName, handler);
+    }
+    unregisterScript(scriptName) {
+        this.scripts.delete(scriptName);
+    }
     async execute(action) {
         try {
             // Resolve the action type
@@ -143,14 +161,21 @@ export class ActionRunner {
             }
             // Param collection: if the action defines ActionParam[] to collect,
             // show a dialog to gather user input before executing.
-            if (action.actionParams && Array.isArray(action.actionParams) && action.actionParams.length > 0) {
+            // Spec defines this as `params: ActionParam[]`; ActionRunner historically
+            // used `actionParams` to disambiguate from the static-params object that
+            // some custom handlers consume. Accept both — when `params` is an array,
+            // treat it as the input-collection definition.
+            const paramDefs = action.actionParams && Array.isArray(action.actionParams) ? action.actionParams
+                : (Array.isArray(action.params) ? action.params : undefined);
+            if (paramDefs && paramDefs.length > 0) {
                 if (this.paramCollectionHandler) {
-                    const collected = await this.paramCollectionHandler(action.actionParams);
+                    const collected = await this.paramCollectionHandler(paramDefs);
                     if (collected === null) {
                         return { success: false, error: 'Action cancelled by user (params)' };
                     }
-                    // Merge collected params into action.params
-                    action.params = { ...(action.params || {}), ...collected };
+                    // Merge collected params into action.params as a values map for downstream consumers.
+                    // (Replace the array form with a values object once collected.)
+                    action.params = { ...(Array.isArray(action.params) ? {} : (action.params || {})), ...collected };
                 }
             }
             // Check for a registered custom handler first
@@ -293,6 +318,18 @@ export class ActionRunner {
         if (!script) {
             return { success: false, error: 'No script provided for script action' };
         }
+        // Named script registry wins over the expression evaluator. This lets
+        // dashboards/views bind a symbolic action name (e.g. 'export_dashboard_pdf')
+        // to a JS callback without piping the literal through ExpressionEvaluator.
+        const named = this.scripts.get(script);
+        if (named) {
+            try {
+                return await named(action, this.context);
+            }
+            catch (error) {
+                return { success: false, error: `Script execution failed: ${error.message}` };
+            }
+        }
         try {
             const result = this.evaluator.evaluate(`\${${script}}`);
             return { success: true, data: result };

package/dist/adapters/ValueDataSource.d.ts

@@ -8,7 +8,7 @@
  * A DataSource adapter for the `provider: 'value'` ViewData mode.
  * Operates entirely on an in-memory array — no network requests.
  */
-import type { DataSource, QueryParams, QueryResult, AggregateParams, AggregateResult } from '@object-ui/types';
+import type { DataSource, MutationEvent, QueryParams, QueryResult, AggregateParams, AggregateResult } from '@object-ui/types';
 export interface ValueDataSourceConfig<T = any> {
     /** The static data array */
     items: T[];
@@ -38,7 +38,10 @@ export interface ValueDataSourceConfig<T = any> {
 export declare class ValueDataSource<T = any> implements DataSource<T> {
     private items;
     private idField;
+    private mutationListeners;
     constructor(config: ValueDataSourceConfig<T>);
+    /** Notify all mutation subscribers */
+    private emitMutation;
     find(_resource: string, params?: QueryParams): Promise<QueryResult<T>>;
     findOne(_resource: string, id: string | number, params?: QueryParams): Promise<T | null>;
     create(_resource: string, data: Partial<T>): Promise<T>;
@@ -49,6 +52,7 @@ export declare class ValueDataSource<T = any> implements DataSource<T> {
     getView(_objectName: string, _viewId: string): Promise<any | null>;
     getApp(_appId: string): Promise<any | null>;
     aggregate(_resource: string, params: AggregateParams): Promise<AggregateResult[]>;
+    onMutation(callback: (event: MutationEvent<T>) => void): () => void;
     /** Get the current number of items */
     get count(): number;
     /** Get a snapshot of all items (cloned) */

package/dist/adapters/ValueDataSource.js

@@ -53,7 +53,9 @@ function matchesASTFilter(record, filterNode) {
             case 'in':
                 return Array.isArray(target) && target.includes(value);
             case 'not in':
-            case 'notin': // alias used by convertFiltersToAST
+            case 'not_in':
+            case 'nin': // canonical (per spec)
+            case 'notin': // legacy alias
                 return Array.isArray(target) && !target.includes(value);
             case 'contains': {
                 const lv = typeof value === 'string' ? value.toLowerCase() : '';
@@ -217,10 +219,27 @@ export class ValueDataSource {
             writable: true,
             value: void 0
         });
+        Object.defineProperty(this, "mutationListeners", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Set()
+        });
         // Deep clone to prevent external mutation
         this.items = JSON.parse(JSON.stringify(config.items));
         this.idField = config.idField;
     }
+    /** Notify all mutation subscribers */
+    emitMutation(event) {
+        for (const listener of this.mutationListeners) {
+            try {
+                listener(event);
+            }
+            catch (err) {
+                console.warn('ValueDataSource: mutation listener error', err);
+            }
+        }
+    }
     // -----------------------------------------------------------------------
     // DataSource interface
     // -----------------------------------------------------------------------
@@ -277,6 +296,7 @@ export class ValueDataSource {
             record[field] = `auto_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
         }
         this.items.push(record);
+        this.emitMutation({ type: 'create', resource: _resource, record: { ...record } });
         return { ...record };
     }
     async update(_resource, id, data) {
@@ -285,6 +305,7 @@ export class ValueDataSource {
             throw new Error(`ValueDataSource: Record with id "${id}" not found`);
         }
         this.items[index] = { ...this.items[index], ...data };
+        this.emitMutation({ type: 'update', resource: _resource, id, record: { ...this.items[index] } });
         return { ...this.items[index] };
     }
     async delete(_resource, id) {
@@ -292,6 +313,7 @@ export class ValueDataSource {
         if (index === -1)
             return false;
         this.items.splice(index, 1);
+        this.emitMutation({ type: 'delete', resource: _resource, id });
         return true;
     }
     async bulk(_resource, operation, data) {
@@ -370,6 +392,13 @@ export class ValueDataSource {
         });
     }
     // -----------------------------------------------------------------------
+    // Mutation subscription (P2 — Event Bus)
+    // -----------------------------------------------------------------------
+    onMutation(callback) {
+        this.mutationListeners.add(callback);
+        return () => { this.mutationListeners.delete(callback); };
+    }
+    // -----------------------------------------------------------------------
     // Extra utilities
     // -----------------------------------------------------------------------
     /** Get the current number of items */

package/dist/errors/index.js

@@ -170,7 +170,7 @@ export class FieldValidationError extends ObjectUIError {
  */
 function interpolate(template, params) {
     return template.replace(/\$\{(\w+)\}/g, (_match, key) => {
-        if (!(key in params) && typeof process !== 'undefined' && process.env?.NODE_ENV !== 'production') {
+        if (!(key in params) && globalThis.process?.env?.NODE_ENV !== 'production') {
             console.warn(`[ObjectUI] Missing interpolation parameter "${key}" in error message template.`);
         }
         return params[key] ?? `\${${key}}`;
@@ -212,8 +212,7 @@ export function createError(code, params = {}, details) {
  * @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') {
+export function formatErrorMessage(error, isDev = globalThis.process?.env?.NODE_ENV !== 'production') {
     const entry = ERROR_CODES[error.code];
     let formatted = `[${error.code}] ${error.message}`;
     if (isDev && entry) {

package/dist/evaluator/ExpressionCache.d.ts

@@ -5,15 +5,6 @@
  * 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
  */
@@ -71,7 +62,15 @@ export declare class ExpressionCache {
      */
     compile(expr: string, varNames: string[]): ExpressionMetadata;
     /**
-     * Compile an expression into a function
+     * Compile an expression into a CSP-safe callable function.
+     *
+     * Uses `SafeExpressionParser` — a recursive-descent interpreter — instead of
+     * `new Function()` so that the expression engine works under strict
+     * Content Security Policy headers that forbid `'unsafe-eval'`.
+     *
+     * A single parser instance is created per compiled expression and reused
+     * across all invocations of the returned closure (`evaluate()` resets all
+     * internal state on every call), avoiding repeated allocations on hot paths.
      */
     private compileExpression;
     /**

package/dist/evaluator/ExpressionCache.js

@@ -5,6 +5,16 @@
  * 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
+ */
+import { SafeExpressionParser } from './SafeExpressionParser.js';
 /**
  * Cache for compiled expressions
  *
@@ -68,16 +78,27 @@ export class ExpressionCache {
         return metadata;
     }
     /**
-     * Compile an expression into a function
+     * Compile an expression into a CSP-safe callable function.
+     *
+     * Uses `SafeExpressionParser` — a recursive-descent interpreter — instead of
+     * `new Function()` so that the expression engine works under strict
+     * Content Security Policy headers that forbid `'unsafe-eval'`.
+     *
+     * A single parser instance is created per compiled expression and reused
+     * across all invocations of the returned closure (`evaluate()` resets all
+     * internal state on every call), avoiding repeated allocations on hot paths.
      */
     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});`);
+        // One parser per compiled expression — reused across hot-path calls.
+        const parser = new SafeExpressionParser();
+        return (...args) => {
+            // Reconstruct the named variable context from positional arguments.
+            const context = {};
+            for (let i = 0; i < varNames.length; i++) {
+                context[varNames[i]] = args[i];
+            }
+            return parser.evaluate(expression, context);
+        };
     }
     /**
      * Evict the least frequently used expression from cache

package/dist/evaluator/SafeExpressionParser.d.ts

@@ -0,0 +1,131 @@
+/**
+ * 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.
+ */
+/**
+ * CSP-safe recursive-descent expression parser.
+ *
+ * Call `evaluate(expression, context)` to parse and execute an expression
+ * string against a data context object without any use of `eval()` or
+ * `new Function()`.
+ *
+ * @example
+ * ```ts
+ * const parser = new SafeExpressionParser();
+ * parser.evaluate('data.amount > 1000', { data: { amount: 1500 } }); // true
+ * parser.evaluate('stage !== "closed_won" && stage !== "closed_lost"', { stage: 'open' }); // true
+ * parser.evaluate('items.filter(i => i.active).length', { items: [{active:true},{active:false}] }); // 1
+ * ```
+ */
+export declare class SafeExpressionParser {
+    private source;
+    private pos;
+    private context;
+    /**
+     * Evaluation guard.
+     *
+     * When `false` the parser still advances `this.pos` through the source
+     * (maintaining correct position for the caller) but suppresses:
+     * - ReferenceErrors from undefined identifiers
+     * - actual function / method invocations
+     * - constructor calls
+     *
+     * This implements proper short-circuit semantics for `||`, `&&`, `??`, and
+     * the ternary operator without needing a separate AST pass.
+     */
+    private _evaluating;
+    /**
+     * Evaluate an expression string against a data context.
+     *
+     * Safe for use under strict CSP — never uses `eval()` or `new Function()`.
+     *
+     * @param expression - The expression to evaluate (without `${}` wrapper)
+     * @param context    - Variables available to the expression
+     * @returns The evaluated result
+     * @throws {ReferenceError} When an identifier is not found in the context
+     * @throws {TypeError}      On type mismatches (e.g., calling a non-function)
+     * @throws {SyntaxError}    On malformed expression syntax
+     */
+    evaluate(expression: string, context: Record<string, unknown>): unknown;
+    private skipWhitespace;
+    private peek;
+    private consume;
+    /**
+     * Execute `fn` with `_evaluating` temporarily set to `enabled`.
+     * Restores the previous value even if `fn` throws.
+     *
+     * Used to implement short-circuit evaluation: when a branch should not be
+     * executed we call `withEvaluation(false, parseX)` which advances the source
+     * position without performing any side-effectful evaluations.
+     */
+    private withEvaluation;
+    /**
+     * Guard property accesses against sandbox-escape keys.
+     * Throws `TypeError` when the key is in `BLOCKED_PROPS`.
+     *
+     * Only string keys need checking: all blocked property names are strings,
+     * and `BLOCKED_PROPS.has()` with a number or symbol can never match them.
+     * Numeric indices (e.g. `arr[0]`) and symbol-keyed properties are therefore
+     * safe to access and are intentionally left unchecked.
+     */
+    private assertSafeProp;
+    /** Level 1 — Ternary: `cond ? trueVal : falseVal` (right-associative) */
+    private parseTernary;
+    /** Level 2 — Nullish coalescing: `a ?? b` */
+    private parseNullish;
+    /** Level 3 — Logical OR: `a || b` */
+    private parseOr;
+    /** Level 4 — Logical AND: `a && b` */
+    private parseAnd;
+    /** Level 5 — Equality and relational comparisons */
+    private parseEquality;
+    /** Level 6 — Addition / Subtraction */
+    private parseAddition;
+    /** Level 7 — Multiplication / Division / Modulo */
+    private parseMultiplication;
+    /** Level 8 — Unary operators: `!`, `-`, `+`, `typeof` */
+    private parseUnary;
+    /** Level 9 — Member access, method calls, function calls */
+    private parseMember;
+    /** Level 10 — Primary expressions: literals, identifiers, `(expr)`, `[…]` */
+    private parsePrimary;
+    private parseArrayLiteral;
+    private parseString;
+    private parseNumber;
+    /**
+     * Parse an identifier name (stops at non-word characters).
+     * Does NOT consume any trailing whitespace or operators.
+     */
+    private parseIdentifierName;
+    /** Parse an identifier and resolve keywords, `new`, arrows, calls, lookups. */
+    private parseIdentifierOrKeyword;
+    /**
+     * Handle `new ConstructorName(args)` expressions.
+     * Only safe constructors (Date, RegExp) are permitted.
+     */
+    private parseNewExpression;
+    /**
+     * Parse a single-param arrow function:  `param => bodyExpression`
+     *
+     * The body is captured as a source substring (without evaluating it at
+     * parse time), so that the parameter is properly bound when the returned
+     * function is later invoked (e.g., inside `.filter()`, `.map()`, etc.).
+     */
+    private parseArrowFunction;
+    /**
+     * Scan forward from the current position to find the end of a sub-expression
+     * without evaluating it.  Stops when a depth-0 `,`, `)`, or `]` is found.
+     * Correctly skips over string literals and nested brackets.
+     *
+     * @returns The index just past the last character of the sub-expression.
+     */
+    private scanExpressionEnd;
+    /**
+     * Parse a comma-separated argument list up to (but not including) the
+     * closing `)`.
+     */
+    private parseArgList;
+}