strata-storage 2.8.5 → 3.0.0

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

@@ -7,22 +7,84 @@ import type { StorageType, StorageCapabilities, StorageValue, ClearOptions, Size
 /**
  * Browser localStorage adapter
  */
+/**
+ * The key prefix web adapters use unless told otherwise, as of 3.0.0.
+ *
+ * 🔴 Before 3.0.0 this was the empty string, which meant this library's keys sat
+ * unprefixed among every other script's in a shared storage area. 2.9.0 made that
+ * safe (a key is ours only if its value is a `StorageValue` envelope); this makes
+ * it tidy as well, so our keys are identifiable by name too.
+ *
+ * Opt out with `defineStorage({ keyPrefix: false })` — see `StrataConfig`.
+ */
+export declare const DEFAULT_WEB_KEY_PREFIX = "strata:";
 export declare class LocalStorageAdapter extends BaseAdapter {
     readonly name: StorageType;
     readonly capabilities: StorageCapabilities;
     protected prefix: string;
     protected listeners: Map<SubscriptionCallback, (event: StorageEvent) => void>;
+    /**
+     * Whether to adopt pre-3.0 unprefixed entries on read.
+     *
+     * 🔴 Defaults to FALSE, and only `Strata` turns it on — for the adapters whose
+     * prefix it resolved. A directly constructed adapter must never adopt bare
+     * keys: `plugin/web.ts` builds a `strata_prefs_` instance beside the main one,
+     * and if that adopted every unprefixed entry it found, it would take them from
+     * the instance they belong to.
+     */
+    protected migrateLegacyKeys: boolean;
     constructor(prefix?: string);
     /**
      * Check if localStorage is available
      */
     isAvailable(): Promise<boolean>;
+    /**
+     * Apply configuration synchronously. See `BaseAdapter.configure` for why the
+     * prefix cannot wait for the async `initialize()`.
+     */
+    configure(config?: {
+        prefix?: string;
+        migrateLegacyKeys?: boolean;
+    }): void;
+    /**
+     * Adopt a pre-3.0 unprefixed entry for `key`, moving it under the current
+     * prefix. Returns the adopted value, or null when there is nothing to adopt.
+     *
+     * This is the whole of the 3.0.0 migration, and it is deliberately **per key,
+     * on read** rather than a bulk sweep. A sweep would adopt every unprefixed
+     * envelope on the origin — including keys belonging to another instance that
+     * opted out of the prefix, or to a sibling application still on 2.x. Adopting
+     * only what the caller actually asks for keeps the blast radius to keys this
+     * instance already uses.
+     *
+     * Three conditions, all required:
+     *  1. migration is enabled and a prefix is actually in effect (nothing to move
+     *     data *into* otherwise);
+     *  2. the legacy value is **ours** — `parseOwnValue`, the 2.9.0 shape check. It
+     *     is what makes this safe at all: with no prefix to go on, shape is the only
+     *     way to tell our data from a third party's;
+     *  3. the prefixed slot is **empty**. A value already there is authoritative, so
+     *     the legacy entry is left alone rather than overwriting newer data.
+     *
+     * It MOVES rather than copies. A copy leaves a stale duplicate that diverges the
+     * moment anything writes — a silent wrong answer, worse than a clean break. A
+     * consumer that needs the bare key to keep existing (a pre-paint script, a
+     * logger reading its own level) takes `keyPrefix: false` instead.
+     */
+    protected adoptLegacyKey<T = unknown>(key: string): StorageValue<T> | null;
     /**
      * Initialize the adapter
      */
     initialize(config?: {
         prefix?: string;
     }): Promise<void>;
+    /**
+     * 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(): boolean;
     /**
      * Get the backing Storage object.
      * Subclasses (e.g. SessionStorageAdapter) override this to target a
@@ -70,6 +132,45 @@ export declare class LocalStorageAdapter extends BaseAdapter {
      * Get all keys (synchronous)
      */
     keysSync(pattern?: string | RegExp): string[];
+    /**
+     * 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.
+     */
+    protected ownKeys(includeExpired?: boolean): Array<{
+        key: string;
+        fullKey: string;
+        value: StorageValue;
+    }>;
+    /**
+     * Remove an entry `ownKeys()` returned, by its PHYSICAL key.
+     *
+     * 🔴 Not `removeSync(key)`. That rebuilds the physical key as `prefix + key`,
+     * which is wrong for a pre-3.0 legacy entry — those live at the bare key, so
+     * `ownKeys()` reports `fullKey === key` for them. Rebuilding would delete
+     * `strata:<key>` instead and leave the legacy entry behind, so `clear()` and
+     * the expiry sweep would silently skip exactly the entries not yet migrated.
+     */
+    protected removeOwnedEntry(entry: {
+        key: string;
+        fullKey: string;
+        value: StorageValue;
+    }): void;
+    /**
+     * 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.
+     */
+    cleanupExpired(): Promise<number>;
     /**
      * Check if key exists (synchronous)
      */

package/dist/adapters/web/LocalStorageAdapter.js

@@ -3,12 +3,23 @@
  * 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";
 /**
  * Browser localStorage adapter
  */
+/**
+ * The key prefix web adapters use unless told otherwise, as of 3.0.0.
+ *
+ * 🔴 Before 3.0.0 this was the empty string, which meant this library's keys sat
+ * unprefixed among every other script's in a shared storage area. 2.9.0 made that
+ * safe (a key is ours only if its value is a `StorageValue` envelope); this makes
+ * it tidy as well, so our keys are identifiable by name too.
+ *
+ * Opt out with `defineStorage({ keyPrefix: false })` — see `StrataConfig`.
+ */
+export const DEFAULT_WEB_KEY_PREFIX = 'strata:';
 export class LocalStorageAdapter extends BaseAdapter {
     name = 'localStorage';
     capabilities = {
@@ -24,7 +35,17 @@ export class LocalStorageAdapter extends BaseAdapter {
     };
     prefix;
     listeners = new Map();
-    constructor(prefix = '') {
+    /**
+     * Whether to adopt pre-3.0 unprefixed entries on read.
+     *
+     * 🔴 Defaults to FALSE, and only `Strata` turns it on — for the adapters whose
+     * prefix it resolved. A directly constructed adapter must never adopt bare
+     * keys: `plugin/web.ts` builds a `strata_prefs_` instance beside the main one,
+     * and if that adopted every unprefixed entry it found, it would take them from
+     * the instance they belong to.
+     */
+    migrateLegacyKeys = false;
+    constructor(prefix = DEFAULT_WEB_KEY_PREFIX) {
         super();
         this.prefix = prefix;
     }
@@ -47,14 +68,103 @@ 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;
         }
+        if (config?.migrateLegacyKeys !== undefined) {
+            this.migrateLegacyKeys = config.migrateLegacyKeys;
+        }
+    }
+    /**
+     * Adopt a pre-3.0 unprefixed entry for `key`, moving it under the current
+     * prefix. Returns the adopted value, or null when there is nothing to adopt.
+     *
+     * This is the whole of the 3.0.0 migration, and it is deliberately **per key,
+     * on read** rather than a bulk sweep. A sweep would adopt every unprefixed
+     * envelope on the origin — including keys belonging to another instance that
+     * opted out of the prefix, or to a sibling application still on 2.x. Adopting
+     * only what the caller actually asks for keeps the blast radius to keys this
+     * instance already uses.
+     *
+     * Three conditions, all required:
+     *  1. migration is enabled and a prefix is actually in effect (nothing to move
+     *     data *into* otherwise);
+     *  2. the legacy value is **ours** — `parseOwnValue`, the 2.9.0 shape check. It
+     *     is what makes this safe at all: with no prefix to go on, shape is the only
+     *     way to tell our data from a third party's;
+     *  3. the prefixed slot is **empty**. A value already there is authoritative, so
+     *     the legacy entry is left alone rather than overwriting newer data.
+     *
+     * It MOVES rather than copies. A copy leaves a stale duplicate that diverges the
+     * moment anything writes — a silent wrong answer, worse than a clean break. A
+     * consumer that needs the bare key to keep existing (a pre-paint script, a
+     * logger reading its own level) takes `keyPrefix: false` instead.
+     */
+    adoptLegacyKey(key) {
+        if (!this.migrateLegacyKeys || !this.prefix)
+            return null;
+        // A key already carrying our prefix is not a legacy key.
+        if (key.startsWith(this.prefix))
+            return null;
+        let storage;
+        try {
+            storage = this.getStorage();
+        }
+        catch {
+            return null;
+        }
+        const raw = storage.getItem(key);
+        if (raw === null)
+            return null;
+        const value = this.parseOwnValue(raw, key);
+        if (!value)
+            return null;
+        if (storage.getItem(this.prefix + key) !== null) {
+            logger.debug(`${this.name}: legacy key "${key}" not adopted — "${this.prefix}${key}" already exists and wins.`);
+            return null;
+        }
+        try {
+            storage.setItem(this.prefix + key, raw);
+            storage.removeItem(key);
+        }
+        catch (error) {
+            // Out of quota, or the area turned read-only mid-flight. The legacy entry
+            // is still intact and still readable, so report and return it.
+            logger.warn(`${this.name}: could not migrate legacy key "${key}":`, error);
+            return value;
+        }
+        logger.debug(`${this.name}: migrated legacy key "${key}" to "${this.prefix}${key}".`);
+        return value;
+    }
+    /**
+     * 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 +187,28 @@ 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.
+        // A miss falls through to a pre-3.0 unprefixed entry, if there is one.
+        const value = this.parseOwnValue(item, key) ?? this.adoptLegacyKey(key);
+        if (!value)
+            return null;
+        if (this.isExpired(value)) {
+            this.removeSync(key);
+            return null;
+        }
+        return value;
     }
     /**
      * Set a value in localStorage
@@ -137,15 +253,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,40 +272,37 @@ 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 entry of this.ownKeys(true)) {
+            const { key, value } = entry;
             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);
+                this.removeOwnedEntry(entry);
             }
         }
     }
@@ -211,20 +316,92 @@ 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 = [];
+        const seen = new Set();
         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;
+            seen.add(key);
+            owned.push({ key, fullKey, value });
+        }
+        // Pre-3.0 unprefixed entries are still ours and must appear here, or `keys()`,
+        // `clear()` and `size()` would silently omit everything not yet read back
+        // (adoption is per-read, so a freshly upgraded app has migrated nothing yet).
+        //
+        // 🔴 Listing is NOT adopting. Enumerating must not move data — a `keys()` call
+        // is a question, not a write — so these are reported at their real physical
+        // key and migrate only when actually read. A prefixed entry for the same
+        // logical key always wins, so upgraded keys are never listed twice.
+        if (this.migrateLegacyKeys && this.prefix) {
+            for (let i = 0; i < storage.length; i++) {
+                const fullKey = storage.key(i);
+                if (!fullKey || fullKey.startsWith(this.prefix) || seen.has(fullKey))
+                    continue;
+                const value = this.parseOwnValue(storage.getItem(fullKey), fullKey);
+                if (!value)
+                    continue;
+                if (!includeExpired && this.isExpired(value))
+                    continue;
+                seen.add(fullKey);
+                owned.push({ key: fullKey, fullKey, value });
             }
         }
-        return this.filterKeys(keys, pattern);
+        return owned;
+    }
+    /**
+     * Remove an entry `ownKeys()` returned, by its PHYSICAL key.
+     *
+     * 🔴 Not `removeSync(key)`. That rebuilds the physical key as `prefix + key`,
+     * which is wrong for a pre-3.0 legacy entry — those live at the bare key, so
+     * `ownKeys()` reports `fullKey === key` for them. Rebuilding would delete
+     * `strata:<key>` instead and leave the legacy entry behind, so `clear()` and
+     * the expiry sweep would silently skip exactly the entries not yet migrated.
+     */
+    removeOwnedEntry(entry) {
+        this.getStorage().removeItem(entry.fullKey);
+        if (this.hasChangeListeners()) {
+            this.emitChange(entry.key, entry.value.value, undefined, 'local');
+        }
+    }
+    /**
+     * 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 entry of this.ownKeys(true)) {
+            if (this.isExpired(entry.value)) {
+                this.removeOwnedEntry(entry);
+                removed++;
+            }
+        }
+        return removed;
     }
     /**
      * Check if key exists (synchronous)
@@ -242,20 +419,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 +456,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;
+            }
+            if (event.storageArea !== area)
                 return;
-            // Check if the key belongs to us
+            // 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();
     }
     /**