@jeanharo98/typed-storage 0.1.1 → 0.1.3

package/README.md

@@ -1,6 +1,6 @@
 # typed-storage
 
-Type-safe `localStorage` and `sessionStorage` with a signal-like API, TTL support, cross-tab sync, and automatic fallback to memory when storage is unavailable.
+Type-safe `localStorage` and `sessionStorage` with a signal-like API, TTL support, cross-tab sync, schema migrations, and automatic fallback to memory when storage is unavailable.
 
 ```typescript
 const appStorage = createStorage({
@@ -14,12 +14,15 @@ appStorage.theme.set('purple');  // ❌ TypeScript error at compile time
 console.log(appStorage.theme()); // 'light' — persisted across reloads
 ```
 
+---
+
 ## ✨ Features
 
 - **Type-safe** — TypeScript infers types from your schema automatically
 - **Signal-like API** — read with `signal()`, write with `signal.set(value)`
 - **TTL / expiration** — keys expire automatically after a defined time
 - **Cross-tab sync** — changes in one tab reflect in others via `StorageEvent`
+- **Schema migrations** — safely transform data when your schema changes
 - **Memory fallback** — works even when `localStorage` is unavailable (Safari private mode, quota exceeded)
 - **Prefix namespacing** — avoid key collisions across apps or modules
 - **sessionStorage support** — opt in per schema
@@ -68,68 +71,111 @@ appStorage.theme.has();                // true
 appStorage.theme.remove();
 appStorage.theme.has();                // false
 
+// Subscribe to changes
+appStorage.theme.onChange((newValue) => {
+    console.log('theme changed to:', newValue);
+});
+
 // Clear all keys in the schema
 appStorage.clear();
 ```
 
 ---
 
-## ⚙️ Options
+## 🔄 Schema Migrations
+
+When your schema changes between versions, migrations ensure users don't lose their data.
 
 ```typescript
-const appStorage = createStorage(schema, options);
-```
+// Version 1 — what users had stored:
+// localStorage['app:theme'] = '"dark"'
+// localStorage['app:fontSize'] = '16'
 
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `prefix` | `string` | — | Prepends `prefix:` to every key in localStorage |
-| `storage` | `'local' \| 'session'` | `'local'` | Use `sessionStorage` instead of `localStorage` |
-| `ttl` | `number` | — | Time to live in milliseconds — key expires after this time |
-| `sync` | `boolean` | `false` | Sync values across browser tabs via `StorageEvent` |
-| `encrypt` | `boolean` | `false` | Shows a security warning — see note below |
+// Version 2 — your new schema:
+const appStorage = createStorage({
+    theme: 'dark' as 'dark' | 'light',
+    preferences: {          // ← new nested object
+        fontSize: 16,
+        language: 'es'
+    }
+}, {
+    prefix: 'app',
+    version: 2,             // ← current schema version
+    migrations: {
+        1: (oldData) => ({  // ← transforms v1 data to v2
+            theme: oldData.theme,
+            preferences: {
+                fontSize: oldData.fontSize,  // moves fontSize inside preferences
+                language: 'es'              // adds new field with default
+            }
+        })
+    }
+});
 
-### Prefix
+// Old data is automatically migrated on first load
+console.log(appStorage.preferences()); // { fontSize: 16, language: 'es' }
+```
 
-```typescript
-const appStorage = createStorage(
-  { theme: 'dark' },
-  { prefix: 'myapp' }
-);
+### Chained migrations (v1 → v2 → v3)
 
-appStorage.theme.set('light');
-// Stored as: localStorage['myapp:theme'] = '"light"'
+```typescript
+createStorage(schema, {
+    prefix: 'app',
+    version: 3,
+    migrations: {
+        1: (data) => ({         // v1 → v2
+            theme: data.theme,
+            preferences: {
+                fontSize: data.fontSize,
+                language: 'es'
+            }
+        }),
+        2: (data) => ({         // v2 → v3
+            ...data,
+            preferences: {
+                ...data.preferences,
+                sidebarOpen: true  // adds new field in v3
+            }
+        })
+    }
+});
 ```
 
-### TTL
+### How migrations work
 
-```typescript
-const appStorage = createStorage(
-  { authToken: '' },
-  { ttl: 3600000 } // expires in 1 hour
-);
 ```
+1. On createStorage(), reads the saved version from localStorage
+   key: 'prefix__version__'
 
-### Cross-tab sync
+2. If no version saved → new install, saves current version and continues
 
-```typescript
-const appStorage = createStorage(
-  { theme: 'dark' },
-  { sync: true }
-);
+3. If saved version < current version:
+   → reads all current data from localStorage
+   → applies each migration in order (v1→v2, v2→v3, etc.)
+   → saves migrated data back to localStorage
+   → updates the version key
 
-// When another tab calls appStorage.theme.set('light'),
-// this tab updates automatically
+4. If saved version === current version → nothing to do
 ```
 
-### sessionStorage
+---
+
+## ⚙️ Options
 
 ```typescript
-const sessionData = createStorage(
-  { step: 1 },
-  { storage: 'session' }
-);
+const appStorage = createStorage(schema, options);
 ```
 
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `prefix` | `string` | — | Prepends `prefix:` to every key in localStorage |
+| `storage` | `'local' \| 'session'` | `'local'` | Use `sessionStorage` instead of `localStorage` |
+| `ttl` | `number` | — | Time to live in milliseconds — key expires after this time |
+| `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 |
+| `encrypt` | `boolean` | `false` | Shows a security warning — see note below |
+
 ---
 
 ## 🔔 onChange
@@ -175,71 +221,45 @@ typed-storage is designed for:
 
 ## 🅰️ Usage with Angular
 
-typed-storage is framework-agnostic. For Angular, wrap it in a service with native Signals:
+```bash
+pnpm add @jeanharo98/typed-storage @jeanharo98/typed-storage-angular
+```
 
-```typescript
-import { Service, signal } from '@angular/core';
-import { createStorage } from 'typed-storage';
+See [@jeanharo98/typed-storage-angular](https://github.com/JeanHaro/typed-storage-angular) for full documentation.
 
+```typescript
 @Service()
 export class StorageService {
-  private _storage = createStorage({
-    theme: 'dark' as 'dark' | 'light',
-    language: 'es' as 'es' | 'en',
-    fontSize: 16,
-  }, {
-    prefix: 'app',
-    sync: true,
-  });
-
-  // Native Angular Signals — reactive in any scenario including zoneless
-  theme = signal(this._storage.theme());
-  language = signal(this._storage.language());
-  fontSize = signal(this._storage.fontSize());
-
-  setTheme(value: 'dark' | 'light') {
-    this._storage.theme.set(value);
-    this.theme.set(value);
-  }
-
-  setLanguage(value: 'es' | 'en') {
-    this._storage.language.set(value);
-    this.language.set(value);
-  }
+    storage: AppStorage;
+
+    constructor() {
+        const ts = new TypedStorageService();
+        this.storage = ts.initialize({
+            theme: 'dark' as 'dark' | 'light',
+            language: 'es' as 'es' | 'en',
+        }, { prefix: 'app', sync: true }) as unknown as AppStorage;
+    }
 }
 ```
 
-```html
-<p>Theme: {{ storageService.theme() }}</p>
-<button (click)="storageService.setTheme('light')">Light</button>
-<button (click)="storageService.setTheme('dark')">Dark</button>
-```
-
 ---
 
 ## ⚛️ Usage with React
 
-```typescript
-import { useState, useEffect } from 'react';
-import { createStorage } from 'typed-storage';
-
-const appStorage = createStorage({
-  theme: 'dark' as 'dark' | 'light',
-});
-
-export function useTheme() {
-  const [theme, setThemeState] = useState(appStorage.theme());
+```bash
+pnpm add @jeanharo98/typed-storage @jeanharo98/typed-storage-react
+```
 
-  useEffect(() => {
-    appStorage.theme.onChange(setThemeState);
-  }, []);
+See [@jeanharo98/typed-storage-react](https://github.com/JeanHaro/typed-storage-react) for full documentation.
 
-  const setTheme = (value: 'dark' | 'light') => {
-    appStorage.theme.set(value);
-    setThemeState(value);
-  };
+```typescript
+function App() {
+    const storage = useStorage({
+        theme: 'dark' as 'dark' | 'light',
+        language: 'es' as 'es' | 'en',
+    }, { prefix: 'app', sync: true });
 
-  return { theme, setTheme };
+    return <p>Theme: {storage.theme}</p>;
 }
 ```
 
@@ -271,6 +291,15 @@ Creates a storage object from a schema. Returns a `StorageResult<T>` with one `S
 
 ---
 
+## 🔗 Related packages
+
+| Package | Description |
+|---------|-------------|
+| [@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 |
+
+---
+
 ## 📄 License
 
 MIT

package/dist/create-storage.js

@@ -1,5 +1,11 @@
 import { createStorageSignal } from './storage-signal.js';
+import { applyMigrations } from './migrations.js';
 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);
+    }
     if (options?.encrypt) {
         console.warn(`
 ⚠️  typed-storage: la opción encrypt está activada.

package/dist/migrations.d.ts

@@ -0,0 +1 @@
+export declare function applyMigrations(prefix: string, currentVersion: number, migrations: Record<number, (data: any) => any>, storage: Storage): void;

package/dist/migrations.js

@@ -0,0 +1,34 @@
+export function applyMigrations(prefix, currentVersion, migrations, storage) {
+    const versionKey = `${prefix}__version__`;
+    const savedVersion = storage.getItem(versionKey);
+    if (!savedVersion) {
+        storage.setItem(versionKey, String(currentVersion));
+        return;
+    }
+    let version = parseInt(savedVersion);
+    if (version >= currentVersion)
+        return;
+    const currentData = {};
+    for (let i = 0; i < storage.length; i++) {
+        const key = storage.key(i);
+        if (key && key.startsWith(prefix) && key !== versionKey) {
+            const value = storage.getItem(key);
+            if (value) {
+                const cleanKey = key.replace(`${prefix}:`, '');
+                currentData[cleanKey] = JSON.parse(value);
+            }
+        }
+    }
+    while (version < currentVersion) {
+        const migration = migrations[version];
+        if (migration) {
+            const migrated = migration(currentData);
+            Object.assign(currentData, migrated);
+        }
+        version++;
+    }
+    for (const [key, value] of Object.entries(currentData)) {
+        storage.setItem(`${prefix}:${key}`, JSON.stringify(value));
+    }
+    storage.setItem(versionKey, String(currentVersion));
+}

package/dist/types.d.ts

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

package/index.html

@@ -7,55 +7,35 @@
     <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',
-            fontSize: 16,
-            sidebarOpen: true,
-        }, { 
-            prefix: 'myapp',
-            ttl: 5000,       // expira en 5 segundos — para probar
-            sync: true
+            preferences: {
+                fontSize: 16,
+                language: 'es'
+            }
+        }, {
+            prefix: 'app',
+            version: 2,
+            migrations: {
+                1: (oldData) => ({
+                    theme: oldData.theme,
+                    preferences: {
+                        fontSize: oldData.fontSize,
+                        language: 'es'
+                    }
+                })
+            }
         });
 
-        // Prueba 1 — valores iniciales
         console.log('theme:', appStorage.theme());
-        console.log('fontSize:', appStorage.fontSize());
-
-        // Prueba 2 — set
-        appStorage.theme.set('light');
-        console.log('theme después de set:', appStorage.theme());
-
-        // Prueba 3 — reset
-        appStorage.theme.reset();
-        console.log('theme después de reset:', appStorage.theme());
-
-        // Prueba 4 — clear
-        appStorage.clear();
-        console.log('theme después de clear:', appStorage.theme());
-
-        // Prueba 5 — warning encrypt
-        const sensitiveStorage = createStorage({
-            token: '',
-        }, { encrypt: true });
-
-        // Prueba has()
-        console.log('¿tiene theme?', appStorage.theme.has());
-
-        // Prueba onChange()
-        appStorage.theme.onChange((newValue) => {
-            console.log('theme cambió a:', newValue);
-        });
-
-        // Prueba set — debería disparar onChange
-        appStorage.theme.set('light');
-        appStorage.theme.set('dark');
-
-        // Prueba reset — debería disparar onChange
-        appStorage.theme.reset();
-
-        // Prueba remove — debería disparar onChange
-        appStorage.theme.remove();
-        console.log('¿tiene theme después de remove?', appStorage.theme.has());
+        console.log('preferences:', appStorage.preferences());
+        console.log('version en localStorage:', localStorage.getItem('app__version__'));
     </script>
 </body>
 </html>

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@jeanharo98/typed-storage",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Type-safe localStorage with reactive signals",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "keywords": [],
   "author": "",
-  "license": "ISC",
+  "license": "MIT",
   "devEngines": {
     "packageManager": {
       "name": "pnpm",

package/src/create-storage.ts

@@ -1,10 +1,28 @@
+// Types
 import { StorageSchema, StorageResult, StorageSignalOptions } from './types.js';
+
+// Storage Signal
 import { createStorageSignal } from './storage-signal.js';
 
+// Migraciones
+import { applyMigrations } from './migrations.js';
+
 export function createStorage<T extends StorageSchema>(
     schema: T,
     options?: StorageSignalOptions
 ): StorageResult<T> {
+    if ( options?.version && options.migrations ) {
+        const sto = options.storage === 'session' ? sessionStorage : localStorage;
+        const prefix = options.prefix ?? '';
+
+        applyMigrations(
+            prefix,
+            options.version,
+            options.migrations,
+            sto
+        );
+    }
+
     if ( options?.encrypt ) {
         console.warn(`
 ⚠️  typed-storage: la opción encrypt está activada.

package/src/migrations.test.ts

@@ -0,0 +1,101 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { applyMigrations } from './migrations';
+
+describe('applyMigrations', () => {
+    beforeEach(() => {
+        localStorage.clear();
+    });
+
+    it('debe guardar la versión inicial si no hay datos previos', () => {
+        applyMigrations('app', 2, {
+            1: (oldData) => ({
+                theme: oldData.theme,
+                preferences: {
+                    fontSize: oldData.fontSize,
+                    language: 'es'
+                }
+            })
+        }, localStorage);
+        
+        const valor = localStorage.getItem('app__version__');
+
+        expect(valor).toBe('2');
+    });
+
+    it('no debe hacer nada si la versión es igual', () => {
+        // Guarda datos con versión 2 ya guardada
+        localStorage.setItem('app__version__', '2');
+        localStorage.setItem('app:theme', '"dark"');
+
+        applyMigrations('app', 2, {
+            1: (oldData) => ({
+                theme: 'light'
+            })
+        }, localStorage);
+
+        // El theme no debe haber cambiado - la migración no se ejecutó
+        expect(localStorage.getItem('app:theme')).toBe('"dark"');
+        expect(localStorage.getItem('app__version__')).toBe('2');
+    });
+
+    it('debe aplicar migración de v1 a v2', () => {
+        // Guarda datos v1 en localStorage
+        localStorage.setItem('app__version__', '1');
+        localStorage.setItem('app:theme', '"dark"');
+        localStorage.setItem('app:fontSize', '16');
+
+        applyMigrations('app', 2, {
+            1: (oldData) => ({
+                theme: oldData.theme,
+                preferences: {
+                    fontSize: oldData.fontSize,
+                    language: 'es'
+                }
+            })
+        }, localStorage);
+
+        // Verifica que los datos fueron migrados correctamente
+        expect(localStorage.getItem('app__version__')).toBe('2');
+        expect(localStorage.getItem('app:theme')).toBe('"dark"');
+
+        const preferences = JSON.parse(localStorage.getItem('app:preferences')!);
+        expect(preferences).toEqual({ fontSize: 16, language: 'es' });
+    });
+
+    it('debe aplicar migraciones encadenadas v1 -> v2 -> v3', () => {
+        // Guarda datos v1
+        localStorage.setItem('app__version__', '1');
+        localStorage.setItem('app:theme', '"dark"');
+        localStorage.setItem('app:fontSize', '16');
+
+        applyMigrations('app', 3, {
+            // v1 -> v2: mueve fontSize a preferences
+            1: (oldData) => ({
+                theme: oldData.theme,
+                preferences: {
+                    fontSize: oldData.fontSize,
+                    language: 'es'
+                }
+            }),
+            // v2 -> v3: añade sidebarOpen a preferences
+            2: (oldData) => ({
+                ...oldData,
+                preferences: {
+                    ...oldData.preferences,
+                    sidebarOpen: true
+                }
+            })
+        }, localStorage);
+
+        // Verifica versión final
+        expect(localStorage.getItem('app__version__')).toBe('3');
+
+        // Verifica datos finales
+        const preferences = JSON.parse(localStorage.getItem('app:preferences')!);
+        expect(preferences).toEqual({
+            fontSize: 16,
+            language: 'es',
+            sidebarOpen: true
+        });
+    });
+})

package/src/migrations.ts

@@ -0,0 +1,60 @@
+export function applyMigrations(
+    prefix: string,
+    currentVersion: number,
+    migrations: Record<number, ( data: any ) => any>,
+    storage: Storage
+): void {
+    const versionKey = `${prefix}__version__`;
+    const savedVersion = storage.getItem(versionKey);
+
+    // Si no hay versión, colocamos datos nuevos, guardamos versión actual y salimos
+    if ( !savedVersion ) {
+        storage.setItem(versionKey, String(currentVersion));
+        return;
+    }
+
+    let version = parseInt(savedVersion);
+
+    // Si ya esta en la versión actual, no hacemos nada
+    if ( version >= currentVersion ) return;
+
+    // Leemos todos los datos actuales
+    const currentData: any = {};
+
+    // Iteramos las keys del storage que empiecen con el prefix
+    for ( let i = 0; i < storage.length; i++ ) {
+        const key = storage.key(i);
+
+        if (key && key.startsWith(prefix) && key !== versionKey ) {
+            const value = storage.getItem(key);
+
+            if ( value ) {
+                // quitamos el prefix para obtener el nombre real de la key
+                const cleanKey = key.replace(`${prefix}:`, '');
+                currentData[cleanKey] = JSON.parse(value);
+            }
+        }
+    }
+
+    // Aplica migraciones en orden
+    while ( version < currentVersion ) {
+        const migration = migrations[version];
+
+        if ( migration ) {
+            const migrated = migration(currentData);
+
+            // Actualizamos currentData con los datos migrados
+            Object.assign(currentData, migrated);
+        }
+
+        version++;
+    }
+
+    // Guardamos los datos migrados
+    for ( const [key, value] of Object.entries(currentData) ) {
+        storage.setItem(`${prefix}:${key}`, JSON.stringify(value));
+    }
+
+    // Actualizamos la versión
+    storage.setItem(versionKey, String(currentVersion));
+}

package/src/types.ts

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