strata-storage 2.8.5 → 3.0.0

package/AI-INTEGRATION-GUIDE.md

@@ -73,6 +73,49 @@ export const storage = defineStorage({
 
 `defineStorage()` pre-registers memory, localStorage, sessionStorage, IndexedDB, cookies, and the Cache API. Use `new Strata(config)` + `registerWebAdapters(instance)` only when you need full control.
 
+🔴 **`defaultStorages` is the preference order for the DEFAULT adapter — not a registration list.** Operations with no explicit `storage` (`keys`, `clear`, `size`, `subscribe`) deliberately span every *registered* adapter. To leave one out entirely, say so:
+
+```typescript
+export const storage = defineStorage({
+  defaultStorages: ['localStorage'],
+  adapters: { sessionStorage: false, indexedDB: false, cookies: false, cache: false },
+});
+```
+
+## Key prefix and the 3.0.0 migration
+
+`localStorage` and `sessionStorage` keys are written under **`strata:`** as of 3.0.0
+(`DEFAULT_WEB_KEY_PREFIX`, exported). Existing data migrates itself: a miss at `strata:<key>` falls back to the bare `<key>`, and if the value is one of ours it is moved under the prefix. Per key, on read — never a bulk sweep, never a value that is not our envelope, never overwriting an existing prefixed value.
+
+🔴 **Set `keyPrefix: false` when anything outside this library reads a physical key directly** — a pre-paint theme script, a logger reading its own level. Migration keeps the data reachable through this library; it cannot fix a hard-coded reader.
+
+```typescript
+export const storage = defineStorage({ keyPrefix: false });          // pre-3.0 keys
+export const storage = defineStorage({ migrateLegacyKeys: false });  // don't adopt 2.x entries
+```
+
+`cookies` (already `strata_`), `indexedDB`, `cache`, `memory` and `url` are unchanged. `namespace` is a separate mechanism: the physical key is `<keyPrefix><namespace>:<key>`.
+
+## Shared storage areas — how this library identifies its own keys
+
+`localStorage`, `sessionStorage` and cookies are shared with every other script on the origin, and the default key prefix is empty — so a name test cannot tell our keys from theirs. **A key counts as ours only when its stored value is a `StorageValue` envelope.**
+
+What follows from that:
+
+- `keys()` returns only keys this library wrote. A key put in the same area by anything else is invisible to it **by design** — that is the fix, not a bug.
+- The TTL sweep and `clear()` never read, parse, delete or log about another application's data.
+- A value we cannot read is **not an error**. It is skipped and reported at `debug`, because it is evidence the key belongs to somebody else. `logger.error` is reserved for a key carrying our envelope that still fails, and for a real storage-access fault.
+- Debug it with `setLogLevel('debug')` (exported), which names each skipped key and why.
+
+```typescript
+import { setLogLevel, isStorageEnvelope } from 'strata-storage';
+
+setLogLevel('debug');                              // see what is being skipped
+isStorageEnvelope(JSON.parse(raw));                // is this value one of ours?
+```
+
+Before 2.9.0 an empty prefix made the adapter claim every key on the origin: it error-logged about third-party values on every sweep, returned them from `keys()`, and could delete one whose JSON happened to carry a past `expires`. Prefixes and namespaces are still worth setting for a clean keyspace — they are no longer what keeps this library off other people's keys.
+
 ## Storage Options (per operation)
 
 ```typescript

package/CHANGELOG.md

@@ -5,6 +5,157 @@ All notable changes to Strata Storage will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.0.0] - 2026-09-01
+
+**Breaking: the web adapters now prefix their keys with `strata:`.** One line restores the old behaviour,
+and existing data migrates itself on read — but read the migration notes before upgrading, because a
+consumer that reads a physical key from outside this library must opt out.
+
+### Breaking
+
+- **`localStorage` and `sessionStorage` keys are now written under `strata:`.** `DEFAULT_WEB_KEY_PREFIX`
+  is exported. Before this release the default prefix was the empty string, so this library's keys sat
+  unprefixed among every other script's on the origin. 2.9.0 made that *safe* — a key is ours only if its
+  value is a `StorageValue` envelope — and this makes it *tidy*, so our keys are identifiable by name too.
+  - `cookies` are unchanged: they already defaulted to `strata_`, and moving them would break existing
+    cookies for no gain.
+  - `indexedDB` and `cache` 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, so none of them change.
+  - `namespace` is a separate mechanism and is unaffected. The physical key is
+    `<keyPrefix><namespace>:<key>`.
+
+### Added
+
+- **`keyPrefix`** — set `false` (or `''`) for the pre-3.0 behaviour, or a string for your own prefix. A
+  per-adapter `adapters.localStorage.prefix` still wins over it.
+- **`migrateLegacyKeys`** (default `true`) — adopt pre-3.0 unprefixed entries on read.
+
+### Migration
+
+**Most consumers need to do nothing.** On a miss at `strata:<key>`, the adapter looks for the bare `<key>`
+and, if the value is one of ours, moves it under the prefix and returns it. Your data stays reachable.
+
+Three properties of that migration, each verified in a browser:
+
+- **It is per key, on read — never a bulk sweep.** A sweep would adopt every unprefixed envelope on the
+  origin, including keys belonging to an instance that opted out or to a sibling app still on 2.x.
+- **It never adopts a value that is not ours** — the 2.9.0 envelope check is what makes it safe at all.
+  A planted `_cltk` is left exactly where it is.
+- **It never overwrites.** A value already at the prefixed key wins and the legacy entry is left alone.
+
+🔴 **Take `keyPrefix: false` if anything outside this library reads a physical key directly** — a
+pre-paint theme script that runs before any module loads, or a logger reading its own level. Those
+readers know the exact key name, and a prefix changes it underneath them. Migration keeps the *data*
+reachable through this library; it cannot fix a hard-coded reader.
+
+```typescript
+// Frozen physical key names, or an external reader — keep 2.x behaviour:
+export const storage = defineStorage({ keyPrefix: false });
+```
+
+🔴 **Two applications sharing one origin, one still on 2.x:** set `migrateLegacyKeys: false` on the
+upgraded one, so it does not move keys the other still reads. Better, give each app a `namespace` —
+they were already colliding before this release.
+
+### Fixed
+
+- **A live timer no longer keeps a Node process alive.** `setInterval` holds the event loop open, so a
+  short-lived script — a build step, a CLI, an SSR warmup — that created an instance never exited unless
+  it also called `close()`. Measured: a script doing one `set`/`get` hung until killed at 120s, and now
+  exits immediately. All three timers (adapter TTL, cross-adapter cleanup, auto-backup) are `unref`'d;
+  it is a no-op in browsers.
+
+## [2.9.0] - 2026-09-01
+
+Closes the entire consumer-reported issue queue — six entries from five projects (LabFlow, ClearHire,
+HabitForge, LifeWell, Trizlink). **No API changes and no data migration**: every key stays exactly where
+it is.
+
+### Fixed
+
+- **A web adapter no longer treats another application's keys as its own** (ISSUE-01, ISSUE-09).
+  `localStorage`, `sessionStorage` and cookies are shared with every other script on the origin, and the
+  default key prefix is empty — so `startsWith(prefix)` matched *every* key there. An adapter now
+  identifies its own data by **shape**: a key counts as ours only if its stored value deserializes into a
+  `StorageValue` envelope. Consequences, all measured in a browser against 2.8.5 and again after:
+  - The permanent error stream is gone. `[strata-storage] Failed to get key _cltk from sessionStorage:
+    SyntaxError…` (Microsoft Clarity's session key) and the same message for a consumer's own
+    `logger-level` no longer occur. **A foreign value is not an error** — it is evidence the key belongs
+    to somebody else, which is the ordinary case in a shared area, so it is skipped and reported at
+    `debug`. `logger.error` is now reserved for a key carrying *our* envelope that still fails, and for a
+    genuine storage-access fault (private mode, a blocked origin).
+  - `keys()` no longer returns keys this library never wrote.
+  - 🔴 **`cleanupExpired()` no longer deletes another application's data.** A foreign key holding valid
+    JSON with a past `expires` was removed by the TTL sweep. Earlier notes in the issue queue recorded
+    this path as latent; driving the repro in a real browser showed it firing, so it was live.
+  - 🔴 **`clear()` no longer wipes the origin.** With an empty prefix the unfiltered branch deleted every
+    key present, including other applications'. It now removes only entries we wrote.
+- **An unscoped `subscribe()` no longer throws** (ISSUE-07). `Strata.subscribe` fanned out across every
+  registered adapter, and `indexedDB`, `cookies` and `cache` — all registered by default — throw
+  `NotSupportedError: Operation 'subscribe' is not supported by indexedDB adapter`. The documented
+  "omit options to hear every adapter" form therefore killed application boot on any default instance.
+  Non-observable backends are skipped; an observer that hears fewer backends is the right outcome when
+  some cannot speak. Naming a non-observable backend explicitly now warns instead of failing silently.
+- **Per-adapter configuration actually reaches the adapter** (ISSUE-08).
+  `defineStorage({ adapters: { localStorage: { prefix: 'app:' } } })` was a silent no-op — the isolation
+  advice the README gave and the fleet skill taught, doing nothing. The adapter honoured
+  `initialize({ prefix })` all along; the config path to it did not cover the **synchronous** API, which
+  is deliberately usable before initialization completes. Adapters now apply configuration synchronously
+  at registration, so `setSync`/`getSync` issued before `initialize()` resolves use the configured prefix
+  instead of writing to the bare key.
+- **`defaultStorages` now protects the synchronous path too** (ISSUE-08, related finding). It reads as an
+  ordered fallback list and behaved as one only for the async API: with `localStorage` unavailable,
+  `defineStorage({ defaultStorages: ['localStorage','memory'] }).setSync(...)` still selected
+  `localStorage` and threw rather than falling through to `memory`.
+- **`clear({ expiredOnly: true })` was a guaranteed no-op** on `localStorage`, `sessionStorage` and
+  cookies. It filtered the output of `keysSync()`, which excludes expired entries — so it inspected
+  exactly the set that could never match.
+- **`cleanupExpired()` reported `0` while doing the work.** On these adapters the reaping happened as an
+  undocumented side effect of enumeration; the count is now real.
+- **`size()` on `LocalStorageAdapter` read `window.localStorage` directly** instead of the adapter's own
+  storage area, so every inherited method was wrong for `sessionStorage` until the subclass
+  re-implemented it.
+- **Cross-tab `storage` events could never match for `sessionStorage`.** The listener compared against
+  `window.localStorage` by name rather than the adapter's own area.
+- **`setLogLevel` / `getLogLevel` are now exported.** The logger documented `setLogLevel('debug')` as a
+  supported control, and it was unreachable from the package entry point. This matters as of this
+  release: skipped foreign keys are reported at `debug`, so raising the level is how a consumer answers
+  "why is my key missing from `keys()`?".
+- **The repo's own version claims contradicted each other** (ISSUE-06). `CLAUDE.md` asserted npm `latest`
+  was `2.8.2` (a bad release) with `2.8.3` "awaiting publish", while `docs/MANUAL-TASKS.md` recorded that
+  publish as done and `package.json` was two releases further on. The version prose is now a pointer to a
+  single home, and **the build fails** when the README's at-a-glance version row disagrees with
+  `package.json` — the row is what npm renders, and it had already shipped stale once.
+
+### Changed
+
+- **`adapters: { <name>: false }` now opts an adapter out of *registration*, not just initialization.**
+  Registering an adapter the instance never uses still costs a TTL sweep over a storage area it does not
+  own. 🔴 `defaultStorages` is **not** this switch — it is the preference order for choosing the *default*
+  adapter, while multi-adapter operations deliberately span everything registered. That distinction was
+  undocumented, and reading `defaultStorages` as a registration allow-list is what produced ISSUE-09.
+- **`SessionStorageAdapter` shrank from 303 lines to 64.** It re-implemented ~230 lines that differed from
+  its parent only by naming `window.sessionStorage`, while the parent already routes every read and write
+  through `getStorage()`. That duplication is why one defect became two issue numbers: the copy carried
+  its own error call, so fixing the `localStorage` path left the `sessionStorage` path untouched.
+
+### Added
+
+- `isStorageEnvelope(value)` is exported — the predicate deciding whether a stored value was written by
+  this library, useful when auditing a shared storage area.
+- Two build gates, run by `yarn build`: the ownership predicate is asserted over 18 cases (including the
+  real-world foreign values above), and the README's version row is checked against `package.json`. Both
+  were watched failing against two differently-shaped planted defects each before being trusted.
+
+### Notes for upgraders
+
+Nothing moves and no migration is required. Behaviour that changes: `keys()` and `clear()` now see only
+this library's own entries, which is the fix rather than a regression. If you relied on an empty-prefix
+instance enumerating or clearing foreign keys, target those keys directly instead.
+
+A future **3.0.0** will give the web adapters a real default key prefix, built on this release's shape
+check, with migrate-on-read and an opt-out for consumers whose physical key names are frozen.
+
 ## [2.8.5] - 2026-07-25
 
 ### Fixed

package/README.md

@@ -32,7 +32,7 @@ integrity checksums and mirrored backups are opt-in per call or per instance.
 
 | | |
 |---|---|
-| **Version** | `2.8.5` |
+| **Version** | `3.0.0` |
 | **License** | MIT |
 | **Node** | `>=24.13.0` |
 | **Platforms** | Web · iOS · Android (via Capacitor) |
@@ -305,8 +305,10 @@ Passed to `defineStorage(config)` or `new Strata(config)`:
 
 | Option | Type | Default | What it does |
 |---|---|---|---|
-| `defaultStorages` | `StorageType[]` | `['localStorage', 'indexedDB', 'sessionStorage', 'memory']` | Preference order for picking the default adapter. |
-| `adapters` | `object` | `{}` | Per-adapter settings, or `false` to skip one. `localStorage`/`sessionStorage` take `{ prefix }`; `indexedDB` takes `{ dbName, version }`; `cookies` takes `{ secure, sameSite }`; `cache` takes `{ cacheName }`. |
+| `defaultStorages` | `StorageType[]` | `['localStorage', 'indexedDB', 'sessionStorage', 'memory']` | Preference order for picking the default adapter, and the fallback order when one is unusable. 🔴 **Not a registration list** — operations with no explicit `storage` (`keys`, `clear`, `size`, `subscribe`) span every *registered* adapter. To leave one out entirely use `adapters: { <name>: false }`. |
+| `keyPrefix` | `string \| false` | `'strata:'` | Key prefix for `localStorage`/`sessionStorage`. `false` restores pre-3.0 unprefixed keys — take it when anything outside this library reads a physical key directly. |
+| `migrateLegacyKeys` | `boolean` | `true` | Adopt pre-3.0 unprefixed entries on read: never a bulk sweep, never a non-envelope, never overwriting an existing prefixed value. |
+| `adapters` | `object` | `{}` | Per-adapter settings, or `false` to leave that adapter unregistered entirely. `localStorage`/`sessionStorage` take `{ prefix }`; `indexedDB` takes `{ dbName, version }`; `cookies` takes `{ secure, sameSite }`; `cache` takes `{ cacheName }`. Settings apply immediately, so they hold for `setSync`/`getSync` issued before `initialize()` resolves. |
 | `encryption` | `{ enabled, password }` | disabled | AES-GCM encryption on every write. Async path only. |
 | `compression` | `{ enabled, threshold }` | disabled | Compress values above `threshold` bytes. Async path only. |
 | `sync` | `{ enabled }` | disabled | Cross-tab change notifications. |
@@ -465,12 +467,18 @@ More: [Troubleshooting](https://stratastorage-docs.aoneahsan.com/reference/troub
   client-side.
 - **Node support is minimal.** Only the `memory` adapter is available outside a browser, so values do not
   persist across processes.
-- **Known open defect — web adapters default to an empty key prefix.** With no prefix, `keys()` on
-  `localStorage`/`sessionStorage` returns every key on the origin, including keys written by other code, and
-  the TTL sweep reads them. In the worst case a foreign key whose value happens to be JSON with an expired
-  `expires` field can be removed. Until this is fixed, set an explicit prefix:
-  `defineStorage({ adapters: { localStorage: { prefix: 'myapp:' } } })`. Tracked as `ISSUE-01` in
-  [docs/REPORTED-ISSUES.md](https://github.com/aoneahsan/strata-storage/blob/main/docs/REPORTED-ISSUES.md).
+- **Web adapters share their storage area, and identify their own data by shape.** `localStorage`,
+  `sessionStorage` and cookies are shared with every other script on the origin. An adapter treats a key
+  as its own only when the stored value is a `StorageValue` envelope, so `keys()`, the TTL sweep and
+  `clear()` never touch another application's data, and a value we cannot read is skipped at `debug`
+  rather than reported as an error. **The consequence to know about:** a key written to the same area by
+  something other than this library is invisible to `keys()` by design. Call `setLogLevel('debug')` to see
+  what is being skipped and why.
+- **Keys are prefixed `strata:` since 3.0.0, and that is a breaking change.** Existing data migrates
+  itself on read, so most consumers do nothing. 🔴 **But if anything outside this library reads a physical
+  key directly — a pre-paint theme script, a logger reading its own level — set
+  `defineStorage({ keyPrefix: false })`.** Migration keeps the data reachable through this library; it
+  cannot fix a hard-coded reader. See [Changelog](https://github.com/aoneahsan/strata-storage/blob/main/CHANGELOG.md).
 - **Firebase adapter names are not in the `StorageType` union.** `'firestore'` and `'realtime'` are runtime
   names, so strict TypeScript may need a cast on the options object.
 

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

@@ -21,6 +21,10 @@ export declare class CacheAdapter extends BaseAdapter {
     /**
      * Initialize the adapter
      */
+    configure(config?: {
+        cacheName?: string;
+        baseUrl?: string;
+    }): void;
     initialize(config?: {
         cacheName?: string;
         baseUrl?: string;

package/dist/adapters/web/CacheAdapter.js

@@ -39,11 +39,14 @@ export class CacheAdapter extends BaseAdapter {
     /**
      * Initialize the adapter
      */
-    async initialize(config) {
+    configure(config) {
         if (config?.cacheName)
             this.cacheName = config.cacheName;
         if (config?.baseUrl)
             this.baseUrl = config.baseUrl;
+    }
+    async initialize(config) {
+        this.configure(config);
         await this.openCache();
         this.startTTLCleanup();
     }

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

@@ -43,7 +43,14 @@ export declare class CookieAdapter extends BaseAdapter {
     /**
      * Initialize the adapter
      */
-    initialize(config?: CookieOptions): Promise<void>;
+    configure(config?: CookieOptions & {
+        prefix?: string;
+    }): void;
+    initialize(config?: CookieOptions & {
+        prefix?: string;
+    }): Promise<void>;
+    /** Whether the cookie jar is usable right now, without awaiting anything. */
+    isAvailableSync(): boolean;
     /**
      * Get a value from cookies
      */
@@ -84,6 +91,18 @@ export declare class CookieAdapter extends BaseAdapter {
      * Get all keys (synchronous)
      */
     keysSync(pattern?: string | RegExp): string[];
+    /**
+     * Every cookie on this origin that this adapter actually owns, envelope
+     * already parsed. The cookie jar is shared with the server and with every
+     * script on the origin, so name alone cannot identify our data — shape can.
+     */
+    protected ownCookies(includeExpired?: boolean): Array<{
+        key: string;
+        cookieKey: string;
+        value: StorageValue;
+    }>;
+    /** Reclaim expired cookies, reading each once and reporting a real count. */
+    cleanupExpired(): Promise<number>;
     /**
      * Check if key exists (synchronous)
      */

package/dist/adapters/web/CookieAdapter.js

@@ -71,12 +71,34 @@ export class CookieAdapter extends BaseAdapter {
     /**
      * Initialize the adapter
      */
-    async initialize(config) {
-        if (config) {
-            this.cookieOptions = { ...this.cookieOptions, ...config };
+    configure(config) {
+        if (!config)
+            return;
+        const { prefix, ...cookieOptions } = config;
+        if (prefix !== undefined) {
+            this.prefix = prefix;
         }
+        this.cookieOptions = { ...this.cookieOptions, ...cookieOptions };
+    }
+    async initialize(config) {
+        this.configure(config);
         this.startTTLCleanup();
     }
+    /** Whether the cookie jar is usable right now, without awaiting anything. */
+    isAvailableSync() {
+        try {
+            if (typeof document === 'undefined')
+                return false;
+            const testKey = `${this.prefix}__test__`;
+            document.cookie = `${testKey}=test; path=/`;
+            const ok = document.cookie.includes(testKey);
+            this.deleteCookie(testKey);
+            return ok;
+        }
+        catch {
+            return false;
+        }
+    }
     /**
      * Get a value from cookies
      */
@@ -91,20 +113,26 @@ export class CookieAdapter extends BaseAdapter {
         const value = this.getCookie(cookieKey);
         if (!value)
             return null;
+        let decoded;
         try {
-            const decoded = decodeURIComponent(value);
-            const parsed = deserialize(decoded);
-            // Check TTL
-            if (this.isExpired(parsed)) {
-                this.removeSync(key);
-                return null;
-            }
-            return parsed;
+            decoded = decodeURIComponent(value);
         }
-        catch (error) {
-            logger.error(`Failed to parse cookie ${key}:`, error);
+        catch {
+            // Not percent-encoded — so not written by this adapter.
+            logger.debug(`${this.name}: skipping cookie "${key}" — not written by this adapter.`);
+            return null;
+        }
+        // The cookie jar is shared with the server and every script on the origin.
+        // A cookie that is not our envelope belongs to somebody else; skip it
+        // silently rather than reporting a parse failure about their data.
+        const parsed = this.parseOwnValue(decoded, key);
+        if (!parsed)
+            return null;
+        if (this.isExpired(parsed)) {
+            this.removeSync(key);
             return null;
         }
+        return parsed;
     }
     /**
      * Set a value in cookies
@@ -185,34 +213,30 @@ export class CookieAdapter extends BaseAdapter {
      */
     clearSync(options) {
         if (!options || (!options.pattern && !options.tags && !options.expiredOnly)) {
-            // Clear all cookies with our prefix
-            const cookies = this.getAllCookies();
-            for (const [cookieKey] of cookies) {
-                if (cookieKey.startsWith(this.prefix)) {
-                    this.deleteCookie(cookieKey);
-                }
+            // Delete only the cookies WE wrote. A name-only sweep deletes the
+            // server's session cookie too when the prefix is empty.
+            for (const { cookieKey } of this.ownCookies(true)) {
+                this.deleteCookie(cookieKey);
             }
             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). Driven from
+        // owned entries INCLUDING expired ones, since `expiredOnly` filters on
+        // exactly what `keysSync()` leaves out.
+        for (const { key, value } of this.ownCookies(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);
@@ -229,19 +253,45 @@ export class CookieAdapter extends BaseAdapter {
      * Get all keys (synchronous)
      */
     keysSync(pattern) {
-        const cookies = this.getAllCookies();
-        const keys = [];
-        for (const [cookieKey] of cookies) {
-            if (cookieKey.startsWith(this.prefix)) {
-                const key = cookieKey.substring(this.prefix.length);
-                // Check if not expired
-                const value = this.getSync(key);
-                if (value) {
-                    keys.push(key);
-                }
+        return this.filterKeys(this.ownCookies().map((entry) => entry.key), pattern);
+    }
+    /**
+     * Every cookie on this origin that this adapter actually owns, envelope
+     * already parsed. The cookie jar is shared with the server and with every
+     * script on the origin, so name alone cannot identify our data — shape can.
+     */
+    ownCookies(includeExpired = false) {
+        const owned = [];
+        for (const [cookieKey, raw] of this.getAllCookies()) {
+            if (!cookieKey.startsWith(this.prefix))
+                continue;
+            const key = cookieKey.substring(this.prefix.length);
+            let decoded;
+            try {
+                decoded = decodeURIComponent(raw);
+            }
+            catch {
+                continue;
+            }
+            const value = this.parseOwnValue(decoded, key);
+            if (!value)
+                continue;
+            if (!includeExpired && this.isExpired(value))
+                continue;
+            owned.push({ key, cookieKey, value });
+        }
+        return owned;
+    }
+    /** Reclaim expired cookies, reading each once and reporting a real count. */
+    async cleanupExpired() {
+        let removed = 0;
+        for (const { key, value } of this.ownCookies(true)) {
+            if (this.isExpired(value)) {
+                this.removeSync(key);
+                removed++;
             }
         }
-        return this.filterKeys(keys, pattern);
+        return removed;
     }
     /**
      * Check if key exists (synchronous)

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

@@ -22,6 +22,11 @@ export declare class IndexedDBAdapter extends BaseAdapter {
     /**
      * Initialize the adapter
      */
+    configure(config?: {
+        dbName?: string;
+        storeName?: string;
+        version?: number;
+    }): void;
     initialize(config?: {
         dbName?: string;
         storeName?: string;

package/dist/adapters/web/IndexedDBAdapter.js

@@ -41,13 +41,16 @@ export class IndexedDBAdapter extends BaseAdapter {
     /**
      * Initialize the adapter
      */
-    async initialize(config) {
+    configure(config) {
         if (config?.dbName)
             this.dbName = config.dbName;
         if (config?.storeName)
             this.storeName = config.storeName;
         if (config?.version)
             this.version = config.version;
+    }
+    async initialize(config) {
+        this.configure(config);
         await this.openDatabase();
         this.startTTLCleanup();
     }