@esportsplus/web-storage 0.4.0 → 0.5.1

package/tests/lz.ts

@@ -0,0 +1,371 @@
+import { describe, expect, it } from 'vitest';
+
+import { compress, decompress } from '~/lz';
+
+
+describe('LZ Compression', () => {
+
+    describe('empty/null handling', () => {
+        it('empty string round-trips', () => {
+            expect(compress('')).toBe('');
+            expect(decompress('')).toBe('');
+        });
+    });
+
+    describe('single characters', () => {
+        it('lowercase a', () => {
+            let compressed = compress('a');
+
+            expect(decompress(compressed)).toBe('a');
+        });
+
+        it('uppercase Z', () => {
+            let compressed = compress('Z');
+
+            expect(decompress(compressed)).toBe('Z');
+        });
+
+        it('null character (U+0000)', () => {
+            let compressed = compress('\0');
+
+            expect(decompress(compressed)).toBe('\0');
+        });
+    });
+
+    describe('short ASCII strings', () => {
+        it('hello world', () => {
+            let input = 'hello world',
+                compressed = compress(input);
+
+            expect(decompress(compressed)).toBe(input);
+        });
+
+        it('the quick brown fox', () => {
+            let input = 'The quick brown fox jumps over the lazy dog',
+                compressed = compress(input);
+
+            expect(decompress(compressed)).toBe(input);
+        });
+
+        it('numbers and symbols', () => {
+            let input = '0123456789!@#$%^&*()_+-=[]{}|;:,.<>?',
+                compressed = compress(input);
+
+            expect(decompress(compressed)).toBe(input);
+        });
+    });
+
+    describe('repetitive strings', () => {
+        it('abcabc repeated 500 times', () => {
+            let input = 'abc'.repeat(500),
+                compressed = compress(input);
+
+            expect(decompress(compressed)).toBe(input);
+        });
+
+        it('single char repeated 1000 times', () => {
+            let input = 'x'.repeat(1000),
+                compressed = compress(input);
+
+            expect(decompress(compressed)).toBe(input);
+        });
+
+        it('aaabbbccc pattern repeated', () => {
+            let input = 'aaabbbccc'.repeat(200),
+                compressed = compress(input);
+
+            expect(decompress(compressed)).toBe(input);
+        });
+    });
+
+    describe('JSON-like strings', () => {
+        it('1KB+ JSON string round-trips', () => {
+            let items: Record<string, unknown>[] = [];
+
+            for (let i = 0; i < 50; i++) {
+                items.push({
+                    age: 20 + (i % 60),
+                    id: i,
+                    name: `user_${i}`,
+                    tags: ['alpha', 'beta', 'gamma']
+                });
+            }
+
+            let input = JSON.stringify({ data: items, total: 50, type: 'users' }),
+                compressed = compress(input);
+
+            expect(input.length).toBeGreaterThan(1024);
+            expect(decompress(compressed)).toBe(input);
+        });
+
+        it('nested JSON structure', () => {
+            let input = JSON.stringify({
+                config: {
+                    database: { host: 'localhost', port: 5432 },
+                    features: { darkMode: true, notifications: false }
+                },
+                users: [
+                    { email: 'alice@test.com', name: 'alice' },
+                    { email: 'bob@test.com', name: 'bob' }
+                ]
+            });
+
+            let compressed = compress(input);
+
+            expect(decompress(compressed)).toBe(input);
+        });
+    });
+
+    describe('unicode', () => {
+        it('emoji characters', () => {
+            let input = '😀🎉🚀💯🔥✨',
+                compressed = compress(input);
+
+            expect(decompress(compressed)).toBe(input);
+        });
+
+        it('CJK characters', () => {
+            let input = '日本語テスト',
+                compressed = compress(input);
+
+            expect(decompress(compressed)).toBe(input);
+        });
+
+        it('mixed scripts', () => {
+            let input = 'Hello 世界! Привет мир! 🎉 café résumé naïve',
+                compressed = compress(input);
+
+            expect(decompress(compressed)).toBe(input);
+        });
+
+        it('arabic and hebrew', () => {
+            let input = 'مرحبا שלום',
+                compressed = compress(input);
+
+            expect(decompress(compressed)).toBe(input);
+        });
+    });
+
+    describe('byte value coverage', () => {
+        it('all 256 byte values individually', () => {
+            for (let i = 0; i < 256; i++) {
+                let input = String.fromCharCode(i),
+                    compressed = compress(input);
+
+                expect(decompress(compressed)).toBe(input);
+            }
+        });
+
+        it('all 256 byte values concatenated', () => {
+            let chars: string[] = [];
+
+            for (let i = 0; i < 256; i++) {
+                chars.push(String.fromCharCode(i));
+            }
+
+            let input = chars.join(''),
+                compressed = compress(input);
+
+            expect(decompress(compressed)).toBe(input);
+        });
+    });
+
+    describe('compression ratio', () => {
+        it('1KB repetitive JSON compresses to < 50%', () => {
+            let items: Record<string, unknown>[] = [];
+
+            for (let i = 0; i < 50; i++) {
+                items.push({
+                    active: true,
+                    name: 'test_user',
+                    role: 'admin',
+                    score: 100
+                });
+            }
+
+            let input = JSON.stringify(items),
+                compressed = compress(input);
+
+            expect(input.length).toBeGreaterThan(1024);
+            expect(compressed.length).toBeLessThan(input.length * 0.5);
+            expect(decompress(compressed)).toBe(input);
+        });
+    });
+
+    describe('edge cases', () => {
+        it('two character string', () => {
+            let compressed = compress('ab');
+
+            expect(decompress(compressed)).toBe('ab');
+        });
+
+        it('three character string', () => {
+            let compressed = compress('abc');
+
+            expect(decompress(compressed)).toBe('abc');
+        });
+
+        it('string with only whitespace', () => {
+            let input = '   \t\n\r  ',
+                compressed = compress(input);
+
+            expect(decompress(compressed)).toBe(input);
+        });
+
+        it('string with newlines', () => {
+            let input = 'line1\nline2\nline3\n',
+                compressed = compress(input);
+
+            expect(decompress(compressed)).toBe(input);
+        });
+
+        it('compressed output contains no null bytes', () => {
+            let inputs = [
+                'hello world',
+                'abc'.repeat(500),
+                JSON.stringify({ key: 'value' }),
+                '日本語テスト'
+            ];
+
+            for (let i = 0, n = inputs.length; i < n; i++) {
+                let compressed = compress(inputs[i]);
+
+                for (let j = 0, m = compressed.length; j < m; j++) {
+                    expect(compressed.charCodeAt(j)).not.toBe(0);
+                }
+            }
+        });
+
+        it('binary-like string with high char codes', () => {
+            let chars: string[] = [];
+
+            for (let i = 0; i < 100; i++) {
+                chars.push(String.fromCharCode(Math.floor(Math.random() * 65535) + 1));
+            }
+
+            let input = chars.join(''),
+                compressed = compress(input);
+
+            expect(decompress(compressed)).toBe(input);
+        });
+    });
+
+    describe('boundary cases', () => {
+        it('very large string (~100KB) round-trips', () => {
+            let items: Record<string, unknown>[] = [];
+
+            for (let i = 0; i < 2000; i++) {
+                items.push({
+                    data: 'x'.repeat(10),
+                    id: i,
+                    name: `entry_${i}`,
+                    value: i * 3.14
+                });
+            }
+
+            let input = JSON.stringify(items);
+
+            expect(input.length).toBeGreaterThan(100_000);
+
+            let compressed = compress(input);
+
+            expect(decompress(compressed)).toBe(input);
+        });
+
+        it('high-entropy string that does not compress well', () => {
+            let chars: string[] = [];
+
+            for (let i = 0; i < 500; i++) {
+                chars.push(String.fromCharCode(32 + (((i * 7) + (i * i * 3)) % 95)));
+            }
+
+            let input = chars.join(''),
+                compressed = compress(input);
+
+            expect(decompress(compressed)).toBe(input);
+        });
+
+        it('exact bit-width boundary (2-bit to 3-bit transition)', () => {
+            // dictSize starts at 3, numBits at 2. After 2 new dictionary entries
+            // dictSize=5 > (1<<2)=4, triggering numBits bump to 3.
+            // 'abcd' has 4 unique chars; pattern 'abcdabcd' creates entries:
+            //   'ab'->3 (dictSize=4), 'bc'->4 (dictSize=5, triggers 2->3 bit transition)
+            let input = 'abcdabcd',
+                compressed = compress(input);
+
+            expect(decompress(compressed)).toBe(input);
+        });
+
+        it('single char repeated 2 times', () => {
+            let compressed = compress('aa');
+
+            expect(decompress(compressed)).toBe('aa');
+        });
+
+        it('single char repeated 3 times', () => {
+            let compressed = compress('aaa');
+
+            expect(decompress(compressed)).toBe('aaa');
+        });
+
+        it('single char repeated 4 times', () => {
+            let compressed = compress('aaaa');
+
+            expect(decompress(compressed)).toBe('aaaa');
+        });
+
+        it('surrogate pairs (mathematical bold fraktur)', () => {
+            let input = '𝕳𝖊𝖑𝖑𝖔',
+                compressed = compress(input);
+
+            expect(decompress(compressed)).toBe(input);
+        });
+    });
+
+    describe('error handling', () => {
+        it('throws on truncated compressed input', () => {
+            let compressed = compress('hello world this is a test string'),
+                truncated = compressed.substring(0, Math.floor(compressed.length / 2));
+
+            expect(() => decompress(truncated)).toThrow('LZ: unexpected end of compressed data');
+        });
+
+        it('throws on invalid decompression code', () => {
+            // Craft a compressed string with a valid header followed by an invalid code:
+            // Start with a valid literal (code=0, 8-bit char 'a'=97), then inject a code
+            // value that exceeds the current dictionary size.
+            // At that point: dictSize=4, numBits=2, valid codes: 0,1,2,3
+            // We need a code >= 4 which is impossible in 2 bits, so we need to grow
+            // the dictionary first. Instead, use a real compressed stream and corrupt it.
+            let compressed = compress('abcdefghijklmnop'),
+                chars = [...compressed.slice(0, -1)];
+
+            // Corrupt a middle byte to inject invalid codes
+            if (chars.length > 3) {
+                chars[2] = String.fromCharCode(chars[2].charCodeAt(0) ^ 0x7F);
+            }
+
+            let corrupted = chars.join('') + compressed[compressed.length - 1];
+
+            expect(() => decompress(corrupted)).toThrow();
+        });
+
+        it('throws when decompressed output exceeds size limit', () => {
+            // Use a moderately sized repetitive input that compresses quickly
+            // but decompresses to >10MB by building a string just over the limit
+            let chunk = 'abcdef'.repeat(100),
+                input = chunk.repeat(Math.ceil(10_485_761 / chunk.length) + 1);
+
+            let compressed = compress(input);
+
+            expect(() => decompress(compressed)).toThrow('LZ: decompressed output exceeds size limit');
+        }, 60000);
+
+        it('100KB repeated data round-trips without triggering size limit', () => {
+            let input = 'a'.repeat(100_000),
+                compressed = compress(input);
+
+            expect(decompress(compressed)).toBe(input);
+        });
+    });
+});

package/storage/feature-research.md

@@ -1,173 +0,0 @@
-# Feature Research: @esportsplus/web-storage
-
-Research date: 2026-03-24
-Sources: localForage, Dexie.js, idb-keyval, store2, RxDB, unstorage, lz-string, lscache, expired-storage, proxy-storage, Valtio, Podda
-
-
-## What We Already Have
-
-- Two drivers: IndexedDB (default), localStorage
-- Unified async API: get, set, delete, all, clear, count, keys, map, filter, only, replace
-- AES-GCM encryption with optional secret
-- TypeScript generics (`Local<T>` with per-key type inference)
-- Namespace isolation via `name:version:` prefix (LS) / separate databases (IDB)
-- Connection pooling for IndexedDB
-- Factory pattern for independent instances
-
-
-## Recommended Features (Priority Order)
-
-
-### 1. TTL / Expiration (HIGH)
-
-The most universally requested missing feature across storage libraries.
-
-**What**: Per-key time-to-live. `set(key, value, { ttl: 60000 })` stores an expiry timestamp alongside the value. On `get`, expired entries return `undefined` and are lazily deleted.
-
-**Why**: Without TTL, consumers reimplement expiry logic on every project. Cache use cases are impossible without it. lscache, expired-storage, and dozens of wrappers exist solely for this.
-
-**Approach**: Envelope wrapping — store `{ value, expiry }` instead of raw value. Lazy deletion on read (check expiry on `get`). Optional proactive sweep via `cleanup()` method.
-
-**API surface**:
-```typescript
-await store.set('session', token, { ttl: 3600000 }); // 1 hour
-await store.get('session'); // undefined after expiry
-await store.ttl('session'); // remaining ms, or -1 if no TTL
-await store.persist('session'); // remove TTL, make permanent
-await store.cleanup(); // proactively sweep all expired entries
-```
-
-**Implemented by**: lscache, expired-storage, ttl-db, localstorage-slim, Redis
-
-
-### 2. Memory Driver (HIGH)
-
-**What**: In-memory `Driver<T>` backed by a `Map`. Non-persistent — data lost on page reload.
-
-**Why**: Essential for unit testing (no browser APIs needed), SSR environments (no `localStorage`/`indexedDB`), and as a fallback when persistent storage is unavailable (private browsing, quota exceeded). Every major library offers this.
-
-**Approach**: Implement `Driver<T>` interface with a `Map<keyof T, T[keyof T]>`. Trivial — the interface already exists.
-
-**API surface**:
-```typescript
-import storage, { DriverType } from '@esportsplus/web-storage';
-
-let store = storage({ driver: DriverType.Memory, name: 'test', version: 1 });
-```
-
-**Implemented by**: localForage (plugin), unstorage (default), proxy-storage
-
-
-### 4. `get(key, factory)` — Lazy Init (HIGH)
-
-**What**: Optional second parameter on `get`. If the key is missing and a factory is provided, call the factory to produce the value, fire-and-forget the `set` (do not await it), and return the value immediately.
-
-**Why**: Extremely common pattern that every consumer reimplements. Especially useful for expensive computations or API calls that should be cached. The fire-and-forget write means the caller is never blocked by storage I/O — the value is returned as soon as the factory resolves.
-
-**Behavior**:
-1. `get(key)` — existing behavior, returns `T[keyof T] | undefined`
-2. `get(key, factory)` — if value exists, return it. If missing, call `factory()`, persist the result via `set` without awaiting, return the factory value. Factory can be sync or async.
-
-**API surface**:
-```typescript
-// Without factory — unchanged, returns T[keyof T] | undefined
-let user = await store.get('user');
-
-// With factory — returns T[keyof T] (never undefined)
-let user = await store.get('user', async () => {
-    return await fetchUser(id);
-});
-
-// Sync factory works too
-let count = await store.get('count', () => 0);
-```
-
-**Implementation note**: The `set` call is intentionally not awaited. The returned value comes from the factory, not from a subsequent read. This means the caller gets the value immediately while the write happens in the background. If the write fails silently, the next `get` with a factory will simply re-invoke it.
-
-**Implemented by**: Common pattern, no library does it particularly well
-
-
-### 5. Compression (HIGH for localStorage)
-
-**What**: Always-on LZ-based compression for the localStorage driver. Multiplies effective capacity by 2-10x.
-
-**Why**: localStorage has a hard 5MB limit. Users consistently hit this wall. IndexedDB has no meaningful quota pressure (60% of disk), so compression is localStorage-only.
-
-**Approach**: Built into the localStorage driver's serialize/deserialize pipeline. No configuration — always active, but with a 100-byte threshold: values under 100 bytes are stored as-is (LZ framing overhead would make them larger), values at or above 100 bytes are compressed via `lz-string` `compressToUTF16`. On read, detect whether the stored value is compressed and decompress accordingly. Compression runs before encryption when a secret is present (compress → encrypt on write, decrypt → decompress on read).
-
-**No API surface** — this is an internal optimization. No user-facing option or configuration. The localStorage driver always compresses large values transparently.
-
-**Implemented by**: lz-string, localstorage-slim, locally (locallyjs)
-
-
-### 6. Change Subscriptions (MEDIUM-HIGH)
-
-**What**: `subscribe(key, callback)` fires when a value changes. Returns an unsubscribe function.
-
-**Why**: Essential for UI framework integration. Dexie's `liveQuery` and RxDB's reactive queries are headline features. A minimal event emitter per key fills the gap between the storage library and the UI layer.
-
-**Approach**: Internal `Map<keyof T, Set<Callback>>` in `Local<T>`. Fire callbacks after `set`, `delete`, `replace`, `clear` complete. No cross-tab sync (keep it simple).
-
-**API surface**:
-```typescript
-let unsubscribe = store.subscribe('theme', (newValue, oldValue) => {
-    applyTheme(newValue);
-});
-
-// or subscribe to all changes
-let unsubscribe = store.subscribe((key, newValue, oldValue) => {
-    console.log(`${key} changed`);
-});
-```
-
-**Implemented by**: Podda, Valtio, unstorage, local-storage-proxy
-
-
-### 7. Migration Callbacks (MEDIUM-HIGH)
-
-**What**: Run transform functions when the version number changes. The `version` parameter already exists but has no migration path.
-
-**Why**: Critical for production apps that evolve their schema. Without migrations, a version bump silently loses or corrupts data. Dexie and RxDB consider this a core feature.
-
-**Approach**: Accept a `migrations` map in options. On construction, detect version change and run the appropriate migration function before the store becomes usable.
-
-**API surface**:
-```typescript
-let store = storage<AppDataV2>({
-    name: 'app',
-    version: 2,
-    migrations: {
-        2: async (old) => {
-            // Transform v1 data to v2 shape
-            let all = await old.all();
-            return { ...all, newField: defaultValue };
-        }
-    }
-});
-```
-
-**Implemented by**: Dexie (`upgrade()`), RxDB (`migrationStrategies`)
-
-
-### 9. sessionStorage Driver (MEDIUM)
-
-**What**: Per-tab ephemeral storage via `sessionStorage`.
-
-**Why**: Fills a real gap for per-tab state (form drafts, wizard progress, auth tokens). Trivial to implement — copy `LocalStorageDriver` and swap `localStorage` for `sessionStorage`.
-
-**API surface**:
-```typescript
-let store = storage({ driver: DriverType.SessionStorage, name: 'tab', version: 1 });
-```
-
-**Implemented by**: store2 (`store.session`)
-
-### 11. OPFS Driver (LOW — emerging)
-
-**What**: Origin Private File System — 3-4x faster than IndexedDB for large binary data. Accessed via Web Worker using `FileSystemSyncAccessHandle`.
-
-**Why**: Emerging as the fastest browser storage for performance-sensitive apps. RxDB reports significant speed gains. However, browser support is still maturing and the API is complex.
-
-**Approach**: Defer until OPFS stabilizes further. Monitor adoption.
-
-**Implemented by**: RxDB, opfs-tools