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

package/src/storage/index.ts

@@ -0,0 +1,175 @@
+/**
+ * Storage Domain - Public API
+ *
+ * Domain-Driven Design (DDD) Architecture
+ *
+ * This is the SINGLE SOURCE OF TRUTH for all storage operations.
+ * ALL imports from the storage domain MUST go through this file.
+ *
+ * Architecture:
+ * - domain: Entities, value objects, errors (business logic)
+ * - application: Ports (interfaces), use cases (not needed for simple CRUD)
+ * - infrastructure: Repository implementation (AsyncStorage adapter)
+ * - presentation: Hooks (React integration)
+ *
+ * Usage:
+ *   import { useStorage, useStorageState, createStore } from '@umituz/react-native-design-system';
+ */
+
+// =============================================================================
+// DOMAIN LAYER - Business Logic
+// =============================================================================
+
+export {
+  StorageKey,
+  createUserKey,
+  createAppKey,
+} from './domain/value-objects/StorageKey';
+
+export type { DynamicStorageKey } from './domain/value-objects/StorageKey';
+
+export {
+  StorageError,
+  StorageReadError,
+  StorageWriteError,
+  StorageDeleteError,
+  StorageSerializationError,
+  StorageDeserializationError,
+} from './domain/errors/StorageError';
+
+export type { StorageResult } from './domain/entities/StorageResult';
+
+export {
+  success,
+  failure,
+  unwrap,
+  map,
+  isSuccess,
+  isFailure,
+} from './domain/entities/StorageResult';
+
+// =============================================================================
+// DOMAIN LAYER - Cached Value Entity
+// =============================================================================
+
+export type { CachedValue } from './domain/entities/CachedValue';
+
+export {
+  createCachedValue,
+  isCacheExpired,
+  getRemainingTTL,
+  getCacheAge,
+} from './domain/entities/CachedValue';
+
+// =============================================================================
+// DOMAIN LAYER - Cache Utilities
+// =============================================================================
+
+export {
+  generateCacheKey,
+  generateListCacheKey,
+  parseCacheKey,
+  isCacheKey,
+} from './domain/utils/CacheKeyGenerator';
+
+// =============================================================================
+// DOMAIN LAYER - Cache Constants
+// =============================================================================
+
+export { TIME_MS, DEFAULT_TTL, CACHE_VERSION } from './domain/constants/CacheDefaults';
+
+// =============================================================================
+// DOMAIN LAYER - Development Utilities
+// =============================================================================
+
+export { isDev, devWarn, devError, devLog } from './domain/utils/devUtils';
+
+// =============================================================================
+// DOMAIN LAYER - Store Types
+// =============================================================================
+
+export type {
+  StoreConfig,
+  PersistedState,
+  SetState,
+  GetState,
+  ActionsCreator,
+} from './domain/types/Store';
+
+// =============================================================================
+// DOMAIN LAYER - Store Factory
+// =============================================================================
+
+export { createStore } from './domain/factories/StoreFactory';
+
+// =============================================================================
+// ZUSTAND - Type Re-exports for Compatibility
+// =============================================================================
+
+export type { StoreApi, UseBoundStore } from 'zustand';
+export type { StateCreator, StoreMutatorIdentifier } from 'zustand/vanilla';
+
+// =============================================================================
+// APPLICATION LAYER - Ports
+// =============================================================================
+
+export type { IStorageRepository } from './application/ports/IStorageRepository';
+
+// =============================================================================
+// INFRASTRUCTURE LAYER - Implementation
+// =============================================================================
+
+export {
+  AsyncStorageRepository,
+  storageRepository,
+} from './infrastructure/repositories/AsyncStorageRepository';
+
+export {
+  storageService,
+  type StateStorage,
+} from './infrastructure/adapters/StorageService';
+
+// =============================================================================
+// PRESENTATION LAYER - Hooks
+// =============================================================================
+
+export { useStorage } from './presentation/hooks/useStorage';
+export { useStorageState } from './presentation/hooks/useStorageState';
+export { useStore } from './presentation/hooks/useStore';
+
+export {
+  usePersistentCache,
+  type PersistentCacheOptions,
+  type PersistentCacheResult,
+} from './presentation/hooks/usePersistentCache';
+
+export { useCacheState } from './presentation/hooks/useCacheState';
+export { CacheStorageOperations } from './presentation/hooks/CacheStorageOperations';
+
+// =============================================================================
+// IN-MEMORY CACHE LAYER (Merged from @umituz/react-native-cache)
+// =============================================================================
+
+export { Cache } from './cache/domain/Cache';
+export { CacheManager, cacheManager } from './cache/domain/CacheManager';
+export { CacheStatsTracker } from './cache/domain/CacheStatsTracker';
+export { PatternMatcher } from './cache/domain/PatternMatcher';
+export { ErrorHandler, CacheError } from './cache/domain/ErrorHandler';
+export { TTLCache } from './cache/infrastructure/TTLCache';
+
+export type {
+  CacheEntry,
+  CacheConfig,
+  CacheStats,
+  EvictionStrategy,
+} from './cache/domain/types/Cache';
+
+export type { EvictionStrategy as IEvictionStrategy } from './cache/domain/strategies/EvictionStrategy';
+
+export { LRUStrategy } from './cache/domain/strategies/LRUStrategy';
+export { LFUStrategy } from './cache/domain/strategies/LFUStrategy';
+export { FIFOStrategy } from './cache/domain/strategies/FIFOStrategy';
+export { TTLStrategy as TTLEvictionStrategy } from './cache/domain/strategies/TTLStrategy';
+
+export { useCache } from './cache/presentation/useCache';
+export { useCachedValue } from './cache/presentation/useCachedValue';

package/src/storage/infrastructure/README.md

@@ -0,0 +1,165 @@
+# Infrastructure Layer
+
+External service adapters and storage repository implementations.
+
+## Overview
+
+Infrastructure layer containing concrete implementations of storage operations. Located at `src/infrastructure/`.
+
+## Directory Structure
+
+- `adapters/` - External service adapters for Zustand persist middleware
+- `repositories/` - Storage repository implementations with Result pattern
+
+## Strategies
+
+### Adapter Implementation
+- Use StorageService adapter for Zustand persist middleware
+- Implement StateStorage interface for Zustand integration
+- Support AsyncStorage, MMKV, and SecureStore adapters
+- Enable custom adapter creation for different storage backends
+
+### Repository Pattern
+- Use AsyncStorageRepository for primary storage operations
+- Implement Result pattern for type-safe error handling
+- Support generic type parameters for type safety
+- Enable serialization/deserialization of complex objects
+
+### Storage Adapters
+- Use storageService for Zustand persist integration
+- Create custom adapters for StateStorage interface
+- Support SecureStore for sensitive data (tokens, credentials)
+- Enable pluggable storage backends
+
+### Error Handling
+- Wrap all storage operations in try-catch blocks
+- Return Result type instead of throwing exceptions
+- Preserve original error context in cause property
+- Support hierarchical error types for specific failures
+
+### Serialization Strategy
+- Use JSON.stringify for object serialization
+- Use JSON.parse for deserialization with type safety
+- Handle circular reference errors
+- Support custom serialization for special types
+
+## Restrictions
+
+### Adapter Implementation
+- DO NOT create adapters without implementing StateStorage interface
+- DO NOT mix different storage backends in single adapter
+- DO NOT skip error handling in adapter methods
+- DO NOT store sensitive data without encryption
+
+### Repository Usage
+- DO NOT create new repository instances (use singleton)
+- DO NOT bypass Result pattern error handling
+- DO NOT use type assertions for type safety
+- DO NOT ignore error codes from storage operations
+
+### Storage Operations
+- DO NOT perform operations without error handling
+- DO NOT assume storage operations succeed
+- DO NOT mix string and object storage methods
+- DO NOT forget to handle null/undefined cases
+
+### Error Handling
+- DO NOT catch and ignore errors silently
+- DO NOT expose sensitive data in error messages
+- DO NOT lose error context when wrapping errors
+- DO NOT create infinite error loops
+
+### Serialization
+- DO NOT serialize unsupported types (functions, symbols)
+- DO NOT assume deserialization always succeeds
+- DO NOT store raw data without validation
+- DO NOT mix data formats in storage
+
+## Rules
+
+### Adapter Implementation
+- MUST implement StateStorage interface for Zustand
+- MUST provide getItem, setItem, removeItem methods
+- MUST return Promise<string | null> from getItem
+- MUST return Promise<void> from setItem and removeItem
+- MUST handle errors gracefully in all methods
+
+### AsyncStorageRepository
+- MUST use singleton pattern (export storageRepository)
+- MUST implement IStorageRepository interface
+- MUST return StorageResult<T> from all methods
+- MUST support generic type parameters
+- MUST serialize objects with JSON.stringify
+- MUST deserialize with JSON.parse and type validation
+- MUST provide default value parameter for getItem
+
+### Method Signatures
+- MUST provide getItem<T>(key, defaultValue): Promise<StorageResult<T>>
+- MUST provide setItem<T>(key, value): Promise<StorageResult<void>>
+- MUST provide getString(key, defaultValue): Promise<StorageResult<string>>
+- MUST provide setString(key, value): Promise<StorageResult<void>>
+- MUST provide removeItem(key): Promise<StorageResult<void>>
+- MUST provide hasItem(key): Promise<boolean>
+- MUST provide clearAll(): Promise<StorageResult<void>>
+
+### Error Handling
+- MUST wrap all storage operations in try-catch
+- MUST return failure() with StorageError on catch
+- MUST preserve original error in cause property
+- MUST include storage key in error context
+- MUST use specific error types (StorageReadError, StorageWriteError)
+- MUST not expose sensitive data in error messages
+
+### Result Pattern
+- MUST return success(data) on successful operations
+- MUST return failure(error) on failed operations
+- MUST check result.success before accessing result.data
+- MUST handle result.error when success is false
+- MUST not throw exceptions from repository methods
+
+### Type Safety
+- MUST use generic type parameters for all value operations
+- MUST infer types from default value parameter
+- MUST not use type assertions for type safety
+- MUST validate types at runtime when deserializing
+- MUST support complex types (objects, arrays)
+
+### Singleton Pattern
+- MUST export single storageRepository instance
+- MUST use singleton for production code
+- MUST enable instance creation for testing
+- MUST not create multiple instances in production
+
+### Custom Adapters
+- MUST implement StateStorage interface
+- MUST handle all required methods
+- MUST support async operations
+- MUST provide error handling
+- MUST be compatible with Zustand persist
+
+### SecureStore Integration
+- MUST use SecureStore for sensitive data only
+- MUST create separate adapter for SecureStore
+- MUST not mix secure and non-secure storage
+- MUST handle SecureStore-specific errors
+
+### Testing Support
+- MUST enable mocking for all methods
+- MUST provide test double support
+- MUST clear state between tests
+- MUST not have hidden dependencies
+- MUST support dependency injection
+
+### Export Rules
+- MUST export storageRepository singleton
+- MUST export AsyncStorageRepository class
+- MUST export storageService adapter
+- MUST export all error types
+- MUST export interface types
+
+### Documentation
+- MUST document all public methods
+- MUST specify error types thrown
+- MUST provide usage examples in separate files
+- MUST warn about common mistakes
+- MUST not include code in README files

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

@@ -0,0 +1,175 @@
+# Storage Adapters
+
+Adapters for integrating Zustand persist middleware with various storage backends.
+
+## Overview
+
+Storage adapter implementations for Zustand persist middleware. Located at `src/infrastructure/adapters/`.
+
+## Strategies
+
+### Adapter Pattern
+- Use StorageService adapter for AsyncStorage integration
+- Implement StateStorage interface for Zustand compatibility
+- Support multiple storage backends (AsyncStorage, MMKV, SecureStore)
+- Enable custom adapter creation for specific needs
+
+### Storage Backend Selection
+- Use AsyncStorage for general-purpose storage
+- Use MMKV for high-performance key-value storage
+- Use SecureStore for sensitive data (tokens, credentials)
+- Use SQLite for complex relational data
+- Use file system for large data or binary files
+
+### Adapter Composition
+- Use namespaced adapters for key isolation
+- Use hybrid adapters for multi-level caching
+- Use encrypted adapters for data security
+- Use migrating adapters for version management
+
+### Error Handling
+- Wrap all storage operations in try-catch blocks
+- Return null on read failures for graceful degradation
+- Log errors for debugging
+- Implement retry logic for transient failures
+
+## Restrictions
+
+### Adapter Implementation
+- DO NOT create adapters without implementing StateStorage interface
+- DO NOT mix synchronous and asynchronous operations
+- DO NOT ignore errors in adapter methods
+- DO NOT create infinite loops in error handlers
+
+### Storage Selection
+- DO NOT use SecureStore for large data
+- DO NOT use AsyncStorage for frequently accessed data
+- DO NOT use file system for simple key-value storage
+- DO NOT use sensitive storage for non-sensitive data
+
+### Adapter Usage
+- DO NOT use the same adapter instance for different purposes
+- DO NOT create adapters without proper error handling
+- DO NOT share adapters between incompatible stores
+- DO NOT forget to clean up resources
+
+### Custom Adapters
+- DO NOT implement custom adapters without necessity
+- DO NOT skip implementing required interface methods
+- DO NOT create adapters with hidden dependencies
+- DO NOT use adapters without testing
+
+## Rules
+
+### StateStorage Interface
+- MUST implement getItem(key): Promise<string | null>
+- MUST implement setItem(key, value): Promise<void>
+- MUST implement removeItem(key): Promise<void>
+- MUST handle all errors gracefully
+- MUST return Promise for all methods
+- MUST be compatible with Zustand persist middleware
+
+### StorageService Adapter
+- MUST use AsyncStorage for storage operations
+- MUST handle serialization/deserialization
+- MUST provide null for missing keys
+- MUST not throw exceptions for missing data
+- MUST be the default adapter for Zustand stores
+
+### Custom Adapter Creation
+- MUST implement StateStorage interface completely
+- MUST handle all three required methods
+- MUST provide async method implementations
+- MUST include error handling
+- MUST be compatible with Zustand persist
+
+### SecureStore Adapter
+- MUST use expo-secure-store for implementation
+- MUST handle SecureStore-specific errors
+- MUST be used only for sensitive data
+- MUST not store large amounts of data
+- MUST provide proper error messages
+
+### MMKV Adapter
+- MUST use react-native-mmkv for implementation
+- MUST initialize MMKV instance properly
+- MUST handle type conversions
+- MUST provide high-performance storage
+- MUST support synchronous operations if needed
+
+### SQLite Adapter
+- MUST initialize database schema on first use
+- MUST use transactions for data integrity
+- MUST handle database connection errors
+- MUST use parameterized queries
+- MUST close connections properly
+
+### File System Adapter
+- MUST validate file paths
+- MUST handle file system permissions
+- MUST provide proper error messages
+- MUST clean up temporary files
+- MUST handle concurrent access safely
+
+### Encrypted Adapter
+- MUST use strong encryption algorithms
+- MUST properly manage encryption keys
+- MUST handle encryption/decryption errors
+- MUST not expose keys in logs
+- MUST use secure key storage
+
+### Namespaced Adapter
+- MUST prefix all keys with namespace
+- MUST use consistent separator (:) in keys
+- MUST enable key isolation between stores
+- MUST prevent key collisions
+- MUST be composable with other adapters
+
+### Hybrid Adapter
+- MUST define clear fallback strategy
+- MUST handle consistency between storages
+- MUST implement read-through caching
+- MUST implement write-through caching
+- MUST handle partial failures gracefully
+
+### Migrating Adapter
+- MUST support version management
+- MUST migrate data on read
+- MUST clean up old data after migration
+- MUST handle migration failures
+- MUST be backward compatible
+
+### Error Handling
+- MUST catch all exceptions in adapter methods
+- MUST return null on read failures
+- MUST log errors for debugging
+- MUST not expose sensitive data in errors
+- MUST provide meaningful error context
+
+### Performance Considerations
+- MUST minimize storage operations
+- MUST batch operations when possible
+- MUST use appropriate storage for data size
+- MUST consider synchronous vs asynchronous operations
+- MUST optimize for read-heavy or write-heavy patterns
+
+### Testing Support
+- MUST enable adapter mocking
+- MUST provide test implementations
+- MUST support dependency injection
+- MUST clear state between tests
+- MUST not have hidden dependencies
+
+### Export Rules
+- MUST export storageService as default adapter
+- MUST export adapter types
+- MUST export adapter utilities
+- MUST document adapter behavior
+- MUST provide usage examples separately
+
+### Documentation
+- MUST document all custom adapters
+- MUST specify storage backend requirements
+- MUST explain adapter behavior
+- MUST warn about limitations
+- MUST not include code in README files

package/src/storage/infrastructure/adapters/StorageService.md

@@ -0,0 +1,103 @@
+# Storage Service
+
+Zustand persist middleware adapter for AsyncStorage integration.
+
+## Overview
+
+StorageService adapts AsyncStorage for use with Zustand's persist middleware, providing automatic state persistence. Located at `src/infrastructure/adapters/StorageService.ts`.
+
+## Strategies
+
+### Storage Adapter Pattern
+- Implement StateStorage interface for Zustand compatibility
+- Wrap AsyncStorage operations in try-catch blocks
+- Provide graceful error handling with logging
+- Return null/undefined on errors to prevent app crashes
+
+### Error Handling Strategy
+- Log all storage errors with context
+- Return null on getItem errors
+- Throw errors on setItem/removeItem for persist middleware
+- Include key name in error messages
+
+### Custom Adapters
+- Create SecureStore adapter for sensitive data (tokens, credentials)
+- Create encrypted storage adapter for high-security requirements
+- Create namespaced adapters for data isolation
+- Create platform-specific adapters (web localStorage vs native)
+
+## Restrictions
+
+### Storage Operations
+- DO NOT use StorageService outside Zustand persist middleware
+- DO NOT store non-serializable data (functions, class instances)
+- DO NOT store large payloads (> 1MB) without chunking strategy
+- DO NOT mix data types in same storage key
+
+### Error Handling
+- DO NOT ignore storage errors in production
+- DO NOT throw on getItem errors (return null instead)
+- DO NOT suppress setItem/removeItem errors
+- DO NOT log sensitive data in error messages
+
+### Custom Adapters
+- DO NOT create adapters without implementing StateStorage interface
+- DO NOT use SecureStore for non-sensitive data (performance)
+- DO NOT use encryption without secure key management
+- DO NOT create platform-specific adapters without Platform checks
+
+## Rules
+
+### Interface Implementation
+- MUST implement `getItem(key: string): Promise<string | null>`
+- MUST implement `setItem(key: string, value: string): Promise<void>`
+- MUST implement `removeItem(key: string): Promise<void>`
+- MUST return Promise for all methods
+
+### Error Handling
+- MUST wrap all AsyncStorage operations in try-catch
+- MUST log errors with key name for debugging
+- MUST return null on getItem errors
+- MUST throw original error on setItem/removeItem errors
+
+### Store Configuration
+- MUST use unique store names across all stores
+- MUST pass storageService as storage option
+- MUST specify store name in persist config
+- MUST handle migration when store schema changes
+
+### Multiple Stores
+- MUST use different store names for different stores
+- MUST ensure store names are unique across app
+- MUST document each store's purpose
+- MUST consider storage key conflicts
+
+### Custom Adapter Creation
+- MUST implement complete StateStorage interface
+- MUST handle errors consistently with base adapter
+- MUST log errors with context
+- MUST document adapter purpose and security model
+
+### Secure Storage
+- MUST use SecureStore for sensitive data only
+- MUST document what data is secure vs regular storage
+- MUST handle SecureStore unavailability (web platform)
+- MUST provide fallback for secure storage failures
+
+### Testing
+- MUST mock StorageService in tests
+- MUST clear storage in test setup
+- MUST test error scenarios
+- MUST test serialization/deserialization
+
+### Version Control
+- MUST increment version when store schema changes
+- MUST implement migrate function for schema changes
+- MUST test migration with old persisted data
+- MUST document migration path
+
+### Performance
+- MUST consider storage operation performance
+- MUST avoid frequent setItem calls (debounce if needed)
+- MUST batch operations when possible
+- MUST monitor storage size limits

package/src/storage/infrastructure/adapters/StorageService.ts

@@ -0,0 +1,49 @@
+/**
+ * Storage Service
+ *
+ * Zustand persist middleware compatible StateStorage implementation.
+ * Uses AsyncStorage under the hood for React Native persistence.
+ */
+
+import AsyncStorage from '@react-native-async-storage/async-storage';
+import { devWarn } from '../../domain/utils/devUtils';
+
+/**
+ * StateStorage interface for Zustand persist middleware
+ */
+export interface StateStorage {
+  getItem: (name: string) => string | null | Promise<string | null>;
+  setItem: (name: string, value: string) => void | Promise<void>;
+  removeItem: (name: string) => void | Promise<void>;
+}
+
+/**
+ * Storage service for Zustand persist middleware
+ * Direct AsyncStorage implementation with proper error handling
+ */
+export const storageService: StateStorage = {
+  getItem: async (name: string): Promise<string | null> => {
+    try {
+      return await AsyncStorage.getItem(name);
+    } catch (error) {
+      devWarn(`StorageService: Failed to get item "${name}"`, error);
+      return null;
+    }
+  },
+
+  setItem: async (name: string, value: string): Promise<void> => {
+    try {
+      await AsyncStorage.setItem(name, value);
+    } catch (error) {
+      devWarn(`StorageService: Failed to set item "${name}"`, error);
+    }
+  },
+
+  removeItem: async (name: string): Promise<void> => {
+    try {
+      await AsyncStorage.removeItem(name);
+    } catch (error) {
+      devWarn(`StorageService: Failed to remove item "${name}"`, error);
+    }
+  },
+};