@umituz/react-native-design-system 4.23.117 → 4.23.119

package/src/utils/errors/adapters/CacheErrorAdapter.ts

@@ -0,0 +1,68 @@
+/**
+ * Cache Error Adapter
+ *
+ * Adapts cache errors to unified DesignSystemError format.
+ * Maintains backward compatibility with CacheError.
+ */
+
+import { DesignSystemError, ErrorCodes, ErrorCategory } from '../DesignSystemError';
+import type { ErrorMetadata } from '../DesignSystemError';
+import { CacheError } from '../../../storage/cache/domain/ErrorHandler';
+
+export class CacheErrorAdapter {
+  /**
+   * Create a DesignSystemError for cache operations
+   */
+  static create(message: string, context: string, cause?: unknown): DesignSystemError {
+    const metadata: ErrorMetadata = {
+      category: ErrorCategory.CACHE,
+      operation: context,
+      cause,
+      retryable: true,
+    };
+
+    return new DesignSystemError(
+      `${context}: ${message}`,
+      ErrorCodes.CACHE_ERROR,
+      { context },
+      metadata
+    );
+  }
+
+  /**
+   * Convert legacy CacheError to DesignSystemError
+   */
+  static fromCacheError(error: CacheError): DesignSystemError {
+    return new DesignSystemError(
+      error.message,
+      ErrorCodes.CACHE_ERROR,
+      { cacheErrorCode: error.code },
+      {
+        category: ErrorCategory.CACHE,
+        retryable: true,
+      }
+    );
+  }
+
+  /**
+   * Handle with timeout (replaces cache ErrorHandler.withTimeout)
+   */
+  static async withTimeout<T>(
+    promise: Promise<T>,
+    timeoutMs: number,
+    context: string
+  ): Promise<T> {
+    const timeoutPromise = new Promise<never>((_, reject) => {
+      setTimeout(() => {
+        reject(
+          this.create(
+            `Operation timed out after ${timeoutMs}ms`,
+            context
+          )
+        );
+      }, timeoutMs);
+    });
+
+    return Promise.race([promise, timeoutPromise]);
+  }
+}

package/src/utils/errors/adapters/ImageErrorAdapter.ts

@@ -0,0 +1,91 @@
+/**
+ * Image Error Adapter
+ *
+ * Adapts image errors to unified DesignSystemError format.
+ * Maintains backward compatibility with ImageError.
+ */
+
+import { DesignSystemError, ErrorCodes, ErrorCategory } from '../DesignSystemError';
+import type { ErrorMetadata } from '../DesignSystemError';
+import {
+  ImageError,
+  IMAGE_ERROR_CODES,
+  type ImageErrorCode,
+} from '../../../image/infrastructure/utils/ImageErrorHandler';
+
+export class ImageErrorAdapter {
+  /**
+   * Map ImageErrorCode to DesignSystemError code
+   */
+  private static mapErrorCode(code: ImageErrorCode): string {
+    switch (code) {
+      case IMAGE_ERROR_CODES.INVALID_URI:
+      case IMAGE_ERROR_CODES.INVALID_DIMENSIONS:
+      case IMAGE_ERROR_CODES.INVALID_QUALITY:
+      case IMAGE_ERROR_CODES.VALIDATION_ERROR:
+        return ErrorCodes.VALIDATION_ERROR;
+
+      case IMAGE_ERROR_CODES.MANIPULATION_FAILED:
+      case IMAGE_ERROR_CODES.CONVERSION_FAILED:
+        return ErrorCodes.IMAGE_LOAD_ERROR;
+
+      case IMAGE_ERROR_CODES.STORAGE_FAILED:
+        return ErrorCodes.STORAGE_ERROR;
+
+      default:
+        return ErrorCodes.UNKNOWN_ERROR;
+    }
+  }
+
+  /**
+   * Create a DesignSystemError for image operations
+   */
+  static create(
+    message: string,
+    code: ImageErrorCode,
+    operation?: string
+  ): DesignSystemError {
+    const metadata: ErrorMetadata = {
+      category: ErrorCategory.IMAGE,
+      operation,
+      retryable: code === IMAGE_ERROR_CODES.MANIPULATION_FAILED,
+    };
+
+    return new DesignSystemError(
+      message,
+      this.mapErrorCode(code),
+      { imageErrorCode: code, operation },
+      metadata
+    );
+  }
+
+  /**
+   * Convert legacy ImageError to DesignSystemError
+   */
+  static fromImageError(error: ImageError): DesignSystemError {
+    return this.create(error.message, error.code as ImageErrorCode, error.operation);
+  }
+
+  /**
+   * Handle unknown image errors
+   */
+  static handleUnknown(error: unknown, operation?: string): DesignSystemError {
+    if (error instanceof ImageError) {
+      return this.fromImageError(error);
+    }
+
+    const message = error instanceof Error ? error.message : 'Unknown image error occurred';
+
+    return new DesignSystemError(
+      message,
+      ErrorCodes.IMAGE_LOAD_ERROR,
+      { operation },
+      {
+        category: ErrorCategory.IMAGE,
+        operation,
+        cause: error,
+        retryable: true,
+      }
+    );
+  }
+}

package/src/utils/errors/adapters/StorageErrorAdapter.ts

@@ -0,0 +1,107 @@
+/**
+ * Storage Error Adapter
+ *
+ * Adapts storage errors to unified DesignSystemError format.
+ * Maintains backward compatibility with StorageError hierarchy.
+ */
+
+import { DesignSystemError, ErrorCodes, ErrorCategory } from '../DesignSystemError';
+import type { ErrorMetadata } from '../DesignSystemError';
+import {
+  StorageError,
+  StorageReadError,
+  StorageWriteError,
+  StorageDeleteError,
+  StorageSerializationError,
+  StorageDeserializationError,
+} from '../../../storage/domain/errors/StorageError';
+
+export class StorageErrorAdapter {
+  /**
+   * Create a DesignSystemError for storage read failures
+   */
+  static readError(key: string, cause?: unknown): DesignSystemError {
+    const metadata: ErrorMetadata = {
+      category: ErrorCategory.STORAGE,
+      operation: 'read',
+      key,
+      cause,
+      retryable: true,
+    };
+
+    return new DesignSystemError(
+      `Failed to read from storage: ${key}`,
+      ErrorCodes.STORAGE_ERROR,
+      { key },
+      metadata
+    );
+  }
+
+  /**
+   * Create a DesignSystemError for storage write failures
+   */
+  static writeError(key: string, cause?: unknown): DesignSystemError {
+    const metadata: ErrorMetadata = {
+      category: ErrorCategory.STORAGE,
+      operation: 'write',
+      key,
+      cause,
+      retryable: true,
+    };
+
+    return new DesignSystemError(
+      `Failed to write to storage: ${key}`,
+      ErrorCodes.STORAGE_ERROR,
+      { key },
+      metadata
+    );
+  }
+
+  /**
+   * Create a DesignSystemError for storage delete failures
+   */
+  static deleteError(key: string, cause?: unknown): DesignSystemError {
+    const metadata: ErrorMetadata = {
+      category: ErrorCategory.STORAGE,
+      operation: 'delete',
+      key,
+      cause,
+      retryable: true,
+    };
+
+    return new DesignSystemError(
+      `Failed to delete from storage: ${key}`,
+      ErrorCodes.STORAGE_ERROR,
+      { key },
+      metadata
+    );
+  }
+
+  /**
+   * Convert legacy StorageError to DesignSystemError
+   */
+  static fromStorageError(error: StorageError): DesignSystemError {
+    let operation = 'unknown';
+
+    if (error instanceof StorageReadError) operation = 'read';
+    else if (error instanceof StorageWriteError) operation = 'write';
+    else if (error instanceof StorageDeleteError) operation = 'delete';
+    else if (error instanceof StorageSerializationError) operation = 'serialize';
+    else if (error instanceof StorageDeserializationError) operation = 'deserialize';
+
+    const cause = 'cause' in error ? error.cause : undefined;
+
+    return new DesignSystemError(
+      error.message,
+      ErrorCodes.STORAGE_ERROR,
+      { key: error.key },
+      {
+        category: ErrorCategory.STORAGE,
+        operation,
+        key: error.key,
+        cause,
+        retryable: true,
+      }
+    );
+  }
+}

package/src/utils/errors/index.ts

@@ -3,5 +3,9 @@
  * Unified error handling for the design system
  */
 
-export { DesignSystemError, ErrorCodes, type ErrorCode } from './DesignSystemError';
+export { DesignSystemError, ErrorCodes, ErrorCategory, type ErrorCode, type ErrorMetadata } from './DesignSystemError';
 export { ErrorHandler } from './ErrorHandler';
+
+// Result type for explicit error handling
+export type { Result } from './types/Result';
+export { ok, err, unwrap, unwrapOr, map, mapError } from './types/Result';

package/src/utils/errors/types/Result.ts

@@ -0,0 +1,64 @@
+/**
+ * Result Type
+ *
+ * Rust/Go-inspired Result type for explicit error handling.
+ * Alternative to throwing errors or returning tuples.
+ */
+
+export type Result<T, E = Error> =
+  | { success: true; value: T; error: null }
+  | { success: false; value: null; error: E };
+
+/**
+ * Create a successful result
+ */
+export function ok<T, E = Error>(value: T): Result<T, E> {
+  return { success: true, value, error: null };
+}
+
+/**
+ * Create an error result
+ */
+export function err<T, E = Error>(error: E): Result<T, E> {
+  return { success: false, value: null, error };
+}
+
+/**
+ * Unwrap result value or throw error
+ */
+export function unwrap<T, E = Error>(result: Result<T, E>): T {
+  if (result.success) {
+    return result.value;
+  }
+  throw result.error;
+}
+
+/**
+ * Unwrap result value or return default
+ */
+export function unwrapOr<T, E = Error>(result: Result<T, E>, defaultValue: T): T {
+  return result.success ? result.value : defaultValue;
+}
+
+/**
+ * Map result value if successful
+ */
+export function map<T, U, E = Error>(
+  result: Result<T, E>,
+  fn: (value: T) => U
+): Result<U, E> {
+  if (result.success) {
+    return ok(fn(result.value));
+  }
+  return { success: false, value: null, error: result.error };
+}
+
+/**
+ * Map result error if failed
+ */
+export function mapError<T, E, F>(
+  result: Result<T, E>,
+  fn: (error: E) => F
+): Result<T, F> {
+  return result.success ? result : err(fn(result.error));
+}

package/src/utils/hooks/index.ts

@@ -0,0 +1,12 @@
+/**
+ * Shared Hooks Barrel Export
+ */
+
+export { useAsyncOperation } from './useAsyncOperation';
+export type {
+  AsyncOperationOptions,
+  AsyncOperationState,
+  AsyncOperationActions,
+  AsyncOperationReturn,
+  ErrorHandler,
+} from './types/AsyncOperationTypes';

package/src/utils/hooks/types/AsyncOperationTypes.ts

@@ -0,0 +1,75 @@
+/**
+ * AsyncOperation Types
+ * Type definitions for useAsyncOperation hook
+ */
+
+export type ErrorHandler<E = Error> = (error: unknown) => E;
+
+export interface AsyncOperationOptions<T, E = Error> {
+  /** Skip execution (useful for conditional operations) */
+  skip?: boolean;
+
+  /** Execute immediately on mount */
+  immediate?: boolean;
+
+  /** Initial data value */
+  initialData?: T | null;
+
+  /** Convert error to custom type */
+  errorHandler?: ErrorHandler<E>;
+
+  /** Callback on success */
+  onSuccess?: (data: T) => void;
+
+  /** Callback on error */
+  onError?: (error: E) => void;
+
+  /** Callback on finally (success or error) */
+  onFinally?: () => void;
+
+  /** Enable retry functionality */
+  enableRetry?: boolean;
+
+  /** Maximum retry attempts */
+  maxRetries?: number;
+}
+
+export interface AsyncOperationState<T, E = Error> {
+  /** Current data value */
+  data: T | null;
+
+  /** Loading state */
+  isLoading: boolean;
+
+  /** Error state */
+  error: E | null;
+
+  /** Is operation idle (not executed yet) */
+  isIdle: boolean;
+
+  /** Is operation successful */
+  isSuccess: boolean;
+
+  /** Is operation in error state */
+  isError: boolean;
+}
+
+export interface AsyncOperationActions<T, E = Error> {
+  /** Execute the async operation */
+  execute: (...args: any[]) => Promise<T | null>;
+
+  /** Retry the last operation */
+  retry: () => Promise<T | null>;
+
+  /** Reset to initial state */
+  reset: () => void;
+
+  /** Set data manually */
+  setData: (data: T | null) => void;
+
+  /** Set error manually */
+  setError: (error: E | null) => void;
+}
+
+export type AsyncOperationReturn<T, E = Error> =
+  AsyncOperationState<T, E> & AsyncOperationActions<T, E>;

package/src/utils/hooks/useAsyncOperation.ts

@@ -0,0 +1,223 @@
+/**
+ * useAsyncOperation Hook
+ *
+ * Eliminates duplicate async error handling patterns across hooks.
+ * Handles isMountedRef + try-catch-finally + loading/error state management.
+ *
+ * Based on the useAsyncData pattern from useDeviceInfo.ts but generalized
+ * for broader use cases.
+ *
+ * @example
+ * ```typescript
+ * // Simple usage (like useAsyncData)
+ * const { data, isLoading, error, execute } = useAsyncOperation(
+ *   async () => await fetchData(),
+ *   { immediate: true }
+ * );
+ *
+ * // Manual execution (like useMedia)
+ * const { execute, isLoading, error } = useAsyncOperation(
+ *   async (uri: string) => await pickImage(uri),
+ *   { immediate: false }
+ * );
+ * const result = await execute('file://...');
+ *
+ * // With custom error handling
+ * const { data, error } = useAsyncOperation(
+ *   async () => await riskyOperation(),
+ *   {
+ *     errorHandler: (err) => err instanceof Error ? err.message : 'Failed',
+ *     onError: (err) => console.error('Operation failed:', err),
+ *   }
+ * );
+ * ```
+ */
+
+import { useState, useCallback, useEffect, useRef, useMemo } from 'react';
+import type {
+  AsyncOperationOptions,
+  AsyncOperationReturn,
+  ErrorHandler,
+} from './types/AsyncOperationTypes';
+
+const defaultErrorHandler: ErrorHandler<Error> = (error: unknown): Error => {
+  if (error instanceof Error) return error;
+  return new Error(String(error));
+};
+
+export function useAsyncOperation<T, E = Error>(
+  operation: (...args: any[]) => Promise<T>,
+  options: AsyncOperationOptions<T, E> = {}
+): AsyncOperationReturn<T, E> {
+  const {
+    skip = false,
+    immediate = false,
+    initialData = null,
+    errorHandler = defaultErrorHandler as ErrorHandler<E>,
+    onSuccess,
+    onError,
+    onFinally,
+    enableRetry = false,
+    maxRetries = 3,
+  } = options;
+
+  // State
+  const [data, setData] = useState<T | null>(initialData);
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setErrorState] = useState<E | null>(null);
+  const [isIdle, setIsIdle] = useState(true);
+
+  // Refs for cleanup and retry
+  const isMountedRef = useRef(true);
+  const lastArgsRef = useRef<any[]>([]);
+  const retryCountRef = useRef(0);
+
+  // Stable callback refs
+  const onSuccessRef = useRef(onSuccess);
+  const onErrorRef = useRef(onError);
+  const onFinallyRef = useRef(onFinally);
+
+  useEffect(() => {
+    onSuccessRef.current = onSuccess;
+    onErrorRef.current = onError;
+    onFinallyRef.current = onFinally;
+  }, [onSuccess, onError, onFinally]);
+
+  // Cleanup on unmount
+  useEffect(() => {
+    return () => {
+      isMountedRef.current = false;
+    };
+  }, []);
+
+  const execute = useCallback(
+    async (...args: any[]): Promise<T | null> => {
+      if (!isMountedRef.current || skip) return null;
+
+      // Store args for retry
+      lastArgsRef.current = args;
+
+      if (isMountedRef.current) {
+        setIsLoading(true);
+        setErrorState(null);
+        setIsIdle(false);
+      }
+
+      try {
+        const result = await operation(...args);
+
+        if (isMountedRef.current) {
+          setData(result);
+          onSuccessRef.current?.(result);
+          retryCountRef.current = 0; // Reset retry count on success
+        }
+
+        return result;
+      } catch (err) {
+        const handledError = errorHandler(err);
+
+        if (isMountedRef.current) {
+          setErrorState(handledError);
+          onErrorRef.current?.(handledError);
+        }
+
+        return null;
+      } finally {
+        if (isMountedRef.current) {
+          setIsLoading(false);
+          onFinallyRef.current?.();
+        }
+      }
+    },
+    [operation, skip, errorHandler]
+  );
+
+  const retry = useCallback(async (): Promise<T | null> => {
+    if (!enableRetry) {
+      if (__DEV__) {
+        console.warn('Retry is not enabled for this operation');
+      }
+      return null;
+    }
+
+    if (retryCountRef.current >= maxRetries) {
+      if (__DEV__) {
+        console.warn(`Max retries (${maxRetries}) reached`);
+      }
+      return null;
+    }
+
+    retryCountRef.current++;
+    return execute(...lastArgsRef.current);
+  }, [execute, enableRetry, maxRetries]);
+
+  const reset = useCallback(() => {
+    if (isMountedRef.current) {
+      setData(initialData);
+      setErrorState(null);
+      setIsLoading(false);
+      setIsIdle(true);
+      retryCountRef.current = 0;
+      lastArgsRef.current = [];
+    }
+  }, [initialData]);
+
+  const setDataManual = useCallback((newData: T | null) => {
+    if (isMountedRef.current) {
+      setData(newData);
+      setErrorState(null);
+      setIsIdle(false);
+    }
+  }, []);
+
+  const setErrorManual = useCallback((newError: E | null) => {
+    if (isMountedRef.current) {
+      setErrorState(newError);
+      setIsIdle(false);
+    }
+  }, []);
+
+  // Auto-execute on mount if immediate
+  useEffect(() => {
+    if (immediate && !skip) {
+      execute();
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [immediate, skip]);
+
+  // Derived state
+  const isSuccess = !isIdle && !isLoading && error === null && data !== null;
+  const isError = !isIdle && !isLoading && error !== null;
+
+  return useMemo(
+    () => ({
+      // State
+      data,
+      isLoading,
+      error,
+      isIdle,
+      isSuccess,
+      isError,
+
+      // Actions
+      execute,
+      retry,
+      reset,
+      setData: setDataManual,
+      setError: setErrorManual,
+    }),
+    [
+      data,
+      isLoading,
+      error,
+      isIdle,
+      isSuccess,
+      isError,
+      execute,
+      retry,
+      reset,
+      setDataManual,
+      setErrorManual,
+    ]
+  );
+}