bun-sqlite-for-rxdb 1.0.1

package/ROADMAP.md

@@ -0,0 +1,532 @@
+# bun-sqlite-for-rxdb Roadmap
+
+> **Status:** Phase 2 Complete ✅ | Phase 3 Complete ✅
+> **Last Updated:** 2026-02-23
+
+---
+
+## 🎯 Vision
+
+Build the **fastest RxDB storage adapter** by leveraging Bun's native SQLite (3-6x faster than better-sqlite3).
+
+**Key Principles:**
+- Start simple, iterate incrementally (Linus approach)
+- Measure before optimizing
+- Ship working code, not perfect code
+- Test-driven development
+
+---
+
+## ✅ Phase 1: Minimal Working Core (COMPLETE)
+
+**Goal:** Prove the concept works
+
+**Delivered:**
+- ✅ RxStorage adapter for bun:sqlite
+- ✅ Atomic transactions (bun:sqlite transaction API)
+- ✅ Core methods: bulkWrite, query, findById, count, cleanup
+- ✅ Reactive changeStream with RxJS
+- ✅ In-memory Mango query filtering (simple but functional)
+- ✅ 8/8 tests passing
+- ✅ Supports RxDB v16 and v17 beta
+- ✅ MIT licensed
+
+**Performance:**
+- ✅ Transactions: Atomic (all-or-nothing)
+- ⚠️ Queries: O(n) — fetches all, filters in JS (slow for 10k+ docs)
+
+**What We Learned:**
+- bun:sqlite API is nearly identical to better-sqlite3 ✅
+- Transaction wrapper works perfectly ✅
+- In-memory filtering is simple but not scalable ⚠️
+
+---
+
+## 🚧 Phase 2: Query Builder & Production Hardening (COMPLETE ✅)
+
+**Goal:** 10-100x query speedup + production-ready features
+
+### **Phase 2.1: Basic Operators (COMPLETE ✅)**
+
+**Architecture:** Functional Core, Imperative Shell
+- ✅ Pure functions for operator translation (testable)
+- ✅ Schema mapper for column info (DRY)
+- ✅ Query builder for composition (scalable)
+- ✅ Instance for orchestration (thin layer)
+
+**Delivered:**
+- ✅ `src/query/operators.ts` - 6 operators ($eq, $ne, $gt, $gte, $lt, $lte)
+- ✅ `src/query/schema-mapper.ts` - Column mapping for _deleted, _meta.lwt, _rev, primaryKey
+- ✅ `src/query/builder.ts` - WHERE clause generation with fallback
+- ✅ Updated `src/instance.ts` - Uses SQL WHERE clauses, falls back to in-memory
+- ✅ 27/27 tests passing (19 storage + 6 operators + 10 builder + 4 schema-mapper)
+- ✅ TypeScript: 0 errors, 0 `any` types (properly typed infrastructure)
+- ✅ Benchmark script created
+
+**Type Safety Achievement:**
+- ✅ Removed ALL 32 instances of `any` and `as any`
+- ✅ Proper RxDB type hierarchy (RxDocumentData<RxDocType>)
+- ✅ Research-driven approach (Lisa + Vivian agents)
+- ✅ No bandaids - proper types throughout
+
+**Performance:**
+- ✅ Queries: Use SQL WHERE clauses with indexes
+- ✅ Fallback: In-memory filtering if WHERE fails
+- ⏳ Benchmark: Not yet measured (script ready)
+
+**Total Effort:** 8 hours (4h planned + 4h type safety)  
+**Status:** COMPLETE ✅
+
+---
+
+### **Phase 2.2: WAL Mode (COMPLETE ✅)**
+
+**Delivered:**
+```typescript
+// src/instance.ts line 55
+this.db.run("PRAGMA journal_mode = WAL");
+```
+
+**Impact:** 3-6x write speedup, better concurrency
+
+**Status:** ✅ COMPLETE
+
+---
+
+### **Phase 2.3: JSONB Storage (COMPLETE ✅)**
+
+**Delivered:**
+```typescript
+// CREATE TABLE with BLOB column
+CREATE TABLE users (id TEXT PRIMARY KEY, data BLOB NOT NULL);
+
+// INSERT with jsonb() function
+INSERT INTO users (id, data) VALUES (?, jsonb(?));
+
+// SELECT with json() function
+SELECT json(data) as data FROM users WHERE id = ?;
+```
+
+**Benchmark Results** (`benchmarks/text-vs-jsonb.ts`):
+```
+1M documents, 15 runs each:
+- Simple query:  1.04x faster (481ms → 464ms)
+- Complex query: 1.57x faster (657ms → 418ms) 🔥
+- Read + parse:  1.20x faster (2.37ms → 1.98ms)
+```
+
+**Impact:** 1.57x faster complex queries, 1.20x faster reads
+
+**Status:** ✅ COMPLETE (implemented as default storage format)
+
+---
+
+### **Phase 2.4: Conflict Detection (COMPLETE ✅)**
+
+**Delivered:**
+```typescript
+// src/instance.ts line 108
+status: 409,  // Proper RxDB conflict handling
+```
+
+**Impact:** Required for replication support
+
+**Status:** ✅ COMPLETE
+
+---
+
+### **Phase 2.5: Query Builder Caching (COMPLETE ✅)**
+
+**Goal:** Cache query builders by schema hash for faster repeated queries
+
+**What We Did:**
+1. ✅ Implemented LRU cache with canonical key generation (fast-stable-stringify)
+2. ✅ True LRU eviction (delete+re-insert on access)
+3. ✅ 500 entry limit with FIFO eviction
+4. ✅ Zero dependencies except fast-stable-stringify (5KB)
+5. ✅ Created 13 edge case tests (object key order, cache thrashing, etc.)
+
+**Performance:**
+- ✅ 4.8-22.6x speedup for cached queries
+- ✅ High-frequency: 565K-808K queries/sec
+- ✅ Memory stress: 1000 unique queries handled correctly
+
+**Status:** ✅ COMPLETE
+
+---
+
+## 📊 Phase 3: Validation & Benchmarking (COMPLETE ✅)
+
+**Goal:** Prove correctness with official tests, then measure performance
+
+**Philosophy:** Trust the official test suite. Don't reinvent the wheel.
+
+### **Phase 3.1: RxDB Official Test Suite (COMPLETE ✅)**
+
+**Why:** Official validation proves our adapter works correctly. Period.
+
+**What We Did:**
+1. ✅ Ran official test suite: `DEFAULT_STORAGE=custom bun run mocha test_tmp/unit/rx-storage-implementations.test.js`
+2. ✅ Fixed statement lifecycle issues:
+   - Switched from db.prepare() to db.query() for static SQL (caching)
+   - Used db.prepare() + finalize() for dynamic SQL (no cache pollution)
+   - Created StatementManager abstraction layer for automatic cleanup
+3. ✅ Implemented connection pooling with reference counting
+4. ✅ Switched to RxDB's official `addRxStorageMultiInstanceSupport()`
+5. ✅ Fixed composite primary key handling
+6. ✅ Rewrote multi-instance tests to use RxDatabase (proper integration level)
+7. ✅ Added low-level changeStream tests for OUR code only
+8. ✅ Added Bun test suite compatibility (node:sqlite import fix + test globals)
+
+**Test Results:**
+```
+Local Tests: 120/120 pass (100%) ✅
+Official RxDB Tests (Mocha through Bun): 112/112 pass (100%) ✅
+Total: 232/232 tests pass (100%) 🎉
+```
+
+**Key Findings:**
+- db.query() caches statements (max 20) - good for static SQL
+- db.prepare() requires manual finalize() - good for dynamic SQL
+- StatementManager abstraction eliminates manual try-finally boilerplate
+- Connection pooling is REQUIRED for multi-instance support (not optional)
+- RxDB's official multi-instance support handles BroadcastChannel correctly
+- Test at the right level: RxDatabase for integration, storage instances for low-level
+- Mocha through Bun: 100% compatibility, native bun test: 98.2%
+
+**Effort:** 16 hours (investigation + implementation + debugging + test rewrites)
+
+**Status:** ✅ COMPLETE (2026-02-23)
+
+---
+
+### **Phase 3.2: Performance Benchmarks (PRIORITY 2)**
+
+**Why:** After correctness is proven, measure and document performance gains.
+
+**Tasks:**
+1. Benchmark vs pe-sqlite-for-rxdb (better-sqlite3)
+2. Measure write throughput (docs/sec)
+3. Measure query latency at scale (1k, 10k, 100k docs)
+4. Document performance gains in README
+5. Create performance comparison charts
+
+**Expected outcome:** Documented proof of performance claims
+
+**Effort:** 4 hours
+
+**What We Did:**
+1. ✅ Created raw database benchmarks (bun:sqlite vs better-sqlite3)
+2. ✅ Tested with WAL + PRAGMA synchronous = 1
+3. ✅ Ran 1M document benchmarks (2 runs for consistency)
+4. ✅ Updated README with performance results
+
+**Performance:**
+- ✅ Bun:sqlite 1.06-1.68x faster than better-sqlite3
+- ✅ WAL + PRAGMA enabled by default in production code
+
+**Status:** ✅ COMPLETE
+
+---
+
+### **Phase 3.3: Custom Tests (OPTIONAL - YAGNI)**
+
+**Why:** Only if users report specific edge cases not covered by official suite.
+
+**Status:** ❌ SKIPPED (not needed - official suite is comprehensive)
+
+---
+
+---
+
+## 🔮 Phase 4: v1.0 Release Preparation (COMPLETE ✅)
+
+**Goal:** Ship production-ready v1.0 with attachments support
+
+**Prerequisites:** ✅ Phase 3 complete (246/246 tests passing)
+
+**Current Status:** Production-ready adapter with full attachments support
+
+**Research Complete (2026-02-23):**
+- ✅ 4 Lisa agents examined: Dexie, Memory, SQLite/MongoDB official storages
+- ✅ 1 Vivian agent researched: Industry patterns (PostgreSQL, IndexedDB, PouchDB)
+- ✅ Synthesis complete: Minimal correct implementation identified
+
+**v1.0 Requirements (ALL COMPLETE):**
+1. ✅ **Operators** - DONE in v0.4.0 (18 operators)
+2. ✅ **Attachments** - DONE (4 tests passing, getAttachmentData implemented)
+3. ✅ **Refactor bulkWrite** - DONE (uses categorizeBulkWriteRows() helper)
+
+**Post-v1.0 (Future Enhancements):**
+- Query normalization helpers (`normalizeMangoQuery`, `prepareQuery`) for better cache hit rate
+- Schema migrations (user_version pragma) - needs design, not storage-level
+- Query plan hints (EXPLAIN QUERY PLAN) - optimization, not critical
+- Custom indexes - advanced feature, defer until requested
+- Attachment deduplication by hash - industry pattern, adds complexity
+
+**Status:** ✅ COMPLETE (2026-02-23)
+
+---
+
+### **RxDB Helper Functions (v1.0 Implementation)**
+
+**Source:** Research from 6 Lisa agents (2026-02-23)
+
+**MUST USE for v1.0:**
+
+1. **`categorizeBulkWriteRows()`** ⭐⭐⭐
+   - **Purpose:** Battle-tested conflict detection + attachment extraction
+   - **Why:** Used by ALL official adapters (Dexie, MongoDB, SQLite)
+   - **Returns:** `{ bulkInsertDocs, bulkUpdateDocs, errors, eventBulk, attachmentsAdd/Remove/Update }`
+   - **Status:** ✅ DONE - Implemented in src/rxdb-helpers.ts (lines 69-251)
+
+2. **`stripAttachmentsDataFromDocument()`** ⭐⭐
+   - **Purpose:** Remove attachment .data field, keep metadata
+   - **When:** Before storing documents with attachments
+   - **Status:** ✅ DONE - Implemented in src/rxdb-helpers.ts (lines 50-60)
+
+3. **`stripAttachmentsDataFromRow()`** ⭐⭐
+   - **Purpose:** Strip attachments from bulk write rows
+   - **When:** Processing bulkWrite with attachments
+   - **Status:** ✅ DONE - Implemented in src/rxdb-helpers.ts (lines 62-67)
+
+4. **`attachmentWriteDataToNormalData()`** ⭐⭐
+   - **Purpose:** Convert attachment write format to storage format
+   - **When:** Processing attachment writes
+   - **Status:** ✅ DONE - Implemented in src/rxdb-helpers.ts (lines 38-48)
+
+5. **`getAttachmentSize()`** ⭐⭐
+   - **Purpose:** Calculate attachment size from base64
+   - **When:** Attachment metadata
+   - **Status:** ✅ DONE - Implemented in src/rxdb-helpers.ts (lines 34-36)
+
+**ALREADY USING:**
+- ✅ `ensureRxStorageInstanceParamsAreCorrect()` - Constructor validation
+
+**OPTIONAL (Post-v1.0):**
+- `normalizeMangoQuery()` - Query normalization for better cache hit rate
+- `prepareQuery()` - Query plan hints for optimization
+
+**NOT NEEDED (RxDB Internal):**
+- ❌ `getSingleDocument()`, `writeSingle()`, `observeSingle()` - Convenience wrappers
+- ❌ `getWrappedStorageInstance()` - RxDB wraps OUR storage
+- ❌ `flatCloneDocWithMeta()` - RxDB internal
+- ❌ `getWrittenDocumentsFromBulkWriteResponse()` - RxDB internal
+
+**Implementation:**
+All helper functions implemented in `src/rxdb-helpers.ts` (custom implementations, not imported from RxDB)
+
+---
+
+## 📋 Current Priorities
+
+### **Completed (2026-02-23):**
+1. ✅ Phase 1: Minimal Working Core
+2. ✅ Phase 2: Query Builder & Production Hardening
+   - ✅ Phase 2.1: Basic Operators
+   - ✅ Phase 2.2: WAL Mode
+   - ✅ Phase 2.3: JSONB Storage
+   - ✅ Phase 2.4: Conflict Detection
+   - ✅ Phase 2.5: Query Builder Caching (4.8-22.6x speedup)
+3. ✅ Phase 3: Validation & Benchmarking
+   - ✅ Phase 3.1: RxDB Official Test Suite (112/112 passing)
+   - ✅ Phase 3.2: Performance Benchmarks (1.06-1.68x faster than better-sqlite3)
+
+**Test Results:** 260/260 tests passing (100%)
+- Our tests: 138/138 ✅
+- Official RxDB: 122/122 ✅
+
+### **v1.0 Release Ready:**
+1. ✅ **Attachments Implemented**
+   - Attachments table with composite keys (documentId||attachmentId)
+   - `getAttachmentData()` method with digest validation
+   - All 5 RxDB helpers implemented
+   - 4 comprehensive test cases
+2. ✅ **bulkWrite Refactored**
+   - Uses `categorizeBulkWriteRows()` helper
+   - Clean architecture with proper conflict handling
+   - Automatic attachment extraction
+3. ✅ **Full test suite passing** - 260/260 tests (100%)
+4. 📦 **Ready for npm publish v1.0.0**
+5. 🎉 **Community adoption** - Gather feedback, iterate
+
+---
+
+## 🎓 Key Learnings (From Crew Research)
+
+### **From Vivian (RxDB Requirements):**
+- All RxStorageInstance methods documented ✅
+- Mango query operators: $eq, $gt, $in, $or, $regex, etc. ✅
+- Conflict resolution: revision-based with _rev field ✅
+- Attachments: base64-encoded strings ✅
+- Performance expectations: <10ms writes, binary search queries ✅
+
+### **From Lisa (SQLite Patterns):**
+- Prepared statements: Cache by schema hash ✅
+- Indexes: deleted+id, mtime_ms+id (we already have!) ✅
+- Transactions: Use wrapper for atomicity ✅
+- WAL mode: Enable once at init ✅
+- Schema: JSONB BLOB + metadata columns ✅
+
+### **From Lisa (Gap Analysis):**
+- Query Builder: 557 lines, handles NULL/boolean edge cases ✅
+- Reference uses 3-layer architecture (we use 1-layer) ✅
+- JSONB vs TEXT: 20-30% storage savings ✅
+- Conflict detection: Catch SQLITE_CONSTRAINT_PRIMARYKEY ✅
+- Our Phase 1 limitations: O(n) queries, no index utilization ✅
+
+---
+
+## 🏴‍☠️ Linus Torvalds Wisdom
+
+> "Talk is cheap. Show me the code."
+
+**Applied:**
+- ✅ Phase 1: Shipped working code in 1 day
+- 🚧 Phase 2: Focus on the bottleneck (query builder)
+- ⏳ Phase 3: Measure before claiming victory
+
+> "Don't over-engineer. Build what you need, when you need it.
+>  Bad programmers worry about the code. Good programmers worry about data structures and their relationships first."
+
+**Applied:**
+- ✅ Phase 1: In-memory filtering (simple, works)
+- 🚧 Phase 2: SQL filtering (needed for scale)
+- ⏸️ Phase 4: Advanced features (defer until needed)
+
+> "Optimize the slow path, not the fast path."
+
+**Applied:**
+- 🎯 Query Builder: THE bottleneck (10-100x impact)
+- ⚡ WAL mode: 3-6x write speedup (5 min effort)
+- 📦 JSONB: 20-30% savings (2 hour effort)
+
+---
+
+## 📈 Success Metrics
+
+**Phase 1 (Complete):**
+- ✅ 8/8 tests passing
+- ✅ TypeScript compiles (0 errors)
+- ✅ Atomic transactions working
+
+**Phase 2 (Complete ✅):**
+- ✅ Query Builder: Basic Mango operators working ($eq, $ne, $gt, $gte, $lt, $lte)
+- ✅ 31/31 tests passing
+- ✅ TypeScript: 0 errors, 0 `any` types
+- ✅ WAL mode enabled (3-6x write speedup)
+- ✅ Proper checkpoint implementation
+- ✅ Conflict detection working (409 errors with documentInDb)
+- ✅ Extensively tested serialization formats (MessagePack, bun:jsc, JSON)
+- ✅ **JSON + TEXT storage: 23.40ms average (10k docs)**
+
+**Phase 3 (Complete ✅):**
+- ✅ Advanced Query Operators: $in, $nin, $or, $and
+- ✅ 51/51 tests passing (44 → 51 tests)
+- ✅ NULL handling for array operators
+- ✅ Recursive query builder with logicalDepth tracking
+- ✅ Complex nested queries (4-level nesting tested)
+- ✅ Benchmarked: 27.39ms average (10k docs)
+- ✅ DRY architecture: Pure functions, no god objects
+- ✅ WAL performance verified: 2.39x speedup (in-memory), 3-6x (file-based)
+- ✅ Nested query tests: 7 comprehensive tests
+- ✅ Architectural patterns documented (10 patterns)
+- ✅ RxDB API alignment verified (partial success pattern)
+
+**Phase 4 (v1.0 Preparation - COMPLETE ✅):**
+- ✅ Operators: DONE in v0.4.0 (18 operators implemented)
+- ✅ RxDB official test suite: DONE (122/122 passing)
+- ✅ Benchmarks: DONE (1.06-1.68x faster than better-sqlite3)
+- ✅ Conflict handling: DONE (409 errors with documentInDb)
+- ✅ Attachments support (getAttachmentData + 4 tests passing)
+- ✅ Refactor bulkWrite (uses categorizeBulkWriteRows helper)
+- ✅ All 5 RxDB helper functions implemented
+- ✅ Test Results: 260/260 tests passing (138 local + 122 official)
+
+---
+
+## 🚀 Post-v1.0 Enhancements (Future)
+
+**These are NOT blockers for v1.0. Implement when users request them.**
+
+### **Custom Indexes from schema.indexes (Optional)**
+- Implement `CREATE INDEX` based on `schema.indexes` definitions
+- **Why defer:** Not required by RxStorageInstance interface, optional optimization
+- **How Dexie does it:** Uses `dexieDb.version(1).stores()` with schema.indexes
+- **Effort:** 4-6 hours
+- **Benefit:** Faster queries on indexed fields (currently only deleted/mtime_ms indexed)
+
+---
+
+## 📋 REMOVED from Roadmap (Research Findings)
+
+**These features DON'T EXIST in RxDB or are already complete:**
+
+### ❌ conflictResolutionTasks() / resolveConflictResultionTask()
+- **Status:** REMOVED in RxDB 16.0.0
+- **Evidence:** Release notes explicitly state removal
+- **What we have:** 409 error handling (correct approach)
+- **Conflict resolution:** Happens at replication level, NOT storage level
+
+### ✅ Operators
+- **Status:** DONE in v0.4.0
+- **Implemented:** 18 operators ($eq, $ne, $gt, $gte, $lt, $lte, $in, $nin, $and, $or, $exists, $regex, $elemMatch, $not, $nor, $type, $size, $mod)
+
+### ❌ normalizeMangoQuery() / prepareQuery()
+- **Status:** OUT OF SCOPE - RxDB core responsibility
+- **Evidence:** Implemented in `rx-query-helper.ts` (lines 35, 269)
+- **What storage receives:** `PreparedQuery` objects (already normalized with query plans)
+- **Interface comment:** "User provided mango queries will be filled up by RxDB via normalizeMangoQuery()"
+- **Conclusion:** Storage adapters do NOT implement these
+
+### ❌ user_version pragma for Schema Migrations
+- **Status:** OUT OF SCOPE - RxDB handles migrations at collection level
+- **Evidence:** No storage plugin uses `user_version`, migrations in `plugins/migration-schema/`
+- **How RxDB handles it:** Schema version in `schema.version`, migrations via plugins
+- **Conclusion:** Storage adapters are version-agnostic, only store data for specific schema version
+
+### ❌ EXPLAIN QUERY PLAN
+- **Status:** OUT OF SCOPE - RxDB provides query plans
+- **Evidence:** No storage plugin uses EXPLAIN QUERY PLAN
+- **What RxDB provides:** `PreparedQuery.queryPlan` with index hints from `query-planner.ts`
+- **Interface comment:** "queryPlan is a hint... not required to use it"
+- **Conclusion:** Storage adapters receive query plans, don't need to generate them
+
+---
+
+## 🔬 Future Research Topics
+
+#### **Hybrid SQL+Mingo Pattern (QUESTION MARK)**
+
+**Goal:** Implement SQL pre-filter + Mingo post-filter IF senior provides evidence.
+
+**Status:** ❓ **ON HOLD** - Waiting for senior to provide:
+- Production examples using this pattern
+- Benchmarks proving it's faster than pure SQL
+- Use cases where it's needed
+
+**If validated:**
+1. Implement hybrid query executor
+2. Benchmark vs pure SQL
+3. Document when to use each approach
+
+**Effort:** 2 hours (if validated)  
+**Status:** ❓ Unproven - need evidence from senior
+
+---
+
+## 🤝 Contributing
+
+This is a community project! Contributions welcome.
+
+**How to help:**
+1. Test with your RxDB app
+2. Report bugs/edge cases
+3. Submit PRs for missing features
+4. Share performance benchmarks
+
+---
+
+**Not affiliated with RxDB or Bun. Community-maintained adapter.**
+
+_Last updated: 2026-02-23 by adam2am_

package/benchmarks/benchmark.ts

@@ -0,0 +1,145 @@
+import { getRxStorageBunSQLite } from '../src/storage';
+import type { RxDocumentData } from 'rxdb';
+
+interface BenchmarkDocType {
+	id: string;
+	name: string;
+	age: number;
+	status: string;
+}
+
+async function benchmark() {
+	console.log('🏴‍☠️ Benchmarking Phase 3 (Advanced Query Operators)...\n');
+
+	const storage = getRxStorageBunSQLite();
+	const instance = await storage.createStorageInstance<BenchmarkDocType>({
+		databaseInstanceToken: 'benchmark-token',
+		databaseName: 'benchmark',
+		collectionName: 'users',
+		schema: {
+			version: 0,
+			primaryKey: 'id',
+			type: 'object',
+			properties: {
+				id: { type: 'string', maxLength: 100 },
+				name: { type: 'string' },
+				age: { type: 'number' },
+				status: { type: 'string' },
+				_deleted: { type: 'boolean' },
+				_attachments: { type: 'object' },
+				_rev: { type: 'string' },
+				_meta: {
+					type: 'object',
+					properties: {
+						lwt: { type: 'number' }
+					}
+				}
+			},
+			required: ['id', 'name', 'age', 'status', '_deleted', '_attachments', '_rev', '_meta']
+		},
+		options: {},
+		multiInstance: false,
+		devMode: false
+	});
+
+	console.log('📝 Inserting 10,000 documents...');
+	const docs: Array<{ document: RxDocumentData<BenchmarkDocType> }> = [];
+	for (let i = 0; i < 10000; i++) {
+		docs.push({
+			document: {
+				id: `user${i}`,
+				name: `User ${i}`,
+				age: 18 + (i % 50),
+				status: i % 2 === 0 ? 'active' : 'inactive',
+				_deleted: false,
+				_attachments: {},
+				_rev: '1-abc',
+				_meta: { lwt: Date.now() }
+			}
+		});
+	}
+
+	await instance.bulkWrite(docs, 'benchmark');
+	console.log('✅ Inserted 10,000 documents\n');
+
+	console.log('⏱️  Query 1: Simple equality (age = 25)');
+	const start1 = performance.now();
+	const result1 = await instance.query({
+		query: { selector: { age: 25 }, sort: [], skip: 0 },
+		queryPlan: { index: [], startKeys: [], endKeys: [], inclusiveStart: true, inclusiveEnd: true, sortSatisfiedByIndex: false, selectorSatisfiedByIndex: false }
+	});
+	const end1 = performance.now();
+	console.log(`   Found ${result1.documents.length} documents in ${(end1 - start1).toFixed(2)}ms\n`);
+
+	console.log('⏱️  Query 2: Greater than (age > 50)');
+	const start2 = performance.now();
+	const result2 = await instance.query({
+		query: { selector: { age: { $gt: 50 } }, sort: [], skip: 0 },
+		queryPlan: { index: [], startKeys: [], endKeys: [], inclusiveStart: true, inclusiveEnd: true, sortSatisfiedByIndex: false, selectorSatisfiedByIndex: false }
+	});
+	const end2 = performance.now();
+	console.log(`   Found ${result2.documents.length} documents in ${(end2 - start2).toFixed(2)}ms\n`);
+
+	console.log('⏱️  Query 3: Multiple conditions (age > 30 AND status = "active")');
+	const start3 = performance.now();
+	const result3 = await instance.query({
+		query: { selector: { age: { $gt: 30 }, status: 'active' }, sort: [], skip: 0 },
+		queryPlan: { index: [], startKeys: [], endKeys: [], inclusiveStart: true, inclusiveEnd: true, sortSatisfiedByIndex: false, selectorSatisfiedByIndex: false }
+	});
+	const end3 = performance.now();
+	console.log(`   Found ${result3.documents.length} documents in ${(end3 - start3).toFixed(2)}ms\n`);
+
+	console.log('⏱️  Query 4: Range query (age >= 20 AND age <= 40)');
+	const start4 = performance.now();
+	const result4 = await instance.query({
+		query: { selector: { age: { $gte: 20, $lte: 40 } }, sort: [], skip: 0 },
+		queryPlan: { index: [], startKeys: [], endKeys: [], inclusiveStart: true, inclusiveEnd: true, sortSatisfiedByIndex: false, selectorSatisfiedByIndex: false }
+	});
+	const end4 = performance.now();
+	console.log(`   Found ${result4.documents.length} documents in ${(end4 - start4).toFixed(2)}ms\n`);
+
+	console.log('⏱️  Query 5: $in operator (age in [25, 30, 35, 40])');
+	const start5 = performance.now();
+	const result5 = await instance.query({
+		query: { selector: { age: { $in: [25, 30, 35, 40] } }, sort: [], skip: 0 },
+		queryPlan: { index: [], startKeys: [], endKeys: [], inclusiveStart: true, inclusiveEnd: true, sortSatisfiedByIndex: false, selectorSatisfiedByIndex: false }
+	});
+	const end5 = performance.now();
+	console.log(`   Found ${result5.documents.length} documents in ${(end5 - start5).toFixed(2)}ms\n`);
+
+	console.log('⏱️  Query 6: $or operator (age < 20 OR age > 60)');
+	const start6 = performance.now();
+	const result6 = await instance.query({
+		query: { selector: { $or: [{ age: { $lt: 20 } }, { age: { $gt: 60 } }] }, sort: [], skip: 0 },
+		queryPlan: { index: [], startKeys: [], endKeys: [], inclusiveStart: true, inclusiveEnd: true, sortSatisfiedByIndex: false, selectorSatisfiedByIndex: false }
+	});
+	const end6 = performance.now();
+	console.log(`   Found ${result6.documents.length} documents in ${(end6 - start6).toFixed(2)}ms\n`);
+
+	console.log('⏱️  Query 7: $nin operator (status not in ["pending", "archived"])');
+	const start7 = performance.now();
+	const result7 = await instance.query({
+		query: { selector: { status: { $nin: ['pending', 'archived'] } }, sort: [], skip: 0 },
+		queryPlan: { index: [], startKeys: [], endKeys: [], inclusiveStart: true, inclusiveEnd: true, sortSatisfiedByIndex: false, selectorSatisfiedByIndex: false }
+	});
+	const end7 = performance.now();
+	console.log(`   Found ${result7.documents.length} documents in ${(end7 - start7).toFixed(2)}ms\n`);
+
+	console.log('⏱️  Query 8: Complex nested ($or + $and + $in)');
+	const start8 = performance.now();
+	const result8 = await instance.query({
+		query: { selector: { $or: [{ $and: [{ age: { $gte: 30 } }, { status: 'active' }] }, { age: { $in: [18, 19, 20] } }] }, sort: [], skip: 0 },
+		queryPlan: { index: [], startKeys: [], endKeys: [], inclusiveStart: true, inclusiveEnd: true, sortSatisfiedByIndex: false, selectorSatisfiedByIndex: false }
+	});
+	const end8 = performance.now();
+	console.log(`   Found ${result8.documents.length} documents in ${(end8 - start8).toFixed(2)}ms\n`);
+
+	const avgTime = ((end1 - start1) + (end2 - start2) + (end3 - start3) + (end4 - start4) + (end5 - start5) + (end6 - start6) + (end7 - start7) + (end8 - start8)) / 8;
+	console.log(`📊 Average query time: ${avgTime.toFixed(2)}ms`);
+	console.log(`\n✅ Phase 3 includes advanced operators: $in, $nin, $or, $and`);
+	console.log(`   Expected speedup: 10-100x for large datasets (vs Phase 1 in-memory filtering)\n`);
+
+	await instance.close();
+}
+
+benchmark().catch(console.error);