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

package/src/storage/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/storage/domain/constants/CacheDefaults.ts

@@ -0,0 +1,64 @@
+/**
+ * Cache Default Constants
+ * Domain layer - Default values for caching
+ *
+ * General-purpose constants for any app
+ */
+
+/**
+ * Time constants in milliseconds
+ */
+export const TIME_MS = {
+  SECOND: 1000,
+  MINUTE: 60 * 1000,
+  HOUR: 60 * 60 * 1000,
+  DAY: 24 * 60 * 60 * 1000,
+  WEEK: 7 * 24 * 60 * 60 * 1000,
+} as const;
+
+/**
+ * Default TTL values for different cache types
+ */
+export const DEFAULT_TTL = {
+  /**
+   * Very short cache (1 minute)
+   * Use for: Real-time data, live updates
+   */
+  VERY_SHORT: TIME_MS.MINUTE,
+
+  /**
+   * Short cache (5 minutes)
+   * Use for: Frequently changing data
+   */
+  SHORT: 5 * TIME_MS.MINUTE,
+
+  /**
+   * Medium cache (30 minutes)
+   * Use for: Moderately changing data, user-specific content
+   */
+  MEDIUM: 30 * TIME_MS.MINUTE,
+
+  /**
+   * Long cache (2 hours)
+   * Use for: Slowly changing data, public content
+   */
+  LONG: 2 * TIME_MS.HOUR,
+
+  /**
+   * Very long cache (24 hours)
+   * Use for: Rarely changing data, master data
+   */
+  VERY_LONG: TIME_MS.DAY,
+
+  /**
+   * Permanent cache (7 days)
+   * Use for: Static content, app configuration
+   */
+  PERMANENT: TIME_MS.WEEK,
+} as const;
+
+/**
+ * Cache version for global invalidation
+ * Increment this to invalidate all caches across the app
+ */
+export const CACHE_VERSION = 1;

package/src/storage/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/storage/domain/entities/CachedValue.ts

@@ -0,0 +1,86 @@
+/**
+ * Cached Value Entity
+ * Domain layer - Represents a cached value with TTL metadata
+ *
+ * General-purpose cache entity for any app that needs persistent caching
+ */
+
+/**
+ * Cached value with time-to-live metadata
+ * Generic type T can be any serializable data
+ */
+export interface CachedValue<T> {
+  /**
+   * The actual cached data
+   */
+  value: T;
+
+  /**
+   * Timestamp when the value was cached (milliseconds)
+   */
+  cachedAt: number;
+
+  /**
+   * Timestamp when the cache expires (milliseconds)
+   */
+  expiresAt: number;
+
+  /**
+   * Optional version for cache invalidation
+   * Increment version to invalidate all caches
+   */
+  version?: number;
+}
+
+/**
+ * Create a new cached value with TTL
+ * @param value - Data to cache
+ * @param ttlMs - Time-to-live in milliseconds
+ * @param version - Optional version number
+ */
+export function createCachedValue<T>(
+  value: T,
+  ttlMs: number,
+  version?: number,
+): CachedValue<T> {
+  const now = Date.now();
+  return {
+    value,
+    cachedAt: now,
+    expiresAt: now + ttlMs,
+    version,
+  };
+}
+
+/**
+ * Check if cached value is expired
+ * @param cached - Cached value to check
+ * @param currentVersion - Optional current version to check against
+ */
+export function isCacheExpired<T>(
+  cached: CachedValue<T>,
+  currentVersion?: number,
+): boolean {
+  const now = Date.now();
+  const timeExpired = now > cached.expiresAt;
+  const versionMismatch = currentVersion !== undefined && cached.version !== currentVersion;
+  return timeExpired || versionMismatch;
+}
+
+/**
+ * Get remaining TTL in milliseconds
+ * Returns 0 if expired
+ */
+export function getRemainingTTL<T>(cached: CachedValue<T>): number {
+  const now = Date.now();
+  const remaining = cached.expiresAt - now;
+  return Math.max(0, remaining);
+}
+
+/**
+ * Get cache age in milliseconds
+ */
+export function getCacheAge<T>(cached: CachedValue<T>): number {
+  const now = Date.now();
+  return now - cached.cachedAt;
+}

package/src/storage/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/storage/domain/entities/StorageResult.ts

@@ -0,0 +1,75 @@
+/**
+ * Storage Result Entity
+ *
+ * Domain-Driven Design: Entity representing storage operation result
+ * Functional programming pattern for error handling (Result type)
+ */
+
+import type { StorageError } from '../errors/StorageError';
+
+/**
+ * Storage Operation Result
+ * Success/Failure pattern for type-safe error handling
+ */
+export type StorageResult<T> =
+  | { success: true; data: T }
+  | { success: false; error: StorageError; fallback?: T };
+
+/**
+ * Create success result
+ */
+export const success = <T>(data: T): StorageResult<T> => ({
+  success: true,
+  data,
+});
+
+/**
+ * Create failure result
+ */
+export const failure = <T>(error: StorageError, fallback?: T): StorageResult<T> => ({
+  success: false,
+  error,
+  fallback,
+});
+
+/**
+ * Type guard for success result
+ */
+export const isSuccess = <T>(result: StorageResult<T>): result is { success: true; data: T } => {
+  return result.success === true;
+};
+
+/**
+ * Type guard for failure result
+ */
+export const isFailure = <T>(result: StorageResult<T>): result is { success: false; error: StorageError; fallback?: T } => {
+  return result.success === false;
+};
+
+/**
+ * Unwrap result with default value
+ */
+export const unwrap = <T>(result: StorageResult<T>, defaultValue: T): T => {
+  if (isSuccess(result)) {
+    return result.data;
+  }
+  // Type guard ensures we can access fallback
+  if (isFailure(result) && result.fallback !== undefined) {
+    return result.fallback;
+  }
+  return defaultValue;
+};
+
+/**
+ * Map result data
+ */
+export const map = <T, U>(
+  result: StorageResult<T>,
+  fn: (data: T) => U
+): StorageResult<U> => {
+  if (isSuccess(result)) {
+    return success(fn(result.data));
+  }
+  // For failure, we can't convert fallback type T to U, so we omit it
+  return failure(result.error);
+};