strata-storage 2.7.0 → 2.8.0

package/dist/adapters/web/SessionStorageAdapter.d.ts

@@ -74,4 +74,3 @@ export declare class SessionStorageAdapter extends LocalStorageAdapter {
      */
     subscribe(callback: import("../../types/index.js").SubscriptionCallback): import("../../types/index.js").UnsubscribeFunction;
 }
-//# sourceMappingURL=SessionStorageAdapter.d.ts.map

package/dist/adapters/web/SessionStorageAdapter.js

@@ -115,7 +115,20 @@ export class SessionStorageAdapter extends LocalStorageAdapter {
      * Remove a value from sessionStorage (synchronous)
      */
     removeSync(key) {
-        const oldValue = this.getSync(key);
+        // Read raw — NOT via getSync(), which deletes expired entries by calling
+        // removeSync() and would recurse here forever. Only read with a listener.
+        let oldValue = null;
+        if (this.hasChangeListeners()) {
+            const item = window.sessionStorage.getItem(this.prefix + key);
+            if (item) {
+                try {
+                    oldValue = deserialize(item);
+                }
+                catch {
+                    oldValue = null;
+                }
+            }
+        }
         window.sessionStorage.removeItem(this.prefix + key);
         if (oldValue) {
             this.emitChange(key, oldValue.value, undefined, 'local');

package/dist/adapters/web/URLAdapter.d.ts

@@ -56,4 +56,3 @@ export declare class URLAdapter extends BaseAdapter {
     private snapshotParams;
     private handleExternalChange;
 }
-//# sourceMappingURL=URLAdapter.d.ts.map

package/dist/adapters/web/index.d.ts

@@ -8,4 +8,3 @@ export { IndexedDBAdapter } from "./IndexedDBAdapter.js";
 export { CookieAdapter } from "./CookieAdapter.js";
 export { CacheAdapter } from "./CacheAdapter.js";
 export { URLAdapter, type URLAdapterConfig } from "./URLAdapter.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/capacitor.d.ts

@@ -17,4 +17,3 @@ export declare function isCapacitorEnvironment(): boolean;
  * Get Capacitor-specific storage types
  */
 export declare function getCapacitorStorageTypes(): string[];
-//# sourceMappingURL=capacitor.d.ts.map

package/dist/config/support.d.ts

@@ -7,4 +7,3 @@ export declare const SUPPORT_CONFIG: {
     readonly label: "Support the Project";
     readonly description: "Help us keep strata-storage free and improving";
 };
-//# sourceMappingURL=support.d.ts.map

package/dist/core/AdapterRegistry.d.ts

@@ -49,4 +49,3 @@ export declare class AdapterRegistry {
      */
     closeAll(): Promise<void>;
 }
-//# sourceMappingURL=AdapterRegistry.d.ts.map

package/dist/core/BaseAdapter.d.ts

@@ -100,4 +100,3 @@ export declare abstract class BaseAdapter implements StorageAdapter {
     abstract remove(key: string): Promise<void>;
     abstract keys(pattern?: string | RegExp): Promise<string[]>;
 }
-//# sourceMappingURL=BaseAdapter.d.ts.map

package/dist/core/Strata.d.ts

@@ -336,6 +336,18 @@ export declare class Strata {
     /** Effective namespace for an operation: a per-call value wins over the
      * instance default (`config.namespace`). Empty strings are treated as none. */
     private effectiveNamespace;
+    /**
+     * 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.
+     */
+    private encodeNamespace;
+    /** The physical-key prefix (with trailing `:`) for a namespace. */
+    private namespacePrefix;
     /** Map a logical key to the physical key actually stored (namespace-prefixed). */
     private resolveKey;
     /** Reduce physical keys to the logical keys owned by `ns`, then apply pattern. */
@@ -363,4 +375,3 @@ export declare class Strata {
     private startAutoBackup;
     private selectAdapter;
 }
-//# sourceMappingURL=Strata.d.ts.map

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/index.d.ts

@@ -1,2 +1 @@
 export * from "../compression.js";
-//# sourceMappingURL=index.d.ts.map

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
      */
@@ -66,4 +81,3 @@ export declare class CompressionManager {
      */
     getSavingsPercentage(compressedData: CompressedData): number;
 }
-//# sourceMappingURL=compression.d.ts.map