strata-storage 2.8.4 → 2.9.0

package/dist/adapters/web/LocalStorageAdapter.js

@@ -3,7 +3,7 @@
  * Provides persistent storage with 5-10MB limit
  */
 import { BaseAdapter } from "../../core/BaseAdapter.js";
-import { serialize, deserialize, getObjectSize } from "../../utils/index.js";
+import { serialize, getObjectSize } from "../../utils/index.js";
 import { QuotaExceededError, SerializationError, StorageError } from "../../utils/errors.js";
 import { logger } from "../../utils/logger.js";
 /**
@@ -47,14 +47,39 @@ export class LocalStorageAdapter extends BaseAdapter {
         }
     }
     /**
-     * Initialize the adapter
+     * Apply configuration synchronously. See `BaseAdapter.configure` for why the
+     * prefix cannot wait for the async `initialize()`.
      */
-    async initialize(config) {
-        if (config?.prefix) {
+    configure(config) {
+        if (config?.prefix !== undefined) {
             this.prefix = config.prefix;
         }
+    }
+    /**
+     * Initialize the adapter
+     */
+    async initialize(config) {
+        this.configure(config);
         this.startTTLCleanup();
     }
+    /**
+     * Whether this storage area is usable RIGHT NOW, without awaiting anything.
+     * The synchronous API needs this: `defaultStorages` reads as an ordered
+     * fallback list, and without a sync probe `setSync` selects an unusable
+     * backend and throws instead of falling through to the next one.
+     */
+    isAvailableSync() {
+        try {
+            const storage = this.getStorage();
+            const testKey = `${this.prefix}__test__`;
+            storage.setItem(testKey, 'test');
+            storage.removeItem(testKey);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
     /**
      * Get the backing Storage object.
      * Subclasses (e.g. SessionStorageAdapter) override this to target a
@@ -77,22 +102,27 @@ export class LocalStorageAdapter extends BaseAdapter {
      * Get a value from localStorage (synchronous)
      */
     getSync(key) {
+        let item;
         try {
-            const item = this.getStorage().getItem(this.prefix + key);
-            if (!item)
-                return null;
-            const value = deserialize(item);
-            // Check TTL
-            if (this.isExpired(value)) {
-                this.removeSync(key);
-                return null;
-            }
-            return value;
+            item = this.getStorage().getItem(this.prefix + key);
         }
         catch (error) {
-            logger.error(`Failed to get key ${key} from ${this.name}:`, error);
+            // A genuine storage-access fault — the area is blocked (private mode, a
+            // cookie policy, a SecurityError on an opaque origin). This one IS ours to
+            // report: the read we were asked for did not happen.
+            logger.error(`Failed to read key ${key} from ${this.name}:`, error);
+            return null;
+        }
+        // A value that is not our envelope belongs to somebody else sharing this
+        // area. parseOwnValue() logs it at debug and returns null — never an error.
+        const value = this.parseOwnValue(item, key);
+        if (!value)
+            return null;
+        if (this.isExpired(value)) {
+            this.removeSync(key);
             return null;
         }
+        return value;
     }
     /**
      * Set a value in localStorage
@@ -137,15 +167,7 @@ export class LocalStorageAdapter extends BaseAdapter {
         // overflow). Only read when a listener actually needs the old value.
         let oldValue = null;
         if (this.hasChangeListeners()) {
-            const item = this.getStorage().getItem(this.prefix + key);
-            if (item) {
-                try {
-                    oldValue = deserialize(item);
-                }
-                catch {
-                    oldValue = null;
-                }
-            }
+            oldValue = this.parseOwnValue(this.getStorage().getItem(this.prefix + key), key);
         }
         this.getStorage().removeItem(this.prefix + key);
         if (oldValue) {
@@ -164,37 +186,33 @@ export class LocalStorageAdapter extends BaseAdapter {
     clearSync(options) {
         if (!options ||
             (!options.pattern && !options.prefix && !options.tags && !options.expiredOnly)) {
-            // Clear all with our prefix
+            // Clear everything WE wrote — never the whole area. With an empty prefix a
+            // name-only sweep here deletes every key on the origin, including another
+            // application's; ownKeys() bounds it to our own envelopes.
             const storage = this.getStorage();
-            const keysToRemove = [];
-            for (let i = 0; i < storage.length; i++) {
-                const key = storage.key(i);
-                if (key?.startsWith(this.prefix)) {
-                    keysToRemove.push(key);
-                }
+            for (const { fullKey } of this.ownKeys(true)) {
+                storage.removeItem(fullKey);
             }
-            keysToRemove.forEach((key) => storage.removeItem(key));
             this.emitChange('*', undefined, undefined, 'local');
             return;
         }
-        // Synchronous filtered clear (mirrors BaseAdapter.clear logic)
-        for (const key of this.keysSync()) {
+        // Synchronous filtered clear (mirrors BaseAdapter.clear logic).
+        // Iterates owned entries INCLUDING expired ones: `expiredOnly` filters on
+        // exactly the entries `keysSync()` leaves out, so driving this loop from
+        // `keysSync()` made that option a guaranteed no-op.
+        for (const { key, value } of this.ownKeys(true)) {
             let shouldDelete = true;
             const pattern = options.pattern || options.prefix;
             if (pattern) {
                 shouldDelete = this.filterKeys([key], pattern).length > 0;
             }
             if (shouldDelete && options.tags) {
-                const value = this.getSync(key);
-                if (!value?.tags || !options.tags.some((tag) => value.tags?.includes(tag))) {
+                if (!value.tags || !options.tags.some((tag) => value.tags?.includes(tag))) {
                     shouldDelete = false;
                 }
             }
-            if (shouldDelete && options.expiredOnly) {
-                const value = this.getSync(key);
-                if (!value || !this.isExpired(value)) {
-                    shouldDelete = false;
-                }
+            if (shouldDelete && options.expiredOnly && !this.isExpired(value)) {
+                shouldDelete = false;
             }
             if (shouldDelete) {
                 this.removeSync(key);
@@ -211,20 +229,53 @@ export class LocalStorageAdapter extends BaseAdapter {
      * Get all keys (synchronous)
      */
     keysSync(pattern) {
+        return this.filterKeys(this.ownKeys().map((entry) => entry.key), pattern);
+    }
+    /**
+     * Every key in this storage area that this adapter actually owns, with the
+     * envelope already parsed (one read per key, not two).
+     *
+     * 🔴 Name is not enough. With the default empty prefix `startsWith(prefix)` is
+     * true for EVERY key on the origin, so this method — not the prefix — is what
+     * keeps `keys()`, the TTL sweep and `clear()` off other scripts' data. An
+     * expired entry is skipped here exactly as before.
+     */
+    ownKeys(includeExpired = false) {
         const storage = this.getStorage();
-        const keys = [];
+        const owned = [];
         for (let i = 0; i < storage.length; i++) {
             const fullKey = storage.key(i);
-            if (fullKey?.startsWith(this.prefix)) {
-                const key = fullKey.substring(this.prefix.length);
-                // Check if not expired
-                const value = this.getSync(key);
-                if (value) {
-                    keys.push(key);
-                }
+            if (!fullKey?.startsWith(this.prefix))
+                continue;
+            const key = fullKey.substring(this.prefix.length);
+            const value = this.parseOwnValue(storage.getItem(fullKey), key);
+            if (!value)
+                continue;
+            if (!includeExpired && this.isExpired(value))
+                continue;
+            owned.push({ key, fullKey, value });
+        }
+        return owned;
+    }
+    /**
+     * Reclaim expired entries, returning how many were removed.
+     *
+     * Overrides the base per-key sweep for two reasons. It reads each key once
+     * instead of twice, and — the load-bearing one — the base sweep is built on
+     * `keys()`, which does not surface expired entries here, so it could only ever
+     * report 0. Before this override the reaping happened as an undocumented side
+     * effect of `getSync()` deleting what it found expired during enumeration,
+     * while the returned count stayed 0.
+     */
+    async cleanupExpired() {
+        let removed = 0;
+        for (const { key, value } of this.ownKeys(true)) {
+            if (this.isExpired(value)) {
+                this.removeSync(key);
+                removed++;
             }
         }
-        return this.filterKeys(keys, pattern);
+        return removed;
     }
     /**
      * Check if key exists (synchronous)
@@ -242,20 +293,21 @@ export class LocalStorageAdapter extends BaseAdapter {
         let keySize = 0;
         let valueSize = 0;
         const byKey = {};
-        for (let i = 0; i < window.localStorage.length; i++) {
-            const fullKey = window.localStorage.key(i);
-            if (fullKey?.startsWith(this.prefix)) {
-                const item = window.localStorage.getItem(fullKey);
-                if (item) {
-                    count++;
-                    const key = fullKey.substring(this.prefix.length);
-                    const itemSize = (fullKey.length + item.length) * 2; // UTF-16
-                    total += itemSize;
-                    if (detailed) {
-                        keySize += fullKey.length * 2;
-                        valueSize += item.length * 2;
-                        byKey[key] = itemSize;
-                    }
+        // `this.getStorage()`, never `window.localStorage` — the subclass points at a
+        // different area, and hard-coding it here made every inherited method wrong
+        // for sessionStorage until the subclass re-implemented it. Owned keys only,
+        // so a shared area is not reported as this adapter's footprint.
+        const storage = this.getStorage();
+        for (const { fullKey, key } of this.ownKeys(true)) {
+            const item = storage.getItem(fullKey);
+            if (item) {
+                count++;
+                const itemSize = (fullKey.length + item.length) * 2; // UTF-16
+                total += itemSize;
+                if (detailed) {
+                    keySize += fullKey.length * 2;
+                    valueSize += item.length * 2;
+                    byKey[key] = itemSize;
                 }
             }
         }
@@ -278,15 +330,27 @@ export class LocalStorageAdapter extends BaseAdapter {
         const unsubscribeLocal = super.subscribe(callback);
         // Also subscribe to remote changes via storage events
         const listener = (event) => {
-            // Only process events from other windows/tabs
-            if (event.storageArea !== window.localStorage)
+            // Only process events from this adapter's own area. Comparing against
+            // `window.localStorage` by name meant the sessionStorage subclass could
+            // never match its own events.
+            let area;
+            try {
+                area = this.getStorage();
+            }
+            catch {
                 return;
-            // Check if the key belongs to us
+            }
+            if (event.storageArea !== area)
+                return;
+            // Check if the key belongs to us — by name AND by shape, since an empty
+            // prefix matches every key another script on this origin writes.
             if (!event.key || !event.key.startsWith(this.prefix))
                 return;
             const key = event.key.substring(this.prefix.length);
-            const oldValue = event.oldValue ? deserialize(event.oldValue) : null;
-            const newValue = event.newValue ? deserialize(event.newValue) : null;
+            const oldValue = this.parseOwnValue(event.oldValue, key);
+            const newValue = this.parseOwnValue(event.newValue, key);
+            if (!oldValue && !newValue)
+                return;
             callback({
                 key,
                 oldValue: oldValue?.value ?? undefined,

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

@@ -20,6 +20,11 @@ export declare class MemoryAdapter extends BaseAdapter {
     /**
      * Initialize the adapter
      */
+    configure(config?: {
+        maxSize?: number;
+    }): void;
+    /** Memory is always usable — no environment can take it away. */
+    isAvailableSync(): boolean;
     initialize(config?: {
         maxSize?: number;
     }): Promise<void>;

package/dist/adapters/web/MemoryAdapter.js

@@ -33,8 +33,16 @@ export class MemoryAdapter extends BaseAdapter {
     /**
      * Initialize the adapter
      */
+    configure(config) {
+        if (config?.maxSize !== undefined)
+            this.maxSize = config.maxSize;
+    }
+    /** Memory is always usable — no environment can take it away. */
+    isAvailableSync() {
+        return true;
+    }
     async initialize(config) {
-        this.maxSize = config?.maxSize;
+        this.configure(config);
         this.startTTLCleanup();
     }
     /**

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

@@ -5,8 +5,20 @@
 import { LocalStorageAdapter } from "./LocalStorageAdapter.js";
 import type { StorageType, StorageCapabilities } from "../../types/index.js";
 /**
- * Browser sessionStorage adapter
- * Extends LocalStorageAdapter as the API is identical
+ * Browser sessionStorage adapter.
+ *
+ * 🔴 This class overrides ONLY what actually differs: the identity, the
+ * capabilities, and which `Storage` object to talk to. Everything else is
+ * inherited, because `LocalStorageAdapter` routes every read and write through
+ * `getStorage()`.
+ *
+ * It used to re-implement `get`/`set`/`remove`/`clear`/`keys`/`size`/`subscribe`
+ * — ~230 lines differing only by naming `window.sessionStorage`. That is how one
+ * defect became two issue numbers: the copy carried its own
+ * `logger.error('Failed to get key … from sessionStorage')`, so fixing the
+ * localStorage path left the sessionStorage path untouched, and the reports came
+ * back separately (ISSUE-01 for `localStorage`, ISSUE-09 for `sessionStorage`,
+ * one root cause). Keep the override surface minimal so that cannot recur.
  */
 export declare class SessionStorageAdapter extends LocalStorageAdapter {
     readonly name: StorageType;
@@ -17,60 +29,8 @@ export declare class SessionStorageAdapter extends LocalStorageAdapter {
      */
     isAvailable(): Promise<boolean>;
     /**
-     * Override all methods to use sessionStorage instead of localStorage
+     * The backing Storage object. This is the ONLY thing that differs from the
+     * parent — every inherited method reads and writes through it.
      */
     protected getStorage(): Storage;
-    /**
-     * Get a value from sessionStorage
-     */
-    get<T = unknown>(key: string): Promise<import("../../types/index.js").StorageValue<T> | null>;
-    /**
-     * Get a value from sessionStorage (synchronous)
-     */
-    getSync<T = unknown>(key: string): import("../../types/index.js").StorageValue<T> | null;
-    /**
-     * Set a value in sessionStorage
-     */
-    set<T = unknown>(key: string, value: import("../../types/index.js").StorageValue<T>): Promise<void>;
-    /**
-     * Set a value in sessionStorage (synchronous)
-     */
-    setSync<T = unknown>(key: string, value: import("../../types/index.js").StorageValue<T>): void;
-    /**
-     * Remove a value from sessionStorage
-     */
-    remove(key: string): Promise<void>;
-    /**
-     * Remove a value from sessionStorage (synchronous)
-     */
-    removeSync(key: string): void;
-    /**
-     * Clear sessionStorage
-     */
-    clear(options?: import("../../types/index.js").ClearOptions): Promise<void>;
-    /**
-     * Clear sessionStorage (synchronous)
-     */
-    clearSync(options?: import("../../types/index.js").ClearOptions): void;
-    /**
-     * Get all keys
-     */
-    keys(pattern?: string | RegExp): Promise<string[]>;
-    /**
-     * Get all keys (synchronous)
-     */
-    keysSync(pattern?: string | RegExp): string[];
-    /**
-     * Check if key exists (synchronous)
-     */
-    hasSync(key: string): boolean;
-    /**
-     * Get storage size
-     */
-    size(detailed?: boolean): Promise<import("../../types/index.js").SizeInfo>;
-    /**
-     * Subscribe to storage changes
-     * Note: sessionStorage doesn't fire storage events in the same tab
-     */
-    subscribe(callback: import("../../types/index.js").SubscriptionCallback): import("../../types/index.js").UnsubscribeFunction;
 }

package/dist/adapters/web/SessionStorageAdapter.js

@@ -3,12 +3,22 @@
  * Provides session-scoped storage with 5-10MB limit
  */
 import { LocalStorageAdapter } from "./LocalStorageAdapter.js";
-import { serialize, deserialize } from "../../utils/index.js";
-import { QuotaExceededError, SerializationError, StorageError } from "../../utils/errors.js";
-import { logger } from "../../utils/logger.js";
+import { StorageError } from "../../utils/errors.js";
 /**
- * Browser sessionStorage adapter
- * Extends LocalStorageAdapter as the API is identical
+ * Browser sessionStorage adapter.
+ *
+ * 🔴 This class overrides ONLY what actually differs: the identity, the
+ * capabilities, and which `Storage` object to talk to. Everything else is
+ * inherited, because `LocalStorageAdapter` routes every read and write through
+ * `getStorage()`.
+ *
+ * It used to re-implement `get`/`set`/`remove`/`clear`/`keys`/`size`/`subscribe`
+ * — ~230 lines differing only by naming `window.sessionStorage`. That is how one
+ * defect became two issue numbers: the copy carried its own
+ * `logger.error('Failed to get key … from sessionStorage')`, so fixing the
+ * localStorage path left the sessionStorage path untouched, and the reports came
+ * back separately (ISSUE-01 for `localStorage`, ISSUE-09 for `sessionStorage`,
+ * one root cause). Keep the override surface minimal so that cannot recur.
  */
 export class SessionStorageAdapter extends LocalStorageAdapter {
     name = 'sessionStorage';
@@ -30,22 +40,14 @@ export class SessionStorageAdapter extends LocalStorageAdapter {
      * Check if sessionStorage is available
      */
     async isAvailable() {
-        try {
-            if (typeof window === 'undefined' || !window.sessionStorage) {
-                return false;
-            }
-            // Test if we can actually use it
-            const testKey = `${this.prefix}__test__`;
-            window.sessionStorage.setItem(testKey, 'test');
-            window.sessionStorage.removeItem(testKey);
-            return true;
-        }
-        catch {
+        if (typeof window === 'undefined' || !window.sessionStorage) {
             return false;
         }
+        return this.isAvailableSync();
     }
     /**
-     * Override all methods to use sessionStorage instead of localStorage
+     * The backing Storage object. This is the ONLY thing that differs from the
+     * parent — every inherited method reads and writes through it.
      */
     getStorage() {
         if (typeof window === 'undefined' || !window.sessionStorage) {
@@ -53,210 +55,4 @@ export class SessionStorageAdapter extends LocalStorageAdapter {
         }
         return window.sessionStorage;
     }
-    /**
-     * Get a value from sessionStorage
-     */
-    async get(key) {
-        return this.getSync(key);
-    }
-    /**
-     * Get a value from sessionStorage (synchronous)
-     */
-    getSync(key) {
-        try {
-            const item = window.sessionStorage.getItem(this.prefix + key);
-            if (!item)
-                return null;
-            const value = deserialize(item);
-            // Check TTL
-            if (this.isExpired(value)) {
-                this.removeSync(key);
-                return null;
-            }
-            return value;
-        }
-        catch (error) {
-            logger.error(`Failed to get key ${key} from sessionStorage:`, error);
-            return null;
-        }
-    }
-    /**
-     * Set a value in sessionStorage
-     */
-    async set(key, value) {
-        this.setSync(key, value);
-    }
-    /**
-     * Set a value in sessionStorage (synchronous)
-     */
-    setSync(key, value) {
-        const fullKey = this.prefix + key;
-        const oldValue = this.getSync(key);
-        try {
-            const serialized = serialize(value);
-            window.sessionStorage.setItem(fullKey, serialized);
-        }
-        catch (error) {
-            if (this.isQuotaError(error)) {
-                throw new QuotaExceededError('SessionStorage quota exceeded', { key, error });
-            }
-            throw new SerializationError(`Failed to store key ${key} in sessionStorage`, error);
-        }
-        // Emit change event
-        this.emitChange(key, oldValue?.value, value.value, 'local');
-    }
-    /**
-     * Remove a value from sessionStorage
-     */
-    async remove(key) {
-        this.removeSync(key);
-    }
-    /**
-     * Remove a value from sessionStorage (synchronous)
-     */
-    removeSync(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');
-        }
-    }
-    /**
-     * Clear sessionStorage
-     */
-    async clear(options) {
-        this.clearSync(options);
-    }
-    /**
-     * Clear sessionStorage (synchronous)
-     */
-    clearSync(options) {
-        if (!options ||
-            (!options.pattern && !options.prefix && !options.tags && !options.expiredOnly)) {
-            // Clear all with our prefix
-            const keysToRemove = [];
-            for (let i = 0; i < window.sessionStorage.length; i++) {
-                const key = window.sessionStorage.key(i);
-                if (key?.startsWith(this.prefix)) {
-                    keysToRemove.push(key);
-                }
-            }
-            keysToRemove.forEach((key) => window.sessionStorage.removeItem(key));
-            this.emitChange('*', undefined, undefined, 'local');
-            return;
-        }
-        // Synchronous filtered clear (mirrors BaseAdapter.clear logic)
-        for (const key of this.keysSync()) {
-            let shouldDelete = true;
-            const pattern = options.pattern || options.prefix;
-            if (pattern) {
-                shouldDelete = this.filterKeys([key], pattern).length > 0;
-            }
-            if (shouldDelete && options.tags) {
-                const value = this.getSync(key);
-                if (!value?.tags || !options.tags.some((tag) => value.tags?.includes(tag))) {
-                    shouldDelete = false;
-                }
-            }
-            if (shouldDelete && options.expiredOnly) {
-                const value = this.getSync(key);
-                if (!value || !this.isExpired(value)) {
-                    shouldDelete = false;
-                }
-            }
-            if (shouldDelete) {
-                this.removeSync(key);
-            }
-        }
-    }
-    /**
-     * Get all keys
-     */
-    async keys(pattern) {
-        return this.keysSync(pattern);
-    }
-    /**
-     * Get all keys (synchronous)
-     */
-    keysSync(pattern) {
-        const keys = [];
-        for (let i = 0; i < window.sessionStorage.length; i++) {
-            const fullKey = window.sessionStorage.key(i);
-            if (fullKey?.startsWith(this.prefix)) {
-                const key = fullKey.substring(this.prefix.length);
-                // Check if not expired
-                const value = this.getSync(key);
-                if (value) {
-                    keys.push(key);
-                }
-            }
-        }
-        return this.filterKeys(keys, pattern);
-    }
-    /**
-     * Check if key exists (synchronous)
-     */
-    hasSync(key) {
-        const value = this.getSync(key);
-        return value !== null && !this.isExpired(value);
-    }
-    /**
-     * Get storage size
-     */
-    async size(detailed) {
-        let total = 0;
-        let count = 0;
-        let keySize = 0;
-        let valueSize = 0;
-        const byKey = {};
-        for (let i = 0; i < window.sessionStorage.length; i++) {
-            const fullKey = window.sessionStorage.key(i);
-            if (fullKey?.startsWith(this.prefix)) {
-                const item = window.sessionStorage.getItem(fullKey);
-                if (item) {
-                    count++;
-                    const key = fullKey.substring(this.prefix.length);
-                    const itemSize = (fullKey.length + item.length) * 2; // UTF-16
-                    total += itemSize;
-                    if (detailed) {
-                        keySize += fullKey.length * 2;
-                        valueSize += item.length * 2;
-                        byKey[key] = itemSize;
-                    }
-                }
-            }
-        }
-        const result = { total, count };
-        if (detailed) {
-            result.byKey = byKey;
-            result.detailed = {
-                keys: keySize,
-                values: valueSize,
-                metadata: 0,
-            };
-        }
-        return result;
-    }
-    /**
-     * Subscribe to storage changes
-     * Note: sessionStorage doesn't fire storage events in the same tab
-     */
-    subscribe(callback) {
-        // For sessionStorage, we only get local changes, not cross-tab
-        // Use the base class subscription for local changes
-        return super.subscribe(callback);
-    }
 }

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

@@ -35,6 +35,9 @@ export declare class URLAdapter extends BaseAdapter {
     private snapshot;
     private changeListener?;
     isAvailable(): Promise<boolean>;
+    configure(config?: URLAdapterConfig): void;
+    /** The URL is usable whenever `window.location` is. */
+    isAvailableSync(): boolean;
     initialize(config?: URLAdapterConfig): Promise<void>;
     getSync<T = unknown>(key: string): StorageValue<T> | null;
     setSync<T = unknown>(key: string, value: StorageValue<T>): void;