@umituz/react-native-settings 4.20.58 → 4.20.60

package/src/infrastructure/README.md

@@ -1,143 +1,109 @@
 # Infrastructure Layer
 
-The infrastructure layer provides concrete implementations of the interfaces defined in the application layer, handling data persistence and external service integrations.
+Provides concrete implementations of the interfaces defined in the application layer, handling data persistence and external service integrations.
 
-## Architecture
+## Purpose
+
+The infrastructure layer is responsible for all external interactions including storage, network calls, and third-party integrations. It implements the interfaces defined in the application layer and provides concrete implementations for data persistence and retrieval.
+
+## File Paths
 
 ```
-infrastructure/
+src/infrastructure/
 ├── repositories/
 │   └── SettingsRepository.ts         # Settings storage implementation
 └── services/
     └── SettingsService.ts            # Settings business logic service
 ```
 
-## Components
+## Strategy
 
-### SettingsRepository
+1. **Interface Implementation**: Implement all interfaces defined in the application layer
+2. **Dependency Injection**: Accept dependencies through constructors for testability
+3. **Error Transformation**: Convert external errors into domain-specific error types
+4. **Default Management**: Automatically create and apply default values for new users
+5. **Storage Abstraction**: Use abstract storage interfaces to remain implementation-agnostic
 
-Concrete implementation of `ISettingsRepository` using `@umituz/react-native-storage` for data persistence.
+## Restrictions
 
-#### Features
+### DO NOT
 
-- **Automatic Defaults**: Creates default settings for new users
-- **Type Safety**: Full TypeScript support
-- **Error Handling**: Comprehensive error catching and reporting
-- **Storage Integration**: Uses storage repository for persistence
+- ❌ DO NOT include business logic that belongs in the application layer
+- ❌ DO NOT expose storage-specific details to upper layers
+- ❌ DO NOT directly access React Native components
+- ❌ DO NOT make network calls without proper error handling
+- ❌ DO NOT store raw exceptions; transform to domain errors
 
-#### Usage
+### NEVER
 
-```typescript
-import { SettingsRepository } from '@umituz/react-native-settings';
+- ❌ NEVER bypass validation rules when saving data
+- ❌ NEVER expose internal storage format to external layers
+- ❌ EVER couple to specific storage implementations without abstraction
+- ❌ EVER assume data always exists; handle null/undefined cases
 
-const repository = new SettingsRepository();
+### AVOID
 
-// Get settings
-const result = await repository.getSettings('user123');
-if (result.success) {
-  console.log(result.data?.theme); // 'auto'
-}
+- ❌ AVOID hardcoding storage keys or paths
+- ❌ AVOID synchronous operations that could block the UI
+- ❌ AVOID caching without proper invalidation strategies
+- ❌ AVOID exposing implementation details in error messages
 
-// Save settings
-await repository.saveSettings({
-  userId: 'user123',
-  theme: 'dark',
-  language: 'en-US',
-  // ... other settings
-});
+## Rules
 
-// Delete settings
-await repository.deleteSettings('user123');
-```
+### ALWAYS
 
-#### Implementation Details
+- ✅ ALWAYS implement interfaces from the application layer
+- ✅ ALWAYS return Results with proper error handling
+- ✅ ALWAYS provide default values for missing data
+- ✅ ALWAYS use dependency injection for external services
+- ✅ ALWAYS handle storage errors gracefully
 
-**getSettings(userId):**
+### MUST
 
-1. Creates storage key from user ID
-2. Attempts to retrieve from storage
-3. Returns defaults if not found
-4. Saves defaults for next time
-5. Returns error on failure
+- ✅ MUST validate data before persistence
+- ✅ MUST transform storage errors to domain errors
+- ✅ MUST use async/await for all I/O operations
+- ✅ MUST ensure thread safety for concurrent operations
 
-```typescript
-const storageKey = createUserKey(StorageKey.USER_PREFERENCES, userId);
-const defaults = this.defaultSettings(userId);
-const result = await storageRepository.getItem<UserSettings>(storageKey, defaults);
+### SHOULD
 
-if (!result.success) {
-  await this.saveSettings(defaults);
-  return { success: true, data: defaults };
-}
+- ✅ SHOULD cache frequently accessed data
+- ✅ SHOULD provide retry logic for transient failures
+- ✅ SHOULD log all storage operations for debugging
+- ✅ SHOULD handle schema migrations gracefully
 
-return { success: true, data: result.data || defaults };
-```
+## AI Agent Guidelines
 
-**saveSettings(settings):**
+1. **When implementing repositories**: Always inject storage dependencies and implement the full interface
+2. **When handling errors**: Transform technical errors into user-friendly domain errors with actionable messages
+3. **When adding caching**: Implement proper cache invalidation and consider cache coherence
+4. **When dealing with defaults**: Provide sensible defaults that match the application's expected behavior
+5. **When creating migrations**: Ensure backward compatibility and provide migration paths for existing data
 
-1. Creates storage key from user ID
-2. Saves settings to storage
-3. Returns success or error
+## Components Reference
 
-```typescript
-const storageKey = createUserKey(StorageKey.USER_PREFERENCES, settings.userId);
-const result = await storageRepository.setItem(storageKey, settings);
+### SettingsRepository
 
-if (!result.success) {
-  return {
-    success: false,
-    error: {
-      code: 'SAVE_SETTINGS_FAILED',
-      message: 'Failed to save settings to storage',
-    },
-  };
-}
+Concrete implementation of `ISettingsRepository` using storage abstraction for data persistence.
 
-return { success: true };
-```
+**Location**: `/Users/umituz/Desktop/github/umituz/apps/artificial_intelligence/npm-packages/react-native-settings/src/infrastructure/repositories/SettingsRepository.ts`
 
-**deleteSettings(userId):**
-
-1. Creates storage key from user ID
-2. Removes from storage
-3. Returns success or error
-
-```typescript
-const storageKey = createUserKey(StorageKey.USER_PREFERENCES, userId);
-const result = await storageRepository.removeItem(storageKey);
-
-return result.success
-  ? { success: true }
-  : {
-      success: false,
-      error: {
-        code: 'DELETE_SETTINGS_FAILED',
-        message: 'Failed to delete settings',
-      },
-    };
-```
+**Features**:
+- Automatic defaults creation for new users
+- Full TypeScript type safety
+- Comprehensive error catching and reporting
+- Storage repository integration
 
 ### SettingsService
 
 Business logic service for high-level settings operations.
 
-#### Usage
-
-```typescript
-import { SettingsService } from '@umituz/react-native-settings';
+**Location**: `/Users/umituz/Desktop/github/umituz/apps/artificial_intelligence/npm-packages/react-native-settings/src/infrastructure/services/SettingsService.ts`
 
-const service = new SettingsService(repository);
-
-// Initialize settings for new user
-await service.initializeUser('user123');
-
-// Update specific settings
-await service.updateTheme('user123', 'dark');
-await service.updateLanguage('user123', 'tr-TR');
-
-// Reset to defaults
-await service.resetToDefaults('user123');
-```
+**Features**:
+- User initialization
+- Partial setting updates
+- Reset to defaults functionality
 
 ## Storage Integration
 
@@ -145,35 +111,13 @@ await service.resetToDefaults('user123');
 
 The repository uses the following storage keys:
 
-```typescript
-enum StorageKey {
-  USER_PREFERENCES = 'user_preferences',  // Main settings storage
-}
-```
+- `USER_PREFERENCES` - Main settings storage key
 
 ### Storage Format
 
-Settings are stored as JSON:
-
-```json
-{
-  "userId": "user123",
-  "theme": "dark",
-  "language": "en-US",
-  "notificationsEnabled": true,
-  "emailNotifications": true,
-  "pushNotifications": false,
-  "soundEnabled": true,
-  "vibrationEnabled": false,
-  "privacyMode": false,
-  "disclaimerAccepted": true,
-  "updatedAt": "2025-01-08T10:30:00.000Z"
-}
-```
-
-## Default Settings
+Settings are stored as JSON with all user preferences including theme, language, notifications, and timestamps.
 
-When creating new settings, these defaults are used:
+## Default Values
 
 | Setting | Default Value | Description |
 |---------|---------------|-------------|
@@ -191,19 +135,8 @@ When creating new settings, these defaults are used:
 
 All repository methods return `SettingsResult<T>`:
 
-```typescript
-// Success case
-{ success: true, data: settings }
-
-// Error case
-{
-  success: false,
-  error: {
-    code: 'GET_SETTINGS_FAILED',
-    message: 'Detailed error message'
-  }
-}
-```
+**Success case**: `{ success: true, data: settings }`
+**Error case**: `{ success: false, error: { code: string, message: string } }`
 
 ### Error Codes
 
@@ -213,296 +146,16 @@ All repository methods return `SettingsResult<T>`:
 | `SAVE_SETTINGS_FAILED` | Failed to save settings |
 | `DELETE_SETTINGS_FAILED` | Failed to delete settings |
 
-## Examples
-
-### Custom Repository Implementation
-
-```typescript
-import type { ISettingsRepository, UserSettings, SettingsResult } from '@umituz/react-native-settings';
-
-class AsyncStorageRepository implements ISettingsRepository {
-  async getSettings(userId: string): Promise<SettingsResult<UserSettings>> {
-    try {
-      const key = `settings_${userId}`;
-      const json = await AsyncStorage.getItem(key);
-
-      if (!json) {
-        return {
-          success: false,
-          error: { code: 'NOT_FOUND', message: 'Settings not found' },
-        };
-      }
-
-      const data = JSON.parse(json);
-      return { success: true, data };
-    } catch (error) {
-      return {
-        success: false,
-        error: {
-          code: 'GET_SETTINGS_FAILED',
-          message: error.message,
-        },
-      };
-    }
-  }
-
-  async saveSettings(settings: UserSettings): Promise<SettingsResult<void>> {
-    try {
-      const key = `settings_${settings.userId}`;
-      const json = JSON.stringify(settings);
-      await AsyncStorage.setItem(key, json);
-      return { success: true };
-    } catch (error) {
-      return {
-        success: false,
-        error: {
-          code: 'SAVE_SETTINGS_FAILED',
-          message: error.message,
-        },
-      };
-    }
-  }
-
-  async deleteSettings(userId: string): Promise<SettingsResult<void>> {
-    try {
-      const key = `settings_${userId}`;
-      await AsyncStorage.removeItem(key);
-      return { success: true };
-    } catch (error) {
-      return {
-        success: false,
-        error: {
-          code: 'DELETE_SETTINGS_FAILED',
-          message: error.message,
-        },
-      };
-    }
-  }
-}
-```
-
-### Using Custom Repository
-
-```typescript
-import { useSettings } from '@umituz/react-native-settings';
-
-// Provide custom repository to your app
-const customRepository = new AsyncStorageRepository();
-
-function App() {
-  return (
-    <SettingsProvider repository={customRepository}>
-      <MyApp />
-    </SettingsProvider>
-  );
-}
-```
-
-### Migration Handler
-
-```typescript
-class MigrationSettingsRepository implements ISettingsRepository {
-  constructor(private baseRepository: ISettingsRepository) {}
-
-  async getSettings(userId: string): Promise<SettingsResult<UserSettings>> {
-    const result = await this.baseRepository.getSettings(userId);
-
-    if (result.success && result.data) {
-      // Migration: Add new fields
-      const migrated = this.migrateSettings(result.data);
-      if (migrated !== result.data) {
-        await this.saveSettings(migrated);
-        return { success: true, data: migrated };
-      }
-    }
-
-    return result;
-  }
-
-  private migrateSettings(settings: UserSettings): UserSettings {
-    // Add new field with default
-    if (!('newField' in settings)) {
-      return { ...settings, newField: defaultValue };
-    }
-    return settings;
-  }
-
-  // Delegate other methods
-  async saveSettings(settings: UserSettings) {
-    return this.baseRepository.saveSettings(settings);
-  }
-
-  async deleteSettings(userId: string) {
-    return this.baseRepository.deleteSettings(userId);
-  }
-}
-```
-
-### Encrypted Storage
-
-```typescript
-import * as SecureStore from 'expo-secure-store';
-
-class SecureSettingsRepository implements ISettingsRepository {
-  async getSettings(userId: string): Promise<SettingsResult<UserSettings>> {
-    try {
-      const key = `secure_settings_${userId}`;
-      const json = await SecureStore.getItemAsync(key);
-
-      if (!json) {
-        return { success: false, error: { code: 'NOT_FOUND', message: 'Not found' } };
-      }
-
-      const data = JSON.parse(json);
-      return { success: true, data };
-    } catch (error) {
-      return {
-        success: false,
-        error: { code: 'GET_SETTINGS_FAILED', message: error.message },
-      };
-    }
-  }
-
-  async saveSettings(settings: UserSettings): Promise<SettingsResult<void>> {
-    try {
-      const key = `secure_settings_${settings.userId}`;
-      const json = JSON.stringify(settings);
-      await SecureStore.setItemAsync(key, json);
-      return { success: true };
-    } catch (error) {
-      return {
-        success: false,
-        error: { code: 'SAVE_SETTINGS_FAILED', message: error.message },
-      };
-    }
-  }
-
-  async deleteSettings(userId: string): Promise<SettingsResult<void>> {
-    try {
-      const key = `secure_settings_${userId}`;
-      await SecureStore.deleteItemAsync(key);
-      return { success: true };
-    } catch (error) {
-      return {
-        success: false,
-        error: { code: 'DELETE_SETTINGS_FAILED', message: error.message },
-      };
-    }
-  }
-}
-```
-
 ## Testing
 
-### Mock Repository
-
-```typescript
-class MockSettingsRepository implements ISettingsRepository {
-  private storage: Map<string, UserSettings> = new Map();
-
-  async getSettings(userId: string): Promise<SettingsResult<UserSettings>> {
-    const settings = this.storage.get(userId);
-    return settings
-      ? { success: true, data: settings }
-      : { success: false, error: { code: 'NOT_FOUND', message: 'Not found' } };
-  }
-
-  async saveSettings(settings: UserSettings): Promise<SettingsResult<void>> {
-    this.storage.set(settings.userId, settings);
-    return { success: true };
-  }
-
-  async deleteSettings(userId: string): Promise<SettingsResult<void>> {
-    this.storage.delete(userId);
-    return { success: true };
-  }
-
-  // Test helper methods
-  clear() {
-    this.storage.clear();
-  }
-
-  hasSettings(userId: string): boolean {
-    return this.storage.has(userId);
-  }
-}
-```
-
-### Test Example
-
-```typescript
-import { SettingsRepository } from '@umituz/react-native-settings';
-
-describe('SettingsRepository', () => {
-  let repository: SettingsRepository;
-
-  beforeEach(() => {
-    repository = new SettingsRepository();
-  });
-
-  it('should save and retrieve settings', async () => {
-    const settings: UserSettings = {
-      userId: 'test123',
-      theme: 'dark',
-      language: 'en-US',
-      notificationsEnabled: true,
-      emailNotifications: true,
-      pushNotifications: false,
-      soundEnabled: true,
-      vibrationEnabled: false,
-      privacyMode: false,
-      disclaimerAccepted: true,
-      updatedAt: new Date(),
-    };
-
-    const saveResult = await repository.saveSettings(settings);
-    expect(saveResult.success).toBe(true);
-
-    const getResult = await repository.getSettings('test123');
-    expect(getResult.success).toBe(true);
-    expect(getResult.data?.theme).toBe('dark');
-  });
-
-  it('should return defaults for new user', async () => {
-    const result = await repository.getSettings('newuser');
-
-    expect(result.success).toBe(true);
-    expect(result.data?.theme).toBe('auto');
-    expect(result.data?.language).toBe('en-US');
-  });
-
-  it('should delete settings', async () => {
-    await repository.saveSettings({
-      userId: 'deleteMe',
-      theme: 'light',
-      // ... other required fields
-    } as any);
-
-    const deleteResult = await repository.deleteSettings('deleteMe');
-    expect(deleteResult.success).toBe(true);
-
-    const getResult = await repository.getSettings('deleteMe');
-    expect(getResult.data?.theme).toBe('auto'); // Returns defaults
-  });
-});
-```
-
-## Best Practices
-
-1. **Use Repository Interface**: Program to `ISettingsRepository`, not concrete implementation
-2. **Handle Errors**: Always check `success` flag
-3. **Type Safety**: Use TypeScript types for all operations
-4. **Validation**: Validate data before saving
-5. **Default Values**: Always provide sensible defaults
-6. **Error Messages**: Include detailed, helpful error messages
-7. **Testing**: Use mock repositories in tests
-8. **Migration**: Handle schema migrations gracefully
+### Mock Repository Pattern
 
-## Related
+Create mock implementations for testing that implement `ISettingsRepository`:
 
-- **Application Layer**: Repository interfaces and types
-- **Presentation Hooks**: React hooks for UI integration
-- **Storage Package**: `@umituz/react-native-storage`
+1. Use in-memory storage (Map or object)
+2. Implement all interface methods
+3. Provide test helper methods (clear, hasSettings, etc.)
+4. Simulate errors for error handling tests
 
 ## License