@object-ui/data-objectstack 0.3.0 → 0.5.0

package/dist/index.d.cts

@@ -8,7 +8,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 +201,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 +217,62 @@ 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;
     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 +295,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 +311,30 @@ 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 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;
 }
 /**
  * Factory function to create an ObjectStack data source.
@@ -93,14 +343,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 };

package/dist/index.d.ts

@@ -8,7 +8,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 +201,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 +217,62 @@ 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;
     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 +295,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 +311,30 @@ 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 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;
 }
 /**
  * Factory function to create an ObjectStack data source.
@@ -93,14 +343,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 };