@umituz/react-native-storage 2.6.22 → 2.6.24

package/src/presentation/README.md

@@ -0,0 +1,181 @@
+# Presentation Layer
+
+React hooks and components for UI integration with storage and cache.
+
+## Overview
+
+Presentation layer containing React hooks for storage and cache operations. Located at `src/presentation/`.
+
+## Directory Structure
+
+- `hooks/` - React hooks for storage and cache integration
+
+## Strategies
+
+### React Integration
+- Use custom hooks for storage operations
+- Use custom hooks for cache operations
+- Enable reactive state management
+- Support automatic re-renders on state changes
+
+### State Management
+- Use useStorageState for persistent state
+- Use useCacheState for cached state
+- Enable automatic sync with storage/cache
+- Support default values and initialization
+
+### Cache Integration
+- Use useCache for cache instance access
+- Use useCachedValue for single value caching
+- Use usePersistentCache for hybrid cache+storage
+- Enable TTL-based invalidation
+
+### Hook Design
+- Follow React hooks rules and best practices
+- Enable composition and reuse
+- Support dependency arrays for optimization
+- Provide cleanup functions for side effects
+
+## Restrictions
+
+### Hook Usage
+- DO NOT call hooks outside React components
+- DO NOT call hooks conditionally or in loops
+- DO NOT mutate state directly
+- DO NOT ignore loading and error states
+
+### State Management
+- DO NOT mix storage and cache state unnecessarily
+- DO NOT create redundant state for same data
+- DO NOT forget to handle undefined/null states
+- DO NOT use stale state in closures
+
+### Performance
+- DO NOT create new cache instances on every render
+- DO NOT skip dependency arrays in useEffect
+- DO NOT cause unnecessary re-renders
+- DO NOT forget cleanup in useEffect
+
+### Error Handling
+- DO NOT ignore errors from async operations
+- DO NOT expose raw error objects to UI
+- DO NOT retry indefinitely on failures
+- DO NOT lose error context
+
+## Rules
+
+### Hook Implementation
+- MUST follow React hooks rules
+- MUST use useMemo for expensive computations
+- MUST use useCallback for stable function references
+- MUST provide cleanup functions for effects
+- MUST support dependency arrays
+
+### Storage Hooks
+- MUST provide useStorage for low-level operations
+- MUST provide useStorageState for state sync
+- MUST support generic type parameters
+- MUST handle loading states
+- MUST handle error states
+- MUST return stable references
+
+### Cache Hooks
+- MUST provide useCache for cache instance access
+- MUST provide useCachedValue for value caching
+- MUST provide useCacheState for state integration
+- MUST support TTL configuration
+- MUST support invalidation callbacks
+- MUST handle cache misses gracefully
+
+### Persistent Cache Hooks
+- MUST provide usePersistentCache for hybrid caching
+- MUST support storage fallback
+- MUST handle rehydration from storage
+- MUST support stale-while-revalidate strategy
+- MUST provide loading, error, and data states
+- MUST support refresh callbacks
+
+### State Synchronization
+- MUST sync state changes to storage/cache
+- MUST re-render on state changes
+- MUST provide latest state to consumers
+- MUST handle race conditions properly
+- MUST support optimistic updates
+
+### Error Handling
+- MUST expose error state from hooks
+- MUST enable error callbacks
+- MUST not throw exceptions from hooks
+- MUST preserve error context
+- MUST support error recovery
+
+### Loading States
+- MUST expose loading state from async hooks
+- MUST indicate initial load vs refresh
+- MUST support loading callbacks
+- MUST prevent duplicate requests
+- MUST handle concurrent operations
+
+### Type Safety
+- MUST use generic type parameters
+- MUST infer types from default values
+- MUST provide type-safe return values
+- MUST support custom type definitions
+- MUST not use type assertions
+
+### Performance Optimization
+- MUST use useMemo for cache instances
+- MUST use useCallback for event handlers
+- MUST provide dependency array parameters
+- MUST prevent unnecessary re-renders
+- MUST enable memoization where appropriate
+
+### Cleanup and Lifecycle
+- MUST clean up subscriptions on unmount
+- MUST clear temporary cache on unmount
+- MUST prevent memory leaks
+- MUST handle component unmount gracefully
+- MUST not update state after unmount
+
+### Hook Naming
+- MUST use 'use' prefix for all hooks
+- MUST use descriptive names for functionality
+- MUST follow naming conventions
+- MUST be consistent with ecosystem
+- MUST indicate purpose in name
+
+### Cache Naming
+- MUST use descriptive cache names
+- MUST avoid generic cache names
+- MUST enable pattern matching for invalidation
+- MUST follow naming conventions
+- MUST prevent naming conflicts
+
+### Testing Support
+- MUST enable hook testing with renderHook
+- MUST provide cleanup for testing
+- MUST support mocking dependencies
+- MUST reset state between tests
+- MUST not have hidden side effects
+
+### Export Rules
+- MUST export all hooks from presentation layer
+- MUST provide TypeScript types
+- MUST document hook behavior
+- MUST specify hook contracts
+- MUST not export internal utilities
+
+### Documentation
+- MUST document all public hooks
+- MUST specify parameter types and requirements
+- MUST explain return value structure
+- MUST provide usage guidance
+- MUST warn about common mistakes
+- MUST not include code examples
+
+### Best Practices Compliance
+- MUST follow React hooks rules
+- MUST enable proper dependency tracking
+- MUST support concurrent mode
+- MUST be compatible with Strict Mode
+- MUST not cause memory leaks

package/src/presentation/hooks/README.md

@@ -0,0 +1,128 @@
+# React Hooks
+
+Integration layer for storage and cache functionality with React components.
+
+## Overview
+
+This directory contains React hooks that integrate storage and cache functionality with React components. Located at `src/presentation/hooks/`.
+
+## Available Hooks
+
+| Hook | Purpose | Use Case |
+|------|---------|----------|
+| `useStorage` | Low-level storage operations | Manual CRUD operations |
+| `useStorageState` | State with auto-persistence | Form data, user preferences |
+| `useStore` | Zustand store selector | State management |
+| `usePersistentCache` | API caching with persistence | Data fetching with offline support |
+| `useCacheState` | In-memory cache state | Temporary state management |
+| `useCache` | In-memory cache operations | Manual cache management |
+| `useCachedValue` | Single value caching | Simple value caching |
+
+## Strategies
+
+### Hook Selection
+- Use `useStorageState` for form inputs and settings
+- Use `useStore` for Zustand integration
+- Use `usePersistentCache` for API data with offline support
+- Use `useCache` for complex caching patterns
+- Use `useCachedValue` for simple single-value caching
+
+### Performance Optimization
+- Use selectors with `useStore` to prevent unnecessary re-renders
+- Memoize callbacks passed to cache hooks
+- Avoid inline fetcher functions
+- Use appropriate TTL based on data change frequency
+
+### Composition Patterns
+- Combine multiple hooks for complex scenarios
+- Use conditional fetching with enabled flag
+- Implement dependent queries with proper data flow
+- Share cache instances across components
+
+## Restrictions
+
+### Hook Usage
+- DO NOT call hooks outside React components or custom hooks
+- DO NOT call hooks conditionally or inside loops
+- DO NOT use `useStorage` when `useStorageState` is sufficient
+- DO NOT use inline fetcher functions (define them first)
+
+### State Management
+- DO NOT mix storage and cache for same data
+- DO NOT use `useStorageState` for large datasets (> 1MB)
+- DO NOT use `useCache` when simple state would suffice
+- DO NOT create new cache instances on every render
+
+### Performance
+- DO NOT select entire store with `useStore` (use selectors)
+- DO NOT recreate fetcher functions on every render
+- DO NOT use very short TTLs (< 5 seconds)
+- DO NOT cache large objects (> 100KB)
+
+### Error Handling
+- DO NOT ignore error states from cache hooks
+- DO NOT silently fail storage operations
+- DO NOT use try-catch inside hooks (handle errors at call site)
+
+## Rules
+
+### Hook Implementation
+- MUST follow React rules of hooks
+- MUST provide TypeScript types for all parameters
+- MUST handle loading states appropriately
+- MUST provide error state for async operations
+
+### Storage Hooks (`useStorage`, `useStorageState`)
+- MUST use unique keys for different state
+- MUST specify initial value for `useStorageState`
+- MUST handle storage errors gracefully
+- MUST provide type parameter for type safety
+
+### Cache Hooks (`useCache`, `useCacheState`, `useCachedValue`)
+- MUST specify cache name when using `useCache`
+- MUST provide fetcher function for `useCachedValue`
+- MUST set appropriate TTL for data type
+- MUST handle cache misses gracefully
+
+### Persistent Cache (`usePersistentCache`)
+- MUST provide unique key for each query
+- MUST define fetcher function that returns Promise
+- MUST specify TTL based on data freshness requirements
+- MUST handle loading and error states
+- MUST implement refresh mechanism
+
+### Store Hook (`useStore`)
+- MUST provide selector function for partial state
+- MUST use memoized selectors to prevent re-renders
+- MUST select only needed state slices
+- MUST avoid selecting entire store
+
+### Testing
+- MUST test hooks with `@testing-library/react-hooks`
+- MUST test loading, success, and error states
+- MUST test cleanup and unmount behavior
+- MUST mock storage/cache in tests
+
+### Error Handling
+- MUST expose error state from async hooks
+- MUST allow error handling at component level
+- MUST log errors in development mode
+- MUST provide retry mechanisms for transient failures
+
+### Type Safety
+- MUST provide generic type parameters
+- MUST enforce types for storage keys
+- MUST use TypeScript strict mode
+- MUST avoid `any` types in hook implementations
+
+### Performance
+- MUST use `useCallback` for functions passed to hooks
+- MUST use `useMemo` for computed values
+- MUST implement proper dependency arrays
+- MUST avoid unnecessary re-renders
+
+### Deprecation
+- MUST document deprecated hooks
+- MUST provide migration path for deprecated hooks
+- MUST maintain backward compatibility when possible
+- MUST remove deprecated hooks after major version bump

package/src/types/README.md

@@ -0,0 +1,103 @@
+# Shared Types
+
+TypeScript type definitions used across the storage package.
+
+## Overview
+
+This directory contains shared type definitions for storage operations, Result pattern, and utility types. Located at `src/types/`.
+
+## Strategies
+
+### Type Organization
+- Define StorageResult for all storage operations
+- Use DynamicStorageKey for type-safe key generation
+- Create utility types for common transformations
+- Export types for external package use
+
+### Result Pattern
+- Use discriminated union for success/failure states
+- Include success flag for type narrowing
+- Preserve error context in failure state
+- Provide type guards for type safety
+
+### Type Safety
+- Use generic type parameters for flexibility
+- Provide type inference where possible
+- Use branded types for distinct primitives
+- Implement conditional types for complex scenarios
+
+### Type Guards
+- Create type guards for runtime validation
+- Use predicate functions for type narrowing
+- Implement instanceof checks for error types
+- Validate structure before type assertions
+
+## Restrictions
+
+### Type Definitions
+- DO NOT use `any` type without compelling reason
+- DO NOT create circular type dependencies
+- DO NOT mix success/failure in same type
+- DO NOT omit error context from Result types
+
+### Type Safety
+- DO NOT use type assertions without validation
+- DO NOT assume optional properties exist
+- DO NOT cast values without type guards
+- DO NOT disable TypeScript rules
+
+### Utility Types
+- DO NOT create overly complex conditional types
+- DO NOT use utility types where simple types suffice
+- DO NOT create recursive types without clear purpose
+- DO NOT mix different type utilities unnecessarily
+
+## Rules
+
+### StorageResult 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 Guards
+- MUST return boolean for type predicates
+- MUST use `is` keyword for type narrowing
+- MUST validate all required properties
+- MUST handle edge cases (null, undefined)
+
+### Generic Types
+- MUST provide descriptive type parameter names
+- MUST constrain generics with extends where appropriate
+- MUST provide default values for common cases
+- MUST document generic constraints
+
+### Utility Types
+- MUST follow TypeScript conventions
+- MUST use built-in utility types when possible
+- MUST document custom utility types
+- MUST test utility type behavior
+
+### Import/Export
+- MUST export types used by external packages
+- MUST use `type` keyword for type-only imports
+- MUST avoid value/type ambiguity
+- MUST organize exports logically
+
+### Type Inference
+- MUST enable TypeScript strict mode
+- MUST provide type annotations for public APIs
+- MUST let TypeScript infer where possible
+- MUST use `typeof` for capturing inferred types
+
+### Documentation
+- MUST document complex type transformations
+- MUST provide examples for non-obvious types
+- MUST explain generic constraints
+- MUST warn about type limitations
+
+### Testing
+- MUST test type guards with various inputs
+- MUST verify utility type behavior
+- MUST test conditional type branches
+- MUST validate type inference results