localspace 1.0.1 → 1.1.0

package/README.md

@@ -8,101 +8,96 @@ localspace — modern storage toolkit that keeps localForage compatibility while
 
 ## Motivation
 
-The industry still leans on localForage’s familiar API, yet modern apps crave stronger typing, async ergonomics, and multi-platform reliability without a painful rewrite. localspace exists to bridge that gap: it honors the old contract while delivering the capabilities teams have been asking for since 2021.
+The industry still leans on localForage's familiar API, yet modern apps crave stronger typing, async ergonomics, and multi-platform reliability without a painful rewrite. localspace exists to bridge that gap: it honors the old contract while delivering first-class TypeScript types, native async/await, reliable IndexedDB cleanup, and a clean driver architecture.
 
-### What needed to change
+**Why rebuild instead of fork?** Starting fresh let us eliminate technical debt while maintaining API compatibility. Teams can migrate from localForage without changing application code, then unlock better developer experience and future extensibility.
 
-localForage’s storage layer stopped evolving while real-world needs kept growing. Long-standing requests—first-class TypeScript types, native async/await, reliable IndexedDB cleanup, consistency across Node and React Native, batch operations, TTL, and encryption—remain unresolved. Teams want those upgrades without abandoning the API that already powers their products.
+## Quick Start
 
-### How localspace responds
+Get started in 5 minutes:
 
-We stay 100% compatible with localForage on the surface, but rebuild the internals with modern JavaScript, a TypeScript-first type system, native Promises, and a clean driver architecture. That drop-in approach delivers predictable behavior (including a complete IndexedDB `dropInstance`), clearer diagnostics, and room to grow with new drivers (Cache API, SQLite, OPFS) and optional plugins (TTL, encryption, compression) across browsers, Node, React Native, and Electron. Our goal is a storage toolkit that preserves your investment in the localForage mental model while finally addressing the community’s accumulated pain points.
+### 1. Install
 
-### Why rebuild instead of fork?
+```bash
+npm install localspace
+# or: yarn add localspace / pnpm add localspace
+```
 
-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.
+### 2. Basic Usage
 
-## Table of Contents
-
-- [Motivation](#motivation)
-  - [What needed to change](#what-needed-to-change)
-  - [How localspace responds](#how-localspace-responds)
-  - [Why rebuild instead of fork?](#why-rebuild-instead-of-fork)
-- [Roadmap](#roadmap)
-- [Installation and Usage](#installation-and-usage)
-  - [localspace delivers modern storage compatibility](#localspace-delivers-modern-storage-compatibility)
-  - [Install and import localspace](#install-and-import-localspace)
-  - [Store data with async flows or callbacks](#store-data-with-async-flows-or-callbacks)
-  - [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)
-- [Troubleshooting](#troubleshooting)
-- [License](#license)
+```ts
+import localspace from 'localspace';
 
-## Roadmap
+// Store and retrieve data
+await localspace.setItem('user', { name: 'Ada', role: 'admin' });
+const user = await localspace.getItem<{ name: string; role: string }>('user');
 
-localspace is built on a foundation designed for growth. Here's what's planned:
+// TypeScript generics for type safety
+interface User {
+  name: string;
+  role: string;
+}
+const typedUser = await localspace.getItem<User>('user');
+```
 
-### Core Compatibility (Complete)
+### 3. Create Isolated Instances
 
-- [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, opt-in for IndexedDB)
-- [x] Connection pooling, transaction batching, and warmup
-- [x] **Improved error handling** - Structured error types with detailed context
+```ts
+const cache = localspace.createInstance({
+  name: 'my-app',
+  storeName: 'cache',
+});
 
-### TODO
+await cache.setItem('token', 'abc123');
+```
 
-- [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
-- [ ] **Node.js** - File system and SQLite adapters
-- [ ] **React Native** - AsyncStorage and SQLite drivers
-- [ ] **Electron** - Main and renderer process coordination
-- [ ] **Deno** - Native KV store integration
-- [x] **TTL plugin** - Time-to-live expiration with automatic cleanup
-- [x] **Encryption plugin** - Transparent encryption/decryption with Web Crypto API
-- [x] **Compression plugin** - LZ-string or Brotli compression for large values
-- [x] **Sync plugin** - Multi-tab synchronization with BroadcastChannel
-- [x] **Quota plugin** - Automatic quota management and cleanup strategies
+### 4. Batch Operations
 
-### 📊 Community Priorities
+```ts
+// Write multiple items in one transaction (IndexedDB)
+await localspace.setItems([
+  { key: 'user:1', value: { name: 'Ada' } },
+  { key: 'user:2', value: { name: 'Grace' } },
+]);
 
-We prioritize features based on community feedback. If you need a specific capability:
+// Read multiple items
+const users = await localspace.getItems(['user:1', 'user:2']);
+```
 
-1. **Check existing issues** to see if it's already requested
-2. **Open a feature request** with your use case and requirements
-3. **Contribute** - We welcome PRs for new drivers, plugins, or improvements
+### 5. Use Plugins
 
-**Want to help?** The most impactful contributions right now:
+```ts
+import localspace, { ttlPlugin, encryptionPlugin } from 'localspace';
 
-- Testing in diverse environments (browsers, frameworks, edge cases)
-- Documentation improvements and usage examples
-- Performance benchmarks and optimization suggestions
-- New driver implementations (especially Cache API and OPFS)
+const secureStore = localspace.createInstance({
+  name: 'secure',
+  plugins: [
+    ttlPlugin({ defaultTTL: 60_000 }), // Auto-expire after 1 minute
+    encryptionPlugin({ key: 'your-32-byte-key' }), // Encrypt data
+  ],
+});
+```
 
-## Installation and Usage
+That's it! For more details, see the sections below.
 
-### 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.**
+## Table of Contents
 
-- Promise-first API with optional callbacks
-- IndexedDB and localStorage drivers included out of the box
-- ES module, CommonJS, and UMD bundles plus `.d.ts` files
-- Drop-in TypeScript generics for value typing
+- [Installation](#installation)
+- [Core API](#core-api)
+- [Batch Operations](#batch-operations)
+- [Coalesced Writes](#coalesced-writes)
+- [Plugin System](#plugin-system)
+- [Configuration](#configuration)
+- [Performance Notes](#performance-notes)
+- [Troubleshooting](#troubleshooting)
+- [Documentation](#documentation)
+- [License](#license)
 
-### Install and import localspace
+---
 
-Install the package with your preferred package manager and import it once at the entry point where you manage storage.
+## Installation
 
 ```bash
 npm install localspace
@@ -116,673 +111,307 @@ pnpm add localspace
 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
-await localspace.setItem('user', { name: 'Ada', role: 'admin' });
-const user = await localspace.getItem<{ name: string; role: string }>('user');
+**Bundles included:** ES modules, CommonJS, UMD, plus `.d.ts` files.
 
-localspace.getItem('user', (error, value) => {
-  if (error) return console.error(error);
-  console.log(value?.name);
-});
-```
+---
 
-### 🚀 Opt into automatic performance optimization (coalesced writes)
+## Core API
 
-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.
+### Storage Methods
 
 ```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
-```
+// Set and get items
+await localspace.setItem('key', value);
+const value = await localspace.getItem<T>('key');
 
-**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.
+// Remove items
+await localspace.removeItem('key');
+await localspace.clear();
 
-**Turn it on or tune it**
+// Query
+const count = await localspace.length();
+const keys = await localspace.keys();
 
-```ts
-const instance = localspace.createInstance({
-  coalesceWrites: true, // opt-in (default is false)
-  coalesceWindowMs: 8, // 8ms window (default)
+// Iterate
+await localspace.iterate<T, void>((value, key, index) => {
+  console.log(key, value);
 });
 ```
 
-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
-- 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?**
+### Callbacks (Legacy Support)
 
 ```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
-// }
+localspace.getItem('user', (error, value) => {
+  if (error) return console.error(error);
+  console.log(value);
+});
 ```
 
-### 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).
+### Driver Selection
 
 ```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
-
-// These features work independently and can be combined
-const optimized = localspace.createInstance({
-  coalesceWrites: true, // optimizes single-item writes (setItem/removeItem)
-  coalesceWindowMs: 8,
-  maxBatchSize: 200, // limits batch API chunk size (setItems/removeItems)
-});
-await optimized.setDriver([optimized.INDEXEDDB]);
+// Web fallback order (default bundled drivers)
+await localspace.setDriver([localspace.INDEXEDDB, localspace.LOCALSTORAGE]);
 
-// 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.
+// Check current driver
+console.log(localspace.driver());
+// 'asyncStorage' | 'localStorageWrapper'
 ```
 
-### 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.
+### React Native AsyncStorage
 
 ```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.
+import AsyncStorage from '@react-native-async-storage/async-storage';
+import localspace from 'localspace';
+import { createReactNativeInstance } from 'localspace/react-native';
 
-```ts
-const sessionCache = localspace.createInstance({
-  name: 'session',
-  storeName: 'volatile-items',
+const mobileStore = await createReactNativeInstance(localspace, {
+  name: 'myapp',
+  storeName: 'kv',
+  reactNativeAsyncStorage: AsyncStorage,
 });
-
-await sessionCache.setItem('token', 'abc123');
 ```
 
-### Choose drivers with predictable fallbacks
+The default `localspace` entry does not bundle the React Native driver; it is included only when importing `localspace/react-native`. Explicit `reactNativeAsyncStorage` injection is recommended.
 
-By default, localspace prefers IndexedDB (`INDEXEDDB`) and falls back to localStorage (`LOCALSTORAGE`). Configure alternative sequences as needed.
+Advanced usage is still available:
 
 ```ts
-await localspace.setDriver([localspace.INDEXEDDB, localspace.LOCALSTORAGE]);
-
-if (!localspace.supports(localspace.INDEXEDDB)) {
-  console.warn('IndexedDB unavailable, using localStorage wrapper.');
-}
+import localspace from 'localspace';
+import { installReactNativeAsyncStorageDriver } from 'localspace/react-native';
 
-// 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]);
+await installReactNativeAsyncStorageDriver(localspace);
+await localspace.setDriver(localspace.REACTNATIVEASYNCSTORAGE);
 ```
 
-**Tip:** Use `defineDriver()` and `getDriver()` to register custom drivers that match the localForage interface.
+Integration smoke (official AsyncStorage Jest mock):
 
-### 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
-const file = new Blob(['hello'], { type: 'text/plain' });
-await localspace.setItem('file', file);
-const restored = await localspace.getItem<Blob>('file');
+```bash
+yarn test:rn:integration
 ```
 
-## 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.
+See `integration/react-native-jest/README.md` for details.
 
-> `coalesceWrites` defaults to `false` so behavior stays predictable. Turn it on when you expect high-frequency writes.
+GitHub Actions Detox workflow template (real simulator/emulator runtime):
 
-### Why coalesce writes?
+- Workflow: `.github/workflows/detox-mobile.yml`
+- Fixture app folder: `integration/react-native-detox/`
+- Fixture README: `integration/react-native-detox/README.md`
 
-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:
+📖 **Full API Reference:** [docs/api-reference.md](./docs/api-reference.md)
 
-- 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
+## Batch Operations
 
-Relevant `LocalSpaceConfig` fields:
+Use batch APIs for better performance with IndexedDB:
 
 ```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.
+// Single transaction write
+await localspace.setItems([
+  { key: 'user:1', value: { name: 'Ada' } },
+  { key: 'user:2', value: { name: 'Lin' } },
+]);
 
-#### `coalesceReadConsistency: 'eventual'`
+// Ordered bulk read
+const result = await localspace.getItems(['user:1', 'user:2']);
+// [{ key: 'user:1', value: {...} }, { key: 'user:2', value: {...} }]
 
-- 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`.
+// Single transaction delete
+await localspace.removeItems(['user:1', 'user:2']);
+```
 
-Use this for logs/analytics or workloads that can tolerate short windows of staleness in exchange for the lightest write path.
+### Transactions
 
-### Bounding batch size
+For atomic multi-step operations:
 
 ```ts
-const store = localspace.createInstance({
-  name: 'logs',
-  storeName: 'events',
-  coalesceWrites: true,
-  coalesceWindowMs: 8,
-  coalesceMaxBatchSize: 64,
-  coalesceReadConsistency: 'eventual',
+await localspace.runTransaction('readwrite', async (tx) => {
+  const current = (await tx.get<number>('counter')) ?? 0;
+  await tx.set('counter', current + 1);
+  await tx.set('lastUpdated', Date.now());
 });
 ```
 
-- 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
+## Coalesced Writes
 
-1. Default: coalescing off
+Opt-in automatic batching of rapid writes for **3-10x performance improvement**:
 
 ```ts
 const store = localspace.createInstance({
-  name: 'app',
-  storeName: 'keyvaluepairs',
-  // coalesceWrites is false by default
+  coalesceWrites: true, // Enable (default: false)
+  coalesceWindowMs: 8, // 8ms merge window
 });
-```
 
-2. High-frequency writes with eventual consistency
-
-```ts
-const logStore = localspace.createInstance({
-  name: 'analytics',
-  storeName: 'events',
-  coalesceWrites: true,
-  coalesceWindowMs: 8,
-  coalesceMaxBatchSize: 64,
-  coalesceReadConsistency: 'eventual',
-});
+// These are automatically batched into one transaction
+await Promise.all([
+  store.setItem('a', 1),
+  store.setItem('b', 2),
+  store.setItem('c', 3),
+]);
 ```
 
-- `setItem` resolves almost immediately.
-- Short windows of stale reads are acceptable.
-- `clear` and `dropInstance` force-flush so queued writes are not lost.
+**Consistency modes:**
 
-3. Strong consistency with bounded batches
+- `'strong'` (default): Reads flush pending writes first
+- `'eventual'`: Reads may see stale values briefly
 
 ```ts
-const userStore = localspace.createInstance({
-  name: 'user-data',
-  storeName: 'kv',
-  coalesceWrites: true,
-  coalesceWindowMs: 8,
-  coalesceMaxBatchSize: 32,
-  coalesceReadConsistency: 'strong',
-});
+// Get performance stats
+const stats = localspace.getPerformanceStats?.();
+// { totalWrites: 150, coalescedWrites: 120, transactionsSaved: 100 }
 ```
 
-- 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.
+localspace ships with a powerful plugin engine:
 
 ```ts
+import localspace, {
+  ttlPlugin,
+  compressionPlugin,
+  encryptionPlugin,
+  syncPlugin,
+  quotaPlugin,
+} from 'localspace';
+
 const store = localspace.createInstance({
   name: 'secure-store',
-  storeName: 'primary',
   plugins: [
-    ttlPlugin({ defaultTTL: 60_000 }),
-    compressionPlugin({ threshold: 1024 }),
-    encryptionPlugin({ key: '0123456789abcdef0123456789abcdef' }),
-    syncPlugin({ channelName: 'localspace-sync' }),
-    quotaPlugin({ maxSize: 5 * 1024 * 1024, evictionPolicy: 'lru' }),
+    ttlPlugin({ defaultTTL: 60_000 }), // Auto-expire
+    compressionPlugin({ threshold: 1024 }), // Compress > 1KB
+    encryptionPlugin({ key: '32-byte-key-here' }), // Encrypt
+    syncPlugin({ channelName: 'my-app' }), // Multi-tab sync
+    quotaPlugin({ maxSize: 5 * 1024 * 1024 }), // 5MB limit
   ],
+  pluginErrorPolicy: 'strict', // Recommended for encryption
 });
 ```
 
-### Lifecycle and hooks
-
-- **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 (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 & 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: 'lenient'` reports and continues; use `strict` 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                         |
-| 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        |
+### Built-in Plugins
 
-**Recommended order**: `[ttlPlugin, compressionPlugin, encryptionPlugin, syncPlugin, quotaPlugin]`
+| Plugin          | Purpose                                              |
+| --------------- | ---------------------------------------------------- |
+| **TTL**         | Auto-expire items with `{ data, expiresAt }` wrapper |
+| **Encryption**  | AES-GCM encryption via Web Crypto API                |
+| **Compression** | LZ-string compression for large values               |
+| **Sync**        | Multi-tab synchronization via BroadcastChannel       |
+| **Quota**       | Storage limit enforcement with LRU eviction          |
 
-### Built-in plugins
+📖 **Full Plugin Documentation:** [docs/plugins.md](./docs/plugins.md)
+📖 **Real-World Examples:** [docs/examples.md](./docs/examples.md)
 
-#### 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 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)
+## Configuration
 
 ```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.
+const store = localspace.createInstance({
+  // Database
+  name: 'myapp', // Database name
+  storeName: 'data', // Store name
+  version: 1, // Schema version
 
-- `threshold` (bytes) controls when compression kicks in
-- Supply a custom `{ compress, decompress }` codec if you prefer pako/Brotli
+  // Driver
+  driver: [localspace.INDEXEDDB, localspace.LOCALSTORAGE],
 
-```ts
-const compressedStore = localspace.createInstance({
-  name: 'compressed-store',
-  plugins: [
-    compressionPlugin({
-      threshold: 1024, // Only compress if > 1KB
-      algorithm: 'lz-string', // Label stored in metadata
-    }),
-  ],
-});
+  // IndexedDB performance
+  durability: 'relaxed', // 'relaxed' (fast) or 'strict'
+  prewarmTransactions: true, // Pre-warm connection
 
-// Custom codec example (using pako)
-import pako from 'pako';
+  // Batching
+  maxBatchSize: 200, // Split large batches
+  coalesceWrites: false, // Merge rapid writes
 
-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' }),
-      },
-    }),
-  ],
+  // Plugins
+  plugins: [],
+  pluginErrorPolicy: 'lenient', // 'strict' for encryption
 });
 ```
 
-#### 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
-- `evictionPolicy: 'error' | 'lru'` (LRU removes least-recently-used keys automatically)
-- `onQuotaExceeded(info)` fires before throwing so you can log/alert users
+// React Native one-step instance
+import localspace from 'localspace';
+import { createReactNativeInstance } from 'localspace/react-native';
 
-```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`);
-      },
-    }),
-  ],
+const mobileStore = await createReactNativeInstance(localspace, {
+  name: 'myapp',
+  storeName: 'data',
+  reactNativeAsyncStorage: AsyncStorage,
 });
-
-// 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** (default is lenient):
-
-   ```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 (recommended)
-   });
-   ```
-
-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    | Set `pluginErrorPolicy: 'strict'` for encryption/compression/ttl       |
-| 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        |
+📖 **Full Configuration Options:** [docs/api-reference.md#configuration-options](./docs/api-reference.md#configuration-options)
 
-## 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.
+## Performance Notes
 
-## Testing & CI
+- **Batch APIs outperform loops:** `setItems()` ~6x faster, `getItems()` ~7.7x faster than per-item loops
+- **Coalesced writes:** 3-10x faster under write bursts (opt-in)
+- **Transaction helpers:** `runTransaction()` for atomic migrations
+- **IndexedDB durability:** Chrome 121+ uses relaxed durability by default
+- **localStorage batches are non-atomic:** Prefer IndexedDB for atomic operations
 
-- 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
+## Troubleshooting
 
-- 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.
+| Issue                       | Solution                                               |
+| --------------------------- | ------------------------------------------------------ |
+| Driver not ready            | Call `await localspace.ready()` before first operation |
+| Quota errors                | Check `error.code === 'QUOTA_EXCEEDED'`                |
+| Plugin errors swallowed     | Set `pluginErrorPolicy: 'strict'`                      |
+| Stale reads with coalescing | Use `coalesceReadConsistency: 'strong'` (default)      |
 
-## Migration Guide
+**Errors** are `LocalSpaceError` with `code`, `details`, and `cause` properties.
 
-### 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.
+## Compatibility
 
-### Enable compatibility mode for driver setup methods
+- **Browsers:** Modern Chromium/Edge, Firefox, Safari
+- **Drivers:** IndexedDB (primary), localStorage
+- **React Native:** AsyncStorage driver available via `localspace/react-native` opt-in entry
+- **WebSQL:** Not supported (migrate to IndexedDB)
+- **Node/SSR:** Custom driver required
 
-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({
-  name: 'legacy-store',
-  storeName: 'pairs',
-  compatibilityMode: true,
-});
+## Documentation
 
-legacy.setDriver(
-  [legacy.LOCALSTORAGE],
-  () => {
-    // Success callback receives no arguments.
-  },
-  (error) => {
-    // Error callback receives the Error object only.
-  }
-);
-```
+| Document                                     | Description                           |
+| -------------------------------------------- | ------------------------------------- |
+| [API Reference](./docs/api-reference.md)     | Complete method documentation         |
+| [Plugin System](./docs/plugins.md)           | Built-in plugins & custom development |
+| [Real-World Examples](./docs/examples.md)    | Production-ready code patterns        |
+| [Migration Guide](./docs/migration-guide.md) | Upgrading from localForage            |
 
-**Note:** Storage methods like `setItem`, `getItem`, `removeItem`, etc. always use Node-style `(error, value)` callbacks regardless of `compatibilityMode`. This matches localForage's original behavior. For example:
+---
 
-```ts
-localspace.setItem('key', 'value', (err, value) => {
-  if (err) {
-    console.error('Error:', err);
-  } else {
-    console.log('Saved:', value);
-  }
-});
-```
+## Roadmap
 
-## Performance notes
+### Complete ✅
 
-- **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.
-- **Batch sizing:** Use `maxBatchSize` to split very large batch operations (`setItems`/`removeItems`/`getItems`) and keep transaction size in check. This works independently from `coalesceWrites`, which optimizes single-item operations.
-- **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:** 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.
+- [x] IndexedDB and localStorage drivers
+- [x] React Native AsyncStorage driver
+- [x] Full localForage API parity
+- [x] TypeScript-first implementation
+- [x] Batch operations & write coalescing
+- [x] Plugin system (TTL, Encryption, Compression, Sync, Quota)
 
-When `compatibilityMode` is off, driver setup methods also use Node-style callbacks. Promises are recommended for all new code.
+### Coming Soon
 
-## Troubleshooting
+- [ ] OPFS driver (Origin Private File System)
+- [ ] Node.js (File system, SQLite)
+- [ ] React Native SQLite driver
+- [ ] Deno (Native KV store)
 
-- **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.
-- **Handle quota errors:** Check for `error.code === 'QUOTA_EXCEEDED'` (or inspect `error.cause`) from `setItem` to inform users about storage limits.
-- **Run unit tests:** The project ships with Vitest and Playwright suites covering API behavior; run `yarn test` to verify changes.
-- **Collect Playwright coverage:** Run `yarn test:e2e:coverage` to re-build the bundle, execute the Playwright suite with Chromium V8 coverage enabled, and emit both text + HTML reports via `nyc` (open `coverage/index.html` after the run; raw JSON sits in `.nyc_output`).
-- **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