@umituz/react-native-design-system 4.23.114 → 4.23.115

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@umituz/react-native-design-system",
-  "version": "4.23.114",
+  "version": "4.23.115",
   "description": "Universal design system for React Native apps - Consolidated package with atoms, molecules, organisms, theme, typography, responsive, safe area, exception, infinite scroll, UUID, image, timezone, offline, onboarding, and loading utilities",
   "main": "./src/index.ts",
   "types": "./src/index.ts",

package/src/filesystem/infrastructure/services/directory.service.ts

@@ -5,6 +5,7 @@
 
 import { Directory, Paths } from "expo-file-system";
 import type { DirectoryType } from "../../domain/entities/File";
+import { ErrorHandler, ErrorCodes } from "../../../utils/errors";
 
 /**
  * Create directory
@@ -14,8 +15,17 @@ export async function createDirectory(uri: string): Promise<boolean> {
     const dir = new Directory(uri);
     await dir.create({ intermediates: true, idempotent: true });
     return true;
-  } catch {
-    return false;
+  } catch (error) {
+    const handled = ErrorHandler.handleAndLog(
+      error,
+      'createDirectory',
+      { uri }
+    );
+    throw ErrorHandler.create(
+      `Failed to create directory: ${handled.message}`,
+      ErrorCodes.DIRECTORY_CREATE_ERROR,
+      { uri, originalError: handled }
+    );
   }
 }
 
@@ -27,8 +37,17 @@ export async function listDirectory(uri: string): Promise<string[]> {
     const dir = new Directory(uri);
     const items = await dir.list();
     return items.map((item) => item.uri);
-  } catch {
-    return [];
+  } catch (error) {
+    const handled = ErrorHandler.handleAndLog(
+      error,
+      'listDirectory',
+      { uri }
+    );
+    throw ErrorHandler.create(
+      `Failed to list directory contents: ${handled.message}`,
+      ErrorCodes.FILE_READ_ERROR,
+      { uri, originalError: handled }
+    );
   }
 }
 
@@ -43,10 +62,19 @@ export function getDirectoryPath(type: DirectoryType): string {
       case "cacheDirectory":
         return Paths.cache.uri;
       default:
-        return "";
+        throw ErrorHandler.create(
+          `Unknown directory type: ${type}`,
+          ErrorCodes.INVALID_INPUT,
+          { type }
+        );
     }
-  } catch {
-    return "";
+  } catch (error) {
+    const handled = ErrorHandler.handleAndLog(
+      error,
+      'getDirectoryPath',
+      { type }
+    );
+    throw handled;
   }
 }
 

package/src/filesystem/infrastructure/services/download.service.ts

@@ -7,6 +7,8 @@ import type { FileOperationResult } from "../../domain/entities/File";
 import { FileUtils } from "../../domain/entities/File";
 import { SUPPORTED_DOWNLOAD_EXTENSIONS, DEFAULT_DOWNLOAD_EXTENSION } from "./download.constants";
 import type { DownloadProgressCallback, DownloadWithProgressResult } from "./download.types";
+import { ErrorHandler, ErrorCodes } from "../../../utils/errors";
+import { retryWithBackoff, isNetworkError } from "../../../utils/async";
 
 const hashUrl = (url: string) => {
   let hash = 0;
@@ -25,9 +27,29 @@ const getCacheUri = (url: string, dir: string) => FileUtils.joinPaths(dir, `cach
 export async function downloadFile(url: string, dest?: string): Promise<FileOperationResult> {
   try {
     const destination = dest ? new File(dest) : new File(Paths.document, FileUtils.generateUniqueFilename("download"));
-    const res = await File.downloadFileAsync(url, destination, { idempotent: true });
+
+    // Retry download with exponential backoff
+    const res = await retryWithBackoff(
+      () => File.downloadFileAsync(url, destination, { idempotent: true }),
+      {
+        maxRetries: 3,
+        baseDelay: 1000,
+        shouldRetry: (error) => isNetworkError(error as Error),
+      }
+    );
+
     return { success: true, uri: res.uri };
-  } catch (e: unknown) { return { success: false, error: e instanceof Error ? e.message : String(e) }; }
+  } catch (error) {
+    const handled = ErrorHandler.handleAndLog(
+      error,
+      'downloadFile',
+      { url, dest }
+    );
+    return {
+      success: false,
+      error: handled.getUserMessage(),
+    };
+  }
 }
 
 export async function downloadFileWithProgress(
@@ -44,7 +66,13 @@ export async function downloadFileWithProgress(
     if (new File(destUri).exists) return { success: true, uri: destUri, fromCache: true };
 
     const response = await fetch(url, { signal });
-    if (!response.ok) throw new Error(`HTTP ${response.status}`);
+    if (!response.ok) {
+      throw ErrorHandler.create(
+        `HTTP ${response.status}: ${response.statusText}`,
+        ErrorCodes.NETWORK_ERROR,
+        { url, status: response.status }
+      );
+    }
 
     const totalBytes = parseInt(response.headers.get("content-length") || "0", 10);
     if (!response.body) return { ...(await downloadFile(url, destUri)), fromCache: false };
@@ -57,7 +85,11 @@ export async function downloadFileWithProgress(
       while (true) {
         if (signal?.aborted) {
           await reader.cancel();
-          throw new Error("Download aborted");
+          throw ErrorHandler.create(
+            'Download aborted by user',
+            ErrorCodes.NETWORK_ERROR,
+            { url }
+          );
         }
 
         const { done, value } = await reader.read();
@@ -76,13 +108,32 @@ export async function downloadFileWithProgress(
     } finally {
       reader.releaseLock();
     }
-  } catch (e: unknown) { return { success: false, error: e instanceof Error ? e.message : String(e) }; }
+  } catch (error) {
+    const handled = ErrorHandler.handleAndLog(
+      error,
+      'downloadFileWithProgress',
+      { url, cacheDir }
+    );
+    return {
+      success: false,
+      error: handled.getUserMessage(),
+    };
+  }
 }
 
 export const isUrlCached = (url: string, dir: string) => new File(getCacheUri(url, dir)).exists;
 export const getCachedFileUri = (url: string, dir: string) => isUrlCached(url, dir) ? getCacheUri(url, dir) : null;
-export const deleteCachedFile = async (url: string, dir: string) => {
-  const f = new File(getCacheUri(url, dir));
-  if (f.exists) await f.delete();
-  return true;
+export const deleteCachedFile = async (url: string, dir: string): Promise<boolean> => {
+  try {
+    const f = new File(getCacheUri(url, dir));
+    if (f.exists) await f.delete();
+    return true;
+  } catch (error) {
+    ErrorHandler.handleAndLog(
+      error,
+      'deleteCachedFile',
+      { url, dir }
+    );
+    return false;
+  }
 };

package/src/filesystem/infrastructure/services/file-manager.service.ts

@@ -5,6 +5,7 @@
 
 import { File, Directory } from "expo-file-system";
 import type { FileOperationResult } from "../../domain/entities/File";
+import { ErrorHandler, ErrorCodes } from "../../../utils/errors";
 
 /**
  * Delete file or directory
@@ -18,8 +19,11 @@ export async function deleteFile(uri: string): Promise<boolean> {
         await file.delete();
         return true;
       }
-    } catch {
+    } catch (fileError) {
       // Not a file, try as directory
+      if (__DEV__) {
+        console.log('[deleteFile] Not a file, trying as directory:', uri);
+      }
     }
 
     // Try as directory
@@ -29,13 +33,30 @@ export async function deleteFile(uri: string): Promise<boolean> {
         await dir.delete();
         return true;
       }
-    } catch {
+    } catch (dirError) {
       // Not a directory either
+      if (__DEV__) {
+        console.log('[deleteFile] Not a directory:', uri);
+      }
     }
 
-    return false;
-  } catch {
-    return false;
+    // File/directory doesn't exist
+    throw ErrorHandler.create(
+      `File or directory not found: ${uri}`,
+      ErrorCodes.FILE_NOT_FOUND,
+      { uri }
+    );
+  } catch (error) {
+    const handled = ErrorHandler.handleAndLog(
+      error,
+      'deleteFile',
+      { uri }
+    );
+    throw ErrorHandler.create(
+      `Failed to delete file: ${handled.message}`,
+      ErrorCodes.FILE_DELETE_ERROR,
+      { uri, originalError: handled }
+    );
   }
 }
 
@@ -52,9 +73,14 @@ export async function copyFile(
     await sourceFile.copy(destination);
     return { success: true, uri: destinationUri };
   } catch (error) {
+    const handled = ErrorHandler.handleAndLog(
+      error,
+      'copyFile',
+      { sourceUri, destinationUri }
+    );
     return {
       success: false,
-      error: error instanceof Error ? error.message : "Unknown error",
+      error: handled.getUserMessage(),
     };
   }
 }
@@ -72,9 +98,14 @@ export async function moveFile(
     await sourceFile.move(destination);
     return { success: true, uri: destinationUri };
   } catch (error) {
+    const handled = ErrorHandler.handleAndLog(
+      error,
+      'moveFile',
+      { sourceUri, destinationUri }
+    );
     return {
       success: false,
-      error: error instanceof Error ? error.message : "Unknown error",
+      error: handled.getUserMessage(),
     };
   }
 }

package/src/filesystem/infrastructure/services/file-writer.service.ts

@@ -6,6 +6,7 @@
 import { File } from "expo-file-system";
 import type { FileEncoding, FileOperationResult } from "../../domain/entities/File";
 import { getEncodingType, type ExpoEncodingType } from "./encoding.service";
+import { ErrorHandler, ErrorCodes } from "../../../utils/errors";
 
 /**
  * Write string to file
@@ -23,10 +24,14 @@ export async function writeFile(
     });
     return { success: true, uri };
   } catch (error) {
-    const writeError = error as Error;
+    const handled = ErrorHandler.handleAndLog(
+      error,
+      'writeFile',
+      { uri, encoding, contentLength: content.length }
+    );
     return {
       success: false,
-      error: writeError.message || "Unknown error",
+      error: handled.getUserMessage(),
     };
   }
 }

package/src/media/infrastructure/services/MediaPickerService.ts

@@ -22,6 +22,7 @@ import {
 } from "../utils/mediaPickerMappers";
 import { PermissionManager } from "../utils/PermissionManager";
 import { FileValidator } from "../../domain/utils/FileValidator";
+import { ErrorHandler, ErrorCodes } from "../../../utils/errors";
 
 /**
  * Media picker service for selecting images/videos
@@ -33,7 +34,11 @@ export class MediaPickerService {
     try {
       const permission = await PermissionManager.requestCameraPermission();
       if (!PermissionManager.isPermissionGranted(permission)) {
-        return { canceled: true };
+        return {
+          canceled: true,
+          error: MediaValidationError.PERMISSION_DENIED,
+          errorMessage: "Camera permission was denied",
+        };
       }
 
       const result = await ImagePicker.launchCameraAsync({
@@ -45,8 +50,13 @@ export class MediaPickerService {
       });
 
       return mapPickerResult(result);
-    } catch {
-      return { canceled: true };
+    } catch (error) {
+      ErrorHandler.handleAndLog(error, 'launchCamera', { options });
+      return {
+        canceled: true,
+        error: MediaValidationError.PICKER_ERROR,
+        errorMessage: "Failed to launch camera",
+      };
     }
   }
 
@@ -56,7 +66,11 @@ export class MediaPickerService {
     try {
       const permission = await PermissionManager.requestCameraPermission();
       if (!PermissionManager.isPermissionGranted(permission)) {
-        return { canceled: true };
+        return {
+          canceled: true,
+          error: MediaValidationError.PERMISSION_DENIED,
+          errorMessage: "Camera permission was denied",
+        };
       }
 
       const result = await ImagePicker.launchCameraAsync({
@@ -67,8 +81,13 @@ export class MediaPickerService {
       });
 
       return mapPickerResult(result);
-    } catch {
-      return { canceled: true };
+    } catch (error) {
+      ErrorHandler.handleAndLog(error, 'launchCameraForVideo', { options });
+      return {
+        canceled: true,
+        error: MediaValidationError.PICKER_ERROR,
+        errorMessage: "Failed to launch camera for video",
+      };
     }
   }
 
@@ -114,8 +133,13 @@ export class MediaPickerService {
       }
 
       return mappedResult;
-    } catch {
-      return { canceled: true };
+    } catch (error) {
+      ErrorHandler.handleAndLog(error, 'pickImage', { options });
+      return {
+        canceled: true,
+        error: MediaValidationError.PICKER_ERROR,
+        errorMessage: "Failed to pick image from library",
+      };
     }
   }
 

package/src/media/infrastructure/services/MediaSaveService.ts

@@ -5,6 +5,7 @@
 
 import * as FileSystem from "expo-file-system";
 import { MediaLibraryPermission } from "../../domain/entities/Media";
+import { ErrorHandler, ErrorCodes } from "../../../utils/errors";
 
 export interface SaveResult {
   success: boolean;
@@ -87,10 +88,14 @@ export class MediaSaveService {
         path: destination,
       };
     } catch (error) {
-      const message = error instanceof Error ? error.message : "Unknown error";
+      const handled = ErrorHandler.handleAndLog(
+        error,
+        'saveToStorage',
+        { uri, mediaType }
+      );
       return {
         success: false,
-        error: `Failed to save media: ${message}`,
+        error: `Failed to save media: ${handled.getUserMessage()}`,
       };
     }
   }

package/src/services/api/ApiClient.ts

@@ -20,6 +20,8 @@ import {
   isSuccessfulResponse,
   fetchWithTimeout,
 } from './utils/responseHandler';
+import { retryWithBackoff, isNetworkError, isRetryableHttpStatus } from '../../utils/async';
+import { ErrorHandler } from '../../utils/errors';
 
 /**
  * Applies interceptors to a value
@@ -46,7 +48,7 @@ export class ApiClient {
   }
 
   /**
-   * Makes an HTTP request
+   * Makes an HTTP request with automatic retry for retryable errors
    */
   async request<T>(requestConfig: ApiRequestConfig): Promise<ApiResponse<T>> {
     try {
@@ -61,11 +63,39 @@ export class ApiClient {
         headers: { ...this.config.headers, ...config.headers },
       });
 
-      const response = await fetchWithTimeout(
-        fullURL,
-        fetchOptions,
-        config.timeout || this.config.timeout || 30000
-      );
+      // Retry only for GET requests and retryable errors
+      const shouldRetry = config.method === 'GET';
+      const timeout = config.timeout || this.config.timeout || 30000;
+
+      const response = shouldRetry
+        ? await retryWithBackoff(
+            () => fetchWithTimeout(fullURL, fetchOptions, timeout),
+            {
+              maxRetries: 3,
+              baseDelay: 1000,
+              shouldRetry: (error) => {
+                // Retry on network errors
+                if (isNetworkError(error as Error)) return true;
+
+                // Retry on specific HTTP status codes (5xx, 429, 408)
+                if ('status' in error && typeof error.status === 'number') {
+                  return isRetryableHttpStatus(error.status);
+                }
+
+                return false;
+              },
+              onRetry: (error, attempt, delay) => {
+                if (__DEV__) {
+                  ErrorHandler.log({
+                    name: 'ApiRetry',
+                    message: `Retrying API request (attempt ${attempt}) after ${delay}ms`,
+                    context: { url: fullURL, error: error.message },
+                  });
+                }
+              },
+            }
+          )
+        : await fetchWithTimeout(fullURL, fetchOptions, timeout);
 
       if (!isSuccessfulResponse(response)) {
         const error = await handleHttpError(response);
@@ -78,6 +108,7 @@ export class ApiClient {
       return parsedResponse;
     } catch (error) {
       const apiError = handleNetworkError(error);
+      ErrorHandler.log(apiError);
       throw await applyInterceptors(apiError, this.config.errorInterceptors);
     }
   }

package/src/utils/async/index.ts

@@ -0,0 +1,12 @@
+/**
+ * Async Utilities
+ * Retry and timeout utilities for async operations
+ */
+
+export {
+  retryWithBackoff,
+  retryWithTimeout,
+  isNetworkError,
+  isRetryableHttpStatus,
+  type RetryOptions,
+} from './retryWithBackoff';

package/src/utils/async/retryWithBackoff.ts

@@ -0,0 +1,177 @@
+/**
+ * retryWithBackoff
+ *
+ * Retry utility with exponential backoff for async operations.
+ * Useful for network requests, file operations, etc.
+ */
+
+import { ErrorHandler } from '../errors/ErrorHandler';
+
+export interface RetryOptions {
+  /**
+   * Maximum number of retry attempts
+   * @default 3
+   */
+  maxRetries?: number;
+
+  /**
+   * Initial delay in milliseconds before first retry
+   * @default 1000
+   */
+  baseDelay?: number;
+
+  /**
+   * Maximum delay in milliseconds (caps exponential growth)
+   * @default 10000
+   */
+  maxDelay?: number;
+
+  /**
+   * Multiplier for exponential backoff
+   * @default 2
+   */
+  backoffMultiplier?: number;
+
+  /**
+   * Function to determine if error is retryable
+   * @default () => true (retry all errors)
+   */
+  shouldRetry?: (error: Error, attempt: number) => boolean;
+
+  /**
+   * Callback on each retry attempt
+   */
+  onRetry?: (error: Error, attempt: number, delay: number) => void;
+}
+
+/**
+ * Retry an async function with exponential backoff
+ *
+ * @example
+ * ```ts
+ * const result = await retryWithBackoff(
+ *   () => fetch('https://api.example.com'),
+ *   { maxRetries: 3, baseDelay: 1000 }
+ * );
+ * ```
+ */
+export async function retryWithBackoff<T>(
+  fn: () => Promise<T>,
+  options: RetryOptions = {}
+): Promise<T> {
+  const {
+    maxRetries = 3,
+    baseDelay = 1000,
+    maxDelay = 10000,
+    backoffMultiplier = 2,
+    shouldRetry = () => true,
+    onRetry,
+  } = options;
+
+  let lastError: Error;
+
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    try {
+      // Attempt the operation
+      return await fn();
+    } catch (error) {
+      lastError = error instanceof Error ? error : new Error(String(error));
+
+      // Check if we should retry
+      const isLastAttempt = attempt === maxRetries;
+      if (isLastAttempt || !shouldRetry(lastError, attempt)) {
+        throw lastError;
+      }
+
+      // Calculate delay with exponential backoff
+      const delay = Math.min(
+        baseDelay * Math.pow(backoffMultiplier, attempt),
+        maxDelay
+      );
+
+      // Call onRetry callback if provided
+      if (onRetry) {
+        onRetry(lastError, attempt + 1, delay);
+      }
+
+      // Log retry in development
+      if (__DEV__) {
+        console.log(
+          `[Retry] Attempt ${attempt + 1}/${maxRetries} failed. Retrying in ${delay}ms...`,
+          lastError.message
+        );
+      }
+
+      // Wait before retrying
+      await new Promise((resolve) => setTimeout(resolve, delay));
+    }
+  }
+
+  // This should never be reached, but TypeScript needs it
+  throw lastError!;
+}
+
+/**
+ * Retry with timeout
+ * Combines retry logic with a timeout
+ *
+ * @example
+ * ```ts
+ * const result = await retryWithTimeout(
+ *   () => fetch('https://api.example.com'),
+ *   { timeout: 5000, maxRetries: 3 }
+ * );
+ * ```
+ */
+export async function retryWithTimeout<T>(
+  fn: () => Promise<T>,
+  options: RetryOptions & { timeout?: number } = {}
+): Promise<T> {
+  const { timeout = 30000, ...retryOptions } = options;
+
+  return retryWithBackoff(
+    () => withTimeout(fn(), timeout),
+    retryOptions
+  );
+}
+
+/**
+ * Add timeout to a promise
+ */
+function withTimeout<T>(
+  promise: Promise<T>,
+  timeoutMs: number
+): Promise<T> {
+  return Promise.race([
+    promise,
+    new Promise<T>((_, reject) =>
+      setTimeout(
+        () => reject(new Error(`Operation timed out after ${timeoutMs}ms`)),
+        timeoutMs
+      )
+    ),
+  ]);
+}
+
+/**
+ * Check if error is a network error
+ * Useful for shouldRetry callback
+ */
+export function isNetworkError(error: Error): boolean {
+  return (
+    error.message.includes('network') ||
+    error.message.includes('timeout') ||
+    error.message.includes('fetch') ||
+    error.message.includes('ECONNREFUSED') ||
+    error.message.includes('ETIMEDOUT')
+  );
+}
+
+/**
+ * Check if error is retryable HTTP status
+ * Useful for shouldRetry callback
+ */
+export function isRetryableHttpStatus(status: number): boolean {
+  // Retry on 5xx server errors and 429 (rate limit)
+  return status >= 500 || status === 429 || status === 408;
+}

package/src/utils/errors/DesignSystemError.ts

@@ -0,0 +1,117 @@
+/**
+ * DesignSystemError
+ *
+ * Unified error class for the design system package.
+ * Provides consistent error handling with error codes and context.
+ */
+
+export class DesignSystemError extends Error {
+  /**
+   * Error code for categorization
+   */
+  public readonly code: string;
+
+  /**
+   * Additional context about the error
+   */
+  public readonly context?: Record<string, any>;
+
+  /**
+   * Timestamp when error was created
+   */
+  public readonly timestamp: Date;
+
+  constructor(
+    message: string,
+    code: string,
+    context?: Record<string, any>
+  ) {
+    super(message);
+    this.name = 'DesignSystemError';
+    this.code = code;
+    this.context = context;
+    this.timestamp = new Date();
+
+    // Maintains proper stack trace for where our error was thrown (only available on V8)
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, DesignSystemError);
+    }
+  }
+
+  /**
+   * Convert error to JSON for logging/debugging
+   */
+  toJSON(): Record<string, any> {
+    return {
+      name: this.name,
+      message: this.message,
+      code: this.code,
+      context: this.context,
+      timestamp: this.timestamp.toISOString(),
+      stack: this.stack,
+    };
+  }
+
+  /**
+   * Get user-friendly error message
+   */
+  getUserMessage(): string {
+    // You can customize user-facing messages based on error codes
+    switch (this.code) {
+      case 'FILE_NOT_FOUND':
+        return 'The requested file could not be found.';
+      case 'PERMISSION_DENIED':
+        return 'Permission denied. Please check app permissions.';
+      case 'NETWORK_ERROR':
+        return 'Network error. Please check your connection.';
+      case 'STORAGE_FULL':
+        return 'Storage is full. Please free up some space.';
+      case 'INVALID_INPUT':
+        return 'Invalid input provided.';
+      default:
+        return this.message;
+    }
+  }
+}
+
+/**
+ * Common error codes used across the design system
+ */
+export const ErrorCodes = {
+  // File system errors
+  FILE_NOT_FOUND: 'FILE_NOT_FOUND',
+  FILE_READ_ERROR: 'FILE_READ_ERROR',
+  FILE_WRITE_ERROR: 'FILE_WRITE_ERROR',
+  FILE_DELETE_ERROR: 'FILE_DELETE_ERROR',
+  DIRECTORY_CREATE_ERROR: 'DIRECTORY_CREATE_ERROR',
+  PERMISSION_DENIED: 'PERMISSION_DENIED',
+  STORAGE_FULL: 'STORAGE_FULL',
+
+  // Network errors
+  NETWORK_ERROR: 'NETWORK_ERROR',
+  TIMEOUT_ERROR: 'TIMEOUT_ERROR',
+  API_ERROR: 'API_ERROR',
+
+  // Media errors
+  MEDIA_PICKER_ERROR: 'MEDIA_PICKER_ERROR',
+  MEDIA_SAVE_ERROR: 'MEDIA_SAVE_ERROR',
+  IMAGE_LOAD_ERROR: 'IMAGE_LOAD_ERROR',
+
+  // Storage errors
+  CACHE_ERROR: 'CACHE_ERROR',
+  STORAGE_ERROR: 'STORAGE_ERROR',
+
+  // Validation errors
+  INVALID_INPUT: 'INVALID_INPUT',
+  VALIDATION_ERROR: 'VALIDATION_ERROR',
+
+  // Theme errors
+  THEME_LOAD_ERROR: 'THEME_LOAD_ERROR',
+  THEME_SAVE_ERROR: 'THEME_SAVE_ERROR',
+
+  // Generic errors
+  UNKNOWN_ERROR: 'UNKNOWN_ERROR',
+  INITIALIZATION_ERROR: 'INITIALIZATION_ERROR',
+} as const;
+
+export type ErrorCode = typeof ErrorCodes[keyof typeof ErrorCodes];

package/src/utils/errors/ErrorHandler.ts

@@ -0,0 +1,137 @@
+/**
+ * ErrorHandler
+ *
+ * Centralized error handling utility for the design system.
+ * Provides consistent error handling, logging, and reporting.
+ */
+
+import { DesignSystemError, ErrorCodes } from './DesignSystemError';
+
+export class ErrorHandler {
+  /**
+   * Handle and normalize errors
+   * Converts any error type to DesignSystemError
+   */
+  static handle(
+    error: unknown,
+    context?: string,
+    additionalContext?: Record<string, any>
+  ): DesignSystemError {
+    // Already a DesignSystemError, return as-is
+    if (error instanceof DesignSystemError) {
+      return error;
+    }
+
+    // Standard Error object
+    if (error instanceof Error) {
+      return new DesignSystemError(
+        error.message,
+        ErrorCodes.UNKNOWN_ERROR,
+        {
+          context,
+          originalError: error.name,
+          stack: error.stack,
+          ...additionalContext,
+        }
+      );
+    }
+
+    // String error
+    if (typeof error === 'string') {
+      return new DesignSystemError(
+        error,
+        ErrorCodes.UNKNOWN_ERROR,
+        { context, ...additionalContext }
+      );
+    }
+
+    // Unknown error type
+    return new DesignSystemError(
+      'An unknown error occurred',
+      ErrorCodes.UNKNOWN_ERROR,
+      {
+        context,
+        originalError: String(error),
+        ...additionalContext,
+      }
+    );
+  }
+
+  /**
+   * Log error to console (only in development)
+   */
+  static log(error: DesignSystemError | Error | unknown): void {
+    if (__DEV__) {
+      if (error instanceof DesignSystemError) {
+        console.error('[DesignSystemError]', error.toJSON());
+      } else if (error instanceof Error) {
+        console.error('[Error]', {
+          name: error.name,
+          message: error.message,
+          stack: error.stack,
+        });
+      } else {
+        console.error('[Unknown Error]', error);
+      }
+    }
+  }
+
+  /**
+   * Handle error with logging
+   * Combines handle() and log() for convenience
+   */
+  static handleAndLog(
+    error: unknown,
+    context?: string,
+    additionalContext?: Record<string, any>
+  ): DesignSystemError {
+    const handled = this.handle(error, context, additionalContext);
+    this.log(handled);
+    return handled;
+  }
+
+  /**
+   * Create a new DesignSystemError with specific code
+   */
+  static create(
+    message: string,
+    code: string,
+    context?: Record<string, any>
+  ): DesignSystemError {
+    return new DesignSystemError(message, code, context);
+  }
+
+  /**
+   * Wrap async function with error handling
+   * Returns [error, result] tuple (similar to Go pattern)
+   */
+  static async tryAsync<T>(
+    fn: () => Promise<T>,
+    context?: string
+  ): Promise<[DesignSystemError | null, T | null]> {
+    try {
+      const result = await fn();
+      return [null, result];
+    } catch (error) {
+      const handled = this.handleAndLog(error, context);
+      return [handled, null];
+    }
+  }
+
+  /**
+   * Wrap sync function with error handling
+   * Returns [error, result] tuple
+   */
+  static try<T>(
+    fn: () => T,
+    context?: string
+  ): [DesignSystemError | null, T | null] {
+    try {
+      const result = fn();
+      return [null, result];
+    } catch (error) {
+      const handled = this.handleAndLog(error, context);
+      return [handled, null];
+    }
+  }
+}

package/src/utils/errors/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Error Utilities
+ * Unified error handling for the design system
+ */
+
+export { DesignSystemError, ErrorCodes, type ErrorCode } from './DesignSystemError';
+export { ErrorHandler } from './ErrorHandler';