@oxyhq/services 5.9.1 → 5.9.3

package/src/utils/asyncUtils.ts

@@ -0,0 +1,265 @@
+/**
+ * Async utilities for common asynchronous patterns and error handling
+ */
+
+/**
+ * Wrapper for async operations with automatic error handling
+ */
+export async function withErrorHandling<T>(
+  operation: () => Promise<T>,
+  errorHandler?: (error: any) => void,
+  context?: string
+): Promise<T | null> {
+  try {
+    return await operation();
+  } catch (error) {
+    if (errorHandler) {
+      errorHandler(error);
+    } else {
+      console.error(`Error in ${context || 'operation'}:`, error);
+    }
+    return null;
+  }
+}
+
+/**
+ * Execute multiple async operations in parallel with error handling
+ */
+export async function parallelWithErrorHandling<T>(
+  operations: (() => Promise<T>)[],
+  errorHandler?: (error: any, index: number) => void
+): Promise<(T | null)[]> {
+  const results = await Promise.allSettled(
+    operations.map((op, index) => 
+      withErrorHandling(op, error => errorHandler?.(error, index))
+    )
+  );
+  
+  return results.map(result => 
+    result.status === 'fulfilled' ? result.value : null
+  );
+}
+
+/**
+ * Retry an async operation with exponential backoff
+ */
+export async function retryAsync<T>(
+  operation: () => Promise<T>,
+  maxRetries: number = 3,
+  baseDelay: number = 1000,
+  shouldRetry?: (error: any) => boolean
+): Promise<T> {
+  let lastError: any;
+  
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    try {
+      return await operation();
+    } catch (error) {
+      lastError = error;
+      
+      if (attempt === maxRetries) {
+        break;
+      }
+      
+      if (shouldRetry && !shouldRetry(error)) {
+        break;
+      }
+      
+      const delay = baseDelay * Math.pow(2, attempt);
+      await new Promise(resolve => setTimeout(resolve, delay));
+    }
+  }
+  
+  throw lastError;
+}
+
+/**
+ * Debounce async function calls
+ */
+export function debounceAsync<T extends (...args: any[]) => Promise<any>>(
+  func: T,
+  delay: number
+): (...args: Parameters<T>) => Promise<ReturnType<T>> {
+  let timeoutId: NodeJS.Timeout;
+  let lastPromise: Promise<ReturnType<T>> | null = null;
+  
+  return (...args: Parameters<T>): Promise<ReturnType<T>> => {
+    return new Promise((resolve, reject) => {
+      clearTimeout(timeoutId);
+      
+      timeoutId = setTimeout(async () => {
+        try {
+          const result = await func(...args);
+          resolve(result);
+        } catch (error) {
+          reject(error);
+        }
+      }, delay);
+    });
+  };
+}
+
+/**
+ * Throttle async function calls
+ */
+export function throttleAsync<T extends (...args: any[]) => Promise<any>>(
+  func: T,
+  limit: number,
+  interval: number
+): (...args: Parameters<T>) => Promise<ReturnType<T>> {
+  let inThrottle = false;
+  let lastPromise: Promise<ReturnType<T>> | null = null;
+  
+  return (...args: Parameters<T>): Promise<ReturnType<T>> => {
+    if (inThrottle) {
+      return lastPromise!;
+    }
+    
+    inThrottle = true;
+    lastPromise = func(...args);
+    
+    setTimeout(() => {
+      inThrottle = false;
+    }, interval);
+    
+    return lastPromise;
+  };
+}
+
+/**
+ * Execute async operations sequentially with progress tracking
+ */
+export async function sequentialWithProgress<T>(
+  operations: (() => Promise<T>)[],
+  onProgress?: (completed: number, total: number) => void
+): Promise<T[]> {
+  const results: T[] = [];
+  
+  for (let i = 0; i < operations.length; i++) {
+    const result = await operations[i]();
+    results.push(result);
+    onProgress?.(i + 1, operations.length);
+  }
+  
+  return results;
+}
+
+/**
+ * Batch async operations
+ */
+export async function batchAsync<T>(
+  items: T[],
+  batchSize: number,
+  processor: (batch: T[]) => Promise<void>
+): Promise<void> {
+  for (let i = 0; i < items.length; i += batchSize) {
+    const batch = items.slice(i, i + batchSize);
+    await processor(batch);
+  }
+}
+
+/**
+ * Create a cancellable async operation
+ */
+export function createCancellableAsync<T>(
+  operation: (signal: AbortSignal) => Promise<T>
+): { execute: () => Promise<T>; cancel: () => void } {
+  let abortController: AbortController | null = null;
+  
+  return {
+    execute: async () => {
+      abortController = new AbortController();
+      return await operation(abortController.signal);
+    },
+    cancel: () => {
+      abortController?.abort();
+    }
+  };
+}
+
+/**
+ * Timeout wrapper for async operations
+ */
+export async function withTimeout<T>(
+  operation: Promise<T>,
+  timeoutMs: number,
+  timeoutMessage?: string
+): Promise<T> {
+  const timeoutPromise = new Promise<never>((_, reject) => {
+    setTimeout(() => {
+      reject(new Error(timeoutMessage || `Operation timed out after ${timeoutMs}ms`));
+    }, timeoutMs);
+  });
+  
+  return Promise.race([operation, timeoutPromise]);
+}
+
+/**
+ * Cache async operation results
+ */
+export function createAsyncCache<T>(
+  ttl: number = 5 * 60 * 1000 // 5 minutes default
+) {
+  const cache = new Map<string, { data: T; timestamp: number }>();
+  
+  return {
+    get: (key: string): T | null => {
+      const item = cache.get(key);
+      if (!item) return null;
+      
+      if (Date.now() - item.timestamp > ttl) {
+        cache.delete(key);
+        return null;
+      }
+      
+      return item.data;
+    },
+    
+    set: (key: string, data: T): void => {
+      cache.set(key, { data, timestamp: Date.now() });
+    },
+    
+    clear: (): void => {
+      cache.clear();
+    },
+    
+    delete: (key: string): boolean => {
+      return cache.delete(key);
+    }
+  };
+}
+
+/**
+ * Execute async operation with loading state
+ */
+export async function withLoadingState<T>(
+  operation: () => Promise<T>,
+  setLoading: (loading: boolean) => void
+): Promise<T> {
+  setLoading(true);
+  try {
+    return await operation();
+  } finally {
+    setLoading(false);
+  }
+}
+
+/**
+ * Create a promise that resolves after a delay
+ */
+export const delay = (ms: number): Promise<void> => 
+  new Promise(resolve => setTimeout(resolve, ms));
+
+/**
+ * Execute async operation with retry on specific errors
+ */
+export async function retryOnError<T>(
+  operation: () => Promise<T>,
+  retryableErrors: (string | number)[],
+  maxRetries: number = 3
+): Promise<T> {
+  return retryAsync(operation, maxRetries, 1000, (error) => {
+    const errorCode = error?.code || error?.status || error?.message;
+    return retryableErrors.includes(errorCode);
+  });
+} 

package/src/utils/errorUtils.ts

@@ -0,0 +1,172 @@
+import { ApiError } from '../models/interfaces';
+
+/**
+ * Error handling utilities for consistent error processing
+ */
+
+/**
+ * Common error codes
+ */
+export const ErrorCodes = {
+  // Authentication errors
+  UNAUTHORIZED: 'UNAUTHORIZED',
+  FORBIDDEN: 'FORBIDDEN',
+  INVALID_TOKEN: 'INVALID_TOKEN',
+  MISSING_TOKEN: 'MISSING_TOKEN',
+  
+  // Validation errors
+  VALIDATION_ERROR: 'VALIDATION_ERROR',
+  MISSING_PARAMETER: 'MISSING_PARAMETER',
+  INVALID_FORMAT: 'INVALID_FORMAT',
+  
+  // Resource errors
+  NOT_FOUND: 'NOT_FOUND',
+  ALREADY_EXISTS: 'ALREADY_EXISTS',
+  CONFLICT: 'CONFLICT',
+  
+  // Server errors
+  INTERNAL_ERROR: 'INTERNAL_ERROR',
+  SERVICE_UNAVAILABLE: 'SERVICE_UNAVAILABLE',
+  TIMEOUT: 'TIMEOUT',
+  
+  // Network errors
+  NETWORK_ERROR: 'NETWORK_ERROR',
+  CONNECTION_FAILED: 'CONNECTION_FAILED'
+} as const;
+
+/**
+ * Create a standardized API error
+ */
+export function createApiError(
+  message: string,
+  code: string = ErrorCodes.INTERNAL_ERROR,
+  status: number = 500,
+  details?: any
+): ApiError {
+  return {
+    message,
+    code,
+    status,
+    details
+  };
+}
+
+/**
+ * Handle common HTTP errors and convert to ApiError
+ */
+export function handleHttpError(error: any): ApiError {
+  // If it's already an ApiError, return it
+  if (error && typeof error === 'object' && 'code' in error && 'status' in error) {
+    return error as ApiError;
+  }
+
+  // Handle axios errors
+  if (error?.response) {
+    const { status, data } = error.response;
+    
+    return createApiError(
+      data?.message || `HTTP ${status} error`,
+      data?.code || getErrorCodeFromStatus(status),
+      status,
+      data
+    );
+  }
+
+  // Handle network errors
+  if (error?.request) {
+    return createApiError(
+      'Network error - no response received',
+      ErrorCodes.NETWORK_ERROR,
+      0
+    );
+  }
+
+  // Handle other errors
+  return createApiError(
+    error?.message || 'Unknown error occurred',
+    ErrorCodes.INTERNAL_ERROR,
+    500
+  );
+}
+
+/**
+ * Get error code from HTTP status
+ */
+function getErrorCodeFromStatus(status: number): string {
+  switch (status) {
+    case 400:
+      return ErrorCodes.VALIDATION_ERROR;
+    case 401:
+      return ErrorCodes.UNAUTHORIZED;
+    case 403:
+      return ErrorCodes.FORBIDDEN;
+    case 404:
+      return ErrorCodes.NOT_FOUND;
+    case 409:
+      return ErrorCodes.CONFLICT;
+    case 422:
+      return ErrorCodes.VALIDATION_ERROR;
+    case 500:
+      return ErrorCodes.INTERNAL_ERROR;
+    case 503:
+      return ErrorCodes.SERVICE_UNAVAILABLE;
+    default:
+      return ErrorCodes.INTERNAL_ERROR;
+  }
+}
+
+/**
+ * Validate required fields and throw error if missing
+ */
+export function validateRequiredFields(data: Record<string, any>, fields: string[]): void {
+  const missing = fields.filter(field => !data[field]);
+  
+  if (missing.length > 0) {
+    throw createApiError(
+      `Missing required fields: ${missing.join(', ')}`,
+      ErrorCodes.MISSING_PARAMETER,
+      400
+    );
+  }
+}
+
+/**
+ * Safe error logging with context
+ */
+export function logError(error: any, context?: string): void {
+  const prefix = context ? `[${context}]` : '[Error]';
+  
+  if (error instanceof Error) {
+    console.error(`${prefix} ${error.message}`, error.stack);
+  } else {
+    console.error(`${prefix}`, error);
+  }
+}
+
+/**
+ * Retry function with exponential backoff
+ */
+export async function retryWithBackoff<T>(
+  fn: () => Promise<T>,
+  maxRetries: number = 3,
+  baseDelay: number = 1000
+): Promise<T> {
+  let lastError: any;
+  
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    try {
+      return await fn();
+    } catch (error) {
+      lastError = error;
+      
+      if (attempt === maxRetries) {
+        break;
+      }
+      
+      const delay = baseDelay * Math.pow(2, attempt);
+      await new Promise(resolve => setTimeout(resolve, delay));
+    }
+  }
+  
+  throw lastError;
+}