http-request-manager 18.15.32 → 18.15.34

package/src/docs/STORE_STATE_SIGNALS_README.md

@@ -0,0 +1,600 @@
+<!-- markdownlint-disable MD031 MD060 -->
+
+# Store State Manager Signals Service
+
+The `StoreStateManagerSignalsService<T>` provides generic, signal-based state management with automatic localStorage persistence for modern Angular applications.
+
+## Overview
+
+This service is a **signal-based alternative** to `StoreStateManagerService`, designed for Angular 19+ applications that need type-safe, reactive state management with automatic persistence.
+
+### Key Features
+
+- ✅ **Generic Type Support** - Full TypeScript generics for type safety
+- ✅ **Signal-Based State** - All state exposed as Angular Signals
+- ✅ **Auto-Persistence** - Automatically saves to localStorage
+- ✅ **Model Transformation** - Computed signals for transformed data
+- ✅ **No Subscriptions** - No manual subscription management
+- ✅ **Built on LocalStorageSignalsManagerService** - Leverages signal-based storage
+
+## Installation
+
+```typescript
+import { StoreStateManagerSignalsService, StateStorageOptions } from 'http-request-manager';
+```
+
+## Basic Usage
+
+### Counter Example
+
+```typescript
+import { Component, computed } from '@angular/core';
+import { StoreStateManagerSignalsService, StateStorageOptions } from 'http-request-manager';
+
+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() }}</h2>
+      <p>Last Updated: {{ lastUpdated() }}</p>
+      <p>History: {{ historyLength() }} 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 StoreStateManagerSignalsService<CounterState>();
+  
+  constructor() {
+    const options = StateStorageOptions.adapt({
+      store: 'counter-state',
+      model: defaultCounterState,
+      options: {
+        storage: 'global',
+        encrypted: false
+      }
+    });
+    
+    this.stateManager.init(options);
+  }
+  
+  // Computed signals from state
+  count = computed(() => this.stateManager.data()?.count || 0);
+  lastUpdated = computed(() => this.stateManager.data()?.lastUpdated || '');
+  historyLength = computed(() => this.stateManager.data()?.history.length || 0);
+  history = computed(() => this.stateManager.data()?.history || []);
+  
+  increment() {
+    const current = this.stateManager.data();
+    if (current) {
+      this.stateManager.updateState({
+        count: current.count + 1,
+        lastUpdated: new Date().toISOString()
+      });
+    }
+  }
+  
+  decrement() {
+    const current = this.stateManager.data();
+    if (current) {
+      this.stateManager.updateState({
+        count: current.count - 1,
+        lastUpdated: new Date().toISOString()
+      });
+    }
+  }
+  
+  reset() {
+    this.stateManager.resetState();
+  }
+  
+  addToHistory() {
+    const current = this.stateManager.data();
+    if (current) {
+      this.stateManager.updateState({
+        history: [...current.history, current.count],
+        lastUpdated: new Date().toISOString()
+      });
+    }
+  }
+}
+```
+
+## API Reference
+
+### Constructor
+
+```typescript
+constructor()
+```
+
+Creates a new instance of the service. Use `init()` to configure.
+
+### Methods
+
+#### `init(options: StateStorageOptions)`
+
+Initializes the state manager with configuration 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.
+
+```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>)`
+
+Updates state with keyed data. Useful for partial updates.
+
+```typescript
+// Update specific property
+this.stateManager.updateData({ name: 'John' });
+```
+
+#### `restoreState()`
+
+Restores state from localStorage.
+
+```typescript
+this.stateManager.restoreState();
+```
+
+#### `resetState()`
+
+Resets state to initial model value.
+
+```typescript
+this.stateManager.resetState();
+```
+
+### Signals
+
+#### `data: ReadonlySignal<T | null>`
+
+Readonly signal containing current state.
+
+```typescript
+state = this.stateManager.data;
+// Usage: state()
+```
+
+#### `transformedData: ComputedSignal<T>`
+
+Computed signal with model transformation applied.
+
+```typescript
+transformed = this.stateManager.transformedData;
+// Usage: transformed()
+```
+
+## 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, computed } from '@angular/core';
+import { StoreStateManagerSignalsService, StateStorageOptions } from 'http-request-manager';
+
+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 StoreStateManagerSignalsService<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);
+  }
+  
+  // Computed selectors
+  profile = computed(() => this.stateManager.data());
+  isLoggedIn = computed(() => !!this.stateManager.data()?.id);
+  userName = computed(() => this.stateManager.data()?.name || 'Guest');
+  theme = computed(() => this.stateManager.data()?.preferences.theme || 'light');
+  
+  updateProfile(profile: Partial<UserProfile>) {
+    this.stateManager.updateState(profile);
+  }
+  
+  updatePreferences(prefs: Partial<UserProfile['preferences']>) {
+    const current = this.stateManager.data();
+    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, computed } from '@angular/core';
+import { StoreStateManagerSignalsService, StateStorageOptions } from 'http-request-manager';
+
+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() }}</p>
+      <p>Total: ${{ total().toFixed(2) }}</p>
+      
+      <div class="cart-items">
+        @for (item of items(); track item.id) {
+          <div 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 StoreStateManagerSignalsService<CartState>();
+  
+  constructor() {
+    const options = StateStorageOptions.adapt({
+      store: 'shopping-cart',
+      model: defaultCart,
+      options: {
+        storage: 'global',
+        encrypted: false
+      }
+    });
+    
+    this.stateManager.init(options);
+  }
+  
+  // Computed signals
+  items = computed(() => this.stateManager.data()?.items || []);
+  itemCount = computed(() => this.items().length);
+  total = computed(() => 
+    this.items().reduce((sum, item) => sum + (item.price * item.quantity), 0)
+  );
+  
+  addItem(item: CartItem) {
+    const current = this.stateManager.data();
+    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.data();
+    if (!current) return;
+    
+    this.stateManager.updateState({
+      items: current.items.filter(i => i.id !== id),
+      lastUpdated: new Date().toISOString()
+    });
+  }
+  
+  clearCart() {
+    this.stateManager.resetState();
+  }
+}
+```
+
+## Migration from ComponentStore 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 (Signals)
+
+```typescript
+import { StoreStateManagerSignalsService } from 'http-request-manager';
+
+interface CounterState {
+  count: number;
+}
+
+class CounterService {
+  private stateManager = new StoreStateManagerSignalsService<CounterState>();
+  
+  constructor() {
+    this.stateManager.init({
+      store: 'counter',
+      model: () => ({ count: 0 })
+    });
+  }
+  
+  readonly count = computed(() => this.stateManager.data()?.count || 0);
+  
+  increment() {
+    const current = this.stateManager.data();
+    this.stateManager.updateState({
+      count: (current?.count || 0) + 1
+    });
+  }
+}
+```
+
+## Comparison with Non-Signal Version
+
+| Feature | ComponentStore Version | Signal Version |
+|---------|----------------------|----------------|
+| **State Management** | NgRx ComponentStore | Angular Signals |
+| **Initialization** | `super(initialState)` | `init(options)` |
+| **Selectors** | `select()` with observables | `computed()` signals |
+| **Updaters** | `updater()` methods | `updateState()` |
+| **Persistence** | Manual subscription | Automatic with effect |
+| **Type Safety** | Generic `<T>` | Generic `<T>` |
+| **Subscriptions** | Manual management | Automatic |
+| **Angular Version** | 14-18 | 19+ |
+
+## Best Practices
+
+1. **Use Computed Signals for Derived State**
+   ```typescript
+   // ✅ Good
+   count = computed(() => this.stateManager.data()?.count || 0);
+   total = computed(() => this.items().reduce(...));
+   
+   // ❌ Avoid
+   getCount() { return this.stateManager.data()?.count; }
+   ```
+
+2. **Initialize Once**
+   ```typescript
+   // ✅ Good - Initialize in constructor or ngOnInit
+   constructor() {
+     this.stateManager.init(options);
+   }
+   
+   // ❌ Avoid - Multiple initializations
+   init() {
+     this.stateManager.init(options); // Called multiple times
+   }
+   ```
+
+3. **Use Partial Updates**
+   ```typescript
+   // ✅ Good - Update only what changed
+   this.stateManager.updateState({ name: 'John' });
+   
+   // ❌ Avoid - Requiring full state
+   this.stateManager.updateState(fullStateObject);
+   ```
+
+4. **Leverage Auto-Persistence**
+   ```typescript
+   // ✅ Good - Just update state
+   this.stateManager.updateState({ count: 42 });
+   
+   // ❌ Avoid - Manual persistence
+   this.stateManager.updateState({ count: 42 });
+   this.save(); // Not needed!
+   ```
+
+## Troubleshooting
+
+### State Not Persisting
+
+**Problem**: State changes not saved to localStorage
+
+**Solution**: Ensure `init()` is called and stateRetrieved flag is set
+```typescript
+this.stateManager.init(options);
+```
+
+### Type Errors
+
+**Problem**: TypeScript errors with generic type
+
+**Solution**: Ensure model function returns correct type
+```typescript
+const options = StateStorageOptions.adapt({
+  store: 'my-store',
+  model: () => ({ count: 0 }) as MyState,  // Cast to your type
+  options: { ... }
+});
+```
+
+### Null State
+
+**Problem**: `data()` returns null
+
+**Solution**: Check if `init()` was called and use default values
+```typescript
+count = computed(() => this.stateManager.data()?.count || 0);
+```
+
+## Related Documentation
+
+- [Signal Services Index](./SIGNAL_SERVICES_README.md)
+- [Non-Signal Store State](./COMPLETE_API_REFERENCE.md#storestatemanagerservice)
+- [LocalStorage Signals](./LOCAL_STORAGE_SIGNALS_README.md)