http-request-manager 18.15.32 → 18.15.34

package/src/docs/LOCAL_STORAGE_README.md

@@ -0,0 +1,1056 @@
+# Local Storage Manager Service
+
+The `LocalStorageManagerService` manages `localStorage` and `sessionStorage` with encryption, expiration, and reactive features for secure and intelligent data persistence.
+
+## Overview
+
+This service provides:
+
+- **Secure Storage** - AES encryption support for sensitive data
+- **Expiration Management** - Automatic cleanup of expired items
+- **Storage Types** - Both localStorage (Global) and sessionStorage (Session)
+- **Reactive Updates** - Observable-based storage state management
+- **Metadata Tracking** - Separate storage of settings and data
+- **Type Safety** - Full TypeScript support with generics
+
+## Installation
+
+```typescript
+import { HttpRequestManagerModule } from 'http-request-manager';
+
+@NgModule({
+  imports: [HttpRequestManagerModule.forRoot({
+    LocalStorageOptions: {
+      storageName: 'my-app-data',
+      storageSettingsName: 'my-app-settings',
+      options: {
+        encrypted: true,
+        expiresIn: '7d'
+      }
+    }
+  })]
+})
+export class AppModule { }
+```
+
+## Basic Usage
+
+### Service Injection
+
+```typescript
+import { Component, inject } from '@angular/core';
+import { LocalStorageManagerService, SettingOptions } from 'http-request-manager';
+
+@Component({
+  selector: 'app-settings',
+  template: `
+    <div class="settings">
+      <h2>User Preferences</h2>
+      
+      <div class="setting-item">
+        <label>Theme:</label>
+        <select [value]="theme()" (change)="setTheme($any($event.target).value)">
+          <option value="light">Light</option>
+          <option value="dark">Dark</option>
+        </select>
+      </div>
+      
+      <div class="setting-item">
+        <label>Language:</label>
+        <select [value]="language()" (change)="setLanguage($any($event.target).value)">
+          <option value="en">English</option>
+          <option value="es">Spanish</option>
+        </select>
+      </div>
+      
+      <div class="setting-item">
+        <label>
+          <input type="checkbox" [checked]="notifications()" 
+                 (change)="setNotifications($any($event.target).checked)">
+          Enable Notifications
+        </label>
+      </div>
+      
+      <div class="actions">
+        <button (click)="clearSettings()">Clear All Settings</button>
+        <button (click)="exportSettings()">Export Settings</button>
+      </div>
+      
+      <div class="storage-info">
+        <p>Settings last updated: {{ lastUpdated() }}</p>
+        <p>Storage size: {{ storageSize() }} bytes</p>
+      </div>
+    </div>
+  `
+})
+export class SettingsComponent {
+  private storage = inject(LocalStorageManagerService);
+
+  // Reactive signals
+  theme = this.storage.signal('theme', 'light');
+  language = this.storage.signal('language', 'en');
+  notifications = this.storage.signal('notifications', true);
+  lastUpdated = this.storage.signal('lastUpdated', new Date().toISOString());
+
+  // Computed
+  storageSize = computed(() => {
+    const data = this.storage.getItem('user-preferences');
+    return data ? JSON.stringify(data).length : 0;
+  });
+
+  setTheme(theme: string) {
+    this.theme.set(theme);
+    this.updateLastUpdated();
+  }
+
+  setLanguage(language: string) {
+    this.language.set(language);
+    this.updateLastUpdated();
+  }
+
+  setNotifications(enabled: boolean) {
+    this.notifications.set(enabled);
+    this.updateLastUpdated();
+  }
+
+  private updateLastUpdated() {
+    this.lastUpdated.set(new Date().toISOString());
+  }
+
+  clearSettings() {
+    this.storage.removeItem('user-preferences');
+    // Reset to defaults
+    this.theme.set('light');
+    this.language.set('en');
+    this.notifications.set(true);
+    this.lastUpdated.set(new Date().toISOString());
+  }
+
+  exportSettings() {
+    const settings = this.storage.getItem('user-preferences');
+    console.log('Settings:', settings);
+  }
+}
+```
+
+## API Reference
+
+### Store Management
+
+#### setStore(options: StoreOptions): void
+
+Create or update a storage store:
+
+```typescript
+this.storage.setStore({
+  name: 'user-preferences',
+  data: {
+    theme: 'dark',
+    language: 'en',
+    notifications: true
+  },
+  options: SettingOptions.adapt({
+    storage: StorageType.GLOBAL,
+    encrypted: true,
+    expiresIn: '30d'
+  })
+});
+```
+
+#### store$(name: string): Observable<any>
+
+Get an observable of store data:
+
+```typescript
+settings$ = this.storage.store$('user-preferences');
+
+<div *ngIf="settings$ | async as settings">
+  Theme: {{ settings.theme }}
+</div>
+```
+
+#### setting$(name: string): Observable<any>
+
+Get an observable of store metadata:
+
+```typescript
+metadata$ = this.storage.setting$('user-preferences');
+
+<div *ngIf="metadata$ | async as meta">
+  Encrypted: {{ meta.encrypted }}
+  Expires: {{ meta.expires }}
+</div>
+```
+
+#### resetStore(): void
+
+Clear all stores:
+
+```typescript
+this.storage.resetStore();
+```
+
+### Item Management
+
+#### setItem(key: string, value: any, options?: SettingOptions): void
+
+Store a value with optional settings:
+
+```typescript
+// Simple storage
+this.storage.setItem('user-name', 'John Doe');
+
+// Encrypted storage
+this.storage.setItem('user-token', 'secret-token', 
+  SettingOptions.adapt({
+    encrypted: true,
+    expiresIn: '1h'
+  })
+);
+
+// Session storage
+this.storage.setItem('temp-data', { temporary: true },
+  SettingOptions.adapt({
+    storage: StorageType.SESSION
+  })
+);
+```
+
+#### getItem(key: string): any
+
+Retrieve a stored value:
+
+```typescript
+const userName = this.storage.getItem('user-name');
+const encryptedToken = this.storage.getItem('user-token'); // Auto-decrypted
+```
+
+#### removeItem(key: string): void
+
+Remove a stored item:
+
+```typescript
+this.storage.removeItem('user-token');
+```
+
+#### hasItem(key: string): boolean
+
+Check if item exists:
+
+```typescript
+if (this.storage.hasItem('user-token')) {
+  console.log('Token exists');
+}
+```
+
+### Signal-Based API
+
+#### signal(key: string, defaultValue: any, options?: SettingOptions): Signal<any>
+
+Create a reactive signal for storage:
+
+```typescript
+// Create signals
+const theme = this.storage.signal('theme', 'light');
+const userData = this.storage.signal('user-data', {}, {
+  encrypted: true,
+  expiresIn: '24h'
+});
+
+// Use in template
+<div [style.color]="theme() === 'dark' ? 'white' : 'black'">
+  {{ theme() }}
+</div>
+```
+
+#### computedSignal(key: string, computeFn: Function): Signal<any>
+
+Create computed signal from storage:
+
+```typescript
+const userName = this.storage.signal('user-name', '');
+const userEmail = this.storage.signal('user-email', '');
+
+// Computed full name
+const fullUser = this.storage.computedSignal('full-user', 
+  () => `${userName()} <${userEmail()}>`
+);
+```
+
+### Data Management
+
+#### getAllItems(): any[]
+
+Get all stored items:
+
+```typescript
+const allItems = this.storage.getAllItems();
+console.log('Stored items:', allItems);
+```
+
+#### getExpiredItems(): any[]
+
+Get items that have expired:
+
+```typescript
+const expired = this.storage.getExpiredItems();
+console.log('Expired items:', expired);
+```
+
+#### clearExpiredItems(): void
+
+Remove all expired items:
+
+```typescript
+this.storage.clearExpiredItems();
+```
+
+#### exportData(): string
+
+Export all data as JSON string:
+
+```typescript
+const exportedData = this.storage.exportData();
+console.log('Exported data:', exportedData);
+```
+
+#### importData(data: string): void
+
+Import data from JSON string:
+
+```typescript
+const dataString = '{"theme":"dark","language":"en"}';
+this.storage.importData(dataString);
+```
+
+## Configuration Options
+
+### SettingOptions
+
+```typescript
+interface SettingOptions {
+  storage: StorageType;        // GLOBAL or SESSION
+  expires?: number;            // Epoch timestamp
+  expiresIn?: string;          // Duration string (e.g., '1d', '2h')
+  encrypted?: boolean;         // Enable encryption
+}
+```
+
+### StorageType Enum
+
+```typescript
+enum StorageType {
+  GLOBAL = 'global',     // localStorage
+  SESSION = 'session'    // sessionStorage
+}
+```
+
+### Duration Format
+
+Supported duration formats:
+- `30s` - 30 seconds
+- `15m` - 15 minutes
+- `2h` - 2 hours
+- `1d` - 1 day
+- `1w` - 1 week
+- `1mo` - 1 month
+- `1y` - 1 year
+
+## Advanced Examples
+
+### User Session Management
+
+```typescript
+import { Injectable, signal, computed } from '@angular/core';
+import { LocalStorageManagerService, SettingOptions } from 'http-request-manager';
+
+@Injectable({
+  providedIn: 'root'
+})
+export class UserSessionService {
+  private storage = inject(LocalStorageManagerService);
+
+  // Session signals
+  isLoggedIn = this.storage.signal('is-logged-in', false);
+  userId = this.storage.signal('user-id', null);
+  userName = this.storage.signal('user-name', '');
+  userRole = this.storage.signal('user-role', 'guest');
+  sessionToken = this.storage.signal('session-token', '', {
+    encrypted: true,
+    expiresIn: '24h'
+  });
+  lastActivity = this.storage.signal('last-activity', Date.now());
+
+  // Computed signals
+  isAdmin = computed(() => this.userRole() === 'admin');
+  isGuest = computed(() => this.userRole() === 'guest');
+  sessionExpired = computed(() => {
+    const lastActivity = this.lastActivity();
+    const now = Date.now();
+    return (now - lastActivity) > (30 * 60 * 1000); // 30 minutes
+  });
+
+  // Session management
+  login(user: any, token: string) {
+    this.isLoggedIn.set(true);
+    this.userId.set(user.id);
+    this.userName.set(user.name);
+    this.userRole.set(user.role || 'user');
+    this.sessionToken.set(token);
+    this.updateLastActivity();
+  }
+
+  logout() {
+    this.isLoggedIn.set(false);
+    this.userId.set(null);
+    this.userName.set('');
+    this.userRole.set('guest');
+    this.sessionToken.set('');
+    this.lastActivity.set(Date.now());
+    
+    // Clear sensitive data
+    this.storage.removeItem('session-token');
+  }
+
+  updateActivity() {
+    this.lastActivity.set(Date.now());
+  }
+
+  private updateLastUpdated() {
+    this.lastActivity.set(Date.now());
+  }
+
+  // Auto-logout on inactivity
+  constructor() {
+    // Monitor user activity
+    ['click', 'keypress', 'scroll'].forEach(event => {
+      document.addEventListener(event, () => {
+        if (this.isLoggedIn()) {
+          this.updateActivity();
+        }
+      });
+    });
+
+    // Check for session expiry every minute
+    setInterval(() => {
+      if (this.sessionExpired() && this.isLoggedIn()) {
+        console.log('Session expired, logging out');
+        this.logout();
+        // Redirect to login page
+        window.location.href = '/login';
+      }
+    }, 60000);
+  }
+}
+```
+
+### Application State Persistence
+
+```typescript
+@Injectable()
+export class AppStateService {
+  private storage = inject(LocalStorageManagerService);
+
+  // UI State
+  sidebarCollapsed = this.storage.signal('sidebar-collapsed', false);
+  theme = this.storage.signal('theme', 'light');
+  language = this.storage.signal('language', 'en');
+  
+  // User Preferences
+  notificationsEnabled = this.storage.signal('notifications', true);
+  emailDigestEnabled = this.storage.signal('email-digest', false);
+  
+  // Feature Flags
+  experimentalFeatures = this.storage.signal('experimental-features', []);
+  betaFeatures = this.storage.signal('beta-features', false);
+  
+  // Navigation State
+  currentPage = this.storage.signal('current-page', 'dashboard');
+  breadcrumbs = this.storage.signal('breadcrumbs', []);
+  
+  // Data Persistence
+  cachedData = this.storage.signal('cached-data', {}, {
+    expiresIn: '1h'
+  });
+  userCache = this.storage.signal('user-cache', {}, {
+    encrypted: true,
+    expiresIn: '30m'
+  });
+
+  // Computed states
+  isDarkTheme = computed(() => this.theme() === 'dark');
+  isExperimentalMode = computed(() => this.experimentalFeatures().includes('new-ui'));
+  hasUnreadNotifications = computed(() => this.notificationsEnabled());
+
+  // State management methods
+  toggleSidebar() {
+    this.sidebarCollapsed.set(!this.sidebarCollapsed());
+  }
+
+  switchTheme(theme: 'light' | 'dark') {
+    this.theme.set(theme);
+    // Apply theme to document
+    document.documentElement.setAttribute('data-theme', theme);
+  }
+
+  setLanguage(language: string) {
+    this.language.set(language);
+    // Update document language
+    document.documentElement.setAttribute('lang', language);
+  }
+
+  enableFeature(feature: string) {
+    const features = this.experimentalFeatures();
+    if (!features.includes(feature)) {
+      this.experimentalFeatures.set([...features, feature]);
+    }
+  }
+
+  disableFeature(feature: string) {
+    const features = this.experimentalFeatures();
+    this.experimentalFeatures.set(features.filter(f => f !== feature));
+  }
+
+  cacheData(key: string, data: any) {
+    const currentCache = this.cachedData();
+    currentCache[key] = {
+      data,
+      timestamp: Date.now()
+    };
+    this.cachedData.set({ ...currentCache });
+  }
+
+  getCachedData(key: string) {
+    const cache = this.cachedData();
+    const cached = cache[key];
+    
+    if (cached && !this.isExpired(cached.timestamp)) {
+      return cached.data;
+    }
+    
+    return null;
+  }
+
+  private isExpired(timestamp: number): boolean {
+    const now = Date.now();
+    const oneHour = 60 * 60 * 1000;
+    return (now - timestamp) > oneHour;
+  }
+
+  // Export/Import state
+  exportAppState() {
+    return {
+      theme: this.theme(),
+      language: this.language(),
+      sidebarCollapsed: this.sidebarCollapsed(),
+      notifications: this.notificationsEnabled(),
+      experimentalFeatures: this.experimentalFeatures()
+    };
+  }
+
+  importAppState(state: any) {
+    if (state.theme) this.theme.set(state.theme);
+    if (state.language) this.language.set(state.language);
+    if (typeof state.sidebarCollapsed === 'boolean') {
+      this.sidebarCollapsed.set(state.sidebarCollapsed);
+    }
+    if (typeof state.notifications === 'boolean') {
+      this.notificationsEnabled.set(state.notifications);
+    }
+    if (Array.isArray(state.experimentalFeatures)) {
+      this.experimentalFeatures.set(state.experimentalFeatures);
+    }
+  }
+}
+```
+
+### Shopping Cart with Persistence
+
+```typescript
+@Injectable()
+export class ShoppingCartService {
+  private storage = inject(LocalStorageManagerService);
+
+  private cartItems = this.storage.signal('shopping-cart', []);
+  private cartTotal = computed(() => 
+    this.cartItems().reduce((total, item) => total + (item.price * item.quantity), 0)
+  );
+  private itemCount = computed(() => 
+    this.cartItems().reduce((count, item) => count + item.quantity, 0)
+  );
+
+  // Cart management
+  addItem(item: any) {
+    const items = this.cartItems();
+    const existingItem = items.find(i => i.id === item.id);
+    
+    if (existingItem) {
+      existingItem.quantity += 1;
+      this.cartItems.set([...items]);
+    } else {
+      this.cartItems.set([...items, { ...item, quantity: 1 }]);
+    }
+  }
+
+  removeItem(itemId: string) {
+    const items = this.cartItems().filter(item => item.id !== itemId);
+    this.cartItems.set(items);
+  }
+
+  updateQuantity(itemId: string, quantity: number) {
+    if (quantity <= 0) {
+      this.removeItem(itemId);
+      return;
+    }
+
+    const items = this.cartItems();
+    const item = items.find(i => i.id === itemId);
+    if (item) {
+      item.quantity = quantity;
+      this.cartItems.set([...items]);
+    }
+  }
+
+  clearCart() {
+    this.cartItems.set([]);
+  }
+
+  // Computed getters
+  get items() { return this.cartItems(); }
+  get total() { return this.cartTotal(); }
+  get count() { return this.itemCount(); }
+
+  // Cart persistence
+  saveCart() {
+    // Auto-saved by signals, but this forces a save
+    this.cartItems.set(this.cartItems());
+  }
+
+  loadCart() {
+    // Cart is automatically loaded from storage
+    const savedCart = this.storage.getItem('shopping-cart');
+    if (savedCart) {
+      this.cartItems.set(savedCart);
+    }
+  }
+
+  // Cart sharing/export
+  exportCart() {
+    return {
+      items: this.cartItems(),
+      total: this.cartTotal(),
+      exportedAt: Date.now()
+    };
+  }
+
+  importCart(cartData: any) {
+    if (cartData.items && Array.isArray(cartData.items)) {
+      this.cartItems.set(cartData.items);
+    }
+  }
+}
+```
+
+## Encryption Support
+
+### Setup Encryption
+
+To use encryption, provide an `APP_ID` in your module:
+
+```typescript
+import { APP_ID } from '@angular/core';
+
+@NgModule({
+  providers: [
+    { provide: APP_ID, useValue: "your-unique-guid-here" }
+  ]
+})
+export class AppModule { }
+```
+
+### Encrypted Storage Example
+
+```typescript
+@Component({
+  selector: 'secure-data'
+})
+export class SecureDataComponent {
+  private storage = inject(LocalStorageManagerService);
+
+  // Sensitive data (automatically encrypted/decrypted)
+  apiKey = this.storage.signal('api-key', '', {
+    encrypted: true,
+    expiresIn: '24h'
+  });
+
+  userCredentials = this.storage.signal('user-credentials', {}, {
+    encrypted: true,
+    expiresIn: '8h'
+  });
+
+  // Non-sensitive data
+  userName = this.storage.signal('username', '');
+
+  saveApiKey(key: string) {
+    this.apiKey.set(key);
+    // Key is automatically encrypted before storing
+  }
+
+  getApiKey() {
+    const key = this.apiKey();
+    // Key is automatically decrypted when retrieved
+    return key;
+  }
+
+  saveCredentials(username: string, password: string) {
+    this.userCredentials.set({
+      username,
+      password: btoa(password) // Additional base64 encoding
+    });
+  }
+
+  getCredentials() {
+    return this.userCredentials();
+  }
+}
+```
+
+## Security Best Practices
+
+### 1. Sensitive Data Handling
+
+```typescript
+// ✅ Good - Use encryption for sensitive data
+this.storage.setItem('user-token', token, {
+  encrypted: true,
+  expiresIn: '1h'
+});
+
+// ❌ Avoid - Store sensitive data without encryption
+this.storage.setItem('user-password', password);
+```
+
+### 2. Expiration Management
+
+```typescript
+// ✅ Good - Set reasonable expiration times
+this.storage.setItem('session-data', data, {
+  expiresIn: '24h' // Expire session data daily
+});
+
+// ❌ Avoid - No expiration for sensitive data
+this.storage.setItem('api-key', key); // Should expire
+```
+
+### 3. Storage Type Selection
+
+```typescript
+// ✅ Good - Use appropriate storage types
+// Session data (cleared when browser closes)
+this.storage.setItem('temp-calculation', result, {
+  storage: StorageType.SESSION
+});
+
+// Persistent data (survives browser restarts)
+this.storage.setItem('user-preferences', prefs, {
+  storage: StorageType.GLOBAL
+});
+```
+
+## Performance Optimization
+
+### Storage Size Monitoring
+
+```typescript
+@Injectable()
+export class StorageMonitorService {
+  private storage = inject(LocalStorageManagerService);
+
+  getStorageSize() {
+    let total = 0;
+    for (let key in localStorage) {
+      if (localStorage.hasOwnProperty(key)) {
+        total += localStorage[key].length + key.length;
+      }
+    }
+    return total;
+  }
+
+  getStorageUsagePercentage() {
+    const used = this.getStorageSize();
+    const quota = 5 * 1024 * 1024; // 5MB typical limit
+    return (used / quota) * 100;
+  }
+
+  optimizeStorage() {
+    // Remove expired items
+    this.storage.clearExpiredItems();
+    
+    // Remove old cache data
+    const cache = this.storage.getItem('cache');
+    if (cache) {
+      const cleaned = this.cleanOldCacheData(cache);
+      this.storage.setItem('cache', cleaned);
+    }
+  }
+
+  private cleanOldCacheData(cache: any) {
+    const oneDayAgo = Date.now() - (24 * 60 * 60 * 1000);
+    return Object.keys(cache)
+      .filter(key => cache[key].timestamp > oneDayAgo)
+      .reduce((obj, key) => {
+        obj[key] = cache[key];
+        return obj;
+      }, {});
+  }
+}
+```
+
+### Batch Operations
+
+```typescript
+@Injectable()
+export class BatchStorageService {
+  private storage = inject(LocalStorageManagerService);
+
+  batchSetItems(items: Array<{key: string, value: any, options?: any}>) {
+    items.forEach(item => {
+      this.storage.setItem(item.key, item.value, item.options);
+    });
+  }
+
+  batchGetItems(keys: string[]) {
+    const result: any = {};
+    keys.forEach(key => {
+      result[key] = this.storage.getItem(key);
+    });
+    return result;
+  }
+
+  batchRemoveItems(keys: string[]) {
+    keys.forEach(key => {
+      this.storage.removeItem(key);
+    });
+  }
+}
+```
+
+## Error Handling
+
+### Storage Error Handling
+
+```typescript
+@Component({
+  selector: 'safe-storage'
+})
+export class SafeStorageComponent {
+  private storage = inject(LocalStorageManagerService);
+
+  safeSetItem(key: string, value: any, options?: any) {
+    try {
+      this.storage.setItem(key, value, options);
+      return { success: true };
+    } catch (error) {
+      console.error('Storage error:', error);
+      
+      // Try to free up space
+      this.cleanupOldData();
+      
+      // Retry once
+      try {
+        this.storage.setItem(key, value, options);
+        return { success: true, warning: 'Cleaned up old data' };
+      } catch (retryError) {
+        console.error('Storage still failing:', retryError);
+        return { success: false, error: 'Storage quota exceeded' };
+      }
+    }
+  }
+
+  private cleanupOldData() {
+    // Remove expired items
+    this.storage.clearExpiredItems();
+    
+    // Remove oldest cache entries
+    const cache = this.storage.getItem('cache');
+    if (cache && Array.isArray(cache)) {
+      // Keep only the 10 most recent entries
+      const recent = cache.slice(-10);
+      this.storage.setItem('cache', recent);
+    }
+  }
+}
+```
+
+## Integration with Other Services
+
+### With HTTP State Service
+
+```typescript
+@Injectable()
+export class UserStateService extends HTTPManagerStateService<User> {
+  private storage = inject(LocalStorageManagerService);
+
+  constructor() {
+    super(
+      ApiRequest.adapt({
+        path: ['users'],
+        adapter: User.adapt
+      }),
+      DataType.ARRAY,
+      DatabaseStorage.adapt({
+        table: 'users-cache',
+        expiresIn: '1h'
+      })
+    );
+  }
+
+  // Cache user preferences locally
+  saveUserPreferences(userId: string, preferences: any) {
+    this.storage.setItem(`user-prefs-${userId}`, preferences, {
+      encrypted: true,
+      expiresIn: '30d'
+    });
+  }
+
+  getUserPreferences(userId: string) {
+    return this.storage.getItem(`user-prefs-${userId}`);
+  }
+}
+```
+
+### With WebSocket
+
+```typescript
+@Injectable()
+export class ChatStateService extends HTTPManagerStateService<Message> {
+  private storage = inject(LocalStorageManagerService);
+
+  constructor() {
+    super(
+      ApiRequest.adapt({
+        path: ['messages'],
+        ws: {
+          id: 'CHAT_STORAGE',
+          wsServer: 'ws://localhost:8080'
+        }
+      }),
+      DataType.ARRAY
+    );
+  }
+
+  // Save chat history locally
+  saveChatHistory(channel: string, messages: Message[]) {
+    this.storage.setItem(`chat-history-${channel}`, messages, {
+      expiresIn: '7d'
+    });
+  }
+
+  getChatHistory(channel: string): Message[] {
+    return this.storage.getItem(`chat-history-${channel}`) || [];
+  }
+}
+```
+
+## Best Practices
+
+### 1. Signal-Based Usage
+
+```typescript
+// ✅ Good - Use signals for reactive updates
+const theme = this.storage.signal('theme', 'light');
+
+// ❌ Avoid - Manual storage management
+getTheme() {
+  return localStorage.getItem('theme') || 'light';
+}
+```
+
+### 2. Consistent Key Naming
+
+```typescript
+// ✅ Good - Consistent naming convention
+this.storage.setItem('user-profile', data);
+this.storage.setItem('user-preferences', prefs);
+this.storage.setItem('user-session', session);
+
+// ❌ Avoid - Inconsistent naming
+this.storage.setItem('profile', data);
+this.storage.setItem('userSettings', prefs);
+this.storage.setItem('sessionInfo', session);
+```
+
+### 3. Appropriate Expiration
+
+```typescript
+// ✅ Good - Set reasonable expiration
+this.storage.setItem('temp-calculation', result, {
+  expiresIn: '1h' // Clear temporary data
+});
+
+this.storage.setItem('user-preferences', prefs, {
+  expiresIn: '30d' // Keep preferences for a month
+});
+
+// ❌ Avoid - No expiration for temporary data
+this.storage.setItem('temp-data', data); // Should have expiration
+```
+
+### 4. Data Validation
+
+```typescript
+// ✅ Good - Validate before storage
+saveUserSettings(settings: any) {
+  if (this.validateSettings(settings)) {
+    this.storage.setItem('user-settings', settings);
+  } else {
+    throw new Error('Invalid settings format');
+  }
+}
+```
+
+## Troubleshooting
+
+### Common Issues
+
+#### 1. Storage Quota Exceeded
+```typescript
+// Monitor storage usage
+const monitor = inject(StorageMonitorService);
+console.log('Storage usage:', monitor.getStorageUsagePercentage(), '%');
+
+// Clean up when approaching limit
+if (monitor.getStorageUsagePercentage() > 80) {
+  monitor.optimizeStorage();
+}
+```
+
+#### 2. Encryption Not Working
+```typescript
+// Ensure APP_ID is provided
+// Check that encrypted items are retrieved properly
+const encryptedData = this.storage.getItem('secure-data');
+console.log('Data decrypted successfully:', encryptedData);
+```
+
+#### 3. Data Not Persisting
+```typescript
+// Check if data is being saved
+this.storage.setItem('test-data', 'test');
+console.log('Data saved:', this.storage.getItem('test-data'));
+
+// Check for storage availability
+if (typeof(Storage) !== "undefined") {
+  console.log('localStorage is available');
+} else {
+  console.log('localStorage is not supported');
+}
+```
+
+## Related Documentation
+
+- [HTTP State Service](http-state/README.md)
+- [Local Storage Signals Service](local-storage-signals/README.md)
+- [Database Manager Service](database/README.md)
+- [Utils Service](utils/README.md)
+- [Architecture Overview](../architecture/README.md)