localspace 0.3.0 → 1.0.0

package/README.md

@@ -23,6 +23,7 @@ We stay 100% compatible with localForage on the surface, but rebuild the interna
 Starting fresh let us eliminate technical debt while maintaining API compatibility. The codebase is written in modern TypeScript, uses contemporary patterns, and has a clear structure that makes it straightforward to add new capabilities. Teams can migrate from localForage without changing application code, then unlock better developer experience and future extensibility.
 
 ## Table of Contents
+
 - [Motivation](#motivation)
   - [What needed to change](#what-needed-to-change)
   - [How localspace responds](#how-localspace-responds)
@@ -35,6 +36,7 @@ Starting fresh let us eliminate technical debt while maintaining API compatibili
   - [Configure isolated stores for clear data boundaries](#configure-isolated-stores-for-clear-data-boundaries)
   - [Choose drivers with predictable fallbacks](#choose-drivers-with-predictable-fallbacks)
   - [Handle binary data across browsers](#handle-binary-data-across-browsers)
+  - [Advanced: Coalesced Writes (IndexedDB only)](#advanced-coalesced-writes-indexeddb-only)
 - [Migration Guide](#migration-guide)
   - [Note differences from localForage before upgrading](#note-differences-from-localforage-before-upgrading)
   - [Enable compatibility mode for legacy callbacks](#enable-compatibility-mode-for-legacy-callbacks)
@@ -46,17 +48,19 @@ Starting fresh let us eliminate technical debt while maintaining API compatibili
 localspace is built on a foundation designed for growth. Here's what's planned:
 
 ### Core Compatibility (Complete)
+
 - [x] IndexedDB and localStorage drivers
 - [x] Full localForage API parity
 - [x] TypeScript-first implementation
 - [x] Comprehensive test coverage
 - [x] Modern build pipeline (ES modules, CommonJS, UMD)
 - [x] Batch operations (`setItems()`, `getItems()`, `removeItems()`) for higher throughput
-- [x] Automatic write coalescing (3-10x faster rapid writes, enabled by default)
+- [x] Automatic write coalescing (3-10x faster rapid writes, opt-in for IndexedDB)
 - [x] Connection pooling, transaction batching, and warmup
 - [x] **Improved error handling** - Structured error types with detailed context
 
 ### TODO
+
 - [x] **Plugin system** - Middleware architecture for cross-cutting concerns
 - [ ] **OPFS driver** - Origin Private File System for high-performance file storage
 - [ ] **Custom driver templates** - Documentation and examples for third-party drivers
@@ -79,6 +83,7 @@ We prioritize features based on community feedback. If you need a specific capab
 3. **Contribute** - We welcome PRs for new drivers, plugins, or improvements
 
 **Want to help?** The most impactful contributions right now:
+
 - Testing in diverse environments (browsers, frameworks, edge cases)
 - Documentation improvements and usage examples
 - Performance benchmarks and optimization suggestions
@@ -87,6 +92,7 @@ We prioritize features based on community feedback. If you need a specific capab
 ## Installation and Usage
 
 ### localspace delivers modern storage compatibility
+
 localspace targets developers who need localForage's API surface without its historical baggage. **You get the same method names, configuration options, and driver constants, all implemented with modern JavaScript and TypeScript types.**
 
 - Promise-first API with optional callbacks
@@ -95,6 +101,7 @@ localspace targets developers who need localForage's API surface without its his
 - Drop-in TypeScript generics for value typing
 
 ### Install and import localspace
+
 Install the package with your preferred package manager and import it once at the entry point where you manage storage.
 
 ```bash
@@ -110,6 +117,7 @@ import localspace from 'localspace';
 ```
 
 ### Store data with async flows or callbacks
+
 Use async/await for the clearest flow. **Callbacks remain supported for parity with existing localForage codebases.**
 
 ```ts
@@ -122,8 +130,9 @@ localspace.getItem('user', (error, value) => {
 });
 ```
 
-### 🚀 Get automatic performance optimization (enabled by default)
-localspace automatically merges rapid single writes into batched transactions, giving you **3-10x performance improvement** without changing your code. This feature is enabled by default and works transparently in the background.
+### 🚀 Opt into automatic performance optimization (coalesced writes)
+
+localspace can merge rapid single writes into batched transactions for IndexedDB, giving you **3-10x performance improvement** under write-heavy bursts. This is opt-in so default behavior stays predictable; enable it when you know you have high write pressure.
 
 ```ts
 // Your existing code - unchanged
@@ -137,22 +146,21 @@ await Promise.all([
 // ✅ Zero code changes required
 ```
 
-**How it works**: When using IndexedDB, rapid writes within an 8ms window are automatically merged into a single transaction commit. This is transparent to your application and has no impact on single writes.
+**How it works**: When using IndexedDB, rapid writes within an 8ms window are merged into a single transaction commit. This is transparent to your application and has no impact on single writes.
+
+**Turn it on or tune it**
 
-**Want to customize or disable it?**
 ```ts
 const instance = localspace.createInstance({
-  coalesceWrites: true,      // enabled by default
-  coalesceWindowMs: 8,       // 8ms window (default)
-});
-
-// Or disable if you need strict per-operation durability
-const strict = localspace.createInstance({
-  coalesceWrites: false,
+  coalesceWrites: true, // opt-in (default is false)
+  coalesceWindowMs: 8, // 8ms window (default)
 });
 ```
 
+For consistency modes, batch limits, and failure semantics, see **Advanced: Coalesced Writes** below.
+
 **When is this useful?**
+
 - Form auto-save that writes multiple fields rapidly
 - Bulk state synchronization loops
 - Real-time collaborative editing
@@ -161,6 +169,7 @@ const strict = localspace.createInstance({
 **Performance impact**: Single infrequent writes are unaffected. Rapid sequential writes get 3-10x faster automatically.
 
 **Want to see the actual performance gains?**
+
 ```ts
 // Get statistics to see how much coalescing helped (IndexedDB only)
 const stats = localspace.getPerformanceStats?.();
@@ -174,6 +183,7 @@ console.log(stats);
 ```
 
 ### Boost throughput with batch operations
+
 Use the batch APIs to group writes and reads into single transactions for IndexedDB and localStorage. This reduces commit overhead and benefits from Chrome’s relaxed durability defaults (see below).
 
 ```ts
@@ -210,17 +220,21 @@ await Promise.all([
 
 // These features work independently and can be combined
 const optimized = localspace.createInstance({
-  coalesceWrites: true,    // optimizes single-item writes (setItem/removeItem)
+  coalesceWrites: true, // optimizes single-item writes (setItem/removeItem)
   coalesceWindowMs: 8,
-  maxBatchSize: 200,       // limits batch API chunk size (setItems/removeItems)
+  maxBatchSize: 200, // limits batch API chunk size (setItems/removeItems)
 });
 await optimized.setDriver([optimized.INDEXEDDB]);
 
-// Note: localStorage batches are not atomic—writes are applied one by one.
-// For critical flows, prefer IndexedDB or handle your own compensating logic.
+// Note: localStorage batches attempt best-effort rollback on failure and map
+// quota errors to QUOTA_EXCEEDED, but they still serialize per-item and are
+// not truly atomic. For strict atomicity or durability, prefer IndexedDB or
+// add your own compensating logic. If you need per-item success/failure, call
+// setItems in smaller chunks or handle errors explicitly.
 ```
 
 ### Run your own transaction
+
 When you need atomic multi-step work (migrations, dependent writes), wrap operations in a single transaction. On IndexedDB this uses one `IDBTransaction`; on localStorage it executes sequentially.
 
 ```ts
@@ -234,6 +248,7 @@ await localspace.runTransaction('readwrite', async (tx) => {
 ```
 
 ### Configure isolated stores for clear data boundaries
+
 Create independent instances when you want to separate cache layers or product features. Each instance can override defaults like `name`, `storeName`, and driver order.
 
 ```ts
@@ -246,6 +261,7 @@ await sessionCache.setItem('token', 'abc123');
 ```
 
 ### Choose drivers with predictable fallbacks
+
 By default, localspace prefers IndexedDB (`INDEXEDDB`) and falls back to localStorage (`LOCALSTORAGE`). Configure alternative sequences as needed.
 
 ```ts
@@ -273,6 +289,7 @@ await bucketed.setDriver([bucketed.INDEXEDDB]);
 **Tip:** Use `defineDriver()` and `getDriver()` to register custom drivers that match the localForage interface.
 
 ### Handle binary data across browsers
+
 localspace serializes complex values transparently. It stores `Blob`, `ArrayBuffer`, and typed arrays in IndexedDB natively and in localStorage via Base64 encoding when necessary. You write the same code regardless of the driver.
 
 ```ts
@@ -281,6 +298,140 @@ await localspace.setItem('file', file);
 const restored = await localspace.getItem<Blob>('file');
 ```
 
+## Advanced: Coalesced Writes (IndexedDB only)
+
+localspace offers an opt-in, configurable coalesced write path to cut IndexedDB transaction count and improve throughput under heavy write bursts.
+
+> `coalesceWrites` defaults to `false` so behavior stays predictable. Turn it on when you expect high-frequency writes.
+
+### Why coalesce writes?
+
+Each IndexedDB write opens a readwrite transaction. At high frequency, transaction startup overhead becomes a bottleneck. With coalescing enabled, `setItem` and `removeItem` calls that land within a short window (default 8 ms) are merged into fewer transactions:
+
+- Multiple writes can share one transaction.
+- `coalesceMaxBatchSize` caps how many ops each flush processes.
+- `coalesceReadConsistency` controls when writes resolve and when reads see them.
+
+### Configuration
+
+Relevant `LocalSpaceConfig` fields:
+
+```ts
+interface LocalSpaceConfig {
+  /**
+   * Enable coalesced writes (IndexedDB only).
+   * Default: false
+   */
+  coalesceWrites?: boolean;
+
+  /**
+   * Time window (ms) for merging writes into the same batch.
+   * Default: 8
+   */
+  coalesceWindowMs?: number;
+
+  /**
+   * Maximum operations per flush batch. Beyond this, flush immediately
+   * and split into multiple transactions.
+   * Default: undefined (no limit)
+   */
+  coalesceMaxBatchSize?: number;
+
+  /**
+   * When coalesceWrites is on:
+   * - 'strong' (default): drain pending writes before reads
+   * - 'eventual': reads skip draining; writes only guarantee queueing
+   */
+  coalesceReadConsistency?: 'strong' | 'eventual';
+}
+```
+
+### Consistency modes
+
+#### `coalesceReadConsistency: 'strong'` (default)
+
+- Writes (`setItem` / `removeItem`): Promises resolve after the data is persisted; flush errors reject.
+- Reads (`getItem`, `iterate`, batch reads): call `drainCoalescedWrites` first so you read what you just wrote.
+
+Use this for user settings, drafts, and any flow where you need read-your-writes.
+
+#### `coalesceReadConsistency: 'eventual'`
+
+- Writes: queued and resolve immediately once enqueued; flush happens in the background. Errors log `console.warn('[localspace] coalesced write failed (eventual mode)', error)` but do not reject the earlier Promise.
+- Reads: do not flush pending writes, so you may briefly see stale values.
+- Destructive operations still force a flush to avoid dropping queued writes: `removeItems`, `clear`, `dropInstance`.
+
+Use this for logs/analytics or workloads that can tolerate short windows of staleness in exchange for the lightest write path.
+
+### Bounding batch size
+
+```ts
+const store = localspace.createInstance({
+  name: 'logs',
+  storeName: 'events',
+  coalesceWrites: true,
+  coalesceWindowMs: 8,
+  coalesceMaxBatchSize: 64,
+  coalesceReadConsistency: 'eventual',
+});
+```
+
+- When the queue reaches `coalesceMaxBatchSize`, it flushes immediately.
+- Flush splits work into batches of up to 64 ops, each in its own transaction.
+- `getPerformanceStats()` reports `totalWrites`, `coalescedWrites`, and `transactionsSaved` so you can see the gains.
+
+### Recommended recipes
+
+1. Default: coalescing off
+
+```ts
+const store = localspace.createInstance({
+  name: 'app',
+  storeName: 'keyvaluepairs',
+  // coalesceWrites is false by default
+});
+```
+
+2. High-frequency writes with eventual consistency
+
+```ts
+const logStore = localspace.createInstance({
+  name: 'analytics',
+  storeName: 'events',
+  coalesceWrites: true,
+  coalesceWindowMs: 8,
+  coalesceMaxBatchSize: 64,
+  coalesceReadConsistency: 'eventual',
+});
+```
+
+- `setItem` resolves almost immediately.
+- Short windows of stale reads are acceptable.
+- `clear` and `dropInstance` force-flush so queued writes are not lost.
+
+3. Strong consistency with bounded batches
+
+```ts
+const userStore = localspace.createInstance({
+  name: 'user-data',
+  storeName: 'kv',
+  coalesceWrites: true,
+  coalesceWindowMs: 8,
+  coalesceMaxBatchSize: 32,
+  coalesceReadConsistency: 'strong',
+});
+```
+
+- Writes resolve after persistence.
+- Reads flush pending writes first.
+- Batching still reduces transaction count.
+
+### Caveats
+
+- Coalesced writes apply to the IndexedDB driver only; localStorage always writes per operation.
+- In `eventual` mode, writes can be lost if the page closes before flush completes, and errors surface only via `console.warn`.
+- For critical durability (orders, payments, irreversible state), avoid `eventual` and consider leaving `coalesceWrites` off entirely.
+
 ## Plugin System
 
 localspace now ships with a first-class plugin engine. Attach middleware when creating an instance or call `use()` later; plugins can mutate payloads, observe driver context, and run async interceptors around every storage call.
@@ -291,8 +442,8 @@ const store = localspace.createInstance({
   storeName: 'primary',
   plugins: [
     ttlPlugin({ defaultTTL: 60_000 }),
-    encryptionPlugin({ key: '0123456789abcdef0123456789abcdef' }),
     compressionPlugin({ threshold: 1024 }),
+    encryptionPlugin({ key: '0123456789abcdef0123456789abcdef' }),
     syncPlugin({ channelName: 'localspace-sync' }),
     quotaPlugin({ maxSize: 5 * 1024 * 1024, evictionPolicy: 'lru' }),
   ],
@@ -303,69 +454,278 @@ const store = localspace.createInstance({
 
 - **Registration** – supply `plugins` when calling `createInstance()` or chain `instance.use(plugin)` later. Each plugin can also expose `enabled` (boolean or function) and `priority` to control execution order.
 - **Lifecycle events** – `onInit(context)` is invoked after `ready()`, and `onDestroy` lets you tear down timers or channels. Call `await instance.destroy()` when disposing of an instance to run every `onDestroy` hook (executed in reverse priority order). Context exposes the active driver, db info, config, and a shared `metadata` bag for cross-plugin coordination.
-- **Interceptors** – hook into `beforeSet/afterSet`, `beforeGet/afterGet`, `beforeRemove/afterRemove`, plus batch-specific methods such as `beforeSetItems` or `beforeGetItems`. Hooks run sequentially: `before*` hooks execute from highest to lowest priority, while `after*` hooks unwind in reverse order so layered transformations (compression → encryption → TTL) remain invertible. Returning a value passes it to the next plugin, while throwing a `LocalSpaceError` aborts the operation.
+- **Interceptors** – hook into `beforeSet/afterSet`, `beforeGet/afterGet`, `beforeRemove/afterRemove`, plus batch-specific methods such as `beforeSetItems` or `beforeGetItems`. Hooks run sequentially: `before*` hooks execute from highest to lowest priority, while `after*` hooks unwind in reverse order so layered transformations (TTL → compression → encryption) remain invertible. Returning a value passes it to the next plugin, while throwing a `LocalSpaceError` aborts the operation.
 - **Per-call state** – plugins can stash data on `context.operationState` (e.g., capture the original value in `beforeSet` and reuse it in `afterSet`). For batch operations, `context.operationState.isBatch` is `true` and `context.operationState.batchSize` provides the total count.
-- **Error handling & init policy** – unexpected exceptions are reported through `plugin.onError`. Throw a `LocalSpaceError` if you need to stop the pipeline (quota violations, failed decryptions, etc.). If a plugin `onInit` throws, the default policy is fail-fast (propagate and abort init). Set `pluginInitPolicy: 'disable-and-continue'` in config to log and skip the failing plugin instead (use with care for critical plugins like encryption).
+- **Error handling & policies** – unexpected exceptions are reported through `plugin.onError`. Throw a `LocalSpaceError` if you need to stop the pipeline (quota violations, failed decryptions, etc.). Init policy: default fail-fast; set `pluginInitPolicy: 'disable-and-continue'` to log and skip the failing plugin. Runtime policy: default `pluginErrorPolicy: 'strict'` propagates all plugin errors; only use `lenient` if you explicitly accept swallowed errors, and avoid lenient for encryption/compression/ttl or any correctness-critical plugin.
 
 ### Plugin execution order
 
 Plugins are sorted by `priority` (higher runs first in `before*`, last in `after*`). Default priorities:
 
-| Plugin | Priority | Notes |
-|--------|----------|-------|
-| sync | -100 | Runs last in `afterSet` to broadcast original (untransformed) values |
-| quota | -10 | Runs late so it measures final payload sizes |
-| ttl, encryption, compression | 0 | Default; chain in registration order |
+| Plugin      | Priority | Notes                                                                |
+| ----------- | -------- | -------------------------------------------------------------------- |
+| sync        | -100     | Runs last in `afterSet` to broadcast original (untransformed) values |
+| quota       | -10      | Runs late so it measures final payload sizes                         |
+| encryption  | 0        | Encrypts after compression so decrypt runs first in `after*`         |
+| compression | 5        | Runs before encryption so payload is compressible                    |
+| ttl         | 10       | Runs outermost so TTL wrapper is transformed by other plugins        |
 
-**Recommended order**: `[ttlPlugin, encryptionPlugin, compressionPlugin, syncPlugin, quotaPlugin]`
+**Recommended order**: `[ttlPlugin, compressionPlugin, encryptionPlugin, syncPlugin, quotaPlugin]`
 
 ### Built-in plugins
 
 #### TTL plugin
+
 Wraps values as `{ data, expiresAt }`, invalidates stale reads, and optionally runs background cleanup. Options:
 
 - `defaultTTL` (ms) and `keyTTL` overrides
-- `cleanupInterval` to periodically scan `iterate()` output
+- `cleanupInterval` to periodically scan expired entries
+- `cleanupBatchSize` (default: 100) for efficient batch cleanup
 - `onExpire(key, value)` callback before removal
 
+```ts
+// Cache API responses for 5 minutes
+const cacheStore = localspace.createInstance({
+  name: 'api-cache',
+  plugins: [
+    ttlPlugin({
+      defaultTTL: 5 * 60 * 1000, // 5 minutes
+      keyTTL: {
+        'user-profile': 30 * 60 * 1000, // 30 minutes for user data
+        'session-token': 60 * 60 * 1000, // 1 hour for session
+      },
+      cleanupInterval: 60 * 1000, // Cleanup every minute
+      cleanupBatchSize: 50, // Process 50 keys at a time
+      onExpire: (key, value) => {
+        console.log(`Cache expired: ${key}`);
+      },
+    }),
+  ],
+});
+
+// Single item and batch operations both respect TTL
+await cacheStore.setItem('user-profile', userData);
+await cacheStore.setItems([
+  { key: 'post-1', value: post1 },
+  { key: 'post-2', value: post2 },
+]);
+```
+
 #### Encryption plugin
+
 Encrypts serialized payloads using the Web Crypto API (AES-GCM by default) and decrypts transparently on reads.
 
 - Provide a `key` (CryptoKey/ArrayBuffer/string) or `keyDerivation` block (PBKDF2)
 - Customize `algorithm`, `ivLength`, `ivGenerator`, or `randomSource`
 - Works in browsers and modern Node runtimes (pass your own `subtle` when needed)
 
+```ts
+// Using a direct key
+const secureStore = localspace.createInstance({
+  name: 'secure-store',
+  plugins: [
+    encryptionPlugin({
+      key: '0123456789abcdef0123456789abcdef', // 32 bytes for AES-256
+    }),
+  ],
+});
+
+// Using PBKDF2 key derivation (recommended for password-based encryption)
+const passwordStore = localspace.createInstance({
+  name: 'password-store',
+  plugins: [
+    encryptionPlugin({
+      keyDerivation: {
+        passphrase: userPassword,
+        salt: 'unique-per-user-salt',
+        iterations: 150000, // Higher = more secure but slower
+        hash: 'SHA-256',
+        length: 256,
+      },
+    }),
+  ],
+});
+
+// Batch operations are also encrypted
+await secureStore.setItems([
+  { key: 'card-number', value: '4111-1111-1111-1111' },
+  { key: 'cvv', value: '123' },
+]);
+```
+
 #### Compression plugin
+
 Runs LZ-string compression (or a custom codec) when payloads exceed a `threshold` and restores them on read.
 
 - `threshold` (bytes) controls when compression kicks in
 - Supply a custom `{ compress, decompress }` codec if you prefer pako/Brotli
 
+```ts
+const compressedStore = localspace.createInstance({
+  name: 'compressed-store',
+  plugins: [
+    compressionPlugin({
+      threshold: 1024, // Only compress if > 1KB
+      algorithm: 'lz-string', // Label stored in metadata
+    }),
+  ],
+});
+
+// Custom codec example (using pako)
+import pako from 'pako';
+
+const pakoStore = localspace.createInstance({
+  name: 'pako-store',
+  plugins: [
+    compressionPlugin({
+      threshold: 512,
+      algorithm: 'gzip',
+      codec: {
+        compress: (data) => pako.gzip(data),
+        decompress: (data) => pako.ungzip(data, { to: 'string' }),
+      },
+    }),
+  ],
+});
+```
+
 #### Sync plugin
+
 Keeps multiple tabs/processes in sync via `BroadcastChannel` (with `storage`-event fallback).
 
 - `channelName` separates logical buses
 - `syncKeys` lets you scope which keys broadcast
 - `conflictStrategy` defaults to `last-write-wins`; provide `onConflict` (return `false` to drop remote writes) for merge logic
 
+```ts
+const syncedStore = localspace.createInstance({
+  name: 'synced-store',
+  plugins: [
+    syncPlugin({
+      channelName: 'my-app-sync',
+      syncKeys: ['cart', 'preferences', 'theme'], // Only sync these keys
+      conflictStrategy: 'last-write-wins',
+      onConflict: ({ key, localTimestamp, incomingTimestamp, value }) => {
+        console.log(`Conflict on ${key}: local=${localTimestamp}, incoming=${incomingTimestamp}`);
+        // Return false to reject the incoming change
+        return localTimestamp < incomingTimestamp;
+      },
+    }),
+  ],
+});
+
+// Changes sync across tabs automatically
+await syncedStore.setItem('cart', { items: [...] });
+await syncedStore.setItems([
+  { key: 'preferences', value: { darkMode: true } },
+  { key: 'theme', value: 'blue' },
+]);
+```
+
 #### Quota plugin
+
 Tracks approximate storage usage after every mutation and enforces limits.
 
-- `maxSize` (bytes) and optional `useNavigatorEstimate` to read the browser’s quota
+- `maxSize` (bytes) and optional `useNavigatorEstimate` to read the browser's quota
 - `evictionPolicy: 'error' | 'lru'` (LRU removes least-recently-used keys automatically)
 - `onQuotaExceeded(info)` fires before throwing so you can log/alert users
 
+```ts
+const quotaStore = localspace.createInstance({
+  name: 'quota-store',
+  plugins: [
+    quotaPlugin({
+      maxSize: 5 * 1024 * 1024, // 5 MB
+      evictionPolicy: 'lru', // Automatically evict least-recently-used items
+      useNavigatorEstimate: true, // Also respect browser quota
+      onQuotaExceeded: ({ key, attemptedSize, maxSize, currentUsage }) => {
+        console.warn(`Quota exceeded: tried to write ${attemptedSize} bytes`);
+        console.warn(`Current usage: ${currentUsage}/${maxSize} bytes`);
+      },
+    }),
+  ],
+});
+
+// Batch operations are also quota-checked
+await quotaStore.setItems([
+  { key: 'large-1', value: largeData1 },
+  { key: 'large-2', value: largeData2 },
+]); // Throws QUOTA_EXCEEDED if total exceeds limit
+```
+
 > Tip: place quota plugins last so they see the final payload size after other transformations (TTL, encryption, compression, etc.).
 
+### Plugin combination best practices
+
+1. **Recommended plugin order** (from highest to lowest priority):
+   ```ts
+   plugins: [
+     ttlPlugin({ ... }),         // priority: 10
+     compressionPlugin({ ... }), // priority: 5
+     encryptionPlugin({ ... }),  // priority: 0
+     quotaPlugin({ ... }),       // priority: -10
+     syncPlugin({ ... }),        // priority: -100
+   ]
+   ```
+
+2. **Always compress before encrypting**: Encrypted data has high entropy and compresses poorly. The default priorities handle this automatically.
+
+3. **Use strict error policy with security-critical plugins**:
+   ```ts
+   // DON'T do this - encryption failures will be silently swallowed
+   const bad = localspace.createInstance({
+     plugins: [encryptionPlugin({ key })],
+     pluginErrorPolicy: 'lenient', // Dangerous!
+   });
+
+   // DO this - encryption failures will propagate
+   const good = localspace.createInstance({
+     plugins: [encryptionPlugin({ key })],
+     pluginErrorPolicy: 'strict', // Safe (default)
+   });
+   ```
+
+4. **Batch operations work with all plugins**: All built-in plugins support `setItems`, `getItems`, and `removeItems`.
+
+### Plugin troubleshooting
+
+| Issue | Solution |
+|-------|----------|
+| TTL items not expiring | Ensure `cleanupInterval` is set, or read items to trigger expiration |
+| Encryption fails silently | Check `pluginErrorPolicy` is not 'lenient' |
+| Compression not working | Verify payload exceeds `threshold` |
+| Sync not updating other tabs | Check `channelName` matches and `syncKeys` includes your key |
+| Quota errors on small writes | Other plugins (TTL, encryption) add overhead; account for wrapper size |
+| Plugin order seems wrong | Check `priority` values; higher = runs first in `before*` hooks |
+
+## Compatibility & environments
+
+- Browsers: modern Chromium/Edge, Firefox, Safari (desktop & iOS). IndexedDB is required for the primary driver; localStorage is available as a fallback.
+- Known differences: Safari private mode / low-quota environments may throw quota; IndexedDB durability hints may be ignored outside Chromium 121+. If you need strict durability, prefer explicit flush/transaction patterns.
+- Node/SSR: browser storage APIs are not available by default; supply a custom driver or guard usage in non-browser contexts.
+
+## Testing & CI
+
+- Recommended pipeline: `yarn lint` (if configured) → `yarn vitest run` → `yarn build` → `playwright test`.
+- Regression coverage includes: coalesced writes + pending queue + maxConcurrentTransactions + idle close, plugin error policies (strict/lenient) including batch hooks, compression/encryption/ttl ordering, sync version persistence, localStorage quota handling with rollback.
+
+## Security & performance guidance
+
+- Plugin order for correctness/performance: `ttl → compression → encryption → sync → quota`.
+- The encryption plugin provides basic crypto; key management/rotation is your responsibility, and you should not swallow encryption/compression errors via a lenient policy.
+- Run compression before encryption for effectiveness; place quota last to see final sizes; keep sync last in `after*` to broadcast original values.
+
 ## Migration Guide
 
 ### Note differences from localForage before upgrading
+
 - `dropInstance()` throws a real `Error` when arguments are invalid. Examine `error.message` instead of comparing string literals.
 - Blob capability checks run on each request instead of being cached. Cache the result in your application if repeated blob writes dominate your workload.
 - **WebSQL is intentionally unsupported.** Migrate any WebSQL-only code to IndexedDB or localStorage before switching.
 
 ### Enable compatibility mode for driver setup methods
-If you maintain older code that expects separate *success* and *error* callbacks for driver setup methods (`setDriver`, `defineDriver`), enable `compatibilityMode` when creating an instance. **Use this mode only for migrations; prefer native Promises going forward.**
+
+If you maintain older code that expects separate _success_ and _error_ callbacks for driver setup methods (`setDriver`, `defineDriver`), enable `compatibilityMode` when creating an instance. **Use this mode only for migrations; prefer native Promises going forward.**
 
 ```ts
 const legacy = localspace.createInstance({
@@ -381,7 +741,7 @@ legacy.setDriver(
   },
   (error) => {
     // Error callback receives the Error object only.
-  },
+  }
 );
 ```
 
@@ -398,7 +758,8 @@ localspace.setItem('key', 'value', (err, value) => {
 ```
 
 ## Performance notes
-- **Automatic write coalescing (enabled by default):** localspace automatically merges rapid single writes (`setItem`/`removeItem`) within an 8ms window into one transaction, giving you 3-10x performance improvement with zero code changes. This is enabled by default for IndexedDB. Set `coalesceWrites: false` if you need strict per-operation durability.
+
+- **Automatic write coalescing (opt-in):** localspace can merge rapid single writes (`setItem`/`removeItem`) within an 8ms window into one transaction for IndexedDB, delivering 3-10x speedups under bursty writes. Enable with `coalesceWrites: true` and see **Advanced: Coalesced Writes** for consistency modes.
 - **Read-your-writes consistency with coalescing:** Pending coalesced writes are flushed before reads (`getItem`, `getItems`, `iterate`, `keys`, `length`, `key`) and destructive ops (`clear`, `dropInstance`), so immediate reads always observe the latest value. If you need eventual reads for speed, you can switch `coalesceReadConsistency` to `'eventual'`.
 - **Batch APIs outperform loops:** Playwright benchmark (`test/playwright/benchmark.spec.ts`) on 500 items x 256B showed `setItems()` ~6x faster and `getItems()` ~7.7x faster than per-item loops, with `removeItems()` ~2.8x faster (Chromium, relaxed durability).
 - **Transaction helpers:** `runTransaction()` lets you co-locate reads/writes in a single transaction for atomic migrations and to shorten lock time.
@@ -406,12 +767,13 @@ localspace.setItem('key', 'value', (err, value) => {
 - **IndexedDB durability defaults:** Chrome 121+ uses relaxed durability by default; keep it for speed or set `durability: 'strict'` in `config` for migration-style writes.
 - **Storage Buckets (Chromium 122+):** supply a `bucket` option to isolate critical data and hint durability/persistence per bucket.
 - **Connection warmup:** IndexedDB instances pre-warm a transaction after init to reduce first-op latency (`prewarmTransactions` enabled by default; set to `false` to skip).
-- **Recommended defaults:** keep `coalesceWrites` enabled (default), `durability` relaxed, and `prewarmTransactions` on. Set `connectionIdleMs` only if you want idle connections to auto-close, and `maxBatchSize` only for very large bulk writes. Prefer IndexedDB for atomic/bulk writes since localStorage batches are non-atomic. Use `maxConcurrentTransactions` to throttle heavy parallel workloads when needed.
+- **Recommended defaults:** leave `coalesceWrites` off unless you know you need higher write throughput; if you enable it, prefer the default `strong` consistency. Keep `durability` relaxed and `prewarmTransactions` on. Set `connectionIdleMs` only if you want idle connections to auto-close, and `maxBatchSize` only for very large bulk writes. Prefer IndexedDB for atomic/bulk writes since localStorage batches are non-atomic. Use `maxConcurrentTransactions` to throttle heavy parallel workloads when needed.
 - **localStorage batch atomicity:** When using localStorage driver, batch operations (`setItems()`, `removeItems()`) are **not atomic**. If an error occurs mid-operation, some items may be written or removed while others are not. In contrast, IndexedDB batch operations use transactions and guarantee atomicity (all-or-nothing). If atomicity is critical for your use case, prefer IndexedDB driver or implement application-level rollback logic.
 
 When `compatibilityMode` is off, driver setup methods also use Node-style callbacks. Promises are recommended for all new code.
 
 ## Troubleshooting
+
 - **Wait for readiness:** Call `await localspace.ready()` before the first operation when you need to confirm driver selection.
 - **Inspect drivers:** Use `localspace.driver()` to confirm which driver is active in different environments.
 - **Read structured errors:** Rejections surface as `LocalSpaceError` with a `code`, contextual `details` (driver, operation, key, attemptedDrivers), and the original `cause`. Branch on `error.code` instead of parsing strings.
@@ -421,4 +783,5 @@ When `compatibilityMode` is off, driver setup methods also use Node-style callba
 - **Collect combined Vitest + Playwright coverage:** Run `yarn coverage:full` to clean previous artifacts, run `vitest --coverage`, stash its Istanbul JSON into `.nyc_output`, then execute the coverage-enabled Playwright suite and emit merged `nyc` reports.
 
 ## License
+
 [MIT](./LICENSE)

package/dist/core/plugin-manager.d.ts

@@ -15,7 +15,12 @@ export declare class PluginManager {
     private readonly destroyed;
     private readonly disabled;
     private orderCounter;
+    private warningsEmitted;
     constructor(host: PluginHost, initialPlugins?: LocalSpacePlugin[]);
+    /**
+     * Validate plugin combinations and emit warnings for potential issues.
+     */
+    private validatePluginCombinations;
     hasPlugins(): boolean;
     registerPlugins(plugins: LocalSpacePlugin[]): void;
     private sortPlugins;