http-request-manager 18.15.33 → 18.15.34

package/src/docs/LOCAL_STORAGE_SIGNALS_README.md

@@ -0,0 +1,338 @@
+# Local Storage Signals Manager Service
+
+The `LocalStorageSignalsManagerService` provides signal-based local and session storage management with encryption, expiration, and automatic persistence for Angular 19+ applications.
+
+## Overview
+
+This service is the signal-based alternative to `LocalStorageManagerService`. The public API is **store-based**: you create named stores, read them through computed signals, and update them by replacing store data. It does **not** expose a per-key `signal()` / `setSignal()` helper API.
+
+### Key Features
+
+- Signal-first selectors via `store(name)`, `stores`, `setting(name)`, and `settings`
+- Automatic persistence to `localStorage` or `sessionStorage`
+- Optional encryption for sensitive store data
+- Expiration support with automatic cleanup
+- Compatible with store-oriented app state such as preferences, sessions, and carts
+
+## Installation
+
+```typescript
+import { HttpRequestManagerModule } from 'http-request-manager';
+
+@NgModule({
+  imports: [
+    HttpRequestManagerModule.forRoot({
+      LocalStorageOptions: {
+        storageName: 'my-app-data',
+        storageSettingsName: 'my-app-settings',
+        options: {
+          encrypted: false,
+          expiresIn: '7d'
+        }
+      }
+    })
+  ]
+})
+export class AppModule {}
+```
+
+## Basic Usage
+
+### Preferences Store Example
+
+```typescript
+import { Component, computed, inject } from '@angular/core';
+import {
+  LocalStorageSignalsManagerService,
+  StorageType
+} from 'http-request-manager';
+
+interface PreferencesState {
+  theme: 'light' | 'dark' | 'auto';
+  language: string;
+  notifications: boolean;
+  lastUpdated: string;
+}
+
+const defaultPreferences = (): PreferencesState => ({
+  theme: 'light',
+  language: 'en',
+  notifications: true,
+  lastUpdated: new Date().toISOString()
+});
+
+@Component({
+  selector: 'app-user-preferences',
+  template: `
+    <div>
+      <p>Theme: {{ theme() }}</p>
+      <p>Language: {{ language() }}</p>
+      <p>Notifications: {{ notifications() ? 'On' : 'Off' }}</p>
+      <button (click)="setTheme('dark')">Dark</button>
+      <button (click)="setTheme('light')">Light</button>
+    </div>
+  `
+})
+export class UserPreferencesComponent {
+  private storage = inject(LocalStorageSignalsManagerService);
+  private readonly storeName = 'user-preferences';
+
+  preferencesStore = this.storage.store(this.storeName);
+
+  preferences = computed(
+    () => this.preferencesStore() ?? defaultPreferences()
+  );
+
+  theme = computed(() => this.preferences().theme);
+  language = computed(() => this.preferences().language);
+  notifications = computed(() => this.preferences().notifications);
+
+  constructor() {
+    if (!this.storage.storeExists(this.storeName)()) {
+      this.storage.createStore({
+        name: this.storeName,
+        data: defaultPreferences(),
+        options: {
+          storage: StorageType.GLOBAL,
+          encrypted: false,
+          expiresIn: '30d'
+        }
+      });
+    }
+  }
+
+  setTheme(theme: PreferencesState['theme']) {
+    const current = this.preferences();
+
+    this.storage.updateStore({
+      name: this.storeName,
+      data: {
+        ...current,
+        theme,
+        lastUpdated: new Date().toISOString()
+      }
+    });
+  }
+}
+```
+
+## API Reference
+
+### Store Mutators
+
+#### `createStore(store: { name: string; data: any; options: SettingOptions })`
+
+Creates a new named store if one does not already exist.
+
+```typescript
+storage.createStore({
+  name: 'user-settings',
+  data: { theme: 'light', language: 'en' },
+  options: {
+    storage: StorageType.GLOBAL,
+    encrypted: false,
+    expiresIn: '30d'
+  }
+});
+```
+
+#### `setStore(store: { id: string; name: string; data: any; options: SettingOptions })`
+
+Low-level setter for replacing a store entry using an explicit store id.
+
+```typescript
+storage.setStore({
+  id: 'abc123',
+  name: 'user-settings',
+  data: { theme: 'dark', language: 'fr' },
+  options: { storage: StorageType.GLOBAL }
+});
+```
+
+#### `updateStore(store: { name: string; data: any })`
+
+Replaces the stored data for an existing named store.
+
+```typescript
+storage.updateStore({
+  name: 'user-settings',
+  data: {
+    theme: 'dark',
+    language: 'fr'
+  }
+});
+```
+
+#### `deleteStore(store: { name: string })`
+
+Removes a named store.
+
+```typescript
+storage.deleteStore({ name: 'user-settings' });
+```
+
+#### `resetStore()`
+
+Clears all managed stores and settings.
+
+```typescript
+storage.resetStore();
+```
+
+### Computed Selectors
+
+#### `stores`
+
+Returns all store settings as a computed signal.
+
+```typescript
+allStores = this.storage.stores;
+allStores();
+```
+
+#### `store(name: string)`
+
+Returns a computed signal for the named store's data.
+
+```typescript
+userSettings = this.storage.store('user-settings');
+userSettings();
+```
+
+#### `settings`
+
+Returns all store settings as a computed signal.
+
+```typescript
+settings = this.storage.settings;
+settings();
+```
+
+#### `setting(name: string)`
+
+Returns a computed signal for one store setting definition.
+
+```typescript
+setting = this.storage.setting('user-settings');
+setting();
+```
+
+#### `storeExists(name: string)`
+
+Returns a computed signal indicating whether a named store exists.
+
+```typescript
+exists = this.storage.storeExists('user-settings');
+exists();
+```
+
+## Storage Options
+
+### `SettingOptions`
+
+```typescript
+interface SettingOptions {
+  storage?: StorageType;
+  encrypted?: boolean;
+  expiresIn?: string;
+  expires?: number;
+}
+```
+
+### `StorageType`
+
+```typescript
+enum StorageType {
+  GLOBAL = 'global',
+  SESSION = 'session'
+}
+```
+
+## Common Patterns
+
+### Session Store
+
+```typescript
+storage.createStore({
+  name: 'session',
+  data: {
+    token: 'abc123',
+    userId: 'u-1'
+  },
+  options: {
+    storage: StorageType.SESSION,
+    encrypted: true,
+    expiresIn: '24h'
+  }
+});
+```
+
+### Cart Store
+
+```typescript
+const cartStore = storage.store('cart');
+
+storage.createStore({
+  name: 'cart',
+  data: [],
+  options: {
+    storage: StorageType.GLOBAL,
+    encrypted: false
+  }
+});
+
+const cartItems = computed(() => cartStore() ?? []);
+
+function addItem(item: any) {
+  storage.updateStore({
+    name: 'cart',
+    data: [...cartItems(), item]
+  });
+}
+```
+
+## Migration from the Observable Version
+
+### Before
+
+```typescript
+private storage = inject(LocalStorageManagerService);
+
+preferences$ = this.storage.store$('user-preferences');
+
+savePreferences(data: any) {
+  this.storage.updateStore({
+    name: 'user-preferences',
+    data
+  });
+}
+```
+
+### After
+
+```typescript
+private storage = inject(LocalStorageSignalsManagerService);
+
+preferencesStore = this.storage.store('user-preferences');
+preferences = computed(() => this.preferencesStore() ?? {});
+
+savePreferences(data: any) {
+  this.storage.updateStore({
+    name: 'user-preferences',
+    data
+  });
+}
+```
+
+## Notes
+
+- The service restores persisted state during its own initialization. You do not need to call `retrieveState()` from consuming components.
+- Use `updateStore()` when you want to replace a store's current payload with merged application state.
+- Use encryption for tokens, session payloads, and sensitive user data.
+
+## Related Documentation
+
+- [Signal Services Index](./SIGNAL_SERVICES_README.md)
+- [Non-Signal Local Storage](./LOCAL_STORAGE_README.md)
+- [Encryption Guide](./ENCRYPTION_README.md)
+- [Store State Signals](./STORE_STATE_SIGNALS_README.md)

package/src/docs/LOGGER_README.md

@@ -0,0 +1,310 @@
+# LoggerService
+
+Centralized logging service for the `http-request-manager` library.
+
+## Overview
+
+The `LoggerService` provides controlled logging that automatically adapts based on the Angular build mode:
+
+- **Development Mode**: Debug and info logs are enabled
+- **Production Mode**: Only warnings and errors are logged
+
+This ensures verbose logging during development while keeping production builds clean and performant.
+
+## Features
+
+- ✅ **Automatic Mode Detection**: Uses Angular's `isDevMode()` to determine logging behavior
+- ✅ **No Configuration Required**: Works out of the box - consuming apps don't need to configure anything
+- ✅ **Multiple Log Levels**: `debug`, `info`, `warn`, `error`
+- ✅ **Context-Aware**: Each log includes a context identifier for easy filtering
+- ✅ **Type-Safe**: Full TypeScript support
+
+## Usage
+
+### Inject the Service
+
+```typescript
+import { LoggerService } from 'http-request-manager';
+
+@Component({ ... })
+export class MyComponent {
+  private logger = inject(LoggerService);
+  
+  doSomething() {
+    this.logger.debug('MyComponent', 'Starting operation');
+  }
+}
+```
+
+### Log Levels
+
+#### Debug (Development Only)
+
+Use for detailed diagnostic information, state changes, connection events:
+
+```typescript
+this.logger.debug('WebSocket', 'Connected to server', { 
+  server: 'ws://localhost:3000',
+  sessionId: 'abc123' 
+});
+```
+
+**Output in Dev Mode:**
+```
+[HTTP-MGR DEBUG] WebSocket: Connected to server { server: 'ws://localhost:3000', sessionId: 'abc123' }
+```
+
+**Output in Prod Mode:**
+```
+(no output)
+```
+
+#### Info (Development Only)
+
+Use for important operational messages and successful operations:
+
+```typescript
+this.logger.info('HTTP', 'Request completed successfully', {
+  url: '/api/users',
+  status: 200,
+  duration: '125ms'
+});
+```
+
+**Output in Dev Mode:**
+```
+[HTTP-MGR INFO] HTTP: Request completed successfully { url: '/api/users', status: 200, duration: '125ms' }
+```
+
+**Output in Prod Mode:**
+```
+(no output)
+```
+
+#### Warning (Always Shown)
+
+Use for potential issues, deprecated usage, recoverable errors:
+
+```typescript
+this.logger.warn('Cache', 'Cache miss for key', { key: 'user_profile' });
+```
+
+**Output (All Modes):**
+```
+[HTTP-MGR WARN] Cache: Cache miss for key { key: 'user_profile' }
+```
+
+#### Error (Always Shown)
+
+Use for actual errors, failures, exceptions:
+
+```typescript
+this.logger.error('Database', 'Connection failed', error);
+```
+
+**Output (All Modes):**
+```
+[HTTP-MGR ERROR] Database: Connection failed Error: Connection timeout...
+```
+
+## Log Output Format
+
+All logs follow a consistent format:
+
+```
+[HTTP-MGR <LEVEL>] <Context>: <Message> <Optional Data>
+```
+
+- **LEVEL**: DEBUG, INFO, WARN, or ERROR
+- **Context**: Component, service, or feature name (e.g., 'WebSocket', 'HTTP', 'StateStore')
+- **Message**: Descriptive message
+- **Data**: Optional object with additional details
+
+## When to Use Each Level
+
+| Level | When to Use | Production Output |
+|-------|-------------|-------------------|
+| `debug` | Detailed diagnostics, state changes, connection events | ❌ Hidden |
+| `info` | Successful operations, important milestones | ❌ Hidden |
+| `warn` | Recoverable errors, deprecated usage, potential issues | ✅ Shown |
+| `error` | Actual failures, exceptions, critical issues | ✅ Shown |
+
+## Examples
+
+### WebSocket Connection
+
+```typescript
+import { LoggerService } from 'http-request-manager';
+
+@Injectable({ providedIn: 'root' })
+export class MyWebSocketService {
+  private logger = inject(LoggerService);
+
+  connect(url: string) {
+    this.logger.debug('WebSocket', 'Attempting connection', { url });
+    
+    this.socket = new WebSocket(url);
+    
+    this.socket.onopen = () => {
+      this.logger.info('WebSocket', '📡 Connected successfully');
+    };
+    
+    this.socket.onerror = (error) => {
+      this.logger.error('WebSocket', 'Connection error', error);
+    };
+  }
+}
+```
+
+### HTTP Request
+
+```typescript
+import { LoggerService } from 'http-request-manager';
+
+@Injectable({ providedIn: 'root' })
+export class HttpService {
+  private logger = inject(LoggerService);
+
+  fetchData(id: string) {
+    this.logger.debug('HTTP', 'Fetching data', { id });
+    
+    return this.http.get(`/api/data/${id}`).pipe(
+      tap(data => {
+        this.logger.info('HTTP', 'Data fetched successfully', { id, count: data.length });
+      }),
+      catchError(error => {
+        this.logger.error('HTTP', 'Fetch failed', { id, error });
+        throw error;
+      })
+    );
+  }
+}
+```
+
+### State Management
+
+```typescript
+import { LoggerService } from 'http-request-manager';
+
+@Injectable()
+export class StateStore extends ComponentStore<State> {
+  private logger = inject(LoggerService);
+
+  updateItem(item: Item) {
+    this.logger.debug('StateStore', 'Updating item', { id: item.id });
+    
+    this.patchState({ items: [...this.state().items, item] });
+    
+    this.logger.info('StateStore', 'Item updated', { 
+      itemId: item.id,
+      totalItems: this.state().items.length 
+    });
+  }
+}
+```
+
+## Migration Guide
+
+### Before (Using console.*)
+
+```typescript
+console.log('WebSocket connected');
+console.error('Error:', error);
+console.warn('Warning message');
+```
+
+### After (Using LoggerService)
+
+```typescript
+this.logger.debug('WebSocket', 'Connected');
+this.logger.error('WebSocket', 'Connection error', error);
+this.logger.warn('WebSocket', 'Connection unstable');
+```
+
+## Benefits
+
+### 1. Automatic Production Optimization
+
+No need to manually strip console statements - debug and info logs are automatically hidden in production builds.
+
+### 2. Consistent Formatting
+
+All logs follow the same format, making them easy to filter and search in browser console.
+
+### 3. Context-Aware
+
+Each log includes context, making it easy to identify the source:
+```
+[HTTP-MGR DEBUG] WebSocket: Connected
+[HTTP-MGR DEBUG] HTTP: Request sent
+[HTTP-MGR DEBUG] StateStore: State updated
+```
+
+### 4. Type Safety
+
+Full TypeScript support with proper typing for all parameters.
+
+### 5. Future-Proof
+
+Easy to extend with additional features:
+- Remote logging
+- Log aggregation
+- Performance monitoring
+- Custom formatters
+
+## API Reference
+
+### LoggerService
+
+#### Methods
+
+##### `debug(context: string, message: string, data?: any): void`
+
+Logs debug information (development mode only).
+
+##### `info(context: string, message: string, data?: any): void`
+
+Logs informational messages (development mode only).
+
+##### `warn(context: string, message: string, data?: any): void`
+
+Logs warnings (always shown).
+
+##### `error(context: string, message: string, data?: any): void`
+
+Logs errors (always shown).
+
+##### `isDebugEnabled(): boolean`
+
+Returns `true` if debug mode is enabled (development mode).
+
+## Implementation Details
+
+The service uses Angular's `isDevMode()` function to automatically detect the build mode:
+
+```typescript
+import { isDevMode } from '@angular/core';
+
+@Injectable({ providedIn: 'root' })
+export class LoggerService {
+  private debugMode = isDevMode();
+  
+  debug(context: string, message: string, data?: any) {
+    if (this.debugMode) {
+      console.log(`[HTTP-MGR DEBUG] ${context}: ${message}`, data);
+    }
+  }
+  // ... other methods
+}
+```
+
+This means:
+- No configuration needed from consuming apps
+- Automatic behavior based on build type
+- Zero runtime overhead in production (debug/info checks are false)
+
+## Related Documentation
+
+- [`HTTP Manager README`](HTTP_MANAGER_README.md)
+- [`WebSocket Manager README`](WS_MANAGER_README.md)
+- [`Architecture`](ARCHITECTURE.md)