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

package/src/storage/application/ports/README.md

@@ -0,0 +1,127 @@
+# Application Ports
+
+Repository interfaces for dependency inversion and testability.
+
+## Overview
+
+Ports define contracts between application and infrastructure layers using dependency inversion principle. Located at `src/application/ports/`.
+
+## Strategies
+
+### Dependency Inversion
+- Define interfaces in application layer
+- Implement interfaces in infrastructure layer
+- Depend on abstractions, not concretions
+- Enable swapping implementations without business logic changes
+
+### Testability Strategy
+- Design interfaces for easy mocking
+- Use constructor injection for dependencies
+- Create fake implementations for testing
+- Separate unit tests from integration tests
+
+### Contract Design
+- Define clear method signatures
+- Use Result pattern for error handling
+- Include type parameters for flexibility
+- Document interface contracts
+
+### Implementation Strategy
+- Provide production implementation (AsyncStorage)
+- Provide mock implementation for testing
+- Support custom implementations (MMKV, SecureStore)
+- Allow platform-specific implementations
+
+## Restrictions
+
+### Interface Design
+- DO NOT include implementation details in interfaces
+- DO NOT change interface signatures without major version bump
+- DO NOT add optional parameters to existing methods
+- DO NOT remove methods from interfaces
+
+### Usage
+- DO NOT use concrete implementations in business logic
+- DO NOT instantiate dependencies inside services
+- DO NOT couple services to specific storage technologies
+- DO NOT bypass interface for performance
+
+### Implementation
+- DO NOT throw exceptions from interface methods
+- DO NOT return undefined (use null or Result)
+- DO NOT ignore type parameters
+- DO NOT mix sync and async patterns
+
+### Testing
+- DO NOT use real storage in unit tests
+- DO NOT share mock instances between tests
+- DO NOT forget to reset mock state
+- DO NOT test interfaces directly
+
+## Rules
+
+### Interface Definition
+- MUST define all required methods
+- MUST use generic type parameters for flexibility
+- MUST return Promise for async operations
+- MUST use Result pattern for error handling
+
+### Method Signatures
+- MUST include type parameter <T> for data operations
+- MUST accept key parameter for storage operations
+- MUST provide defaultValue for getItem methods
+- MUST return StorageResult for operations that can fail
+
+### Constructor Injection
+- MUST inject interfaces through constructors
+- MUST store interface reference as private field
+- MUST mark constructor parameter as readonly
+- MUST not create instances inside class
+
+### Implementation Classes
+- MUST implement complete interface
+- MUST handle all error cases internally
+- MUST return appropriate error types
+- MUST log errors for debugging
+
+### Mock Implementations
+- MUST implement all interface methods
+- MUST provide methods to set mock behavior
+- MUST track method calls for assertions
+- MUST reset state between tests
+
+### Custom Implementations
+- MUST implement IStorageRepository interface
+- MUST handle serialization consistently
+- MUST provide error details in results
+- MUST document platform limitations
+
+### Dependency Injection
+- MUST use interface types in constructors
+- MUST not depend on concrete classes
+- MUST support different implementations
+- MUST validate dependencies at construction time
+
+### Type Safety
+- MUST specify type parameters for all operations
+- MUST enforce type consistency
+- MUST use type guards for validation
+- MUST avoid type assertions
+
+### Error Handling
+- MUST return failure Result for errors
+- MUST include error context (key, operation)
+- MUST preserve original error as cause
+- MUST not throw exceptions from interface methods
+
+### Testing Strategy
+- MUST use mock implementations for unit tests
+- MUST use real implementations for integration tests
+- MUST reset state in test setup
+- MUST test error scenarios
+
+### Documentation
+- MUST document interface contracts
+- MUST specify error types for each method
+- MUST include parameter descriptions
+- MUST provide usage examples in tests

package/src/storage/cache/README.md

@@ -0,0 +1,154 @@
+# Cache Module
+
+High-performance in-memory cache system with TTL and multiple eviction strategies.
+
+## Overview
+
+The cache module provides a comprehensive in-memory caching solution with TTL (Time To Live), LRU, LFU, and FIFO eviction strategies. Located at `src/cache/`.
+
+## Architecture
+
+```
+cache/
+├── domain/              # Business logic and entities
+│   ├── Cache.ts        # Main Cache class
+│   ├── CacheManager.ts # Singleton cache manager
+│   ├── CacheStatsTracker.ts
+│   ├── PatternMatcher.ts
+│   ├── ErrorHandler.ts
+│   ├── strategies/     # Eviction strategies
+│   └── types/          # TypeScript types
+├── infrastructure/     # Infrastructure implementation
+│   └── TTLCache.ts
+└── presentation/       # React integration
+    ├── useCache.ts
+    └── useCachedValue.ts
+```
+
+## Strategies
+
+### Cache Organization
+- Use CacheManager for multiple named caches
+- Create separate caches for different data types
+- Use environment-specific configurations
+- Implement cache hierarchy for performance
+
+### Eviction Strategy Selection
+- Use LRU for frequently accessed recent data
+- Use LFU for popularity-based caching
+- Use FIFO for simple queue-based caching
+- Use TTL for time-based expiration
+
+### React Integration
+- Use useCache hook for manual cache management
+- Use useCachedValue for automatic value caching
+- Share cache instances across components
+- Implement cleanup on component unmount
+
+### Performance Optimization
+- Monitor cache hit rates and adjust sizes
+- Use appropriate TTL based on data change frequency
+- Implement cache warmup for critical data
+- Use pattern-based invalidation for bulk operations
+
+## Restrictions
+
+### Cache Creation
+- DO NOT create unlimited cache sizes without max limit
+- DO NOT use zero or negative TTL values
+- DO NOT mix unrelated data types in same cache
+- DO NOT create caches without considering eviction strategy
+
+### Memory Management
+- DO NOT cache large objects (> 100KB) without size limits
+- DO NOT cache frequently changing data with long TTL
+- DO NOT ignore memory warnings from cache statistics
+- DO NOT let caches grow unbounded
+
+### Pattern Usage
+- DO NOT use broad patterns (e.g., `*`) for invalidation
+- DO NOT mix different separators in cache keys
+- DO NOT create ambiguous key structures
+- DO NOT use patterns without documenting structure
+
+### React Integration
+- DO NOT create new cache instances on every render
+- DO NOT use cache hooks without proper cleanup
+- DO NOT share cache state between unrelated components
+- DO NOT ignore loading and error states
+
+## Rules
+
+### Cache Configuration
+- MUST specify maxSize for all caches
+- MUST set defaultTTL based on data characteristics
+- MUST provide onEvict callback in development
+- MUST document cache purpose and data type
+
+### Cache Operations
+- MUST use get() for retrieving values
+- MUST use set() for storing values with optional TTL
+- MUST use has() to check key existence
+- MUST use delete() to remove specific keys
+- MUST use clear() to remove all entries
+
+### Cache Keys
+- MUST use consistent key structure (e.g., `entity:id:attribute`)
+- MUST use descriptive key names
+- MUST document key patterns in code comments
+- MUST avoid key collisions across different data types
+
+### Eviction Strategy
+- MUST choose appropriate strategy for use case
+- MUST configure strategy parameters correctly
+- MUST monitor eviction statistics
+- MUST test eviction behavior under load
+
+### TTL Management
+- MUST set TTL based on data freshness requirements
+- MUST use TIME_MS constants for time values
+- MUST consider stale data impact
+- MUST implement refresh mechanisms for critical data
+
+### Error Handling
+- MUST handle cache errors gracefully
+- MUST log cache operation failures
+- MUST provide fallback for cache misses
+- MUST not throw exceptions from cache operations
+
+### Statistics Tracking
+- MUST track hits, misses, and evictions
+- MUST calculate hit rate correctly
+- MUST provide getStats() method
+- MUST reset statistics in tests
+
+### Pattern-Based Operations
+- MUST use `invalidatePattern()` for bulk invalidation
+- MUST use `:` as default separator
+- MUST support `*` wildcard
+- MUST return count of invalidated keys
+
+### React Hooks
+- MUST follow React rules of hooks
+- MUST cleanup cache on unmount
+- MUST provide loading states for async operations
+- MUST handle errors in fetcher functions
+
+### Testing Requirements
+- MUST clear cache before each test
+- MUST test hit/miss scenarios
+- MUST test eviction behavior
+- MUST test TTL expiration
+- MUST test pattern matching
+
+### Type Safety
+- MUST use generic type parameter for cached values
+- MUST enforce type consistency
+- MUST provide type inference
+- MUST avoid `any` types
+
+### Performance Monitoring
+- MUST monitor cache hit rate
+- MUST alert on low hit rates (< 50%)
+- MUST track memory usage
+- MUST log performance anomalies

package/src/storage/cache/__tests__/PerformanceAndMemory.test.ts

@@ -0,0 +1,387 @@
+/* eslint-disable @typescript-eslint/no-unused-vars */
+/**
+ * Performance and Memory Leak Tests
+ */
+
+import { Cache } from '../Cache';
+import { TTLCache } from '../TTLCache';
+import { cacheManager } from '../CacheManager';
+import { PatternMatcher } from '../PatternMatcher';
+import { renderHook, act } from '@testing-library/react';
+import { useCache } from '../../presentation/useCache';
+
+describe('Performance and Memory Leak Tests', () => {
+  describe('Cache Performance', () => {
+    test('should handle large number of entries efficiently', () => {
+      const cache = new Cache<string>({ maxSize: 10000 });
+      const startTime = performance.now();
+      
+      // Add 10,000 entries
+      for (let i = 0; i < 10000; i++) {
+        cache.set(`key${i}`, `value${i}`);
+      }
+      
+      const insertTime = performance.now() - startTime;
+      
+      // Test retrieval performance
+      const retrieveStart = performance.now();
+      for (let i = 0; i < 10000; i++) {
+        cache.get(`key${i}`);
+      }
+      const retrieveTime = performance.now() - retrieveStart;
+      
+      expect(cache.getStats().size).toBe(10000);
+      expect(insertTime).toBeLessThan(1000); // 1 second for 10k inserts
+      expect(retrieveTime).toBeLessThan(500); // 0.5 second for 10k retrievals
+    });
+
+    test('should handle rapid eviction without performance degradation', () => {
+      const cache = new Cache<string>({ maxSize: 100 });
+      const startTime = performance.now();
+      
+      // Add and rapidly evict entries
+      for (let i = 0; i < 1000; i++) {
+        cache.set(`key${i}`, `value${i}`);
+      }
+      
+      const endTime = performance.now();
+      const duration = endTime - startTime;
+      
+      expect(cache.getStats().size).toBe(100); // Should maintain max size
+      expect(cache.getStats().evictions).toBeGreaterThan(800); // Many evictions
+      expect(duration).toBeLessThan(1000); // Should complete quickly
+    });
+
+    test('should handle pattern invalidation efficiently', () => {
+      const cache = new Cache<string>();
+      
+      // Add entries with different patterns
+      for (let i = 0; i < 1000; i++) {
+        cache.set(`user:${i}:profile`, `profile${i}`);
+        cache.set(`user:${i}:settings`, `settings${i}`);
+        cache.set(`post:${i}`, `post${i}`);
+      }
+      
+      const startTime = performance.now();
+      const invalidatedCount = cache.invalidatePattern('user:*:profile');
+      const endTime = performance.now();
+      
+      const duration = endTime - startTime;
+      
+      expect(invalidatedCount).toBe(1000);
+      expect(duration).toBeLessThan(100); // Should be very fast
+      expect(cache.getStats().size).toBe(2000); // posts + settings remain
+    });
+  });
+
+  describe('Memory Management', () => {
+    test('should not memory leak with cache destruction', () => {
+      const caches: TTLCache<string>[] = [];
+      
+      // Create many caches
+      for (let i = 0; i < 100; i++) {
+        const cache = new TTLCache<string>({ cleanupIntervalMs: 100 });
+        cache.set(`key${i}`, `value${i}`);
+        caches.push(cache);
+      }
+      
+      // Destroy all caches
+      const startTime = performance.now();
+      caches.forEach(cache => cache.destroy());
+      const endTime = performance.now();
+      
+      const duration = endTime - startTime;
+      
+      expect(duration).toBeLessThan(1000); // Should destroy quickly
+      
+      // Operations on destroyed caches should be safe
+      caches.forEach(cache => {
+        expect(() => cache.set('test', 'value')).not.toThrow();
+        expect(cache.get('test')).toBeUndefined();
+      });
+    });
+
+    test('should handle cache manager memory efficiently', () => {
+      const cacheNames: string[] = [];
+      
+      // Create many caches through manager
+      for (let i = 0; i < 1000; i++) {
+        const name = `cache-${i}`;
+        cacheNames.push(name);
+        const cache = cacheManager.getCache<string>(name);
+        cache.set(`key${i}`, `value${i}`);
+      }
+      
+      expect(cacheManager.getCacheNames()).toHaveLength(1000);
+      
+      // Delete all caches
+      const startTime = performance.now();
+      cacheNames.forEach(name => cacheManager.deleteCache(name));
+      const endTime = performance.now();
+      
+      const duration = endTime - startTime;
+      
+      expect(duration).toBeLessThan(1000);
+      expect(cacheManager.getCacheNames()).toHaveLength(0);
+    });
+
+    test('should cleanup pattern matcher cache', () => {
+      // Create many unique patterns to fill cache
+      for (let i = 0; i < 1000; i++) {
+        PatternMatcher.convertPatternToRegex(`pattern-${i}-*`);
+      }
+      
+      // Clear cache and verify memory is freed
+      PatternMatcher.clearCache();
+      
+      // Should still work after clear
+      expect(PatternMatcher.matchesPattern('test-key', 'test-*')).toBe(true);
+    });
+  });
+
+  describe('React Hooks Performance', () => {
+    test('should handle many hook instances without memory leaks', () => {
+      const hooks: Array<ReturnType<typeof useCache<string>>> = [];
+      
+      // Create many hook instances
+      for (let i = 0; i < 100; i++) {
+        const { result } = renderHook(() => useCache<string>(`test-cache-${i}`));
+        hooks.push(result.current);
+      }
+      
+      // Perform operations on all hooks
+      const startTime = performance.now();
+      hooks.forEach((hook, index) => {
+        act(() => {
+          hook.set(`key${index}`, `value${index}`);
+        });
+      });
+      const endTime = performance.now();
+      
+      const duration = endTime - startTime;
+      
+      expect(duration).toBeLessThan(2000); // Should complete within 2 seconds
+      
+      // Verify all operations worked
+      hooks.forEach((hook, index) => {
+        expect(hook.get(`key${index}`)).toBe(`value${index}`);
+      });
+      
+      // Cleanup all hooks
+      hooks.forEach(() => {
+        // Hooks will be automatically cleaned up when unmounted
+      });
+    });
+
+    test('should handle rapid hook re-renders efficiently', () => {
+      const { result, rerender } = renderHook(() => useCache<string>('rapid-cache'));
+      
+      const startTime = performance.now();
+      
+      // Perform many rapid operations
+      for (let i = 0; i < 1000; i++) {
+        act(() => {
+          result.current.set(`key${i}`, `value${i}`);
+        });
+      }
+      
+      const endTime = performance.now();
+      const duration = endTime - startTime;
+      
+      expect(duration).toBeLessThan(3000); // Should complete within 3 seconds
+      expect(result.current.getStats().size).toBeLessThanOrEqual(100); // Limited by eviction
+    });
+  });
+
+  describe('Stress Tests', () => {
+    test('should handle concurrent operations safely', async () => {
+      const cache = new Cache<string>({ maxSize: 1000 });
+      const promises: Promise<void>[] = [];
+      
+      // Create concurrent operations
+      for (let i = 0; i < 100; i++) {
+        promises.push(
+          new Promise<void>((resolve) => {
+            setTimeout(() => {
+              for (let j = 0; j < 10; j++) {
+                const key = `concurrent-${i}-${j}`;
+                const value = `value-${i}-${j}`;
+                cache.set(key, value);
+                cache.get(key);
+              }
+              resolve();
+            }, Math.random() * 100);
+          })
+        );
+      }
+      
+      // Wait for all operations to complete
+      await Promise.all(promises);
+      
+      // Verify cache is in consistent state
+      const stats = cache.getStats();
+      expect(stats.size).toBeLessThanOrEqual(1000);
+      expect(stats.hits + stats.misses).toBeGreaterThan(0);
+    });
+
+    test('should handle TTL cache under stress', async () => {
+      jest.useFakeTimers();
+      
+      const cache = new TTLCache<string>({ 
+        maxSize: 500, 
+        defaultTTL: 100,
+        cleanupIntervalMs: 50 
+      });
+      
+      // Add many entries with short TTL
+      for (let i = 0; i < 1000; i++) {
+        cache.set(`stress-key${i}`, `stress-value${i}`);
+      }
+      
+      // Advance time to trigger multiple cleanup cycles
+      for (let i = 0; i < 10; i++) {
+        jest.advanceTimersByTime(50);
+        await new Promise(resolve => setTimeout(resolve, 0));
+      }
+      
+      // Cache should handle stress without errors
+      expect(() => cache.get('any-key')).not.toThrow();
+      
+      const stats = cache.getStats();
+      expect(stats.expirations).toBeGreaterThan(0);
+      
+      cache.destroy();
+      jest.useRealTimers();
+    });
+
+    test('should handle pattern matching stress test', () => {
+      const patterns: string[] = [];
+      const keys: string[] = [];
+      
+      // Generate many patterns and keys
+      for (let i = 0; i < 1000; i++) {
+        patterns.push(`pattern-${i}-*`);
+        keys.push(`pattern-${i}-value`);
+      }
+      
+      const startTime = performance.now();
+      
+      // Test all pattern matches
+      patterns.forEach((pattern, index) => {
+        PatternMatcher.matchesPattern(keys[index], pattern);
+      });
+      
+      const endTime = performance.now();
+      const duration = endTime - startTime;
+      
+      expect(duration).toBeLessThan(100); // Should be very fast with caching
+    });
+  });
+
+  describe('Memory Leak Detection', () => {
+    test('should not leak memory with repeated cache operations', () => {
+      const cache = new Cache<string>();
+      const initialMemory = process.memoryUsage().heapUsed;
+      
+      // Perform many operations
+      for (let cycle = 0; cycle < 100; cycle++) {
+        // Add many entries
+        for (let i = 0; i < 100; i++) {
+          cache.set(`cycle-${cycle}-key-${i}`, `value-${i}`);
+        }
+        
+        // Clear cache
+        cache.clear();
+        
+        // Force garbage collection if available
+        if (global.gc) {
+          global.gc();
+        }
+      }
+      
+      const finalMemory = process.memoryUsage().heapUsed;
+      const memoryIncrease = finalMemory - initialMemory;
+      
+      // Memory increase should be minimal (allowing for some variance)
+      expect(memoryIncrease).toBeLessThan(10 * 1024 * 1024); // Less than 10MB
+    });
+
+    test('should not leak memory with repeated hook mount/unmount', () => {
+      const initialMemory = process.memoryUsage().heapUsed;
+      
+      // Mount and unmount hooks repeatedly
+      for (let i = 0; i < 100; i++) {
+        const { unmount } = renderHook(() => useCache<string>(`test-cache-${i}`));
+        
+        act(() => {
+          // Perform some operations
+        });
+        
+        unmount();
+        
+        // Force garbage collection if available
+        if (global.gc) {
+          global.gc();
+        }
+      }
+      
+      const finalMemory = process.memoryUsage().heapUsed;
+      const memoryIncrease = finalMemory - initialMemory;
+      
+      // Memory increase should be minimal
+      expect(memoryIncrease).toBeLessThan(5 * 1024 * 1024); // Less than 5MB
+    });
+  });
+
+  describe('Performance Regression Tests', () => {
+    test('should maintain performance with large cache sizes', () => {
+      const sizes = [100, 1000, 5000, 10000];
+      
+      sizes.forEach(size => {
+        const cache = new Cache<string>({ maxSize: size });
+        const startTime = performance.now();
+        
+        // Fill cache
+        for (let i = 0; i < size; i++) {
+          cache.set(`key${i}`, `value${i}`);
+        }
+        
+        // Random access pattern
+        for (let i = 0; i < size; i++) {
+          const randomIndex = Math.floor(Math.random() * size);
+          cache.get(`key${randomIndex}`);
+        }
+        
+        const endTime = performance.now();
+        const duration = endTime - startTime;
+        
+        // Performance should scale reasonably
+        const opsPerMs = (size * 2) / duration; // inserts + gets
+        expect(opsPerMs).toBeGreaterThan(10); // At least 10 ops per ms
+      });
+    });
+
+    test('should maintain pattern matching performance', () => {
+      const patternComplexities = [
+        'simple:*',
+        'complex:*:pattern:*:here',
+        'very:complex:pattern:*:with:many:parts:*:and:sections',
+      ];
+      
+      patternComplexities.forEach(pattern => {
+        const startTime = performance.now();
+        
+        // Test many matches
+        for (let i = 0; i < 1000; i++) {
+          PatternMatcher.matchesPattern(`test:${i}:value`, pattern);
+        }
+        
+        const endTime = performance.now();
+        const duration = endTime - startTime;
+        
+        // Even complex patterns should be fast
+        expect(duration).toBeLessThan(50); // Less than 50ms for 1000 matches
+      });
+    });
+  });
+});

package/src/storage/cache/__tests__/setup.ts

@@ -0,0 +1,19 @@
+/**
+ * Test Setup
+ */
+
+// Mock console methods in test environment
+(global as any).console = {
+  ...console,
+  log: jest.fn(),
+  warn: jest.fn(),
+  error: jest.fn(),
+};
+
+// Mock __DEV__ for testing
+(global as any).__DEV__ = true;
+
+// Mock timers globally
+jest.useFakeTimers({
+  doNotFake: ['nextTick', 'setImmediate']
+});