@angular-libs/signal-storage 0.0.1-beta.0

package/README.md

@@ -0,0 +1,67 @@
+# @angular-libs/signal-storage
+
+A simple and robust Angular library for managing state using Angular Signals with built-in persistence to `localStorage` and `sessionStorage`.
+
+## Installation
+
+Install the library using npm:
+
+```bash
+npm install @angular-libs/signal-storage
+```
+
+## Features
+
+- **Angular Signals Integration**: Seamlessly syncs your storage state with Angular Signals.
+- **Persistent Storage**: Automatically saves to `localStorage` or `sessionStorage`.
+- **Type-safe**: Built with TypeScript to ensure type safety for your stored data.
+- **Lightweight**: Zero external dependencies other than Angular.
+
+## Usage
+
+Here is a basic example of how to use `@angular-libs/signal-storage` in your Angular components or services.
+
+```typescript
+import { Component, effect, inject } from '@angular/core';
+import { SignalStorageService } from '@angular-libs/signal-storage';
+
+// Define your storage state structure using an interface
+interface AppStorage {
+  appTheme: 'light' | 'dark';
+}
+
+@Component({
+  selector: 'app-root',
+  standalone: true,
+  template: `
+    <div>
+      <p>Current Theme: {{ theme() }}</p>
+      <button (click)="toggleTheme()">Toggle Theme</button>
+    </div>
+  `,
+})
+export class AppComponent {
+  private storage = inject(SignalStorageService<AppStorage>);
+
+  // Initialize storage signal with a key and default value
+  theme = this.storage.getSignal('appTheme', 'light');
+
+  constructor() {
+    effect(() => {
+      console.log('Theme changed to:', this.theme());
+    });
+  }
+
+  toggleTheme() {
+    // To update, use the storage service's set or update methods
+    this.storage.set('appTheme', this.theme() === 'light' ? 'dark' : 'light');
+
+    // Alternatively, using update:
+    // this.storage.update('appTheme', theme => theme === 'light' ? 'dark' : 'light');
+  }
+}
+```
+
+## License
+
+MIT

package/fesm2022/angular-libs-signal-storage.mjs

@@ -0,0 +1,111 @@
+import { signal } from '@angular/core';
+
+class SignalStorageService {
+    storage;
+    signals = new Map();
+    /**
+     * Create a new SignalStorageService instance
+     * @param storage The storage to use (localStorage or sessionStorage). Defaults to localStorage.
+     */
+    constructor(storage = localStorage) {
+        this.storage = storage;
+        if (typeof window !== 'undefined') {
+            window.addEventListener('storage', (event) => {
+                if (event.storageArea === this.storage &&
+                    event.key &&
+                    this.signals.has(event.key)) {
+                    try {
+                        const newValue = event.newValue ? JSON.parse(event.newValue) : null;
+                        this.signals.get(event.key).set(newValue);
+                    }
+                    catch {
+                        // Ignore parse errors from external changes
+                    }
+                }
+            });
+        }
+    }
+    get(key, defaultValue) {
+        const item = this.storage.getItem(key);
+        if (item === null) {
+            return defaultValue ?? null;
+        }
+        try {
+            return JSON.parse(item);
+        }
+        catch {
+            return defaultValue ?? null;
+        }
+    }
+    getSignal(key, defaultValue) {
+        if (!this.signals.has(key)) {
+            const initialValue = this.get(key, defaultValue);
+            this.signals.set(key, signal(initialValue));
+        }
+        return this.signals.get(key).asReadonly();
+    }
+    /**
+     * Set typed data in localStorage
+     * @param key The key to set
+     * @param value The value to store
+     */
+    set(key, value) {
+        try {
+            this.storage.setItem(key, JSON.stringify(value));
+        }
+        catch (e) {
+            console.error(`Error saving to storage for key "${String(key)}". Storage quota may be exceeded.`, e);
+        }
+        if (this.signals.has(key)) {
+            this.signals.get(key).set(value);
+        }
+    }
+    /**
+     * Update typed data based on current value using a callback
+     * @param key The key to update
+     * @param updateFn Callback function that receives the current value and returns the new value
+     */
+    update(key, updateFn) {
+        const currentValue = this.get(key);
+        const newValue = updateFn(currentValue);
+        this.set(key, newValue);
+    }
+    /**
+     * Remove an item from localStorage
+     * @param key The key to remove
+     */
+    remove(key) {
+        this.storage.removeItem(key);
+        if (this.signals.has(key)) {
+            this.signals.get(key).set(null);
+        }
+    }
+    /**
+     * Check if a key exists in localStorage
+     * @param key The key to check
+     * @returns true if the key exists, false otherwise
+     */
+    has(key) {
+        return this.storage.getItem(key) !== null;
+    }
+    /**
+     * Clear all localStorage
+     */
+    clear() {
+        this.storage.clear();
+        for (const sig of this.signals.values()) {
+            sig.set(null);
+        }
+    }
+}
+
+/*
+ * Public API Surface of signal-storage
+ */
+
+/**
+ * Generated bundle index. Do not edit.
+ */
+
+export { SignalStorageService };
+//# sourceMappingURL=angular-libs-signal-storage.mjs.map

package/fesm2022/angular-libs-signal-storage.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"angular-libs-signal-storage.mjs","sources":["../../../../projects/angular-libs/signal-storage/src/lib/signal-storage.ts","../../../../projects/angular-libs/signal-storage/src/public-api.ts","../../../../projects/angular-libs/signal-storage/src/angular-libs-signal-storage.ts"],"sourcesContent":["import { signal, WritableSignal, Signal } from '@angular/core';\n\nexport class SignalStorageService<T extends Record<string, any> = {}> {\n  private storage: Storage;\n  private signals = new Map<keyof T, WritableSignal<any>>();\n\n  /**\n   * Create a new SignalStorageService instance\n   * @param storage The storage to use (localStorage or sessionStorage). Defaults to localStorage.\n   */\n  constructor(storage: Storage = localStorage) {\n    this.storage = storage;\n    if (typeof window !== 'undefined') {\n      window.addEventListener('storage', (event: StorageEvent) => {\n        if (\n          event.storageArea === this.storage &&\n          event.key &&\n          this.signals.has(event.key as keyof T)\n        ) {\n          try {\n            const newValue = event.newValue ? JSON.parse(event.newValue) : null;\n            this.signals.get(event.key as keyof T)!.set(newValue);\n          } catch {\n            // Ignore parse errors from external changes\n          }\n        }\n      });\n    }\n  }\n  /**\n   * Get typed data from SignalStorageService\n   * @param key The key to retrieve\n   * @returns The typed data or null if not found\n   */\n  get<K extends keyof T>(key: K): T[K] | null;\n  /**\n   * Get typed data from SignalStorageService with a default value\n   * @param key The key to retrieve\n   * @param defaultValue The default value to return if key not found\n   * @returns The stored data or the default value\n   */\n  get<K extends keyof T>(key: K, defaultValue: T[K]): T[K];\n  get<K extends keyof T>(key: K, defaultValue?: T[K]): T[K] | null {\n    const item = this.storage.getItem(key as string);\n    if (item === null) {\n      return defaultValue ?? null;\n    }\n    try {\n      return JSON.parse(item) as T[K];\n    } catch {\n      return defaultValue ?? null;\n    }\n  }\n\n  /**\n   * Get a reactive Angular signal for a key\n   * @param key The key to retrieve\n   * @param defaultValue The default value to return if key not found\n   * @returns A read-only Signal containing the stored data\n   */\n  getSignal<K extends keyof T>(key: K): Signal<T[K] | null>;\n  getSignal<K extends keyof T>(key: K, defaultValue: T[K]): Signal<T[K]>;\n  getSignal<K extends keyof T>(key: K, defaultValue?: T[K]): Signal<any> {\n    if (!this.signals.has(key)) {\n      const initialValue = this.get(key, defaultValue as T[K]);\n      this.signals.set(key, signal(initialValue));\n    }\n    return this.signals.get(key)!.asReadonly();\n  }\n\n  /**\n   * Set typed data in localStorage\n   * @param key The key to set\n   * @param value The value to store\n   */\n  set<K extends keyof T>(key: K, value: T[K]): void {\n    try {\n      this.storage.setItem(key as string, JSON.stringify(value));\n    } catch (e) {\n      console.error(\n        `Error saving to storage for key \"${String(key)}\". Storage quota may be exceeded.`,\n        e,\n      );\n    }\n    if (this.signals.has(key)) {\n      this.signals.get(key)!.set(value);\n    }\n  }\n\n  /**\n   * Update typed data based on current value using a callback\n   * @param key The key to update\n   * @param updateFn Callback function that receives the current value and returns the new value\n   */\n  update<K extends keyof T>(key: K, updateFn: (currentValue: T[K] | null) => T[K]): void {\n    const currentValue = this.get(key);\n    const newValue = updateFn(currentValue);\n    this.set(key, newValue);\n  }\n\n  /**\n   * Remove an item from localStorage\n   * @param key The key to remove\n   */\n  remove<K extends keyof T>(key: K): void {\n    this.storage.removeItem(key as string);\n    if (this.signals.has(key)) {\n      this.signals.get(key)!.set(null);\n    }\n  }\n\n  /**\n   * Check if a key exists in localStorage\n   * @param key The key to check\n   * @returns true if the key exists, false otherwise\n   */\n  has<K extends keyof T>(key: K): boolean {\n    return this.storage.getItem(key as string) !== null;\n  }\n\n  /**\n   * Clear all localStorage\n   */\n  clear(): void {\n    this.storage.clear();\n    for (const sig of this.signals.values()) {\n      sig.set(null);\n    }\n  }\n}\n","/*\n * Public API Surface of signal-storage\n */\n\nexport * from './lib/signal-storage';\n","/**\n * Generated bundle index. Do not edit.\n */\n\nexport * from './public-api';\n"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@angular-libs/signal-storage",
+  "version": "0.0.1-beta.0",
+  "peerDependencies": {
+    "@angular/common": ">=18.0.0",
+    "@angular/core": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "tslib": "^2.3.0"
+  },
+  "sideEffects": false,
+  "module": "fesm2022/angular-libs-signal-storage.mjs",
+  "typings": "types/angular-libs-signal-storage.d.ts",
+  "exports": {
+    "./package.json": {
+      "default": "./package.json"
+    },
+    ".": {
+      "types": "./types/angular-libs-signal-storage.d.ts",
+      "default": "./fesm2022/angular-libs-signal-storage.mjs"
+    }
+  }
+}

package/types/angular-libs-signal-storage.d.ts

@@ -0,0 +1,61 @@
+import { Signal } from '@angular/core';
+
+declare class SignalStorageService<T extends Record<string, any> = {}> {
+    private storage;
+    private signals;
+    /**
+     * Create a new SignalStorageService instance
+     * @param storage The storage to use (localStorage or sessionStorage). Defaults to localStorage.
+     */
+    constructor(storage?: Storage);
+    /**
+     * Get typed data from SignalStorageService
+     * @param key The key to retrieve
+     * @returns The typed data or null if not found
+     */
+    get<K extends keyof T>(key: K): T[K] | null;
+    /**
+     * Get typed data from SignalStorageService with a default value
+     * @param key The key to retrieve
+     * @param defaultValue The default value to return if key not found
+     * @returns The stored data or the default value
+     */
+    get<K extends keyof T>(key: K, defaultValue: T[K]): T[K];
+    /**
+     * Get a reactive Angular signal for a key
+     * @param key The key to retrieve
+     * @param defaultValue The default value to return if key not found
+     * @returns A read-only Signal containing the stored data
+     */
+    getSignal<K extends keyof T>(key: K): Signal<T[K] | null>;
+    getSignal<K extends keyof T>(key: K, defaultValue: T[K]): Signal<T[K]>;
+    /**
+     * Set typed data in localStorage
+     * @param key The key to set
+     * @param value The value to store
+     */
+    set<K extends keyof T>(key: K, value: T[K]): void;
+    /**
+     * Update typed data based on current value using a callback
+     * @param key The key to update
+     * @param updateFn Callback function that receives the current value and returns the new value
+     */
+    update<K extends keyof T>(key: K, updateFn: (currentValue: T[K] | null) => T[K]): void;
+    /**
+     * Remove an item from localStorage
+     * @param key The key to remove
+     */
+    remove<K extends keyof T>(key: K): void;
+    /**
+     * Check if a key exists in localStorage
+     * @param key The key to check
+     * @returns true if the key exists, false otherwise
+     */
+    has<K extends keyof T>(key: K): boolean;
+    /**
+     * Clear all localStorage
+     */
+    clear(): void;
+}
+
+export { SignalStorageService };