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

package/src/storage/infrastructure/repositories/AsyncStorageRepository.ts

@@ -0,0 +1,98 @@
+/**
+ * AsyncStorage Repository
+ *
+ * Domain-Driven Design: Infrastructure implementation of IStorageRepository
+ * Adapts React Native AsyncStorage to domain interface using composition
+ */
+
+import type { IStorageRepository } from '../../application/ports/IStorageRepository';
+import type { StorageResult } from '../../domain/entities/StorageResult';
+import { BaseStorageOperations } from './BaseStorageOperations';
+import { StringStorageOperations } from './StringStorageOperations';
+import { BatchStorageOperations } from './BatchStorageOperations';
+
+/**
+ * AsyncStorage Repository Implementation
+ * Uses composition to follow Single Responsibility Principle
+ */
+export class AsyncStorageRepository implements IStorageRepository {
+  private baseOps: BaseStorageOperations;
+  private stringOps: StringStorageOperations;
+  private batchOps: BatchStorageOperations;
+
+  constructor() {
+    this.baseOps = new BaseStorageOperations();
+    this.stringOps = new StringStorageOperations();
+    this.batchOps = new BatchStorageOperations();
+  }
+
+  /**
+   * Get item from AsyncStorage with type safety
+   */
+  async getItem<T>(key: string, defaultValue: T): Promise<StorageResult<T>> {
+    return this.baseOps.getItem(key, defaultValue);
+  }
+
+  /**
+   * Set item in AsyncStorage with automatic JSON serialization
+   */
+  async setItem<T>(key: string, value: T): Promise<StorageResult<T>> {
+    return this.baseOps.setItem(key, value);
+  }
+
+  /**
+   * Get string value (no JSON parsing)
+   */
+  async getString(key: string, defaultValue: string): Promise<StorageResult<string>> {
+    return this.stringOps.getString(key, defaultValue);
+  }
+
+  /**
+   * Set string value (no JSON serialization)
+   */
+  async setString(key: string, value: string): Promise<StorageResult<string>> {
+    return this.stringOps.setString(key, value);
+  }
+
+  /**
+   * Remove item from AsyncStorage
+   */
+  async removeItem(key: string): Promise<StorageResult<void>> {
+    return this.baseOps.removeItem(key);
+  }
+
+  /**
+   * Check if key exists in storage
+   */
+  async hasItem(key: string): Promise<boolean> {
+    return this.baseOps.hasItem(key);
+  }
+
+  /**
+   * Clear all AsyncStorage data
+   */
+  async clearAll(): Promise<StorageResult<void>> {
+    return this.baseOps.clearAll();
+  }
+
+  /**
+   * Get multiple items at once
+   */
+  async getMultiple(
+    keys: string[]
+  ): Promise<StorageResult<Record<string, string | null>>> {
+    return this.batchOps.getMultiple(keys);
+  }
+
+  /**
+   * Get all keys from storage
+   */
+  async getAllKeys(): Promise<StorageResult<string[]>> {
+    return this.batchOps.getAllKeys();
+  }
+}
+
+/**
+ * Singleton instance
+ */
+export const storageRepository = new AsyncStorageRepository();

package/src/storage/infrastructure/repositories/BaseStorageOperations.ts

@@ -0,0 +1,100 @@
+/**
+ * Base Storage Operations
+ *
+ * Core storage operations following Single Responsibility Principle
+ */
+
+import AsyncStorage from '@react-native-async-storage/async-storage';
+import type { StorageResult } from '../../domain/entities/StorageResult';
+import { success, failure } from '../../domain/entities/StorageResult';
+import {
+  StorageReadError,
+  StorageWriteError,
+  StorageDeleteError,
+  StorageSerializationError,
+  StorageDeserializationError,
+} from '../../domain/errors/StorageError';
+import { devWarn } from '../../domain/utils/devUtils';
+
+/**
+ * Base storage operations implementation
+ */
+export class BaseStorageOperations {
+  /**
+   * Get item from AsyncStorage with type safety
+   */
+  async getItem<T>(key: string, defaultValue: T): Promise<StorageResult<T>> {
+    try {
+      const value = await AsyncStorage.getItem(key);
+
+      if (value === null) {
+        return success(defaultValue);
+      }
+
+      try {
+        const parsed = JSON.parse(value) as T;
+        return success(parsed);
+      } catch (parseError) {
+        return failure(new StorageDeserializationError(key, parseError), defaultValue);
+      }
+    } catch (error) {
+      return failure(new StorageReadError(key, error), defaultValue);
+    }
+  }
+
+  /**
+   * Set item in AsyncStorage with automatic JSON serialization
+   */
+  async setItem<T>(key: string, value: T): Promise<StorageResult<T>> {
+    try {
+      let serialized: string;
+      try {
+        serialized = JSON.stringify(value);
+      } catch (serializeError) {
+        return failure(new StorageSerializationError(key, serializeError));
+      }
+
+      await AsyncStorage.setItem(key, serialized);
+      return success(value);
+    } catch (error) {
+      return failure(new StorageWriteError(key, error));
+    }
+  }
+
+  /**
+   * Remove item from AsyncStorage
+   */
+  async removeItem(key: string): Promise<StorageResult<void>> {
+    try {
+      await AsyncStorage.removeItem(key);
+      return success(undefined);
+    } catch (error) {
+      return failure(new StorageDeleteError(key, error));
+    }
+  }
+
+  /**
+   * Check if key exists in storage
+   */
+  async hasItem(key: string): Promise<boolean> {
+    try {
+      const value = await AsyncStorage.getItem(key);
+      return value !== null;
+    } catch (error) {
+      devWarn(`BaseStorageOperations: Failed to check if key "${key}" exists`, error);
+      return false;
+    }
+  }
+
+  /**
+   * Clear all AsyncStorage data
+   */
+  async clearAll(): Promise<StorageResult<void>> {
+    try {
+      await AsyncStorage.clear();
+      return success(undefined);
+    } catch (error) {
+      return failure(new StorageDeleteError('ALL_KEYS', error));
+    }
+  }
+}

package/src/storage/infrastructure/repositories/BatchStorageOperations.ts

@@ -0,0 +1,42 @@
+/**
+ * Batch Storage Operations
+ *
+ * Batch operations following Single Responsibility Principle
+ */
+
+import AsyncStorage from '@react-native-async-storage/async-storage';
+import type { StorageResult } from '../../domain/entities/StorageResult';
+import { success, failure } from '../../domain/entities/StorageResult';
+import { StorageReadError } from '../../domain/errors/StorageError';
+
+/**
+ * Batch storage operations for efficiency
+ */
+export class BatchStorageOperations {
+  /**
+   * Get multiple items at once
+   */
+  async getMultiple(
+    keys: string[]
+  ): Promise<StorageResult<Record<string, string | null>>> {
+    try {
+      const pairs = await AsyncStorage.multiGet(keys);
+      const result = Object.fromEntries(pairs);
+      return success(result);
+    } catch (error) {
+      return failure(new StorageReadError('MULTIPLE_KEYS', error));
+    }
+  }
+
+  /**
+   * Get all keys from storage
+   */
+  async getAllKeys(): Promise<StorageResult<string[]>> {
+    try {
+      const keys = await AsyncStorage.getAllKeys();
+      return success([...keys]);
+    } catch (error) {
+      return failure(new StorageReadError('ALL_KEYS', error));
+    }
+  }
+}

package/src/storage/infrastructure/repositories/README.md

@@ -0,0 +1,121 @@
+# Storage Repositories
+
+Repository pattern implementation for data persistence with error handling.
+
+## Overview
+
+AsyncStorageRepository provides storage operations with Result pattern for error handling. Located at `src/infrastructure/repositories/`.
+
+## Strategies
+
+### Result Pattern
+- Return Result objects instead of throwing exceptions
+- Use success/failure states for predictable error handling
+- Include error details in failure results
+- Allow graceful degradation when operations fail
+
+### Serialization Strategy
+- Automatically serialize objects to JSON
+- Deserialize with type safety using generics
+- Handle circular reference errors gracefully
+- Support all JSON-serializable types
+
+### Error Handling Strategy
+- Categorize errors by type (read, write, serialization)
+- Include key name in error context
+- Preserve original error as cause
+- Log errors for debugging
+
+### Performance Strategy
+- Use parallel operations for batch operations
+- Implement chunking for large datasets
+- Avoid synchronous operations on main thread
+- Cache frequently accessed values
+
+## Restrictions
+
+### Storage Operations
+- DO NOT store non-JSON-serializable data (functions, class instances)
+- DO NOT store circular references
+- DO NOT use undefined values (use null instead)
+- DO NOT store extremely large payloads (> 1MB) without chunking
+
+### Error Handling
+- DO NOT ignore error states in Result objects
+- DO NOT throw exceptions from repository methods
+- DO NOT return null for missing keys (use defaultValue)
+- DO NOT suppress error logging in production
+
+### Type Safety
+- DO NOT use `any` type for stored values
+- DO NOT skip type parameters on generic methods
+- DO NOT assume Result is always successful
+- DO NOT cast results without checking success flag
+
+### Performance
+- DO NOT perform sequential operations in loops (use parallel)
+- DO NOT read same key multiple times without caching
+- DO NOT write to storage on every state change (debounce)
+- DO NOT store redundant data
+
+## Rules
+
+### Interface Implementation
+- MUST implement IStorageRepository interface completely
+- MUST return StorageResult<T> for all methods
+- MUST include error details in failure results
+- MUST handle all exceptions internally
+
+### Method Signatures
+- MUST provide generic type parameter for type safety
+- MUST accept defaultValue parameter for getItem methods
+- MUST return Promise for all async operations
+- MUST preserve key names in error messages
+
+### Error Handling
+- MUST wrap all storage operations in try-catch
+- MUST return failure Result on errors
+- MUST include error code and message
+- MUST log errors before returning failure
+
+### Serialization
+- MUST use JSON.stringify for setItem operations
+- MUST use JSON.parse for getItem operations
+- MUST handle JSON parsing errors
+- MUST validate deserialized structure
+
+### Type Safety
+- MUST enforce type parameter consistency
+- MUST use type guards for runtime validation
+- MUST provide type inference for return values
+- MUST avoid type assertions when possible
+
+### Result Objects
+- MUST set success flag to true or false
+- MUST include data in success results
+- MUST include error in failure results
+- MUST check success flag before accessing data
+
+### Singleton Usage
+- MUST use exported singleton instance
+- MUST NOT create multiple repository instances
+- MUST reset state between tests
+- MUST clear storage in test setup
+
+### Testing
+- MUST mock repository for unit tests
+- MUST use real repository for integration tests
+- MUST clear storage before each test
+- MUST test both success and failure scenarios
+
+### Performance
+- MUST use Promise.all for parallel operations
+- MUST implement debouncing for frequent writes
+- MUST use appropriate chunk sizes for large data
+- MUST monitor storage size limits
+
+### Error Categories
+- MUST use StorageReadError for read failures
+- MUST use StorageWriteError for write failures
+- MUST use StorageSerializationError for serialization failures
+- MUST use StorageDeserializationError for parsing failures

package/src/storage/infrastructure/repositories/StringStorageOperations.ts

@@ -0,0 +1,44 @@
+/**
+ * String Storage Operations
+ *
+ * Specialized string operations following Single Responsibility Principle
+ */
+
+import AsyncStorage from '@react-native-async-storage/async-storage';
+import type { StorageResult } from '../../domain/entities/StorageResult';
+import { success, failure } from '../../domain/entities/StorageResult';
+import { StorageReadError, StorageWriteError } from '../../domain/errors/StorageError';
+
+/**
+ * String-specific storage operations
+ */
+export class StringStorageOperations {
+  /**
+   * Get string value (no JSON parsing)
+   */
+  async getString(key: string, defaultValue: string): Promise<StorageResult<string>> {
+    try {
+      const value = await AsyncStorage.getItem(key);
+
+      if (value === null) {
+        return success(defaultValue);
+      }
+
+      return success(value);
+    } catch (error) {
+      return failure(new StorageReadError(key, error), defaultValue);
+    }
+  }
+
+  /**
+   * Set string value (no JSON serialization)
+   */
+  async setString(key: string, value: string): Promise<StorageResult<string>> {
+    try {
+      await AsyncStorage.setItem(key, value);
+      return success(value);
+    } catch (error) {
+      return failure(new StorageWriteError(key, error));
+    }
+  }
+}

package/src/storage/infrastructure/repositories/__tests__/AsyncStorageRepository.test.ts

@@ -0,0 +1,170 @@
+/* eslint-disable @typescript-eslint/no-unused-vars */
+/**
+ * AsyncStorageRepository Tests
+ *
+ * Unit tests for AsyncStorageRepository
+ */
+
+import { AsyncStorageRepository } from '../AsyncStorageRepository';
+import { AsyncStorage } from '../../__tests__/mocks/asyncStorage.mock';
+
+describe('AsyncStorageRepository', () => {
+  let repository: AsyncStorageRepository;
+
+  beforeEach(() => {
+    repository = new AsyncStorageRepository();
+    (AsyncStorage as any).__clear();
+  });
+
+  describe('Composition', () => {
+    it('should use composition pattern', () => {
+      expect(repository).toBeInstanceOf(AsyncStorageRepository);
+      
+      // Test that all methods are available
+      expect(typeof repository.getItem).toBe('function');
+      expect(typeof repository.setItem).toBe('function');
+      expect(typeof repository.getString).toBe('function');
+      expect(typeof repository.setString).toBe('function');
+      expect(typeof repository.removeItem).toBe('function');
+      expect(typeof repository.hasItem).toBe('function');
+      expect(typeof repository.clearAll).toBe('function');
+      expect(typeof repository.getMultiple).toBe('function');
+      expect(typeof repository.getAllKeys).toBe('function');
+    });
+  });
+
+  describe('Delegation', () => {
+    it('should delegate getItem to BaseStorageOperations', async () => {
+      const key = 'test-key';
+      const defaultValue = 'default';
+      const expectedValue = 'test-value';
+
+      await AsyncStorage.setItem(key, JSON.stringify(expectedValue));
+
+      const result = await repository.getItem(key, defaultValue);
+
+      expect(result.success).toBe(true);
+      expect(result.data).toBe(expectedValue);
+    });
+
+    it('should delegate setItem to BaseStorageOperations', async () => {
+      const key = 'test-key';
+      const value = 'test-value';
+
+      const result = await repository.setItem(key, value);
+
+      expect(result.success).toBe(true);
+      expect(result.data).toBe(value);
+    });
+
+    it('should delegate getString to StringStorageOperations', async () => {
+      const key = 'test-key';
+      const defaultValue = 'default';
+      const expectedValue = 'test-string';
+
+      await AsyncStorage.setItem(key, expectedValue);
+
+      const result = await repository.getString(key, defaultValue);
+
+      expect(result.success).toBe(true);
+      expect(result.data).toBe(expectedValue);
+    });
+
+    it('should delegate setString to StringStorageOperations', async () => {
+      const key = 'test-key';
+      const value = 'test-string';
+
+      const result = await repository.setString(key, value);
+
+      expect(result.success).toBe(true);
+      expect(result.data).toBe(value);
+    });
+
+    it('should delegate removeItem to BaseStorageOperations', async () => {
+      const key = 'test-key';
+
+      await AsyncStorage.setItem(key, 'test-value');
+
+      const result = await repository.removeItem(key);
+
+      expect(result.success).toBe(true);
+    });
+
+    it('should delegate hasItem to BaseStorageOperations', async () => {
+      const key = 'test-key';
+
+      await AsyncStorage.setItem(key, 'test-value');
+
+      const exists = await repository.hasItem(key);
+
+      expect(exists).toBe(true);
+    });
+
+    it('should delegate clearAll to BaseStorageOperations', async () => {
+      await AsyncStorage.setItem('key1', 'value1');
+      await AsyncStorage.setItem('key2', 'value2');
+
+      const result = await repository.clearAll();
+
+      expect(result.success).toBe(true);
+    });
+
+    it('should delegate getMultiple to BatchStorageOperations', async () => {
+      const keys = ['key1', 'key2'];
+      
+      await AsyncStorage.setItem('key1', 'value1');
+      await AsyncStorage.setItem('key2', 'value2');
+
+      const result = await repository.getMultiple(keys);
+
+      expect(result.success).toBe(true);
+      expect(result.data).toEqual({
+        key1: 'value1',
+        key2: 'value2'
+      });
+    });
+
+    it('should delegate getAllKeys to BatchStorageOperations', async () => {
+      await AsyncStorage.setItem('key1', 'value1');
+      await AsyncStorage.setItem('key2', 'value2');
+
+      const result = await repository.getAllKeys();
+
+      expect(result.success).toBe(true);
+      expect(result.data).toEqual(expect.arrayContaining(['key1', 'key2']));
+    });
+  });
+
+  describe('Error Handling', () => {
+    it('should handle errors from delegated operations', async () => {
+      const key = 'test-key';
+      
+      // Mock error in AsyncStorage
+      (AsyncStorage.getItem as jest.Mock).mockRejectedValue(new Error('Storage error'));
+
+      const result = await repository.getItem(key, 'default');
+
+      expect(result.success).toBe(false);
+      expect(result.error).toBeDefined();
+    });
+  });
+
+  describe('Type Safety', () => {
+    it('should maintain type safety for generic methods', async () => {
+      interface TestData {
+        id: number;
+        name: string;
+      }
+
+      const key = 'typed-key';
+      const data: TestData = { id: 1, name: 'test' };
+
+      const setResult = await repository.setItem<TestData>(key, data);
+      const getResult = await repository.getItem<TestData>(key, { id: 0, name: '' });
+
+      expect(setResult.success).toBe(true);
+      expect(getResult.success).toBe(true);
+      expect(getResult.data).toEqual(data);
+    });
+  });
+});