@umituz/react-native-storage 2.6.23 → 2.6.24

package/README.md

@@ -0,0 +1,137 @@
+# React Native Storage
+
+Unified storage solution for React Native with AsyncStorage persistence, Zustand state management, and in-memory caching.
+
+## Overview
+
+Complete storage and caching solution following Domain-Driven Design principles. Located at `src/`.
+
+## Features
+
+- **AsyncStorage Integration** - Type-safe storage operations
+- **Zustand State Management** - Persisted stores with factory pattern
+- **In-Memory Cache** - TTL, LRU, LFU, FIFO eviction strategies
+- **React Hooks** - Simple and powerful API for React integration
+- **Type-Safe** - Full TypeScript support with generics
+- **Domain-Driven Design** - Clean Architecture implementation
+- **Result Pattern** - Type-safe error handling without exceptions
+
+## Installation
+
+Install the package and required dependencies:
+
+```bash
+npm install @umituz/react-native-storage
+npm install @react-native-async-storage/async-storage zustand
+```
+
+For Expo projects:
+
+```bash
+npx expo install @react-native-async-storage/async-storage zustand
+```
+
+## Documentation
+
+For detailed documentation, refer to module READMEs:
+
+- [Cache Module](./src/cache/README.md) - In-memory cache system
+- [React Hooks](./src/presentation/hooks/README.md) - All React hooks
+- [Domain Layer](./src/domain/README.md) - Business logic and entities
+- [Infrastructure Layer](./src/infrastructure/README.md) - AsyncStorage integration
+- [Application Layer](./src/application/README.md) - Ports and interfaces
+
+## Architecture
+
+Clean Architecture with DDD principles:
+
+```
+┌─────────────────────────────────────────┐
+│         Presentation Layer              │
+│         (React Hooks, Components)       │
+└─────────────────────────────────────────┘
+                  ↓
+┌─────────────────────────────────────────┐
+│         Application Layer               │
+│         (Use Cases, Ports)              │
+└─────────────────────────────────────────┘
+                  ↓
+┌─────────────────────────────────────────┐
+│         Domain Layer                    │
+│         (Business Logic, Entities)      │
+└─────────────────────────────────────────┘
+                  ↓
+┌─────────────────────────────────────────┐
+│         Infrastructure Layer            │
+│         (AsyncStorage, MMKV)            │
+└─────────────────────────────────────────┘
+```
+
+## Module Structure
+
+### Storage Hooks
+Located at `src/presentation/hooks/`
+- `useStorage()` - AsyncStorage operations
+- `useStorageState(key, initial)` - State with storage sync
+- `useStore(store, selector)` - Zustand store hook
+
+### Cache Hooks
+Located at `src/presentation/hooks/`
+- `useCache(name, config)` - In-memory cache instance
+- `useCachedValue(key, fetcher, ttl)` - Single value caching
+- `usePersistentCache(key, fetcher, opts)` - API caching with persistence
+- `useCacheState()` - Cache state integration
+
+### Storage Operations
+Located at `src/infrastructure/repositories/`
+- `getItem(key, default)` - Retrieve value with default
+- `setItem(key, value)` - Store value
+- `getString(key, default)` - Retrieve string value
+- `setString(key, value)` - Store string value
+- `removeItem(key)` - Delete value
+- `hasItem(key)` - Check existence
+- `clearAll()` - Clear all storage
+
+### Cache Operations
+Located at `src/cache/infrastructure/`
+- `new Cache(config)` - Create cache instance
+- `cache.set(key, value, ttl)` - Add value with TTL
+- `cache.get(key)` - Retrieve value
+- `cache.has(key)` - Check existence
+- `cache.delete(key)` - Delete entry
+- `cache.clear()` - Clear all entries
+- `cache.invalidatePattern(pattern)` - Pattern-based invalidation
+- `cache.getStats()` - Get cache statistics
+
+### Store Factory
+Located at `src/domain/factories/`
+- `createStore(config)` - Create Zustand store with persistence
+- Support for actions, persist middleware, versioning
+
+## Error Handling
+
+All operations use Result pattern for type-safe error handling:
+
+```typescript
+type StorageResult<T> =
+  | { success: true; data: T }
+  | { success: false; error: StorageError }
+```
+
+Check `success` property before accessing `data` or `error`.
+
+## Type Safety
+
+Full TypeScript support with generic type parameters:
+
+- Storage operations: `getItem<User>(key, defaultValue)`
+- Cache operations: `new Cache<Product>(config)`
+- Store state: Type-inferred from initial state
+
+## License
+
+MIT © [Ümit UZ](https://github.com/umituz)
+
+## GitHub
+
+[https://github.com/umituz/react-native-storage](https://github.com/umituz/react-native-storage)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@umituz/react-native-storage",
-  "version": "2.6.23",
+  "version": "2.6.24",
   "description": "Unified storage solution with AsyncStorage persistence, Zustand state management, and in-memory caching for React Native",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
@@ -57,6 +57,7 @@
   },
   "files": [
     "src",
+    "examples",
     "README.md",
     "LICENSE"
   ]

package/src/README.md

@@ -0,0 +1,185 @@
+# Source Directory
+
+Main source code for react-native-storage package following Domain-Driven Design principles.
+
+## Overview
+
+Complete implementation of storage and caching solution with Clean Architecture. Located at `src/`.
+
+## Architecture
+
+Clean Architecture with DDD principles:
+- `application/` - Application layer (ports/interfaces)
+- `cache/` - In-memory caching module
+- `domain/` - Domain layer (business logic)
+- `infrastructure/` - Infrastructure layer (implementations)
+- `presentation/` - Presentation layer (React hooks)
+- `types/` - Shared TypeScript types
+
+## Strategies
+
+### Layer Organization
+- Use application layer for interfaces and ports
+- Use domain layer for business logic and entities
+- Use infrastructure layer for external service implementations
+- Use presentation layer for React integration
+- Use cache module for in-memory caching
+
+### Dependency Flow
+- Presentation depends on domain
+- Domain depends on nothing (core)
+- Infrastructure implements domain interfaces
+- Application defines contracts between layers
+
+### Module Separation
+- Keep cache module independent and self-contained
+- Enable cache usage without storage dependency
+- Support standalone cache operations
+- Maintain clean module boundaries
+
+### Type Safety
+- Use TypeScript for all modules
+- Provide generic type parameters
+- Enable type inference
+- Support branded types for storage keys
+
+## Restrictions
+
+### Layer Dependencies
+- DO NOT import infrastructure in domain layer
+- DO NOT import presentation in domain layer
+- DO NOT import application in infrastructure
+- DO NOT create circular dependencies
+
+### Module Boundaries
+- DO NOT mix concerns across layers
+- DO NOT bypass layer boundaries
+- DO NOT expose implementation details
+- DO NOT create tight coupling between modules
+
+### Code Organization
+- DO NOT place business logic in presentation
+- DO NOT place UI code in domain
+- DO NOT place external dependencies in domain
+- DO NOT create god objects
+
+### Architecture Compliance
+- DO NOT violate dependency inversion principle
+- DO NOT ignore layer responsibilities
+- DO NOT create ambiguous module placement
+- DO NOT mix abstraction levels
+
+## Rules
+
+### Application Layer
+- MUST define IStorageRepository interface
+- MUST provide ports for dependency inversion
+- MUST not contain implementation details
+- MUST be framework-agnostic
+- MUST enable constructor injection
+
+### Cache Module
+- MUST provide domain entities (CacheManager, CachedValue)
+- MUST provide infrastructure implementation (TTLCache)
+- MUST provide presentation hooks (useCache, useCachedValue)
+- MUST support multiple eviction strategies (LRU, LFU, FIFO, TTL)
+- MUST be independent and self-contained
+
+### Domain Layer
+- MUST contain core business logic
+- MUST define value objects (StorageKey)
+- MUST define entities (CachedValue, Result)
+- MUST provide factory functions (createStore)
+- MUST define error types (StorageError hierarchy)
+- MUST not depend on external frameworks
+
+### Infrastructure Layer
+- MUST implement IStorageRepository interface
+- MUST provide StorageService adapter for Zustand
+- MUST handle Result pattern for error handling
+- MUST support AsyncStorage as primary backend
+- MUST enable custom storage backends
+
+### Presentation Layer
+- MUST provide React hooks for storage
+- MUST provide React hooks for cache
+- MUST enable reactive state management
+- MUST handle loading and error states
+- MUST follow React hooks rules
+
+### Types Module
+- MUST provide shared TypeScript types
+- MUST define StorageResult type
+- MUST define DynamicStorageKey type
+- MUST enable type-safe operations
+- MUST be imported by all layers
+
+### Export Structure
+- MUST export from index.ts at root level
+- MUST organize exports by module
+- MUST provide TypeScript types
+- MUST maintain backward compatibility
+- MUST not export internal utilities
+
+### File Organization
+- MUST place files in appropriate layer
+- MUST follow feature-based organization within layers
+- MUST use descriptive file names
+- MUST maintain consistent structure
+- MUST enable easy navigation
+
+### Testing Structure
+- MUST place tests in __tests__ directories
+- MUST mirror source structure
+- MUST provide comprehensive coverage
+- MUST enable isolated testing
+- MUST not depend on external services
+
+### Type Safety Requirements
+- MUST use TypeScript for all files
+- MUST provide generic type parameters
+- MUST enable type inference
+- MUST not use `any` type
+- MUST enforce strict type checking
+
+### Error Handling
+- MUST use Result pattern for operations
+- MUST preserve error context
+- MUST provide hierarchical error types
+- MUST not throw exceptions across layers
+- MUST handle errors gracefully
+
+### Documentation
+- MUST provide README for each layer
+- MUST document public APIs
+- MUST specify file locations
+- MUST explain architecture decisions
+- MUST not include code examples in README files
+
+### Naming Conventions
+- MUST use camelCase for files and variables
+- MUST use PascalCase for types and interfaces
+- MUST use descriptive names
+- MUST follow React hooks naming (use prefix)
+- MUST maintain consistency across modules
+
+### Performance Considerations
+- MUST optimize for read-heavy or write-heavy patterns
+- MUST minimize unnecessary re-renders
+- MUST use memoization where appropriate
+- MUST enable lazy loading
+- MUST consider bundle size impact
+
+### Security Requirements
+- MUST not expose sensitive data in logs
+- MUST use SecureStore for sensitive data
+- MUST handle encryption for secure storage
+- MUST validate input data
+- MUST prevent injection attacks
+
+### Best Practices Compliance
+- MUST follow Single Responsibility Principle
+- MUST follow Open/Closed Principle
+- MUST follow Liskov Substitution Principle
+- MUST follow Interface Segregation Principle
+- MUST follow Dependency Inversion Principle

package/src/application/README.md

@@ -0,0 +1,158 @@
+# Application Layer
+
+Ports and interfaces for dependency inversion between domain and infrastructure layers.
+
+## Overview
+
+Application layer containing interfaces (ports) for storage operations. Located at `src/application/`.
+
+## Directory Structure
+
+- `ports/` - Repository interfaces defining storage contracts
+
+## Strategies
+
+### Dependency Inversion
+- Use IStorageRepository interface for storage operations
+- Define contracts in application layer
+- Implement interfaces in infrastructure layer
+- Enable dependency injection for testing
+
+### Port Definition
+- Use IStorageRepository as primary storage interface
+- Define all storage operations as methods
+- Support Result pattern for error handling
+- Enable generic type parameters for type safety
+
+### Use Case Pattern
+- Create use cases for complex business logic
+- Inject IStorageRepository through constructor
+- Encapsulate business rules in use case methods
+- Enable testing with mock implementations
+
+### Interface Segregation
+- Define cohesive interfaces for specific purposes
+- Support granular method dependencies
+- Enable single responsibility principle
+- Facilitate testing with focused mocks
+
+## Restrictions
+
+### Interface Definition
+- DO NOT define implementation details in interfaces
+- DO NOT create interfaces without clear purpose
+- DO NOT mix different concerns in single interface
+- DO NOT include framework-specific types
+
+### Dependency Injection
+- DO NOT create concrete instances in use cases
+- DO NOT use hardcoded dependencies
+- DO NOT skip constructor injection
+- DO NOT create circular dependencies
+
+### Use Case Implementation
+- DO NOT implement business logic in components
+- DO NOT mix storage operations with UI logic
+- DO NOT create use cases without clear purpose
+- DO NOT bypass error handling in use cases
+
+### Testing
+- DO NOT test with real storage implementations
+- DO NOT create complex mock implementations
+- DO NOT share state between tests
+- DO NOT forget to reset mocks between tests
+
+## Rules
+
+### IStorageRepository Interface
+- MUST define getItem<T>(key, defaultValue): Promise<StorageResult<T>>
+- MUST define setItem<T>(key, value): Promise<StorageResult<void>>
+- MUST define getString(key, defaultValue): Promise<StorageResult<string>>
+- MUST define setString(key, value): Promise<StorageResult<void>>
+- MUST define removeItem(key): Promise<StorageResult<void>>
+- MUST define hasItem(key): Promise<boolean>
+- MUST define clearAll(): Promise<StorageResult<void>>
+
+### Interface Design
+- MUST use generic type parameters for value operations
+- MUST return Result type for all mutable operations
+- MUST support type inference from parameters
+- MUST be framework-agnostic
+- MUST define contracts only (no implementation)
+
+### Method Signatures
+- MUST accept key parameter for all operations
+- MUST accept defaultValue parameter for get operations
+- MUST accept value parameter for set operations
+- MUST return Promise for all async operations
+- MUST include StorageResult for typed results
+
+### Use Case Implementation
+- MUST accept IStorageRepository in constructor
+- MUST define single responsibility per use case
+- MUST handle Result pattern in all operations
+- MUST return domain types from use case methods
+- MUST not expose storage implementation details
+
+### Constructor Injection
+- MUST inject dependencies through constructor
+- MUST store dependencies as private fields
+- MUST use interface types for dependencies
+- MUST enable dependency injection for testing
+- MUST not create instances inside use cases
+
+### Error Handling
+- MUST check result.success before accessing data
+- MUST handle result.error appropriately
+- MUST propagate errors to callers when needed
+- MUST not throw exceptions from use cases
+- MUST preserve error context
+
+### Testing Requirements
+- MUST enable mocking of IStorageRepository
+- MUST support test double implementations
+- MUST isolate tests from real storage
+- MUST clear state between test runs
+- MUST not depend on external services
+
+### Mock Implementation
+- MUST implement full IStorageRepository interface
+- MUST return appropriate Result types
+- MUST simulate storage behavior accurately
+- MUST support async operations with Promise
+- MUST be simple and predictable
+
+### Custom Repository Implementation
+- MUST implement IStorageRepository interface
+- MUST use Result pattern for all methods
+- MUST handle errors appropriately
+- MUST support generic type parameters
+- MUST be compatible with existing code
+
+### Layer Separation
+- MUST not depend on infrastructure implementations
+- MUST not depend on presentation components
+- MUST define contracts for domain use
+- MUST enable layer independence
+- MUST support testing at each layer
+
+### Export Rules
+- MUST export IStorageRepository interface
+- MUST export all port interfaces
+- MUST not export implementations
+- MUST provide TypeScript types
+- MUST document interface contracts
+
+### Architecture Compliance
+- MUST follow dependency inversion principle
+- MUST depend on abstractions not concretions
+- MUST enable independent layer evolution
+- MUST support multiple implementations
+- MUST maintain clear separation of concerns
+
+### Documentation
+- MUST document all interface methods
+- MUST specify method contracts clearly
+- MUST provide usage guidance
+- MUST explain Result pattern usage
+- MUST not include implementation examples

package/src/application/ports/README.md

@@ -0,0 +1,127 @@
+# Application Ports
+
+Repository interfaces for dependency inversion and testability.
+
+## Overview
+
+Ports define contracts between application and infrastructure layers using dependency inversion principle. Located at `src/application/ports/`.
+
+## Strategies
+
+### Dependency Inversion
+- Define interfaces in application layer
+- Implement interfaces in infrastructure layer
+- Depend on abstractions, not concretions
+- Enable swapping implementations without business logic changes
+
+### Testability Strategy
+- Design interfaces for easy mocking
+- Use constructor injection for dependencies
+- Create fake implementations for testing
+- Separate unit tests from integration tests
+
+### Contract Design
+- Define clear method signatures
+- Use Result pattern for error handling
+- Include type parameters for flexibility
+- Document interface contracts
+
+### Implementation Strategy
+- Provide production implementation (AsyncStorage)
+- Provide mock implementation for testing
+- Support custom implementations (MMKV, SecureStore)
+- Allow platform-specific implementations
+
+## Restrictions
+
+### Interface Design
+- DO NOT include implementation details in interfaces
+- DO NOT change interface signatures without major version bump
+- DO NOT add optional parameters to existing methods
+- DO NOT remove methods from interfaces
+
+### Usage
+- DO NOT use concrete implementations in business logic
+- DO NOT instantiate dependencies inside services
+- DO NOT couple services to specific storage technologies
+- DO NOT bypass interface for performance
+
+### Implementation
+- DO NOT throw exceptions from interface methods
+- DO NOT return undefined (use null or Result)
+- DO NOT ignore type parameters
+- DO NOT mix sync and async patterns
+
+### Testing
+- DO NOT use real storage in unit tests
+- DO NOT share mock instances between tests
+- DO NOT forget to reset mock state
+- DO NOT test interfaces directly
+
+## Rules
+
+### Interface Definition
+- MUST define all required methods
+- MUST use generic type parameters for flexibility
+- MUST return Promise for async operations
+- MUST use Result pattern for error handling
+
+### Method Signatures
+- MUST include type parameter <T> for data operations
+- MUST accept key parameter for storage operations
+- MUST provide defaultValue for getItem methods
+- MUST return StorageResult for operations that can fail
+
+### Constructor Injection
+- MUST inject interfaces through constructors
+- MUST store interface reference as private field
+- MUST mark constructor parameter as readonly
+- MUST not create instances inside class
+
+### Implementation Classes
+- MUST implement complete interface
+- MUST handle all error cases internally
+- MUST return appropriate error types
+- MUST log errors for debugging
+
+### Mock Implementations
+- MUST implement all interface methods
+- MUST provide methods to set mock behavior
+- MUST track method calls for assertions
+- MUST reset state between tests
+
+### Custom Implementations
+- MUST implement IStorageRepository interface
+- MUST handle serialization consistently
+- MUST provide error details in results
+- MUST document platform limitations
+
+### Dependency Injection
+- MUST use interface types in constructors
+- MUST not depend on concrete classes
+- MUST support different implementations
+- MUST validate dependencies at construction time
+
+### Type Safety
+- MUST specify type parameters for all operations
+- MUST enforce type consistency
+- MUST use type guards for validation
+- MUST avoid type assertions
+
+### Error Handling
+- MUST return failure Result for errors
+- MUST include error context (key, operation)
+- MUST preserve original error as cause
+- MUST not throw exceptions from interface methods
+
+### Testing Strategy
+- MUST use mock implementations for unit tests
+- MUST use real implementations for integration tests
+- MUST reset state in test setup
+- MUST test error scenarios
+
+### Documentation
+- MUST document interface contracts
+- MUST specify error types for each method
+- MUST include parameter descriptions
+- MUST provide usage examples in tests