@object-ui/core 0.5.0 → 2.0.0

package/dist/actions/TransactionManager.d.ts

@@ -0,0 +1,193 @@
+/**
+ * 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 - Transaction Manager
+ *
+ * Provides transaction wrapper for multi-step operations via @objectstack/client.
+ * Supports optimistic UI updates with rollback on failure and batch operation
+ * progress tracking with connection-aware retry.
+ *
+ * @module actions
+ * @packageDocumentation
+ */
+import type { DataSource, TransactionConfig, TransactionResult, ActionResult, UIActionSchema } from '@object-ui/types';
+/**
+ * Operation within a transaction (recorded for rollback)
+ */
+export interface TransactionOperation {
+    /** Operation type */
+    type: 'create' | 'update' | 'delete';
+    /** Target resource name */
+    resource: string;
+    /** Record ID (for update/delete) */
+    id?: string | number;
+    /** Data payload */
+    data?: Record<string, any>;
+    /** Previous state (for rollback) */
+    previousState?: Record<string, any>;
+    /** Result of the operation */
+    result?: any;
+}
+/**
+ * Optimistic update entry for UI state management
+ */
+export interface OptimisticUpdate {
+    /** Unique update ID */
+    id: string;
+    /** Operation type */
+    type: 'create' | 'update' | 'delete';
+    /** Target resource */
+    resource: string;
+    /** Record ID */
+    recordId?: string | number;
+    /** Optimistic data to display */
+    optimisticData: Record<string, any>;
+    /** Previous data (for rollback) */
+    previousData?: Record<string, any>;
+    /** Whether the update has been confirmed by server */
+    confirmed: boolean;
+    /** Whether the update was rolled back */
+    rolledBack: boolean;
+}
+/**
+ * Progress event for batch transaction operations
+ */
+export interface TransactionProgressEvent {
+    /** Transaction name */
+    transactionName: string;
+    /** Total operations to execute */
+    total: number;
+    /** Completed operations */
+    completed: number;
+    /** Failed operations */
+    failed: number;
+    /** Progress percentage (0-100) */
+    percentage: number;
+    /** Current operation description */
+    currentOperation?: string;
+}
+/**
+ * Progress callback type
+ */
+export type TransactionProgressCallback = (event: TransactionProgressEvent) => void;
+/**
+ * Transaction manager for executing multi-step operations with rollback support
+ */
+export declare class TransactionManager {
+    private dataSource;
+    private operations;
+    private optimisticUpdates;
+    private progressListeners;
+    private maxRetries;
+    private retryDelay;
+    constructor(dataSource: DataSource, options?: {
+        maxRetries?: number;
+        retryDelay?: number;
+    });
+    /**
+     * Register a progress listener
+     */
+    onProgress(listener: TransactionProgressCallback): () => void;
+    /**
+     * Execute a set of operations within a logical transaction.
+     * If any operation fails, previously completed operations are rolled back.
+     *
+     * @example
+     * ```ts
+     * const result = await manager.executeTransaction({
+     *   name: 'Create Order',
+     *   actions: [createOrderAction, updateInventoryAction, sendNotificationAction],
+     *   retryOnConflict: true,
+     *   maxRetries: 3,
+     * }, actionExecutor);
+     * ```
+     */
+    executeTransaction(config: TransactionConfig, actionExecutor: (action: UIActionSchema) => Promise<ActionResult>): Promise<TransactionResult>;
+    /**
+     * Apply an optimistic update to the UI and return a handle for confirmation/rollback.
+     *
+     * @example
+     * ```ts
+     * const update = manager.applyOptimisticUpdate({
+     *   type: 'update',
+     *   resource: 'orders',
+     *   recordId: '123',
+     *   optimisticData: { status: 'completed' },
+     *   previousData: { status: 'pending' },
+     * });
+     *
+     * try {
+     *   await dataSource.update('orders', '123', { status: 'completed' });
+     *   manager.confirmOptimisticUpdate(update.id);
+     * } catch (error) {
+     *   manager.rollbackOptimisticUpdate(update.id);
+     * }
+     * ```
+     */
+    applyOptimisticUpdate(params: {
+        type: 'create' | 'update' | 'delete';
+        resource: string;
+        recordId?: string | number;
+        optimisticData: Record<string, any>;
+        previousData?: Record<string, any>;
+    }): OptimisticUpdate;
+    /**
+     * Confirm an optimistic update (server operation succeeded)
+     */
+    confirmOptimisticUpdate(updateId: string): boolean;
+    /**
+     * Rollback an optimistic update (server operation failed)
+     * Returns the previous data that should be restored in the UI.
+     */
+    rollbackOptimisticUpdate(updateId: string): Record<string, any> | undefined;
+    /**
+     * Get all pending (unconfirmed, non-rolled-back) optimistic updates
+     */
+    getPendingUpdates(): OptimisticUpdate[];
+    /**
+     * Clear all optimistic updates
+     */
+    clearOptimisticUpdates(): void;
+    /**
+     * Execute a batch of data operations with progress tracking and retry.
+     *
+     * @example
+     * ```ts
+     * const results = await manager.executeBatch('orders', 'update', items, {
+     *   onProgress: (event) => console.log(`${event.percentage}% complete`),
+     * });
+     * ```
+     */
+    executeBatch<T = any>(resource: string, operation: 'create' | 'update' | 'delete', items: Partial<T>[], options?: {
+        onProgress?: TransactionProgressCallback;
+        retryOnError?: boolean;
+        maxRetries?: number;
+    }): Promise<{
+        success: boolean;
+        results: T[];
+        errors: Array<{
+            index: number;
+            error: string;
+        }>;
+        total: number;
+        succeeded: number;
+        failed: number;
+    }>;
+    /**
+     * Record an operation for potential rollback
+     */
+    recordOperation(op: TransactionOperation): void;
+    /**
+     * Rollback all recorded operations in reverse order
+     */
+    private rollbackOperations;
+    /**
+     * Emit progress event to all listeners
+     */
+    private emitProgress;
+}

package/dist/actions/TransactionManager.js

@@ -0,0 +1,410 @@
+/**
+ * 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.
+ */
+/**
+ * Transaction manager for executing multi-step operations with rollback support
+ */
+export class TransactionManager {
+    constructor(dataSource, options) {
+        Object.defineProperty(this, "dataSource", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "operations", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: []
+        });
+        Object.defineProperty(this, "optimisticUpdates", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Map()
+        });
+        Object.defineProperty(this, "progressListeners", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: []
+        });
+        Object.defineProperty(this, "maxRetries", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "retryDelay", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.dataSource = dataSource;
+        this.maxRetries = options?.maxRetries ?? 3;
+        this.retryDelay = options?.retryDelay ?? 1000;
+    }
+    /**
+     * Register a progress listener
+     */
+    onProgress(listener) {
+        this.progressListeners.push(listener);
+        return () => {
+            const idx = this.progressListeners.indexOf(listener);
+            if (idx > -1)
+                this.progressListeners.splice(idx, 1);
+        };
+    }
+    /**
+     * Execute a set of operations within a logical transaction.
+     * If any operation fails, previously completed operations are rolled back.
+     *
+     * @example
+     * ```ts
+     * const result = await manager.executeTransaction({
+     *   name: 'Create Order',
+     *   actions: [createOrderAction, updateInventoryAction, sendNotificationAction],
+     *   retryOnConflict: true,
+     *   maxRetries: 3,
+     * }, actionExecutor);
+     * ```
+     */
+    async executeTransaction(config, actionExecutor) {
+        const transactionId = generateId();
+        const actions = config.actions || [];
+        const maxRetries = config.maxRetries ?? this.maxRetries;
+        const actionResults = [];
+        this.operations = [];
+        let completed = 0;
+        let failed = 0;
+        const emitProgress = (currentOp) => {
+            this.emitProgress({
+                transactionName: config.name || transactionId,
+                total: actions.length,
+                completed,
+                failed,
+                percentage: actions.length > 0 ? ((completed + failed) / actions.length) * 100 : 0,
+                currentOperation: currentOp,
+            });
+        };
+        try {
+            for (const action of actions) {
+                emitProgress(action.label || action.name);
+                let result;
+                let lastError;
+                // Retry loop for conflict handling
+                for (let attempt = 0; attempt <= maxRetries; attempt++) {
+                    try {
+                        result = await actionExecutor(action);
+                        if (result.success) {
+                            break;
+                        }
+                        else {
+                            lastError = result.error;
+                            // Only retry on conflict if enabled
+                            if (config.retryOnConflict && attempt < maxRetries) {
+                                await delay(this.retryDelay * Math.pow(2, attempt));
+                                continue;
+                            }
+                            break;
+                        }
+                    }
+                    catch (error) {
+                        lastError = error.message;
+                        if (config.retryOnConflict && attempt < maxRetries) {
+                            await delay(this.retryDelay * Math.pow(2, attempt));
+                            continue;
+                        }
+                        result = { success: false, error: lastError };
+                        break;
+                    }
+                }
+                if (!result) {
+                    result = { success: false, error: lastError || 'Unknown error' };
+                }
+                actionResults.push(result);
+                if (result.success) {
+                    completed++;
+                    emitProgress();
+                }
+                else {
+                    failed++;
+                    emitProgress();
+                    // Transaction failed - rollback previous operations
+                    await this.rollbackOperations();
+                    return {
+                        success: false,
+                        transactionId,
+                        actionResults,
+                        error: result.error || `Action "${action.name}" failed`,
+                        rolledBack: true,
+                    };
+                }
+            }
+            return {
+                success: true,
+                transactionId,
+                actionResults,
+            };
+        }
+        catch (error) {
+            await this.rollbackOperations();
+            return {
+                success: false,
+                transactionId,
+                actionResults,
+                error: error.message,
+                rolledBack: true,
+            };
+        }
+    }
+    /**
+     * Apply an optimistic update to the UI and return a handle for confirmation/rollback.
+     *
+     * @example
+     * ```ts
+     * const update = manager.applyOptimisticUpdate({
+     *   type: 'update',
+     *   resource: 'orders',
+     *   recordId: '123',
+     *   optimisticData: { status: 'completed' },
+     *   previousData: { status: 'pending' },
+     * });
+     *
+     * try {
+     *   await dataSource.update('orders', '123', { status: 'completed' });
+     *   manager.confirmOptimisticUpdate(update.id);
+     * } catch (error) {
+     *   manager.rollbackOptimisticUpdate(update.id);
+     * }
+     * ```
+     */
+    applyOptimisticUpdate(params) {
+        const update = {
+            id: generateId(),
+            type: params.type,
+            resource: params.resource,
+            recordId: params.recordId,
+            optimisticData: params.optimisticData,
+            previousData: params.previousData,
+            confirmed: false,
+            rolledBack: false,
+        };
+        this.optimisticUpdates.set(update.id, update);
+        return update;
+    }
+    /**
+     * Confirm an optimistic update (server operation succeeded)
+     */
+    confirmOptimisticUpdate(updateId) {
+        const update = this.optimisticUpdates.get(updateId);
+        if (!update)
+            return false;
+        update.confirmed = true;
+        return true;
+    }
+    /**
+     * Rollback an optimistic update (server operation failed)
+     * Returns the previous data that should be restored in the UI.
+     */
+    rollbackOptimisticUpdate(updateId) {
+        const update = this.optimisticUpdates.get(updateId);
+        if (!update)
+            return undefined;
+        update.rolledBack = true;
+        return update.previousData;
+    }
+    /**
+     * Get all pending (unconfirmed, non-rolled-back) optimistic updates
+     */
+    getPendingUpdates() {
+        return Array.from(this.optimisticUpdates.values()).filter(u => !u.confirmed && !u.rolledBack);
+    }
+    /**
+     * Clear all optimistic updates
+     */
+    clearOptimisticUpdates() {
+        this.optimisticUpdates.clear();
+    }
+    /**
+     * Execute a batch of data operations with progress tracking and retry.
+     *
+     * @example
+     * ```ts
+     * const results = await manager.executeBatch('orders', 'update', items, {
+     *   onProgress: (event) => console.log(`${event.percentage}% complete`),
+     * });
+     * ```
+     */
+    async executeBatch(resource, operation, items, options) {
+        const maxRetries = options?.maxRetries ?? this.maxRetries;
+        const retryOnError = options?.retryOnError ?? true;
+        const results = [];
+        const errors = [];
+        let completed = 0;
+        let failed = 0;
+        const emitProgress = (currentOp) => {
+            const event = {
+                transactionName: `batch-${operation}`,
+                total: items.length,
+                completed,
+                failed,
+                percentage: items.length > 0 ? ((completed + failed) / items.length) * 100 : 0,
+                currentOperation: currentOp,
+            };
+            this.emitProgress(event);
+            options?.onProgress?.(event);
+        };
+        // Try bulk operation first if available
+        if (this.dataSource.bulk) {
+            try {
+                const bulkResult = await this.dataSource.bulk(resource, operation, items);
+                return {
+                    success: true,
+                    results: bulkResult,
+                    errors: [],
+                    total: items.length,
+                    succeeded: items.length,
+                    failed: 0,
+                };
+            }
+            catch {
+                // Fall through to individual processing
+            }
+        }
+        // Individual processing with retry
+        for (let i = 0; i < items.length; i++) {
+            const item = items[i];
+            let lastError;
+            let success = false;
+            for (let attempt = 0; attempt <= (retryOnError ? maxRetries : 0); attempt++) {
+                try {
+                    let result;
+                    switch (operation) {
+                        case 'create':
+                            result = await this.dataSource.create(resource, item);
+                            break;
+                        case 'update': {
+                            const id = item.id;
+                            if (!id)
+                                throw new Error(`Missing ID for item at index ${i}`);
+                            result = await this.dataSource.update(resource, id, item);
+                            break;
+                        }
+                        case 'delete': {
+                            const deleteId = item.id;
+                            if (!deleteId)
+                                throw new Error(`Missing ID for item at index ${i}`);
+                            await this.dataSource.delete(resource, deleteId);
+                            result = item;
+                            break;
+                        }
+                    }
+                    results.push(result);
+                    completed++;
+                    success = true;
+                    emitProgress();
+                    break;
+                }
+                catch (error) {
+                    lastError = error.message;
+                    if (retryOnError && attempt < maxRetries) {
+                        await delay(this.retryDelay * Math.pow(2, attempt));
+                        continue;
+                    }
+                }
+            }
+            if (!success) {
+                errors.push({ index: i, error: lastError || 'Unknown error' });
+                failed++;
+                emitProgress();
+            }
+        }
+        return {
+            success: errors.length === 0,
+            results,
+            errors,
+            total: items.length,
+            succeeded: completed,
+            failed,
+        };
+    }
+    /**
+     * Record an operation for potential rollback
+     */
+    recordOperation(op) {
+        this.operations.push(op);
+    }
+    /**
+     * Rollback all recorded operations in reverse order
+     */
+    async rollbackOperations() {
+        const ops = [...this.operations].reverse();
+        for (const op of ops) {
+            try {
+                switch (op.type) {
+                    case 'create':
+                        // Undo create -> delete the created record
+                        if (op.result?.id) {
+                            await this.dataSource.delete(op.resource, op.result.id);
+                        }
+                        break;
+                    case 'update':
+                        // Undo update -> restore previous state
+                        if (op.id && op.previousState) {
+                            await this.dataSource.update(op.resource, op.id, op.previousState);
+                        }
+                        break;
+                    case 'delete':
+                        // Undo delete -> re-create with previous state
+                        if (op.previousState) {
+                            await this.dataSource.create(op.resource, op.previousState);
+                        }
+                        break;
+                }
+            }
+            catch (error) {
+                // Rollback errors are logged but don't throw
+                console.error(`Rollback failed for ${op.type} on ${op.resource}:`, error);
+            }
+        }
+        this.operations = [];
+    }
+    /**
+     * Emit progress event to all listeners
+     */
+    emitProgress(event) {
+        for (const listener of this.progressListeners) {
+            try {
+                listener(event);
+            }
+            catch (error) {
+                console.error('Error in transaction progress listener:', error);
+            }
+        }
+    }
+}
+// ==========================================================================
+// Helpers
+// ==========================================================================
+/**
+ * Generate a unique transaction ID using crypto when available
+ */
+function generateId() {
+    if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') {
+        return `txn_${crypto.randomUUID()}`;
+    }
+    return `txn_${Date.now()}_${Math.random().toString(36).slice(2, 10)}`;
+}
+/**
+ * Promise-based delay
+ */
+function delay(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}

package/dist/actions/index.d.ts

@@ -6,3 +6,4 @@
  * LICENSE file in the root directory of this source tree.
  */
 export * from './ActionRunner.js';
+export * from './TransactionManager.js';

package/dist/actions/index.js

@@ -6,3 +6,4 @@
  * LICENSE file in the root directory of this source tree.
  */
 export * from './ActionRunner.js';
+export * from './TransactionManager.js';

package/dist/adapters/ApiDataSource.d.ts

@@ -0,0 +1,69 @@
+/**
+ * ObjectUI — ApiDataSource
+ * 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.
+ *
+ * A DataSource adapter for the `provider: 'api'` ViewData mode.
+ * Makes raw HTTP requests using the HttpRequest configs from ViewData.
+ */
+import type { DataSource, QueryParams, QueryResult, HttpRequest } from '@object-ui/types';
+export interface ApiDataSourceConfig {
+    /** HttpRequest config for read operations (find, findOne) */
+    read?: HttpRequest;
+    /** HttpRequest config for write operations (create, update, delete) */
+    write?: HttpRequest;
+    /** Custom fetch implementation (defaults to globalThis.fetch) */
+    fetch?: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+    /** Default headers applied to all requests */
+    defaultHeaders?: Record<string, string>;
+}
+/**
+ * ApiDataSource — a DataSource adapter for raw HTTP APIs.
+ *
+ * Used when `ViewData.provider === 'api'`. The read and write HttpRequest
+ * configs define the endpoints; all CRUD methods map onto HTTP verbs.
+ *
+ * Read operations use the `read` config, write operations use the `write` config.
+ * Both fall back to each other when one is not provided.
+ *
+ * @example
+ * ```ts
+ * const ds = new ApiDataSource({
+ *   read:  { url: '/api/contacts', method: 'GET' },
+ *   write: { url: '/api/contacts', method: 'POST' },
+ * });
+ *
+ * const result = await ds.find('contacts', { $top: 10 });
+ * ```
+ */
+export declare class ApiDataSource<T = any> implements DataSource<T> {
+    private readConfig;
+    private writeConfig;
+    private fetchFn;
+    private defaultHeaders;
+    constructor(config: ApiDataSourceConfig);
+    private request;
+    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>;
+    update(_resource: string, id: string | number, data: Partial<T>): Promise<T>;
+    delete(_resource: string, id: string | number): Promise<boolean>;
+    getObjectSchema(_objectName: string): Promise<any>;
+    getView(_objectName: string, _viewId: string): Promise<any | null>;
+    getApp(_appId: string): Promise<any | null>;
+    /**
+     * Normalize various API response shapes into a QueryResult.
+     *
+     * Supported shapes:
+     * - `T[]`                      → wrap in QueryResult
+     * - `{ data: T[] }`            → extract data
+     * - `{ items: T[] }`           → extract items
+     * - `{ results: T[] }`         → extract results
+     * - `{ records: T[] }`         → extract records (Salesforce-style)
+     * - `{ value: T[] }`           → extract value (OData-style)
+     * - Full QueryResult (has data + totalCount) → return as-is
+     */
+    private normalizeQueryResult;
+}