@jeanharo98/typed-storage 0.1.5 → 0.1.6

package/README.md

@@ -160,7 +160,56 @@ createStorage(schema, {
 
 ---
 
-## ⚙️ Options
+## 🗄️ Heavy data with IndexedDB
+
+For large datasets that exceed `localStorage`'s ~5MB limit (file lists, extensive history, large collections), use `createHeavyStorage` — a separate async API backed by IndexedDB.
+
+```typescript
+import { createHeavyStorage } from 'typed-storage';
+
+const heavyStorage = createHeavyStorage({
+    documents: [] as Document[],
+    userPhotos: [] as Photo[]
+}, {
+    dbName: 'myapp-storage',
+    ttl: 86400000  // optional — same TTL support as the sync API
+});
+
+// All operations are async — IndexedDB is asynchronous by nature
+await heavyStorage.documents.set([...manyDocuments]);
+const docs = await heavyStorage.documents.get();
+await heavyStorage.documents.remove();
+
+heavyStorage.documents.onChange((newValue) => {
+    console.log('documents changed:', newValue);
+});
+
+await heavyStorage.clear();
+```
+
+### Why a separate API?
+
+`createStorage()` uses a synchronous Signal-like API by design — that's the core value of typed-storage. IndexedDB is asynchronous by nature, so mixing it into the same API would break that synchronous contract.
+
+```
+createStorage()       → sync, Signal-like, for UI preferences and small state
+createHeavyStorage()  → async, Promise-based, for large datasets
+```
+
+If you only need small values (theme, language, settings), stick with `createStorage()`. Use `createHeavyStorage()` only when you specifically need to store data beyond localStorage's size limits.
+
+### `HeavySignal<T>` API
+
+| Member | Description |
+|--------|-------------|
+| `signal.get()` | Returns a Promise with the current value |
+| `signal.set(value)` | Stores the value, returns a Promise |
+| `signal.remove()` | Deletes the value, returns a Promise |
+| `signal.onChange(cb)` | Subscribes to value changes (called synchronously after set/remove) |
+
+---
+
+
 
 ```typescript
 const appStorage = createStorage(schema, options);

package/dist/heavy-storage.d.ts

@@ -0,0 +1,19 @@
+interface HeavyStorageOptions {
+    dbName?: string;
+    ttl?: number;
+}
+interface HeavySignal<T> {
+    get(): Promise<T>;
+    set(value: T): Promise<void>;
+    remove(): Promise<void>;
+    onChange(callback: (value: T) => void): void;
+}
+export declare function createHeavySignal<T>(key: string, initialValue: T, options?: HeavyStorageOptions): HeavySignal<T>;
+type HeavyStorageSchema = Record<string, any>;
+type HeavyStorageResult<T extends HeavyStorageSchema> = {
+    [K in keyof T]: HeavySignal<T[K]>;
+} & {
+    clear(): Promise<void>;
+};
+export declare function createHeavyStorage<T extends HeavyStorageSchema>(schema: T, options?: HeavyStorageOptions): HeavyStorageResult<T>;
+export {};

package/dist/heavy-storage.js

@@ -0,0 +1,89 @@
+function openDB(dbName) {
+    return new Promise((resolve, reject) => {
+        const request = indexedDB.open(dbName, 1);
+        request.onupgradeneeded = (event) => {
+            const db = event.target.result;
+            if (!db.objectStoreNames.contains('storage')) {
+                db.createObjectStore('storage');
+            }
+        };
+        request.onsuccess = () => resolve(request.result);
+        request.onerror = () => reject(request.error);
+    });
+}
+function dbGet(db, key) {
+    return new Promise((resolve, reject) => {
+        const transaction = db.transaction('storage', 'readonly');
+        const store = transaction.objectStore('storage');
+        const request = store.get(key);
+        request.onsuccess = () => resolve(request.result);
+        request.onerror = () => reject(request.error);
+    });
+}
+function dbSet(db, key, value) {
+    return new Promise((resolve, reject) => {
+        const transaction = db.transaction('storage', 'readwrite');
+        const store = transaction.objectStore('storage');
+        const request = store.put(value, key);
+        request.onsuccess = () => resolve();
+        request.onerror = () => reject(request.error);
+    });
+}
+function dbDelete(db, key) {
+    return new Promise((resolve, reject) => {
+        const transaction = db.transaction('storage', 'readwrite');
+        const store = transaction.objectStore('storage');
+        const request = store.delete(key);
+        request.onsuccess = () => resolve();
+        request.onerror = () => reject(request.error);
+    });
+}
+export function createHeavySignal(key, initialValue, options) {
+    const dbName = options?.dbName ?? 'typed-storage-heavy';
+    const listeners = [];
+    function notify(value) {
+        listeners.forEach(cb => cb(value));
+    }
+    const signal = {};
+    signal.get = async function () {
+        const db = await openDB(dbName);
+        const stored = await dbGet(db, key);
+        if (stored === undefined)
+            return initialValue;
+        if (stored.expiresAt && Date.now() > stored.expiresAt) {
+            await dbDelete(db, key);
+            return initialValue;
+        }
+        return stored.value ?? initialValue;
+    };
+    signal.set = async function (value) {
+        const db = await openDB(dbName);
+        await dbSet(db, key, {
+            value,
+            expiresAt: options?.ttl ? Date.now() + options.ttl : undefined
+        });
+        notify(value);
+    };
+    signal.remove = async function () {
+        const db = await openDB(dbName);
+        await dbDelete(db, key);
+        notify(initialValue);
+    };
+    signal.onChange = function (callback) {
+        listeners.push(callback);
+    };
+    return signal;
+}
+export function createHeavyStorage(schema, options) {
+    const result = {};
+    const keys = Object.keys(schema);
+    for (const key of keys) {
+        result[key] = createHeavySignal(key, schema[key], options);
+    }
+    result.clear = async () => {
+        for (const key of keys) {
+            await result[key].remove();
+        }
+    };
+    return result;
+}

package/dist/index.d.ts

@@ -1,2 +1,3 @@
 export { createStorage } from './create-storage.js';
+export { createHeavyStorage } from './heavy-storage.js';
 export type { StorageSignal, StorageSchema, StorageResult, StorageSignalOptions } from './types.js';

package/dist/index.js

@@ -1 +1,2 @@
 export { createStorage } from './create-storage.js';
+export { createHeavyStorage } from './heavy-storage.js';

package/index.html

@@ -5,30 +5,41 @@
 </head>
 <body>
     <script type="module">
-        import { createStorage } from './dist/index.js';
+        import { createHeavyStorage } from './dist/index.js';
 
-        const compressedStorage = createStorage({
-            bigData: { items: [] }
+        const heavyStorage = createHeavyStorage({
+            documents: [],
+            userPhotos: []
         }, {
-            prefix: 'compressed',
-            compress: true
+            dbName: 'test-heavy-storage'
         });
 
-        // Genera datos grandes para probar
-        const bigArray = Array.from({ length: 100 }, (_, i) => ({
-            id: i,
-            name: `Item ${i}`,
-            description: 'Lorem ipsum dolor sit amet consectetur'
-        }));
+        async function test() {
+            // Set
+            await heavyStorage.documents.set([
+                { id: 1, name: 'Documento 1' },
+                { id: 2, name: 'Documento 2' }
+            ]);
+            console.log('✅ Documentos guardados');
 
-        compressedStorage.bigData.set({ items: bigArray });
+            // Get
+            const docs = await heavyStorage.documents.get();
+            console.log('📄 Documentos leídos:', docs);
 
-        console.log('Valor leído:', compressedStorage.bigData());
-        console.log('Tamaño en localStorage:', localStorage.getItem('compressed:bigData')?.length, 'caracteres');
+            // onChange
+            heavyStorage.documents.onChange((newValue) => {
+                console.log('🔔 documents cambió a:', newValue);
+            });
 
-        // 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');
+            await heavyStorage.documents.set([{ id: 3, name: 'Documento nuevo' }]);
+
+            // Remove
+            await heavyStorage.userPhotos.remove();
+            const photos = await heavyStorage.userPhotos.get();
+            console.log('🗑️ userPhotos después de remove:', photos);
+        }
+
+        test();
     </script>
 </body>
 </html>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jeanharo98/typed-storage",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "Type-safe localStorage with reactive signals",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -16,6 +16,7 @@
   },
   "devDependencies": {
     "@vitest/coverage-v8": "^4.1.8",
+    "fake-indexeddb": "^6.2.5",
     "jsdom": "^29.1.1",
     "ts-node": "^10.9.2",
     "typescript": "^6.0.3",

package/src/heavy-storage.test.ts

@@ -0,0 +1,99 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { createHeavyStorage } from './heavy-storage.js';
+
+describe('createHeavyStorage', () => {
+
+    it('debe retornar el initialValue si no hay datos guardados', async () => {
+        // crea heavyStorage con dbName único para este test
+        const heavyStorage = createHeavyStorage({
+            documents: [],
+            userPhotos: []
+        }, {
+            dbName: 'test-heavy-storage'
+        });
+
+        // verifica que get() retorna el initialValue
+        const result = await heavyStorage.documents.get();
+        expect(result).toEqual([]);
+    });
+
+    it('debe guardar y leer un valor con set/get', async () => {
+        // crea heavyStorage
+        const heavyStorage = createHeavyStorage({
+            documents: [] as any[]
+        }, {
+            dbName: 'test-db-2'
+        });
+
+
+        // llama set() con un valor
+        const newDocs = [{ id: 1, name: 'Doc 1' }];
+        await heavyStorage.documents.set(newDocs);
+
+        // verifica que get() retorna ese valor
+        const result = await heavyStorage.documents.get();
+        expect(result).toEqual(newDocs);
+    });
+
+    it('debe eliminar un valor con remove()', async () => {
+        // crea heavyStorage, set() un valor
+        const heavyStorage = createHeavyStorage({
+            documents: [] as any[]
+        }, {
+            dbName: 'test-db-3'
+        });
+        await heavyStorage.documents.set([{ id: 1, name: 'Doc 1' }]);
+
+        // llama remove()
+        await heavyStorage.documents.remove();
+
+        // verifica que get() retorna el initialValue
+        const result = await heavyStorage.documents.get();
+        expect(result).toEqual([]);
+    });
+
+    it('debe notificar a onChange cuando se llama set()', async () => {
+        // usa vi.fn() como callback
+        const heavyStorage = createHeavyStorage({
+            documents: [] as any[]
+        }, {
+            dbName: 'test-db-4'
+        });
+        const callback = vi.fn();
+
+        // registra onChange
+        heavyStorage.documents.onChange(callback);
+
+        // llama set()
+        const newDocs = [{ id: 1, name: 'Doc 1' }];
+        await heavyStorage.documents.set(newDocs);
+
+        // verifica que el callback fue llamado con el valor correcto
+        expect(callback).toHaveBeenCalledWith(newDocs);
+    });
+
+    it('clear() debe resetear todas las keys del schema', async () => {
+        // crea heavyStorage con 2 keys
+        const heavyStorage = createHeavyStorage({
+            documents: [] as any[],
+            userPhotos: [] as any[]
+        }, {
+            dbName: 'test-db-5'
+        });
+
+        // set() en ambas
+        await heavyStorage.documents.set([{ id: 1 }]);
+        await heavyStorage.userPhotos.set([{ url: 'photo.jpg' }]);
+
+        // llama clear()
+        await heavyStorage.clear();
+
+        // verifica que ambas vuelven a su initialValue
+        const docs = await heavyStorage.documents.get();
+        const photos = await heavyStorage.userPhotos.get();
+
+        expect(docs).toEqual([]);
+        expect(photos).toEqual([]);
+    });
+
+});

package/src/heavy-storage.ts

@@ -0,0 +1,146 @@
+// Abrir/crear la base de datos
+function openDB(dbName: string): Promise<IDBDatabase> {
+    return new Promise((resolve, reject) => {
+        const request = indexedDB.open(dbName, 1);
+
+        request.onupgradeneeded = (event) => {
+            const db = (event.target as IDBOpenDBRequest).result;
+            // Crea el "object store" — equivalente a una tabla
+            if (!db.objectStoreNames.contains('storage')) {
+                db.createObjectStore('storage');
+            }
+        };
+
+        request.onsuccess = () => resolve(request.result);
+        request.onerror = () => reject(request.error);
+    });
+}
+
+function dbGet(db: IDBDatabase, key: string): Promise<any> {
+    return new Promise((resolve, reject) => {
+        const transaction = db.transaction('storage', 'readonly');
+        const store = transaction.objectStore('storage');
+        const request = store.get(key);
+
+        request.onsuccess = () => resolve(request.result);
+        request.onerror = () => reject(request.error);
+    });
+}
+
+function dbSet(db: IDBDatabase, key: string, value: any): Promise<void> {
+    return new Promise((resolve, reject) => {
+        const transaction = db.transaction('storage', 'readwrite');
+        const store = transaction.objectStore('storage');
+        const request = store.put(value, key);
+
+        request.onsuccess = () => resolve();
+        request.onerror = () => reject(request.error);
+    });
+}
+
+function dbDelete(db: IDBDatabase, key: string): Promise<void> {
+    return new Promise((resolve, reject) => {
+        const transaction = db.transaction('storage', 'readwrite');
+        const store = transaction.objectStore('storage');
+        const request = store.delete(key);
+
+        request.onsuccess = () => resolve();
+        request.onerror = () => reject(request.error);
+    });
+}
+
+// ===========================================
+
+interface HeavyStorageOptions {
+    dbName?: string;
+    ttl?: number;
+}
+
+interface HeavySignal<T> {
+    get(): Promise<T>;
+    set(value: T): Promise<void>;
+    remove(): Promise<void>;
+    onChange(callback: (value: T) => void): void;
+}
+
+export function createHeavySignal<T>(
+    key: string,
+    initialValue: T,
+    options?: HeavyStorageOptions
+): HeavySignal<T> {
+    const dbName = options?.dbName ?? 'typed-storage-heavy';
+    const listeners: Array<(value: T) => void> = [];
+
+    function notify(value: T): void {
+        listeners.forEach(cb => cb(value));
+    }
+
+    const signal: any = {};
+
+    signal.get = async function(): Promise<T> {
+        const db = await openDB(dbName);
+        const stored = await dbGet(db, key);
+        
+        if (stored === undefined) return initialValue;
+
+        // Verifica TTL si existe
+        if (stored.expiresAt && Date.now() > stored.expiresAt) {
+            await dbDelete(db, key);
+            return initialValue;
+        }
+
+        return stored.value ?? initialValue;
+    };
+
+    signal.set = async function(value: T): Promise<void> {
+        const db = await openDB(dbName);
+        await dbSet(db, key, {
+            value,
+            expiresAt: options?.ttl ? Date.now() + options.ttl : undefined
+        });
+        notify(value);
+    };
+
+    signal.remove = async function(): Promise<void> {
+        const db = await openDB(dbName);
+        await dbDelete(db, key);
+        notify(initialValue);
+    };
+
+    signal.onChange = function(callback: (value: T) => void): void {
+        listeners.push(callback);
+    };
+
+    return signal as HeavySignal<T>;
+}
+
+// ===========================================
+// Iteramos el schema completo
+
+type HeavyStorageSchema = Record<string, any>;
+
+type HeavyStorageResult<T extends HeavyStorageSchema> = {
+    [K in keyof T]: HeavySignal<T[K]>;
+} & {
+    clear(): Promise<void>;
+};
+
+export function createHeavyStorage<T extends HeavyStorageSchema>(
+    schema: T,
+    options?: HeavyStorageOptions
+): HeavyStorageResult<T> {
+    const result: any = {};
+
+    const keys = Object.keys(schema);
+    for (const key of keys) {
+        result[key] = createHeavySignal(key, schema[key], options);
+    }
+
+    result.clear = async () => {
+        for (const key of keys) {
+            await result[key].remove();
+        }
+    };
+
+    return result as HeavyStorageResult<T>;
+}

package/src/index.ts

@@ -1,2 +1,8 @@
 export { createStorage } from './create-storage.js';
-export type { StorageSignal, StorageSchema, StorageResult, StorageSignalOptions } from './types.js';
+export { createHeavyStorage } from './heavy-storage.js';
+export type { 
+    StorageSignal, 
+    StorageSchema, 
+    StorageResult, 
+    StorageSignalOptions 
+} from './types.js';

package/vitest.config.ts

@@ -4,5 +4,6 @@ export default defineConfig({
     test: {
         environment: 'jsdom',
         globals: true,
+        setupFiles: ['./vitest.setup.ts']
     }
 });

package/vitest.setup.ts

@@ -0,0 +1 @@
+import 'fake-indexeddb/auto';