strata-storage 2.7.0 → 2.7.1

package/dist/core/Strata.js

@@ -63,7 +63,13 @@ export class Strata {
      */
     async initialize() {
         if (!this._readyPromise) {
-            this._readyPromise = this._performInitialization();
+            // On failure, clear the cached promise so a later call can retry instead
+            // of permanently re-awaiting a rejected promise (e.g. a transient adapter
+            // error during init should not brick the instance forever).
+            this._readyPromise = this._performInitialization().catch((error) => {
+                this._readyPromise = undefined;
+                throw error;
+            });
         }
         return this._readyPromise;
     }
@@ -441,12 +447,42 @@ export class Strata {
             // Fast path: an unfiltered, un-namespaced clear wipes the whole adapter.
             if (!needsInspection) {
                 await adapter.clear();
+                // Propagate the full clear cross-tab so other tabs converge, matching
+                // the set/remove broadcasts. ONLY full clears broadcast — a filtered or
+                // namespaced clear must not wipe the whole adapter elsewhere.
+                // localStorage/sessionStorage propagate natively and are skipped on the
+                // receiving side; applyRemoteChange clears the adapter directly (no
+                // re-broadcast), so there is no sync loop.
+                if (this.syncManager) {
+                    this.syncManager.broadcast({
+                        type: 'clear',
+                        storage: adapter.name,
+                        timestamp: Date.now(),
+                    });
+                }
+                continue;
+            }
+            // `expiredOnly` with no other narrowing filter: delegate to the adapter's
+            // bulk expired-reclamation when it has one (SQLite reaps in a single
+            // DELETE). The key-inspection loop below cannot reach expired rows on
+            // backends whose keys() already filters them out (SQLite filters in SQL),
+            // so without this it would be a silent no-op there.
+            if (options?.expiredOnly &&
+                !ns &&
+                !options?.prefix &&
+                !options?.pattern &&
+                !options?.tags &&
+                olderThanTs === undefined &&
+                typeof adapter.cleanupExpired === 'function') {
+                await adapter.cleanupExpired();
                 continue;
             }
             // Filtered/namespaced clear: inspect keys and remove only the matches.
-            const scopedPrefix = ns ? `${ns}:${options?.prefix ?? ''}` : options?.prefix;
+            const scopedPrefix = ns
+                ? `${this.namespacePrefix(ns)}${options?.prefix ?? ''}`
+                : options?.prefix;
             for (const physicalKey of await adapter.keys()) {
-                if (ns && !physicalKey.startsWith(`${ns}:`))
+                if (ns && !physicalKey.startsWith(this.namespacePrefix(ns)))
                     continue;
                 if (scopedPrefix && !physicalKey.startsWith(scopedPrefix))
                     continue;
@@ -641,11 +677,22 @@ export class Strata {
             try {
                 if (!needsInspection) {
                     adapter.clearSync();
+                    // Propagate the full clear cross-tab (see clear()). Only full clears
+                    // broadcast; localStorage/sessionStorage are skipped on receive.
+                    if (this.syncManager) {
+                        this.syncManager.broadcast({
+                            type: 'clear',
+                            storage: adapter.name,
+                            timestamp: Date.now(),
+                        });
+                    }
                     continue;
                 }
-                const scopedPrefix = ns ? `${ns}:${options?.prefix ?? ''}` : options?.prefix;
+                const scopedPrefix = ns
+                    ? `${this.namespacePrefix(ns)}${options?.prefix ?? ''}`
+                    : options?.prefix;
                 for (const physicalKey of adapter.keysSync()) {
-                    if (ns && !physicalKey.startsWith(`${ns}:`))
+                    if (ns && !physicalKey.startsWith(this.namespacePrefix(ns)))
                         continue;
                     if (scopedPrefix && !physicalKey.startsWith(scopedPrefix))
                         continue;
@@ -720,11 +767,21 @@ export class Strata {
     computeExpiration(options) {
         if (this.ttlManager)
             return this.ttlManager.calculateExpiration(options);
-        if (typeof options?.ttl === 'number')
-            return Date.now() + options.ttl;
+        // Pre-init fallback: mirror TTLManager.calculateExpiration's precedence
+        // (expireAt > expireAfter > ttl > defaultTTL) and past-guarding, so a write
+        // issued before initialize() expires identically to one issued after.
         if (options?.expireAt !== undefined) {
-            return typeof options.expireAt === 'number' ? options.expireAt : options.expireAt.getTime();
+            const t = options.expireAt instanceof Date ? options.expireAt.getTime() : options.expireAt;
+            return t > Date.now() ? t : undefined;
         }
+        if (options?.expireAfter !== undefined) {
+            const t = options.expireAfter instanceof Date ? options.expireAfter.getTime() : options.expireAfter;
+            return t > Date.now() ? t : undefined;
+        }
+        if (typeof options?.ttl === 'number')
+            return Date.now() + options.ttl;
+        if (this.config.ttl?.defaultTTL)
+            return Date.now() + this.config.ttl.defaultTTL;
         return undefined;
     }
     /**
@@ -752,7 +809,7 @@ export class Strata {
                 continue;
             }
             let storageTotal = 0;
-            const prefix = `${ns}:`;
+            const prefix = this.namespacePrefix(ns);
             for (const physicalKey of await adapter.keys()) {
                 if (!physicalKey.startsWith(prefix))
                     continue;
@@ -797,7 +854,7 @@ export class Strata {
                     callback(change);
                     return;
                 }
-                const prefix = `${ns}:`;
+                const prefix = this.namespacePrefix(ns);
                 if (!change.key.startsWith(prefix))
                     return;
                 callback({ ...change, key: change.key.slice(prefix.length) });
@@ -847,9 +904,9 @@ export class Strata {
         // integrity repair, decryption, and decompression.
         const decoded = [];
         for (const physicalKey of rawKeys) {
-            if (ns && !physicalKey.startsWith(`${ns}:`))
+            if (ns && !physicalKey.startsWith(this.namespacePrefix(ns)))
                 continue;
-            const logicalKey = ns ? physicalKey.slice(ns.length + 1) : physicalKey;
+            const logicalKey = ns ? physicalKey.slice(this.namespacePrefix(ns).length) : physicalKey;
             if (!isValidKey(logicalKey))
                 continue;
             const value = await this.get(logicalKey, options);
@@ -1136,8 +1193,8 @@ export class Strata {
         const items = await this.ttlManager.getExpiring(timeWindow, () => adapter.keys(), (physicalKey) => adapter.get(physicalKey));
         return ns
             ? items
-                .filter((item) => item.key.startsWith(`${ns}:`))
-                .map((item) => ({ ...item, key: item.key.slice(ns.length + 1) }))
+                .filter((item) => item.key.startsWith(this.namespacePrefix(ns)))
+                .map((item) => ({ ...item, key: item.key.slice(this.namespacePrefix(ns).length) }))
             : items;
     }
     /**
@@ -1158,7 +1215,7 @@ export class Strata {
         const ns = this.effectiveNamespace(options);
         const expired = await this.ttlManager.cleanup(async () => {
             const keys = await adapter.keys();
-            return ns ? keys.filter((key) => key.startsWith(`${ns}:`)) : keys;
+            return ns ? keys.filter((key) => key.startsWith(this.namespacePrefix(ns))) : keys;
         }, (physicalKey) => adapter.get(physicalKey), (physicalKey) => adapter.remove(physicalKey));
         return expired.length;
     }
@@ -1248,7 +1305,14 @@ export class Strata {
                 : [config.defaultStorage, ...existing];
         }
         if (!normalized.defaultStorages || normalized.defaultStorages.length === 0) {
-            normalized.defaultStorages = ['memory'];
+            // Persistent-first, matching the default `storage` singleton: prefer
+            // durable backends so writes survive a reload, with sync-capable
+            // localStorage ahead of async-only indexedDB, and volatile `memory` as the
+            // last-resort fallback (SSR / no web storage). selectDefaultAdapter only
+            // picks from adapters that are actually available, so unusable entries are
+            // skipped. (A bare instance previously defaulted to memory-only, silently
+            // contradicting the documented persistent-first behavior.)
+            normalized.defaultStorages = ['localStorage', 'indexedDB', 'sessionStorage', 'memory'];
         }
         return normalized;
     }
@@ -1266,14 +1330,30 @@ export class Strata {
         const ns = options?.namespace ?? this.config.namespace;
         return ns && ns.length > 0 ? ns : undefined;
     }
+    /**
+     * Encode a namespace into an unambiguous physical-key prefix component.
+     * `:` is a legal character in user keys, so a bare `${ns}:${key}` join lets
+     * namespace `a` + key `b:c` collide with namespace `a:b` + key `c` (both
+     * `a:b:c`), leaking keys across namespaces. Percent-encoding `:` (and the `%`
+     * escape itself) in the namespace component removes the ambiguity while
+     * leaving the user key — including any `:` — untouched. Namespaces without a
+     * `:` are unchanged, so existing namespaced data keeps the same physical key.
+     */
+    encodeNamespace(ns) {
+        return ns.replace(/%/g, '%25').replace(/:/g, '%3A');
+    }
+    /** The physical-key prefix (with trailing `:`) for a namespace. */
+    namespacePrefix(ns) {
+        return `${this.encodeNamespace(ns)}:`;
+    }
     /** Map a logical key to the physical key actually stored (namespace-prefixed). */
     resolveKey(key, options) {
         const ns = this.effectiveNamespace(options);
-        return ns ? `${ns}:${key}` : key;
+        return ns ? `${this.encodeNamespace(ns)}:${key}` : key;
     }
     /** Reduce physical keys to the logical keys owned by `ns`, then apply pattern. */
     scopeAndStripKeys(physicalKeys, ns, pattern) {
-        const prefix = `${ns}:`;
+        const prefix = `${this.encodeNamespace(ns)}:`;
         const logical = physicalKeys
             .filter((key) => key.startsWith(prefix))
             .map((key) => key.slice(prefix.length));
@@ -1296,8 +1376,9 @@ export class Strata {
     getDefaultStorages() {
         // Only return adapters that are actually registered
         const registered = Array.from(this.registry.getAll().keys()).map((key) => String(key));
-        // Prefer these storages in order if available
-        const preferredOrder = ['indexedDB', 'localStorage', 'sessionStorage', 'memory'];
+        // Prefer these storages in order if available (sync-capable localStorage
+        // ahead of async-only indexedDB, mirroring normalizeConfig's default).
+        const preferredOrder = ['localStorage', 'indexedDB', 'sessionStorage', 'memory'];
         const available = preferredOrder.filter((storage) => registered.includes(storage));
         // Always include memory as fallback if registered
         if (available.length === 0 && registered.includes('memory')) {
@@ -1362,8 +1443,25 @@ export class Strata {
         }
     }
     async applyRemoteChange(change) {
-        if (change.source !== 'remote' || !change.key || change.key === '*')
+        if (change.source !== 'remote' || !change.key)
+            return;
+        // A full-clear broadcast arrives as a keyless ('*') change. Apply it to the
+        // matching adapter so cleared state stays consistent cross-tab. Clearing the
+        // adapter directly (not this.clear()) avoids re-broadcasting, so no loop.
+        if (change.key === '*') {
+            if (change.storage === 'localStorage' || change.storage === 'sessionStorage')
+                return;
+            const clearTarget = this.adapters.get(change.storage);
+            if (clearTarget) {
+                try {
+                    await clearTarget.clear();
+                }
+                catch (error) {
+                    logger.warn(`Failed to apply remote clear for "${change.storage}":`, error);
+                }
+            }
             return;
+        }
         if (change.storage === 'localStorage' || change.storage === 'sessionStorage')
             return;
         const adapter = this.adapters.get(change.storage);

package/dist/features/compression.d.ts

@@ -41,22 +41,37 @@ export declare class CompressionManager {
      * Check if data is compressed
      */
     isCompressedData(data: unknown): data is CompressedData;
+    private static readonly FORMAT;
+    private static readonly LZW_MAX_CODE;
     /**
-     * LZ-string compression implementation
+     * LZ compression over UTF-8 bytes.
+     *
+     * The alphabet is bytes (0–255), so the literal-vs-dictionary-code
+     * discriminator (`< 256`) on decompress is correct for ALL input — including
+     * CJK / emoji / symbols whose code points are ≥ 256. (Operating on raw UTF-16
+     * chars previously misclassified any such literal as a dictionary code and
+     * silently corrupted the stored value, or threw on read.)
      */
     private lzCompress;
     /**
-     * LZ-string decompression implementation
+     * LZ decompression — inverse of {@link lzCompress}, reconstructing UTF-8 bytes
+     * then decoding them back to the original string.
      */
     private lzDecompress;
+    private static readonly B64_CHARS;
+    /** Base64-encode raw bytes (btoa when available, else a pure-JS fallback). */
+    private bytesToBase64;
+    /** Decode a base64 string back to raw bytes (atob when available, else pure-JS). */
+    private base64ToBytes;
     /**
-     * Base64 encoding for compressed data
+     * Legacy decoder for payloads written by <= 2.7.0 (algorithm 'lz'): the
+     * original UTF-16-char LZW over the raw string with a `decodeURIComponent`
+     * base64 layer. Kept read-only so existing compressed-at-rest values still
+     * decode after upgrading to the current byte-LZW codec. (That codec corrupted
+     * non-Latin1 input, so legacy payloads are Latin1 in practice.)
      */
-    private encodeToBase64;
-    /**
-     * Base64 decoding for compressed data
-     */
-    private decodeFromBase64;
+    private legacyLzDecompress;
+    private legacyDecodeFromBase64;
     /**
      * Get compression ratio
      */

package/dist/features/compression.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"compression.d.ts","sourceRoot":"","sources":["../../src/features/compression.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,SAAS,CAAC,EAAE,IAAI,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc,EAAE,MAAM,CAAC;CACxB;AAED;;GAEG;AACH,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,MAAM,CAA8B;gBAEhC,MAAM,GAAE,iBAAsB;IAQ1C;;OAEG;IACG,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,cAAc,GAAG,OAAO,CAAC;IA8BhE;;OAEG;IACG,UAAU,CAAC,CAAC,GAAG,OAAO,EAAE,cAAc,EAAE,cAAc,GAAG,OAAO,CAAC,CAAC,CAAC;IAazE;;OAEG;IACH,gBAAgB,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,IAAI,cAAc;IAWvD;;OAEG;IACH,OAAO,CAAC,UAAU;IAmClB;;OAEG;IACH,OAAO,CAAC,YAAY;IA+BpB;;OAEG;IACH,OAAO,CAAC,cAAc;IA2BtB;;OAEG;IACH,OAAO,CAAC,gBAAgB;IA6BxB;;OAEG;IACH,mBAAmB,CAAC,cAAc,EAAE,cAAc,GAAG,MAAM;IAI3D;;OAEG;IACH,oBAAoB,CAAC,cAAc,EAAE,cAAc,GAAG,MAAM;CAO7D"}
+{"version":3,"file":"compression.d.ts","sourceRoot":"","sources":["../../src/features/compression.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,SAAS,CAAC,EAAE,IAAI,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc,EAAE,MAAM,CAAC;CACxB;AAED;;GAEG;AACH,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,MAAM,CAA8B;gBAEhC,MAAM,GAAE,iBAAsB;IAQ1C;;OAEG;IACG,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,cAAc,GAAG,OAAO,CAAC;IAkChE;;OAEG;IACG,UAAU,CAAC,CAAC,GAAG,OAAO,EAAE,cAAc,EAAE,cAAc,GAAG,OAAO,CAAC,CAAC,CAAC;IAmBzE;;OAEG;IACH,gBAAgB,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,IAAI,cAAc;IAcvD,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAW;IAMzC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,YAAY,CAAU;IAE9C;;;;;;;;OAQG;IACH,OAAO,CAAC,UAAU;IAmClB;;;OAGG;IACH,OAAO,CAAC,YAAY;IA4CpB,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,SAAS,CACoC;IAErE,8EAA8E;IAC9E,OAAO,CAAC,aAAa;IAyBrB,oFAAoF;IACpF,OAAO,CAAC,aAAa;IA2BrB;;;;;;OAMG;IACH,OAAO,CAAC,kBAAkB;IA8B1B,OAAO,CAAC,sBAAsB;IAiB9B;;OAEG;IACH,mBAAmB,CAAC,cAAc,EAAE,cAAc,GAAG,MAAM;IAI3D;;OAEG;IACH,oBAAoB,CAAC,cAAc,EAAE,cAAc,GAAG,MAAM;CAO7D"}

package/dist/features/compression.js

@@ -34,8 +34,12 @@ export class CompressionManager {
                 return data;
             }
             return {
+                // Tag the on-disk format so decompress() can pick the right decoder.
+                // Older releases wrote `algorithm: 'lz'` with a UTF-16-char codec that
+                // corrupted non-Latin1 data; the current byte-LZW format is tagged
+                // distinctly and old 'lz' payloads still read via the legacy path.
                 data: compressed,
-                algorithm: this.config.algorithm,
+                algorithm: CompressionManager.FORMAT,
                 originalSize,
                 compressedSize,
             };
@@ -52,7 +56,12 @@ export class CompressionManager {
             if (!this.isCompressedData(compressedData)) {
                 return compressedData;
             }
-            const decompressed = this.lzDecompress(compressedData.data);
+            // Route by stored format tag: the current byte-LZW format vs. the legacy
+            // UTF-16-char codec written by <= 2.7.0 (algorithm 'lz'), so existing
+            // compressed-at-rest values keep decoding after upgrade.
+            const decompressed = compressedData.algorithm === CompressionManager.FORMAT
+                ? this.lzDecompress(compressedData.data)
+                : this.legacyLzDecompress(compressedData.data);
             return JSON.parse(decompressed);
         }
         catch (error) {
@@ -70,120 +79,198 @@ export class CompressionManager {
             'originalSize' in data &&
             'compressedSize' in data);
     }
+    // Format tag stored in CompressedData.algorithm for the current byte-LZW
+    // codec. Payloads written by <= 2.7.0 are tagged 'lz' and decode via the
+    // legacy path; anything tagged FORMAT uses the current decoder.
+    static FORMAT = 'lz-u8';
+    // Freeze the LZW dictionary at 16 bits so every token serializes to exactly
+    // two bytes; both encoder and decoder stop growing the dictionary at the same
+    // point, staying in sync. 0xFFFF entries is ample for storage-sized values;
+    // beyond it, already-learned phrases still compress, just no new ones.
+    static LZW_MAX_CODE = 0xffff;
     /**
-     * LZ-string compression implementation
+     * LZ compression over UTF-8 bytes.
+     *
+     * The alphabet is bytes (0–255), so the literal-vs-dictionary-code
+     * discriminator (`< 256`) on decompress is correct for ALL input — including
+     * CJK / emoji / symbols whose code points are ≥ 256. (Operating on raw UTF-16
+     * chars previously misclassified any such literal as a dictionary code and
+     * silently corrupted the stored value, or threw on read.)
      */
     lzCompress(uncompressed) {
-        if (uncompressed == null)
+        const bytes = new TextEncoder().encode(uncompressed);
+        if (bytes.length === 0)
             return '';
-        const context = new Map();
-        const out = [];
-        let currentChar;
-        let phrase = uncompressed.charAt(0);
-        let code = 256;
-        for (let i = 1; i < uncompressed.length; i++) {
-            currentChar = uncompressed.charAt(i);
-            if (context.has(phrase + currentChar)) {
-                phrase += currentChar;
+        const dictionary = new Map();
+        let nextCode = 256;
+        const tokens = [];
+        let phrase = String.fromCharCode(bytes[0]); // byte-string (each char 0–255)
+        for (let i = 1; i < bytes.length; i++) {
+            const current = String.fromCharCode(bytes[i]);
+            const combined = phrase + current;
+            if (dictionary.has(combined)) {
+                phrase = combined;
             }
             else {
-                if (phrase.length > 1) {
-                    out.push(String.fromCharCode(context.get(phrase)));
-                }
-                else {
-                    out.push(phrase);
+                // `phrase` is always either a single byte (literal) or an existing
+                // dictionary entry, so the lookup below is always defined.
+                tokens.push(phrase.length === 1 ? phrase.charCodeAt(0) : dictionary.get(phrase));
+                if (nextCode <= CompressionManager.LZW_MAX_CODE) {
+                    dictionary.set(combined, nextCode++);
                 }
-                context.set(phrase + currentChar, code);
-                code++;
-                phrase = currentChar;
+                phrase = current;
             }
         }
-        if (phrase.length > 1) {
-            out.push(String.fromCharCode(context.get(phrase)));
+        tokens.push(phrase.length === 1 ? phrase.charCodeAt(0) : dictionary.get(phrase));
+        // Serialize each token as a 16-bit big-endian value, then base64.
+        const out = new Uint8Array(tokens.length * 2);
+        for (let i = 0; i < tokens.length; i++) {
+            out[i * 2] = (tokens[i] >> 8) & 0xff;
+            out[i * 2 + 1] = tokens[i] & 0xff;
         }
-        else {
-            out.push(phrase);
-        }
-        return this.encodeToBase64(out.join(''));
+        return this.bytesToBase64(out);
     }
     /**
-     * LZ-string decompression implementation
+     * LZ decompression — inverse of {@link lzCompress}, reconstructing UTF-8 bytes
+     * then decoding them back to the original string.
      */
     lzDecompress(compressed) {
-        if (compressed == null)
+        if (!compressed)
             return '';
-        if (compressed === '')
+        const inBytes = this.base64ToBytes(compressed);
+        const tokenCount = inBytes.length >> 1;
+        if (tokenCount === 0)
             return '';
-        const decoded = this.decodeFromBase64(compressed);
         const dictionary = new Map();
-        let currentChar = decoded.charAt(0);
-        let oldPhrase = currentChar;
-        const out = [currentChar];
-        let code = 256;
-        let phrase;
-        for (let i = 1; i < decoded.length; i++) {
-            const currentCode = decoded.charCodeAt(i);
-            if (currentCode < 256) {
-                phrase = decoded.charAt(i);
+        let nextCode = 256;
+        const readToken = (i) => (inBytes[i * 2] << 8) | inBytes[i * 2 + 1];
+        // The first token is always a literal byte (the dictionary starts empty).
+        let oldPhrase = String.fromCharCode(readToken(0));
+        const out = [oldPhrase];
+        for (let i = 1; i < tokenCount; i++) {
+            const code = readToken(i);
+            let phrase;
+            if (code < 256) {
+                phrase = String.fromCharCode(code);
+            }
+            else if (dictionary.has(code)) {
+                phrase = dictionary.get(code);
             }
             else {
-                phrase = dictionary.get(currentCode) || oldPhrase + currentChar;
+                // Classic LZW edge: the code equals the entry we are about to define.
+                phrase = oldPhrase + oldPhrase.charAt(0);
             }
             out.push(phrase);
-            currentChar = phrase.charAt(0);
-            dictionary.set(code, oldPhrase + currentChar);
-            code++;
+            if (nextCode <= CompressionManager.LZW_MAX_CODE) {
+                dictionary.set(nextCode++, oldPhrase + phrase.charAt(0));
+            }
             oldPhrase = phrase;
         }
-        return out.join('');
+        // `out` holds byte-strings; rebuild the byte sequence and UTF-8 decode it.
+        const joined = out.join('');
+        const bytes = new Uint8Array(joined.length);
+        for (let i = 0; i < joined.length; i++) {
+            bytes[i] = joined.charCodeAt(i) & 0xff;
+        }
+        return new TextDecoder().decode(bytes);
     }
-    /**
-     * Base64 encoding for compressed data
-     */
-    encodeToBase64(input) {
+    static B64_CHARS = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+    /** Base64-encode raw bytes (btoa when available, else a pure-JS fallback). */
+    bytesToBase64(bytes) {
         if (typeof btoa !== 'undefined') {
-            // Browser environment
-            return btoa(unescape(encodeURIComponent(input)));
+            let binary = '';
+            const chunk = 0x8000;
+            for (let i = 0; i < bytes.length; i += chunk) {
+                binary += String.fromCharCode(...bytes.subarray(i, i + chunk));
+            }
+            return btoa(binary);
         }
-        // Pure JS implementation for Node.js or other environments
-        const chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/=';
+        const chars = CompressionManager.B64_CHARS;
         let result = '';
-        let i = 0;
-        while (i < input.length) {
-            const a = input.charCodeAt(i++);
-            const b = i < input.length ? input.charCodeAt(i++) : 0;
-            const c = i < input.length ? input.charCodeAt(i++) : 0;
+        for (let i = 0; i < bytes.length; i += 3) {
+            const a = bytes[i];
+            const b = i + 1 < bytes.length ? bytes[i + 1] : 0;
+            const c = i + 2 < bytes.length ? bytes[i + 2] : 0;
             const bitmap = (a << 16) | (b << 8) | c;
             result += chars.charAt((bitmap >> 18) & 63);
             result += chars.charAt((bitmap >> 12) & 63);
-            result += i - 2 < input.length ? chars.charAt((bitmap >> 6) & 63) : '=';
-            result += i - 1 < input.length ? chars.charAt(bitmap & 63) : '=';
+            result += i + 1 < bytes.length ? chars.charAt((bitmap >> 6) & 63) : '=';
+            result += i + 2 < bytes.length ? chars.charAt(bitmap & 63) : '=';
         }
         return result;
     }
+    /** Decode a base64 string back to raw bytes (atob when available, else pure-JS). */
+    base64ToBytes(input) {
+        if (typeof atob !== 'undefined') {
+            const binary = atob(input);
+            const bytes = new Uint8Array(binary.length);
+            for (let i = 0; i < binary.length; i++) {
+                bytes[i] = binary.charCodeAt(i) & 0xff;
+            }
+            return bytes;
+        }
+        const chars = CompressionManager.B64_CHARS;
+        const clean = input.replace(/[^A-Za-z0-9+/]/g, '');
+        const bytes = [];
+        for (let i = 0; i < clean.length; i += 4) {
+            const e1 = chars.indexOf(clean.charAt(i));
+            const e2 = chars.indexOf(clean.charAt(i + 1));
+            const e3 = chars.indexOf(clean.charAt(i + 2));
+            const e4 = chars.indexOf(clean.charAt(i + 3));
+            const bitmap = (e1 << 18) | (Math.max(e2, 0) << 12) | (Math.max(e3, 0) << 6) | Math.max(e4, 0);
+            bytes.push((bitmap >> 16) & 255);
+            if (e3 !== -1)
+                bytes.push((bitmap >> 8) & 255);
+            if (e4 !== -1)
+                bytes.push(bitmap & 255);
+        }
+        return new Uint8Array(bytes);
+    }
     /**
-     * Base64 decoding for compressed data
+     * Legacy decoder for payloads written by <= 2.7.0 (algorithm 'lz'): the
+     * original UTF-16-char LZW over the raw string with a `decodeURIComponent`
+     * base64 layer. Kept read-only so existing compressed-at-rest values still
+     * decode after upgrading to the current byte-LZW codec. (That codec corrupted
+     * non-Latin1 input, so legacy payloads are Latin1 in practice.)
      */
-    decodeFromBase64(input) {
-        if (typeof atob !== 'undefined') {
-            // Browser environment
-            return decodeURIComponent(escape(atob(input)));
+    legacyLzDecompress(compressed) {
+        if (!compressed)
+            return '';
+        const decoded = typeof atob !== 'undefined'
+            ? decodeURIComponent(escape(atob(compressed)))
+            : this.legacyDecodeFromBase64(compressed);
+        const dictionary = new Map();
+        let currentChar = decoded.charAt(0);
+        let oldPhrase = currentChar;
+        const out = [currentChar];
+        let code = 256;
+        for (let i = 1; i < decoded.length; i++) {
+            const currentCode = decoded.charCodeAt(i);
+            const phrase = currentCode < 256
+                ? decoded.charAt(i)
+                : dictionary.get(currentCode) || oldPhrase + currentChar;
+            out.push(phrase);
+            currentChar = phrase.charAt(0);
+            dictionary.set(code, oldPhrase + currentChar);
+            code++;
+            oldPhrase = phrase;
         }
-        // Pure JS implementation
-        const chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/=';
+        return out.join('');
+    }
+    legacyDecodeFromBase64(input) {
+        const chars = `${CompressionManager.B64_CHARS}=`;
         let result = '';
-        let i = 0;
-        input = input.replace(/[^A-Za-z0-9+/]/g, '');
-        while (i < input.length) {
-            const encoded1 = chars.indexOf(input.charAt(i++));
-            const encoded2 = chars.indexOf(input.charAt(i++));
-            const encoded3 = chars.indexOf(input.charAt(i++));
-            const encoded4 = chars.indexOf(input.charAt(i++));
-            const bitmap = (encoded1 << 18) | (encoded2 << 12) | (encoded3 << 6) | encoded4;
+        const clean = input.replace(/[^A-Za-z0-9+/]/g, '');
+        for (let i = 0; i < clean.length; i += 4) {
+            const e1 = chars.indexOf(clean.charAt(i));
+            const e2 = chars.indexOf(clean.charAt(i + 1));
+            const e3 = chars.indexOf(clean.charAt(i + 2));
+            const e4 = chars.indexOf(clean.charAt(i + 3));
+            const bitmap = (e1 << 18) | (e2 << 12) | (e3 << 6) | e4;
             result += String.fromCharCode((bitmap >> 16) & 255);
-            if (encoded3 !== 64)
+            if (e3 !== 64 && e3 !== -1)
                 result += String.fromCharCode((bitmap >> 8) & 255);
-            if (encoded4 !== 64)
+            if (e4 !== 64 && e4 !== -1)
                 result += String.fromCharCode(bitmap & 255);
         }
         return result;

package/dist/features/migration.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"migration.d.ts","sourceRoot":"","sources":["../../src/features/migration.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE9C,MAAM,WAAW,SAAS;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,EAAE,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/C,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACnD;AAED,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,UAAU,CAAmB;IAErC,QAAQ,CAAC,SAAS,EAAE,SAAS,GAAG,IAAI;IAK9B,OAAO,CAAC,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;YA0B9D,iBAAiB;YAKjB,UAAU;CAOzB"}
+{"version":3,"file":"migration.d.ts","sourceRoot":"","sources":["../../src/features/migration.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAG9C,MAAM,WAAW,SAAS;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,EAAE,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/C,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACnD;AAED,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,UAAU,CAAmB;IAErC,QAAQ,CAAC,SAAS,EAAE,SAAS,GAAG,IAAI;IAK9B,OAAO,CAAC,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;YAgC9D,iBAAiB;YAKjB,UAAU;CAOzB"}

package/dist/features/migration.js

@@ -1,6 +1,7 @@
 /**
  * Migration utilities for storage upgrades
  */
+import { MigrationError } from "../utils/errors.js";
 export class MigrationManager {
     migrations = [];
     register(migration) {
@@ -22,9 +23,13 @@ export class MigrationManager {
         }
         else {
             for (const migration of migrationsToRun.reverse()) {
-                if (migration.down) {
-                    await migration.down(adapter);
+                // An irreversible migration must NOT silently lower the stored version
+                // (that would claim a rollback that never reverted the data). Fail
+                // before touching anything so the version stays consistent with data.
+                if (!migration.down) {
+                    throw new MigrationError(`Cannot roll back migration ${migration.version}: it has no down() and is irreversible.`);
                 }
+                await migration.down(adapter);
                 await this.setVersion(adapter, migration.version - 1);
             }
         }

package/dist/features/query.d.ts

@@ -68,6 +68,7 @@ export declare class QueryEngine {
     /**
      * Set nested value in object using dot notation
      */
+    private static readonly FORBIDDEN_KEYS;
     private setNestedValue;
     /**
      * Delete nested value from object using dot notation