@umituz/react-native-design-system 2.8.7 → 2.8.8

package/src/storage/infrastructure/repositories/__tests__/BaseStorageOperations.test.ts

@@ -0,0 +1,201 @@
+/* eslint-disable @typescript-eslint/no-unused-vars */
+/**
+ * BaseStorageOperations Tests
+ *
+ * Unit tests for BaseStorageOperations
+ */
+
+import { BaseStorageOperations } from '../BaseStorageOperations';
+import { AsyncStorage } from '../../__tests__/mocks/asyncStorage.mock';
+import { StorageReadError, StorageWriteError, StorageDeleteError } from '../../../domain/errors/StorageError';
+
+describe('BaseStorageOperations', () => {
+  let baseOps: BaseStorageOperations;
+
+  beforeEach(() => {
+    baseOps = new BaseStorageOperations();
+    (AsyncStorage as any).__clear();
+  });
+
+  describe('getItem', () => {
+    it('should get item successfully', async () => {
+      const key = 'test-key';
+      const value = { test: 'value' };
+      const defaultValue = { default: true };
+
+      // Setup
+      await AsyncStorage.setItem(key, JSON.stringify(value));
+
+      // Test
+      const result = await baseOps.getItem(key, defaultValue);
+
+      expect(result.success).toBe(true);
+      expect(result.data).toEqual(value);
+    });
+
+    it('should return default value for missing key', async () => {
+      const key = 'missing-key';
+      const defaultValue = { default: true };
+
+      const result = await baseOps.getItem(key, defaultValue);
+
+      expect(result.success).toBe(true);
+      expect(result.data).toBe(defaultValue);
+    });
+
+    it('should handle deserialization error', async () => {
+      const key = 'invalid-json-key';
+      const defaultValue = { default: true };
+
+      // Setup invalid JSON
+      await AsyncStorage.setItem(key, 'invalid-json');
+
+      const result = await baseOps.getItem(key, defaultValue);
+
+      expect(result.success).toBe(false);
+      expect(result.data).toBe(defaultValue);
+      expect(result.error).toBeInstanceOf(StorageReadError);
+    });
+
+    it('should handle storage read error', async () => {
+      const key = 'test-key';
+      const defaultValue = { default: true };
+
+      // Mock storage error
+      (AsyncStorage.getItem as jest.Mock).mockRejectedValue(new Error('Storage error'));
+
+      const result = await baseOps.getItem(key, defaultValue);
+
+      expect(result.success).toBe(false);
+      expect(result.data).toBe(defaultValue);
+      expect(result.error).toBeInstanceOf(StorageReadError);
+    });
+  });
+
+  describe('setItem', () => {
+    it('should set item successfully', async () => {
+      const key = 'test-key';
+      const value = { test: 'value' };
+
+      const result = await baseOps.setItem(key, value);
+
+      expect(result.success).toBe(true);
+      expect(result.data).toEqual(value);
+
+      // Verify storage
+      const stored = await AsyncStorage.getItem(key);
+      expect(JSON.parse(stored!)).toEqual(value);
+    });
+
+    it('should handle serialization error', async () => {
+      const key = 'test-key';
+      const value = { circular: {} };
+      value.circular = value; // Create circular reference
+
+      const result = await baseOps.setItem(key, value);
+
+      expect(result.success).toBe(false);
+      expect(result.error).toBeInstanceOf(StorageWriteError);
+    });
+
+    it('should handle storage write error', async () => {
+      const key = 'test-key';
+      const value = { test: 'value' };
+
+      // Mock storage error
+      (AsyncStorage.setItem as jest.Mock).mockRejectedValue(new Error('Storage error'));
+
+      const result = await baseOps.setItem(key, value);
+
+      expect(result.success).toBe(false);
+      expect(result.error).toBeInstanceOf(StorageWriteError);
+    });
+  });
+
+  describe('removeItem', () => {
+    it('should remove item successfully', async () => {
+      const key = 'test-key';
+
+      // Setup
+      await AsyncStorage.setItem(key, 'test-value');
+
+      const result = await baseOps.removeItem(key);
+
+      expect(result.success).toBe(true);
+
+      // Verify removal
+      const stored = await AsyncStorage.getItem(key);
+      expect(stored).toBeNull();
+    });
+
+    it('should handle storage delete error', async () => {
+      const key = 'test-key';
+
+      // Mock storage error
+      (AsyncStorage.removeItem as jest.Mock).mockRejectedValue(new Error('Storage error'));
+
+      const result = await baseOps.removeItem(key);
+
+      expect(result.success).toBe(false);
+      expect(result.error).toBeInstanceOf(StorageDeleteError);
+    });
+  });
+
+  describe('hasItem', () => {
+    it('should return true for existing item', async () => {
+      const key = 'test-key';
+
+      // Setup
+      await AsyncStorage.setItem(key, 'test-value');
+
+      const exists = await baseOps.hasItem(key);
+
+      expect(exists).toBe(true);
+    });
+
+    it('should return false for missing item', async () => {
+      const key = 'missing-key';
+
+      const exists = await baseOps.hasItem(key);
+
+      expect(exists).toBe(false);
+    });
+
+    it('should return false on storage error', async () => {
+      const key = 'test-key';
+
+      // Mock storage error
+      (AsyncStorage.getItem as jest.Mock).mockRejectedValue(new Error('Storage error'));
+
+      const exists = await baseOps.hasItem(key);
+
+      expect(exists).toBe(false);
+    });
+  });
+
+  describe('clearAll', () => {
+    it('should clear all storage successfully', async () => {
+      // Setup
+      await AsyncStorage.setItem('key1', 'value1');
+      await AsyncStorage.setItem('key2', 'value2');
+
+      const result = await baseOps.clearAll();
+
+      expect(result.success).toBe(true);
+
+      // Verify clear
+      const keys = await AsyncStorage.getAllKeys();
+      expect(keys).toHaveLength(0);
+    });
+
+    it('should handle storage clear error', async () => {
+      // Mock storage error
+      (AsyncStorage.clear as jest.Mock).mockRejectedValue(new Error('Storage error'));
+
+      const result = await baseOps.clearAll();
+
+      expect(result.success).toBe(false);
+      expect(result.error).toBeInstanceOf(StorageDeleteError);
+    });
+  });
+});

package/src/storage/presentation/README.md

@@ -0,0 +1,181 @@
+# Presentation Layer
+
+React hooks and components for UI integration with storage and cache.
+
+## Overview
+
+Presentation layer containing React hooks for storage and cache operations. Located at `src/presentation/`.
+
+## Directory Structure
+
+- `hooks/` - React hooks for storage and cache integration
+
+## Strategies
+
+### React Integration
+- Use custom hooks for storage operations
+- Use custom hooks for cache operations
+- Enable reactive state management
+- Support automatic re-renders on state changes
+
+### State Management
+- Use useStorageState for persistent state
+- Use useCacheState for cached state
+- Enable automatic sync with storage/cache
+- Support default values and initialization
+
+### Cache Integration
+- Use useCache for cache instance access
+- Use useCachedValue for single value caching
+- Use usePersistentCache for hybrid cache+storage
+- Enable TTL-based invalidation
+
+### Hook Design
+- Follow React hooks rules and best practices
+- Enable composition and reuse
+- Support dependency arrays for optimization
+- Provide cleanup functions for side effects
+
+## Restrictions
+
+### Hook Usage
+- DO NOT call hooks outside React components
+- DO NOT call hooks conditionally or in loops
+- DO NOT mutate state directly
+- DO NOT ignore loading and error states
+
+### State Management
+- DO NOT mix storage and cache state unnecessarily
+- DO NOT create redundant state for same data
+- DO NOT forget to handle undefined/null states
+- DO NOT use stale state in closures
+
+### Performance
+- DO NOT create new cache instances on every render
+- DO NOT skip dependency arrays in useEffect
+- DO NOT cause unnecessary re-renders
+- DO NOT forget cleanup in useEffect
+
+### Error Handling
+- DO NOT ignore errors from async operations
+- DO NOT expose raw error objects to UI
+- DO NOT retry indefinitely on failures
+- DO NOT lose error context
+
+## Rules
+
+### Hook Implementation
+- MUST follow React hooks rules
+- MUST use useMemo for expensive computations
+- MUST use useCallback for stable function references
+- MUST provide cleanup functions for effects
+- MUST support dependency arrays
+
+### Storage Hooks
+- MUST provide useStorage for low-level operations
+- MUST provide useStorageState for state sync
+- MUST support generic type parameters
+- MUST handle loading states
+- MUST handle error states
+- MUST return stable references
+
+### Cache Hooks
+- MUST provide useCache for cache instance access
+- MUST provide useCachedValue for value caching
+- MUST provide useCacheState for state integration
+- MUST support TTL configuration
+- MUST support invalidation callbacks
+- MUST handle cache misses gracefully
+
+### Persistent Cache Hooks
+- MUST provide usePersistentCache for hybrid caching
+- MUST support storage fallback
+- MUST handle rehydration from storage
+- MUST support stale-while-revalidate strategy
+- MUST provide loading, error, and data states
+- MUST support refresh callbacks
+
+### State Synchronization
+- MUST sync state changes to storage/cache
+- MUST re-render on state changes
+- MUST provide latest state to consumers
+- MUST handle race conditions properly
+- MUST support optimistic updates
+
+### Error Handling
+- MUST expose error state from hooks
+- MUST enable error callbacks
+- MUST not throw exceptions from hooks
+- MUST preserve error context
+- MUST support error recovery
+
+### Loading States
+- MUST expose loading state from async hooks
+- MUST indicate initial load vs refresh
+- MUST support loading callbacks
+- MUST prevent duplicate requests
+- MUST handle concurrent operations
+
+### Type Safety
+- MUST use generic type parameters
+- MUST infer types from default values
+- MUST provide type-safe return values
+- MUST support custom type definitions
+- MUST not use type assertions
+
+### Performance Optimization
+- MUST use useMemo for cache instances
+- MUST use useCallback for event handlers
+- MUST provide dependency array parameters
+- MUST prevent unnecessary re-renders
+- MUST enable memoization where appropriate
+
+### Cleanup and Lifecycle
+- MUST clean up subscriptions on unmount
+- MUST clear temporary cache on unmount
+- MUST prevent memory leaks
+- MUST handle component unmount gracefully
+- MUST not update state after unmount
+
+### Hook Naming
+- MUST use 'use' prefix for all hooks
+- MUST use descriptive names for functionality
+- MUST follow naming conventions
+- MUST be consistent with ecosystem
+- MUST indicate purpose in name
+
+### Cache Naming
+- MUST use descriptive cache names
+- MUST avoid generic cache names
+- MUST enable pattern matching for invalidation
+- MUST follow naming conventions
+- MUST prevent naming conflicts
+
+### Testing Support
+- MUST enable hook testing with renderHook
+- MUST provide cleanup for testing
+- MUST support mocking dependencies
+- MUST reset state between tests
+- MUST not have hidden side effects
+
+### Export Rules
+- MUST export all hooks from presentation layer
+- MUST provide TypeScript types
+- MUST document hook behavior
+- MUST specify hook contracts
+- MUST not export internal utilities
+
+### Documentation
+- MUST document all public hooks
+- MUST specify parameter types and requirements
+- MUST explain return value structure
+- MUST provide usage guidance
+- MUST warn about common mistakes
+- MUST not include code examples
+
+### Best Practices Compliance
+- MUST follow React hooks rules
+- MUST enable proper dependency tracking
+- MUST support concurrent mode
+- MUST be compatible with Strict Mode
+- MUST not cause memory leaks

package/src/storage/presentation/hooks/CacheStorageOperations.ts

@@ -0,0 +1,94 @@
+/**
+ * Cache Storage Operations
+ *
+ * Handles cache storage operations following Single Responsibility Principle
+ */
+
+import { storageRepository } from '../../infrastructure/repositories/AsyncStorageRepository';
+import type { CachedValue } from '../../domain/entities/CachedValue';
+import { createCachedValue } from '../../domain/entities/CachedValue';
+import { devWarn } from '../../domain/utils/devUtils';
+
+export interface CacheStorageOptions {
+  ttl?: number;
+  version?: number;
+  enabled?: boolean;
+}
+
+/**
+ * Handles cache storage operations with proper error handling and memory management
+ */
+export class CacheStorageOperations {
+  private static instance: CacheStorageOperations | null = null;
+
+  /**
+   * Singleton pattern to prevent memory leaks
+   */
+  static getInstance(): CacheStorageOperations {
+    if (!CacheStorageOperations.instance) {
+      CacheStorageOperations.instance = new CacheStorageOperations();
+    }
+    return CacheStorageOperations.instance;
+  }
+
+  /**
+   * Reset singleton instance (useful for testing)
+   */
+  static resetInstance(): void {
+    CacheStorageOperations.instance = null;
+  }
+
+  /**
+   * Load cached data from storage
+   */
+  async loadFromStorage<T>(
+    key: string
+  ): Promise<CachedValue<T> | null> {
+    try {
+      const result = await storageRepository.getString(key, '');
+
+      if (result.success && result.data) {
+        const cached = JSON.parse(result.data) as CachedValue<T>;
+        return cached;
+      }
+
+      return null;
+    } catch (error) {
+      devWarn(`CacheStorageOperations: Failed to load cache for key "${key}"`, error);
+      return null;
+    }
+  }
+
+  /**
+   * Save data to cache storage
+   */
+  async saveToStorage<T>(
+    key: string,
+    value: T,
+    options: CacheStorageOptions = {}
+  ): Promise<void> {
+    const { ttl, version, enabled = true } = options;
+
+    if (!enabled) return;
+
+    try {
+      const cached = createCachedValue(value, ttl || 0, version);
+      await storageRepository.setString(key, JSON.stringify(cached));
+    } catch (error) {
+      devWarn(`CacheStorageOperations: Failed to save cache for key "${key}"`, error);
+    }
+  }
+
+  /**
+   * Clear cached data from storage
+   */
+  async clearFromStorage(key: string, enabled = true): Promise<void> {
+    if (!enabled) return;
+
+    try {
+      await storageRepository.removeItem(key);
+    } catch (error) {
+      devWarn(`CacheStorageOperations: Failed to clear cache for key "${key}"`, error);
+    }
+  }
+}

package/src/storage/presentation/hooks/README.md

@@ -0,0 +1,128 @@
+# React Hooks
+
+Integration layer for storage and cache functionality with React components.
+
+## Overview
+
+This directory contains React hooks that integrate storage and cache functionality with React components. Located at `src/presentation/hooks/`.
+
+## Available Hooks
+
+| Hook | Purpose | Use Case |
+|------|---------|----------|
+| `useStorage` | Low-level storage operations | Manual CRUD operations |
+| `useStorageState` | State with auto-persistence | Form data, user preferences |
+| `useStore` | Zustand store selector | State management |
+| `usePersistentCache` | API caching with persistence | Data fetching with offline support |
+| `useCacheState` | In-memory cache state | Temporary state management |
+| `useCache` | In-memory cache operations | Manual cache management |
+| `useCachedValue` | Single value caching | Simple value caching |
+
+## Strategies
+
+### Hook Selection
+- Use `useStorageState` for form inputs and settings
+- Use `useStore` for Zustand integration
+- Use `usePersistentCache` for API data with offline support
+- Use `useCache` for complex caching patterns
+- Use `useCachedValue` for simple single-value caching
+
+### Performance Optimization
+- Use selectors with `useStore` to prevent unnecessary re-renders
+- Memoize callbacks passed to cache hooks
+- Avoid inline fetcher functions
+- Use appropriate TTL based on data change frequency
+
+### Composition Patterns
+- Combine multiple hooks for complex scenarios
+- Use conditional fetching with enabled flag
+- Implement dependent queries with proper data flow
+- Share cache instances across components
+
+## Restrictions
+
+### Hook Usage
+- DO NOT call hooks outside React components or custom hooks
+- DO NOT call hooks conditionally or inside loops
+- DO NOT use `useStorage` when `useStorageState` is sufficient
+- DO NOT use inline fetcher functions (define them first)
+
+### State Management
+- DO NOT mix storage and cache for same data
+- DO NOT use `useStorageState` for large datasets (> 1MB)
+- DO NOT use `useCache` when simple state would suffice
+- DO NOT create new cache instances on every render
+
+### Performance
+- DO NOT select entire store with `useStore` (use selectors)
+- DO NOT recreate fetcher functions on every render
+- DO NOT use very short TTLs (< 5 seconds)
+- DO NOT cache large objects (> 100KB)
+
+### Error Handling
+- DO NOT ignore error states from cache hooks
+- DO NOT silently fail storage operations
+- DO NOT use try-catch inside hooks (handle errors at call site)
+
+## Rules
+
+### Hook Implementation
+- MUST follow React rules of hooks
+- MUST provide TypeScript types for all parameters
+- MUST handle loading states appropriately
+- MUST provide error state for async operations
+
+### Storage Hooks (`useStorage`, `useStorageState`)
+- MUST use unique keys for different state
+- MUST specify initial value for `useStorageState`
+- MUST handle storage errors gracefully
+- MUST provide type parameter for type safety
+
+### Cache Hooks (`useCache`, `useCacheState`, `useCachedValue`)
+- MUST specify cache name when using `useCache`
+- MUST provide fetcher function for `useCachedValue`
+- MUST set appropriate TTL for data type
+- MUST handle cache misses gracefully
+
+### Persistent Cache (`usePersistentCache`)
+- MUST provide unique key for each query
+- MUST define fetcher function that returns Promise
+- MUST specify TTL based on data freshness requirements
+- MUST handle loading and error states
+- MUST implement refresh mechanism
+
+### Store Hook (`useStore`)
+- MUST provide selector function for partial state
+- MUST use memoized selectors to prevent re-renders
+- MUST select only needed state slices
+- MUST avoid selecting entire store
+
+### Testing
+- MUST test hooks with `@testing-library/react-hooks`
+- MUST test loading, success, and error states
+- MUST test cleanup and unmount behavior
+- MUST mock storage/cache in tests
+
+### Error Handling
+- MUST expose error state from async hooks
+- MUST allow error handling at component level
+- MUST log errors in development mode
+- MUST provide retry mechanisms for transient failures
+
+### Type Safety
+- MUST provide generic type parameters
+- MUST enforce types for storage keys
+- MUST use TypeScript strict mode
+- MUST avoid `any` types in hook implementations
+
+### Performance
+- MUST use `useCallback` for functions passed to hooks
+- MUST use `useMemo` for computed values
+- MUST implement proper dependency arrays
+- MUST avoid unnecessary re-renders
+
+### Deprecation
+- MUST document deprecated hooks
+- MUST provide migration path for deprecated hooks
+- MUST maintain backward compatibility when possible
+- MUST remove deprecated hooks after major version bump