@umituz/react-native-storage 2.6.22 → 2.6.24

package/src/domain/README.md

@@ -0,0 +1,128 @@
+# Domain Layer
+
+Core business logic, entities, value objects, and error handling for storage operations.
+
+## Overview
+
+The domain layer contains the fundamental business logic and types used throughout the storage system. Located at `src/domain/`.
+
+## Architecture
+
+```
+domain/
+├── constants/        # Time constants and defaults
+├── entities/         # Domain entities (CachedValue, Result)
+├── errors/           # Error classes and types
+├── factories/        # Zustand store factory
+├── types/            # TypeScript type definitions
+├── utils/            # Helper functions
+└── value-objects/    # StorageKey value objects
+```
+
+## Strategies
+
+### Value Objects
+- Use StorageKey for type-safe storage keys
+- Create scoped keys (user, organization, app)
+- Use key factories for consistent key generation
+- Document key structure patterns
+
+### Error Handling
+- Use specific error types for different failure scenarios
+- Apply Result pattern for type-safe error handling
+- Preserve error context (key, operation, cause)
+- Categorize errors by type (read, write, serialization)
+
+### Store Factory
+- Use createStore for Zustand store creation
+- Implement persist for state persistence
+- Use versioning and migration for schema changes
+- Apply partialize to select persisted state
+
+### Key Generation
+- Use generateCacheKey for cache entries
+- Use generateListCacheKey for list queries
+- Document key patterns in code comments
+- Use parseCacheKey for key extraction
+
+## Restrictions
+
+### Value Objects
+- DO NOT create keys without using factory functions
+- DO NOT mix key scopes (user vs app vs org)
+- DO NOT use dynamic strings as storage keys
+- DO NOT create ambiguous key structures
+
+### Error Handling
+- DO NOT throw exceptions from Result types
+- DO NOT use generic Error class
+- DO NOT lose error context when wrapping errors
+- DO NOT ignore error states in Result objects
+
+### Store Factory
+- DO NOT create stores without names
+- DO NOT use persist without version number
+- DO NOT change schema without migration
+- DO NOT persist sensitive data without encryption
+
+### Type Safety
+- DO NOT use `any` for type parameters
+- DO NOT skip type guards for runtime validation
+- DO NOT assume Result is always success
+- DO NOT cast values without validation
+
+## Rules
+
+### Value Objects (StorageKey)
+- MUST use factory functions for key creation
+- MUST use consistent key structure (prefix:params)
+- MUST include scope prefix (app:, user:, org:)
+- MUST document key patterns
+
+### Error Classes
+- MUST extend StorageError base class
+- MUST include error code
+- MUST preserve error context (key, operation)
+- MUST attach cause error when wrapping exceptions
+
+### Result Pattern
+- MUST use success() for successful operations
+- MUST use failure() for errors
+- MUST check success flag before accessing data
+- MUST provide type parameter for data
+
+### Store Factory
+- MUST provide unique store name
+- MUST define initial state
+- MUST specify version when persist is enabled
+- MUST implement migrate function for schema changes
+
+### Type Definitions
+- MUST use generic type parameters
+- MUST provide type inference
+- MUST enforce type safety
+- MUST document complex types
+
+### Constants
+- MUST use TIME_MS for time values
+- MUST use DEFAULT_TTL for cache TTL
+- MUST define constants in separate files
+- MUST export constants for external use
+
+### Utilities
+- MUST validate input parameters
+- MUST handle edge cases gracefully
+- MUST provide type guards for validation
+- MUST log warnings in development
+
+### Testing
+- MUST test error scenarios
+- MUST test Result pattern operations
+- MUST validate key generation
+- MUST test store creation and persistence
+
+### Documentation
+- MUST document complex types
+- MUST specify error codes
+- MUST provide usage examples in comments
+- MUST warn about common mistakes

package/src/domain/constants/README.md

@@ -0,0 +1,105 @@
+# Domain Constants
+
+Time constants and default values for storage and cache operations.
+
+## Overview
+
+Constant values for time-based calculations and default configuration. Located at `src/domain/constants/`.
+
+## Strategies
+
+### Time Constants
+- Use TIME_MS for all time-based calculations
+- Provide constants for common time units
+- Enable readable time calculations
+- Support time arithmetic
+
+### Default Values
+- Use DEFAULT_TTL for standard cache lifetime
+- Set sensible defaults for common use cases
+- Document default value rationale
+- Allow override for specific needs
+
+### Version Management
+- Use CACHE_VERSION for cache key versioning
+- Increment version on breaking changes
+- Support migration between versions
+- Include version in cache keys
+
+## Restrictions
+
+### Time Calculations
+- DO NOT use hardcoded millisecond values
+- DO NOT calculate time values inline
+- DO NOT mix time units (seconds vs milliseconds)
+- DO NOT use magic numbers for time
+
+### Constants
+- DO NOT redefine TIME_MS values elsewhere
+- DO NOT modify constants at runtime
+- DO NOT use deprecated constants
+- DO NOT create duplicate constants
+
+### Version Management
+- DO NOT skip version numbers
+- DO NOT reuse old versions
+- DO NOT forget to update CACHE_VERSION
+- DO NOT change version format
+
+## Rules
+
+### TIME_MS Constants
+- MUST provide SECOND (1000ms)
+- MUST provide MINUTE (60000ms)
+- MUST provide HOUR (3600000ms)
+- MUST provide DAY (86400000ms)
+- MUST provide WEEK (604800000ms)
+- MUST be in milliseconds
+
+### DEFAULT_TTL
+- MUST be set to 300000 (5 minutes)
+- MUST be used for cache when no TTL specified
+- MUST balance freshness and performance
+- MUST be documented
+
+### CACHE_VERSION
+- MUST be integer value
+- MUST start at 1
+- MUST increment on breaking changes
+- MUST be included in cache keys
+
+### Constant Usage
+- MUST use TIME_MS for all time calculations
+- MUST use DEFAULT_TTL for default cache lifetime
+- MUST use CACHE_VERSION for versioning
+- MUST not calculate values inline
+
+### Time Arithmetic
+- MUST use TIME_MS constants for calculations
+- MUST support multiplication for extended periods
+- MUST be readable and maintainable
+- MUST avoid magic numbers
+
+### Version Control
+- MUST increment CACHE_VERSION on schema changes
+- MUST implement migration for old versions
+- MUST document breaking changes
+- MUST support backward compatibility where possible
+
+### Export Rules
+- MUST export all constants
+- MUST use const for immutability
+- MUST organize constants by purpose
+- MUST provide TypeScript types
+
+### Documentation
+- MUST document time units clearly
+- MUST specify values in milliseconds
+- MUST explain default value choices
+- MUST warn about common mistakes
+
+### Testing Requirements
+- MUST test time constant values
+- MUST verify version increment logic
+- MUST test migration between versions
+- MUST validate default TTL usage

package/src/domain/entities/README.md

@@ -0,0 +1,109 @@
+# Domain Entities
+
+Core entities for the storage domain including CachedValue and Result pattern.
+
+## Overview
+
+Fundamental domain entities used throughout the storage system. Located at `src/domain/entities/`.
+
+## Strategies
+
+### CachedValue Entity
+- Use for cache entries with TTL and metadata
+- Track creation timestamp for expiration
+- Support TTL-based expiration checking
+- Enable age calculation and remaining TTL queries
+
+### Result Pattern
+- Use discriminated union for type-safe error handling
+- Provide success/failure states with type narrowing
+- Include error context in failure state
+- Support functional transformations (map, unwrap)
+
+### Entity Composition
+- Combine CachedValue with cache operations
+- Use Result for all storage operations
+- Enable error propagation without exceptions
+- Support functional error handling patterns
+
+## Restrictions
+
+### CachedValue
+- DO NOT modify timestamp after creation (except for sliding expiration)
+- DO NOT adjust TTL manually to extend lifetime
+- DO NOT create CachedValue without factory function
+- DO NOT use negative or zero TTL values
+
+### Result Pattern
+- DO NOT throw exceptions from Result operations
+- DO NOT access data without checking success flag
+- DO NOT ignore failure states
+- DO NOT mix success and failure in same type
+
+### Type Safety
+- DO NOT use `any` for Result data type
+- DO NOT skip type guards when checking results
+- DO NOT cast results without validation
+- DO NOT create circular type dependencies
+
+## Rules
+
+### CachedValue Entity
+- MUST use generic type parameter <T> for data
+- MUST include timestamp (milliseconds since epoch)
+- MUST include ttl (time to live in milliseconds)
+- MUST provide factory function for creation
+- MUST validate structure on creation
+
+### Result Type
+- MUST use discriminated union with success flag
+- MUST include data in success state
+- MUST include error in failure state
+- MUST provide type parameter for data type
+- MUST enable type narrowing with success flag
+
+### Factory Functions
+- MUST provide createCachedValue(data, ttl)
+- MUST provide success(data) factory
+- MUST provide failure(error) factory
+- MUST validate input parameters
+- MUST return properly typed entities
+
+### Type Guards
+- MUST provide isSuccess() type guard
+- MUST provide isFailure() type guard
+- MUST provide isCacheExpired() validator
+- MUST use predicate return type for type narrowing
+- MUST validate all required fields
+
+### Utility Functions
+- MUST provide getRemainingTTL() for cache entries
+- MUST provide getCacheAge() for cache entries
+- MUST provide unwrap() for Result extraction
+- MUST provide map() for Result transformation
+- MUST handle edge cases (null, undefined)
+
+### Error Handling
+- MUST preserve error context in failures
+- MUST attach cause errors when wrapping
+- MUST include error codes for categorization
+- MUST log errors in development mode
+
+### Serialization
+- MUST support JSON serialization for CachedValue
+- MUST validate structure after deserialization
+- MUST handle circular reference errors
+- MUST provide type guards for validation
+
+### Testing Requirements
+- MUST test entity creation and validation
+- MUST test expiration logic with various TTL values
+- MUST test Result pattern operations
+- MUST test type guard behavior
+- MUST test edge cases
+
+### Documentation
+- MUST document all public methods
+- MUST specify parameter types and return types
+- MUST provide usage guidance without code examples
+- MUST warn about common mistakes

package/src/domain/errors/README.md

@@ -0,0 +1,126 @@
+# Storage Errors
+
+Error classes and error handling strategies for storage operations.
+
+## Overview
+
+Hierarchical error classes for storage operations with context preservation. Located at `src/domain/errors/`.
+
+## Strategies
+
+### Error Hierarchy
+- Use StorageError as base class for all storage errors
+- Create specific error types for different operations
+- Preserve error context (key, operation, cause)
+- Enable error type checking with instanceof
+
+### Error Categories
+- StorageReadError for read failures
+- StorageWriteError for write failures
+- StorageDeleteError for delete failures
+- StorageSerializationError for serialization failures
+- StorageDeserializationError for parsing failures
+
+### Error Handling Strategy
+- Use Result pattern instead of throwing exceptions
+- Preserve original error as cause property
+- Include error codes for programmatic handling
+- Log errors with full context
+
+### Error Recovery
+- Implement retry logic for transient failures
+- Provide fallback values for graceful degradation
+- Clear corrupted data when appropriate
+- Alert monitoring systems for critical errors
+
+## Restrictions
+
+### Error Creation
+- DO NOT throw generic Error class
+- DO NOT lose error context when wrapping
+- DO NOT create error types without clear purpose
+- DO NOT use strings for error codes
+
+### Error Handling
+- DO NOT catch and ignore errors silently
+- DO NOT suppress error logging in production
+- DO NOT retry indefinitely on persistent failures
+- DO NOT expose sensitive data in error messages
+
+### Error Types
+- DO NOT mix different error categories
+- DO NOT create circular error hierarchies
+- DO NOT omit error code from custom errors
+- DO NOT cause infinite error loops
+
+## Rules
+
+### Error Base Class
+- MUST extend Error class
+- MUST include code property (string)
+- MUST preserve stack trace
+- MUST accept cause parameter for wrapping
+- MUST include message parameter
+
+### Specific Error Types
+- MUST extend StorageError base class
+- MUST include key property for storage errors
+- MUST include cause property when wrapping
+- MUST use specific error codes
+- MUST set appropriate error name
+
+### Error Codes
+- MUST use format: CATEGORY_ERROR (e.g., STORAGE_READ_ERROR)
+- MUST be unique across error types
+- MUST be descriptive and searchable
+- MUST follow naming convention
+- MUST be documented
+
+### Error Context
+- MUST include storage key in storage errors
+- MUST include original operation type
+- MUST attach cause error when wrapping
+- MUST preserve stack trace
+- MUST include timestamp for debugging
+
+### Error Handling Patterns
+- MUST use try-catch for all storage operations
+- MUST check error types with instanceof
+- MUST log errors with full context
+- MUST provide error recovery where possible
+- MUST not expose sensitive data
+
+### Custom Error Creation
+- MUST extend StorageError for custom errors
+- MUST provide unique error code
+- MUST include all required context
+- MUST document error purpose
+- MUST follow naming conventions
+
+### Error Logging
+- MUST log error code and message
+- MUST log error context (key, operation)
+- MUST log cause error if present
+- MUST log stack trace in development
+- MUST not log sensitive data
+
+### Error Testing
+- MUST test error creation
+- MUST test error type checking
+- MUST test error context preservation
+- MUST test error logging
+- MUST test error recovery logic
+
+### Type Safety
+- MUST use instanceof for type checking
+- MUST use type guards where appropriate
+- MUST enforce error codes as literal types
+- MUST provide TypeScript types
+- MUST not use `any` for error types
+
+### Error Recovery
+- MUST implement retry limits
+- MUST provide fallback strategies
+- MUST clear corrupted data when detected
+- MUST alert on critical failures
+- MUST document recovery behavior

package/src/domain/factories/README.md

@@ -0,0 +1,138 @@
+# Domain Factories
+
+Factory functions for creating Zustand stores with persistence.
+
+## Overview
+
+Factory functions for creating Zustand stores with AsyncStorage persistence. Located at `src/domain/factories/`.
+
+## Strategies
+
+### Store Creation
+- Use createStore() factory for all Zustand stores
+- Provide type inference for state and actions
+- Support optional persistence
+- Enable store composition
+
+### Persistence Strategy
+- Use persist middleware for AsyncStorage integration
+- Configure storage adapter (StorageService)
+- Support selective persistence (partialize)
+- Enable versioning and migration
+
+### Store Configuration
+- Require unique store name
+- Define initial state clearly
+- Create actions with set/get helpers
+- Support middleware configuration
+
+### Type Safety
+- Infer state types from initial state
+- Separate state and actions types
+- Enable type-safe selectors
+- Support generic store types
+
+## Restrictions
+
+### Store Creation
+- DO NOT create stores without factory
+- DO NOT duplicate store names
+- DO NOT mix state and actions unnecessarily
+- DO NOT create stores without clear purpose
+
+### Persistence
+- DO NOT enable persist without unique name
+- DO NOT persist sensitive data without encryption
+- DO NOT forget version when schema changes
+- DO NOT omit migration for breaking changes
+
+### Type Safety
+- DO NOT use `any` for state type
+- DO NOT bypass type inference
+- DO NOT cast state to wrong type
+- DO NOT create circular type dependencies
+
+## Rules
+
+### Factory Function
+- MUST provide createStore(config) function
+- MUST accept name parameter (required)
+- MUST accept initialState parameter (required)
+- MUST accept actions parameter (optional)
+- MUST accept persist parameter (optional)
+
+### Store Configuration
+- MUST require unique store name
+- MUST define complete initial state
+- MUST provide type inference
+- MUST validate configuration
+- MUST return configured store
+
+### Persistence Setup
+- MUST use zustand persist middleware
+- MUST use storageService adapter
+- MUST include store name in config
+- MUST support version parameter
+- MUST support partialize function
+
+### Actions Creation
+- MUST provide set helper for updates
+- MUST provide get helper for reads
+- MUST support both object and function updates
+- MUST enable action composition
+- MUST preserve type safety
+
+### Type Inference
+- MUST infer state type from initialState
+- MUST infer actions type from actions return
+- MUST support ReturnType for external use
+- MUST enable Pick for action subsets
+
+### Version Management
+- MUST increment version on schema changes
+- MUST provide migrate function
+- MUST handle old persisted states
+- MUST document breaking changes
+- MUST support multiple version migrations
+
+### Partialize Function
+- MUST accept full state parameter
+- MUST return partial state for persistence
+- MUST exclude transient state
+- MUST include all persistent state
+- MUST enable optimization
+
+### Migration Function
+- MUST accept persistedState parameter
+- MUST accept version parameter
+- MUST return migrated state
+- MUST handle all old versions
+- MUST default to identity for current version
+
+### OnRehydrate Callback
+- MUST accept hydrated state parameter
+- MUST execute after rehydration
+- MUST enable initialization logic
+- MUST not block hydration
+- MUST support async operations
+
+### Error Handling
+- MUST validate store configuration
+- MUST throw descriptive errors for invalid config
+- MUST handle persistence errors gracefully
+- MUST log errors in development
+- MUST provide fallback when possible
+
+### Testing Support
+- MUST enable store reset in tests
+- MUST support mocking persistence
+- MUST provide test utilities
+- MUST clear state between tests
+- MUST not have hidden dependencies
+
+### Documentation
+- MUST document store purpose
+- MUST specify state structure
+- MUST document all actions
+- MUST explain persistence strategy
+- MUST warn about common mistakes