@jeanharo98/typed-storage 0.1.3 → 0.1.5

package/README.md

@@ -174,10 +174,45 @@ const appStorage = createStorage(schema, options);
 | `sync` | `boolean` | `false` | Sync values across browser tabs via `StorageEvent` |
 | `version` | `number` | — | Current schema version — required for migrations |
 | `migrations` | `Record<number, (data) => data>` | — | Migration functions per version |
+| `compress` | `boolean` | `false` | Compresses data with LZ-string before storing |
 | `encrypt` | `boolean` | `false` | Shows a security warning — see note below |
 
 ---
 
+## 📦 Compression
+
+For large or repetitive data (lists, history, complex objects), enable compression to reduce the space used in `localStorage`:
+
+```typescript
+const appStorage = createStorage({
+    cart: { items: [] }
+}, {
+    prefix: 'shop',
+    compress: true
+});
+
+appStorage.cart.set({ items: [...manyProducts] });
+// Data is compressed with LZ-string before saving
+// and decompressed automatically when read
+```
+
+### When to use it
+
+```
+✅ Useful for:
+   - Large lists (shopping carts, history)
+   - Repetitive JSON structures
+   - Data approaching localStorage's ~5MB limit
+
+❌ Not needed for:
+   - Small values like theme, language, fontSize
+   - The compression overhead isn't worth it for tiny data
+```
+
+Compression only runs when `compress: true` is explicitly set — there's zero overhead for the default use case.
+
+---
+
 ## 🔔 onChange
 
 Subscribe to changes on any key:
@@ -297,6 +332,7 @@ Creates a storage object from a schema. Returns a `StorageResult<T>` with one `S
 |---------|-------------|
 | [@jeanharo98/typed-storage-angular](https://github.com/JeanHaro/typed-storage-angular) | Angular wrapper with native Signals |
 | [@jeanharo98/typed-storage-react](https://github.com/JeanHaro/typed-storage-react) | React wrapper with useStorage() hook |
+| [typed-storage-devtools](https://github.com/JeanHaro/typed-storage-devtools) | Chrome DevTools extension for real-time inspection |
 
 ---
 

package/dist/create-storage.js

@@ -1,11 +1,22 @@
 import { createStorageSignal } from './storage-signal.js';
 import { applyMigrations } from './migrations.js';
+function registerPrefix(prefix, sto) {
+    const registryKey = '__typed-storage__';
+    const existing = sto.getItem(registryKey);
+    const prefixes = existing ? JSON.parse(existing) : [];
+    if (prefix && !prefixes.includes(prefix)) {
+        prefixes.push(prefix);
+        sto.setItem(registryKey, JSON.stringify(prefixes));
+    }
+}
 export function createStorage(schema, options) {
     if (options?.version && options.migrations) {
         const sto = options.storage === 'session' ? sessionStorage : localStorage;
         const prefix = options.prefix ?? '';
         applyMigrations(prefix, options.version, options.migrations, sto);
     }
+    const sto = options?.storage === 'session' ? sessionStorage : localStorage;
+    registerPrefix(options?.prefix ?? '', sto);
     if (options?.encrypt) {
         console.warn(`
 ⚠️  typed-storage: la opción encrypt está activada.

package/dist/storage-signal.js

@@ -1,3 +1,4 @@
+import LZString from 'lz-string';
 import { MemoryStorage } from "./memory-storage.js";
 function safeParseJSON(value, fallback) {
     if (!value)
@@ -31,7 +32,10 @@ export function createStorageSignal(key, initialValue, options) {
     if (options?.prefix) {
         key = `${options.prefix}:${key}`;
     }
-    const savedData = sto.getItem(key);
+    const rawData = sto.getItem(key);
+    const savedData = options?.compress && rawData
+        ? LZString.decompress(rawData)
+        : rawData;
     let currentValue;
     const listeners = [];
     function notify(value) {
@@ -60,7 +64,10 @@ export function createStorageSignal(key, initialValue, options) {
                     notify(initialValue);
                     return currentValue = initialValue;
                 }
-                const item = safeParseJSON(event.newValue, initialValue);
+                const rawNewValue = options?.compress
+                    ? LZString.decompress(event.newValue)
+                    : event.newValue;
+                const item = safeParseJSON(rawNewValue, initialValue);
                 notify(item.value);
                 return currentValue = item.value;
             }
@@ -69,15 +76,23 @@ export function createStorageSignal(key, initialValue, options) {
     signalBase.set = function (newValue) {
         currentValue = newValue;
         notify(currentValue);
-        sto.setItem(key, JSON.stringify({
+        const dataToStore = JSON.stringify({
             value: newValue,
             expiresAt: options?.ttl ? Date.now() + options.ttl : undefined
-        }));
+        });
+        const finalData = options?.compress
+            ? LZString.compress(dataToStore)
+            : dataToStore;
+        sto.setItem(key, finalData);
     };
     signalBase.reset = function () {
         currentValue = initialValue;
         notify(currentValue);
-        sto.setItem(key, JSON.stringify(initialValue));
+        const dataToStore = JSON.stringify(initialValue);
+        const finalData = options?.compress
+            ? LZString.compress(dataToStore)
+            : dataToStore;
+        sto.setItem(key, finalData);
     };
     signalBase.has = function () {
         return !!sto.getItem(key);

package/dist/types.d.ts

@@ -6,6 +6,7 @@ export interface StorageSignalOptions {
     encrypt?: boolean;
     version?: number;
     migrations?: Record<number, (data: any) => any>;
+    compress?: boolean;
 }
 export interface StorageSignal<T> {
     (): T;

package/index.html

@@ -7,35 +7,28 @@
     <script type="module">
         import { createStorage } from './dist/index.js';
 
-        // Simula datos viejos en localStorage (schema v1)
-        localStorage.setItem('app:theme', '"dark"');
-        localStorage.setItem('app:fontSize', '16');
-        localStorage.setItem('app__version__', '1');
-
-        // Crea el storage con schema v2 y migración
-        const appStorage = createStorage({
-            theme: 'dark',
-            preferences: {
-                fontSize: 16,
-                language: 'es'
-            }
+        const compressedStorage = createStorage({
+            bigData: { items: [] }
         }, {
-            prefix: 'app',
-            version: 2,
-            migrations: {
-                1: (oldData) => ({
-                    theme: oldData.theme,
-                    preferences: {
-                        fontSize: oldData.fontSize,
-                        language: 'es'
-                    }
-                })
-            }
+            prefix: 'compressed',
+            compress: true
         });
 
-        console.log('theme:', appStorage.theme());
-        console.log('preferences:', appStorage.preferences());
-        console.log('version en localStorage:', localStorage.getItem('app__version__'));
+        // Genera datos grandes para probar
+        const bigArray = Array.from({ length: 100 }, (_, i) => ({
+            id: i,
+            name: `Item ${i}`,
+            description: 'Lorem ipsum dolor sit amet consectetur'
+        }));
+
+        compressedStorage.bigData.set({ items: bigArray });
+
+        console.log('Valor leído:', compressedStorage.bigData());
+        console.log('Tamaño en localStorage:', localStorage.getItem('compressed:bigData')?.length, 'caracteres');
+
+        // Compara con la versión sin comprimir
+        const uncompressedSize = JSON.stringify({ value: { items: bigArray } }).length;
+        console.log('Tamaño sin comprimir sería:', uncompressedSize, 'caracteres');
     </script>
 </body>
 </html>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jeanharo98/typed-storage",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Type-safe localStorage with reactive signals",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -19,6 +19,7 @@
     "jsdom": "^29.1.1",
     "ts-node": "^10.9.2",
     "typescript": "^6.0.3",
+    "vite": "^8.0.16",
     "vitest": "^4.1.8"
   },
   "repository": {
@@ -29,10 +30,14 @@
   "bugs": {
     "url": "https://github.com/JeanHaro/typed-storage/issues"
   },
+  "dependencies": {
+    "lz-string": "^1.5.0"
+  },
   "scripts": {
     "dev": "ts-node src/index.ts",
     "build": "tsc",
     "test": "vitest",
-    "test:coverage": "vitest --coverage"
+    "test:coverage": "vitest --coverage",
+    "serve": "vite"
   }
 }

package/src/create-storage.ts

@@ -7,10 +7,25 @@ import { createStorageSignal } from './storage-signal.js';
 // Migraciones
 import { applyMigrations } from './migrations.js';
 
+function registerPrefix (
+    prefix: string,
+    sto: Storage
+): void {
+    const registryKey = '__typed-storage__';
+    const existing = sto.getItem(registryKey);
+    const prefixes: string[] = existing ? JSON.parse(existing) : [];
+
+    if ( prefix && !prefixes.includes(prefix) ) {
+        prefixes.push(prefix);
+        sto.setItem(registryKey, JSON.stringify(prefixes));
+    }
+}
+
 export function createStorage<T extends StorageSchema>(
     schema: T,
     options?: StorageSignalOptions
 ): StorageResult<T> {
+    // Migraciones
     if ( options?.version && options.migrations ) {
         const sto = options.storage === 'session' ? sessionStorage : localStorage;
         const prefix = options.prefix ?? '';
@@ -23,6 +38,10 @@ export function createStorage<T extends StorageSchema>(
         );
     }
 
+    // Registramos el prefix en localStorage
+    const sto = options?.storage === 'session' ? sessionStorage : localStorage;
+    registerPrefix(options?.prefix ?? '', sto);
+
     if ( options?.encrypt ) {
         console.warn(`
 ⚠️  typed-storage: la opción encrypt está activada.

package/src/storage-signal.test.ts

@@ -84,4 +84,38 @@ describe('onChange', () => {
         theme.reset();
         expect(callback).toHaveBeenCalledWith('dark');
     });
+});
+
+describe('compress option', () => {
+    beforeEach(() => localStorage.clear());
+
+    it('debe comprimir y descomprimir correctamente', () => {
+        const signal = createStorageSignal<{ items: any[] }>(
+            'data', 
+            { items: [] }, 
+            { compress: true }
+        );
+        const bigData = { 
+            items: Array.from({ length: 50 }, 
+            (_, i) => ({ id: i })) 
+        };
+        
+        signal.set(bigData);
+        
+        expect(signal()).toEqual(bigData);
+    });
+
+    it('el dato comprimido debe ocupar menos espacio que sin comprimir', () => {
+        const compressed = createStorageSignal('data1', '', { compress: true, prefix: 'c1' });
+        const uncompressed = createStorageSignal('data2', '', { prefix: 'c2' });
+        
+        const repetitive = 'a'.repeat(1000);
+        compressed.set(repetitive);
+        uncompressed.set(repetitive);
+        
+        const compressedSize = localStorage.getItem('c1:data1')!.length;
+        const uncompressedSize = localStorage.getItem('c2:data2')!.length;
+        
+        expect(compressedSize).toBeLessThan(uncompressedSize);
+    });
 });

package/src/storage-signal.ts

@@ -1,3 +1,5 @@
+import LZString from 'lz-string';
+
 // Tipos
 import { StorageSignal, StorageSignalOptions } from "./types.js";
 
@@ -33,7 +35,7 @@ function safeParseJSON<T>(value: string, fallback: T): StoredValue<T> {
     }
 } 
 
-// Obtenemos el valor del localStorage o SessionStorage, si sale error entonces se usará el MemoryStorage
+// Obtenemos el valor del localStorage o SessionStorage, sino MemoryStorage
 function getStorage(type: 'local' | 'session'): Storage | MemoryStorage {
     try {
         const sto = type === 'session' ? sessionStorage : localStorage;
@@ -63,7 +65,10 @@ export function createStorageSignal<T>(
         key = `${options.prefix}:${key}`;
     }
 
-    const savedData = sto.getItem(key);
+    const rawData = sto.getItem(key);
+    const savedData = options?.compress && rawData 
+                            ? LZString.decompress(rawData) 
+                            : rawData;
     let currentValue: T;
 
     const listeners: Array<(value: T) => void> = [];
@@ -101,7 +106,10 @@ export function createStorageSignal<T>(
                 } 
 
                 // Parseamos el nuevo valor
-                const item = safeParseJSON(event.newValue, initialValue);
+                const rawNewValue = options?.compress 
+                                        ? LZString.decompress(event.newValue)
+                                        : event.newValue;
+                const item = safeParseJSON(rawNewValue, initialValue);
 
                 notify(item.value as T);
                 return currentValue = item.value as T;
@@ -112,19 +120,29 @@ export function createStorageSignal<T>(
     signalBase.set = function ( newValue: T ): void {
         currentValue = newValue;
         notify(currentValue);
-        sto.setItem(
-            key, 
-            JSON.stringify({
-                value: newValue,
-                expiresAt: options?.ttl ? Date.now() + options.ttl : undefined
-            })
-        );
+        
+        const dataToStore = JSON.stringify({
+            value: newValue,
+            expiresAt: options?.ttl ? Date.now() + options.ttl : undefined
+        });
+
+        const finalData = options?.compress 
+                                ? LZString.compress(dataToStore) 
+                                : dataToStore;
+
+        sto.setItem( key, finalData );
     }
 
     signalBase.reset = function(): void {
         currentValue = initialValue;
         notify(currentValue);
-        sto.setItem(key, JSON.stringify(initialValue));
+        
+        const dataToStore = JSON.stringify(initialValue);
+        const finalData = options?.compress
+                                ? LZString.compress(dataToStore)
+                                : dataToStore;
+
+        sto.setItem(key, finalData);
     }
 
     signalBase.has = function(): boolean {

package/src/types.ts

@@ -7,6 +7,7 @@ export interface StorageSignalOptions {
     encrypt?: boolean;
     version?: number;
     migrations?: Record<number, ( data: any ) => any>;
+    compress?: boolean;
 }
 
 // Objeto reactivo con getter, setter y reset