📐 @angular-helpers/storage

A premium, high-performance, and secure reactive storage system for Angular. It bridges a fast synchronous L1 memory Signal Cache with async L2 storage backends (Cache API, IndexedDB, Local/SessionStorage) with optional AES-GCM encryption, dynamic TOON compression, and surgical key-level reactive Entity management.

⚡ Quick Path

1. Import and Setup

import { injectStorageSignal, injectEntityStore } from '@angular-helpers/storage';

2. Basic Signal Storage (L1 + L2 Cache API)

// Synchronous L1 Signal, Native Cache API L2 in background
const userPref = injectStorageSignal('user-pref', 'light-mode', {
  storageType: 'cacheapi',
  serializer: 'json',
});

// Read value (automatically handles async loading states)
console.log(userPref().data); // 'light-mode'
console.log(userPref().loading); // true | false

// Reactive write - auto-persists to Cache API
userPref.set({ data: 'dark-mode', loading: false, error: null });

3. High-Performance Entity Store

interface Product {
  id: string;
  name: string;
  price: number;
}

const productStore = injectEntityStore<string, Product>({
  idKey: 'id',
  persistKey: 'products-cache',
  storageOptions: {
    storageType: 'indexeddb',
    serializer: 'toon', // Compresses payload up to 60%!
  },
});

// 1. Write-Once, Freeze-Once O(1) insertion
productStore.setOne({ id: 'P1', name: 'Laptop', price: 999 });

// 2. Read entities safely (frozen in runtime, compile-time ReadonlyMap)
const laptop = productStore.entities().get('P1');
// laptop.price = 1000; // ❌ Throws TypeError in runtime, compile error in TS!

// 3. Surgical Granular Reactivity
// This computed signal ONLY evaluates when product 'P1' changes.
// Updates to product 'P2' will NOT trigger re-evaluation!
const productSignal = productStore.entitySignal('P1');
const laptopName = computed(() => productSignal()?.name);

🔬 Under the Hood

| Core Feature | Technical Strategy | Cognitive Benefit | | :------------------------- | :----------------------------------------------- | :------------------------------------------------------------------------------------- | | Strategy Transport | Pluggable StorageTransport interface | MVP on main thread today, 100% transparent Shared Worker upgrade tomorrow. | | Native Cache API | Directly utilizes window.caches | Offloads heavy JSON/TOON parsing off the main thread natively via Response.json(). | | Write-Once Freeze-Once | Object.freeze applied only on set operations | Guaranteed immutability with near-zero read performance penalty. | | TOON Serializer | Pluggable token-based serializer | Compresses structured array payloads by 30-60%, bypassing standard 5MB storage limits. | | WebCrypto AES-GCM | Native asynchronous browser cryptography | Seamlessly encrypts data at rest with hardware-accelerated algorithms. |

🛠️ Verification Checklist

• [ ] Runtime immutability: Bypassing compile safety via (store.entities() as any).set(...) throws a runtime TypeError.
• [ ] Granular updates: Modifying entity A does not trigger change evaluation on components listening to entity B.
• [ ] Incognito boundaries: Safari private browsing fallback automatically protects active signals when database writes fail.