localspace 0.1.1 → 0.2.0

package/README.md

@@ -51,11 +51,12 @@ localspace is built on a foundation designed for growth. Here's what's planned:
 - [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] Connection pooling, transaction batching, and warmup
 
 ### TODO
-- [ ] **Batch operations** - `setItems()`, `getItems()`, `removeItems()` for better performance
 - [ ] **Improved error handling** - Structured error types with detailed context
-- [ ] **Performance optimizations** - Connection pooling, transaction batching
 - [ ] **Plugin system** - Middleware architecture for cross-cutting concerns
 - [ ] **Cache API driver** - Native browser caching with automatic HTTP semantics
 - [ ] **OPFS driver** - Origin Private File System for high-performance file storage
@@ -123,6 +124,109 @@ 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.
+
+```ts
+// Your existing code - unchanged
+await Promise.all([
+  localspace.setItem('setting1', value1),
+  localspace.setItem('setting2', value2),
+  localspace.setItem('setting3', value3),
+]);
+// ✅ Automatically batched into one transaction!
+// ✅ 3-10x faster than individual commits
+// ✅ 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.
+
+**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,
+});
+```
+
+**When is this useful?**
+- Form auto-save that writes multiple fields rapidly
+- Bulk state synchronization loops
+- Real-time collaborative editing
+- Any code with multiple sequential `setItem()` calls
+
+**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?.();
+console.log(stats);
+// {
+//   totalWrites: 150,           // Total write operations
+//   coalescedWrites: 120,       // Operations that were merged
+//   transactionsSaved: 100,     // Transactions saved by coalescing
+//   avgCoalesceSize: 4.8        // Average batch size
+// }
+```
+
+### 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
+const items = [
+  { key: 'user:1', value: { name: 'Ada' } },
+  { key: 'user:2', value: { name: 'Lin' } },
+];
+
+// Single transaction write
+await localspace.setItems(items);
+
+// Ordered bulk read
+const result = await localspace.getItems(items.map((item) => item.key));
+console.log(result); // [{ key: 'user:1', value: {…} }, { key: 'user:2', value: {…} }]
+
+// Single transaction delete
+await localspace.removeItems(items.map((item) => item.key));
+
+// For very large batches, set a chunk size to avoid huge transactions
+const limited = localspace.createInstance({ maxBatchSize: 200 });
+await limited.setDriver([limited.INDEXEDDB]);
+await limited.setItems(items); // will split into 200-item chunks
+
+// Optional: coalesce rapid single writes into one transaction (IndexedDB)
+const coalesced = localspace.createInstance({
+  coalesceWrites: true,
+  coalesceWindowMs: 8,
+});
+await coalesced.setDriver([coalesced.INDEXEDDB]);
+await Promise.all([
+  coalesced.setItem('fast-1', 'a'),
+  coalesced.setItem('fast-2', 'b'),
+]); // batched into one tx within the window
+
+// Note: localStorage batches are not atomic—writes are applied one by one.
+// For critical flows, prefer IndexedDB or handle your own compensating logic.
+```
+
+### 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
+await localspace.setDriver([localspace.INDEXEDDB]);
+await localspace.runTransaction('readwrite', async (tx) => {
+  const current = await tx.get<number>('counter');
+  const next = (current ?? 0) + 1;
+  await tx.set('counter', next);
+  await tx.set('lastUpdated', Date.now());
+});
+```
+
 ### 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.
 
@@ -144,6 +248,20 @@ await localspace.setDriver([localspace.INDEXEDDB, localspace.LOCALSTORAGE]);
 if (!localspace.supports(localspace.INDEXEDDB)) {
   console.warn('IndexedDB unavailable, using localStorage wrapper.');
 }
+
+// Hint IndexedDB durability (Chrome defaults to "relaxed" from 121+)
+await localspace.setDriver([localspace.INDEXEDDB]);
+await localspace.ready();
+// Global durability hint for this instance
+localspace.config({ durability: 'strict' }); // or omit to stay relaxed for speed
+
+// Use Storage Buckets (Chromium 122+) to isolate data and hints
+const bucketed = localspace.createInstance({
+  name: 'mail-cache',
+  storeName: 'drafts',
+  bucket: { name: 'drafts', durability: 'strict', persisted: true },
+});
+await bucketed.setDriver([bucketed.INDEXEDDB]);
 ```
 
 **Tip:** Use `defineDriver()` and `getDriver()` to register custom drivers that match the localForage interface.
@@ -197,6 +315,17 @@ localspace.setItem('key', 'value', (err, value) => {
 });
 ```
 
+## Performance notes
+- **Automatic write coalescing (enabled by default):** localspace automatically merges rapid single writes 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.
+- **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.
+- **Batch sizing:** Use `maxBatchSize` to split very large batches and keep transaction size in check.
+- **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.
+- **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

package/dist/drivers/indexeddb.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"indexeddb.d.ts","sourceRoot":"","sources":["../../src/drivers/indexeddb.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,MAAM,EAKP,MAAM,UAAU,CAAC;AAgkClB,QAAA,MAAM,YAAY,EAAE,MAanB,CAAC;AAEF,eAAe,YAAY,CAAC"}
+{"version":3,"file":"indexeddb.d.ts","sourceRoot":"","sources":["../../src/drivers/indexeddb.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,MAAM,EASP,MAAM,UAAU,CAAC;AAw7DlB,QAAA,MAAM,YAAY,EAAE,MAkBnB,CAAC;AAEF,eAAe,YAAY,CAAC"}