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

@@ -16,11 +16,32 @@ interface Driver<T> {
 
 type Filter<T> = (data: { i: number; key: keyof T; stop: VoidFunction; value: T[keyof T] }) => boolean | Promise<boolean>;
 
+type MigrationContext = {
+    all(): Promise<Record<string, unknown>>;
+};
+
+type MigrationFn = (old: MigrationContext) => Promise<Record<string, unknown>>;
+
 type Options = {
-    driver?: DriverType.IndexedDB | DriverType.LocalStorage;
+    driver?: DriverType.IndexedDB | DriverType.LocalStorage | DriverType.Memory | DriverType.SessionStorage;
+    migrations?: Record<number, MigrationFn>;
     name: string;
     version: number;
 };
 
+type SetOptions = {
+    ttl?: number;
+};
+
+type TTLEnvelope<V> = {
+    __e: number;
+    __v: V;
+};
+
+
+type GlobalCallback<T> = (key: keyof T, newValue: T[keyof T] | undefined, oldValue: T[keyof T] | undefined) => void;
+
+type KeyCallback<T, K extends keyof T = keyof T> = (newValue: T[K] | undefined, oldValue: T[K] | undefined) => void;
+
 
-export type { Driver, Filter, Options };
+export type { Driver, Filter, GlobalCallback, KeyCallback, MigrationContext, MigrationFn, Options, SetOptions, TTLEnvelope };

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/indexeddb.ts

@@ -0,0 +1,297 @@
+import 'fake-indexeddb/auto';
+
+import { describe, expect, it } from 'vitest';
+
+import { IndexedDBDriver } from '~/drivers/indexeddb';
+
+
+type TestData = { age: number; name: string; tags: string[] };
+
+
+let id = 0;
+
+function uid() {
+    return `test-db-${++id}`;
+}
+
+
+describe('IndexedDBDriver', () => {
+
+    describe('all', () => {
+        it('returns all stored key-value pairs', async () => {
+            let db = uid(),
+                driver = new IndexedDBDriver<TestData>(db, 1);
+
+            await driver.set('name', 'alice');
+            await driver.set('age', 30);
+
+            let result = await driver.all();
+
+            expect(result).toEqual({ age: 30, name: 'alice' });
+        });
+
+        it('returns empty object when storage is empty', async () => {
+            let driver = new IndexedDBDriver<TestData>(uid(), 1);
+
+            expect(await driver.all()).toEqual({});
+        });
+    });
+
+
+    describe('clear', () => {
+        it('removes all entries', async () => {
+            let db = uid(),
+                driver = new IndexedDBDriver<TestData>(db, 1);
+
+            await driver.set('name', 'alice');
+            await driver.set('age', 25);
+            await driver.clear();
+
+            expect(await driver.count()).toBe(0);
+            expect(await driver.all()).toEqual({});
+        });
+    });
+
+
+    describe('constructor / connect', () => {
+        it('creates database and object store', async () => {
+            let driver = new IndexedDBDriver<TestData>(uid(), 1);
+
+            expect(await driver.count()).toBe(0);
+        });
+
+        it('reuses connection for same name+version', async () => {
+            let db = uid(),
+                a = new IndexedDBDriver<TestData>(db, 1),
+                b = new IndexedDBDriver<TestData>(db, 1);
+
+            await a.set('name', 'alice');
+
+            expect(await b.get('name')).toBe('alice');
+        });
+    });
+
+
+    describe('count', () => {
+        it('returns 0 when empty', async () => {
+            let driver = new IndexedDBDriver<TestData>(uid(), 1);
+
+            expect(await driver.count()).toBe(0);
+        });
+
+        it('returns correct count of stored items', async () => {
+            let db = uid(),
+                driver = new IndexedDBDriver<TestData>(db, 1);
+
+            await driver.set('name', 'alice');
+            await driver.set('age', 30);
+            await driver.set('tags', ['a', 'b']);
+
+            expect(await driver.count()).toBe(3);
+        });
+    });
+
+
+    describe('delete', () => {
+        it('handles deleting non-existent keys without error', async () => {
+            let driver = new IndexedDBDriver<TestData>(uid(), 1);
+
+            await expect(driver.delete(['name', 'age'])).resolves.toBeUndefined();
+        });
+
+        it('removes specified keys', async () => {
+            let db = uid(),
+                driver = new IndexedDBDriver<TestData>(db, 1);
+
+            await driver.set('name', 'alice');
+            await driver.set('age', 30);
+            await driver.set('tags', ['x']);
+
+            await driver.delete(['name', 'tags']);
+
+            expect(await driver.get('name')).toBeUndefined();
+            expect(await driver.get('tags')).toBeUndefined();
+            expect(await driver.get('age')).toBe(30);
+            expect(await driver.count()).toBe(1);
+        });
+    });
+
+
+    describe('keys', () => {
+        it('returns all keys', async () => {
+            let db = uid(),
+                driver = new IndexedDBDriver<TestData>(db, 1);
+
+            await driver.set('name', 'alice');
+            await driver.set('age', 30);
+
+            let keys = await driver.keys();
+
+            expect(keys.sort()).toEqual(['age', 'name']);
+        });
+
+        it('returns empty array when empty', async () => {
+            let driver = new IndexedDBDriver<TestData>(uid(), 1);
+
+            expect(await driver.keys()).toEqual([]);
+        });
+    });
+
+
+    describe('map', () => {
+        it('iterates over all entries with correct value, key, and index', async () => {
+            let db = uid(),
+                driver = new IndexedDBDriver<TestData>(db, 1),
+                entries: { i: number; key: keyof TestData; value: TestData[keyof TestData] }[] = [];
+
+            await driver.set('age', 25);
+            await driver.set('name', 'bob');
+
+            await driver.map((value, key, i) => {
+                entries.push({ i, key, value });
+            });
+
+            expect(entries).toHaveLength(2);
+
+            entries.sort((a, b) => (a.key as string).localeCompare(b.key as string));
+
+            expect(entries[0]).toEqual({ i: expect.any(Number), key: 'age', value: 25 });
+            expect(entries[1]).toEqual({ i: expect.any(Number), key: 'name', value: 'bob' });
+        });
+
+        it('works on empty store with no callback invocations', async () => {
+            let called = false,
+                driver = new IndexedDBDriver<TestData>(uid(), 1);
+
+            await driver.map(() => {
+                called = true;
+            });
+
+            expect(called).toBe(false);
+        });
+    });
+
+
+    describe('only', () => {
+        it('returns empty Map when no keys match', async () => {
+            let driver = new IndexedDBDriver<TestData>(uid(), 1),
+                result = await driver.only(['name', 'age']);
+
+            expect(result.size).toBe(0);
+        });
+
+        it('returns Map with only requested keys', async () => {
+            let db = uid(),
+                driver = new IndexedDBDriver<TestData>(db, 1);
+
+            await driver.set('name', 'alice');
+            await driver.set('age', 30);
+            await driver.set('tags', ['a']);
+
+            let result = await driver.only(['name', 'tags']);
+
+            expect(result.size).toBe(2);
+            expect(result.get('name')).toBe('alice');
+            expect(result.get('tags')).toEqual(['a']);
+        });
+
+        it('skips keys that do not exist', async () => {
+            let db = uid(),
+                driver = new IndexedDBDriver<TestData>(db, 1);
+
+            await driver.set('name', 'alice');
+
+            let result = await driver.only(['name', 'age']);
+
+            expect(result.size).toBe(1);
+            expect(result.get('name')).toBe('alice');
+            expect(result.has('age')).toBe(false);
+        });
+    });
+
+
+    describe('replace', () => {
+        it('replaces multiple entries at once', async () => {
+            let db = uid(),
+                driver = new IndexedDBDriver<TestData>(db, 1);
+
+            await driver.set('name', 'alice');
+
+            await driver.replace([
+                ['name', 'bob'],
+                ['age', 42],
+                ['tags', ['x', 'y']]
+            ]);
+
+            expect(await driver.get('name')).toBe('bob');
+            expect(await driver.get('age')).toBe(42);
+            expect(await driver.get('tags')).toEqual(['x', 'y']);
+            expect(await driver.count()).toBe(3);
+        });
+    });
+
+
+    describe('set / get', () => {
+        it('overwrites existing key', async () => {
+            let db = uid(),
+                driver = new IndexedDBDriver<TestData>(db, 1);
+
+            await driver.set('name', 'alice');
+            await driver.set('name', 'bob');
+
+            expect(await driver.get('name')).toBe('bob');
+            expect(await driver.count()).toBe(1);
+        });
+
+        it('returns true on successful set', async () => {
+            let driver = new IndexedDBDriver<TestData>(uid(), 1);
+
+            expect(await driver.set('name', 'alice')).toBe(true);
+        });
+
+        it('returns undefined for non-existent key', async () => {
+            let driver = new IndexedDBDriver<TestData>(uid(), 1);
+
+            expect(await driver.get('name')).toBeUndefined();
+        });
+
+        it('sets and retrieves a number value', async () => {
+            let db = uid(),
+                driver = new IndexedDBDriver<TestData>(db, 1);
+
+            await driver.set('age', 25);
+
+            expect(await driver.get('age')).toBe(25);
+        });
+
+        it('sets and retrieves a string value', async () => {
+            let db = uid(),
+                driver = new IndexedDBDriver<TestData>(db, 1);
+
+            await driver.set('name', 'alice');
+
+            expect(await driver.get('name')).toBe('alice');
+        });
+
+        it('sets and retrieves an array value', async () => {
+            let db = uid(),
+                driver = new IndexedDBDriver<TestData>(db, 1);
+
+            await driver.set('tags', ['a', 'b', 'c']);
+
+            expect(await driver.get('tags')).toEqual(['a', 'b', 'c']);
+        });
+
+        it('sets and retrieves an object value', async () => {
+            type ObjData = { meta: { nested: boolean; value: number } };
+
+            let db = uid(),
+                driver = new IndexedDBDriver<ObjData>(db, 1),
+                obj = { nested: true, value: 42 };
+
+            await driver.set('meta', obj);
+
+            expect(await driver.get('meta')).toEqual(obj);
+        });
+    });
+});