strata-storage 2.7.0 → 2.8.0

package/AI-INTEGRATION-GUIDE.md

@@ -1,6 +1,6 @@
 # AI Integration Guide - strata-storage
 
-Quick reference for AI development agents (Claude Code, Cursor, Copilot, etc.) to integrate `strata-storage` into web and mobile projects. Current version: **2.7.0**.
+Quick reference for AI development agents (Claude Code, Cursor, Copilot, etc.) to integrate `strata-storage` into web and mobile projects. Current version: **2.7.1**.
 
 ## Installation
 
@@ -81,7 +81,7 @@ await storage.set('key', value, {
   ttl: 3_600_000,       // expire in 1 hour (ms)
   encrypt: true,        // async only — requires encryption config + password
   compress: true,       // async only
-  tags: ['user-data'],  // for queries
+  tags: ['user-data'],  // grouping; filter with clear({ tags })
   metadata: { version: 1 },
   verify: true,         // store + check an integrity checksum (2.5.0)
   durable: true,        // read back and verify the write (2.5.0)
@@ -90,6 +90,27 @@ await storage.set('key', value, {
 const value = await storage.get('key', { storage: 'indexedDB' });
 ```
 
+## Query data model
+
+`query(condition, options?)` matches the condition against the **stored value's own
+bare fields** (the decoded user value) using MongoDB-style operators
+(`$eq $ne $gt $gte $lt $lte $in $nin $regex $exists $type $and $or $not`):
+
+```typescript
+// matches stored values whose own `status` === 'active' AND `score` >= 10
+const rows = await storage.query<{ status: string; score: number }>({
+  status: 'active',
+  score: { $gte: 10 },
+}); // => Array<{ key: string; value: T }>
+
+// sort/skip/limit/select use bare value field names (no `value.` prefix)
+await storage.query({ status: 'active' }, { sort: { score: -1 }, limit: 20 });
+```
+
+The wrapper fields `key`, `tags`, `created`, `updated`, `expires`, and `metadata`
+are **NOT** queryable via `query()` — they return nothing. Filter by tag with
+`clear({ tags })`, not `query()`.
+
 ## Synchronous API (2.5.0)
 
 No `await`. Works only on sync-capable adapters: `memory`, `localStorage`, `sessionStorage`, `cookies`, `url`.
@@ -270,6 +291,25 @@ const storage = defineStorage({
 | `getTTL`/`extendTTL`/`persist` | TTL management |
 | `registerAdapter(adapter)` | `void` |
 
+## Notes for AI agents
+
+- **Error handling** — every library error class (`QuotaExceededError`,
+  `EncryptionError`, `ValidationError`, `NotFoundError`, `IntegrityError`, etc.)
+  extends `StrataError`. Catch any of them with `catch (e) { if (e instanceof StrataError) … }`.
+- **Server / SSR durability** — the default `storage` singleton uses web adapters and
+  **falls back to non-persistent `memory` on Node/SSR** (no localStorage/IndexedDB there).
+  For durable server storage register `sqlite`/`filesystem` or a custom adapter and
+  target it with `{ storage: '…' }`.
+- **Browser encryption** — `crypto.subtle` requires a **secure context**
+  (HTTPS or `localhost`); encryption throws on insecure-origin pages. Node 20+ is fine.
+- **Sync API limits** — `getSync`/`setSync`/… throw on async-only adapters
+  (indexedDB, cache, sqlite, filesystem, secure, preferences); `setSync` throws if
+  `encrypt`/`compress` is requested, and `getSync` throws on an encrypted/compressed
+  stored value. Use the async API there.
+- **`useStorage` value is `T | null`** — element `[0]` is `null` during initial load
+  and when the key is absent with no default, *even when a defaultValue is passed*.
+  Null-guard before use.
+
 ## Troubleshooting
 
 | Issue | Solution |
@@ -293,3 +333,7 @@ Full documentation lives at **https://stratastorage-docs.aoneahsan.com**:
 - [Recovery & Integrity](https://stratastorage-docs.aoneahsan.com/api/features/recovery)
 - [Changelog](https://stratastorage-docs.aoneahsan.com/reference/changelog)
 - Machine-readable: [`/llms.txt`](https://stratastorage-docs.aoneahsan.com/llms.txt) · [`/llms-full.txt`](https://stratastorage-docs.aoneahsan.com/llms-full.txt)
+
+---
+
+Developed with ❤️ by the **Strata Storage Team** — maintained by [Ahsan Mahmood](https://aoneahsan.com). Questions or integration help: **aoneahsan@gmail.com**.

package/LICENSE

@@ -1,35 +1,21 @@
-Copyright 2024 Ahsan Mahmood
-
-Licensed under the Apache License, Version 2.0 (the "License");
-you may not use this file except in compliance with the License.
-You may obtain a copy of the License at
-
-    http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.
-
-================================================================================
-
-Full Apache License 2.0 text: https://www.apache.org/licenses/LICENSE-2.0.txt
-
-================================================================================
-
-Additional Terms:
-
-1. Attribution Requirement:
-   You must retain all copyright notices and this license in any distribution.
-
-2. Contribution Agreement:
-   Any contributions submitted for inclusion shall be under the same license.
-
-3. Name and Trademark:
-   "Strata Storage" name may not be used for derivative works without permission.
-
-4. Patent Grant:
-   This license includes express patent grants from contributors.
-
-For the complete license terms and plain English explanation, see LICENSE.md
+MIT License
+
+Copyright (c) 2024-2026 Ahsan Mahmood
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -5,12 +5,12 @@
 - **[AI Integration Guide](./AI-INTEGRATION-GUIDE.md)** — quick reference for AI development agents (Claude Code, Cursor, Copilot).
 
 [![npm version](https://img.shields.io/npm/v/strata-storage.svg)](https://www.npmjs.com/package/strata-storage)
-[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 [![TypeScript](https://img.shields.io/badge/TypeScript-strict-blue.svg)](https://www.typescriptlang.org/)
 [![Platform](https://img.shields.io/badge/platform-Web%20%7C%20iOS%20%7C%20Android-lightgrey.svg)](https://stratastorage.aoneahsan.com)
 
-- **Version:** `2.7.0`
-- **License:** Apache-2.0
+- **Version:** `2.8.0`
+- **License:** MIT
 - **Node.js:** `>= 24.13.0`
 - **Module format:** ESM only
 
@@ -478,24 +478,24 @@ Optional peer dependencies (install only the ones you use): `react >= 19.2.3`, `
 
 ## Documentation
 
-📚 **Full documentation: [stratastorage-docs.aoneahsan.com](https://stratastorage-docs.aoneahsan.com)**
-🤖 **For AI agents: [stratastorage-docs.aoneahsan.com/ai](https://stratastorage-docs.aoneahsan.com/ai)** (plus [`/llms.txt`](https://stratastorage-docs.aoneahsan.com/llms.txt) and [`/llms-full.txt`](https://stratastorage-docs.aoneahsan.com/llms-full.txt))
+📚 **Docs:** browse in-repo in [`./docs`](./docs/intro.md) · hosted at [stratastorage-docs.aoneahsan.com](https://stratastorage-docs.aoneahsan.com)
+🤖 **For AI agents:** [`AI-INTEGRATION-GUIDE.md`](./AI-INTEGRATION-GUIDE.md) · hosted [/ai](https://stratastorage-docs.aoneahsan.com/ai) · [`/llms.txt`](https://stratastorage-docs.aoneahsan.com/llms.txt)
 
 ### Getting Started
-- [Installation](https://stratastorage-docs.aoneahsan.com/installation) · [Quick Start](https://stratastorage-docs.aoneahsan.com/quick-start) · [Configuration](https://stratastorage-docs.aoneahsan.com/configuration)
+- [Introduction](./docs/intro.md) · [Installation](./docs/installation.md) · [Quick Start](./docs/quick-start.md) · [Configuration](./docs/configuration.md)
 
 ### API
-- [API Reference](https://stratastorage-docs.aoneahsan.com/api) · [Core (`Strata`)](https://stratastorage-docs.aoneahsan.com/api/core/strata) · [Types](https://stratastorage-docs.aoneahsan.com/api/core/types) · [Errors](https://stratastorage-docs.aoneahsan.com/api/core/errors)
-- [All adapters](https://stratastorage-docs.aoneahsan.com/api/adapters) — web (localStorage, IndexedDB, cookies, Cache, URL, …) + Capacitor (Preferences, Secure, SQLite, Filesystem) + remote (Firebase)
+- [API Reference](./docs/api/README.md) · [Core (`Strata`)](./docs/api/core/strata.md) · [Types](./docs/api/core/types.md) · [Errors](./docs/api/core/errors.md)
+- [All adapters](./docs/api/adapters/README.md) — web (localStorage, IndexedDB, cookies, Cache, URL, …) + Capacitor (Preferences, Secure, SQLite, Filesystem) + remote (Firebase)
 
 ### Features
-- [Encryption](https://stratastorage-docs.aoneahsan.com/guides/features/encryption) · [Compression](https://stratastorage-docs.aoneahsan.com/guides/features/compression) · [TTL](https://stratastorage-docs.aoneahsan.com/api/features/ttl) · [Sync](https://stratastorage-docs.aoneahsan.com/guides/features/sync) · [Queries](https://stratastorage-docs.aoneahsan.com/guides/features/queries) · [Migrations](https://stratastorage-docs.aoneahsan.com/guides/features/migrations) · [Recovery & Integrity](https://stratastorage-docs.aoneahsan.com/api/features/recovery)
+- [Encryption](./docs/guides/features/encryption.md) · [Compression](./docs/guides/features/compression.md) · [TTL](./docs/api/features/ttl.md) · [Sync](./docs/guides/features/sync.md) · [Queries](./docs/guides/features/queries.md) · [Migrations](./docs/guides/features/migrations.md) · [Recovery & Integrity](./docs/api/features/recovery.md)
 
 ### Platforms
-- [Web](https://stratastorage-docs.aoneahsan.com/guides/platforms/web) · [iOS](https://stratastorage-docs.aoneahsan.com/guides/platforms/ios) · [Android](https://stratastorage-docs.aoneahsan.com/guides/platforms/android) · [Capacitor](https://stratastorage-docs.aoneahsan.com/guides/platforms/capacitor) · [Firebase](https://stratastorage-docs.aoneahsan.com/guides/platforms/firebase)
+- [Web](./docs/guides/platforms/web.md) · [iOS](./docs/guides/platforms/ios.md) · [Android](./docs/guides/platforms/android.md) · [Capacitor](./docs/guides/platforms/capacitor.md) · [Firebase](./docs/guides/platforms/firebase.md)
 
 ### Examples & Reference
-- [Examples](https://stratastorage-docs.aoneahsan.com/examples) · [Changelog](https://stratastorage-docs.aoneahsan.com/reference/changelog) · [FAQ](https://stratastorage-docs.aoneahsan.com/reference/faq) · [Troubleshooting](https://stratastorage-docs.aoneahsan.com/reference/troubleshooting) · [Migration](https://stratastorage-docs.aoneahsan.com/migration)
+- [Examples](./docs/examples/README.md) · [Changelog](./docs/reference/changelog.md) · [FAQ](./docs/reference/faq.md) · [Troubleshooting](./docs/reference/troubleshooting.md) · [Migration](./docs/migration.md)
 
 ## Contributing
 
@@ -503,7 +503,7 @@ Contributions are welcome — please read the [Contributing Guide](./.github/CON
 
 ## License
 
-Apache License 2.0 — see [LICENSE](LICENSE). Free for commercial use, modification, and distribution with patent protection; attribution required; provided without warranty.
+MIT License — see [LICENSE](LICENSE). Free for commercial and non-commercial use, modification, distribution, and sublicensing; the only condition is keeping the copyright and license notice; provided without warranty.
 
 ## Author
 
@@ -529,7 +529,9 @@ Apache License 2.0 — see [LICENSE](LICENSE). Free for commercial use, modifica
 
 ---
 
-Made by [Ahsan Mahmood](https://aoneahsan.com). **One API. Every Storage. Everywhere.**
+Developed with ❤️ by the **Strata Storage Team** — maintained by [Ahsan Mahmood](https://aoneahsan.com) · aoneahsan@gmail.com.
+
+**One API. Every Storage. Everywhere.**
 
 <!-- project-links:start -->
 ## Links

package/dist/LICENSE

@@ -1,35 +1,21 @@
-Copyright 2024 Ahsan Mahmood
-
-Licensed under the Apache License, Version 2.0 (the "License");
-you may not use this file except in compliance with the License.
-You may obtain a copy of the License at
-
-    http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.
-
-================================================================================
-
-Full Apache License 2.0 text: https://www.apache.org/licenses/LICENSE-2.0.txt
-
-================================================================================
-
-Additional Terms:
-
-1. Attribution Requirement:
-   You must retain all copyright notices and this license in any distribution.
-
-2. Contribution Agreement:
-   Any contributions submitted for inclusion shall be under the same license.
-
-3. Name and Trademark:
-   "Strata Storage" name may not be used for derivative works without permission.
-
-4. Patent Grant:
-   This license includes express patent grants from contributors.
-
-For the complete license terms and plain English explanation, see LICENSE.md
+MIT License
+
+Copyright (c) 2024-2026 Ahsan Mahmood
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/README.md

@@ -5,12 +5,12 @@
 - **[AI Integration Guide](./AI-INTEGRATION-GUIDE.md)** — quick reference for AI development agents (Claude Code, Cursor, Copilot).
 
 [![npm version](https://img.shields.io/npm/v/strata-storage.svg)](https://www.npmjs.com/package/strata-storage)
-[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 [![TypeScript](https://img.shields.io/badge/TypeScript-strict-blue.svg)](https://www.typescriptlang.org/)
 [![Platform](https://img.shields.io/badge/platform-Web%20%7C%20iOS%20%7C%20Android-lightgrey.svg)](https://stratastorage.aoneahsan.com)
 
-- **Version:** `2.7.0`
-- **License:** Apache-2.0
+- **Version:** `2.8.0`
+- **License:** MIT
 - **Node.js:** `>= 24.13.0`
 - **Module format:** ESM only
 
@@ -478,24 +478,24 @@ Optional peer dependencies (install only the ones you use): `react >= 19.2.3`, `
 
 ## Documentation
 
-📚 **Full documentation: [stratastorage-docs.aoneahsan.com](https://stratastorage-docs.aoneahsan.com)**
-🤖 **For AI agents: [stratastorage-docs.aoneahsan.com/ai](https://stratastorage-docs.aoneahsan.com/ai)** (plus [`/llms.txt`](https://stratastorage-docs.aoneahsan.com/llms.txt) and [`/llms-full.txt`](https://stratastorage-docs.aoneahsan.com/llms-full.txt))
+📚 **Docs:** browse in-repo in [`./docs`](./docs/intro.md) · hosted at [stratastorage-docs.aoneahsan.com](https://stratastorage-docs.aoneahsan.com)
+🤖 **For AI agents:** [`AI-INTEGRATION-GUIDE.md`](./AI-INTEGRATION-GUIDE.md) · hosted [/ai](https://stratastorage-docs.aoneahsan.com/ai) · [`/llms.txt`](https://stratastorage-docs.aoneahsan.com/llms.txt)
 
 ### Getting Started
-- [Installation](https://stratastorage-docs.aoneahsan.com/installation) · [Quick Start](https://stratastorage-docs.aoneahsan.com/quick-start) · [Configuration](https://stratastorage-docs.aoneahsan.com/configuration)
+- [Introduction](./docs/intro.md) · [Installation](./docs/installation.md) · [Quick Start](./docs/quick-start.md) · [Configuration](./docs/configuration.md)
 
 ### API
-- [API Reference](https://stratastorage-docs.aoneahsan.com/api) · [Core (`Strata`)](https://stratastorage-docs.aoneahsan.com/api/core/strata) · [Types](https://stratastorage-docs.aoneahsan.com/api/core/types) · [Errors](https://stratastorage-docs.aoneahsan.com/api/core/errors)
-- [All adapters](https://stratastorage-docs.aoneahsan.com/api/adapters) — web (localStorage, IndexedDB, cookies, Cache, URL, …) + Capacitor (Preferences, Secure, SQLite, Filesystem) + remote (Firebase)
+- [API Reference](./docs/api/README.md) · [Core (`Strata`)](./docs/api/core/strata.md) · [Types](./docs/api/core/types.md) · [Errors](./docs/api/core/errors.md)
+- [All adapters](./docs/api/adapters/README.md) — web (localStorage, IndexedDB, cookies, Cache, URL, …) + Capacitor (Preferences, Secure, SQLite, Filesystem) + remote (Firebase)
 
 ### Features
-- [Encryption](https://stratastorage-docs.aoneahsan.com/guides/features/encryption) · [Compression](https://stratastorage-docs.aoneahsan.com/guides/features/compression) · [TTL](https://stratastorage-docs.aoneahsan.com/api/features/ttl) · [Sync](https://stratastorage-docs.aoneahsan.com/guides/features/sync) · [Queries](https://stratastorage-docs.aoneahsan.com/guides/features/queries) · [Migrations](https://stratastorage-docs.aoneahsan.com/guides/features/migrations) · [Recovery & Integrity](https://stratastorage-docs.aoneahsan.com/api/features/recovery)
+- [Encryption](./docs/guides/features/encryption.md) · [Compression](./docs/guides/features/compression.md) · [TTL](./docs/api/features/ttl.md) · [Sync](./docs/guides/features/sync.md) · [Queries](./docs/guides/features/queries.md) · [Migrations](./docs/guides/features/migrations.md) · [Recovery & Integrity](./docs/api/features/recovery.md)
 
 ### Platforms
-- [Web](https://stratastorage-docs.aoneahsan.com/guides/platforms/web) · [iOS](https://stratastorage-docs.aoneahsan.com/guides/platforms/ios) · [Android](https://stratastorage-docs.aoneahsan.com/guides/platforms/android) · [Capacitor](https://stratastorage-docs.aoneahsan.com/guides/platforms/capacitor) · [Firebase](https://stratastorage-docs.aoneahsan.com/guides/platforms/firebase)
+- [Web](./docs/guides/platforms/web.md) · [iOS](./docs/guides/platforms/ios.md) · [Android](./docs/guides/platforms/android.md) · [Capacitor](./docs/guides/platforms/capacitor.md) · [Firebase](./docs/guides/platforms/firebase.md)
 
 ### Examples & Reference
-- [Examples](https://stratastorage-docs.aoneahsan.com/examples) · [Changelog](https://stratastorage-docs.aoneahsan.com/reference/changelog) · [FAQ](https://stratastorage-docs.aoneahsan.com/reference/faq) · [Troubleshooting](https://stratastorage-docs.aoneahsan.com/reference/troubleshooting) · [Migration](https://stratastorage-docs.aoneahsan.com/migration)
+- [Examples](./docs/examples/README.md) · [Changelog](./docs/reference/changelog.md) · [FAQ](./docs/reference/faq.md) · [Troubleshooting](./docs/reference/troubleshooting.md) · [Migration](./docs/migration.md)
 
 ## Contributing
 
@@ -503,7 +503,7 @@ Contributions are welcome — please read the [Contributing Guide](./.github/CON
 
 ## License
 
-Apache License 2.0 — see [LICENSE](LICENSE). Free for commercial use, modification, and distribution with patent protection; attribution required; provided without warranty.
+MIT License — see [LICENSE](LICENSE). Free for commercial and non-commercial use, modification, distribution, and sublicensing; the only condition is keeping the copyright and license notice; provided without warranty.
 
 ## Author
 
@@ -529,7 +529,9 @@ Apache License 2.0 — see [LICENSE](LICENSE). Free for commercial use, modifica
 
 ---
 
-Made by [Ahsan Mahmood](https://aoneahsan.com). **One API. Every Storage. Everywhere.**
+Developed with ❤️ by the **Strata Storage Team** — maintained by [Ahsan Mahmood](https://aoneahsan.com) · aoneahsan@gmail.com.
+
+**One API. Every Storage. Everywhere.**
 
 <!-- project-links:start -->
 ## Links

package/dist/adapters/capacitor/FilesystemAdapter.d.ts

@@ -43,4 +43,3 @@ export declare class FilesystemAdapter extends BaseAdapter {
      */
     size(detailed?: boolean): Promise<SizeInfo>;
 }
-//# sourceMappingURL=FilesystemAdapter.d.ts.map

package/dist/adapters/capacitor/PreferencesAdapter.d.ts

@@ -43,4 +43,3 @@ export declare class PreferencesAdapter extends BaseAdapter {
      */
     size(detailed?: boolean): Promise<SizeInfo>;
 }
-//# sourceMappingURL=PreferencesAdapter.d.ts.map

package/dist/adapters/capacitor/SecureAdapter.d.ts

@@ -66,4 +66,3 @@ export declare class SecureAdapter extends BaseAdapter {
      */
     getEncryptedPreference(key: string, fileName?: string): Promise<unknown>;
 }
-//# sourceMappingURL=SecureAdapter.d.ts.map

package/dist/adapters/capacitor/SqliteAdapter.d.ts

@@ -86,4 +86,3 @@ export declare class SqliteAdapter extends BaseAdapter {
      */
     transaction(): Promise<Transaction>;
 }
-//# sourceMappingURL=SqliteAdapter.d.ts.map

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

@@ -6,4 +6,3 @@ export { PreferencesAdapter } from "./PreferencesAdapter.js";
 export { SqliteAdapter } from "./SqliteAdapter.js";
 export { SecureAdapter } from "./SecureAdapter.js";
 export { FilesystemAdapter } from "./FilesystemAdapter.js";
-//# sourceMappingURL=index.d.ts.map

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

@@ -88,4 +88,3 @@ export declare class CacheAdapter extends BaseAdapter {
      */
     private isQuotaError;
 }
-//# sourceMappingURL=CacheAdapter.d.ts.map

package/dist/adapters/web/CacheAdapter.js

@@ -3,7 +3,7 @@
  * Provides network-aware storage for offline support
  */
 import { BaseAdapter } from "../../core/BaseAdapter.js";
-import { getObjectSize } from "../../utils/index.js";
+import { getObjectSize, serialize, deserialize } from "../../utils/index.js";
 import { StorageError, QuotaExceededError, NotSupportedError } from "../../utils/errors.js";
 import { logger } from "../../utils/logger.js";
 /**
@@ -84,7 +84,7 @@ export class CacheAdapter extends BaseAdapter {
             const response = await cache.match(url);
             if (!response)
                 return null;
-            const data = (await response.json());
+            const data = deserialize(await response.text());
             // Check TTL
             if (this.isExpired(data)) {
                 await this.remove(key);
@@ -105,8 +105,9 @@ export class CacheAdapter extends BaseAdapter {
         const url = this.keyToUrl(key);
         const oldValue = await this.get(key);
         try {
-            // Create Response with the data
-            const response = new Response(JSON.stringify(value), {
+            // Create Response with the data (shared serialize preserves Date/Map/Set
+            // etc., matching the other adapters instead of raw JSON).
+            const response = new Response(serialize(value), {
                 headers: {
                     'Content-Type': 'application/json',
                     'X-Strata-Created': value.created.toString(),
@@ -130,7 +131,21 @@ export class CacheAdapter extends BaseAdapter {
     async remove(key) {
         const cache = await this.openCache();
         const url = this.keyToUrl(key);
-        const oldValue = await this.get(key);
+        // Read raw via cache.match — NOT via get(), which deletes an expired entry
+        // by awaiting remove(), recursing here and never resolving. Only read when
+        // a listener needs the old value.
+        let oldValue = null;
+        if (this.hasChangeListeners()) {
+            const response = await cache.match(url);
+            if (response) {
+                try {
+                    oldValue = deserialize(await response.text());
+                }
+                catch {
+                    oldValue = null;
+                }
+            }
+        }
         const deleted = await cache.delete(url);
         if (deleted && oldValue) {
             this.emitChange(key, oldValue.value, undefined, 'local');

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

@@ -110,4 +110,3 @@ export declare class CookieAdapter extends BaseAdapter {
     private getAllCookies;
 }
 export {};
-//# sourceMappingURL=CookieAdapter.d.ts.map

package/dist/adapters/web/CookieAdapter.js

@@ -3,6 +3,7 @@
  * Provides limited storage with 4KB per cookie limit
  */
 import { BaseAdapter } from "../../core/BaseAdapter.js";
+import { serialize, deserialize } from "../../utils/index.js";
 import { StorageError, QuotaExceededError } from "../../utils/errors.js";
 import { logger } from "../../utils/logger.js";
 /**
@@ -92,7 +93,7 @@ export class CookieAdapter extends BaseAdapter {
             return null;
         try {
             const decoded = decodeURIComponent(value);
-            const parsed = JSON.parse(decoded);
+            const parsed = deserialize(decoded);
             // Check TTL
             if (this.isExpired(parsed)) {
                 this.removeSync(key);
@@ -118,7 +119,7 @@ export class CookieAdapter extends BaseAdapter {
         const cookieKey = this.prefix + key;
         const oldValue = this.getSync(key);
         try {
-            const serialized = JSON.stringify(value);
+            const serialized = serialize(value);
             const encoded = encodeURIComponent(serialized);
             // Check size limit
             if (encoded.length > this.maxCookieSize) {
@@ -153,8 +154,21 @@ export class CookieAdapter extends BaseAdapter {
      * Remove a value from cookies (synchronous)
      */
     removeSync(key) {
-        const oldValue = this.getSync(key);
         const cookieKey = this.prefix + key;
+        // Read raw — NOT via getSync(), which deletes expired cookies by calling
+        // removeSync() and would recurse here forever. Only read with a listener.
+        let oldValue = null;
+        if (this.hasChangeListeners()) {
+            const raw = this.getCookie(cookieKey);
+            if (raw) {
+                try {
+                    oldValue = deserialize(decodeURIComponent(raw));
+                }
+                catch {
+                    oldValue = null;
+                }
+            }
+        }
         this.deleteCookie(cookieKey);
         if (oldValue) {
             this.emitChange(key, oldValue.value, undefined, 'local');
@@ -289,6 +303,16 @@ export class CookieAdapter extends BaseAdapter {
     setCookie(name, value, options = {}) {
         if (typeof document === 'undefined')
             return;
+        // The value is percent-encoded by the caller, but the NAME is written raw —
+        // reject cookie-control characters in it so a crafted key cannot inject
+        // extra attributes (`; Path=/`) or additional cookies (`; evil=1`).
+        const hasControlChar = [...name].some((ch) => {
+            const code = ch.charCodeAt(0);
+            return code < 0x20 || code === 0x7f;
+        });
+        if (/[;=,\s]/.test(name) || hasControlChar) {
+            throw new StorageError(`Invalid cookie name "${name}": contains forbidden characters`);
+        }
         let cookie = `${name}=${value}`;
         if (options.maxAge !== undefined) {
             cookie += `; max-age=${options.maxAge}`;

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

@@ -82,4 +82,3 @@ export declare class IndexedDBAdapter extends BaseAdapter {
      */
     private isQuotaError;
 }
-//# sourceMappingURL=IndexedDBAdapter.d.ts.map

package/dist/adapters/web/IndexedDBAdapter.js

@@ -139,7 +139,11 @@ export class IndexedDBAdapter extends BaseAdapter {
      */
     async remove(key) {
         const db = await this.openDatabase();
-        const oldValue = await this.get(key);
+        // Only read the old value when a listener needs it. get() on an expired key
+        // fire-and-forgets remove(), so an unconditional read here spawns redundant
+        // remove→get cycles; gating also drops the read for this observable:false
+        // adapter.
+        const oldValue = this.hasChangeListeners() ? await this.get(key) : null;
         const { promise, resolve, reject } = createDeferred();
         const transaction = db.transaction([this.storeName], 'readwrite');
         const store = transaction.objectStore(this.storeName);

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

@@ -91,4 +91,3 @@ export declare class LocalStorageAdapter extends BaseAdapter {
      */
     protected isQuotaError(error: unknown): boolean;
 }
-//# sourceMappingURL=LocalStorageAdapter.d.ts.map

package/dist/adapters/web/LocalStorageAdapter.js

@@ -132,7 +132,21 @@ export class LocalStorageAdapter extends BaseAdapter {
      * Remove a value from localStorage (synchronous)
      */
     removeSync(key) {
-        const oldValue = this.getSync(key);
+        // Read the raw stored value directly — NOT via getSync(), which deletes an
+        // expired entry by calling removeSync(), recursing here forever (stack
+        // 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;
+                }
+            }
+        }
         this.getStorage().removeItem(this.prefix + key);
         if (oldValue) {
             this.emitChange(key, oldValue.value, undefined, 'local');

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

@@ -27,6 +27,13 @@ export declare class MemoryAdapter extends BaseAdapter {
      * Get a value from memory
      */
     get<T = unknown>(key: string): Promise<StorageValue<T> | null>;
+    /**
+     * Clone a stored value to isolate it from external mutation. Prefers
+     * structuredClone (preserves Map/Set/Date/TypedArray/ArrayBuffer — so the
+     * advertised `binary: true` capability holds), falling back to deepClone where
+     * structuredClone is unavailable or the value isn't structured-cloneable.
+     */
+    private clone;
     /**
      * Get a value from memory (synchronous)
      */
@@ -90,4 +97,3 @@ export declare class MemoryAdapter extends BaseAdapter {
      */
     close(): Promise<void>;
 }
-//# sourceMappingURL=MemoryAdapter.d.ts.map

package/dist/adapters/web/MemoryAdapter.js

@@ -43,6 +43,23 @@ export class MemoryAdapter extends BaseAdapter {
     async get(key) {
         return this.getSync(key);
     }
+    /**
+     * Clone a stored value to isolate it from external mutation. Prefers
+     * structuredClone (preserves Map/Set/Date/TypedArray/ArrayBuffer — so the
+     * advertised `binary: true` capability holds), falling back to deepClone where
+     * structuredClone is unavailable or the value isn't structured-cloneable.
+     */
+    clone(value) {
+        if (typeof structuredClone === 'function') {
+            try {
+                return structuredClone(value);
+            }
+            catch {
+                // Fall through to deepClone (e.g. value carries a non-cloneable field).
+            }
+        }
+        return deepClone(value);
+    }
     /**
      * Get a value from memory (synchronous)
      */
@@ -55,8 +72,8 @@ export class MemoryAdapter extends BaseAdapter {
             this.removeSync(key);
             return null;
         }
-        // Return a deep clone to prevent external modifications
-        return deepClone(value);
+        // Return a clone to prevent external modifications
+        return this.clone(value);
     }
     /**
      * Set a value in memory
@@ -83,8 +100,8 @@ export class MemoryAdapter extends BaseAdapter {
                 });
             }
         }
-        // Store a deep clone to prevent external modifications
-        const clonedValue = deepClone(value);
+        // Store a clone to prevent external modifications
+        const clonedValue = this.clone(value);
         this.storage.set(key, clonedValue);
         // Update size tracking
         if (oldValue) {
@@ -214,7 +231,7 @@ export class MemoryAdapter extends BaseAdapter {
                 if (matches) {
                     results.push({
                         key,
-                        value: deepClone(item.value),
+                        value: this.clone(item.value),
                     });
                 }
             }