@esportsplus/web-storage 0.4.0 → 0.5.0

package/README.md

@@ -0,0 +1,248 @@
+# @esportsplus/web-storage
+
+Typed async storage with multiple backends, TTL, encryption, compression, subscriptions, and migrations.
+
+```typescript
+import storage, { DriverType } from '@esportsplus/web-storage';
+
+type UserData = { name: string; preferences: { theme: string } };
+
+let store = storage<UserData>({ name: 'app', version: 1 });
+
+await store.set('name', 'alice');
+await store.get('name'); // 'alice'
+```
+
+
+## Install
+
+```bash
+pnpm add @esportsplus/web-storage
+```
+
+
+## Drivers
+
+| Driver | Persistence | Compression | Use Case |
+|--------|------------|-------------|----------|
+| IndexedDB | Permanent | No | Default. Large data, no quota pressure |
+| localStorage | Permanent | Yes (LZ) | Small data, 5MB limit |
+| sessionStorage | Per-tab | Yes (LZ) | Tab-scoped state |
+| Memory | None | No | Testing, SSR, fallback |
+
+```typescript
+// IndexedDB (default)
+let store = storage<T>({ name: 'app', version: 1 });
+
+// localStorage
+let store = storage<T>({ driver: DriverType.LocalStorage, name: 'app', version: 1 });
+
+// sessionStorage
+let store = storage<T>({ driver: DriverType.SessionStorage, name: 'app', version: 1 });
+
+// Memory (non-persistent)
+let store = storage<T>({ driver: DriverType.Memory, name: 'app', version: 1 });
+```
+
+
+## API
+
+All methods are async and fully typed via `Local<T>`.
+
+### Core CRUD
+
+```typescript
+// Set a value
+await store.set('name', 'alice');
+
+// Get a value
+let name = await store.get('name'); // string | undefined
+
+// Get with factory (lazy init — never returns undefined)
+let name = await store.get('name', () => 'default');
+let user = await store.get('name', async () => await fetchUser());
+
+// Delete keys
+await store.delete('name', 'preferences');
+
+// Replace multiple values
+let failed = await store.replace({ name: 'bob', preferences: { theme: 'dark' } });
+
+// Get all entries
+let all = await store.all();
+
+// Get specific keys
+let subset = await store.only('name', 'preferences');
+
+// Count entries
+let count = await store.count();
+
+// List keys
+let keys = await store.keys();
+
+// Clear everything
+await store.clear();
+```
+
+### Iteration
+
+```typescript
+// Map over all entries
+await store.map((value, key, i) => {
+    console.log(key, value);
+});
+
+// Filter entries (with early stop)
+let result = await store.filter(({ key, value, stop }) => {
+    if (key === 'name') {
+        stop(); // halt iteration
+    }
+
+    return typeof value === 'string';
+});
+```
+
+
+## TTL / Expiration
+
+Per-key time-to-live in milliseconds. Expired entries return `undefined` and are lazily deleted.
+
+```typescript
+// Set with 1 hour TTL
+await store.set('session', token, { ttl: 3600000 });
+
+// Check remaining time (-1 if no TTL or expired)
+await store.ttl('session'); // ms remaining
+
+// Remove TTL (make permanent)
+await store.persist('session');
+
+// Proactively sweep all expired entries
+await store.cleanup();
+```
+
+
+## Encryption
+
+Optional AES-GCM encryption via a secret string.
+
+```typescript
+let store = storage<T>({ name: 'secure', version: 1 }, 'my-secret-key');
+
+await store.set('token', 'sensitive-data'); // encrypted at rest
+await store.get('token'); // 'sensitive-data' (decrypted)
+```
+
+
+## Change Subscriptions
+
+Subscribe to value changes. Returns an unsubscribe function.
+
+```typescript
+// Per-key subscription
+let unsubscribe = store.subscribe('name', (newValue, oldValue) => {
+    console.log(`name: ${oldValue} -> ${newValue}`);
+});
+
+// Global subscription (all keys)
+let unsubscribe = store.subscribe((key, newValue, oldValue) => {
+    console.log(`${String(key)} changed`);
+});
+
+// Stop listening
+unsubscribe();
+```
+
+Fires after: `set`, `delete`, `replace`, `clear`, `cleanup`.
+
+
+## Migrations
+
+Run transform functions when the version number changes.
+
+```typescript
+type V1 = { name: string };
+type V2 = { displayName: string; name: string };
+
+let store = storage<V2>({
+    name: 'app',
+    version: 2,
+    migrations: {
+        2: async (old) => {
+            let data = await old.all();
+
+            return {
+                ...data,
+                displayName: (data.name as string) || 'Anonymous'
+            };
+        }
+    }
+});
+```
+
+Migrations run sequentially. Version 1 to 3 runs migration 2 then migration 3. Each migration receives the current store data and returns the transformed data.
+
+
+## Compression
+
+localStorage and sessionStorage drivers automatically compress values >= 100 bytes using an inlined LZW compressor. No configuration needed.
+
+- Values < 100 bytes: stored as JSON (LZ overhead not worth it)
+- Values >= 100 bytes: LZ compressed (2-10x capacity gain on JSON)
+- Backward compatible: existing uncompressed values read normally
+- Runs before encryption on write, after decryption on read
+
+
+## Factory Pattern (`get` with default)
+
+```typescript
+// Sync factory
+let count = await store.get('count', () => 0);
+
+// Async factory
+let user = await store.get('user', async () => {
+    return await fetchUser(id);
+});
+```
+
+The factory is called only when the key is missing or expired. The produced value is persisted via a fire-and-forget `set` (caller isn't blocked by the write).
+
+
+## Types
+
+```typescript
+import type { Local } from '@esportsplus/web-storage';
+import { DriverType } from '@esportsplus/web-storage';
+
+type Options = {
+    driver?: DriverType;
+    migrations?: Record<number, MigrationFn>;
+    name: string;
+    version: number;
+};
+
+type SetOptions = {
+    ttl?: number;
+};
+
+type MigrationFn = (old: {
+    all(): Promise<Record<string, unknown>>;
+}) => Promise<Record<string, unknown>>;
+
+// Subscription callbacks
+type KeyCallback<T, K extends keyof T> = (
+    newValue: T[K] | undefined,
+    oldValue: T[K] | undefined
+) => void;
+
+type GlobalCallback<T> = (
+    key: keyof T,
+    newValue: T[keyof T] | undefined,
+    oldValue: T[keyof T] | undefined
+) => void;
+```
+
+
+## License
+
+MIT

package/build/drivers/localstorage.d.ts

@@ -5,6 +5,7 @@ declare class LocalStorageDriver<T> implements Driver<T> {
     private getKeys;
     private key;
     private parse;
+    private serialize;
     all(): Promise<T>;
     clear(): Promise<void>;
     count(): Promise<number>;

package/build/drivers/localstorage.js

@@ -1,3 +1,4 @@
+import { compress, decompress } from '../lz.js';
 class LocalStorageDriver {
     prefix;
     constructor(name, version) {
@@ -21,12 +22,19 @@ class LocalStorageDriver {
             return undefined;
         }
         try {
+            if (value.charCodeAt(0) === 1) {
+                return JSON.parse(decompress(value.slice(1)));
+            }
             return JSON.parse(value);
         }
         catch {
             return undefined;
         }
     }
+    serialize(value) {
+        let json = JSON.stringify(value);
+        return json.length >= 100 ? '\x01' + compress(json) : json;
+    }
     async all() {
         let keys = this.getKeys(), result = {};
         for (let i = 0, n = keys.length; i < n; i++) {
@@ -78,12 +86,12 @@ class LocalStorageDriver {
     }
     async replace(entries) {
         for (let i = 0, n = entries.length; i < n; i++) {
-            localStorage.setItem(this.key(entries[i][0]), JSON.stringify(entries[i][1]));
+            localStorage.setItem(this.key(entries[i][0]), this.serialize(entries[i][1]));
         }
     }
     async set(key, value) {
         try {
-            localStorage.setItem(this.key(key), JSON.stringify(value));
+            localStorage.setItem(this.key(key), this.serialize(value));
             return true;
         }
         catch {

package/build/drivers/sessionstorage.d.ts

@@ -5,6 +5,7 @@ declare class SessionStorageDriver<T> implements Driver<T> {
     private getKeys;
     private key;
     private parse;
+    private serialize;
     all(): Promise<T>;
     clear(): Promise<void>;
     count(): Promise<number>;

package/build/drivers/sessionstorage.js

@@ -1,3 +1,4 @@
+import { compress, decompress } from '../lz.js';
 class SessionStorageDriver {
     prefix;
     constructor(name, version) {
@@ -21,12 +22,19 @@ class SessionStorageDriver {
             return undefined;
         }
         try {
+            if (value.charCodeAt(0) === 1) {
+                return JSON.parse(decompress(value.slice(1)));
+            }
             return JSON.parse(value);
         }
         catch {
             return undefined;
         }
     }
+    serialize(value) {
+        let json = JSON.stringify(value);
+        return json.length >= 100 ? '\x01' + compress(json) : json;
+    }
     async all() {
         let keys = this.getKeys(), result = {};
         for (let i = 0, n = keys.length; i < n; i++) {
@@ -78,12 +86,12 @@ class SessionStorageDriver {
     }
     async replace(entries) {
         for (let i = 0, n = entries.length; i < n; i++) {
-            sessionStorage.setItem(this.key(entries[i][0]), JSON.stringify(entries[i][1]));
+            sessionStorage.setItem(this.key(entries[i][0]), this.serialize(entries[i][1]));
         }
     }
     async set(key, value) {
         try {
-            sessionStorage.setItem(this.key(key), JSON.stringify(value));
+            sessionStorage.setItem(this.key(key), this.serialize(value));
             return true;
         }
         catch {

package/build/lz.d.ts

@@ -0,0 +1,3 @@
+declare const compress: (input: string) => string;
+declare const decompress: (compressed: string) => string;
+export { compress, decompress };

package/build/lz.js

@@ -0,0 +1,134 @@
+function emitLiteral(ctx, ch) {
+    let code = ch.charCodeAt(0);
+    if (code < 256) {
+        writeBits(ctx, ctx.numBits, 0);
+        writeBits(ctx, 8, code);
+    }
+    else {
+        writeBits(ctx, ctx.numBits, 1);
+        writeBits(ctx, 16, code);
+    }
+}
+function readBits(ctx, n) {
+    let result = 0;
+    for (let i = 0; i < n; i++) {
+        if (ctx.bitPos > 15) {
+            ctx.currentValue = ctx.compressed.charCodeAt(ctx.pos++) - 1;
+            ctx.bitPos = 0;
+        }
+        result = (result << 1) | ((ctx.currentValue >> (15 - ctx.bitPos)) & 1);
+        ctx.bitPos++;
+    }
+    return result;
+}
+function writeBits(ctx, n, value) {
+    for (let i = n - 1; i >= 0; i--) {
+        ctx.buffer = (ctx.buffer << 1) | ((value >> i) & 1);
+        ctx.bitsInBuffer++;
+        if (ctx.bitsInBuffer === 16) {
+            ctx.output.push(ctx.buffer + 1);
+            ctx.buffer = 0;
+            ctx.bitsInBuffer = 0;
+        }
+    }
+}
+const compress = (input) => {
+    if (!input) {
+        return '';
+    }
+    let ctx = { bitsInBuffer: 0, buffer: 0, numBits: 2, output: [] }, dictSize = 3, dictionary = new Map(), w = '';
+    for (let i = 0, n = input.length; i < n; i++) {
+        let c = input[i], wc = w + c;
+        if (dictionary.has(wc)) {
+            w = wc;
+            continue;
+        }
+        if (w.length > 0) {
+            if (dictionary.has(w)) {
+                writeBits(ctx, ctx.numBits, dictionary.get(w));
+            }
+            else {
+                emitLiteral(ctx, w);
+            }
+            dictionary.set(wc, dictSize++);
+            if (dictSize > (1 << ctx.numBits)) {
+                ctx.numBits++;
+            }
+        }
+        w = c;
+    }
+    if (w.length > 0) {
+        if (dictionary.has(w)) {
+            writeBits(ctx, ctx.numBits, dictionary.get(w));
+        }
+        else {
+            emitLiteral(ctx, w);
+        }
+    }
+    dictSize++;
+    if (dictSize > (1 << ctx.numBits)) {
+        ctx.numBits++;
+    }
+    writeBits(ctx, ctx.numBits, 2);
+    if (ctx.bitsInBuffer > 0) {
+        ctx.output.push(((ctx.buffer << (16 - ctx.bitsInBuffer)) & 0xFFFF) + 1);
+    }
+    ctx.output.push((ctx.bitsInBuffer === 0 ? 16 : ctx.bitsInBuffer) + 1);
+    let chars = [];
+    for (let i = 0, n = ctx.output.length; i < n; i++) {
+        chars.push(String.fromCharCode(ctx.output[i]));
+    }
+    return chars.join('');
+};
+const decompress = (compressed) => {
+    if (!compressed) {
+        return '';
+    }
+    let ctx = { bitPos: 16, compressed: '', currentValue: 0, pos: 0 }, dictSize = 3, dictionary = [], numBits = 2;
+    ctx.compressed = compressed.substring(0, compressed.length - 1);
+    let code = readBits(ctx, numBits), entry;
+    if (code === 0) {
+        entry = String.fromCharCode(readBits(ctx, 8));
+    }
+    else if (code === 1) {
+        entry = String.fromCharCode(readBits(ctx, 16));
+    }
+    else {
+        return '';
+    }
+    let result = [entry], w = entry;
+    while (true) {
+        let slotIdx = dictionary.length;
+        dictionary.push('');
+        dictSize++;
+        if (dictSize > (1 << numBits)) {
+            numBits++;
+        }
+        code = readBits(ctx, numBits);
+        if (code === 2) {
+            dictionary.pop();
+            break;
+        }
+        let slotCode = slotIdx + 3;
+        if (code === 0) {
+            entry = String.fromCharCode(readBits(ctx, 8));
+        }
+        else if (code === 1) {
+            entry = String.fromCharCode(readBits(ctx, 16));
+        }
+        else if (code === slotCode) {
+            entry = w + w[0];
+        }
+        else if (code >= 3 && code < slotCode) {
+            entry = dictionary[code - 3];
+        }
+        else {
+            throw new Error('LZ: invalid decompression code');
+        }
+        dictionary[slotIdx] = w + entry[0];
+        result.push(entry);
+        w = entry;
+    }
+    return result.join('');
+};
+export { compress, decompress };

package/package.json

@@ -19,7 +19,7 @@
   },
   "type": "module",
   "types": "build/index.d.ts",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "scripts": {
     "build": "tsc && tsc-alias",
     "test": "vitest run",

package/src/drivers/localstorage.ts

@@ -1,3 +1,4 @@
+import { compress, decompress } from '~/lz';
 import type { Driver } from '~/types';
 
 
@@ -35,6 +36,10 @@ class LocalStorageDriver<T> implements Driver<T> {
         }
 
         try {
+            if (value.charCodeAt(0) === 1) {
+                return JSON.parse(decompress(value.slice(1)));
+            }
+
             return JSON.parse(value);
         }
         catch {
@@ -42,6 +47,12 @@ class LocalStorageDriver<T> implements Driver<T> {
         }
     }
 
+    private serialize(value: T[keyof T]): string {
+        let json = JSON.stringify(value);
+
+        return json.length >= 100 ? '\x01' + compress(json) : json;
+    }
+
 
     async all(): Promise<T> {
         let keys = this.getKeys(),
@@ -112,13 +123,13 @@ class LocalStorageDriver<T> implements Driver<T> {
 
     async replace(entries: [keyof T, T[keyof T]][]): Promise<void> {
         for (let i = 0, n = entries.length; i < n; i++) {
-            localStorage.setItem(this.key(entries[i][0]), JSON.stringify(entries[i][1]));
+            localStorage.setItem(this.key(entries[i][0]), this.serialize(entries[i][1]));
         }
     }
 
     async set(key: keyof T, value: T[keyof T]): Promise<boolean> {
         try {
-            localStorage.setItem(this.key(key), JSON.stringify(value));
+            localStorage.setItem(this.key(key), this.serialize(value));
             return true;
         }
         catch {

package/src/drivers/sessionstorage.ts

@@ -1,3 +1,4 @@
+import { compress, decompress } from '~/lz';
 import type { Driver } from '~/types';
 
 
@@ -35,6 +36,10 @@ class SessionStorageDriver<T> implements Driver<T> {
         }
 
         try {
+            if (value.charCodeAt(0) === 1) {
+                return JSON.parse(decompress(value.slice(1)));
+            }
+
             return JSON.parse(value);
         }
         catch {
@@ -42,6 +47,12 @@ class SessionStorageDriver<T> implements Driver<T> {
         }
     }
 
+    private serialize(value: T[keyof T]): string {
+        let json = JSON.stringify(value);
+
+        return json.length >= 100 ? '\x01' + compress(json) : json;
+    }
+
 
     async all(): Promise<T> {
         let keys = this.getKeys(),
@@ -112,13 +123,13 @@ class SessionStorageDriver<T> implements Driver<T> {
 
     async replace(entries: [keyof T, T[keyof T]][]): Promise<void> {
         for (let i = 0, n = entries.length; i < n; i++) {
-            sessionStorage.setItem(this.key(entries[i][0]), JSON.stringify(entries[i][1]));
+            sessionStorage.setItem(this.key(entries[i][0]), this.serialize(entries[i][1]));
         }
     }
 
     async set(key: keyof T, value: T[keyof T]): Promise<boolean> {
         try {
-            sessionStorage.setItem(this.key(key), JSON.stringify(value));
+            sessionStorage.setItem(this.key(key), this.serialize(value));
             return true;
         }
         catch {