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

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

@@ -0,0 +1,146 @@
+/**
+ * In-Memory Cache
+ */
+
+import type { CacheEntry, CacheConfig, CacheStats, EvictionStrategy } from './types/Cache';
+import { CacheStatsTracker } from './CacheStatsTracker';
+import { PatternMatcher } from './PatternMatcher';
+import { LRUStrategy } from './strategies/LRUStrategy';
+import { LFUStrategy } from './strategies/LFUStrategy';
+import { FIFOStrategy } from './strategies/FIFOStrategy';
+import { TTLStrategy } from './strategies/TTLStrategy';
+
+export class Cache<T = unknown> {
+  private store = new Map<string, CacheEntry<T>>();
+  private config: Required<CacheConfig>;
+  private statsTracker = new CacheStatsTracker();
+  private strategies = {
+    lru: new LRUStrategy<T>(),
+    lfu: new LFUStrategy<T>(),
+    fifo: new FIFOStrategy<T>(),
+    ttl: new TTLStrategy<T>(),
+  };
+
+  constructor(config: CacheConfig = {}) {
+    this.config = {
+      maxSize: config.maxSize || 100,
+      defaultTTL: config.defaultTTL || 5 * 60 * 1000,
+      onEvict: config.onEvict || (() => { }),
+      onExpire: config.onExpire || (() => { }),
+    };
+  }
+
+  set(key: string, value: T, ttl?: number): void {
+    if (this.store.size >= this.config.maxSize && !this.store.has(key)) {
+      this.evictOne('lru');
+    }
+
+    const entry: CacheEntry<T> = {
+      value,
+      timestamp: Date.now(),
+      ttl: ttl || this.config.defaultTTL,
+      accessCount: 0,
+      lastAccess: Date.now(),
+    };
+
+    this.store.set(key, entry);
+    this.statsTracker.updateSize(this.store.size);
+
+    if (typeof __DEV__ !== 'undefined' && __DEV__ && typeof console !== 'undefined' && console.log) {
+      console.log(`Cache: Set key "${key}" with TTL ${entry.ttl}ms`);
+    }
+  }
+
+  get(key: string): T | undefined {
+    const entry = this.store.get(key);
+
+    if (!entry) {
+      this.statsTracker.recordMiss();
+      return undefined;
+    }
+
+    if (this.isExpired(entry)) {
+      this.delete(key);
+      this.statsTracker.recordMiss();
+      this.statsTracker.recordExpiration();
+      this.config.onExpire(key, entry);
+      return undefined;
+    }
+
+    entry.accessCount++;
+    entry.lastAccess = Date.now();
+    this.statsTracker.recordHit();
+    return entry.value;
+  }
+
+  has(key: string): boolean {
+    const entry = this.store.get(key);
+    if (!entry) return false;
+    if (this.isExpired(entry)) {
+      this.delete(key);
+      return false;
+    }
+    return true;
+  }
+
+  delete(key: string): boolean {
+    const deleted = this.store.delete(key);
+    if (deleted) {
+      this.statsTracker.updateSize(this.store.size);
+    }
+    return deleted;
+  }
+
+  invalidatePattern(pattern: string): number {
+    const regex = PatternMatcher.convertPatternToRegex(pattern);
+    let invalidatedCount = 0;
+
+    for (const key of this.store.keys()) {
+      if (regex.test(key)) {
+        this.store.delete(key);
+        invalidatedCount++;
+      }
+    }
+
+    this.statsTracker.updateSize(this.store.size);
+    return invalidatedCount;
+  }
+
+  clear(): void {
+    this.store.clear();
+    this.statsTracker.reset();
+  }
+
+  getStats(): CacheStats {
+    return this.statsTracker.getStats();
+  }
+
+  keys(): string[] {
+    return Array.from(this.store.keys());
+  }
+
+  private isExpired(entry: CacheEntry<T>): boolean {
+    return Date.now() - entry.timestamp > entry.ttl;
+  }
+
+  private evictOne(strategy: EvictionStrategy): void {
+    const evictionStrategy = this.strategies[strategy];
+    if (!evictionStrategy) return;
+
+    const keyToEvict = evictionStrategy.findKeyToEvict(this.store);
+    if (keyToEvict) {
+      const entry = this.store.get(keyToEvict);
+      this.store.delete(keyToEvict);
+      this.statsTracker.recordEviction();
+      this.statsTracker.updateSize(this.store.size);
+
+      if (typeof __DEV__ !== 'undefined' && __DEV__) {
+        console.log(`Cache: Evicted key "${keyToEvict}" using ${strategy} strategy`);
+      }
+
+      if (entry) {
+        this.config.onEvict(keyToEvict, entry);
+      }
+    }
+  }
+}

package/src/storage/cache/domain/CacheManager.md

@@ -0,0 +1,83 @@
+# Cache Manager
+
+Centralized singleton manager for multiple named cache instances with lifecycle management.
+
+## Overview
+
+CacheManager provides centralized management for multiple named cache instances. Located at `src/cache/domain/CacheManager.ts`.
+
+## Strategies
+
+### Cache Separation
+- Use separate cache instances for different data types or domains
+- Create environment-specific caches (development vs production)
+- Implement feature-flagged caches for experimental functionality
+- Use cache hierarchy patterns (L1/L2) for performance optimization
+
+### Lifecycle Management
+- Initialize caches on first access (lazy loading)
+- Implement cache warmup strategies for critical data
+- Monitor cache statistics for performance optimization
+- Clean up unused caches periodically
+
+### Multi-Cache Patterns
+- Use cache segmentation by data type or domain
+- Implement namespaced cache organization
+- Apply cache hierarchy with promotion/demotion
+- Use preset configurations for different TTL ranges
+
+## Restrictions
+
+### Cache Creation
+- DO NOT create duplicate caches with the same name
+- DO NOT use generic or non-descriptive cache names
+- DO NOT mix unrelated data types in the same cache
+- DO NOT create caches without considering TTL requirements
+
+### Cache Deletion
+- DO NOT delete caches that might be in use
+- DO NOT rely on manual cleanup without automated strategy
+- DO NOT delete caches during critical operations
+
+### Configuration
+- DO NOT use extremely short TTLs (< 1 second) as they're ineffective
+- DO NOT use extremely long TTLs (> 1 year) to avoid stale data
+- DO NOT ignore cache size limits
+
+## Rules
+
+### Cache Naming
+- MUST use descriptive names indicating cached data type
+- MUST use consistent naming convention (kebab-case or camelCase)
+- MUST include domain/business context in cache name
+- MUST document cache purpose in code comments
+
+### Cache Configuration
+- MUST specify appropriate maxSize for expected data volume
+- MUST set defaultTTL based on data change frequency
+- MUST provide onEvict callback for monitoring in development
+- MUST use preset configurations for standard TTL ranges
+
+### Cache Access
+- MUST use `getCache()` to retrieve or create cache instances
+- MUST check if cache exists before operations when appropriate
+- MUST call `deleteCache()` to remove unused caches
+- MUST use `getCacheNames()` to monitor active caches
+
+### Cache Lifecycle
+- MUST implement warmup for frequently-accessed data
+- MUST monitor cache statistics (hit rate, size) periodically
+- MUST clean up unused caches in long-running applications
+- MUST call `clearAll()` in test beforeEach hooks
+
+### Testing
+- MUST clear all caches in test setup
+- MUST use isolated cache names in tests
+- MUST delete test caches after test completion
+- MUST test cache creation, retrieval, and deletion
+
+### Error Handling
+- MUST handle cache deletion failures gracefully
+- MUST log cache creation with configuration
+- MUST monitor cache statistics for anomalies
+- MUST implement fallback for cache manager failures

package/src/storage/cache/domain/CacheManager.ts

@@ -0,0 +1,48 @@
+/**
+ * Cache Manager
+ * Manages multiple cache instances
+ */
+
+import { Cache } from './Cache';
+import type { CacheConfig } from './types/Cache';
+
+export class CacheManager {
+  private static instance: CacheManager;
+  private caches = new Map<string, Cache<any>>();
+
+  private constructor() {}
+
+  static getInstance(): CacheManager {
+    if (!CacheManager.instance) {
+      CacheManager.instance = new CacheManager();
+    }
+    return CacheManager.instance;
+  }
+
+  getCache<T>(name: string, config?: CacheConfig): Cache<T> {
+    if (!this.caches.has(name)) {
+      this.caches.set(name, new Cache<T>(config));
+    }
+    return this.caches.get(name)!;
+  }
+
+  deleteCache(name: string): boolean {
+    const cache = this.caches.get(name);
+    if (cache) {
+      cache.clear();
+      return this.caches.delete(name);
+    }
+    return false;
+  }
+
+  clearAll(): void {
+    this.caches.forEach((cache) => cache.clear());
+    this.caches.clear();
+  }
+
+  getCacheNames(): string[] {
+    return Array.from(this.caches.keys());
+  }
+}
+
+export const cacheManager = CacheManager.getInstance();

package/src/storage/cache/domain/CacheStatsTracker.md

@@ -0,0 +1,169 @@
+# Cache Statistics Tracking
+
+Real-time monitoring and metrics for cache performance and health.
+
+## Overview
+
+Cache statistics tracker for monitoring cache operations and performance. Located at `src/cache/domain/`.
+
+## Strategies
+
+### Metrics Collection
+- Use CacheStatsTracker for real-time statistics
+- Track hits, misses, evictions, and expirations
+- Calculate hit rate automatically
+- Monitor cache size changes
+
+### Performance Monitoring
+- Monitor hit rate for cache effectiveness
+- Track eviction rates for capacity issues
+- Monitor expiration rates for TTL optimization
+- Track size changes for memory management
+
+### Health Analysis
+- Use hit rate as primary health indicator
+- Monitor eviction rate for capacity planning
+- Track expiration patterns for TTL tuning
+- Compare metrics over time for trends
+
+### Alerting
+- Set thresholds for critical metrics
+- Alert on low hit rates
+- Alert on high eviction rates
+- Alert on abnormal expiration patterns
+
+## Restrictions
+
+### Statistics Tracking
+- DO NOT track statistics without cache instance
+- DO NOT ignore statistics in production
+- DO NOT reset statistics without clear reason
+- DO NOT track sensitive data in statistics
+
+### Performance Impact
+- DO NOT track statistics with high overhead
+- DO NOT collect statistics synchronously
+- DO NOT store unlimited history
+- DO NOT impact cache performance for statistics
+
+### Alert Configuration
+- DO NOT set thresholds without baseline data
+- DO NOT alert on single metric violations
+- DO NOT create alert storms
+- DO NOT ignore alert fatigue
+
+### Data Collection
+- DO NOT collect PII in statistics
+- DO NOT store raw cache data in stats
+- DO NOT expose detailed stats in production logs
+- DO NOT aggregate without retention policy
+
+## Rules
+
+### CacheStatsTracker Implementation
+- MUST provide recordHit() method
+- MUST provide recordMiss() method
+- MUST provide recordEviction() method
+- MUST provide recordExpiration() method
+- MUST provide updateSize() method
+- MUST provide getStats() method
+- MUST provide reset() method
+
+### CacheStats Interface
+- MUST include size: number (current entry count)
+- MUST include hits: number (total cache hits)
+- MUST include misses: number (total cache misses)
+- MUST include evictions: number (total evictions)
+- MUST include expirations: number (total expirations)
+- MUST include hitRate: number (calculated ratio 0-1)
+
+### Hit Rate Calculation
+- MUST calculate as hits / (hits + misses)
+- MUST return 0 when no operations recorded
+- MUST handle division by zero
+- MUST provide value between 0 and 1
+- MUST update on every hit or miss
+
+### Statistics Updates
+- MUST update statistics atomically
+- MUST increment counters for each operation
+- MUST recalculate hit rate after each hit/miss
+- MUST update size on cache modifications
+- MUST not lose updates on concurrent operations
+
+### Reset Behavior
+- MUST reset all counters to zero
+- MUST reset hit rate to 0
+- MUST be callable after cache clear
+- MUST not affect cache data
+- MUST be idempotent
+
+### Thread Safety
+- MUST handle concurrent record operations
+- MUST not corrupt statistics on parallel updates
+- MUST provide consistent reads
+- MUST use atomic operations for counters
+- MUST prevent race conditions
+
+### Performance Requirements
+- MUST have minimal overhead on cache operations
+- MUST not block cache operations
+- MUST use efficient data structures
+- MUST not cause memory leaks
+- MUST be suitable for production use
+
+### Monitoring Integration
+- MUST provide access to current statistics
+- MUST support statistics export
+- MUST enable real-time monitoring
+- MUST support custom metrics
+- MUST integrate with logging systems
+
+### Health Check Support
+- MUST enable health assessment
+- MUST support threshold-based alerts
+- MUST provide trend analysis capability
+- MUST enable performance diagnostics
+- MUST support optimization recommendations
+
+### Data Retention
+- MUST provide current statistics
+- MUST not store unlimited historical data
+- MUST support snapshot capability
+- MUST enable time-series analysis
+- MUST handle memory limits
+
+### Type Safety
+- MUST provide TypeScript types
+- MUST use numeric types for metrics
+- MUST ensure type-safe operations
+- MUST prevent type coercion errors
+- MUST support generic usage
+
+### Export and Serialization
+- MUST support JSON serialization
+- MUST provide readable format
+- MUST include all metrics
+- MUST preserve data types
+- MUST enable external analysis
+
+### Best Practices Compliance
+- MUST follow performance monitoring best practices
+- MUST enable observability
+- MUST support debugging
+- MUST provide actionable insights
+- MUST not impact cache functionality
+
+### Documentation Requirements
+- MUST document all metrics clearly
+- MUST explain hit rate calculation
+- MUST provide usage guidance
+- MUST specify performance characteristics
+- MUST not include code examples in documentation
+
+### Testing Requirements
+- MUST test all recording methods
+- MUST test hit rate calculation accuracy
+- MUST test reset functionality
+- MUST test concurrent operations
+- MUST verify thread safety

package/src/storage/cache/domain/CacheStatsTracker.ts

@@ -0,0 +1,49 @@
+/**
+ * Cache Statistics Tracker
+ */
+
+import type { CacheStats } from './types/Cache';
+
+export class CacheStatsTracker {
+  private stats: CacheStats = {
+    size: 0,
+    hits: 0,
+    misses: 0,
+    evictions: 0,
+    expirations: 0,
+  };
+
+  recordHit(): void {
+    this.stats.hits++;
+  }
+
+  recordMiss(): void {
+    this.stats.misses++;
+  }
+
+  recordEviction(): void {
+    this.stats.evictions++;
+  }
+
+  recordExpiration(): void {
+    this.stats.expirations++;
+  }
+
+  updateSize(size: number): void {
+    this.stats.size = size;
+  }
+
+  getStats(): CacheStats {
+    return { ...this.stats };
+  }
+
+  reset(): void {
+    this.stats = {
+      size: 0,
+      hits: 0,
+      misses: 0,
+      evictions: 0,
+      expirations: 0,
+    };
+  }
+}

package/src/storage/cache/domain/CachedValue.md

@@ -0,0 +1,97 @@
+# Cache Entry (CachedValue)
+
+Cached value entity with TTL and metadata for time-based expiration.
+
+## Overview
+
+CachedValue represents a single cached entry with value, timestamp, TTL, and access tracking. Located at `src/cache/domain/CachedValue.ts`.
+
+## Strategies
+
+### TTL Management
+- Set TTL based on data change frequency
+- Use shorter TTL for frequently changing data
+- Use longer TTL for static or rarely changing data
+- Consider sliding expiration for frequently accessed data
+
+### Metadata Tracking
+- Track creation timestamp for age calculation
+- Track TTL for expiration checking
+- Optionally track access count for analytics
+- Optionally track last access time for LRU eviction
+
+### Validation Strategy
+- Always validate TTL is within reasonable bounds
+- Check expiration before returning cached values
+- Validate structure when deserializing from storage
+- Implement type guards for type safety
+
+## Restrictions
+
+### TTL Values
+- DO NOT use negative TTL values
+- DO NOT use zero TTL (data expires immediately)
+- DO NOT use extremely short TTLs (< 1000ms)
+- DO NOT use extremely long TTLs (> 10 years)
+
+### Metadata Modification
+- DO NOT modify timestamp after creation (except for sliding expiration)
+- DO NOT manually adjust TTL to extend cache lifetime
+- DO NOT alter data property directly (use cache methods)
+- DO NOT assume timestamp is in seconds (it's milliseconds)
+
+### Serialization
+- DO NOT serialize without validating structure first
+- DO NOT deserialize without type checking
+- DO NOT assume cached values are always valid JSON
+- DO NOT mix different data types in same cache entry
+
+## Rules
+
+### Creation
+- MUST use `createCachedValue()` factory function
+- MUST specify TTL in milliseconds
+- MUST capture current timestamp in milliseconds
+- MUST include all required fields (data, timestamp, ttl)
+
+### Expiration Checking
+- MUST use `isCacheExpired()` before accessing cached data
+- MUST compare timestamp + ttl against current time
+- MUST treat expired entries as non-existent
+- MUST remove expired entries from cache
+
+### TTL Calculation
+- MUST use `getRemainingTTL()` to check time until expiration
+- MUST return 0 or negative for expired entries
+- MUST use milliseconds for all time calculations
+- MUST handle edge cases (zero, negative, very large TTL)
+
+### Age Tracking
+- MUST use `getCacheAge()` to determine entry age
+- MUST calculate age as (current time - timestamp)
+- MUST return age in milliseconds
+- MUST use age for analytics and monitoring
+
+### Serialization/Deserialization
+- MUST validate structure after deserialization
+- MUST use TypeScript type guards for type safety
+- MUST handle JSON parsing errors gracefully
+- MUST preserve timestamp and TTL during serialization
+
+### Type Safety
+- MUST use generic type parameter for data field
+- MUST enforce type checking with `isValidCachedValue()`
+- MUST validate data structure when loading from storage
+- MUST handle type mismatches gracefully
+
+### Error Handling
+- MUST handle invalid TTL values gracefully
+- MUST throw descriptive errors for malformed entries
+- MUST log expiration warnings in development
+- MUST provide fallback for corrupted cache entries
+
+### Testing
+- MUST test expiration logic with various TTL values
+- MUST test edge cases (zero, negative, very large TTL)
+- MUST test serialization/deserialization roundtrip
+- MUST test type validation with type guards

package/src/storage/cache/domain/ErrorHandler.md

@@ -0,0 +1,99 @@
+# Cache Error Handler
+
+Centralized error handling for cache operations with recovery and monitoring.
+
+## Overview
+
+ErrorHandler provides unified error handling for cache operations with logging, recovery, and alerting capabilities. Located at `src/cache/domain/ErrorHandler.ts`.
+
+## Strategies
+
+### Error Handling Strategy
+- Use silent failure for non-critical cache operations
+- Implement retry logic for transient failures
+- Provide fallback values for degraded operation
+- Use graceful degradation when cache fails
+
+### Recovery Strategy
+- Implement auto-recovery for corrupted cache data
+- Clear and rebuild cache on unrecoverable errors
+- Use fallback storage mechanism when primary fails
+- Implement circuit breaker pattern for repeated failures
+
+### Monitoring Strategy
+- Track error counts by error type
+- Aggregate recent errors for pattern analysis
+- Alert on error threshold exceeded
+- Log errors with context for debugging
+
+## Restrictions
+
+### Error Handling
+- DO NOT silently swallow all errors
+- DO NOT throw errors from error handlers (recursive)
+- DO NOT block application on cache errors
+- DO NOT retry indefinitely on persistent failures
+
+### Error Reporting
+- DO NOT log sensitive data in error messages
+- DO NOT include full stack traces in production logs
+- DO NOT send errors to remote services without rate limiting
+- DO NOT overwhelm logging with duplicate errors
+
+### Recovery Attempts
+- DO NOT attempt recovery more than configured retry limit
+- DO NOT clear cache without logging reason
+- DO NOT fall back to insecure storage mechanisms
+- DO NOT continue operations after critical failures
+
+## Rules
+
+### Error Creation
+- MUST use `CacheError` class for all cache errors
+- MUST include descriptive error message
+- MUST specify error code from standard codes
+- MUST attach cause error when wrapping exceptions
+
+### Error Codes
+- MUST use `CACHE_ERROR` for generic cache errors
+- MUST use `CACHE_FULL` when cache at capacity
+- MUST use `CACHE_INVALID_KEY` for invalid keys
+- MUST use `CACHE_EXPIRED` for expiration errors
+- MUST use `CACHE_SERIALIZATION` for serialization failures
+- MUST use `CACHE_DESERIALIZATION` for deserialization failures
+
+### Error Handling
+- MUST call `ErrorHandler.handle()` for all caught errors
+- MUST include context information when available
+- MUST log errors before recovery attempts
+- MUST not throw from error handlers
+
+### Error Logging
+- MUST log error code and message
+- MUST log operation context (get/set/delete)
+- MUST log cache name when applicable
+- MUST log cause error if present
+
+### Error Recovery
+- MUST implement maximum retry limit
+- MUST log recovery attempts
+- MUST fall back to safe state on failure
+- MUST notify monitoring after recovery
+
+### Error Tracking
+- MUST increment error counter for each error type
+- MUST alert when error count exceeds threshold
+- MUST reset counters after alert or periodically
+- MUST aggregate recent errors for analysis
+
+### Context Enrichment
+- MUST include operation type in error context
+- MUST include cache key when applicable
+- MUST include cache name for multi-cache scenarios
+- MUST include timestamp for error correlation
+
+### Testing
+- MUST test error handling with mock errors
+- MUST test recovery logic with failure scenarios
+- MUST test error tracking with repeated errors
+- MUST test logging output format