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

package/src/storage/cache/domain/strategies/__tests__/EvictionStrategies.test.ts

@@ -0,0 +1,293 @@
+/**
+ * Eviction Strategies Tests
+ */
+
+import { LRUStrategy } from '../LRUStrategy';
+import { LFUStrategy } from '../LFUStrategy';
+import { FIFOStrategy } from '../FIFOStrategy';
+import { TTLStrategy } from '../TTLStrategy';
+import type { CacheEntry } from '../../types/Cache';
+
+describe('Eviction Strategies', () => {
+  const createMockEntries = (): Map<string, CacheEntry<string>> => {
+    const entries = new Map<string, CacheEntry<string>>();
+    const now = Date.now();
+    
+    entries.set('key1', {
+      value: 'value1',
+      timestamp: now - 1000,
+      ttl: 5000,
+      accessCount: 5,
+      lastAccess: now - 500,
+    });
+    
+    entries.set('key2', {
+      value: 'value2',
+      timestamp: now - 2000,
+      ttl: 5000,
+      accessCount: 3,
+      lastAccess: now - 100,
+    });
+    
+    entries.set('key3', {
+      value: 'value3',
+      timestamp: now - 3000,
+      ttl: 5000,
+      accessCount: 10,
+      lastAccess: now - 1500,
+    });
+    
+    return entries;
+  };
+
+  describe('LRUStrategy', () => {
+    let strategy: LRUStrategy<string>;
+
+    beforeEach(() => {
+      strategy = new LRUStrategy<string>();
+    });
+
+    test('should evict least recently used key', () => {
+      const entries = createMockEntries();
+      const keyToEvict = strategy.findKeyToEvict(entries);
+      
+      // key3 has the oldest lastAccess time
+      expect(keyToEvict).toBe('key3');
+    });
+
+    test('should return undefined for empty entries', () => {
+      const entries = new Map<string, CacheEntry<string>>();
+      const keyToEvict = strategy.findKeyToEvict(entries);
+      
+      expect(keyToEvict).toBeUndefined();
+    });
+
+    test('should handle single entry', () => {
+      const entries = new Map<string, CacheEntry<string>>();
+      entries.set('key1', {
+        value: 'value1',
+        timestamp: Date.now(),
+        ttl: 5000,
+        accessCount: 1,
+        lastAccess: Date.now(),
+      });
+      
+      const keyToEvict = strategy.findKeyToEvict(entries);
+      expect(keyToEvict).toBe('key1');
+    });
+  });
+
+  describe('LFUStrategy', () => {
+    let strategy: LFUStrategy<string>;
+
+    beforeEach(() => {
+      strategy = new LFUStrategy<string>();
+    });
+
+    test('should evict least frequently used key', () => {
+      const entries = createMockEntries();
+      const keyToEvict = strategy.findKeyToEvict(entries);
+      
+      // key2 has the lowest access count (3)
+      expect(keyToEvict).toBe('key2');
+    });
+
+    test('should return undefined for empty entries', () => {
+      const entries = new Map<string, CacheEntry<string>>();
+      const keyToEvict = strategy.findKeyToEvict(entries);
+      
+      expect(keyToEvict).toBeUndefined();
+    });
+
+    test('should handle ties by choosing first encountered', () => {
+      const entries = new Map<string, CacheEntry<string>>();
+      const now = Date.now();
+      
+      entries.set('key1', {
+        value: 'value1',
+        timestamp: now,
+        ttl: 5000,
+        accessCount: 2,
+        lastAccess: now,
+      });
+      
+      entries.set('key2', {
+        value: 'value2',
+        timestamp: now,
+        ttl: 5000,
+        accessCount: 2,
+        lastAccess: now,
+      });
+      
+      const keyToEvict = strategy.findKeyToEvict(entries);
+      // Should return the first key with lowest count
+      expect(keyToEvict).toBe('key1');
+    });
+  });
+
+  describe('FIFOStrategy', () => {
+    let strategy: FIFOStrategy<string>;
+
+    beforeEach(() => {
+      strategy = new FIFOStrategy<string>();
+    });
+
+    test('should evict first inserted key', () => {
+      const entries = createMockEntries();
+      const keyToEvict = strategy.findKeyToEvict(entries);
+      
+      // Map preserves insertion order, so first key should be evicted
+      expect(keyToEvict).toBe('key1');
+    });
+
+    test('should return undefined for empty entries', () => {
+      const entries = new Map<string, CacheEntry<string>>();
+      const keyToEvict = strategy.findKeyToEvict(entries);
+      
+      expect(keyToEvict).toBeUndefined();
+    });
+
+    test('should handle single entry', () => {
+      const entries = new Map<string, CacheEntry<string>>();
+      entries.set('onlyKey', {
+        value: 'value',
+        timestamp: Date.now(),
+        ttl: 5000,
+        accessCount: 1,
+        lastAccess: Date.now(),
+      });
+      
+      const keyToEvict = strategy.findKeyToEvict(entries);
+      expect(keyToEvict).toBe('onlyKey');
+    });
+  });
+
+  describe('TTLStrategy', () => {
+    let strategy: TTLStrategy<string>;
+
+    beforeEach(() => {
+      strategy = new TTLStrategy<string>();
+    });
+
+    test('should evict key with nearest expiry', () => {
+      const now = Date.now();
+      const entries = new Map<string, CacheEntry<string>>();
+      
+      entries.set('key1', {
+        value: 'value1',
+        timestamp: now - 1000,
+        ttl: 2000, // Expires at now + 1000
+        accessCount: 1,
+        lastAccess: now,
+      });
+      
+      entries.set('key2', {
+        value: 'value2',
+        timestamp: now - 500,
+        ttl: 1000, // Expires at now + 500
+        accessCount: 1,
+        lastAccess: now,
+      });
+      
+      entries.set('key3', {
+        value: 'value3',
+        timestamp: now - 2000,
+        ttl: 3000, // Expires at now + 1000
+        accessCount: 1,
+        lastAccess: now,
+      });
+      
+      const keyToEvict = strategy.findKeyToEvict(entries);
+      
+      // key2 expires soonest (now + 500)
+      expect(keyToEvict).toBe('key2');
+    });
+
+    test('should return undefined for empty entries', () => {
+      const entries = new Map<string, CacheEntry<string>>();
+      const keyToEvict = strategy.findKeyToEvict(entries);
+      
+      expect(keyToEvict).toBeUndefined();
+    });
+
+    test('should handle already expired entries', () => {
+      const now = Date.now();
+      const entries = new Map<string, CacheEntry<string>>();
+      
+      entries.set('key1', {
+        value: 'value1',
+        timestamp: now - 2000,
+        ttl: 1000, // Already expired
+        accessCount: 1,
+        lastAccess: now,
+      });
+      
+      entries.set('key2', {
+        value: 'value2',
+        timestamp: now - 1000,
+        ttl: 2000, // Expires at now + 1000
+        accessCount: 1,
+        lastAccess: now,
+      });
+      
+      const keyToEvict = strategy.findKeyToEvict(entries);
+      
+      // key1 is already expired, should be evicted first
+      expect(keyToEvict).toBe('key1');
+    });
+
+    test('should handle ties by choosing first encountered', () => {
+      const now = Date.now();
+      const entries = new Map<string, CacheEntry<string>>();
+      
+      entries.set('key1', {
+        value: 'value1',
+        timestamp: now - 1000,
+        ttl: 2000, // Both expire at now + 1000
+        accessCount: 1,
+        lastAccess: now,
+      });
+      
+      entries.set('key2', {
+        value: 'value2',
+        timestamp: now - 1000,
+        ttl: 2000, // Both expire at now + 1000
+        accessCount: 1,
+        lastAccess: now,
+      });
+      
+      const keyToEvict = strategy.findKeyToEvict(entries);
+      
+      // Should return the first key with nearest expiry
+      expect(keyToEvict).toBe('key1');
+    });
+  });
+
+  describe('Strategy Integration', () => {
+    test('all strategies should handle different data types', () => {
+      const numberStrategy = new LRUStrategy<number>();
+      const objectStrategy = new LRUStrategy<{ id: string }>();
+      
+      const numberEntries = new Map<string, CacheEntry<number>>();
+      numberEntries.set('num1', {
+        value: 42,
+        timestamp: Date.now(),
+        ttl: 5000,
+        accessCount: 1,
+        lastAccess: Date.now(),
+      });
+      
+      const objectEntries = new Map<string, CacheEntry<{ id: string }>>();
+      objectEntries.set('obj1', {
+        value: { id: 'test' },
+        timestamp: Date.now(),
+        ttl: 5000,
+        accessCount: 1,
+        lastAccess: Date.now(),
+      });
+      
+      expect(numberStrategy.findKeyToEvict(numberEntries)).toBe('num1');
+      expect(objectStrategy.findKeyToEvict(objectEntries)).toBe('obj1');
+    });
+  });
+});

package/src/storage/cache/domain/types/Cache.ts

@@ -0,0 +1,28 @@
+/**
+ * Cache Types
+ */
+
+export interface CacheEntry<T> {
+  value: T;
+  timestamp: number;
+  ttl: number;
+  accessCount: number;
+  lastAccess: number;
+}
+
+export interface CacheConfig {
+  maxSize?: number;
+  defaultTTL?: number;
+  onEvict?: (key: string, entry: CacheEntry<unknown>) => void;
+  onExpire?: (key: string, entry: CacheEntry<unknown>) => void;
+}
+
+export interface CacheStats {
+  size: number;
+  hits: number;
+  misses: number;
+  evictions: number;
+  expirations: number;
+}
+
+export type EvictionStrategy = 'lru' | 'lfu' | 'fifo' | 'ttl';

package/src/storage/cache/domain/types/README.md

@@ -0,0 +1,107 @@
+# Cache Domain Types
+
+TypeScript interfaces and types for cache system.
+
+## Overview
+
+TypeScript type definitions for cache entries, configuration, statistics, and eviction strategies. Located at `src/cache/domain/types/`.
+
+## Strategies
+
+### Cache Entry Definition
+- Define CacheEntry with value, timestamp, TTL, and access tracking
+- Include metadata for eviction strategies
+- Support generic type parameter for cached values
+- Track access patterns for statistics
+
+### Cache Configuration
+- Provide optional configuration parameters
+- Set sensible defaults (maxSize: 100, TTL: 5 minutes)
+- Support lifecycle callbacks (onEvict, onExpire)
+- Allow strategy selection
+
+### Statistics Tracking
+- Track hits, misses, evictions, expirations
+- Calculate hit rate automatically
+- Provide snapshot of cache state
+- Support performance monitoring
+
+### Type Safety
+- Use generic type parameter for cached values
+- Enforce type consistency across operations
+- Provide type inference for cache creation
+- Support nested type structures
+
+## Restrictions
+
+### Type Definitions
+- DO NOT use optional properties for required fields
+- DO NOT mix different data types in same cache without generic
+- DO NOT create circular type dependencies
+- DO NOT omit timestamp or TTL from entries
+
+### Configuration
+- DO NOT allow unlimited cache sizes (must have maxSize)
+- DO NOT set zero or negative TTL as default
+- DO NOT make callbacks required (use optional)
+- DO NOT ignore validation in configuration
+
+### Statistics
+- DO NOT calculate statistics on every access (expensive)
+- DO NOT track unnecessary metrics
+- DO NOT use floating-point for hit rate (use decimal)
+- DO NOT expose internal tracking fields
+
+## Rules
+
+### CacheEntry Interface
+- MUST include value field of generic type T
+- MUST include timestamp (creation time in milliseconds)
+- MUST include ttl (time to live in milliseconds)
+- MUST include accessCount (for LFU strategy)
+- MUST include lastAccess (for LRU strategy)
+
+### CacheConfig Interface
+- MUST provide maxSize with default value of 100
+- MUST provide defaultTTL with default value of 300000 (5 minutes)
+- MUST provide optional onEvict callback
+- MUST provide optional onExpire callback
+- MUST validate configuration values
+
+### CacheStats Interface
+- MUST include size (current entry count)
+- MUST include hits (cache hit count)
+- MUST include misses (cache miss count)
+- MUST include evictions (evicted entry count)
+- MUST include expirations (expired entry count)
+- MUST include hitRate (calculated as hits / (hits + misses))
+
+### Eviction Strategy Type
+- MUST be union of literal types ('lru' | 'lfu' | 'fifo' | 'ttl')
+- MUST support custom strategies
+- MUST be case-sensitive
+- MUST be documented
+
+### Generic Type Parameters
+- MUST use T for cached value type
+- MUST provide type inference
+- MUST support nested types
+- MUST enforce type safety
+
+### Type Guards
+- MUST provide isCacheEntry guard
+- MUST validate all required fields
+- MUST check types of all fields
+- MUST handle edge cases
+
+### Statistics Calculation
+- MUST calculate hitRate as decimal (0-1)
+- MUST update statistics on every operation
+- MUST provide accurate counts
+- MUST not expose internal calculation methods
+
+### Export Rules
+- MUST export all public types
+- MUST use `type` keyword for type-only exports
+- MUST maintain backward compatibility
+- MUST document type changes

package/src/storage/cache/index.ts

@@ -0,0 +1,28 @@
+/**
+ * @umituz/react-native-cache
+ * In-memory caching utilities for React Native
+ */
+
+export { Cache } from './domain/Cache';
+export { CacheManager, cacheManager } from './domain/CacheManager';
+export { CacheStatsTracker } from './domain/CacheStatsTracker';
+export { PatternMatcher } from './domain/PatternMatcher';
+export { ErrorHandler, CacheError } from './domain/ErrorHandler';
+export { TTLCache } from './infrastructure/TTLCache';
+
+export type {
+  CacheEntry,
+  CacheConfig,
+  CacheStats,
+  EvictionStrategy,
+} from './domain/types/Cache';
+
+export type { EvictionStrategy as IEvictionStrategy } from './domain/strategies/EvictionStrategy';
+
+export { LRUStrategy } from './domain/strategies/LRUStrategy';
+export { LFUStrategy } from './domain/strategies/LFUStrategy';
+export { FIFOStrategy } from './domain/strategies/FIFOStrategy';
+export { TTLStrategy as TTLEvictionStrategy } from './domain/strategies/TTLStrategy';
+
+export { useCache } from './presentation/useCache';
+export { useCachedValue } from './presentation/useCachedValue';

package/src/storage/cache/infrastructure/README.md

@@ -0,0 +1,126 @@
+# Cache Infrastructure
+
+Implementation details and concrete implementations of cache domain logic.
+
+## Overview
+
+Infrastructure layer for cache system, providing TTLCache implementation with actual storage and eviction logic. Located at `src/cache/infrastructure/`.
+
+## Strategies
+
+### Cache Implementation
+- Use Map data structure for O(1) operations
+- Implement TTL-based expiration checking
+- Support eviction strategies from domain layer
+- Provide thread-safe operations
+
+### Storage Management
+- Track cache size limits
+- Implement automatic eviction when full
+- Clean up expired entries periodically
+- Support manual cache clearing
+
+### Performance Optimization
+- Minimize memory overhead per entry
+- Use efficient data structures
+- Implement lazy expiration checking
+- Cache frequently accessed metadata
+
+### Integration with Domain
+- Implement interfaces defined in domain layer
+- Use domain types for type safety
+- Follow domain-level strategies and rules
+- Export clean API to presentation layer
+
+## Restrictions
+
+### Implementation
+- DO NOT expose internal storage directly
+- DO NOT bypass eviction strategies
+- DO NOT allow cache size to exceed limit
+- DO NOT store non-serializable data
+
+### Performance
+- DO NOT perform expensive operations on every access
+- DO NOT use blocking operations
+- DO NOT allocate memory unnecessarily
+- DO NOT iterate entire cache for single operations
+
+### Expiration
+- DO NOT ignore expired entries on access
+- DO NOT auto-clean without explicit trigger
+- DO NOT use inconsistent time sources
+- DO NOT rely solely on TTL for memory management
+
+## Rules
+
+### TTLCache Implementation
+- MUST implement Cache interface from domain
+- MUST enforce maxSize limit
+- MUST check expiration on get operations
+- MUST trigger eviction when full
+- MUST provide accurate statistics
+
+### Entry Storage
+- MUST use Map<string, CacheEntry<T>> for storage
+- MUST include all required metadata
+- MUST update timestamps on access
+- MUST validate entry structure
+
+### Expiration Handling
+- MUST check (timestamp + ttl) < Date.now()
+- MUST return undefined for expired entries
+- MUST remove expired entries from storage
+- MUST track expiration statistics
+
+### Eviction Execution
+- MUST call strategy.findKeyToEvict() when full
+- MUST remove selected entry from storage
+- MUST trigger onEvict callback if provided
+- MUST update eviction statistics
+
+### Statistics Tracking
+- MUST increment hits on successful get
+- MUST increment misses on failed get
+- MUST increment evictions on eviction
+- MUST increment expirations on expiration
+- MUST calculate hitRate correctly
+
+### Public Methods
+- MUST implement set(key, value, ttl?)
+- MUST implement get(key) -> T | undefined
+- MUST implement has(key) -> boolean
+- MUST implement delete(key) -> boolean
+- MUST implement clear()
+- MUST implement getStats()
+
+### Configuration Validation
+- MUST validate maxSize > 0
+- MUST validate defaultTTL > 0
+- MUST provide default values
+- MUST reject invalid configuration
+
+### Lifecycle Callbacks
+- MUST call onEvict(entry) when entry evicted
+- MUST call onExpire(entry) when entry expired
+- MUST pass key and entry to callbacks
+- MUST handle callback errors gracefully
+
+### Type Safety
+- MUST use generic type parameter T
+- MUST enforce type consistency
+- MUST provide type inference
+- MUST validate input types where possible
+
+### Thread Safety
+- MUST handle concurrent access appropriately
+- MUST not corrupt cache state
+- MUST provide atomic operations
+- MUST handle race conditions
+
+### Testing Requirements
+- MUST test all eviction strategies
+- MUST test expiration logic
+- MUST test statistics accuracy
+- MUST test edge cases (empty, full, expired)
+- MUST measure performance

package/src/storage/cache/infrastructure/TTLCache.ts

@@ -0,0 +1,103 @@
+/**
+ * TTL Cache
+ * Time-to-live cache with automatic cleanup
+ */
+
+import { Cache } from '../domain/Cache';
+import type { CacheConfig } from '../domain/types/Cache';
+
+export class TTLCache<T = unknown> extends Cache<T> {
+  private cleanupInterval: ReturnType<typeof setInterval> | null = null;
+  private isDestroyed = false;
+  private readonly cleanupIntervalMs: number;
+
+  constructor(config: CacheConfig & { cleanupIntervalMs?: number } = {}) {
+    super(config);
+
+    this.cleanupIntervalMs = config.cleanupIntervalMs || 60000;
+    this.startCleanup();
+  }
+
+  private startCleanup(): void {
+    if (this.isDestroyed) return;
+
+    this.cleanupInterval = setInterval(() => {
+      if (!this.isDestroyed) {
+        this.cleanup();
+      }
+    }, this.cleanupIntervalMs);
+  }
+
+  private cleanup(): void {
+    if (this.isDestroyed) return;
+
+    const keys = this.keys();
+    let cleanedCount = 0;
+    const now = Date.now();
+
+    for (const key of keys) {
+      const entry = (this as any).store.get(key);
+      if (entry && (now - entry.timestamp) > entry.ttl) {
+        (this as any).store.delete(key);
+        cleanedCount++;
+      }
+    }
+
+    if (cleanedCount > 0) {
+      (this as any).statsTracker.updateSize((this as any).store.size);
+      (this as any).statsTracker.recordExpiration();
+
+      if (typeof __DEV__ !== 'undefined' && __DEV__) {
+        console.log(`TTLCache: Cleaned up ${cleanedCount} expired entries`);
+      }
+    }
+  }
+
+  destroy(): void {
+    if (this.isDestroyed) return;
+
+    this.isDestroyed = true;
+
+    if (this.cleanupInterval) {
+      clearInterval(this.cleanupInterval);
+      this.cleanupInterval = null;
+    }
+
+    this.clear();
+  }
+
+  override set(key: string, value: T, ttl?: number): void {
+    if (this.isDestroyed) {
+      if (typeof __DEV__ !== 'undefined' && __DEV__) {
+        console.warn('TTLCache: Attempted to set value on destroyed cache');
+      }
+      return;
+    }
+    super.set(key, value, ttl);
+  }
+
+  override get(key: string): T | undefined {
+    if (this.isDestroyed) {
+      if (typeof __DEV__ !== 'undefined' && __DEV__) {
+        console.warn('TTLCache: Attempted to get value from destroyed cache');
+      }
+      return undefined;
+    }
+    return super.get(key);
+  }
+
+  override has(key: string): boolean {
+    if (this.isDestroyed) return false;
+    return super.has(key);
+  }
+
+  override delete(key: string): boolean {
+    if (this.isDestroyed) return false;
+    return super.delete(key);
+  }
+
+  override clear(): void {
+    if (this.isDestroyed) return;
+    super.clear();
+  }
+}