@umituz/react-native-storage 2.6.22 → 2.6.24

package/src/cache/domain/PatternMatcher.md

@@ -0,0 +1,122 @@
+# Pattern Matcher
+
+Pattern-based cache key matching for bulk operations.
+
+## Overview
+
+PatternMatcher provides wildcard-based cache key matching for efficient bulk invalidation and querying operations. Located at `src/cache/domain/PatternMatcher.ts`.
+
+## Strategies
+
+### Pattern Syntax
+- Use `*` wildcard to match any characters (including empty)
+- Use `:` as default separator for structured keys
+- Support multiple wildcards in single pattern
+- Enable regex-compatible patterns for advanced matching
+
+### Performance Optimization
+- Pre-compile frequently used patterns
+- Cache regex objects for repeated use
+- Use pattern indexing for large key sets
+- Implement batch pattern matching for efficiency
+
+### Bulk Operations
+- Use patterns for invalidating multiple keys
+- Filter keys by pattern for querying
+- Extract parameters from matched keys
+- Support hierarchical invalidation
+
+### Pattern Organization
+- Define pattern constants for reuse
+- Document pattern purpose and structure
+- Use consistent naming conventions
+- Group related patterns together
+
+## Restrictions
+
+### Pattern Usage
+- DO NOT use overly broad patterns (e.g., `*`)
+- DO NOT mix different separators in same pattern
+- DO NOT create ambiguous patterns
+- DO NOT use patterns without documenting purpose
+
+### Performance
+- DO NOT compile same pattern repeatedly
+- DO NOT iterate through all keys for pattern matching
+- DO NOT use patterns for single-key operations
+- DO NOT create complex regex patterns unnecessarily
+
+### Pattern Design
+- DO NOT use special regex characters without escaping
+- DO NOT assume pattern separator is always `:`
+- DO NOT create patterns that match unintended keys
+- DO NOT use patterns for exact key matching
+
+### Testing
+- DO NOT skip testing edge cases (empty keys, special characters)
+- DO NOT forget to test non-matching keys
+- DO NOT assume pattern behavior without tests
+- DO NOT use production data in pattern tests
+
+## Rules
+
+### Pattern Syntax
+- MUST use `*` for wildcard matching
+- MUST use `:` as default separator
+- MUST support multiple wildcards per pattern
+- MUST escape special regex characters in patterns
+
+### Method Implementation
+- MUST provide `convertPatternToRegex(pattern: string): RegExp`
+- MUST provide `matchPattern(key: string, pattern: string): boolean`
+- MUST provide `filterKeys(keys: string[], pattern: string): string[]`
+- MUST handle empty pattern strings gracefully
+
+### Pattern Conversion
+- MUST escape special regex characters except `*`
+- MUST replace `*` with `.*` regex equivalent
+- MUST anchor pattern with `^` and `$`
+- MUST return compiled RegExp object
+
+### Matching Logic
+- MUST use RegExp.test() for matching
+- MUST handle empty key strings
+- MUST return boolean for match results
+- MUST be case-sensitive by default
+
+### Filtering Operations
+- MUST return array of matching keys
+- MUST preserve input array order
+- MUST handle empty input arrays
+- MUST not modify input array
+
+### Performance Optimization
+- MUST cache compiled regex objects
+- MUST provide method to clear pattern cache
+- MUST use efficient iteration for large key sets
+- MUST avoid redundant pattern compilation
+
+### Error Handling
+- MUST throw error for invalid patterns
+- MUST handle null/undefined inputs gracefully
+- MUST log pattern compilation errors
+- MUST provide descriptive error messages
+
+### Pattern Documentation
+- MUST document all pattern constants
+- MUST specify pattern structure and purpose
+- MUST provide examples of matching keys
+- MUST warn about performance implications
+
+### Testing Requirements
+- MUST test wildcard matching
+- MUST test multiple wildcards
+- MUST test non-matching keys
+- MUST test edge cases (empty strings, special characters)
+- MUST test pattern extraction
+
+### Integration with Cache
+- MUST work with Cache.invalidatePattern()
+- MUST support bulk operations
+- MUST handle non-existent keys gracefully
+- MUST return count of invalidated keys

package/src/cache/domain/README.md

@@ -0,0 +1,118 @@
+# Cache Domain
+
+Core business logic and entities for the cache system.
+
+## Overview
+
+Domain layer contains cache entities, managers, error handling, and pattern matching. Located at `src/cache/domain/`.
+
+## Strategies
+
+### Domain Design
+- Implement core cache business logic
+- Define cache entities and value objects
+- Provide error handling and recovery
+- Support pattern-based operations
+
+### Cache Management
+- Use singleton pattern for CacheManager
+- Support multiple named cache instances
+- Provide lifecycle management (create, delete, clear)
+- Track statistics across all caches
+
+### Error Handling
+- Centralize error handling logic
+- Categorize errors by type
+- Provide recovery strategies
+- Log errors for debugging
+
+### Pattern Matching
+- Support wildcard patterns for bulk operations
+- Use consistent separator (`:`)
+- Enable efficient key filtering
+- Support invalidation by pattern
+
+## Restrictions
+
+### Domain Logic
+- DO NOT mix infrastructure concerns in domain
+- DO NOT depend on React or UI libraries
+- DO NOT include I/O operations
+- DO NOT use AsyncStorage directly
+
+### Error Handling
+- DO NOT throw exceptions from domain logic
+- DO NOT ignore error conditions
+- DO NOT lose error context
+- DO NOT create generic error types
+
+### Pattern Matching
+- DO NOT use regex patterns directly (use PatternMatcher)
+- DO NOT mix different separators
+- DO NOT create ambiguous patterns
+- DO NOT use overly broad patterns
+
+### Cache Management
+- DO NOT create unlimited cache instances
+- DO NOT allow duplicate cache names
+- DO NOT leak memory through unreferenced caches
+- DO NOT ignore cache statistics
+
+## Rules
+
+### Cache Entity
+- MUST implement generic Cache<T> class
+- MUST provide CRUD operations (get, set, has, delete)
+- MUST provide clear() operation
+- MUST provide invalidatePattern() operation
+- MUST provide getStats() operation
+
+### CacheManager Singleton
+- MUST provide getCache(name, config?) method
+- MUST return same instance for same name
+- MUST provide deleteCache(name) method
+- MUST provide clearAll() method
+- MUST provide getCacheNames() method
+
+### Error Handling
+- MUST use CacheError base class
+- MUST define specific error types
+- MUST provide error codes
+- MUST preserve error context (key, operation)
+
+### Pattern Matcher
+- MUST provide convertPatternToRegex() method
+- MUST provide matchPattern() method
+- MUST provide filterKeys() method
+- MUST use `*` for wildcard
+- MUST use `:` as default separator
+
+### Statistics Tracking
+- MUST track hits, misses, evictions, expirations
+- MUST calculate hit rate
+- MUST provide getStats() method
+- MUST reset statistics in tests
+
+### Type Safety
+- MUST use generic type parameter <T>
+- MUST enforce type consistency
+- MUST provide type inference
+- MUST avoid `any` types
+
+### Testing Support
+- MUST provide clearAll() for test cleanup
+- MUST reset statistics between tests
+- MUST support mock implementations
+- MUST not have hidden dependencies
+
+### Documentation Rules
+- MUST document all public methods
+- MUST specify parameter types
+- MUST specify return types
+- MUST provide usage examples in comments
+
+### Performance Rules
+- MUST use efficient data structures (Map)
+- MUST provide O(1) access for get/set
+- MUST provide O(n) worst case for pattern operations
+- MUST minimize memory overhead

package/src/cache/domain/strategies/README.md

@@ -0,0 +1,117 @@
+# Cache Eviction Strategies
+
+Algorithms for determining which cache entries to evict when cache is full.
+
+## Overview
+
+Eviction strategies determine which cache entries to remove when the cache reaches its maximum size. Located at `src/cache/domain/strategies/`.
+
+## Strategies
+
+### Strategy Selection
+- Use LRU (Least Recently Used) for most use cases - best general performance
+- Use LFU (Least Frequently Used) for popularity-based caching - keeps frequently accessed items
+- Use FIFO (First In First Out) for simple queue-based caching - lowest overhead
+- Use TTL (Time To Live) for time-sensitive data - required for expiration
+
+### Performance Considerations
+- LRU provides O(1) eviction time with proper data structures
+- LFU provides O(n) eviction time but better for read-heavy workloads
+- FIFO provides O(1) eviction time with minimal overhead
+- TTL requires periodic cleanup but essential for freshness
+
+### Access Pattern Analysis
+- Consider data access patterns when choosing strategy
+- Use LRU for temporal locality (recently accessed likely to be accessed again)
+- Use LFU for frequency-based patterns (popular items should stay)
+- Use FIFO for sequential access patterns
+- Use TTL when data freshness is critical
+
+### Implementation Strategy
+- Implement EvictionStrategy interface for custom strategies
+- Track necessary metadata (access count, last access, timestamp)
+- Provide findKeyToEvict method for selection
+- Update metadata on cache operations
+
+## Restrictions
+
+### Strategy Usage
+- DO NOT use LFU for write-heavy workloads (expensive)
+- DO NOT use FIFO when access patterns matter
+- DO NOT use TTL when data staleness is acceptable
+- DO NOT change strategies after cache creation
+
+### Performance
+- DO NOT implement O(n²) eviction algorithms
+- DO NOT scan entire cache for eviction on every operation
+- DO NOT track unnecessary metadata for chosen strategy
+- DO NOT use complex algorithms for simple use cases
+
+### Custom Strategies
+- DO NOT implement custom strategies without thorough testing
+- DO NOT ignore edge cases (empty cache, single entry)
+- DO NOT create strategies without clear performance benefits
+- DO NOT mix multiple eviction strategies in same cache
+
+## Rules
+
+### EvictionStrategy Interface
+- MUST implement findKeyToEvict(store: Map): string | undefined
+- MUST return undefined when store is empty
+- MUST return single key for eviction
+- MUST handle all cache states correctly
+
+### LRU Strategy
+- MUST track lastAccess timestamp for each entry
+- MUST update lastAccess on every get operation
+- MUST select entry with oldest lastAccess time
+- MUST provide O(1) or O(log n) time complexity
+
+### LFU Strategy
+- MUST track accessCount for each entry
+- MUST increment accessCount on every get operation
+- MUST select entry with lowest accessCount
+- MUST handle ties consistently (use LRU as tiebreaker)
+
+### FIFO Strategy
+- MUST track insertion order for each entry
+- MUST select oldest entry (first inserted)
+- MUST NOT consider access patterns
+- MUST provide O(1) time complexity
+
+### TTL Strategy
+- MUST check timestamp + ttl against current time
+- MUST select expired entries first
+- MUST fall back to secondary strategy if no expired entries
+- MUST handle zero TTL entries (immediate eviction)
+
+### Metadata Updates
+- MUST update eviction metadata on every cache operation
+- MUST update metadata on cache set operations
+- MUST update metadata on cache get operations
+- MUST reset metadata appropriately on cache updates
+
+### Edge Cases
+- MUST handle empty cache (return undefined)
+- MUST handle single entry cache
+- MUST handle all entries with same metadata
+- MUST handle concurrent access safely
+
+### Strategy Selection
+- MUST use LRU as default strategy
+- MUST allow strategy override in configuration
+- MUST validate strategy choice
+- MUST document strategy behavior
+
+### Testing Requirements
+- MUST test eviction with full cache
+- MUST test eviction with empty cache
+- MUST test metadata tracking accuracy
+- MUST test edge cases
+- MUST measure time complexity
+
+### Performance Rules
+- MUST not exceed O(n) for eviction selection
+- MUST not allocate memory during eviction
+- MUST not use blocking operations
+- MUST minimize CPU overhead

package/src/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/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/cache/presentation/README.md

@@ -0,0 +1,123 @@
+# Cache Presentation
+
+React hooks and UI integration for cache system.
+
+## Overview
+
+Presentation layer provides React hooks and components for integrating cache functionality with React applications. Located at `src/cache/presentation/`.
+
+## Strategies
+
+### Hook Design
+- Create hooks for common caching patterns
+- Provide simple, composable APIs
+- Support React Suspense where applicable
+- Handle loading and error states
+
+### React Integration
+- Follow React rules of hooks
+- Support dependency arrays correctly
+- Clean up on component unmount
+- Avoid unnecessary re-renders
+
+### State Management
+- Expose cache state reactively
+- Provide update mechanisms
+- Support invalidation and refresh
+- Handle stale data appropriately
+
+### Performance
+- Use memoization to prevent redundant operations
+- Implement efficient re-render strategies
+- Debounce rapid cache operations
+- Minimize hook overhead
+
+## Restrictions
+
+### Hook Usage
+- DO NOT call hooks outside React components
+- DO NOT call hooks conditionally
+- DO NOT call hooks in loops
+- DO NOT create new cache instances on every render
+
+### State Management
+- DO NOT cause infinite re-render loops
+- DO NOT mutate state directly
+- DO NOT ignore loading states
+- DO NOT swallow errors silently
+
+### Performance
+- DO NOT recreate functions on every render
+- DO NOT subscribe to entire cache when slice needed
+- DO NOT perform expensive operations in render
+- DO NOT cache large computed values in hook state
+
+### Cleanup
+- DO NOT leak subscriptions
+- DO NOT forget cleanup on unmount
+- DO NOT create memory leaks
+- DO NOT leave timers running
+
+## Rules
+
+### Hook Implementation
+- MUST follow React rules of hooks
+- MUST use `use` prefix for hook names
+- MUST provide TypeScript types
+- MUST handle errors gracefully
+
+### useCache Hook
+- MUST accept cache name parameter
+- MUST return cache interface methods
+- MUST provide consistent API across renders
+- MUST handle non-existent cache gracefully
+
+### useCachedValue Hook
+- MUST accept key and fetcher function
+- MUST accept optional TTL parameter
+- MUST return value, setter, and invalidate function
+- MUST handle loading state
+- MUST handle error state
+
+### State Updates
+- MUST trigger re-renders on cache changes
+- MUST use React state for reactive values
+- MUST memoize callbacks to prevent re-renders
+- MUST update state atomically
+
+### Cleanup Behavior
+- MUST clean up subscriptions on unmount
+- MUST cancel pending operations
+- MUST clear timers
+- MUST not leak memory
+
+### Error Handling
+- MUST expose error state to caller
+- MUST allow error recovery
+- MUST log errors in development
+- MUST provide error boundaries for usage
+
+### TypeScript Types
+- MUST provide generic type parameters
+- MUST infer types from cache
+- MUST enforce type safety
+- MUST document complex types
+
+### Performance Rules
+- MUST use useCallback for stable function references
+- MUST use useMemo for expensive computations
+- MUST provide stable references across renders
+- MUST minimize re-render frequency
+
+### Testing Requirements
+- MUST test with @testing-library/react-hooks
+- MUST test cleanup behavior
+- MUST test error scenarios
+- MUST test type safety
+- MUST test re-render behavior
+
+### Export Rules
+- MUST export hooks from index file
+- MUST provide consistent naming
+- MUST document hook contracts
+- MUST maintain backward compatibility