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

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

@@ -0,0 +1,42 @@
+/**
+ * Error Handler for Cache Operations
+ */
+
+export class CacheError extends Error {
+  constructor(message: string, public readonly code: string) {
+    super(message);
+    this.name = 'CacheError';
+  }
+}
+
+export class ErrorHandler {
+  static handle(error: unknown, context: string): never {
+    if (error instanceof CacheError) {
+      throw error;
+    }
+    
+    if (error instanceof Error) {
+      throw new CacheError(`${context}: ${error.message}`, 'CACHE_ERROR');
+    }
+    
+    throw new CacheError(`${context}: Unknown error`, 'UNKNOWN_ERROR');
+  }
+
+  static async withTimeout<T>(
+    promise: Promise<T>,
+    timeoutMs: number,
+    context: string
+  ): Promise<T> {
+    const timeoutPromise = new Promise<never>((_, reject) => {
+      setTimeout(() => {
+        reject(new CacheError(`${context}: Operation timed out after ${timeoutMs}ms`, 'TIMEOUT'));
+      }, timeoutMs);
+    });
+
+    try {
+      return await Promise.race([promise, timeoutPromise]);
+    } catch (error) {
+      this.handle(error, context);
+    }
+  }
+}

package/src/storage/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/storage/cache/domain/PatternMatcher.ts

@@ -0,0 +1,30 @@
+/**
+ * Pattern Matcher for Cache Keys
+ */
+
+const regexCache = new Map<string, RegExp>();
+
+export class PatternMatcher {
+  static convertPatternToRegex(pattern: string): RegExp {
+    if (regexCache.has(pattern)) {
+      return regexCache.get(pattern)!;
+    }
+
+    const escapedPattern = pattern
+      .replace(/[.+?^${}()|[\]\\]/g, '\\$&')
+      .replace(/\*/g, '.*');
+    const regex = new RegExp(`^${escapedPattern}$`);
+    
+    regexCache.set(pattern, regex);
+    return regex;
+  }
+
+  static matchesPattern(key: string, pattern: string): boolean {
+    const regex = this.convertPatternToRegex(pattern);
+    return regex.test(key);
+  }
+
+  static clearCache(): void {
+    regexCache.clear();
+  }
+}

package/src/storage/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/storage/cache/domain/__tests__/Cache.test.ts

@@ -0,0 +1,293 @@
+/* eslint-disable @typescript-eslint/no-unused-vars */
+/**
+ * Cache Class Tests
+ */
+
+import { Cache } from '../Cache';
+import type { CacheConfig } from '../types/Cache';
+
+describe('Cache', () => {
+  let cache: Cache<string>;
+
+  beforeEach(() => {
+    cache = new Cache<string>({ maxSize: 3, defaultTTL: 1000 });
+  });
+
+  describe('Basic Operations', () => {
+    test('should set and get values', () => {
+      cache.set('key1', 'value1');
+      expect(cache.get('key1')).toBe('value1');
+    });
+
+    test('should return undefined for non-existent keys', () => {
+      expect(cache.get('nonexistent')).toBeUndefined();
+    });
+
+    test('should check if key exists', () => {
+      cache.set('key1', 'value1');
+      expect(cache.has('key1')).toBe(true);
+      expect(cache.has('nonexistent')).toBe(false);
+    });
+
+    test('should delete keys', () => {
+      cache.set('key1', 'value1');
+      expect(cache.delete('key1')).toBe(true);
+      expect(cache.has('key1')).toBe(false);
+      expect(cache.delete('nonexistent')).toBe(false);
+    });
+
+    test('should clear all keys', () => {
+      cache.set('key1', 'value1');
+      cache.set('key2', 'value2');
+      cache.clear();
+      expect(cache.has('key1')).toBe(false);
+      expect(cache.has('key2')).toBe(false);
+      expect(cache.getStats().size).toBe(0);
+    });
+
+    test('should return all keys', () => {
+      cache.set('key1', 'value1');
+      cache.set('key2', 'value2');
+      const keys = cache.keys();
+      expect(keys).toContain('key1');
+      expect(keys).toContain('key2');
+      expect(keys).toHaveLength(2);
+    });
+  });
+
+  describe('TTL (Time To Live)', () => {
+    beforeEach(() => {
+      jest.useFakeTimers();
+    });
+
+    afterEach(() => {
+      jest.useRealTimers();
+    });
+
+    test('should expire entries after TTL', () => {
+      cache.set('key1', 'value1', 1000);
+      expect(cache.get('key1')).toBe('value1');
+
+      jest.advanceTimersByTime(1001);
+      expect(cache.get('key1')).toBeUndefined();
+    });
+
+    test('should use default TTL when not specified', () => {
+      cache.set('key1', 'value1');
+      expect(cache.get('key1')).toBe('value1');
+
+      jest.advanceTimersByTime(1001);
+      expect(cache.get('key1')).toBeUndefined();
+    });
+
+    test('should call onExpire callback when entry expires', () => {
+      const onExpire = jest.fn();
+      const cacheWithCallback = new Cache<string>({ 
+        defaultTTL: 1000, 
+        onExpire 
+      });
+
+      cacheWithCallback.set('key1', 'value1');
+      jest.advanceTimersByTime(1001);
+      cacheWithCallback.get('key1'); // Trigger expiration check
+
+      expect(onExpire).toHaveBeenCalledWith('key1', expect.objectContaining({
+        value: 'value1',
+        timestamp: expect.any(Number),
+        ttl: 1000,
+        accessCount: 0,
+        lastAccess: expect.any(Number)
+      }));
+    });
+  });
+
+  describe('Eviction', () => {
+    test('should evict LRU when cache is full', () => {
+      const onEvict = jest.fn();
+      const cacheWithCallback = new Cache<string>({ 
+        maxSize: 2, 
+        onEvict 
+      });
+
+      cacheWithCallback.set('key1', 'value1');
+      cacheWithCallback.set('key2', 'value2');
+      
+      // Access key1 to make it recently used
+      cacheWithCallback.get('key1');
+      
+      // Add third item, should evict key2 (least recently used)
+      cacheWithCallback.set('key3', 'value3');
+      
+      expect(cacheWithCallback.has('key1')).toBe(true);
+      expect(cacheWithCallback.has('key2')).toBe(false);
+      expect(cacheWithCallback.has('key3')).toBe(true);
+      expect(onEvict).toHaveBeenCalledWith('key2', expect.any(Object));
+    });
+
+    test('should not evict when updating existing key', () => {
+      cache.set('key1', 'value1');
+      cache.set('key2', 'value2');
+      cache.set('key3', 'value3');
+      
+      // Update existing key, should not cause eviction
+      cache.set('key1', 'value1-updated');
+      
+      expect(cache.has('key1')).toBe(true);
+      expect(cache.has('key2')).toBe(true);
+      expect(cache.has('key3')).toBe(true);
+      expect(cache.get('key1')).toBe('value1-updated');
+    });
+  });
+
+  describe('Pattern Invalidation', () => {
+    test('should invalidate keys matching pattern', () => {
+      cache.set('user:1', 'user1');
+      cache.set('user:2', 'user2');
+      cache.set('post:1', 'post1');
+      cache.set('admin', 'admin');
+
+      const invalidatedCount = cache.invalidatePattern('user:*');
+      
+      expect(invalidatedCount).toBe(2);
+      expect(cache.has('user:1')).toBe(false);
+      expect(cache.has('user:2')).toBe(false);
+      expect(cache.has('post:1')).toBe(true);
+      expect(cache.has('admin')).toBe(true);
+    });
+
+    test('should handle complex patterns', () => {
+      cache.set('user:1:profile', 'profile1');
+      cache.set('user:2:profile', 'profile2');
+      cache.set('user:1:settings', 'settings1');
+      cache.set('post:1', 'post1');
+
+      const invalidatedCount = cache.invalidatePattern('user:*:profile');
+      
+      expect(invalidatedCount).toBe(2);
+      expect(cache.has('user:1:profile')).toBe(false);
+      expect(cache.has('user:2:profile')).toBe(false);
+      expect(cache.has('user:1:settings')).toBe(true);
+      expect(cache.has('post:1')).toBe(true);
+    });
+
+    test('should return 0 for non-matching patterns', () => {
+      cache.set('user:1', 'user1');
+      cache.set('post:1', 'post1');
+
+      const invalidatedCount = cache.invalidatePattern('admin:*');
+      
+      expect(invalidatedCount).toBe(0);
+      expect(cache.has('user:1')).toBe(true);
+      expect(cache.has('post:1')).toBe(true);
+    });
+  });
+
+  describe('Statistics', () => {
+    test('should track cache statistics correctly', () => {
+      // Initial stats
+      let stats = cache.getStats();
+      expect(stats.size).toBe(0);
+      expect(stats.hits).toBe(0);
+      expect(stats.misses).toBe(0);
+      expect(stats.evictions).toBe(0);
+      expect(stats.expirations).toBe(0);
+
+      // Set some values
+      cache.set('key1', 'value1');
+      cache.set('key2', 'value2');
+      
+      stats = cache.getStats();
+      expect(stats.size).toBe(2);
+
+      // Hit
+      cache.get('key1');
+      stats = cache.getStats();
+      expect(stats.hits).toBe(1);
+      expect(stats.misses).toBe(0);
+
+      // Miss
+      cache.get('nonexistent');
+      stats = cache.getStats();
+      expect(stats.hits).toBe(1);
+      expect(stats.misses).toBe(1);
+
+      // Delete
+      cache.delete('key1');
+      stats = cache.getStats();
+      expect(stats.size).toBe(1);
+
+      // Clear
+      cache.clear();
+      stats = cache.getStats();
+      expect(stats.size).toBe(0);
+      expect(stats.hits).toBe(0);
+      expect(stats.misses).toBe(0);
+    });
+
+    test('should return immutable stats object', () => {
+      cache.set('key1', 'value1');
+      const stats1 = cache.getStats();
+      const stats2 = cache.getStats();
+      
+      expect(stats1).toEqual(stats2);
+      expect(stats1).not.toBe(stats2); // Different references
+    });
+  });
+
+  describe('Access Count and Last Access', () => {
+    test('should track access count and last access time', () => {
+      const startTime = Date.now();
+      
+      cache.set('key1', 'value1');
+      
+      // First access
+      cache.get('key1');
+      let stats = cache.getStats();
+      
+      // Second access
+      jest.advanceTimersByTime(100);
+      cache.get('key1');
+      
+      // Verify access tracking (internal implementation detail)
+      expect(cache.get('key1')).toBe('value1');
+    });
+  });
+
+  describe('Configuration', () => {
+    test('should use custom configuration', () => {
+      const customConfig: CacheConfig = {
+        maxSize: 10,
+        defaultTTL: 5000,
+        onEvict: jest.fn(),
+        onExpire: jest.fn(),
+      };
+
+      const customCache = new Cache<string>(customConfig);
+      
+      customCache.set('key1', 'value1');
+      expect(customCache.get('key1')).toBe('value1');
+      
+      // Should not expire before custom TTL
+      jest.advanceTimersByTime(4000);
+      expect(customCache.get('key1')).toBe('value1');
+      
+      // Should expire after custom TTL
+      jest.advanceTimersByTime(1001);
+      expect(customCache.get('key1')).toBeUndefined();
+    });
+
+    test('should use default configuration when not provided', () => {
+      const defaultCache = new Cache<string>();
+      
+      defaultCache.set('key1', 'value1');
+      expect(defaultCache.get('key1')).toBe('value1');
+      
+      // Should use default TTL (5 minutes)
+      jest.advanceTimersByTime(5 * 60 * 1000 - 1);
+      expect(defaultCache.get('key1')).toBe('value1');
+      
+      jest.advanceTimersByTime(2);
+      expect(defaultCache.get('key1')).toBeUndefined();
+    });
+  });
+});