@object-ui/data-objectstack 0.3.1 → 2.0.0

package/src/index.ts

@@ -7,8 +7,54 @@
  */
 
 import { ObjectStackClient, type QueryOptions as ObjectStackQueryOptions } from '@objectstack/client';
-import type { DataSource, QueryParams, QueryResult } from '@object-ui/types';
+import type { DataSource, QueryParams, QueryResult, FileUploadResult } from '@object-ui/types';
 import { convertFiltersToAST } from '@object-ui/core';
+import { MetadataCache } from './cache/MetadataCache';
+import {
+  ObjectStackError,
+  MetadataNotFoundError,
+  BulkOperationError,
+  ConnectionError,
+  createErrorFromResponse,
+} from './errors';
+
+/**
+ * Connection state for monitoring
+ */
+export type ConnectionState = 'disconnected' | 'connecting' | 'connected' | 'reconnecting' | 'error';
+
+/**
+ * Connection state change event
+ */
+export interface ConnectionStateEvent {
+  state: ConnectionState;
+  timestamp: number;
+  error?: Error;
+}
+
+/**
+ * Batch operation progress event
+ */
+export interface BatchProgressEvent {
+  operation: 'create' | 'update' | 'delete';
+  total: number;
+  completed: number;
+  failed: number;
+  percentage: number;
+}
+
+/**
+ * Event listener type for connection state changes
+ */
+export type ConnectionStateListener = (event: ConnectionStateEvent) => void;
+
+/**
+ * Event listener type for batch operation progress
+ */
+export type BatchProgressListener = (event: BatchProgressEvent) => void;
+
+// Re-export FileUploadResult from types for consumers
+export type { FileUploadResult } from '@object-ui/types';
 
 /**
  * ObjectStack Data Source Adapter
@@ -23,7 +69,14 @@ import { convertFiltersToAST } from '@object-ui/core';
  * 
  * 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', {
@@ -32,16 +85,39 @@ import { convertFiltersToAST } from '@object-ui/core';
  * });
  * ```
  */
-export class ObjectStackAdapter<T = any> implements DataSource<T> {
+export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
   private client: ObjectStackClient;
   private connected: boolean = false;
+  private metadataCache: MetadataCache;
+  private connectionState: ConnectionState = 'disconnected';
+  private connectionStateListeners: ConnectionStateListener[] = [];
+  private batchProgressListeners: BatchProgressListener[] = [];
+  private autoReconnect: boolean;
+  private maxReconnectAttempts: number;
+  private reconnectDelay: number;
+  private reconnectAttempts: number = 0;
+  private baseUrl: string;
+  private token?: string;
 
   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;
   }) {
     this.client = new ObjectStackClient(config);
+    this.metadataCache = new MetadataCache(config.cache);
+    this.autoReconnect = config.autoReconnect ?? true;
+    this.maxReconnectAttempts = config.maxReconnectAttempts ?? 3;
+    this.reconnectDelay = config.reconnectDelay ?? 1000;
+    this.baseUrl = config.baseUrl;
+    this.token = config.token;
   }
 
   /**
@@ -50,11 +126,127 @@ export class ObjectStackAdapter<T = any> implements DataSource<T> {
    */
   async connect(): Promise<void> {
     if (!this.connected) {
-      await this.client.connect();
-      this.connected = true;
+      this.setConnectionState('connecting');
+      
+      try {
+        await this.client.connect();
+        this.connected = true;
+        this.reconnectAttempts = 0;
+        this.setConnectionState('connected');
+      } catch (error: unknown) {
+        const errorMessage = error instanceof Error ? error.message : 'Failed to connect to ObjectStack server';
+        const connectionError = new ConnectionError(
+          errorMessage,
+          undefined,
+          { originalError: error }
+        );
+        
+        this.setConnectionState('error', connectionError);
+        
+        // Attempt auto-reconnect if enabled
+        if (this.autoReconnect && this.reconnectAttempts < this.maxReconnectAttempts) {
+          await this.attemptReconnect();
+        } else {
+          throw connectionError;
+        }
+      }
     }
   }
 
+  /**
+   * Attempt to reconnect to the server with exponential backoff
+   */
+  private async attemptReconnect(): Promise<void> {
+    this.reconnectAttempts++;
+    this.setConnectionState('reconnecting');
+    
+    // Exponential backoff: delay * 2^(attempts-1)
+    const delay = this.reconnectDelay * Math.pow(2, this.reconnectAttempts - 1);
+    
+    await new Promise(resolve => setTimeout(resolve, delay));
+    
+    this.connected = false;
+    await this.connect();
+  }
+
+  /**
+   * Get the current connection state
+   */
+  getConnectionState(): ConnectionState {
+    return this.connectionState;
+  }
+
+  /**
+   * Check if the adapter is currently connected
+   */
+  isConnected(): boolean {
+    return this.connected && this.connectionState === 'connected';
+  }
+
+  /**
+   * Register a listener for connection state changes
+   */
+  onConnectionStateChange(listener: ConnectionStateListener): () => void {
+    this.connectionStateListeners.push(listener);
+    
+    // Return unsubscribe function
+    return () => {
+      const index = this.connectionStateListeners.indexOf(listener);
+      if (index > -1) {
+        this.connectionStateListeners.splice(index, 1);
+      }
+    };
+  }
+
+  /**
+   * Register a listener for batch operation progress
+   */
+  onBatchProgress(listener: BatchProgressListener): () => void {
+    this.batchProgressListeners.push(listener);
+    
+    // Return unsubscribe function
+    return () => {
+      const index = this.batchProgressListeners.indexOf(listener);
+      if (index > -1) {
+        this.batchProgressListeners.splice(index, 1);
+      }
+    };
+  }
+
+  /**
+   * Set connection state and notify listeners
+   */
+  private setConnectionState(state: ConnectionState, error?: Error): void {
+    this.connectionState = state;
+    
+    const event: ConnectionStateEvent = {
+      state,
+      timestamp: Date.now(),
+      error,
+    };
+    
+    this.connectionStateListeners.forEach(listener => {
+      try {
+        listener(event);
+      } catch (err) {
+        console.error('Error in connection state listener:', err);
+      }
+    });
+  }
+
+  /**
+   * Emit batch progress event to listeners
+   */
+  private emitBatchProgress(event: BatchProgressEvent): void {
+    this.batchProgressListeners.forEach(listener => {
+      try {
+        listener(event);
+      } catch (err) {
+        console.error('Error in batch progress listener:', err);
+      }
+    });
+  }
+
   /**
    * Find multiple records with query parameters.
    * Converts OData-style params to ObjectStack query options.
@@ -63,14 +255,27 @@ export class ObjectStackAdapter<T = any> implements DataSource<T> {
     await this.connect();
 
     const queryOptions = this.convertQueryParams(params);
-    const result = await this.client.data.find<T>(resource, queryOptions);
+    const result: unknown = await this.client.data.find<T>(resource, queryOptions);
+
+    // Handle legacy/raw array response (e.g. from some mock servers or non-OData endpoints)
+    if (Array.isArray(result)) {
+      return {
+        data: result,
+        total: result.length,
+        page: 1,
+        pageSize: result.length,
+        hasMore: false,
+      };
+    }
 
+    const resultObj = result as { value?: T[]; count?: number };
     return {
-      data: result.value,
-      total: result.count,
-      page: params?.$skip ? Math.floor(params.$skip / (params.$top || 20)) + 1 : 1,
+      data: resultObj.value || [],
+      total: resultObj.count || (resultObj.value ? resultObj.value.length : 0),
+      // Calculate page number safely
+      page: params?.$skip && params.$top ? Math.floor(params.$skip / params.$top) + 1 : 1,
       pageSize: params?.$top,
-      hasMore: result.value.length === params?.$top,
+      hasMore: params?.$top ? (resultObj.value?.length || 0) === params.$top : false,
     };
   }
 
@@ -81,11 +286,11 @@ export class ObjectStackAdapter<T = any> implements DataSource<T> {
     await this.connect();
 
     try {
-      const record = await this.client.data.get<T>(resource, String(id));
-      return record;
-    } catch (error) {
+      const result = await this.client.data.get<T>(resource, String(id));
+      return result.record;
+    } catch (error: unknown) {
       // If record not found, return null instead of throwing
-      if ((error as any)?.status === 404) {
+      if ((error as Record<string, unknown>)?.status === 404) {
         return null;
       }
       throw error;
@@ -97,7 +302,8 @@ export class ObjectStackAdapter<T = any> implements DataSource<T> {
    */
   async create(resource: string, data: Partial<T>): Promise<T> {
     await this.connect();
-    return this.client.data.create<T>(resource, data);
+    const result = await this.client.data.create<T>(resource, data);
+    return result.record;
   }
 
   /**
@@ -105,7 +311,8 @@ export class ObjectStackAdapter<T = any> implements DataSource<T> {
    */
   async update(resource: string, id: string | number, data: Partial<T>): Promise<T> {
     await this.connect();
-    return this.client.data.update<T>(resource, String(id), data);
+    const result = await this.client.data.update<T>(resource, String(id), data);
+    return result.record;
   }
 
   /**
@@ -114,35 +321,170 @@ export class ObjectStackAdapter<T = any> implements DataSource<T> {
   async delete(resource: string, id: string | number): Promise<boolean> {
     await this.connect();
     const result = await this.client.data.delete(resource, String(id));
-    return result.success;
+    return result.deleted;
   }
 
   /**
-   * 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
    */
   async bulk(resource: string, operation: 'create' | 'update' | 'delete', data: Partial<T>[]): Promise<T[]> {
     await this.connect();
 
-    switch (operation) {
-      case 'create':
-        return this.client.data.createMany<T>(resource, data);
-      case 'delete': {
-        const ids = data.map(item => (item as any).id).filter(Boolean);
-        await this.client.data.deleteMany(resource, ids);
-        return [];
+    if (!data || data.length === 0) {
+      return [];
+    }
+
+    const total = data.length;
+    let completed = 0;
+    let failed = 0;
+
+    const emitProgress = () => {
+      this.emitBatchProgress({
+        operation,
+        total,
+        completed,
+        failed,
+        percentage: total > 0 ? (completed + failed) / total * 100 : 0,
+      });
+    };
+
+    try {
+      switch (operation) {
+        case 'create': {
+          emitProgress();
+          const created = await this.client.data.createMany<T>(resource, data);
+          completed = created.length;
+          failed = total - completed;
+          emitProgress();
+          return created;
+        }
+        
+        case 'delete': {
+          const ids = data.map(item => (item as Record<string, unknown>).id).filter(Boolean) as string[];
+          
+          if (ids.length === 0) {
+            // Track which items are missing IDs
+            const errors = data.map((_, index) => ({
+              index,
+              error: `Missing ID for item at index ${index}`
+            }));
+            
+            failed = data.length;
+            emitProgress();
+            
+            throw new BulkOperationError('delete', 0, data.length, errors);
+          }
+          
+          emitProgress();
+          await this.client.data.deleteMany(resource, ids);
+          completed = ids.length;
+          failed = total - completed;
+          emitProgress();
+          return [] as T[];
+        }
+        
+        case 'update': {
+          // Check if client supports updateMany
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          if (typeof (this.client.data as any).updateMany === 'function') {
+            try {
+              emitProgress();
+              // eslint-disable-next-line @typescript-eslint/no-explicit-any
+              const updateMany = (this.client.data as any).updateMany;
+              const updated = await updateMany(resource, data) as T[];
+              completed = updated.length;
+              failed = total - completed;
+              emitProgress();
+              return updated;
+            } catch {
+              // If updateMany is not supported, fall back to individual updates
+              // Silently fallback without logging
+            }
+          }
+          
+          // Fallback: Process updates individually with detailed error tracking and progress
+          const results: T[] = [];
+          const errors: Array<{ index: number; error: unknown }> = [];
+          
+          for (let i = 0; i < data.length; i++) {
+            const item = data[i];
+            const id = (item as Record<string, unknown>).id;
+            
+            if (!id) {
+              errors.push({ index: i, error: 'Missing ID' });
+              failed++;
+              emitProgress();
+              continue;
+            }
+            
+            try {
+              const result = await this.client.data.update<T>(resource, String(id), item);
+              results.push(result.record);
+              completed++;
+              emitProgress();
+            } catch (error: unknown) {
+              const errorMessage = error instanceof Error ? error.message : String(error);
+              errors.push({ index: i, error: errorMessage });
+              failed++;
+              emitProgress();
+            }
+          }
+          
+          // If there were any errors, throw BulkOperationError
+          if (errors.length > 0) {
+            throw new BulkOperationError(
+              'update',
+              results.length,
+              errors.length,
+              errors,
+              { resource, totalRecords: data.length }
+            );
+          }
+          
+          return results;
+        }
+        
+        default:
+          throw new ObjectStackError(
+            `Unsupported bulk operation: ${operation}`,
+            'UNSUPPORTED_OPERATION',
+            400
+          );
       }
-      case 'update': {
-        // For update, we need to handle each record individually
-        // or use the batch update if all records get the same changes
-        const results = await Promise.all(
-          data.map(item => 
-            this.client.data.update<T>(resource, String((item as any).id), item)
-          )
-        );
-        return results;
+    } catch (error: unknown) {
+      // Emit final progress with failure
+      emitProgress();
+      
+      // If it's already a BulkOperationError, re-throw it
+      if (error instanceof BulkOperationError) {
+        throw error;
+      }
+      
+      // If it's already an ObjectStackError, re-throw it
+      if (error instanceof ObjectStackError) {
+        throw error;
       }
-      default:
-        throw new Error(`Unsupported bulk operation: ${operation}`);
+      
+      // Wrap other errors in BulkOperationError with proper error tracking
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      const errors = data.map((_, index) => ({
+        index,
+        error: errorMessage
+      }));
+      
+      throw new BulkOperationError(
+        operation,
+        0,
+        data.length,
+        errors,
+        { resource, originalError: error }
+      );
     }
   }
 
@@ -162,15 +504,32 @@ export class ObjectStackAdapter<T = any> implements DataSource<T> {
 
     // Filtering - convert to ObjectStack FilterNode AST format
     if (params.$filter) {
-      options.filters = convertFiltersToAST(params.$filter);
+      if (Array.isArray(params.$filter)) {
+        // Assume active AST format if it's already an array
+        options.filters = params.$filter;
+      } else {
+        options.filters = convertFiltersToAST(params.$filter);
+      }
     }
 
     // Sorting - convert to ObjectStack format
     if (params.$orderby) {
-      const sortArray = Object.entries(params.$orderby).map(([field, order]) => {
-        return order === 'desc' ? `-${field}` : field;
-      });
-      options.sort = sortArray;
+      if (Array.isArray(params.$orderby)) {
+        // Handle array format ['name', '-age'] or [{ field: 'name', order: 'asc' }]
+        options.sort = params.$orderby.map(item => {
+          if (typeof item === 'string') return item;
+          // Handle object format { field: 'name', order: 'desc' }
+          const field = item.field;
+          const order = item.order || 'asc';
+          return order === 'desc' ? `-${field}` : field;
+        });
+      } else {
+        // Handle Record format { name: 'asc', age: 'desc' }
+        const sortArray = Object.entries(params.$orderby).map(([field, order]) => {
+          return order === 'desc' ? `-${field}` : field;
+        });
+        options.sort = sortArray;
+      }
     }
 
     // Pagination
@@ -187,19 +546,41 @@ export class ObjectStackAdapter<T = any> implements DataSource<T> {
 
   /**
    * 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
    */
-  async getObjectSchema(objectName: string): Promise<any> {
+  async getObjectSchema(objectName: string): Promise<unknown> {
     await this.connect();
     
     try {
-      const schema = await this.client.meta.getObject(objectName);
+      // Use cache with automatic fetching
+      const schema = await this.metadataCache.get(objectName, async () => {
+        const result: any = await this.client.meta.getObject(objectName);
+        
+        // Unwrap 'item' property if present (common API response wrapper)
+        if (result && result.item) {
+          return result.item;
+        }
+
+        return result;
+      });
+      
       return schema;
-    } catch (error) {
-      console.error(`Failed to fetch schema for ${objectName}:`, error);
-      throw error;
+    } catch (error: unknown) {
+      // Check if it's a 404 error
+      const errorObj = error as Record<string, unknown>;
+      if (errorObj?.status === 404 || errorObj?.statusCode === 404) {
+        throw new MetadataNotFoundError(objectName, { originalError: error });
+      }
+      
+      // For other errors, wrap in ObjectStackError if not already
+      if (error instanceof ObjectStackError) {
+        throw error;
+      }
+      
+      throw createErrorFromResponse(errorObj, `getObjectSchema(${objectName})`);
     }
   }
 
@@ -209,6 +590,230 @@ export class ObjectStackAdapter<T = any> implements DataSource<T> {
   getClient(): ObjectStackClient {
     return this.client;
   }
+
+  /**
+   * 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
+   */
+  async getDiscovery(): Promise<unknown | null> {
+    try {
+      // Ensure we're connected first
+      await this.connect();
+      
+      // Access discovery data from the client
+      // The ObjectStackClient caches discovery during connect()
+      // This is an internal property, but documented for this use case
+      // @ts-expect-error - Accessing internal discoveryInfo property
+      return this.client.discoveryInfo || null;
+    } catch {
+      return 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
+   */
+  async getView(objectName: string, viewId: string): Promise<unknown | null> {
+    await this.connect();
+
+    try {
+      const cacheKey = `view:${objectName}:${viewId}`;
+      return await this.metadataCache.get(cacheKey, async () => {
+        // Try meta.getItem for view metadata
+        const result: any = await this.client.meta.getItem(objectName, `views/${viewId}`);
+        if (result && result.item) return result.item;
+        return result ?? null;
+      });
+    } catch {
+      // Server doesn't support view metadata — return null to fall back to static config
+      return 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
+   */
+  async getApp(appId: string): Promise<unknown | null> {
+    await this.connect();
+
+    try {
+      const cacheKey = `app:${appId}`;
+      return await this.metadataCache.get(cacheKey, async () => {
+        const result: any = await this.client.meta.getItem('apps', appId);
+        if (result && result.item) return result.item;
+        return result ?? null;
+      });
+    } catch {
+      // Server doesn't support app metadata — return null to fall back to static config
+      return null;
+    }
+  }
+
+  /**
+   * Get cache statistics for monitoring performance.
+   */
+  getCacheStats() {
+    return this.metadataCache.getStats();
+  }
+
+  /**
+   * Invalidate metadata cache entries.
+   * 
+   * @param key - Optional key to invalidate. If omitted, invalidates all entries.
+   */
+  invalidateCache(key?: string): void {
+    this.metadataCache.invalidate(key);
+  }
+
+  /**
+   * Clear all cache entries and statistics.
+   */
+  clearCache(): void {
+    this.metadataCache.clear();
+  }
+
+  /**
+   * 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)
+   */
+  async uploadFile(
+    resource: string,
+    file: File | Blob,
+    options?: {
+      recordId?: string;
+      fieldName?: string;
+      metadata?: Record<string, unknown>;
+      onProgress?: (percent: number) => void;
+    },
+  ): Promise<FileUploadResult> {
+    await this.connect();
+
+    const formData = new FormData();
+    formData.append('file', file);
+
+    if (options?.recordId) {
+      formData.append('recordId', options.recordId);
+    }
+    if (options?.fieldName) {
+      formData.append('fieldName', options.fieldName);
+    }
+    if (options?.metadata) {
+      formData.append('metadata', JSON.stringify(options.metadata));
+    }
+
+    const url = `${this.baseUrl}/api/data/${encodeURIComponent(resource)}/upload`;
+
+    const response = await fetch(url, {
+      method: 'POST',
+      body: formData,
+      headers: {
+        ...(this.getAuthHeaders()),
+      },
+    });
+
+    if (!response.ok) {
+      const error = await response.json().catch(() => ({ message: response.statusText }));
+      throw new ObjectStackError(
+        error.message || `Upload failed with status ${response.status}`,
+        'UPLOAD_ERROR',
+        response.status,
+      );
+    }
+
+    return response.json();
+  }
+
+  /**
+   * 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
+   */
+  async uploadFiles(
+    resource: string,
+    files: (File | Blob)[],
+    options?: {
+      recordId?: string;
+      fieldName?: string;
+      metadata?: Record<string, unknown>;
+      onProgress?: (percent: number) => void;
+    },
+  ): Promise<FileUploadResult[]> {
+    await this.connect();
+
+    const formData = new FormData();
+    files.forEach((file, idx) => {
+      formData.append(`files`, file, (file as File).name || `file-${idx}`);
+    });
+
+    if (options?.recordId) {
+      formData.append('recordId', options.recordId);
+    }
+    if (options?.fieldName) {
+      formData.append('fieldName', options.fieldName);
+    }
+    if (options?.metadata) {
+      formData.append('metadata', JSON.stringify(options.metadata));
+    }
+
+    const url = `${this.baseUrl}/api/data/${encodeURIComponent(resource)}/upload`;
+
+    const response = await fetch(url, {
+      method: 'POST',
+      body: formData,
+      headers: {
+        ...(this.getAuthHeaders()),
+      },
+    });
+
+    if (!response.ok) {
+      const error = await response.json().catch(() => ({ message: response.statusText }));
+      throw new ObjectStackError(
+        error.message || `Upload failed with status ${response.status}`,
+        'UPLOAD_ERROR',
+        response.status,
+      );
+    }
+
+    return response.json();
+  }
+
+  /**
+   * Get authorization headers from the adapter config.
+   */
+  private getAuthHeaders(): Record<string, string> {
+    const headers: Record<string, string> = {};
+    if (this.token) {
+      headers['Authorization'] = `Bearer ${this.token}`;
+    }
+    return headers;
+  }
 }
 
 /**
@@ -218,14 +823,40 @@ export 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
  * });
  * ```
  */
-export function createObjectStackAdapter<T = any>(config: {
+export 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> {
   return new ObjectStackAdapter<T>(config);
 }
+
+// Export error classes for error handling
+export {
+  ObjectStackError,
+  MetadataNotFoundError,
+  BulkOperationError,
+  ConnectionError,
+  AuthenticationError,
+  ValidationError,
+  createErrorFromResponse,
+  isObjectStackError,
+  isErrorType,
+} from './errors';
+
+// Export cache types
+export type { CacheStats } from './cache/MetadataCache';