@umituz/react-native-storage 2.6.22 → 2.6.24

package/src/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/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/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/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/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