@telperion/ng-pack 1.3.2 → 1.4.1

package/fesm2022/telperion-ng-pack-storage-signals.mjs

@@ -1,7 +1,52 @@
 import { InjectionToken, inject } from '@angular/core';
-import { ReactiveWebLocalStorage, ReactiveWebSessionStorage } from '@thalesrc/reactive-storage';
+import { ReactiveWebLocalStorage, ReactiveWebSessionStorage, ReactiveCookieStorage } from '@telperion/reactive-storage';
 import { toSignal } from '@angular/core/rxjs-interop';
 
+/**
+ * Creates a StorageSignal from a ReactiveStorage instance.
+ *
+ * @template T - The type of value stored
+ * @param storage - The ReactiveStorage instance (localStorage, sessionStorage, or cookie storage)
+ * @param store - The storage namespace/store name
+ * @param key - The key within the store
+ * @returns A StorageSignal that provides reactive access to the stored value
+ *
+ * @remarks
+ * This is a low-level factory function that bridges Angular signals with ReactiveStorage.
+ * Most applications should use the higher-level functions:
+ * - {@link localStorageSignal} for localStorage
+ * - {@link sessionStorageSignal} for sessionStorage
+ * - {@link cookieStorageSignal} for cookies
+ *
+ * The function:
+ * 1. Converts the ReactiveStorage Observable into an Angular signal using `toSignal`
+ * 2. Creates a Proxy that intercepts calls to add `set`, `update`, and `delete` methods
+ * 3. Ensures all storage operations propagate to both the underlying storage and the signal
+ *
+ * **Proxy Pattern:**
+ * The returned signal is a Proxy that:
+ * - Delegates reading to the underlying signal
+ * - Provides `set()` to write values
+ * - Provides `update()` for functional updates
+ * - Provides `delete()` to remove the value
+ *
+ * @example
+ * ```typescript
+ * // Typically used internally by specialized signal creators
+ * import { ReactiveWebLocalStorage } from '@telperion/reactive-storage';
+ *
+ * const storage = new ReactiveWebLocalStorage('my-app');
+ * const userSignal = storageSignal<User>(storage, 'users', 'current');
+ *
+ * userSignal.set({ id: 1, name: 'Alice' });
+ * console.log(userSignal()); // { id: 1, name: 'Alice' }
+ *
+ * userSignal.update(user => ({ ...user, name: 'Bob' }));
+ * userSignal.delete();
+ * ```
+ *
+ * @internal This is primarily for internal use. Use the specialized signal creators instead.
+ */
 function storageSignal(storage, store, key) {
     const source = toSignal(storage.get(store, key));
     function setter(value) {
@@ -34,33 +79,594 @@ function storageSignal(storage, store, key) {
     });
 }
 
+/**
+ * Injection token for the ReactiveWebLocalStorage singleton.
+ * @internal
+ */
 const LOCAL_STORAGE = new InjectionToken('Telperion Local Storage');
+/**
+ * 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
+ */
 function provideLocalStorage(appName) {
     return {
         provide: LOCAL_STORAGE,
         useValue: new ReactiveWebLocalStorage(appName)
     };
 }
+/**
+ * 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
+ */
 function localStorageSignal(store, key) {
     const storage = inject(LOCAL_STORAGE);
     return storageSignal(storage, store, key);
 }
 
+/**
+ * Injection token for the ReactiveWebSessionStorage singleton.
+ * @internal
+ */
 const SESSION_STORAGE = new InjectionToken('Telperion Session Storage');
+/**
+ * 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
+ */
 function provideSessionStorage(appName) {
     return {
         provide: SESSION_STORAGE,
         useValue: new ReactiveWebSessionStorage(appName)
     };
 }
+/**
+ * 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
+ */
 function sessionStorageSignal(store, key) {
     const storage = inject(SESSION_STORAGE);
     return storageSignal(storage, store, key);
 }
 
+var _a;
+/**
+ * Internal provider that manages ReactiveCookieStorage instances with different configurations.
+ *
+ * @remarks
+ * This class implements a registry pattern to ensure that cookie storages with identical
+ * configurations share the same underlying ReactiveCookieStorage instance. This is critical for:
+ * - Preventing duplicate cookie writes
+ * - Ensuring consistent change detection across components
+ * - Optimizing memory usage
+ *
+ * **Linker Pattern:**
+ * All instances created by this provider share a common linker (Symbol) to enable
+ * cross-instance synchronization even when using different option combinations.
+ *
+ * **Instance Deduplication:**
+ * Two `cookieStorageSignal` calls with the same options will reuse the same storage instance,
+ * preventing redundant cookie operations.
+ *
+ * @internal This class is not exported publicly
+ */
+class CookieStorageProvider {
+    appName;
+    baseOptions;
+    /**
+     * Valid cookie option keys that can be used to configure cookie storage.
+     * Filters out any invalid properties from being passed to cookie operations.
+     */
+    static #VALID_OPTIONS = ['path', 'domain', 'secure', 'sameSite', 'expires', 'maxAge'];
+    /**
+     * Shared linker symbol used to synchronize all cookie storage instances
+     * created by this provider, enabling cross-instance change notifications.
+     */
+    #linker = Symbol('ReactiveCookieStorage Linker');
+    /**
+     * Registry of ReactiveCookieStorage instances keyed by their configuration options.
+     * Ensures instances with identical options are reused.
+     */
+    #stores = new Map();
+    /**
+     * Creates a new CookieStorageProvider with base configuration.
+     *
+     * @param appName - Optional application name for namespacing cookie keys
+     * @param baseOptions - Default cookie options applied to all storage instances
+     */
+    constructor(appName, baseOptions = {}) {
+        this.appName = appName;
+        this.baseOptions = baseOptions;
+        const parsedOptions = this.#parseOptions(baseOptions);
+        this.#stores.set(parsedOptions, new ReactiveCookieStorage(appName, parsedOptions, this.#linker));
+    }
+    /**
+     * Gets or creates a ReactiveCookieStorage instance with the specified options.
+     *
+     * @param options - Cookie options to override base options
+     * @returns A ReactiveCookieStorage instance (reused if options match existing instance)
+     *
+     * @remarks
+     * This method implements option merging and instance deduplication:
+     * 1. Merges provided options with base options (provided options take precedence)
+     * 2. Checks if an instance with these exact options already exists
+     * 3. Returns existing instance if found, otherwise creates and caches a new one
+     *
+     * All instances share the same linker for cross-instance synchronization.
+     */
+    getStore(options = {}) {
+        const parsedOptions = this.#parseOptions({ ...this.baseOptions, ...options });
+        let existingKey = this.#getStoredOptions(parsedOptions);
+        if (!existingKey) {
+            this.#stores.set(parsedOptions, new ReactiveCookieStorage(this.appName, parsedOptions, this.#linker));
+            existingKey = parsedOptions;
+        }
+        return this.#stores.get(existingKey);
+    }
+    /**
+     * Filters cookie options to include only valid properties.
+     *
+     * @param options - Raw options object that may contain invalid properties
+     * @returns Filtered options containing only valid cookie configuration properties
+     */
+    #parseOptions(options) {
+        return Object.fromEntries(Object.entries(options).filter(([key]) => _a.#VALID_OPTIONS.includes(key)));
+    }
+    /**
+     * Searches the registry for an existing options object that matches the provided options.
+     *
+     * @param options - Cookie options to search for
+     * @returns The stored options object if found, undefined otherwise
+     *
+     * @remarks
+     * Two options objects are considered equal if all valid cookie properties have identical values.
+     */
+    #getStoredOptions(options) {
+        const stored = this.#stores.keys();
+        return stored.find(storedOpts => {
+            return _a.#VALID_OPTIONS.every(key => storedOpts[key] === options[key]);
+        });
+    }
+}
+_a = CookieStorageProvider;
+/**
+ * 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
+ */
+function provideCookieStorage(appName, options) {
+    return {
+        provide: CookieStorageProvider,
+        useValue: new CookieStorageProvider(appName, options)
+    };
+}
+/**
+ * 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
+ */
+function cookieStorageSignal(store, key, options) {
+    const provider = inject(CookieStorageProvider);
+    const storage = provider.getStore(options);
+    return storageSignal(storage, store, key);
+}
+
 /**
  * Generated bundle index. Do not edit.
  */
 
-export { localStorageSignal, provideLocalStorage, provideSessionStorage, sessionStorageSignal };
+export { cookieStorageSignal, localStorageSignal, provideCookieStorage, provideLocalStorage, provideSessionStorage, sessionStorageSignal };
 //# sourceMappingURL=telperion-ng-pack-storage-signals.mjs.map