@telperion/ng-pack 1.3.1 → 1.4.1

package/types/telperion-ng-pack-storage-signals.d.ts

@@ -1,13 +1,514 @@
 import { WritableSignal, Provider } from '@angular/core';
+import { ReactiveCookieStorageOptions } from '@telperion/reactive-storage';
 
+/**
+ * A specialized writable signal interface for browser storage that extends Angular's WritableSignal
+ * with storage-specific operations.
+ *
+ * @template T - The type of value stored in the storage signal
+ *
+ * @remarks
+ * StorageSignal combines Angular's signal reactivity with browser storage persistence.
+ * It supports standard signal operations (get, set, update) plus a delete operation to remove
+ * the stored value.
+ *
+ * The signal value is always `T | null | undefined` because:
+ * - `null` indicates the key exists but has no value
+ * - `undefined` indicates the key doesn't exist in storage
+ *
+ * @example
+ * ```typescript
+ * // Type-safe signal for user preferences
+ * const theme: StorageSignal<string> = localStorageSignal('settings', 'theme');
+ *
+ * // Read value (returns string | null | undefined)
+ * const currentTheme = theme();
+ *
+ * // Set new value
+ * theme.set('dark');
+ *
+ * // Update based on current value
+ * theme.update(current => current === 'dark' ? 'light' : 'dark');
+ *
+ * // Delete from storage
+ * theme.delete();
+ * ```
+ *
+ * @see {@link WritableSignal}
+ * @public
+ */
 interface StorageSignal<T> extends WritableSignal<T | null | undefined> {
+    /**
+     * Deletes the value from storage and updates the signal to undefined.
+     *
+     * @remarks
+     * This method removes the key-value pair from the underlying storage
+     * (localStorage, sessionStorage, or cookies) and updates the signal
+     * to reflect the deletion by setting its value to `undefined`.
+     *
+     * All components or effects subscribed to this signal will be notified
+     * of the change.
+     *
+     * @example
+     * ```typescript
+     * const userToken = localStorageSignal<string>('auth', 'token');
+     * userToken.set('abc123');
+     *
+     * // Later, on logout
+     * userToken.delete(); // Removes from storage, signal() returns undefined
+     * ```
+     */
     delete(): void;
 }
 
+/**
+ * Provides a ReactiveWebLocalStorage instance for dependency injection.
+ *
+ * @param appName - Optional application name for namespacing localStorage keys
+ * @returns An Angular provider configuration
+ *
+ * @remarks
+ * This provider creates a singleton ReactiveWebLocalStorage instance that can be injected
+ * throughout your application. All `localStorageSignal` calls will use this shared instance,
+ * ensuring consistent storage access and change detection.
+ *
+ * **Namespacing:**
+ * The `appName` parameter prefixes all localStorage keys to prevent conflicts:
+ * - With appName: `my-app:store:key`
+ * - Without appName: `store:key`
+ *
+ * **Singleton Pattern:**
+ * Only one instance is created per application, ensuring:
+ * - Consistent storage access across components
+ * - Efficient memory usage
+ * - Reliable cross-component synchronization
+ *
+ * @example
+ * ```typescript
+ * // app.config.ts
+ * import { ApplicationConfig } from '@angular/core';
+ * import { provideLocalStorage } from '@telperion/ng-pack/storage-signals';
+ *
+ * export const appConfig: ApplicationConfig = {
+ *   providers: [
+ *     provideLocalStorage('my-app'),
+ *     // ... other providers
+ *   ]
+ * };
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Without namespace (keys are not prefixed)
+ * export const appConfig: ApplicationConfig = {
+ *   providers: [
+ *     provideLocalStorage(),
+ *   ]
+ * };
+ * ```
+ *
+ * @public
+ */
 declare function provideLocalStorage(appName?: string): Provider;
+/**
+ * Creates a reactive signal connected to browser's localStorage.
+ *
+ * @template T - The type of value stored
+ * @param store - The storage namespace/store name
+ * @param key - The key within the store
+ * @returns A StorageSignal that reactively tracks the localStorage value
+ *
+ * @remarks
+ * This function creates an Angular signal that automatically syncs with localStorage.
+ * Any changes to the value (via `set`, `update`, or `delete`) are immediately persisted
+ * to localStorage and propagate to all components using the same signal.
+ *
+ * **Requirements:**
+ * Must call {@link provideLocalStorage} in application config before using this function.
+ *
+ * **Storage Key:**
+ * The actual localStorage key is formed as:
+ * - With app name: `appName:store:key`
+ * - Without app name: `store:key`
+ *
+ * **Type Safety:**
+ * Values are automatically serialized/deserialized as JSON:
+ * - Objects and arrays are preserved
+ * - Primitives (string, number, boolean) work correctly
+ * - Functions and undefined values are not supported
+ *
+ * **Cross-Component Sync:**
+ * All components using the same `store` and `key` share the same signal state.
+ * Changes in one component immediately reflect in others.
+ *
+ * @example
+ * ```typescript
+ * import { Component } from '@angular/core';
+ * import { localStorageSignal } from '@telperion/ng-pack/storage-signals';
+ *
+ * @Component({
+ *   selector: 'app-settings',
+ *   template: `
+ *     <div>
+ *       <p>Theme: {{ theme() }}</p>
+ *       <button (click)="theme.set('dark')">Dark</button>
+ *       <button (click)="theme.set('light')">Light</button>
+ *       <button (click)="theme.delete()">Reset</button>
+ *     </div>
+ *   `
+ * })
+ * export class SettingsComponent {
+ *   theme = localStorageSignal<string>('settings', 'theme');
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Complex types
+ * interface UserPreferences {
+ *   theme: 'light' | 'dark';
+ *   fontSize: number;
+ *   notifications: boolean;
+ * }
+ *
+ * const prefs = localStorageSignal<UserPreferences>('user', 'preferences');
+ *
+ * // Set entire object
+ * prefs.set({ theme: 'dark', fontSize: 14, notifications: true });
+ *
+ * // Update specific property
+ * prefs.update(current => ({
+ *   ...current,
+ *   theme: current?.theme === 'dark' ? 'light' : 'dark'
+ * }));
+ * ```
+ *
+ * @throws Error if {@link provideLocalStorage} was not called in application config
+ *
+ * @public
+ */
 declare function localStorageSignal<T>(store: string, key: string): StorageSignal<T>;
 
+/**
+ * Provides a ReactiveWebSessionStorage instance for dependency injection.
+ *
+ * @param appName - Optional application name for namespacing sessionStorage keys
+ * @returns An Angular provider configuration
+ *
+ * @remarks
+ * This provider creates a singleton ReactiveWebSessionStorage instance that can be injected
+ * throughout your application. All `sessionStorageSignal` calls will use this shared instance,
+ * ensuring consistent storage access and change detection.
+ *
+ * **SessionStorage vs LocalStorage:**
+ * - **sessionStorage**: Data persists only for the browser tab/window session (cleared on close)
+ * - **localStorage**: Data persists indefinitely until explicitly cleared
+ *
+ * **Use Cases for sessionStorage:**
+ * - Multi-step form wizards
+ * - Temporary authentication tokens
+ * - Per-session user preferences
+ * - Shopping cart for current session
+ * - Tab-specific state isolation
+ *
+ * **Namespacing:**
+ * The `appName` parameter prefixes all sessionStorage keys to prevent conflicts:
+ * - With appName: `my-app:store:key`
+ * - Without appName: `store:key`
+ *
+ * **Singleton Pattern:**
+ * Only one instance is created per application, ensuring:
+ * - Consistent storage access across components
+ * - Efficient memory usage
+ * - Reliable cross-component synchronization
+ *
+ * @example
+ * ```typescript
+ * // app.config.ts
+ * import { ApplicationConfig } from '@angular/core';
+ * import { provideSessionStorage } from '@telperion/ng-pack/storage-signals';
+ *
+ * export const appConfig: ApplicationConfig = {
+ *   providers: [
+ *     provideSessionStorage('my-app'),
+ *     // ... other providers
+ *   ]
+ * };
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Without namespace
+ * export const appConfig: ApplicationConfig = {
+ *   providers: [
+ *     provideSessionStorage(),
+ *   ]
+ * };
+ * ```
+ *
+ * @public
+ */
 declare function provideSessionStorage(appName?: string): Provider;
+/**
+ * Creates a reactive signal connected to browser's sessionStorage.
+ *
+ * @template T - The type of value stored
+ * @param store - The storage namespace/store name
+ * @param key - The key within the store
+ * @returns A StorageSignal that reactively tracks the sessionStorage value
+ *
+ * @remarks
+ * This function creates an Angular signal that automatically syncs with sessionStorage.
+ * Any changes to the value (via `set`, `update`, or `delete`) are immediately persisted
+ * to sessionStorage and propagate to all components using the same signal.
+ *
+ * **Session Lifecycle:**
+ * - Data is cleared when the browser tab/window is closed
+ * - Each tab has its own independent sessionStorage
+ * - Opening a page in a new tab creates fresh sessionStorage (even for same URL)
+ * - Refreshing the page preserves sessionStorage data
+ *
+ * **Requirements:**
+ * Must call {@link provideSessionStorage} in application config before using this function.
+ *
+ * **Storage Key:**
+ * The actual sessionStorage key is formed as:
+ * - With app name: `appName:store:key`
+ * - Without app name: `store:key`
+ *
+ * **Type Safety:**
+ * Values are automatically serialized/deserialized as JSON:
+ * - Objects and arrays are preserved
+ * - Primitives (string, number, boolean) work correctly
+ * - Functions and undefined values are not supported
+ *
+ * **Cross-Component Sync:**
+ * All components in the same tab using the same `store` and `key` share the same signal state.
+ * Changes in one component immediately reflect in others within the same tab.
+ * Different tabs do NOT share sessionStorage.
+ *
+ * @example
+ * ```typescript
+ * import { Component } from '@angular/core';
+ * import { sessionStorageSignal } from '@telperion/ng-pack/storage-signals';
+ *
+ * @Component({
+ *   selector: 'app-wizard',
+ *   template: `
+ *     <div>
+ *       <p>Current Step: {{ currentStep() }}</p>
+ *       <button (click)="nextStep()">Next</button>
+ *       <button (click)="currentStep.delete()">Reset</button>
+ *     </div>
+ *   `
+ * })
+ * export class WizardComponent {
+ *   currentStep = sessionStorageSignal<number>('wizard', 'step');
+ *
+ *   nextStep() {
+ *     this.currentStep.update(step => (step ?? 0) + 1);
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Form data that shouldn't persist across sessions
+ * interface FormData {
+ *   email: string;
+ *   message: string;
+ * }
+ *
+ * const formData = sessionStorageSignal<FormData>('contact', 'draft');
+ *
+ * // Auto-save form data (cleared when tab closes)
+ * formData.set({ email: 'user@example.com', message: 'Hello!' });
+ *
+ * // Update specific field
+ * formData.update(current => ({
+ *   ...current,
+ *   message: 'Updated message'
+ * }));
+ * ```
+ *
+ * @throws Error if {@link provideSessionStorage} was not called in application config
+ *
+ * @public
+ */
 declare function sessionStorageSignal<T>(store: string, key: string): StorageSignal<T>;
 
-export { localStorageSignal, provideLocalStorage, provideSessionStorage, sessionStorageSignal };
+/**
+ * Provides a CookieStorageProvider instance for dependency injection.
+ *
+ * @param appName - Optional application name for namespacing cookie keys
+ * @param options - Default cookie options applied to all cookie storage signals
+ * @returns An Angular provider configuration
+ *
+ * @remarks
+ * This provider creates a singleton CookieStorageProvider that manages all cookie storage
+ * instances in your application. All `cookieStorageSignal` calls will use this shared provider.
+ *
+ * **Cookie Namespacing:**
+ * The `appName` parameter prefixes all cookie names to prevent conflicts:
+ * - With appName: `my-app:store:key`
+ * - Without appName: `store:key`
+ *
+ * **Base Options:**
+ * The `options` parameter provides default cookie configuration for all signals.
+ * Individual signals can override these options when created.
+ *
+ * **Common Options:**
+ * - `path` - Cookie path (default: current path)
+ * - `domain` - Cookie domain (default: current domain)
+ * - `secure` - Require HTTPS (recommended for production)
+ * - `sameSite` - CSRF protection ('strict' | 'lax' | 'none')
+ * - `maxAge` - Expiry time in seconds
+ * - `expires` - Expiry as Date object
+ *
+ * **Instance Management:**
+ * The provider automatically deduplicates storage instances:
+ * - Signals with identical options share the same storage instance
+ * - All instances are linked for cross-instance synchronization
+ * - Memory-efficient for applications with many cookie signals
+ *
+ * @example
+ * ```typescript
+ * // app.config.ts
+ * import { ApplicationConfig } from '@angular/core';
+ * import { provideCookieStorage } from '@telperion/ng-pack/storage-signals';
+ *
+ * export const appConfig: ApplicationConfig = {
+ *   providers: [
+ *     provideCookieStorage('my-app', {
+ *       path: '/',
+ *       secure: true,
+ *       sameSite: 'strict',
+ *       maxAge: 86400 // 24 hours
+ *     }),
+ *   ]
+ * };
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Minimal configuration
+ * export const appConfig: ApplicationConfig = {
+ *   providers: [
+ *     provideCookieStorage('my-app'),
+ *   ]
+ * };
+ * ```
+ *
+ * @public
+ */
+declare function provideCookieStorage(appName?: string, options?: ReactiveCookieStorageOptions): Provider;
+/**
+ * Creates a reactive signal connected to browser cookies.
+ *
+ * @template T - The type of value stored
+ * @param store - The cookie namespace/store name
+ * @param key - The cookie key within the store
+ * @param options - Optional cookie-specific options that override provider defaults
+ * @returns A StorageSignal that reactively tracks the cookie value
+ *
+ * @remarks
+ * This function creates an Angular signal that automatically syncs with browser cookies.
+ * Any changes to the value (via `set`, `update`, or `delete`) are immediately written
+ * to cookies and propagate to all components using the same signal.
+ *
+ * **Requirements:**
+ * Must call {@link provideCookieStorage} in application config before using this function.
+ *
+ * **Cookie Name:**
+ * The actual cookie name is formed as:
+ * - With app name: `appName:store:key`
+ * - Without app name: `store:key`
+ *
+ * **Size Limitations:**
+ * Cookies have a ~4KB size limit. The underlying ReactiveCookieStorage enforces a 4000 byte
+ * limit and throws an error if exceeded. Use localStorage for larger data.
+ *
+ * **Options Merging:**
+ * Cookie options are merged in this order (later overrides earlier):
+ * 1. Provider base options (from `provideCookieStorage`)
+ * 2. Signal-specific options (from this function's `options` parameter)
+ *
+ * **Instance Deduplication:**
+ * Signals with identical merged options share the same underlying storage instance:
+ * ```typescript
+ * // These share the same storage instance
+ * const token1 = cookieStorageSignal('auth', 'token', { secure: true });
+ * const token2 = cookieStorageSignal('auth', 'token', { secure: true });
+ *
+ * // These use different instances (different options)
+ * const temp = cookieStorageSignal('auth', 'token', { maxAge: 300 });
+ * ```
+ *
+ * **Type Safety:**
+ * Values are automatically serialized/deserialized as JSON:
+ * - Objects and arrays are preserved
+ * - Primitives (string, number, boolean) work correctly
+ * - Functions and undefined values are not supported
+ *
+ * **Security Best Practices:**
+ * - Use `secure: true` in production (HTTPS only)
+ * - Use `sameSite: 'strict'` for CSRF protection
+ * - Set appropriate `maxAge` or `expires` for sensitive data
+ * - Never store sensitive data in cookies without encryption
+ *
+ * @example
+ * ```typescript
+ * import { Component } from '@angular/core';
+ * import { cookieStorageSignal } from '@telperion/ng-pack/storage-signals';
+ *
+ * @Component({
+ *   selector: 'app-auth',
+ *   template: `
+ *     <div>
+ *       <p>Token: {{ authToken() }}</p>
+ *       <button (click)="login()">Login</button>
+ *       <button (click)="logout()">Logout</button>
+ *     </div>
+ *   `
+ * })
+ * export class AuthComponent {
+ *   // Secure cookie with 1 hour expiry
+ *   authToken = cookieStorageSignal<string>('auth', 'token', {
+ *     secure: true,
+ *     sameSite: 'strict',
+ *     maxAge: 3600
+ *   });
+ *
+ *   login() {
+ *     this.authToken.set('abc123');
+ *   }
+ *
+ *   logout() {
+ *     this.authToken.delete();
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // User preferences with different cookie lifetimes
+ * const theme = cookieStorageSignal<string>('prefs', 'theme', {
+ *   maxAge: 31536000 // 1 year
+ * });
+ *
+ * const tempSetting = cookieStorageSignal<boolean>('prefs', 'banner-dismissed', {
+ *   maxAge: 86400 // 1 day
+ * });
+ *
+ * theme.set('dark');
+ * tempSetting.set(true);
+ * ```
+ *
+ * @throws Error if {@link provideCookieStorage} was not called in application config
+ * @throws Error if the serialized value exceeds 4000 bytes
+ *
+ * @public
+ */
+declare function cookieStorageSignal<T>(store: string, key: string, options?: ReactiveCookieStorageOptions): StorageSignal<unknown>;
+
+export { cookieStorageSignal, localStorageSignal, provideCookieStorage, provideLocalStorage, provideSessionStorage, sessionStorageSignal };