@object-ui/core 0.3.0 → 0.5.0

package/src/actions/ActionRunner.ts

@@ -0,0 +1,195 @@
+/**
+ * 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 - Action Runner
+ * 
+ * Executes actions defined in ActionSchema and EventHandler.
+ */
+
+import { ExpressionEvaluator } from '../evaluator/ExpressionEvaluator';
+
+export interface ActionResult {
+  success: boolean;
+  data?: any;
+  error?: string;
+  reload?: boolean;
+  close?: boolean;
+  redirect?: string;
+}
+
+export interface ActionContext {
+  data?: Record<string, any>;
+  record?: any;
+  user?: any;
+  [key: string]: any;
+}
+
+export type ActionHandler = (
+  action: any,
+  context: ActionContext
+) => Promise<ActionResult> | ActionResult;
+
+export class ActionRunner {
+  private handlers = new Map<string, ActionHandler>();
+  private evaluator: ExpressionEvaluator;
+  private context: ActionContext;
+
+  constructor(context: ActionContext = {}) {
+    this.context = context;
+    this.evaluator = new ExpressionEvaluator(context);
+  }
+
+  registerHandler(actionName: string, handler: ActionHandler): void {
+    this.handlers.set(actionName, handler);
+  }
+
+  async execute(action: any): Promise<ActionResult> {
+    try {
+      if (action.condition) {
+        const shouldExecute = this.evaluator.evaluateCondition(action.condition);
+        if (!shouldExecute) {
+          return { success: false, error: 'Action condition not met' };
+        }
+      }
+
+      if (action.disabled) {
+        const isDisabled = typeof action.disabled === 'string'
+          ? this.evaluator.evaluateCondition(action.disabled)
+          : action.disabled;
+        
+        if (isDisabled) {
+          return { success: false, error: 'Action is disabled' };
+        }
+      }
+
+      if (action.type === 'action' || action.actionType) {
+        return await this.executeActionSchema(action);
+      } else if (action.type === 'navigation' || action.navigate) {
+        return await this.executeNavigation(action);
+      } else if (action.type === 'api' || action.api) {
+        return await this.executeAPI(action);
+      } else if (action.onClick) {
+        await action.onClick();
+        return { success: true };
+      }
+
+      return { success: false, error: 'Unknown action type' };
+    } catch (error) {
+      return { success: false, error: (error as Error).message };
+    }
+  }
+
+  private async executeActionSchema(action: any): Promise<ActionResult> {
+    const result: ActionResult = { success: true };
+
+    if (action.confirmText) {
+      const confirmed = await this.showConfirmation(action.confirmText);
+      if (!confirmed) {
+        return { success: false, error: 'Action cancelled by user' };
+      }
+    }
+
+    if (action.api) {
+      const apiResult = await this.executeAPI(action);
+      if (!apiResult.success) return apiResult;
+      result.data = apiResult.data;
+    }
+
+    if (action.onClick) {
+      await action.onClick();
+    }
+
+    result.reload = action.reload !== false;
+    result.close = action.close !== false;
+
+    if (action.redirect) {
+      result.redirect = this.evaluator.evaluate(action.redirect) as string;
+    }
+
+    return result;
+  }
+
+  /**
+   * Execute navigation action
+   */
+  private async executeNavigation(action: any): Promise<ActionResult> {
+    const nav = action.navigate || action;
+    const to = this.evaluator.evaluate(nav.to) as string;
+
+    // Validate URL to prevent javascript: or data: schemes
+    const isValidUrl = typeof to === 'string' && (
+      to.startsWith('http://') || 
+      to.startsWith('https://') || 
+      to.startsWith('/') || 
+      to.startsWith('./')
+    );
+
+    if (!isValidUrl) {
+      return {
+        success: false,
+        error: 'Invalid URL scheme. Only http://, https://, and relative URLs are allowed.'
+      };
+    }
+
+    if (nav.external) {
+      window.open(to, '_blank', 'noopener,noreferrer');
+    } else {
+      return { success: true, redirect: to };
+    }
+
+    return { success: true };
+  }
+
+  private async executeAPI(action: any): Promise<ActionResult> {
+    const apiConfig = action.api;
+    
+    if (typeof apiConfig === 'string') {
+      try {
+        const response = await fetch(apiConfig, {
+          method: action.method || 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify(this.context.data || {})
+        });
+
+        if (!response.ok) {
+          throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+        }
+
+        const data = await response.json();
+        return { success: true, data };
+      } catch (error) {
+        return { success: false, error: (error as Error).message };
+      }
+    }
+
+    return { success: false, error: 'Complex API configuration not yet implemented' };
+  }
+
+  private async showConfirmation(message: string): Promise<boolean> {
+    const evaluatedMessage = this.evaluator.evaluate(message) as string;
+    return window.confirm(evaluatedMessage);
+  }
+
+  updateContext(newContext: Partial<ActionContext>): void {
+    this.context = { ...this.context, ...newContext };
+    this.evaluator.updateContext(newContext);
+  }
+
+  getContext(): ActionContext {
+    return this.context;
+  }
+}
+
+export async function executeAction(
+  action: any,
+  context: ActionContext = {}
+): Promise<ActionResult> {
+  const runner = new ActionRunner(context);
+  return await runner.execute(action);
+}

package/src/actions/index.ts

@@ -0,0 +1,9 @@
+/**
+ * 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.
+ */
+
+export * from './ActionRunner.js';

package/src/adapters/README.md

@@ -0,0 +1,180 @@
+# Data Source Adapters
+
+This directory contains data source adapters that bridge various backend protocols with the ObjectUI DataSource interface.
+
+## ObjectStack Adapter
+
+The `ObjectStackAdapter` provides seamless integration with ObjectStack Protocol servers.
+
+### Features
+
+- ✅ Full CRUD operations (find, findOne, create, update, delete)
+- ✅ Bulk operations (createMany, updateMany, deleteMany)
+- ✅ Auto-discovery of server capabilities
+- ✅ Query parameter translation (OData-style → ObjectStack)
+- ✅ Proper error handling
+- ✅ TypeScript types
+
+### Usage
+
+```typescript
+import { createObjectStackAdapter } from '@object-ui/core';
+
+// Create the adapter
+const dataSource = createObjectStackAdapter({
+  baseUrl: 'https://api.example.com',
+  token: 'your-auth-token', // Optional
+});
+
+// Use it with ObjectUI components
+const schema = {
+  type: 'data-table',
+  dataSource,
+  resource: 'users',
+  columns: [
+    { header: 'Name', accessorKey: 'name' },
+    { header: 'Email', accessorKey: 'email' },
+  ]
+};
+```
+
+### Advanced Usage
+
+```typescript
+import { ObjectStackAdapter } from '@object-ui/core';
+
+const adapter = new ObjectStackAdapter({
+  baseUrl: 'https://api.example.com',
+  token: process.env.API_TOKEN,
+  fetch: customFetch // Optional: use custom fetch (e.g., Next.js fetch)
+});
+
+// Manually connect (optional, auto-connects on first request)
+await adapter.connect();
+
+// Query with filters (MongoDB-like operators)
+const result = await adapter.find('tasks', {
+  $filter: { 
+    status: 'active',
+    priority: { $gte: 2 }
+  },
+  $orderby: { createdAt: 'desc' },
+  $top: 20,
+  $skip: 0
+});
+
+// Access the underlying client for advanced operations
+const client = adapter.getClient();
+const metadata = await client.meta.getObject('task');
+```
+
+### Filter Conversion
+
+The adapter automatically converts MongoDB-like filter operators to **ObjectStack FilterNode AST format**. This ensures compatibility with the latest ObjectStack Protocol (v0.1.2+).
+
+#### Supported Filter Operators
+
+| MongoDB Operator | ObjectStack Operator | Example |
+|------------------|---------------------|---------|
+| `$eq` or simple value | `=` | `{ status: 'active' }` → `['status', '=', 'active']` |
+| `$ne` | `!=` | `{ status: { $ne: 'archived' } }` → `['status', '!=', 'archived']` |
+| `$gt` | `>` | `{ age: { $gt: 18 } }` → `['age', '>', 18]` |
+| `$gte` | `>=` | `{ age: { $gte: 18 } }` → `['age', '>=', 18]` |
+| `$lt` | `<` | `{ age: { $lt: 65 } }` → `['age', '<', 65]` |
+| `$lte` | `<=` | `{ age: { $lte: 65 } }` → `['age', '<=', 65]` |
+| `$in` | `in` | `{ status: { $in: ['active', 'pending'] } }` → `['status', 'in', ['active', 'pending']]` |
+| `$nin` / `$notin` | `notin` | `{ status: { $nin: ['archived'] } }` → `['status', 'notin', ['archived']]` |
+| `$contains` / `$regex` | `contains` | `{ name: { $contains: 'John' } }` → `['name', 'contains', 'John']` |
+| `$startswith` | `startswith` | `{ email: { $startswith: 'admin' } }` → `['email', 'startswith', 'admin']` |
+| `$between` | `between` | `{ age: { $between: [18, 65] } }` → `['age', 'between', [18, 65]]` |
+
+#### Complex Filter Examples
+
+**Multiple conditions** are combined with `'and'`:
+
+```typescript
+// Input
+$filter: {
+  age: { $gte: 18, $lte: 65 },
+  status: 'active'
+}
+
+// Converted to AST
+['and', 
+  ['age', '>=', 18],
+  ['age', '<=', 65],
+  ['status', '=', 'active']
+]
+```
+
+### Query Parameter Mapping
+
+The adapter automatically converts ObjectUI query parameters (OData-style) to ObjectStack protocol:
+
+| ObjectUI ($) | ObjectStack | Description |
+|--------------|-------------|-------------|
+| `$select` | `select` | Field selection |
+| `$filter` | `filters` (AST) | Filter conditions (converted to FilterNode AST) |
+| `$orderby` | `sort` | Sort order |
+| `$skip` | `skip` | Pagination offset |
+| `$top` | `top` | Limit records |
+
+### Example with Sorting
+
+```typescript
+// OData-style
+await dataSource.find('users', {
+  $orderby: { 
+    createdAt: 'desc',
+    name: 'asc'
+  }
+});
+
+// Converted to ObjectStack: ['-createdAt', 'name']
+```
+
+## Creating Custom Adapters
+
+To create a custom adapter, implement the `DataSource<T>` interface:
+
+```typescript
+import type { DataSource, QueryParams, QueryResult } from '@object-ui/types';
+
+export class MyCustomAdapter<T = any> implements DataSource<T> {
+  async find(resource: string, params?: QueryParams): Promise<QueryResult<T>> {
+    // Your implementation
+  }
+  
+  async findOne(resource: string, id: string | number): Promise<T | null> {
+    // Your implementation
+  }
+  
+  async create(resource: string, data: Partial<T>): Promise<T> {
+    // Your implementation
+  }
+  
+  async update(resource: string, id: string | number, data: Partial<T>): Promise<T> {
+    // Your implementation
+  }
+  
+  async delete(resource: string, id: string | number): Promise<boolean> {
+    // Your implementation
+  }
+  
+  // Optional: bulk operations
+  async bulk?(resource: string, operation: string, data: Partial<T>[]): Promise<T[]> {
+    // Your implementation
+  }
+}
+```
+
+## Available Adapters
+
+- **ObjectStackAdapter** - For ObjectStack Protocol servers
+- More adapters coming soon (REST, GraphQL, Supabase, Firebase, etc.)
+
+## Related Packages
+
+- `@objectstack/client` - ObjectStack Client SDK
+- `@objectstack/spec` - ObjectStack Protocol Specification
+- `@object-ui/types` - ObjectUI Type Definitions

package/src/adapters/index.ts

@@ -0,0 +1,10 @@
+/**
+ * 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.
+ */
+
+// export { ObjectStackAdapter, createObjectStackAdapter } from './objectstack-adapter';
+// Adapters have been moved to separate packages (e.g. @object-ui/data-objectstack)

package/src/builder/schema-builder.ts

@@ -1,3 +1,11 @@
+/**
+ * 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 - Schema Builder
  * 

package/src/evaluator/ExpressionCache.ts

@@ -0,0 +1,192 @@
+/**
+ * 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 class ExpressionCache {
+  private cache = new Map<string, ExpressionMetadata>();
+  private maxSize: number;
+  
+  /**
+   * Create a new expression cache
+   * 
+   * @param maxSize Maximum number of expressions to cache (default: 1000)
+   */
+  constructor(maxSize = 1000) {
+    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: string, varNames: string[]): ExpressionMetadata {
+    // 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: ExpressionMetadata = {
+      fn,
+      varNames: [...varNames],
+      expression: expr,
+      compiledAt: Date.now(),
+      hitCount: 1,
+    };
+    
+    this.cache.set(cacheKey, metadata);
+    return metadata;
+  }
+  
+  /**
+   * Compile an expression into a function
+   */
+  private compileExpression(expression: string, varNames: string[]): CompiledExpression {
+    // 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});`) as CompiledExpression;
+  }
+  
+  /**
+   * Evict the least frequently used expression from cache
+   */
+  private evictLFU(): void {
+    let oldestKey: string | null = 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: string, varNames: string[]): boolean {
+    const cacheKey = `${expr}::${varNames.join(',')}`;
+    return this.cache.has(cacheKey);
+  }
+  
+  /**
+   * Clear the cache
+   */
+  clear(): void {
+    this.cache.clear();
+  }
+  
+  /**
+   * Get cache statistics
+   */
+  getStats(): {
+    size: number;
+    maxSize: number;
+    totalHits: number;
+    entries: Array<{ expression: string; hitCount: number }>;
+  } {
+    let totalHits = 0;
+    const entries: Array<{ expression: string; hitCount: number }> = [];
+    
+    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),
+    };
+  }
+}