@umituz/react-native-storage 2.6.23 → 2.6.25

package/src/domain/value-objects/README.md

@@ -0,0 +1,120 @@
+# Value Objects
+
+Type-safe storage key value objects for scoped data organization.
+
+## Overview
+
+Value objects for creating structured, type-safe storage keys with scoping. Located at `src/domain/value-objects/`.
+
+## Strategies
+
+### Key Organization
+- Use factory functions for key creation
+- Organize keys by scope (app, user, organization)
+- Use consistent separator (`:`) throughout
+- Enable type-safe key generation
+
+### Scoping Strategy
+- Use app scope for application-wide data
+- Use user scope for user-specific data
+- Use organization scope for organization data
+- Create custom scopes for specific use cases
+
+### Type Safety
+- Use generic type parameters for section names
+- Enable type inference for key structure
+- Prevent key collisions through naming
+- Support key pattern matching
+
+### Key Formats
+- Follow consistent format: `scope:id:section`
+- Use descriptive section names
+- Document key patterns in code comments
+- Support pattern-based invalidation
+
+## Restrictions
+
+### Key Creation
+- DO NOT create keys without factory functions
+- DO NOT use dynamic strings as keys
+- DO NOT mix different key scopes
+- DO NOT create ambiguous key structures
+
+### Key Formats
+- DO NOT use inconsistent separators
+- DO NOT use empty section names
+- DO NOT use special characters in keys
+- DO NOT create overly deep hierarchies
+
+### Type Safety
+- DO NOT use `any` for key sections
+- DO NOT skip type parameters
+- DO NOT cast keys to strings prematurely
+- DO NOT mix different key types
+
+## Rules
+
+### Factory Functions
+- MUST use createUserKey() for user data
+- MUST use createAppKey() for app data
+- MUST use createUserScopedKey() for user-scoped data
+- MUST use createOrganizationScopedKey() for organization data
+- MUST validate input parameters
+
+### Key Format
+- MUST use `:` as separator
+- MUST follow pattern: `scope:identifier:section`
+- MUST include all three parts
+- MUST be descriptive and searchable
+- MUST be consistent across codebase
+
+### Type Safety
+- MUST use generic type parameter for section names
+- MUST provide type inference
+- MUST enforce valid section names
+- MUST support template literal types
+- MUST prevent invalid combinations
+
+### Key Usage
+- MUST use with storage repository methods
+- MUST maintain type safety through usage chain
+- MUST support pattern-based operations
+- MUST enable efficient key lookup
+
+### Key Serialization
+- MUST convert to string for storage operations
+- MUST preserve structure information
+- MUST support reverse transformation
+- MUST handle special characters correctly
+
+### Pattern Matching
+- MUST support wildcard patterns for invalidation
+- MUST use consistent separator in patterns
+- MUST enable bulk operations
+- MUST handle pattern edge cases
+
+### Type Guards
+- MUST provide isUserKey() guard
+- MUST provide isAppKey() guard
+- MUST provide isOrgKey() guard
+- MUST use predicate return types
+- MUST validate key structure
+
+### Error Handling
+- MUST validate key format
+- MUST throw descriptive errors for invalid keys
+- MUST include key in error context
+- MUST handle edge cases gracefully
+
+### Documentation
+- MUST document key patterns
+- MUST specify format for each scope
+- MUST provide examples in comments
+- MUST warn about common mistakes
+
+### Testing Requirements
+- MUST test key creation with valid inputs
+- MUST test key validation with invalid inputs
+- MUST test type guard behavior
+- MUST test pattern matching
+- MUST test serialization

package/src/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/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/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/infrastructure/repositories/README.md

@@ -0,0 +1,121 @@
+# Storage Repositories
+
+Repository pattern implementation for data persistence with error handling.
+
+## Overview
+
+AsyncStorageRepository provides storage operations with Result pattern for error handling. Located at `src/infrastructure/repositories/`.
+
+## Strategies
+
+### Result Pattern
+- Return Result objects instead of throwing exceptions
+- Use success/failure states for predictable error handling
+- Include error details in failure results
+- Allow graceful degradation when operations fail
+
+### Serialization Strategy
+- Automatically serialize objects to JSON
+- Deserialize with type safety using generics
+- Handle circular reference errors gracefully
+- Support all JSON-serializable types
+
+### Error Handling Strategy
+- Categorize errors by type (read, write, serialization)
+- Include key name in error context
+- Preserve original error as cause
+- Log errors for debugging
+
+### Performance Strategy
+- Use parallel operations for batch operations
+- Implement chunking for large datasets
+- Avoid synchronous operations on main thread
+- Cache frequently accessed values
+
+## Restrictions
+
+### Storage Operations
+- DO NOT store non-JSON-serializable data (functions, class instances)
+- DO NOT store circular references
+- DO NOT use undefined values (use null instead)
+- DO NOT store extremely large payloads (> 1MB) without chunking
+
+### Error Handling
+- DO NOT ignore error states in Result objects
+- DO NOT throw exceptions from repository methods
+- DO NOT return null for missing keys (use defaultValue)
+- DO NOT suppress error logging in production
+
+### Type Safety
+- DO NOT use `any` type for stored values
+- DO NOT skip type parameters on generic methods
+- DO NOT assume Result is always successful
+- DO NOT cast results without checking success flag
+
+### Performance
+- DO NOT perform sequential operations in loops (use parallel)
+- DO NOT read same key multiple times without caching
+- DO NOT write to storage on every state change (debounce)
+- DO NOT store redundant data
+
+## Rules
+
+### Interface Implementation
+- MUST implement IStorageRepository interface completely
+- MUST return StorageResult<T> for all methods
+- MUST include error details in failure results
+- MUST handle all exceptions internally
+
+### Method Signatures
+- MUST provide generic type parameter for type safety
+- MUST accept defaultValue parameter for getItem methods
+- MUST return Promise for all async operations
+- MUST preserve key names in error messages
+
+### Error Handling
+- MUST wrap all storage operations in try-catch
+- MUST return failure Result on errors
+- MUST include error code and message
+- MUST log errors before returning failure
+
+### Serialization
+- MUST use JSON.stringify for setItem operations
+- MUST use JSON.parse for getItem operations
+- MUST handle JSON parsing errors
+- MUST validate deserialized structure
+
+### Type Safety
+- MUST enforce type parameter consistency
+- MUST use type guards for runtime validation
+- MUST provide type inference for return values
+- MUST avoid type assertions when possible
+
+### Result Objects
+- MUST set success flag to true or false
+- MUST include data in success results
+- MUST include error in failure results
+- MUST check success flag before accessing data
+
+### Singleton Usage
+- MUST use exported singleton instance
+- MUST NOT create multiple repository instances
+- MUST reset state between tests
+- MUST clear storage in test setup
+
+### Testing
+- MUST mock repository for unit tests
+- MUST use real repository for integration tests
+- MUST clear storage before each test
+- MUST test both success and failure scenarios
+
+### Performance
+- MUST use Promise.all for parallel operations
+- MUST implement debouncing for frequent writes
+- MUST use appropriate chunk sizes for large data
+- MUST monitor storage size limits
+
+### Error Categories
+- MUST use StorageReadError for read failures
+- MUST use StorageWriteError for write failures
+- MUST use StorageSerializationError for serialization failures
+- MUST use StorageDeserializationError for parsing failures