http-request-manager 18.15.34 → 18.16.1

package/src/docs/STORE_STATE_MANAGER_README.md

@@ -1,556 +0,0 @@
-<!-- markdownlint-disable MD031 MD060 -->
-
-# Store State Manager Service
-
-The `StoreStateManagerService<T>` provides generic, ComponentStore-based state management with automatic localStorage persistence for Angular applications.
-
-## Overview
-
-This service is a **ComponentStore-based** state management solution designed for Angular applications that need type-safe state management with automatic persistence to localStorage or sessionStorage.
-
-### Key Features
-
-- ✅ **Generic Type Support** - Full TypeScript generics for type safety
-- ✅ **ComponentStore-Based** - Built on NgRx ComponentStore for robust state management
-- ✅ **Auto-Persistence** - Automatically saves to localStorage/sessionStorage
-- ✅ **Model Transformation** - Support for model transformation functions
-- ✅ **Reactive Updates** - Observable-based state updates
-- ✅ **Built on LocalStorageManagerService** - Leverages secure storage layer
-
-## Installation
-
-```typescript
-import { StoreStateManagerService, StateStorageOptions } from 'http-request-manager';
-```
-
-## Basic Usage
-
-### Counter Example
-
-```typescript
-import { Component, inject } from '@angular/core';
-import { StoreStateManagerService, StateStorageOptions } from 'http-request-manager';
-import { Observable } from 'rxjs';
-
-interface CounterState {
-  count: number;
-  lastUpdated: string;
-  history: number[];
-}
-
-const defaultCounterState: () => CounterState = () => ({
-  count: 0,
-  lastUpdated: new Date().toISOString(),
-  history: []
-});
-
-@Component({
-  selector: 'app-counter',
-  template: `
-    <div class="counter">
-      <h2>Count: {{ count$ | async }}</h2>
-      <p>Last Updated: {{ lastUpdated$ | async }}</p>
-      <p>History: {{ historyLength$ | async }} items</p>
-      
-      <div class="actions">
-        <button (click)="increment()">+</button>
-        <button (click)="decrement()">-</button>
-        <button (click)="reset()">Reset</button>
-        <button (click)="addToHistory()">Add to History</button>
-      </div>
-    </div>
-  `
-})
-export class CounterComponent {
-  private stateManager = new StoreStateManagerService<CounterState>();
-  
-  // Observable selectors
-  count$: Observable<number> = this.stateManager.select(state => state.count || 0);
-  lastUpdated$: Observable<string> = this.stateManager.select(state => state.lastUpdated || '');
-  historyLength$: Observable<number> = this.stateManager.select(state => state.history?.length || 0);
-  history$: Observable<number[]> = this.stateManager.select(state => state.history || []);
-
-  constructor() {
-    const options = StateStorageOptions.adapt({
-      store: 'counter-state',
-      model: defaultCounterState,
-      options: {
-        storage: 'global',
-        encrypted: false
-      }
-    });
-    
-    this.stateManager.init(options);
-  }
-  
-  increment() {
-    const current = this.stateManager.get();
-    this.stateManager.updateState({
-      count: (current?.count || 0) + 1,
-      lastUpdated: new Date().toISOString()
-    });
-  }
-  
-  decrement() {
-    const current = this.stateManager.get();
-    this.stateManager.updateState({
-      count: (current?.count || 0) - 1,
-      lastUpdated: new Date().toISOString()
-    });
-  }
-  
-  reset() {
-    this.stateManager.resetState();
-  }
-  
-  addToHistory() {
-    const current = this.stateManager.get();
-    this.stateManager.updateState({
-      history: [...(current?.history || []), current?.count || 0],
-      lastUpdated: new Date().toISOString()
-    });
-  }
-}
-```
-
-## API Reference
-
-### Constructor
-
-```typescript
-constructor(options?: StateStorageOptions)
-```
-
-Creates a new instance with optional configuration.
-
-### Methods
-
-#### `init(options?: StateStorageOptions)`
-
-Initializes or reconfigures the state manager with options.
-
-```typescript
-interface StateStorageOptions {
-  store: string;              // Store name
-  model: () => T;             // Factory function for initial state
-  options: SettingOptions;    // Storage options
-}
-
-// Example
-const options = StateStorageOptions.adapt({
-  store: 'user-preferences',
-  model: () => ({ theme: 'light', language: 'en' }),
-  options: {
-    storage: 'global',
-    encrypted: false,
-    expiresIn: '30d'
-  }
-});
-
-this.stateManager.init(options);
-```
-
-#### `updateState(state: Partial<T>)`
-
-Updates the state with partial data. Merges with existing state and persists to storage.
-
-```typescript
-interface UserState {
-  name: string;
-  email: string;
-  age: number;
-}
-
-// Update single field
-this.stateManager.updateState({ name: 'John' });
-
-// Update multiple fields
-this.stateManager.updateState({ 
-  name: 'Jane',
-  email: 'jane@example.com'
-});
-```
-
-#### `updateData(data: Partial<T>)`
-
-Updater method for partial state updates. Uses ComponentStore updater pattern.
-
-```typescript
-// Update specific property
-this.stateManager.updateData({ name: 'John' });
-```
-
-#### `restoreState()`
-
-Restores state from localStorage. Returns a Subscription.
-
-```typescript
-const subscription = this.stateManager.restoreState();
-```
-
-#### `resetState()`
-
-Resets state to initial model value and updates storage.
-
-```typescript
-this.stateManager.resetState();
-```
-
-### Observables
-
-#### `data$: Observable<T>`
-
-Main observable containing current state with model transformation applied.
-
-```typescript
-state$ = this.stateManager.data$;
-// Usage: state$ | async
-```
-
-#### `operationResult$: Observable<StateOperationResult | null>`
-
-Observable emitting operation results for CREATE, UPDATE, DELETE operations.
-
-```typescript
-interface StateOperationResult {
-  success: boolean;
-  operation: 'CREATE' | 'UPDATE' | 'DELETE';
-  key?: string;
-  value?: any;
-  timestamp: number;
-  error?: string;
-}
-
-// Usage
-this.stateManager.operationResult$.subscribe(result => {
-  if (result?.success) {
-    console.log(`${result.operation} succeeded for key: ${result.key}`);
-  }
-});
-```
-
-### Selectors
-
-Use ComponentStore's `select` method to create derived observables:
-
-```typescript
-readonly count$ = this.select(state => state.count);
-readonly history$ = this.select(state => state.history);
-readonly isLoggedIn$ = this.select(state => !!state.user?.id);
-```
-
-### Updaters
-
-Use ComponentStore's `updater` method to create state update functions:
-
-```typescript
-readonly increment = this.updater((state, value: number) => ({
-  ...state,
-  count: state.count + value,
-  lastUpdated: new Date().toISOString()
-}));
-
-readonly addUser = this.updater((state, user: User) => ({
-  ...state,
-  users: [...state.users, user]
-}));
-```
-
-## StateStorageOptions
-
-### Interface
-
-```typescript
-interface StateStorageOptionsInterface {
-  store?: string;
-  options?: SettingOptions;
-  model?: (state: any) => any;
-}
-```
-
-### SettingOptions
-
-```typescript
-interface SettingOptions {
-  storage?: StorageType;      // 'global' or 'session'
-  encrypted?: boolean;         // Enable encryption
-  expiresIn?: string;          // Expiration: '1h', '1d', '7d', '30d'
-  expires?: number;           // Expiration timestamp (computed)
-}
-```
-
-### StorageType
-
-```typescript
-enum StorageType {
-  GLOBAL = 'global',           // localStorage
-  SESSION = 'session'          // sessionStorage
-}
-```
-
-## Advanced Examples
-
-### User Profile Management
-
-```typescript
-import { Injectable } from '@angular/core';
-import { StoreStateManagerService, StateStorageOptions } from 'http-request-manager';
-import { Observable } from 'rxjs';
-
-interface UserProfile {
-  id: string;
-  name: string;
-  email: string;
-  avatar?: string;
-  preferences: {
-    theme: 'light' | 'dark';
-    language: string;
-    notifications: boolean;
-  };
-  lastLogin: string;
-}
-
-const defaultProfile: () => UserProfile = () => ({
-  id: '',
-  name: '',
-  email: '',
-  preferences: {
-    theme: 'light',
-    language: 'en',
-    notifications: true
-  },
-  lastLogin: new Date().toISOString()
-});
-
-@Injectable({ providedIn: 'root' })
-export class UserProfileService {
-  private stateManager = new StoreStateManagerService<UserProfile>();
-  
-  constructor() {
-    this.init();
-  }
-  
-  private init() {
-    const options = StateStorageOptions.adapt({
-      store: 'user-profile',
-      model: defaultProfile,
-      options: {
-        storage: 'global',
-        encrypted: false,
-        expiresIn: '90d'
-      }
-    });
-    
-    this.stateManager.init(options);
-  }
-  
-  // Selectors
-  readonly profile$ = this.stateManager.select(state => state);
-  readonly isLoggedIn$ = this.stateManager.select(state => !!state.id);
-  readonly userName$ = this.stateManager.select(state => state.name || 'Guest');
-  readonly theme$ = this.stateManager.select(state => state.preferences.theme || 'light');
-  
-  updateProfile(profile: Partial<UserProfile>) {
-    this.stateManager.updateState(profile);
-  }
-  
-  updatePreferences(prefs: Partial<UserProfile['preferences']>) {
-    const current = this.stateManager.get();
-    if (current) {
-      this.stateManager.updateState({
-        ...current,
-        preferences: { ...current.preferences, ...prefs }
-      });
-    }
-  }
-  
-  login(user: { id: string; name: string; email: string }) {
-    this.stateManager.updateState({
-      ...user,
-      lastLogin: new Date().toISOString()
-    });
-  }
-  
-  logout() {
-    this.stateManager.resetState();
-  }
-}
-```
-
-### Shopping Cart with Persistence
-
-```typescript
-import { Component, inject } from '@angular/core';
-import { StoreStateManagerService, StateStorageOptions } from 'http-request-manager';
-import { Observable } from 'rxjs';
-
-interface CartItem {
-  id: number;
-  name: string;
-  price: number;
-  quantity: number;
-}
-
-interface CartState {
-  items: CartItem[];
-  lastUpdated: string;
-}
-
-const defaultCart: () => CartState = () => ({
-  items: [],
-  lastUpdated: new Date().toISOString()
-});
-
-@Component({
-  selector: 'app-shopping-cart',
-  template: `
-    <div class="cart">
-      <h2>Shopping Cart</h2>
-      <p>Items: {{ itemCount$ | async }}</p>
-      <p>Total: ${{ total$ | async | number:'1.2-2' }}</p>
-      
-      <div class="cart-items">
-        <div *ngFor="let item of items$ | async" class="cart-item">
-          <span>{{ item.name }}</span>
-          <span>\${{ item.price }} x {{ item.quantity }}</span>
-          <span>Subtotal: \${{ item.price * item.quantity }}</span>
-          <button (click)="removeItem(item.id)">Remove</button>
-        </div>
-      </div>
-      
-      <button (click)="clearCart()">Clear Cart</button>
-    </div>
-  `
-})
-export class ShoppingCartComponent {
-  private stateManager = new StoreStateManagerService<CartState>();
-  
-  constructor() {
-    const options = StateStorageOptions.adapt({
-      store: 'shopping-cart',
-      model: defaultCart,
-      options: {
-        storage: 'global',
-        encrypted: false
-      }
-    });
-    
-    this.stateManager.init(options);
-  }
-  
-  // Selectors
-  items$ = this.stateManager.select(state => state.items || []);
-  itemCount$ = this.stateManager.select(state => state.items.length);
-  total$ = this.stateManager.select(state => 
-    state.items.reduce((sum, item) => sum + (item.price * item.quantity), 0)
-  );
-  
-  addItem(item: CartItem) {
-    const current = this.stateManager.get();
-    if (!current) return;
-    
-    const existing = current.items.find(i => i.id === item.id);
-    
-    if (existing) {
-      this.stateManager.updateState({
-        items: current.items.map(i => 
-          i.id === item.id 
-            ? { ...i, quantity: i.quantity + 1 }
-            : i
-        ),
-        lastUpdated: new Date().toISOString()
-      });
-    } else {
-      this.stateManager.updateState({
-        items: [...current.items, { ...item, quantity: 1 }],
-        lastUpdated: new Date().toISOString()
-      });
-    }
-  }
-  
-  removeItem(id: number) {
-    const current = this.stateManager.get();
-    if (!current) return;
-    
-    this.stateManager.updateState({
-      items: current.items.filter(i => i.id !== id),
-      lastUpdated: new Date().toISOString()
-    });
-  }
-  
-  clearCart() {
-    this.stateManager.resetState();
-  }
-}
-```
-
-## Migration to Signals Version
-
-### Before (ComponentStore)
-
-```typescript
-import { ComponentStore } from '@ngrx/component-store';
-
-interface State {
-  count: number;
-}
-
-class CounterStore extends ComponentStore<State> {
-  constructor() {
-    super({ count: 0 });
-  }
-  
-  readonly count$ = this.select(state => state.count);
-  
-  readonly increment = this.updater((state) => ({
-    count: state.count + 1
-  }));
-}
-```
-
-### After (StoreStateManagerService)
-
-```typescript
-import { StoreStateManagerService, StateStorageOptions } from 'http-request-manager';
-
-interface CounterState {
-  count: number;
-}
-
-class CounterService {
-  private stateManager = new StoreStateManagerService<CounterState>();
-  
-  constructor() {
-    this.stateManager.init({
-      store: 'counter',
-      model: () => ({ count: 0 })
-    });
-  }
-  
-  readonly count$ = this.stateManager.select(state => state.count || 0);
-  
-  increment() {
-    const current = this.stateManager.get();
-    this.stateManager.updateState({
-      count: (current?.count || 0) + 1
-    });
-  }
-}
-```
-
-**Benefits of StoreStateManagerService:**
-- ✅ Automatic persistence to localStorage
-- ✅ Built-in model transformation
-- ✅ Operation result tracking
-- ✅ State restoration on app restart
-- ✅ Encryption support
-
-### Modern Alternative (Signals)
-
-For Angular 19+, consider using [`StoreStateManagerSignalsService`](./STORE_STATE_SIGNALS_README.md) for better performance and simpler code.
-
-## Related Documentation
-
-- [Store State Signals Service](./STORE_STATE_SIGNALS_README.md) - Signal-based version for Angular 19+
-- [Local Storage Manager Service](./LOCAL_STORAGE_README.md) - Underlying storage layer
-- [Complete API Reference](./COMPLETE_API_REFERENCE.md) - Full service API