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

package/src/storage/domain/types/Store.ts

@@ -0,0 +1,44 @@
+/**
+ * Store Types
+ * Zustand store configuration with actions support
+ */
+
+import type { StoreApi } from 'zustand';
+
+/** Set function type for Zustand */
+export type SetState<T> = StoreApi<T>['setState'];
+
+/** Get function type for Zustand */
+export type GetState<T> = StoreApi<T>['getState'];
+
+/** Actions creator function */
+export type ActionsCreator<TState, TActions> = (
+  set: SetState<TState & TActions>,
+  get: GetState<TState & TActions>
+) => TActions;
+
+/** Store configuration */
+export interface StoreConfig<TState extends object, TActions extends object = object> {
+  /** Unique store name (used as storage key) */
+  name: string;
+  /** Initial state */
+  initialState: TState;
+  /** Actions creator function */
+  actions?: ActionsCreator<TState, TActions>;
+  /** Enable AsyncStorage persistence */
+  persist?: boolean;
+  /** State version for migrations */
+  version?: number;
+  /** Select which state to persist */
+  partialize?: (state: TState & TActions) => Partial<TState>;
+  /** Callback after rehydration */
+  onRehydrate?: (state: TState & TActions) => void;
+  /** Migration function for version changes */
+  migrate?: (persistedState: unknown, version: number) => TState;
+}
+
+/** Persisted state wrapper */
+export interface PersistedState<T> {
+  state: T;
+  version: number;
+}

package/src/storage/domain/utils/CacheKeyGenerator.ts

@@ -0,0 +1,66 @@
+/**
+ * Cache Key Generator
+ * Domain layer - Utility for generating consistent cache keys
+ *
+ * General-purpose key generation for any app
+ */
+
+/**
+ * Generate a cache key from prefix and identifier
+ * @param prefix - Cache key prefix (e.g., 'posts', 'products', 'user')
+ * @param id - Unique identifier
+ * @returns Formatted cache key
+ *
+ * @example
+ * generateCacheKey('posts', '123') // 'cache:posts:123'
+ * generateCacheKey('user', 'profile') // 'cache:user:profile'
+ */
+export function generateCacheKey(prefix: string, id: string | number): string {
+  return `cache:${prefix}:${id}`;
+}
+
+/**
+ * Generate a cache key for a list/collection
+ * @param prefix - Cache key prefix
+ * @param params - Optional query parameters
+ *
+ * @example
+ * generateListCacheKey('posts') // 'cache:posts:list'
+ * generateListCacheKey('posts', { page: 1 }) // 'cache:posts:list:page=1'
+ */
+export function generateListCacheKey(
+  prefix: string,
+  params?: Record<string, string | number>,
+): string {
+  const base = `cache:${prefix}:list`;
+  if (!params) return base;
+
+  const paramString = Object.entries(params)
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([key, value]) => `${key}=${value}`)
+    .join(':');
+
+  return `${base}:${paramString}`;
+}
+
+/**
+ * Parse a cache key to extract prefix and id
+ * @param key - Cache key to parse
+ * @returns Object with prefix and id, or null if invalid
+ */
+export function parseCacheKey(key: string): { prefix: string; id: string } | null {
+  const parts = key.split(':');
+  if (parts.length < 3 || parts[0] !== 'cache') return null;
+
+  return {
+    prefix: parts[1] || '',
+    id: parts.slice(2).join(':'),
+  };
+}
+
+/**
+ * Check if a key is a cache key
+ */
+export function isCacheKey(key: string): boolean {
+  return key.startsWith('cache:');
+}

package/src/storage/domain/utils/README.md

@@ -0,0 +1,127 @@
+# Domain Utilities
+
+Helper functions for cache key generation and development utilities.
+
+## Overview
+
+Utility functions for cache operations and development-only features. Located at `src/domain/utils/`.
+
+## Strategies
+
+### Cache Key Generation
+- Use generateCacheKey() for single items
+- Use generateListCacheKey() for collections
+- Include version in cache keys
+- Support key parsing and validation
+
+### Key Format
+- Follow consistent format: `cache:type:id:version`
+- For lists: `cache:type:list:params:version`
+- Use colon (`:`) as separator
+- Enable pattern matching
+
+### Development Utilities
+- Use isDev() for environment detection
+- Use devWarn/devError/devLog for dev-only logging
+- Provide no-op functions in production
+- Enable debug features without performance cost
+
+### Key Validation
+- Use isCacheKey() for validation
+- Use parseCacheKey() for extraction
+- Support type checking
+- Enable safe key operations
+
+## Restrictions
+
+### Key Generation
+- DO NOT generate keys manually
+- DO NOT mix key formats
+- DO NOT use inconsistent separators
+- DO NOT omit version from keys
+
+### Development Utilities
+- DO NOT log in production (use dev functions)
+- DO NOT include debug code in production builds
+- DO NOT bypass isDev() checks
+- DO NOT leave development code in production
+
+### Key Parsing
+- DO NOT parse keys with string methods
+- DO NOT assume key format
+- DO NOT skip validation
+- DO NOT ignore parse errors
+
+## Rules
+
+### Key Generation Functions
+- MUST provide generateCacheKey(type, id)
+- MUST provide generateListCacheKey(type, params)
+- MUST include version in generated keys
+- MUST use consistent separator
+- MUST validate input parameters
+
+### Key Format
+- MUST use format: `cache:{type}:{id}:v{version}`
+- MUST use `:` as separator
+- MUST include version prefix `v`
+- MUST be parseable by parseCacheKey()
+- MUST be unique across different entities
+
+### Key Parsing
+- MUST provide parseCacheKey() function
+- MUST return structured data (type, id, version, isList)
+- MUST handle invalid keys gracefully
+- MUST return null for invalid format
+- MUST extract parameters for list keys
+
+### Key Validation
+- MUST provide isCacheKey() function
+- MUST validate format string
+- MUST check for required parts
+- MUST return boolean result
+- MUST be used before parsing
+
+### Development Functions
+- MUST provide isDev() function
+- MUST provide devWarn() for warnings
+- MUST provide devError() for errors
+- MUST provide devLog() for general logging
+- MUST no-op in production
+
+### Environment Detection
+- MUST check __DEV__ or equivalent
+- MUST return boolean for isDev()
+- MUST be compile-time constant when possible
+- MUST not have runtime overhead in production
+
+### Logging Functions
+- MUST only log in development mode
+- MUST accept variable arguments
+- MUST use console methods appropriately
+- MUST not expose sensitive data
+
+### TypeScript Types
+- MUST provide ParsedCacheKey interface
+- MUST specify function signatures
+- MUST enable type inference
+- MUST use generic types where appropriate
+
+### Performance
+- MUST not perform expensive operations in dev checks
+- MUST provide no-op implementations in production
+- MUST minimize bundle size impact
+- MUST not include dev tools in production builds
+
+### Export Rules
+- MUST export all utility functions
+- MUST organize exports by category
+- MUST provide TypeScript types
+- MUST document function behavior
+
+### Testing Requirements
+- MUST test key generation with various inputs
+- MUST test key parsing with valid and invalid keys
+- MUST test validation functions
+- MUST test development mode detection
+- MUST verify production no-op behavior

package/src/storage/domain/utils/__tests__/devUtils.test.ts

@@ -0,0 +1,97 @@
+/**
+ * Development Utilities Tests
+ */
+
+import { isDev, devWarn, devError, devLog } from '../devUtils';
+
+// Mock console methods
+const mockConsoleWarn = jest.fn();
+const mockConsoleError = jest.fn();
+const mockConsoleLog = jest.fn();
+
+describe('Development Utilities', () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+    
+    // Mock console methods
+    console.warn = mockConsoleWarn;
+    console.error = mockConsoleError;
+    console.log = mockConsoleLog;
+  });
+
+  describe('isDev', () => {
+    it('should return true when __DEV__ is true', () => {
+      (globalThis as any).__DEV__ = true;
+      expect(isDev()).toBe(true);
+    });
+
+    it('should return false when __DEV__ is false', () => {
+      (globalThis as any).__DEV__ = false;
+      expect(isDev()).toBe(false);
+    });
+
+    it('should return false when __DEV__ is undefined', () => {
+      delete (globalThis as any).__DEV__;
+      expect(isDev()).toBe(false);
+    });
+  });
+
+  describe('devWarn', () => {
+    it('should log warning when in development mode', () => {
+      (globalThis as any).__DEV__ = true;
+      
+      devWarn('Test warning', { data: 'test' });
+      
+      expect(mockConsoleWarn).toHaveBeenCalledWith('Test warning', { data: 'test' });
+    });
+
+    it('should not log warning when not in development mode', () => {
+      (globalThis as any).__DEV__ = false;
+      
+      devWarn('Test warning', { data: 'test' });
+      
+      expect(mockConsoleWarn).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('devError', () => {
+    it('should log error when in development mode', () => {
+      (globalThis as any).__DEV__ = true;
+      
+      devError('Test error', new Error('test'));
+      
+      expect(mockConsoleError).toHaveBeenCalledWith('Test error', new Error('test'));
+    });
+
+    it('should not log error when not in development mode', () => {
+      (globalThis as any).__DEV__ = false;
+      
+      devError('Test error', new Error('test'));
+      
+      expect(mockConsoleError).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('devLog', () => {
+    it('should log info when in development mode', () => {
+      (globalThis as any).__DEV__ = true;
+      
+      devLog('Test log', { info: 'test' });
+      
+      expect(mockConsoleLog).toHaveBeenCalledWith('Test log', { info: 'test' });
+    });
+
+    it('should not log info when not in development mode', () => {
+      (globalThis as any).__DEV__ = false;
+      
+      devLog('Test log', { info: 'test' });
+      
+      expect(mockConsoleLog).not.toHaveBeenCalled();
+    });
+  });
+
+  afterEach(() => {
+    // Clean up __DEV__ after each test
+    delete (globalThis as any).__DEV__;
+  });
+});

package/src/storage/domain/utils/devUtils.ts

@@ -0,0 +1,37 @@
+/**
+ * Development utilities
+ */
+
+/**
+ * Check if running in development mode
+ */
+export const isDev = (): boolean => {
+  return (globalThis as any).__DEV__ === true;
+};
+
+/**
+ * Log warning in development mode only
+ */
+export const devWarn = (message: string, ...args: any[]): void => {
+  if (isDev()) {
+    console.warn(message, ...args);
+  }
+};
+
+/**
+ * Log error in development mode only
+ */
+export const devError = (message: string, ...args: any[]): void => {
+  if (isDev()) {
+    console.error(message, ...args);
+  }
+};
+
+/**
+ * Log info in development mode only
+ */
+export const devLog = (message: string, ...args: any[]): void => {
+  if (isDev()) {
+    console.log(message, ...args);
+  }
+};

package/src/storage/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/storage/domain/value-objects/StorageKey.ts

@@ -0,0 +1,60 @@
+/**
+ * Storage Key Value Object
+ *
+ * Domain-Driven Design: Value Object for storage keys
+ * Ensures type safety and prevents invalid key usage
+ */
+
+/**
+ * Storage key with dynamic suffix
+ */
+export type DynamicStorageKey = {
+  base: string;
+  suffix: string;
+};
+
+/**
+ * Helper to create user-specific storage key
+ *
+ * @param baseKey Base storage key
+ * @param userId User identifier
+ * @returns User-specific key
+ */
+export const createUserKey = (baseKey: string, userId: string): string => {
+  return `${baseKey}_${userId}`;
+};
+
+/**
+ * Helper to create app-specific storage key
+ *
+ * @param baseKey Base storage key
+ * @param appName App identifier
+ * @returns App-specific key
+ */
+export const createAppKey = (baseKey: string, appName: string): string => {
+  return `${appName}_${baseKey}`;
+};
+
+/**
+ * Helper to create namespaced storage key
+ *
+ * @param namespace Key namespace
+ * @param key Specific key
+ * @returns Namespaced key
+ */
+export const createNamespacedKey = (namespace: string, key: string): string => {
+  return `${namespace}:${key}`;
+};
+
+/**
+ * Common storage keys for cross-app usage
+ * Generic keys that can be used across multiple applications
+ */
+export enum StorageKey {
+  USER_PREFERENCES = '@user_preferences',
+  APP_SETTINGS = '@app_settings',
+  LANGUAGE = '@language',
+  UI_PREFERENCES = '@ui_preferences',
+  QUERY_CACHE = '@query_cache',
+  DATA_CACHE = '@data_cache',
+}