@object-ui/data-objectstack 0.3.1 → 2.0.0

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import { ObjectStackClient } from '@objectstack/client';
-import { DataSource, QueryParams, QueryResult } from '@object-ui/types';
+import { DataSource, QueryParams, QueryResult, FileUploadResult } from '@object-ui/types';
+export { FileUploadResult } from '@object-ui/types';
 
 /**
  * ObjectUI
@@ -8,6 +9,186 @@ import { DataSource, QueryParams, QueryResult } from '@object-ui/types';
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
+/**
+ * Base error class for all ObjectStack adapter errors
+ */
+declare class ObjectStackError extends Error {
+    code: string;
+    statusCode?: number | undefined;
+    details?: Record<string, unknown> | undefined;
+    /**
+     * Create a new ObjectStackError
+     *
+     * @param message - Human-readable error message
+     * @param code - Unique error code for programmatic handling
+     * @param statusCode - Optional HTTP status code
+     * @param details - Optional additional error details for debugging
+     */
+    constructor(message: string, code: string, statusCode?: number | undefined, details?: Record<string, unknown> | undefined);
+    /**
+     * Convert error to JSON for logging/debugging
+     */
+    toJSON(): {
+        name: string;
+        message: string;
+        code: string;
+        statusCode: number | undefined;
+        details: Record<string, unknown> | undefined;
+        stack: string | undefined;
+    };
+}
+/**
+ * Error thrown when requested metadata/schema is not found
+ */
+declare class MetadataNotFoundError extends ObjectStackError {
+    constructor(objectName: string, details?: Record<string, unknown>);
+}
+/**
+ * Error thrown when a bulk operation fails
+ */
+declare class BulkOperationError extends ObjectStackError {
+    successCount: number;
+    failureCount: number;
+    errors: Array<{
+        index: number;
+        error: unknown;
+    }>;
+    /**
+     * Create a new BulkOperationError
+     *
+     * @param operation - The bulk operation that failed (create, update, delete)
+     * @param successCount - Number of successful operations
+     * @param failureCount - Number of failed operations
+     * @param errors - Array of individual errors
+     * @param details - Additional error details
+     */
+    constructor(operation: 'create' | 'update' | 'delete', successCount: number, failureCount: number, errors: Array<{
+        index: number;
+        error: unknown;
+    }>, details?: Record<string, unknown>);
+    /**
+     * Get a summary of the bulk operation failure
+     */
+    getSummary(): {
+        operation: string;
+        total: number;
+        successful: number;
+        failed: number;
+        failureRate: number;
+        errors: {
+            index: number;
+            error: unknown;
+        }[];
+    };
+}
+/**
+ * Error thrown when connection to ObjectStack server fails
+ */
+declare class ConnectionError extends ObjectStackError {
+    url?: string | undefined;
+    constructor(message: string, url?: string | undefined, details?: Record<string, unknown>, statusCode?: number);
+}
+/**
+ * Error thrown when authentication fails
+ */
+declare class AuthenticationError extends ObjectStackError {
+    constructor(message?: string, details?: Record<string, unknown>, statusCode?: number);
+}
+/**
+ * Error thrown when data validation fails
+ */
+declare class ValidationError extends ObjectStackError {
+    field?: string | undefined;
+    validationErrors?: Array<{
+        field: string;
+        message: string;
+    }> | undefined;
+    /**
+     * Create a new ValidationError
+     *
+     * @param message - Human-readable error message
+     * @param field - The field that failed validation (optional)
+     * @param validationErrors - Array of validation error details
+     * @param details - Additional error details
+     */
+    constructor(message: string, field?: string | undefined, validationErrors?: Array<{
+        field: string;
+        message: string;
+    }> | undefined, details?: Record<string, unknown>);
+    /**
+     * Get all validation errors as a formatted list
+     */
+    getValidationErrors(): {
+        field: string;
+        message: string;
+    }[];
+}
+/**
+ * Helper function to create an error from an HTTP response
+ *
+ * @param response - Response object or error from fetch/axios
+ * @param context - Additional context for debugging
+ * @returns Appropriate error instance
+ */
+declare function createErrorFromResponse(response: Record<string, unknown>, context?: string): ObjectStackError;
+/**
+ * Type guard to check if an error is an ObjectStackError
+ */
+declare function isObjectStackError(error: unknown): error is ObjectStackError;
+/**
+ * Type guard to check if an error is a specific ObjectStack error type
+ */
+declare function isErrorType<T extends ObjectStackError>(error: unknown, errorClass: new (...args: any[]) => T): error is T;
+
+/**
+ * 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 statistics for monitoring
+ */
+interface CacheStats {
+    size: number;
+    maxSize: number;
+    hits: number;
+    misses: number;
+    evictions: number;
+    hitRate: number;
+}
+
+/**
+ * Connection state for monitoring
+ */
+type ConnectionState = 'disconnected' | 'connecting' | 'connected' | 'reconnecting' | 'error';
+/**
+ * Connection state change event
+ */
+interface ConnectionStateEvent {
+    state: ConnectionState;
+    timestamp: number;
+    error?: Error;
+}
+/**
+ * Batch operation progress event
+ */
+interface BatchProgressEvent {
+    operation: 'create' | 'update' | 'delete';
+    total: number;
+    completed: number;
+    failed: number;
+    percentage: number;
+}
+/**
+ * Event listener type for connection state changes
+ */
+type ConnectionStateListener = (event: ConnectionStateEvent) => void;
+/**
+ * Event listener type for batch operation progress
+ */
+type BatchProgressListener = (event: BatchProgressEvent) => void;
 
 /**
  * ObjectStack Data Source Adapter
@@ -22,7 +203,14 @@ import { DataSource, QueryParams, QueryResult } from '@object-ui/types';
  *
  * const dataSource = new ObjectStackAdapter({
  *   baseUrl: 'https://api.example.com',
- *   token: 'your-api-token'
+ *   token: 'your-api-token',
+ *   autoReconnect: true,
+ *   maxReconnectAttempts: 5
+ * });
+ *
+ * // Monitor connection state
+ * dataSource.onConnectionStateChange((event) => {
+ *   console.log('Connection state:', event.state);
  * });
  *
  * const users = await dataSource.find('users', {
@@ -31,19 +219,64 @@ import { DataSource, QueryParams, QueryResult } from '@object-ui/types';
  * });
  * ```
  */
-declare class ObjectStackAdapter<T = any> implements DataSource<T> {
+declare class ObjectStackAdapter<T = unknown> implements DataSource<T> {
     private client;
     private connected;
+    private metadataCache;
+    private connectionState;
+    private connectionStateListeners;
+    private batchProgressListeners;
+    private autoReconnect;
+    private maxReconnectAttempts;
+    private reconnectDelay;
+    private reconnectAttempts;
+    private baseUrl;
+    private token?;
     constructor(config: {
         baseUrl: string;
         token?: string;
         fetch?: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+        cache?: {
+            maxSize?: number;
+            ttl?: number;
+        };
+        autoReconnect?: boolean;
+        maxReconnectAttempts?: number;
+        reconnectDelay?: number;
     });
     /**
      * Ensure the client is connected to the server.
      * Call this before making requests or it will auto-connect on first request.
      */
     connect(): Promise<void>;
+    /**
+     * Attempt to reconnect to the server with exponential backoff
+     */
+    private attemptReconnect;
+    /**
+     * Get the current connection state
+     */
+    getConnectionState(): ConnectionState;
+    /**
+     * Check if the adapter is currently connected
+     */
+    isConnected(): boolean;
+    /**
+     * Register a listener for connection state changes
+     */
+    onConnectionStateChange(listener: ConnectionStateListener): () => void;
+    /**
+     * Register a listener for batch operation progress
+     */
+    onBatchProgress(listener: BatchProgressListener): () => void;
+    /**
+     * Set connection state and notify listeners
+     */
+    private setConnectionState;
+    /**
+     * Emit batch progress event to listeners
+     */
+    private emitBatchProgress;
     /**
      * Find multiple records with query parameters.
      * Converts OData-style params to ObjectStack query options.
@@ -66,7 +299,13 @@ declare class ObjectStackAdapter<T = any> implements DataSource<T> {
      */
     delete(resource: string, id: string | number): Promise<boolean>;
     /**
-     * Bulk operations (optional implementation).
+     * Bulk operations with optimized batch processing and error handling.
+     * Emits progress events for tracking operation status.
+     *
+     * @param resource - Resource name
+     * @param operation - Operation type (create, update, delete)
+     * @param data - Array of records to process
+     * @returns Promise resolving to array of results
      */
     bulk(resource: string, operation: 'create' | 'update' | 'delete', data: Partial<T>[]): Promise<T[]>;
     /**
@@ -76,15 +315,95 @@ declare class ObjectStackAdapter<T = any> implements DataSource<T> {
     private convertQueryParams;
     /**
      * Get object schema/metadata from ObjectStack.
+     * Uses caching to improve performance for repeated requests.
      *
      * @param objectName - Object name
      * @returns Promise resolving to the object schema
      */
-    getObjectSchema(objectName: string): Promise<any>;
+    getObjectSchema(objectName: string): Promise<unknown>;
     /**
      * Get access to the underlying ObjectStack client for advanced operations.
      */
     getClient(): ObjectStackClient;
+    /**
+     * Get the discovery information from the connected server.
+     * Returns the capabilities and service status of the ObjectStack server.
+     *
+     * Note: This accesses an internal property of the ObjectStackClient.
+     * The discovery data is populated during client.connect() and cached.
+     *
+     * @returns Promise resolving to discovery data, or null if not connected
+     */
+    getDiscovery(): Promise<unknown | null>;
+    /**
+     * Get a view definition for an object.
+     * Attempts to fetch from the server metadata API.
+     * Falls back to null if the server doesn't provide view definitions,
+     * allowing the consumer to use static config.
+     *
+     * @param objectName - Object name
+     * @param viewId - View identifier
+     * @returns Promise resolving to the view definition or null
+     */
+    getView(objectName: string, viewId: string): Promise<unknown | null>;
+    /**
+     * Get an application definition by name or ID.
+     * Attempts to fetch from the server metadata API.
+     * Falls back to null if the server doesn't provide app definitions,
+     * allowing the consumer to use static config.
+     *
+     * @param appId - Application identifier
+     * @returns Promise resolving to the app definition or null
+     */
+    getApp(appId: string): Promise<unknown | null>;
+    /**
+     * Get cache statistics for monitoring performance.
+     */
+    getCacheStats(): CacheStats;
+    /**
+     * Invalidate metadata cache entries.
+     *
+     * @param key - Optional key to invalidate. If omitted, invalidates all entries.
+     */
+    invalidateCache(key?: string): void;
+    /**
+     * Clear all cache entries and statistics.
+     */
+    clearCache(): void;
+    /**
+     * Upload a single file to a resource.
+     * Posts the file as multipart/form-data to the ObjectStack server.
+     *
+     * @param resource - The resource/object name to attach the file to
+     * @param file - File object or Blob to upload
+     * @param options - Additional upload options (recordId, fieldName, metadata)
+     * @returns Promise resolving to the upload result (file URL, metadata)
+     */
+    uploadFile(resource: string, file: File | Blob, options?: {
+        recordId?: string;
+        fieldName?: string;
+        metadata?: Record<string, unknown>;
+        onProgress?: (percent: number) => void;
+    }): Promise<FileUploadResult>;
+    /**
+     * Upload multiple files to a resource.
+     * Posts all files as a single multipart/form-data request.
+     *
+     * @param resource - The resource/object name to attach the files to
+     * @param files - Array of File objects or Blobs to upload
+     * @param options - Additional upload options
+     * @returns Promise resolving to array of upload results
+     */
+    uploadFiles(resource: string, files: (File | Blob)[], options?: {
+        recordId?: string;
+        fieldName?: string;
+        metadata?: Record<string, unknown>;
+        onProgress?: (percent: number) => void;
+    }): Promise<FileUploadResult[]>;
+    /**
+     * Get authorization headers from the adapter config.
+     */
+    private getAuthHeaders;
 }
 /**
  * Factory function to create an ObjectStack data source.
@@ -93,14 +412,24 @@ declare class ObjectStackAdapter<T = any> implements DataSource<T> {
  * ```typescript
  * const dataSource = createObjectStackAdapter({
  *   baseUrl: process.env.API_URL,
- *   token: process.env.API_TOKEN
+ *   token: process.env.API_TOKEN,
+ *   cache: { maxSize: 100, ttl: 300000 },
+ *   autoReconnect: true,
+ *   maxReconnectAttempts: 5
  * });
  * ```
  */
-declare function createObjectStackAdapter<T = any>(config: {
+declare function createObjectStackAdapter<T = unknown>(config: {
     baseUrl: string;
     token?: string;
     fetch?: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+    cache?: {
+        maxSize?: number;
+        ttl?: number;
+    };
+    autoReconnect?: boolean;
+    maxReconnectAttempts?: number;
+    reconnectDelay?: number;
 }): DataSource<T>;
 
-export { ObjectStackAdapter, createObjectStackAdapter };
+export { AuthenticationError, type BatchProgressEvent, type BatchProgressListener, BulkOperationError, type CacheStats, ConnectionError, type ConnectionState, type ConnectionStateEvent, type ConnectionStateListener, MetadataNotFoundError, ObjectStackAdapter, ObjectStackError, ValidationError, createErrorFromResponse, createObjectStackAdapter, isErrorType, isObjectStackError };