http-request-manager 18.7.21 → 18.7.24

package/STORE_STATE_MANAGER_README.md

@@ -1,1322 +0,0 @@
-# Store State Manager Service
-
-The `StoreStateManagerService` extends `ComponentStore` to provide persistent state management synchronized with local or session storage. It bridges the gap between in-memory state and persistent storage.
-
-## Overview
-
-This service provides:
-
-- **ComponentStore Extension** - Full ComponentStore functionality with persistence
-- **Storage Synchronization** - Automatic state save/restore from localStorage/sessionStorage
-- **Encryption Support** - Optional encryption for sensitive state data
-- **Model Adaptation** - Support for model adapters to ensure state structure
-- **Reactivity** - Maintains all ComponentStore benefits (selectors, updaters, effects)
-- **Migration Support** - Built-in support for state migrations
-
-## Installation
-
-```typescript
-import { HttpRequestManagerModule } from 'http-request-manager';
-
-@NgModule({
-  imports: [HttpRequestManagerModule.forRoot({
-    LocalStorageOptions: {
-      storageName: 'app-state',
-      options: { encrypted: true }
-    }
-  })]
-})
-export class AppModule { }
-```
-
-## Basic Usage
-
-### Creating a Persistent State Service
-
-```typescript
-import { Injectable } from '@angular/core';
-import { StoreStateManagerService, StateStorageOptions, SettingOptions } from 'http-request-manager';
-import { StorageType } from 'http-request-manager';
-
-interface UserSettings {
-  theme: 'light' | 'dark';
-  language: string;
-  notifications: boolean;
-  emailDigest: boolean;
-  autoSave: boolean;
-}
-
-@Injectable({
-  providedIn: 'root'
-})
-export class UserSettingsStateService extends StoreStateManagerService<UserSettings> {
-
-  constructor() {
-    super(
-      StateStorageOptions.adapt({
-        store: 'user-settings',           // Unique store name
-        options: SettingOptions.adapt({
-          storage: StorageType.GLOBAL,   // localStorage
-          encrypted: true,               // Encrypt sensitive data
-          expiresIn: '30d'              // 30 days expiration
-        }),
-        model: UserSettings.adapt         // Model adapter for validation
-      })
-    );
-  }
-
-  // Public API methods
-  updateTheme(theme: 'light' | 'dark') {
-    this.updateData({ theme });
-  }
-
-  updateLanguage(language: string) {
-    this.updateData({ language });
-  }
-
-  toggleNotifications() {
-    this.updateData(state => ({
-      ...state,
-      notifications: !state.notifications
-    }));
-  }
-
-  toggleEmailDigest() {
-    this.updateData(state => ({
-      ...state,
-      emailDigest: !state.emailDigest
-    }));
-  }
-
-  updateAutoSave(enabled: boolean) {
-    this.updateData({ autoSave: enabled });
-  }
-
-  resetToDefaults() {
-    this.updateData({
-      theme: 'light',
-      language: 'en',
-      notifications: true,
-      emailDigest: false,
-      autoSave: true
-    });
-  }
-}
-```
-
-### Using in Components
-
-```typescript
-import { Component, inject } from '@angular/core';
-import { UserSettingsStateService } from './user-settings-state.service';
-
-@Component({
-  selector: 'app-settings',
-  template: `
-    <div class="settings-container">
-      <h2>User Settings</h2>
-      
-      <div class="setting-section">
-        <h3>Appearance</h3>
-        <div class="setting-item">
-          <label>Theme:</label>
-          <select [value]="settings?.theme" (change)="updateTheme($any($event.target).value)">
-            <option value="light">Light</option>
-            <option value="dark">Dark</option>
-          </select>
-        </div>
-      </div>
-      
-      <div class="setting-section">
-        <h3>Localization</h3>
-        <div class="setting-item">
-          <label>Language:</label>
-          <select [value]="settings?.language" (change)="updateLanguage($any($event.target).value)">
-            <option value="en">English</option>
-            <option value="es">Español</option>
-            <option value="fr">Français</option>
-          </select>
-        </div>
-      </div>
-      
-      <div class="setting-section">
-        <h3>Notifications</h3>
-        <div class="setting-item">
-          <label>
-            <input type="checkbox" [checked]="settings?.notifications" 
-                   (change)="toggleNotifications()">
-            Enable Push Notifications
-          </label>
-        </div>
-        <div class="setting-item">
-          <label>
-            <input type="checkbox" [checked]="settings?.emailDigest" 
-                   (change)="toggleEmailDigest()">
-            Weekly Email Digest
-          </label>
-        </div>
-      </div>
-      
-      <div class="setting-section">
-        <h3>Preferences</h3>
-        <div class="setting-item">
-          <label>
-            <input type="checkbox" [checked]="settings?.autoSave" 
-                   (change)="updateAutoSave($any($event.target).checked)">
-            Auto-save Changes
-          </label>
-        </div>
-      </div>
-      
-      <div class="actions">
-        <button (click)="resetToDefaults()">Reset to Defaults</button>
-        <button (click)="exportSettings()">Export Settings</button>
-        <button (click)="clearSettings()">Clear All</button>
-      </div>
-      
-      <div class="storage-info" *ngIf="storageInfo">
-        <p>Last updated: {{ storageInfo.lastUpdated | date:'medium' }}</p>
-        <p>Storage type: {{ storageInfo.storageType }}</p>
-        <p>Encrypted: {{ storageInfo.encrypted ? 'Yes' : 'No' }}</p>
-      </div>
-    </div>
-  `
-})
-export class SettingsComponent {
-  private settingsStore = inject(UserSettingsStateService);
-  
-  settings = this.settingsStore.data$;
-  storageInfo = this.settingsStore.storageInfo$;
-  
-  updateTheme(theme: 'light' | 'dark') {
-    this.settingsStore.updateTheme(theme);
-  }
-  
-  updateLanguage(language: string) {
-    this.settingsStore.updateLanguage(language);
-  }
-  
-  toggleNotifications() {
-    this.settingsStore.toggleNotifications();
-  }
-  
-  toggleEmailDigest() {
-    this.settingsStore.toggleEmailDigest();
-  }
-  
-  updateAutoSave(enabled: boolean) {
-    this.settingsStore.updateAutoSave(enabled);
-  }
-  
-  resetToDefaults() {
-    this.settingsStore.resetToDefaults();
-  }
-  
-  exportSettings() {
-    const settings = this.settingsStore.exportData();
-    console.log('Settings exported:', settings);
-  }
-  
-  clearSettings() {
-    this.settingsStore.clearData();
-  }
-}
-```
-
-## API Reference
-
-### Constructor Options
-
-#### StateStorageOptions
-
-```typescript
-interface StateStorageOptions {
-  store: string;              // Unique store name
-  options: SettingOptions;    // Storage configuration
-  model?: Function;           // Model adapter for validation
-  version?: number;           // State version for migrations
-}
-```
-
-### State Management Methods
-
-#### updateData(updater: ((state: T) => T) | T): void
-
-Update state with new data or updater function:
-
-```typescript
-// Direct update
-this.store.updateData({ theme: 'dark' });
-
-// Function update
-this.store.updateData(state => ({
-  ...state,
-  notifications: !state.notifications
-}));
-```
-
-#### clearData(): void
-
-Clear all stored data:
-
-```typescript
-this.store.clearData();
-```
-
-### Selectors
-
-#### data$: Observable<T>
-
-Get current state:
-
-```typescript
-settings$ = this.store.data$;
-
-<div *ngIf="settings$ | async as settings">
-  Theme: {{ settings.theme }}
-</div>
-```
-
-#### storageInfo$: Observable<any>
-
-Get storage metadata:
-
-```typescript
-info$ = this.store.storageInfo$;
-
-<div *ngIf="info$ | async as info">
-  Last updated: {{ info.lastUpdated }}
-  Encrypted: {{ info.encrypted }}
-</div>
-```
-
-### Data Operations
-
-#### exportData(): any
-
-Export current state:
-
-```typescript
-const exportedData = this.store.exportData();
-console.log('Exported state:', exportedData);
-```
-
-#### importData(data: any): void
-
-Import state data:
-
-```typescript
-this.store.importData({
-  theme: 'dark',
-  language: 'en',
-  notifications: true
-});
-```
-
-## Advanced Examples
-
-### Shopping Cart State
-
-```typescript
-interface CartItem {
-  id: string;
-  name: string;
-  price: number;
-  quantity: number;
-  image?: string;
-}
-
-interface CartState {
-  items: CartItem[];
-  total: number;
-  itemCount: number;
-  lastUpdated: Date;
-  promoCode?: string;
-  discount: number;
-}
-
-@Injectable()
-export class ShoppingCartStateService extends StoreStateManagerService<CartState> {
-
-  constructor() {
-    super(
-      StateStorageOptions.adapt({
-        store: 'shopping-cart',
-        options: SettingOptions.adapt({
-          storage: StorageType.GLOBAL,
-          encrypted: false,
-          expiresIn: '7d'
-        }),
-        model: CartState.adapt
-      })
-    );
-  }
-
-  // Cart operations
-  addItem(item: Omit<CartItem, 'quantity'>) {
-    this.updateData(state => {
-      const existingItem = state.items.find(i => i.id === item.id);
-      
-      let newItems: CartItem[];
-      if (existingItem) {
-        newItems = state.items.map(i => 
-          i.id === item.id 
-            ? { ...i, quantity: i.quantity + 1 }
-            : i
-        );
-      } else {
-        newItems = [...state.items, { ...item, quantity: 1 }];
-      }
-      
-      return this.calculateTotals({ ...state, items: newItems });
-    });
-  }
-
-  removeItem(itemId: string) {
-    this.updateData(state => ({
-      ...state,
-      items: state.items.filter(item => item.id !== itemId),
-      lastUpdated: new Date()
-    }));
-  }
-
-  updateQuantity(itemId: string, quantity: number) {
-    if (quantity <= 0) {
-      this.removeItem(itemId);
-      return;
-    }
-
-    this.updateData(state => {
-      const newItems = state.items.map(item =>
-        item.id === itemId ? { ...item, quantity } : item
-      );
-      
-      return this.calculateTotals({ ...state, items: newItems });
-    });
-  }
-
-  clearCart() {
-    this.updateData({
-      items: [],
-      total: 0,
-      itemCount: 0,
-      lastUpdated: new Date(),
-      discount: 0
-    });
-  }
-
-  applyPromoCode(promoCode: string) {
-    this.updateData(state => {
-      const discount = this.calculateDiscount(promoCode, state.total);
-      return {
-        ...state,
-        promoCode,
-        discount,
-        lastUpdated: new Date()
-      };
-    });
-  }
-
-  removePromoCode() {
-    this.updateData(state => ({
-      ...state,
-      promoCode: undefined,
-      discount: 0,
-      lastUpdated: new Date()
-    }));
-  }
-
-  // Computed values
-  getTotal() {
-    return this.data$.pipe(map(state => state.total));
-  }
-
-  getItemCount() {
-    return this.data$.pipe(map(state => state.itemCount));
-  }
-
-  getItems() {
-    return this.data$.pipe(map(state => state.items));
-  }
-
-  hasItems() {
-    return this.data$.pipe(map(state => state.items.length > 0));
-  }
-
-  getDiscount() {
-    return this.data$.pipe(map(state => state.discount));
-  }
-
-  // Private helpers
-  private calculateTotals(state: CartState): CartState {
-    const subtotal = state.items.reduce((sum, item) => sum + (item.price * item.quantity), 0);
-    const discountAmount = (subtotal * state.discount) / 100;
-    const total = subtotal - discountAmount;
-    const itemCount = state.items.reduce((sum, item) => sum + item.quantity, 0);
-
-    return {
-      ...state,
-      total,
-      itemCount,
-      lastUpdated: new Date()
-    };
-  }
-
-  private calculateDiscount(promoCode: string, total: number): number {
-    const discounts: { [key: string]: number } = {
-      'SAVE10': 10,
-      'WELCOME20': 20,
-      'HOLIDAY15': 15
-    };
-    
-    return discounts[promoCode.toUpperCase()] || 0;
-  }
-}
-```
-
-### Multi-tenant Application State
-
-```typescript
-interface TenantInfo {
-  id: string;
-  name: string;
-  domain: string;
-  logo?: string;
-  theme: {
-    primary: string;
-    secondary: string;
-    accent: string;
-  };
-  features: string[];
-  settings: {
-    maxUsers: number;
-    storageLimit: number;
-    apiRateLimit: number;
-  };
-}
-
-interface UserInfo {
-  id: string;
-  tenantId: string;
-  email: string;
-  name: string;
-  role: 'admin' | 'user' | 'guest';
-  permissions: string[];
-  lastLogin: Date;
-}
-
-interface AppState {
-  tenant: TenantInfo | null;
-  user: UserInfo | null;
-  isAuthenticated: boolean;
-  preferences: {
-    sidebarCollapsed: boolean;
-    theme: 'light' | 'dark' | 'auto';
-    language: string;
-    notifications: {
-      email: boolean;
-      push: boolean;
-      sms: boolean;
-    };
-  };
-  ui: {
-    loading: boolean;
-    error: string | null;
-    breadcrumbs: Array<{ label: string; url: string }>;
-  };
-}
-
-@Injectable()
-export class AppStateService extends StoreStateManagerService<AppState> {
-
-  constructor() {
-    super(
-      StateStorageOptions.adapt({
-        store: 'app-state',
-        options: SettingOptions.adapt({
-          storage: StorageType.GLOBAL,
-          encrypted: true,  // Encrypt sensitive data
-          expiresIn: '24h'
-        }),
-        model: AppState.adapt,
-        version: 1  // For future migrations
-      })
-    );
-  }
-
-  // Authentication
-  login(user: UserInfo, tenant: TenantInfo) {
-    this.updateData({
-      user,
-      tenant,
-      isAuthenticated: true,
-      ui: {
-        ...this.getCurrentState().ui,
-        error: null
-      }
-    });
-  }
-
-  logout() {
-    this.updateData({
-      user: null,
-      tenant: null,
-      isAuthenticated: false,
-      preferences: {
-        ...this.getCurrentState().preferences,
-        // Keep user preferences but clear auth data
-      }
-    });
-  }
-
-  updateUser(user: Partial<UserInfo>) {
-    this.updateData(state => ({
-      ...state,
-      user: state.user ? { ...state.user, ...user } : null
-    }));
-  }
-
-  // Tenant management
-  switchTenant(tenant: TenantInfo) {
-    this.updateData(state => ({
-      ...state,
-      tenant,
-      user: state.user ? { ...state.user, tenantId: tenant.id } : null
-    }));
-  }
-
-  updateTenantSettings(settings: Partial<TenantInfo['settings']>) {
-    this.updateData(state => ({
-      ...state,
-      tenant: state.tenant ? {
-        ...state.tenant,
-        settings: { ...state.tenant.settings, ...settings }
-      } : null
-    }));
-  }
-
-  // Preferences
-  updatePreferences(preferences: Partial<AppState['preferences']>) {
-    this.updateData(state => ({
-      ...state,
-      preferences: { ...state.preferences, ...preferences }
-    }));
-  }
-
-  toggleSidebar() {
-    this.updateData(state => ({
-      ...state,
-      preferences: {
-        ...state.preferences,
-        sidebarCollapsed: !state.preferences.sidebarCollapsed
-      }
-    }));
-  }
-
-  setTheme(theme: 'light' | 'dark' | 'auto') {
-    this.updatePreferences({ theme });
-  }
-
-  setLanguage(language: string) {
-    this.updatePreferences({ language });
-  }
-
-  updateNotificationSettings(settings: Partial<AppState['preferences']['notifications']>) {
-    this.updateData(state => ({
-      ...state,
-      preferences: {
-        ...state.preferences,
-        notifications: {
-          ...state.preferences.notifications,
-          ...settings
-        }
-      }
-    }));
-  }
-
-  // UI State
-  setLoading(loading: boolean) {
-    this.updateData(state => ({
-      ...state,
-      ui: { ...state.ui, loading }
-    }));
-  }
-
-  setError(error: string | null) {
-    this.updateData(state => ({
-      ...state,
-      ui: { ...state.ui, error }
-    }));
-  }
-
-  clearError() {
-    this.setError(null);
-  }
-
-  setBreadcrumbs(breadcrumbs: Array<{ label: string; url: string }>) {
-    this.updateData(state => ({
-      ...state,
-      ui: { ...state.ui, breadcrumbs }
-    }));
-  }
-
-  // Computed selectors
-  isAdmin() {
-    return this.data$.pipe(map(state => state.user?.role === 'admin'));
-  }
-
-  isAuthenticated() {
-    return this.data$.pipe(map(state => state.isAuthenticated));
-  }
-
-  currentTenant() {
-    return this.data$.pipe(map(state => state.tenant));
-  }
-
-  currentUser() {
-    return this.data$.pipe(map(state => state.user));
-  }
-
-  hasPermission(permission: string) {
-    return this.data$.pipe(
-      map(state => state.user?.permissions.includes(permission) || false)
-    );
-  }
-
-  isFeatureEnabled(feature: string) {
-    return this.data$.pipe(
-      map(state => state.tenant?.features.includes(feature) || false)
-    );
-  }
-
-  // Data persistence
-  exportState() {
-    return this.exportData();
-  }
-
-  importState(state: Partial<AppState>) {
-    this.importData({ ...this.getCurrentState(), ...state });
-  }
-
-  // Migration support
-  migrateFromVersion1(state: any): AppState {
-    // Example migration logic
-    return {
-      ...state,
-      ui: {
-        ...state.ui,
-        breadcrumbs: state.ui?.breadcrumbs || []
-      }
-    };
-  }
-
-  // Private helper
-  private getCurrentState(): AppState {
-    let currentState: AppState | undefined;
-    this.data$.pipe(take(1)).subscribe(state => currentState = state);
-    return currentState!;
-  }
-}
-```
-
-### Game Progress Tracking
-
-```typescript
-interface GameLevel {
-  id: string;
-  name: string;
-  completed: boolean;
-  score: number;
-  stars: number; // 0-3 stars
-  timeSpent: number; // in seconds
-  completedAt?: Date;
-}
-
-interface GameProgress {
-  playerId: string;
-  totalScore: number;
-  currentLevel: string;
-  unlockedLevels: string[];
-  levels: GameLevel[];
-  achievements: string[];
-  settings: {
-    soundEnabled: boolean;
-    musicEnabled: boolean;
-    difficulty: 'easy' | 'normal' | 'hard';
-    showHints: boolean;
-  };
-  statistics: {
-    totalPlayTime: number;
-    levelsCompleted: number;
-    totalStars: number;
-    averageScore: number;
-    bestStreak: number;
-    currentStreak: number;
-  };
-}
-
-@Injectable()
-export class GameProgressStateService extends StoreStateManagerService<GameProgress> {
-
-  constructor() {
-    super(
-      StateStorageOptions.adapt({
-        store: `game-progress-${this.getPlayerId()}`,
-        options: SettingOptions.adapt({
-          storage: StorageType.GLOBAL,
-          encrypted: false,
-          expiresIn: '1y' // Keep progress for a year
-        }),
-        model: GameProgress.adapt
-      })
-    );
-  }
-
-  // Level management
-  completeLevel(levelId: string, score: number, timeSpent: number, stars: number) {
-    this.updateData(state => {
-      const levelIndex = state.levels.findIndex(l => l.id === levelId);
-      if (levelIndex === -1) return state;
-
-      const updatedLevels = [...state.levels];
-      const level = { ...updatedLevels[levelIndex] };
-      
-      if (!level.completed || score > level.score) {
-        level.completed = true;
-        level.score = score;
-        level.stars = Math.max(level.stars, stars);
-        level.timeSpent = timeSpent;
-        level.completedAt = new Date();
-        
-        updatedLevels[levelIndex] = level;
-
-        // Unlock next level
-        const nextLevelIndex = levelIndex + 1;
-        const unlockedLevels = [...state.unlockedLevels];
-        if (nextLevelIndex < state.levels.length) {
-          const nextLevel = state.levels[nextLevelIndex];
-          if (!unlockedLevels.includes(nextLevel.id)) {
-            unlockedLevels.push(nextLevel.id);
-          }
-        }
-
-        // Update statistics
-        const statistics = this.calculateStatistics({ ...state, levels: updatedLevels, unlockedLevels });
-
-        return {
-          ...state,
-          levels: updatedLevels,
-          unlockedLevels,
-          currentLevel: nextLevelIndex < state.levels.length ? state.levels[nextLevelIndex].id : state.currentLevel,
-          statistics
-        };
-      }
-
-      return state;
-    });
-  }
-
-  resetLevel(levelId: string) {
-    this.updateData(state => {
-      const levelIndex = state.levels.findIndex(l => l.id === levelId);
-      if (levelIndex === -1) return state;
-
-      const updatedLevels = [...state.levels];
-      updatedLevels[levelIndex] = {
-        ...updatedLevels[levelIndex],
-        completed: false,
-        score: 0,
-        stars: 0,
-        timeSpent: 0,
-        completedAt: undefined
-      };
-
-      return {
-        ...state,
-        levels: updatedLevels,
-        statistics: this.calculateStatistics({ ...state, levels: updatedLevels })
-      };
-    });
-  }
-
-  unlockLevel(levelId: string) {
-    this.updateData(state => {
-      if (!state.unlockedLevels.includes(levelId)) {
-        return {
-          ...state,
-          unlockedLevels: [...state.unlockedLevels, levelId]
-        };
-      }
-      return state;
-    });
-  }
-
-  // Achievement system
-  unlockAchievement(achievementId: string) {
-    this.updateData(state => {
-      if (!state.achievements.includes(achievementId)) {
-        return {
-          ...state,
-          achievements: [...state.achievements, achievementId]
-        };
-      }
-      return state;
-    });
-  }
-
-  // Settings
-  updateSettings(settings: Partial<GameProgress['settings']>) {
-    this.updateData(state => ({
-      ...state,
-      settings: { ...state.settings, ...settings }
-    }));
-  }
-
-  toggleSound() {
-    this.updateData(state => ({
-      ...state,
-      settings: {
-        ...state.settings,
-        soundEnabled: !state.settings.soundEnabled
-      }
-    }));
-  }
-
-  toggleMusic() {
-    this.updateData(state => ({
-      ...state,
-      settings: {
-        ...state.settings,
-        musicEnabled: !state.settings.musicEnabled
-      }
-    }));
-  }
-
-  setDifficulty(difficulty: 'easy' | 'normal' | 'hard') {
-    this.updateSettings({ difficulty });
-  }
-
-  // Progress queries
-  getCompletedLevels() {
-    return this.data$.pipe(
-      map(state => state.levels.filter(level => level.completed))
-    );
-  }
-
-  getLevelProgress(levelId: string) {
-    return this.data$.pipe(
-      map(state => state.levels.find(level => level.id === levelId))
-    );
-  }
-
-  isLevelUnlocked(levelId: string) {
-    return this.data$.pipe(
-      map(state => state.unlockedLevels.includes(levelId))
-    );
-  }
-
-  getTotalStars() {
-    return this.data$.pipe(
-      map(state => state.statistics.totalStars)
-    );
-  }
-
-  getCompletionPercentage() {
-    return this.data$.pipe(
-      map(state => {
-        const completedLevels = state.levels.filter(l => l.completed).length;
-        return (completedLevels / state.levels.length) * 100;
-      })
-    );
-  }
-
-  getNextLevel() {
-    return this.data$.pipe(
-      map(state => {
-        const currentLevelIndex = state.levels.findIndex(l => l.id === state.currentLevel);
-        return state.levels[currentLevelIndex + 1] || null;
-      })
-    );
-  }
-
-  // Statistics
-  private calculateStatistics(state: GameProgress): GameProgress['statistics'] {
-    const completedLevels = state.levels.filter(l => l.completed);
-    const totalPlayTime = state.statistics.totalPlayTime + 
-      completedLevels.reduce((sum, level) => sum + level.timeSpent, 0);
-    const totalStars = completedLevels.reduce((sum, level) => sum + level.stars, 0);
-    const averageScore = completedLevels.length > 0 
-      ? completedLevels.reduce((sum, level) => sum + level.score, 0) / completedLevels.length
-      : 0;
-
-    // Calculate streak (consecutive levels completed)
-    let currentStreak = 0;
-    for (let i = 0; i < state.levels.length; i++) {
-      if (state.levels[i].completed) {
-        currentStreak++;
-      } else {
-        break;
-      }
-    }
-
-    return {
-      ...state.statistics,
-      totalPlayTime,
-      levelsCompleted: completedLevels.length,
-      totalStars,
-      averageScore,
-      bestStreak: Math.max(state.statistics.bestStreak, currentStreak),
-      currentStreak
-    };
-  }
-
-  // Data management
-  exportProgress() {
-    return this.exportData();
-  }
-
-  importProgress(progressData: GameProgress) {
-    this.importData(progressData);
-  }
-
-  resetAllProgress() {
-    this.updateData({
-      playerId: this.getPlayerId(),
-      totalScore: 0,
-      currentLevel: 'level-1',
-      unlockedLevels: ['level-1'],
-      levels: this.initializeLevels(),
-      achievements: [],
-      settings: {
-        soundEnabled: true,
-        musicEnabled: true,
-        difficulty: 'normal',
-        showHints: true
-      },
-      statistics: {
-        totalPlayTime: 0,
-        levelsCompleted: 0,
-        totalStars: 0,
-        averageScore: 0,
-        bestStreak: 0,
-        currentStreak: 0
-      }
-    });
-  }
-
-  private getPlayerId(): string {
-    // Generate or retrieve player ID
-    let playerId = localStorage.getItem('playerId');
-    if (!playerId) {
-      playerId = 'player-' + Date.now();
-      localStorage.setItem('playerId', playerId);
-    }
-    return playerId;
-  }
-
-  private initializeLevels(): GameLevel[] {
-    // Initialize game levels - this would come from your game data
-    return [
-      { id: 'level-1', name: 'Tutorial', completed: false, score: 0, stars: 0, timeSpent: 0 },
-      { id: 'level-2', name: 'Getting Started', completed: false, score: 0, stars: 0, timeSpent: 0 },
-      { id: 'level-3', name: 'First Challenge', completed: false, score: 0, stars: 0, timeSpent: 0 },
-      // ... more levels
-    ];
-  }
-}
-```
-
-## State Migration
-
-### Version Management
-
-```typescript
-@Injectable()
-export class MigratableStateService extends StoreStateManagerService<any> {
-
-  constructor() {
-    super(
-      StateStorageOptions.adapt({
-        store: 'migratable-state',
-        options: SettingOptions.adapt({
-          storage: StorageType.GLOBAL,
-          encrypted: false
-        }),
-        version: 2  // Current version
-      })
-    );
-  }
-
-  // Handle migrations
-  protected override handleMigration(storedData: any, currentVersion: number): any {
-    let migratedData = storedData;
-    let version = currentVersion;
-
-    // Migrate from version 1 to 2
-    if (version < 2) {
-      migratedData = this.migrateFromV1ToV2(migratedData);
-      version = 2;
-    }
-
-    // Future migrations would go here
-    // if (version < 3) {
-    //   migratedData = this.migrateFromV2ToV3(migratedData);
-    //   version = 3;
-    // }
-
-    return { data: migratedData, version };
-  }
-
-  private migrateFromV1ToV2(data: any): any {
-    // Example migration: add new field with default value
-    return {
-      ...data,
-      newField: data.newField || 'default-value',
-      migratedAt: new Date()
-    };
-  }
-}
-```
-
-## Best Practices
-
-### 1. Model Validation
-
-```typescript
-// ✅ Good - Use model adapters for validation
-@Injectable()
-export class ValidatedStateService extends StoreStateManagerService<UserSettings> {
-
-  constructor() {
-    super(
-      StateStorageOptions.adapt({
-        store: 'validated-settings',
-        model: UserSettings.adapt  // Validates and normalizes data
-      })
-    );
-  }
-}
-
-// ❌ Avoid - No model validation
-super(
-  StateStorageOptions.adapt({
-    store: 'settings',
-    // No model validation
-  })
-);
-```
-
-### 2. Appropriate Storage Types
-
-```typescript
-// ✅ Good - Choose appropriate storage
-// Session-specific data
-super(StateStorageOptions.adapt({
-  store: 'temp-calculation',
-  options: SettingOptions.adapt({
-    storage: StorageType.SESSION  // Cleared on browser close
-  })
-}));
-
-// Persistent user preferences
-super(StateStorageOptions.adapt({
-  store: 'user-preferences',
-  options: SettingOptions.adapt({
-    storage: StorageType.GLOBAL   // Persists across sessions
-  })
-}));
-```
-
-### 3. Error Handling
-
-```typescript
-// ✅ Good - Handle storage errors gracefully
-updateData(updater: ((state: T) => T) | T): void {
-  try {
-    super.updateData(updater);
-  } catch (error) {
-    console.error('Failed to update state:', error);
-    // Optionally show user notification
-    this.showErrorNotification('Failed to save changes');
-  }
-}
-```
-
-### 4. State Size Management
-
-```typescript
-// ✅ Good - Keep state size reasonable
-@Injectable()
-export class OptimizedStateService extends StoreStateManagerService<AppState> {
-
-  updateData(updater: ((state: T) => T) | T): void {
-    super.updateData(state => {
-      const newState = typeof updater === 'function' ? updater(state) : updater;
-      
-      // Prune old data if state becomes too large
-      if (this.getStateSize(newState) > MAX_STATE_SIZE) {
-        return this.pruneState(newState);
-      }
-      
-      return newState;
-    });
-  }
-
-  private getStateSize(state: any): number {
-    return JSON.stringify(state).length;
-  }
-
-  private pruneState(state: any): any {
-    // Remove old log entries, cache data, etc.
-    return {
-      ...state,
-      logs: state.logs?.slice(-100), // Keep only recent logs
-      cache: undefined // Clear cache
-    };
-  }
-}
-```
-
-## Performance Optimization
-
-### Selective Persistence
-
-```typescript
-@Injectable()
-export class SelectivePersistenceService extends StoreStateManagerService<any> {
-
-  // Only persist specific parts of state
-  protected override shouldPersist(key: string, value: any): boolean {
-    // Don't persist large objects or temporary data
-    if (key === 'tempData' || key === 'largeCache') {
-      return false;
-    }
-    
-    // Don't persist computed values
-    if (key.startsWith('computed') || key.startsWith('derived')) {
-      return false;
-    }
-    
-    return true;
-  }
-
-  // Custom persistence logic
-  protected override persistState(state: any): void {
-    const persistentState = this.filterPersistentData(state);
-    super.persistState(persistentState);
-  }
-
-  private filterPersistentData(state: any): any {
-    const { tempData, largeCache, computedValues, ...persistentState } = state;
-    return persistentState;
-  }
-}
-```
-
-### Debounced Updates
-
-```typescript
-@Injectable()
-export class DebouncedStateService extends StoreStateManagerService<any> {
-
-  private updateTimeout?: any;
-
-  updateData(updater: ((state: T) => T) | T): void {
-    // Clear previous timeout
-    if (this.updateTimeout) {
-      clearTimeout(this.updateTimeout);
-    }
-
-    // Debounce updates to avoid excessive storage writes
-    this.updateTimeout = setTimeout(() => {
-      super.updateData(updater);
-    }, 500); // 500ms debounce
-  }
-}
-```
-
-## Troubleshooting
-
-### Common Issues
-
-#### 1. Storage Quota Exceeded
-```typescript
-// Monitor storage usage
-@Injectable()
-export class StorageMonitoringService extends StoreStateManagerService<any> {
-
-  updateData(updater: ((state: T) => T) | T): void {
-    try {
-      super.updateData(updater);
-    } catch (error) {
-      if (error.name === 'QuotaExceededError') {
-        this.handleQuotaExceeded();
-      } else {
-        throw error;
-      }
-    }
-  }
-
-  private handleQuotaExceeded() {
-    // Clean up old data
-    this.cleanupOldData();
-    
-    // Retry the update
-    super.updateData(this.pendingUpdate);
-  }
-
-  private cleanupOldData() {
-    // Remove old state versions, logs, etc.
-    const oldKeys = Object.keys(localStorage).filter(key => 
-      key.startsWith('app-state-') && key !== this.storeName
-    );
-    oldKeys.forEach(key => localStorage.removeItem(key));
-  }
-}
-```
-
-#### 2. Corrupted State Data
-```typescript
-// Handle corrupted data gracefully
-protected override handleMigration(storedData: any, currentVersion: number): any {
-  try {
-    return super.handleMigration(storedData, currentVersion);
-  } catch (error) {
-    console.warn('Corrupted state data detected, resetting to defaults');
-    
-    // Reset to default state
-    return {
-      data: this.getDefaultState(),
-      version: currentVersion
-    };
-  }
-}
-```
-
-#### 3. Encryption Issues
-```typescript
-// Ensure APP_ID is provided for encryption
-@NgModule({
-  providers: [
-    { provide: APP_ID, useValue: "your-unique-guid-here" }
-  ]
-})
-export class AppModule { }
-
-// Handle encryption errors
-protected override encryptData(data: any): string {
-  try {
-    return super.encryptData(data);
-  } catch (error) {
-    console.warn('Encryption failed, storing without encryption');
-    return JSON.stringify(data);
-  }
-}
-```
-
-## Related Documentation
-
-- [ComponentStore Documentation](https://ngrx.io/guide/component-store)
-- [Local Storage Service](local-storage/README.md)
-- [HTTP State Service](http-state/README.md)
-- [Architecture Overview](../architecture/README.md)