@esportsplus/web-storage 0.4.0 → 0.5.1

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++) {
@@ -44,7 +52,13 @@ class LocalStorageDriver {
         }
     }
     async count() {
-        return this.getKeys().length;
+        let count = 0;
+        for (let i = 0, n = localStorage.length; i < n; i++) {
+            if (localStorage.key(i)?.startsWith(this.prefix)) {
+                count++;
+            }
+        }
+        return count;
     }
     async delete(keys) {
         for (let i = 0, n = keys.length; i < n; i++) {
@@ -78,12 +92,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++) {
@@ -44,7 +52,13 @@ class SessionStorageDriver {
         }
     }
     async count() {
-        return this.getKeys().length;
+        let count = 0;
+        for (let i = 0, n = sessionStorage.length; i < n; i++) {
+            if (sessionStorage.key(i)?.startsWith(this.prefix)) {
+                count++;
+            }
+        }
+        return count;
     }
     async delete(keys) {
         for (let i = 0, n = keys.length; i < n; i++) {
@@ -78,12 +92,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/index.d.ts

@@ -1,10 +1,10 @@
 import type { Filter, GlobalCallback, KeyCallback, Options, SetOptions } from './types.js';
 declare class Local<T> {
+    private cipher;
     private driver;
     private globals;
     private listeners;
     private ready;
-    private secret;
     private version;
     constructor(options: Options, secret?: string);
     all(): Promise<T>;