@esportsplus/web-storage 0.4.0 → 0.5.0

package/src/lz.ts

@@ -0,0 +1,192 @@
+type CompressCtx = { bitsInBuffer: number; buffer: number; numBits: number; output: number[] };
+type DecompressCtx = { bitPos: number; compressed: string; currentValue: number; pos: number };
+
+
+function emitLiteral(ctx: CompressCtx, ch: string) {
+    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: DecompressCtx, n: number): number {
+    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: CompressCtx, n: number, value: number) {
+    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: string): string => {
+    if (!input) {
+        return '';
+    }
+
+    let ctx: CompressCtx = { bitsInBuffer: 0, buffer: 0, numBits: 2, output: [] },
+        dictSize = 3,
+        dictionary = new Map<string, number>(),
+        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);
+        }
+    }
+
+    // Trailing dict advance: ensures the decompressor's last placeholder growth
+    // matches (the decompressor will push a placeholder before reading EOF)
+    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: string[] = [];
+
+    for (let i = 0, n = ctx.output.length; i < n; i++) {
+        chars.push(String.fromCharCode(ctx.output[i]));
+    }
+
+    return chars.join('');
+};
+
+const decompress = (compressed: string): string => {
+    if (!compressed) {
+        return '';
+    }
+
+    let ctx: DecompressCtx = { bitPos: 16, compressed: '', currentValue: 0, pos: 0 },
+        dictSize = 3,
+        dictionary: string[] = [],
+        numBits = 2;
+
+    ctx.compressed = compressed.substring(0, compressed.length - 1);
+
+    let code = readBits(ctx, numBits),
+        entry: string;
+
+    if (code === 0) {
+        entry = String.fromCharCode(readBits(ctx, 8));
+    }
+    else if (code === 1) {
+        entry = String.fromCharCode(readBits(ctx, 16));
+    }
+    else {
+        return '';
+    }
+
+    let result: string[] = [entry],
+        w = entry;
+
+    while (true) {
+        // Reserve dict slot BEFORE reading (matches compressor's add-before-next-emit timing)
+        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/storage/test-audit-web-storage.md

@@ -0,0 +1,74 @@
+# Test Audit: @esportsplus/web-storage
+
+## Summary
+- Source modules: 8
+- Tested modules: 8 (100%)
+- Benchmarked modules: 0 (0%)
+- Total tests: 253
+- Total gaps found: 23
+
+## Missing Tests (Priority Order)
+
+| Module | Export / Path | Type | Risk |
+|--------|-------------|------|------|
+| Local<T> + SessionStorage | All Local<T> methods with SS driver | integration | HIGH — only 1 factory test exists for SS; zero method coverage at Local<T> layer |
+| Local<T> + Memory | TTL methods (ttl, persist, cleanup) | integration | HIGH — TTL logic is driver-agnostic but untested against Memory driver |
+| Local<T> + Memory | get(key, factory) | integration | MED — factory tested for IDB/LS but not Memory |
+| Local<T> + Memory | encryption (with secret) | integration | MED — no encryption round-trip tests for Memory driver |
+| Local<T> + Memory | filter, only, map, length | integration | MED — bulk read operations untested at Local<T> layer for Memory |
+| Local<T> | persist() on non-existent key | edge case | MED — returns false by code inspection, no test |
+| Local<T> | persist() on already-permanent key | edge case | LOW — returns true, no test |
+| Local<T> | cleanup() subscription notifications | integration | MED — validator flagged: cleanup fires notify but no test covers it |
+| Local<T> | get() TTL expiry + subscription | edge case | MED — expired get does fire-and-forget delete but bypasses subscription-aware delete path; behavior unclear |
+| Local<T> | count() with VERSION_KEY present | edge case | MED — should return count-1 when migrations active; no test |
+| Local<T> | keys() with VERSION_KEY present | edge case | MED — should exclude __version__; no test |
+| Local<T> + encryption | get(key, factory) + encryption | integration | LOW — factory + encrypt combo untested |
+| Local<T> + LS | compression + encryption combined | integration | MED — encrypted ciphertext stored via driver which may attempt compression; round-trip untested |
+
+## Shallow Tests
+
+| Module | Export | Covered | Missing |
+|--------|--------|---------|---------|
+| Local<T>.persist() | IDB, LS | happy path (has TTL, removes it) | non-existent key, already-permanent key, expired key |
+| Local<T>.cleanup() | IDB, LS | removes expired entries | empty store, no expired entries, subscription notifications |
+| Local<T>.clear() | IDB, LS, Memory | clears all + notifies | VERSION_KEY preserved after clear (migration stores re-init) |
+| Local<T>.subscribe() | Memory | set, delete, replace, clear, unsubscribe | cleanup notifications, factory-triggered notifications, TTL expiry notifications |
+| Local<T>.map() | IDB, LS, Memory | iterates entries | TTL filtering + VERSION_KEY filtering combined |
+| LZ compress/decompress | round-trip | all string types | very large strings (>100KB), strings that produce larger output than input (random/high-entropy) |
+| LocalStorageDriver.parse() | error handling | corrupted compressed data | corrupted non-compressed JSON, null byte in stored data |
+
+## Missing Benchmarks
+
+No benchmark infrastructure exists. For a storage library, benchmarks would be useful for:
+
+| Module | Export | Reason |
+|--------|--------|--------|
+| LZ compress/decompress | compress() | Called on every localStorage write ≥100 bytes |
+| LZ compress/decompress | decompress() | Called on every localStorage read of compressed data |
+| LocalStorageDriver | set/get | Hot path for localStorage operations |
+| IndexedDBDriver | set/get/all | Async I/O operations, would reveal contention |
+| Local<T> | set with encryption | Encryption + serialization overhead |
+
+## Stale Tests
+
+None found. All test references match current exports.
+
+## Recommendations
+
+### Priority 1: SessionStorage Local<T> integration (HIGH)
+The sessionStorage driver has full driver-level tests (36) but almost zero Local<T> integration tests (just 1 factory test). Add at minimum: set/get, all, delete, clear, count, keys — mirroring the existing Memory driver block. Encryption and TTL should also be tested since the driver shares serialization logic with localStorage but includes compression.
+
+### Priority 2: Memory driver feature coverage (HIGH)
+TTL, persist, cleanup, get(key, factory), encryption, and bulk read operations are untested at the Local<T> layer for the Memory driver. Since Memory is the recommended driver for unit testing, these gaps are ironic — users testing their own code with Memory may hit untested paths.
+
+### Priority 3: Cross-feature edge cases (MED)
+- cleanup() + subscription notifications
+- get() TTL expiry + subscription side-effects
+- count()/keys() with VERSION_KEY present (migrations active)
+- Compression + encryption combined round-trip
+- persist() on non-existent and already-permanent keys
+
+### Priority 4: LZ compression boundaries (LOW)
+- Very large strings (100KB+)
+- High-entropy strings that don't compress
+- Explicit test that compression never increases size by more than a bounded amount

package/tests/drivers/localstorage.ts

@@ -232,6 +232,92 @@ describe('LocalStorageDriver', () => {
     });
 
 
+    describe('compression', () => {
+        type LargeData = { bio: string };
+
+        let largeDriver: LocalStorageDriver<LargeData>,
+            largeValue: string;
+
+        beforeEach(() => {
+            largeDriver = new LocalStorageDriver<LargeData>('lz', 1);
+            largeValue = 'a'.repeat(200);
+        });
+
+        it('stores small values without compression prefix', async () => {
+            await driver.set('name', 'alice');
+
+            let raw = localStorage.getItem('test:1:name')!;
+
+            expect(raw.charCodeAt(0)).not.toBe(1);
+            expect(raw).toBe('"alice"');
+        });
+
+        it('stores large values with \\x01 prefix', async () => {
+            await largeDriver.set('bio', largeValue);
+
+            let raw = localStorage.getItem('lz:1:bio')!;
+
+            expect(raw.charCodeAt(0)).toBe(1);
+        });
+
+        it('round-trips large values through set/get', async () => {
+            await largeDriver.set('bio', largeValue);
+
+            expect(await largeDriver.get('bio')).toBe(largeValue);
+        });
+
+        it('round-trips large values through replace/all', async () => {
+            await largeDriver.replace([['bio', largeValue]]);
+
+            let all = await largeDriver.all();
+
+            expect(all.bio).toBe(largeValue);
+        });
+
+        it('reads existing uncompressed values (backward compat)', async () => {
+            localStorage.setItem('lz:1:bio', JSON.stringify(largeValue));
+
+            expect(await largeDriver.get('bio')).toBe(largeValue);
+        });
+
+        it('compressed output is smaller than raw JSON', async () => {
+            await largeDriver.set('bio', largeValue);
+
+            let compressed = localStorage.getItem('lz:1:bio')!,
+                raw = JSON.stringify(largeValue);
+
+            expect(compressed.length).toBeLessThan(raw.length);
+        });
+
+        it('handles 100-byte boundary correctly', async () => {
+            type BoundaryData = { val: string };
+
+            let boundaryDriver = new LocalStorageDriver<BoundaryData>('bound', 1);
+
+            // JSON.stringify('"' + 'x'.repeat(97) + '"') = 97 chars + 2 quotes = "xxx...x" = 99 chars inside quotes, total 99+2=101? No.
+            // JSON.stringify('x'.repeat(96)) = '"' + 'x'*96 + '"' = 98 bytes < 100 => no compress
+            await boundaryDriver.set('val', 'x'.repeat(96));
+
+            let rawSmall = localStorage.getItem('bound:1:val')!;
+
+            expect(rawSmall.charCodeAt(0)).not.toBe(1);
+
+            // JSON.stringify('x'.repeat(98)) = '"' + 'x'*98 + '"' = 100 bytes >= 100 => compress
+            await boundaryDriver.set('val', 'x'.repeat(98));
+
+            let rawLarge = localStorage.getItem('bound:1:val')!;
+
+            expect(rawLarge.charCodeAt(0)).toBe(1);
+        });
+
+        it('parse returns undefined for corrupted compressed data', async () => {
+            localStorage.setItem('lz:1:bio', '\x01corrupted-data');
+
+            expect(await largeDriver.get('bio')).toBeUndefined();
+        });
+    });
+
+
     describe('set / get', () => {
         it('overwrites existing key', async () => {
             await driver.set('name', 'alice');

package/tests/drivers/sessionstorage.ts

@@ -232,6 +232,91 @@ describe('SessionStorageDriver', () => {
     });
 
 
+    describe('compression', () => {
+        type LargeData = { bio: string };
+
+        let largeDriver: SessionStorageDriver<LargeData>,
+            largeValue: string;
+
+        beforeEach(() => {
+            largeDriver = new SessionStorageDriver<LargeData>('lz', 1);
+            largeValue = 'a'.repeat(200);
+        });
+
+        it('stores small values without compression prefix', async () => {
+            await driver.set('name', 'alice');
+
+            let raw = sessionStorage.getItem('test:1:name')!;
+
+            expect(raw.charCodeAt(0)).not.toBe(1);
+            expect(raw).toBe('"alice"');
+        });
+
+        it('stores large values with \\x01 prefix', async () => {
+            await largeDriver.set('bio', largeValue);
+
+            let raw = sessionStorage.getItem('lz:1:bio')!;
+
+            expect(raw.charCodeAt(0)).toBe(1);
+        });
+
+        it('round-trips large values through set/get', async () => {
+            await largeDriver.set('bio', largeValue);
+
+            expect(await largeDriver.get('bio')).toBe(largeValue);
+        });
+
+        it('round-trips large values through replace/all', async () => {
+            await largeDriver.replace([['bio', largeValue]]);
+
+            let all = await largeDriver.all();
+
+            expect(all.bio).toBe(largeValue);
+        });
+
+        it('reads existing uncompressed values (backward compat)', async () => {
+            sessionStorage.setItem('lz:1:bio', JSON.stringify(largeValue));
+
+            expect(await largeDriver.get('bio')).toBe(largeValue);
+        });
+
+        it('compressed output is smaller than raw JSON', async () => {
+            await largeDriver.set('bio', largeValue);
+
+            let compressed = sessionStorage.getItem('lz:1:bio')!,
+                raw = JSON.stringify(largeValue);
+
+            expect(compressed.length).toBeLessThan(raw.length);
+        });
+
+        it('handles 100-byte boundary correctly', async () => {
+            type BoundaryData = { val: string };
+
+            let boundaryDriver = new SessionStorageDriver<BoundaryData>('bound', 1);
+
+            // JSON.stringify('x'.repeat(96)) = '"' + 'x'*96 + '"' = 98 bytes < 100 => no compress
+            await boundaryDriver.set('val', 'x'.repeat(96));
+
+            let rawSmall = sessionStorage.getItem('bound:1:val')!;
+
+            expect(rawSmall.charCodeAt(0)).not.toBe(1);
+
+            // JSON.stringify('x'.repeat(98)) = '"' + 'x'*98 + '"' = 100 bytes >= 100 => compress
+            await boundaryDriver.set('val', 'x'.repeat(98));
+
+            let rawLarge = sessionStorage.getItem('bound:1:val')!;
+
+            expect(rawLarge.charCodeAt(0)).toBe(1);
+        });
+
+        it('parse returns undefined for corrupted compressed data', async () => {
+            sessionStorage.setItem('lz:1:bio', '\x01corrupted-data');
+
+            expect(await largeDriver.get('bio')).toBeUndefined();
+        });
+    });
+
+
     describe('set / get', () => {
         it('overwrites existing key', async () => {
             await driver.set('name', 'alice');