@esportsplus/web-storage 0.3.5 → 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/constants.d.ts

@@ -1,5 +1,7 @@
 declare enum DriverType {
     IndexedDB = 0,
-    LocalStorage = 1
+    LocalStorage = 1,
+    Memory = 2,
+    SessionStorage = 3
 }
 export { DriverType };

package/build/constants.js

@@ -2,5 +2,7 @@ var DriverType;
 (function (DriverType) {
     DriverType[DriverType["IndexedDB"] = 0] = "IndexedDB";
     DriverType[DriverType["LocalStorage"] = 1] = "LocalStorage";
+    DriverType[DriverType["Memory"] = 2] = "Memory";
+    DriverType[DriverType["SessionStorage"] = 3] = "SessionStorage";
 })(DriverType || (DriverType = {}));
 export { DriverType };

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/memory.d.ts

@@ -0,0 +1,16 @@
+import type { Driver } from '../types.js';
+declare class MemoryDriver<T> implements Driver<T> {
+    private store;
+    constructor(name: string, _version: number);
+    all(): Promise<T>;
+    clear(): Promise<void>;
+    count(): Promise<number>;
+    delete(keys: (keyof T)[]): Promise<void>;
+    get(key: keyof T): Promise<T[keyof T] | undefined>;
+    keys(): Promise<(keyof T)[]>;
+    map(fn: (value: T[keyof T], key: keyof T, i: number) => void | Promise<void>): Promise<void>;
+    only(keys: (keyof T)[]): Promise<Map<keyof T, T[keyof T]>>;
+    replace(entries: [keyof T, T[keyof T]][]): Promise<void>;
+    set(key: keyof T, value: T[keyof T]): Promise<boolean>;
+}
+export { MemoryDriver };

package/build/drivers/memory.js

@@ -0,0 +1,64 @@
+let stores = new Map();
+class MemoryDriver {
+    store;
+    constructor(name, _version) {
+        let existing = stores.get(name);
+        if (existing) {
+            this.store = existing;
+        }
+        else {
+            this.store = new Map();
+            stores.set(name, this.store);
+        }
+    }
+    async all() {
+        let result = {};
+        for (let [key, value] of this.store) {
+            result[key] = value;
+        }
+        return result;
+    }
+    async clear() {
+        this.store.clear();
+    }
+    async count() {
+        return this.store.size;
+    }
+    async delete(keys) {
+        for (let i = 0, n = keys.length; i < n; i++) {
+            this.store.delete(keys[i]);
+        }
+    }
+    async get(key) {
+        return this.store.get(key);
+    }
+    async keys() {
+        return [...this.store.keys()];
+    }
+    async map(fn) {
+        let i = 0;
+        for (let [key, value] of this.store) {
+            await fn(value, key, i++);
+        }
+    }
+    async only(keys) {
+        let results = new Map();
+        for (let i = 0, n = keys.length; i < n; i++) {
+            let value = this.store.get(keys[i]);
+            if (value !== undefined) {
+                results.set(keys[i], value);
+            }
+        }
+        return results;
+    }
+    async replace(entries) {
+        for (let i = 0, n = entries.length; i < n; i++) {
+            this.store.set(entries[i][0], entries[i][1]);
+        }
+    }
+    async set(key, value) {
+        this.store.set(key, value);
+        return true;
+    }
+}
+export { MemoryDriver };

package/build/drivers/sessionstorage.d.ts

@@ -0,0 +1,20 @@
+import type { Driver } from '../types.js';
+declare class SessionStorageDriver<T> implements Driver<T> {
+    private prefix;
+    constructor(name: string, version: number);
+    private getKeys;
+    private key;
+    private parse;
+    private serialize;
+    all(): Promise<T>;
+    clear(): Promise<void>;
+    count(): Promise<number>;
+    delete(keys: (keyof T)[]): Promise<void>;
+    get(key: keyof T): Promise<T[keyof T] | undefined>;
+    keys(): Promise<(keyof T)[]>;
+    map(fn: (value: T[keyof T], key: keyof T, i: number) => void | Promise<void>): Promise<void>;
+    only(keys: (keyof T)[]): Promise<Map<keyof T, T[keyof T]>>;
+    replace(entries: [keyof T, T[keyof T]][]): Promise<void>;
+    set(key: keyof T, value: T[keyof T]): Promise<boolean>;
+}
+export { SessionStorageDriver };

package/build/drivers/sessionstorage.js

@@ -0,0 +1,102 @@
+import { compress, decompress } from '../lz.js';
+class SessionStorageDriver {
+    prefix;
+    constructor(name, version) {
+        this.prefix = `${name}:${version}:`;
+    }
+    getKeys() {
+        let keys = [];
+        for (let i = 0, n = sessionStorage.length; i < n; i++) {
+            let key = sessionStorage.key(i);
+            if (key && key.startsWith(this.prefix)) {
+                keys.push(key.slice(this.prefix.length));
+            }
+        }
+        return keys;
+    }
+    key(key) {
+        return this.prefix + String(key);
+    }
+    parse(value) {
+        if (value === null) {
+            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++) {
+            let value = this.parse(sessionStorage.getItem(this.prefix + keys[i]));
+            if (value !== undefined) {
+                result[keys[i]] = value;
+            }
+        }
+        return result;
+    }
+    async clear() {
+        let keys = this.getKeys();
+        for (let i = 0, n = keys.length; i < n; i++) {
+            sessionStorage.removeItem(this.prefix + keys[i]);
+        }
+    }
+    async count() {
+        return this.getKeys().length;
+    }
+    async delete(keys) {
+        for (let i = 0, n = keys.length; i < n; i++) {
+            sessionStorage.removeItem(this.key(keys[i]));
+        }
+    }
+    async get(key) {
+        return this.parse(sessionStorage.getItem(this.key(key)));
+    }
+    async keys() {
+        return this.getKeys();
+    }
+    async map(fn) {
+        let keys = this.getKeys();
+        for (let i = 0, n = keys.length; i < n; i++) {
+            let value = this.parse(sessionStorage.getItem(this.prefix + keys[i]));
+            if (value !== undefined) {
+                await fn(value, keys[i], i);
+            }
+        }
+    }
+    async only(keys) {
+        let results = new Map();
+        for (let i = 0, n = keys.length; i < n; i++) {
+            let value = this.parse(sessionStorage.getItem(this.key(keys[i])));
+            if (value !== undefined) {
+                results.set(keys[i], value);
+            }
+        }
+        return results;
+    }
+    async replace(entries) {
+        for (let i = 0, n = entries.length; i < n; i++) {
+            sessionStorage.setItem(this.key(entries[i][0]), this.serialize(entries[i][1]));
+        }
+    }
+    async set(key, value) {
+        try {
+            sessionStorage.setItem(this.key(key), this.serialize(value));
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+}
+export { SessionStorageDriver };

package/build/index.d.ts

@@ -1,20 +1,30 @@
-import type { Filter, Options } from './types.js';
+import type { Filter, GlobalCallback, KeyCallback, Options, SetOptions } from './types.js';
 declare class Local<T> {
     private driver;
+    private globals;
+    private listeners;
+    private ready;
     private secret;
+    private version;
     constructor(options: Options, secret?: string);
     all(): Promise<T>;
     clear(): Promise<void>;
+    cleanup(): Promise<void>;
     count(): Promise<number>;
     delete(...keys: (keyof T)[]): Promise<void>;
     filter(fn: Filter<T>): Promise<T>;
     get(key: keyof T): Promise<T[keyof T] | undefined>;
+    get(key: keyof T, factory: () => T[keyof T] | Promise<T[keyof T]>): Promise<T[keyof T]>;
     keys(): Promise<(keyof T)[]>;
     length(): Promise<number>;
     map(fn: (value: T[keyof T], key: keyof T, i: number) => void | Promise<void>): Promise<void>;
     only(...keys: (keyof T)[]): Promise<T>;
+    persist(key: keyof T): Promise<boolean>;
     replace(values: Partial<T>): Promise<string[]>;
-    set(key: keyof T, value: T[keyof T]): Promise<boolean>;
+    set(key: keyof T, value: T[keyof T], options?: SetOptions): Promise<boolean>;
+    subscribe(callback: GlobalCallback<T>): () => void;
+    subscribe<K extends keyof T>(key: K, callback: KeyCallback<T, K>): () => void;
+    ttl(key: keyof T): Promise<number>;
 }
 declare const _default: <T>(options: Options, secret?: string) => Local<T>;
 export default _default;