strata-storage 2.8.5 → 3.0.0

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;

package/dist/adapters/web/URLAdapter.js

@@ -39,7 +39,7 @@ export class URLAdapter extends BaseAdapter {
             typeof window.location !== 'undefined' &&
             typeof window.history !== 'undefined');
     }
-    async initialize(config) {
+    configure(config) {
         if (config?.mode)
             this.mode = config.mode;
         if (config?.prefix !== undefined)
@@ -48,6 +48,13 @@ export class URLAdapter extends BaseAdapter {
             this.historyMode = config.history;
         if (typeof config?.maxLength === 'number')
             this.maxLength = config.maxLength;
+    }
+    /** The URL is usable whenever `window.location` is. */
+    isAvailableSync() {
+        return typeof window !== 'undefined' && typeof window.location !== 'undefined';
+    }
+    async initialize(config) {
+        this.configure(config);
         if (typeof window === 'undefined')
             return;
         // Seed the snapshot and listen for external navigation (back/forward, manual

package/dist/core/BaseAdapter.d.ts

@@ -14,6 +14,22 @@ export declare abstract class BaseAdapter implements StorageAdapter {
     protected queryEngine: QueryEngine;
     protected ttlCleanupInterval?: ReturnType<typeof setInterval>;
     protected ttlCheckInterval: number;
+    /**
+     * Apply adapter configuration SYNCHRONOUSLY, before any operation runs.
+     *
+     * 🔴 Config that changes the PHYSICAL KEY (`prefix`) cannot wait for the async
+     * `initialize()`. The synchronous API is deliberately usable before
+     * initialization completes — `Strata.selectAdapterSync()` falls back to the
+     * registry — so a `prefix` applied only at `initialize()` is silently absent
+     * for every `setSync`/`getSync` issued in that window, and the value lands at
+     * the bare key. That is the whole of ISSUE-08: `initialize({ prefix })` worked,
+     * and the config path to it did not.
+     *
+     * `initialize()` calls this first, so both paths agree. Default is a no-op;
+     * adapters with configurable fields override it with pure assignment only —
+     * never I/O, never a timer.
+     */
+    configure(_config?: unknown): void;
     /**
      * Initialize TTL cleanup if needed
      */
@@ -33,6 +49,22 @@ export declare abstract class BaseAdapter implements StorageAdapter {
      * `Strata.cleanupExpired()`.
      */
     cleanupExpired(): Promise<number>;
+    /**
+     * Parse a raw stored string into a value THIS adapter owns, or null.
+     *
+     * 🔴 The classification is the point, not the parse. Web adapters share their
+     * storage area with every other script on the origin, so a raw value that is
+     * not our envelope means the key belongs to somebody else — the ordinary case,
+     * not a failure. Reporting it through `logger.error` asserts something untrue
+     * about the consumer's own data, and on any origin running a third-party
+     * script that stores a raw string (Microsoft Clarity's `_cltk` is the usual
+     * one) it produces a permanent error stream that reaches their error tracker.
+     *
+     * `logger.error` is therefore reserved for a key carrying OUR envelope that
+     * still fails — which is a real defect, and currently cannot be distinguished
+     * from somebody else's data at all.
+     */
+    protected parseOwnValue<T = unknown>(raw: string | null, key: string): StorageValue<T> | null;
     /**
      * Check if value is expired
      */

package/dist/core/BaseAdapter.js

@@ -2,7 +2,7 @@
  * Base adapter implementation with common functionality
  */
 import { NotSupportedError } from "../utils/errors.js";
-import { EventEmitter, matchGlob, getObjectSize } from "../utils/index.js";
+import { EventEmitter, matchGlob, getObjectSize, deserialize, isStorageEnvelope } from "../utils/index.js";
 import { logger } from "../utils/logger.js";
 import { QueryEngine } from "../features/query.js";
 /**
@@ -13,6 +13,24 @@ export class BaseAdapter {
     queryEngine = new QueryEngine();
     ttlCleanupInterval;
     ttlCheckInterval = 60000; // Check every minute
+    /**
+     * Apply adapter configuration SYNCHRONOUSLY, before any operation runs.
+     *
+     * 🔴 Config that changes the PHYSICAL KEY (`prefix`) cannot wait for the async
+     * `initialize()`. The synchronous API is deliberately usable before
+     * initialization completes — `Strata.selectAdapterSync()` falls back to the
+     * registry — so a `prefix` applied only at `initialize()` is silently absent
+     * for every `setSync`/`getSync` issued in that window, and the value lands at
+     * the bare key. That is the whole of ISSUE-08: `initialize({ prefix })` worked,
+     * and the config path to it did not.
+     *
+     * `initialize()` calls this first, so both paths agree. Default is a no-op;
+     * adapters with configurable fields override it with pure assignment only —
+     * never I/O, never a timer.
+     */
+    configure(_config) {
+        // No configurable fields by default.
+    }
     /**
      * Initialize TTL cleanup if needed
      */
@@ -27,6 +45,13 @@ export class BaseAdapter {
                 logger.error(`TTL cleanup error in ${this.name}:`, error);
             }
         }, this.ttlCheckInterval);
+        // 🔴 Do not hold a Node process open. An outstanding interval keeps the event
+        // loop alive, so a short-lived script — a build step, a CLI, an SSR warmup —
+        // that creates an instance and finishes its work never exits unless it also
+        // calls close(). `unref` does not exist in browsers (setInterval returns a
+        // number there), so the optional call is simply a no-op; in Node the timer
+        // keeps working for as long as the process does.
+        this.ttlCleanupInterval.unref?.();
     }
     /**
      * Stop TTL cleanup
@@ -60,6 +85,40 @@ export class BaseAdapter {
         }
         return removed;
     }
+    /**
+     * Parse a raw stored string into a value THIS adapter owns, or null.
+     *
+     * 🔴 The classification is the point, not the parse. Web adapters share their
+     * storage area with every other script on the origin, so a raw value that is
+     * not our envelope means the key belongs to somebody else — the ordinary case,
+     * not a failure. Reporting it through `logger.error` asserts something untrue
+     * about the consumer's own data, and on any origin running a third-party
+     * script that stores a raw string (Microsoft Clarity's `_cltk` is the usual
+     * one) it produces a permanent error stream that reaches their error tracker.
+     *
+     * `logger.error` is therefore reserved for a key carrying OUR envelope that
+     * still fails — which is a real defect, and currently cannot be distinguished
+     * from somebody else's data at all.
+     */
+    parseOwnValue(raw, key) {
+        if (raw === null || raw === '')
+            return null;
+        let parsed;
+        try {
+            parsed = deserialize(raw);
+        }
+        catch {
+            logger.debug(`${this.name}: skipping key "${key}" — value is not readable as ${this.name} data ` +
+                `(not written by this adapter).`);
+            return null;
+        }
+        if (!isStorageEnvelope(parsed)) {
+            logger.debug(`${this.name}: skipping key "${key}" — value carries no storage envelope ` +
+                `(not written by this adapter).`);
+            return null;
+        }
+        return parsed;
+    }
     /**
      * Check if value is expired
      */

package/dist/core/Strata.d.ts

@@ -222,6 +222,12 @@ export declare class Strata {
     clearSync(options?: ClearOptions & StorageOptions): void;
     private requireSyncAdapter;
     private selectAdapterSync;
+    /**
+     * Whether an adapter can serve a synchronous operation right now. An adapter
+     * with no `isAvailableSync` is assumed usable — absence of a probe is not
+     * evidence of unavailability.
+     */
+    private static isUsableSync;
     private syncCapableAdapters;
     private computeExpiration;
     /**
@@ -314,6 +320,30 @@ export declare class Strata {
      * ```
      */
     registerAdapter(adapter: StorageAdapter): void;
+    /**
+     * Web adapters that share their storage area with every other script on the
+     * origin, and therefore take the instance-wide `keyPrefix`.
+     *
+     * Cookies are excluded deliberately: they already default to `strata_`, so
+     * moving them would break existing cookies for no gain. IndexedDB and the Cache
+     * API own a named store, memory owns its own Map, and the URL adapter already
+     * prefixes its params — none of them can collide with another script's keys.
+     */
+    private static readonly PREFIXED_WEB_ADAPTERS;
+    /**
+     * The configured options for one adapter, or undefined when it has none.
+     *
+     * For the shared-area web adapters this also resolves the 3.0.0 key prefix and
+     * decides whether that adapter may adopt pre-3.0 unprefixed entries. Precedence,
+     * and it lives only here:
+     *
+     *   1. `adapters.<name>.prefix` — the most specific thing the caller wrote
+     *   2. `keyPrefix` — the instance-wide switch (`false` restores 2.x behaviour)
+     *   3. the adapter's own constructor default (`DEFAULT_WEB_KEY_PREFIX`)
+     */
+    private adapterConfigFor;
+    /** Push the configured options into an adapter synchronously. */
+    private applyAdapterConfig;
     /**
      * Initialize and attach any registered adapters that are not yet active, then
      * re-pick the default adapter. Call this after `registerAdapter()` on an