spl.js 1.0.0 → 1.0.1

package/.TODO.md

@@ -0,0 +1,792 @@
+# Cursor Implementation for spl.js
+
+## Background: SQLite Cursors
+
+### SQLite C API
+
+SQLite doesn't expose a separate "cursor" object. Instead, the **prepared statement** (`sqlite3_stmt`) acts as the cursor:
+
+- `sqlite3_prepare_v2()` - Compile SQL into a prepared statement
+- `sqlite3_step()` - Advance to next row (returns `SQLITE_ROW` or `SQLITE_DONE`)
+- `sqlite3_column_*()` - Extract column values from current row
+- `sqlite3_reset()` - Rewind cursor to beginning for re-execution
+- `sqlite3_finalize()` - Destroy statement and free resources
+
+### Advantages of Cursors
+
+| Advantage | Description |
+|-----------|-------------|
+| Memory efficient | Rows fetched one-at-a-time, no need to load entire result set |
+| Streaming | Process large datasets without memory exhaustion |
+| Random access | Can bind new parameters and re-execute with reset |
+| Multiple concurrent | Many cursors can operate on same table independently |
+| Fast seeking | Internal B-tree cursors enable efficient key-based lookups |
+
+### Disadvantages of Cursors
+
+| Disadvantage | Description |
+|--------------|-------------|
+| Manual lifecycle | Must finalize or risk memory leaks |
+| No row locking | Other operations can modify data under an active cursor |
+| Forward-only by default | Standard iteration is sequential |
+| Statement caching | Reusing statements requires careful reset management |
+| Connection affinity | Cursors tied to their database connection |
+
+### References
+
+- [SQLite C/C++ Interface Introduction](https://sqlite.org/cintro.html)
+- [sqlite3_step() Documentation](https://sqlite.org/c3ref/step.html)
+- [SQLite B-Tree Module](https://sqlite.org/btreemodule.html)
+- [SQLite Bytecode Engine](https://sqlite.org/opcode.html)
+
+---
+
+## Current spl.js Architecture
+
+### Message Protocol (Main Thread -> Worker)
+
+```javascript
+// Single operation
+{
+  __id__: number,        // Unique message ID for response matching
+  fn: string,            // Function name (e.g., 'db.exec', 'fs.file')
+  id: number,            // Database instance ID
+  args: any[]            // Arguments to pass
+}
+
+// Batch operations
+{
+  __id__: number,
+  fn: [
+    { id, fn, args },    // Array of multiple operations
+    ...
+  ]
+}
+```
+
+### Response Protocol (Worker -> Main Thread)
+
+```javascript
+{
+  __id__: number,        // Echoes the request's __id__
+  res: any,              // Result/response data
+  err: string            // Error message if execution failed
+}
+```
+
+### Key Architectural Patterns
+
+1. **Promise Queue**: Each message gets unique `__id__` stored in queue, response matches it back
+2. **Transferables**: Large ArrayBuffers transferred by reference, not copied
+3. **Batch Operations**: Multiple SQL operations sent in single message via async generator
+4. **Thenable Chaining**: Synchronous API stacks operations, sends in batch when awaited
+
+---
+
+## Research: How Other Libraries Handle This
+
+### Python sqlite3 (DB-API 2.0)
+
+```python
+# Create cursor from connection
+cur = con.cursor()
+
+# execute() prepares but does NOT fetch all rows
+cur.execute("SELECT * FROM users WHERE age > ?", (18,))
+
+# User chooses fetch strategy AFTER execute:
+row = cur.fetchone()           # Single row
+rows = cur.fetchmany(100)      # Batch of 100
+rows = cur.fetchall()          # All at once
+
+# Or iterate directly (cursor is iterable)
+for row in cur.execute("SELECT * FROM users"):
+    print(row)
+```
+
+**Key behavior discovered in [CPython source](https://github.com/python/cpython/blob/main/Modules/_sqlite/cursor.c):**
+
+```c
+// In _pysqlite_query_execute():
+rc = stmt_step(self->statement->st);  // Step ONCE
+
+if (rc == SQLITE_ROW) {
+    // SELECT with results → STOP HERE
+    // Statement left "open", positioned at first row
+}
+else if (rc == SQLITE_DONE) {
+    // INSERT/UPDATE/DELETE or empty SELECT
+    // Reset statement immediately
+    stmt_reset(self->statement);
+}
+```
+
+**Python steps ONCE** - just enough to determine if there's data:
+- `SQLITE_ROW` → SELECT has data, statement stays open for lazy fetch
+- `SQLITE_DONE` → INSERT/UPDATE/DELETE executed immediately, or empty SELECT
+
+### better-sqlite3 (Node.js)
+
+```javascript
+// Prepare statement from db
+const stmt = db.prepare('SELECT * FROM users WHERE age > ?');
+
+// User chooses execution method:
+const row = stmt.get(18);              // First row only
+const rows = stmt.all(18);             // All rows at once
+for (const row of stmt.iterate(18)) { // Iterate one-by-one
+    console.log(row);
+}
+```
+
+**Key insight**: `.prepare()` creates statement, then user chooses `.all()` vs `.iterate()`.
+
+### Pattern Comparison
+
+| Library | Prepare | Get All | Iterate/Stream |
+|---------|---------|---------|----------------|
+| **Python sqlite3** | `cur.execute(sql)` | `cur.fetchall()` | `for row in cur:` |
+| **better-sqlite3** | `db.prepare(sql)` | `stmt.all()` | `stmt.iterate()` |
+| **spl.js current** | `db.exec(sql)` | `db.get.rows` | ❌ N/A |
+
+**Both libraries separate preparation from fetching strategy.**
+
+### References
+
+- [Python sqlite3 Documentation](https://docs.python.org/3/library/sqlite3.html)
+- [CPython sqlite3 cursor.c source](https://github.com/python/cpython/blob/main/Modules/_sqlite/cursor.c)
+- [better-sqlite3 API](https://github.com/WiseLibs/better-sqlite3/blob/master/docs/api.md)
+
+---
+
+## API Design Options (Undecided)
+
+### The `exec().cursor()` Problem
+
+**Issue**: In synchronous code, `exec()` cannot know if `.cursor()` will be called after it returns.
+
+Current spl.js `exec()` behavior:
+1. Prepares statement
+2. Binds parameters
+3. **Steps through ALL rows** (loads entire result into memory)
+4. Finalizes statement
+5. Returns `_db` for chaining
+
+When `cursor()` is then called, the data is **already fully loaded in memory**, defeating the purpose of streaming/cursor-based iteration.
+
+---
+
+### Option A: `db.cursor(sql, params, batchSize?)`
+
+Separate method, bypasses `exec()` entirely.
+
+```javascript
+// Node.js (sync)
+const cursor = db.cursor('SELECT * FROM users WHERE age > ?', [18], 100);
+
+console.log(cursor.cols);  // ['id', 'name', 'age']
+
+while (!cursor.done) {
+    for (const user of cursor.objs) {
+        console.log(user.name);
+    }
+}
+```
+
+| Pros | Cons |
+|------|------|
+| No wasted work | New method to learn |
+| Clear separation of concerns | Different pattern from exec() |
+| Single prepare, single pass | |
+
+**Implementation**: New `db.cursor()` method, straightforward.
+
+---
+
+### Option B: `exec(sql, params, { cursor: true/batchSize })`
+
+Flag on exec() to return cursor instead of db.
+
+```javascript
+// Node.js (sync)
+const cursor = db.exec('SELECT * FROM users WHERE age > ?', [18], { cursor: true });
+// or with explicit batch size:
+const cursor = db.exec('SELECT * FROM users WHERE age > ?', [18], { cursor: 100 });
+
+console.log(cursor.cols);  // ['id', 'name', 'age']
+
+while (!cursor.done) {
+    for (const user of cursor.objs) {
+        console.log(user.name);
+    }
+}
+```
+
+| Pros | Cons |
+|------|------|
+| No wasted work - exec() knows mode upfront | Return type changes based on options |
+| Single entry point (no new method) | Chaining stops when cursor mode (returns cursor, not _db) |
+| No breaking change | Options parameter adds complexity |
+| Explicit intent | |
+
+**Implementation**:
+```javascript
+this.exec = (sql, par, opt = {}) => {
+    const { cursor: cursorMode } = opt;
+    const batchSize = typeof cursorMode === 'number' ? cursorMode : 100;
+
+    if (cursorMode) {
+        // Cursor mode: prepare + bind, step ONCE
+        const stmt = sqlite3_prepare_v2(...);
+        bind(stmt, par);
+        sqlite3_step(stmt);  // Step to first row
+        const columns = getColumnNames(stmt);
+        const firstRow = readCurrentRow(stmt);
+        return createCursor(stmt, columns, firstRow, batchSize);
+    }
+
+    // Normal mode: existing behavior
+    // ... prepare, bind, step ALL, finalize ...
+    return _db;
+};
+```
+
+---
+
+### Option C: `exec(...).cursor()` with Lazy exec (Python-style) ⭐
+
+Modify `exec()` to step **once** like Python - just enough to determine if there's data.
+
+```javascript
+// Usage stays the same:
+db.exec('INSERT INTO users VALUES (?)', ['Alice']);  // Executes immediately (DONE)
+db.exec('SELECT * FROM users');                       // Steps once, waits
+db.get.rows;                                          // NOW fetches all remaining
+// OR
+db.exec('SELECT * FROM users').cursor(100);           // Returns cursor for streaming
+```
+
+**Implementation**:
+
+```javascript
+this.exec = (sql, par) => {
+    const stmt = sqlite3_prepare_v2(sql);
+    bind(stmt, par);
+
+    const rc = sqlite3_step(stmt);  // Step ONCE
+
+    if (rc === SQLITE_DONE) {
+        // INSERT/UPDATE/DELETE or empty SELECT
+        // Executed immediately, finalize now
+        sqlite3_finalize(stmt);
+        _result = result([], []);
+        _pendingStmt = null;
+    }
+    else if (rc === SQLITE_ROW) {
+        // SELECT with data - save state, DON'T finalize
+        _pendingStmt = stmt;
+        _pendingColumns = getColumns(stmt);
+        _firstRow = readCurrentRow(stmt);  // Save row we already stepped to
+    }
+
+    return _db;
+};
+
+// .get - consume all remaining rows (lazy)
+Object.defineProperty(this, 'get', {
+    get: () => {
+        if (_pendingStmt) {
+            const rows = [_firstRow];  // Include first row
+            while (sqlite3_step(_pendingStmt) === SQLITE_ROW) {
+                rows.push(readCurrentRow(_pendingStmt));
+            }
+            sqlite3_finalize(_pendingStmt);
+            _result = result(_pendingColumns, rows);
+            _pendingStmt = null;
+            _firstRow = null;
+        }
+        return _result;
+    }
+});
+
+// .cursor() - return iterator using the open statement
+this.cursor = (batchSize = 100) => {
+    if (!_pendingStmt) {
+        throw new Error('No pending SELECT or already consumed');
+    }
+    const cursor = createCursor(_pendingStmt, _pendingColumns, _firstRow, batchSize);
+    _pendingStmt = null;  // Cursor now owns the statement
+    _firstRow = null;
+    return cursor;
+};
+```
+
+| Pros | Cons |
+|------|------|
+| `exec().cursor()` works efficiently | Subtle behavior change (lazy fetch) |
+| Matches Python's proven pattern | `.get` must be called to consume results |
+| INSERT/UPDATE/DELETE still immediate | Can only call `.get` OR `.cursor()`, not both |
+| No new methods needed | Need to handle "dangling" statement if neither called |
+| Single pass, no wasted work | |
+
+**Edge cases to handle**:
+- What if user calls `exec()` twice without consuming first? → Finalize previous `_pendingStmt`
+- What if `db.close()` called with pending statement? → Finalize in close()
+- Empty SELECT (no rows)? → `SQLITE_DONE` on first step, same as INSERT
+
+---
+
+### Comparison Summary
+
+| Aspect | Option A | Option B | Option C |
+|--------|----------|----------|----------|
+| API | `db.cursor()` | `exec(..., {cursor})` | `exec().cursor()` |
+| Efficiency | ✅ Single pass | ✅ Single pass | ✅ Single pass |
+| Breaking change | No | No | Subtle (lazy `.get`) |
+| New method | Yes | No | No |
+| Return type | New type | Conditional | Consistent |
+| Chaining after | N/A | Stops | `.get` or `.cursor()` |
+| Matches Python | Partially | No | ✅ Yes |
+
+---
+
+## Cursor Object Design
+
+The cursor mirrors Result's API but fetches lazily in batches.
+
+### Result vs Cursor Comparison
+
+| Property | Result | Cursor |
+|----------|--------|--------|
+| `.cols` | Getter (all columns) | Getter (all columns) |
+| `.rows` | Getter (all data) | Getter (next batch as arrays) |
+| `.objs` | Getter (all data) | Getter (next batch as objects) |
+| `.flat` | Getter (all data) | Getter (next batch flattened) |
+| `.first` | Getter (first row) | N/A (use `exec().get.first` instead) |
+| `.done` | N/A | Getter (true if exhausted) |
+
+### Auto-Cleanup Behavior (Important for Documentation)
+
+Cursors are **automatically finalized** in these scenarios:
+
+1. **Cursor exhausted** - When `.done` becomes true (all rows consumed)
+2. **New `exec()` called** - Finalizes any previous pending statement
+3. **`db.close()` called** - Finalizes all open cursors/statements
+
+**No explicit `close()` or `reset()` needed.** Users can simply:
+- Iterate until done (auto-cleanup)
+- Call `exec()` again (previous cursor cleaned up)
+- Let cursor go out of scope after `exec()` replaces it
+
+### Implementation
+
+```javascript
+const createCursor = (stmt, columns, firstRow, batchSize) => {
+    let _done = false;
+    let _firstRow = firstRow;  // Already stepped to first row in exec()
+
+    const fetchBatch = () => {
+        if (_done) return [];
+
+        const rows = [];
+
+        // Include first row if we have it
+        if (_firstRow) {
+            rows.push(_firstRow);
+            _firstRow = null;
+        }
+
+        // Fetch remaining up to batchSize
+        while (rows.length < batchSize) {
+            const rc = sqlite3_step(stmt);
+            if (rc === SQLITE_ROW) {
+                rows.push(readCurrentRow(stmt));
+            } else {
+                _done = true;
+                sqlite3_finalize(stmt);  // Auto-finalize when exhausted
+                break;
+            }
+        }
+
+        return rows;
+    };
+
+    const toObj = (row) => columns.reduce((o, col, i) => {
+        o[col] = row[i];
+        return o;
+    }, {});
+
+    return Object.freeze({
+        // Metadata
+        get cols() { return columns.slice(); },
+        get done() { return _done; },
+
+        // Fetch getters - each access fetches next batch
+        get rows() { return fetchBatch(); },
+        get objs() { return fetchBatch().map(toObj); },
+        get flat() { return fetchBatch().flat(); },
+    });
+};
+```
+
+### Usage Examples
+
+```javascript
+// Node.js (sync)
+const cursor = db.exec('SELECT id, name, age FROM users').cursor(100);
+
+console.log(cursor.cols);  // ['id', 'name', 'age']
+
+while (!cursor.done) {
+    for (const user of cursor.objs) {
+        console.log(user.name);
+    }
+}
+// Cursor auto-finalized when exhausted
+
+// For single row, don't use cursor:
+const count = db.exec('SELECT COUNT(*) FROM users').get.first;
+
+// Mix formats (each .rows/.objs/.flat fetches next batch)
+const cursor2 = db.exec('SELECT * FROM logs').cursor(50);
+const first50asArrays = cursor2.rows;
+const next50asObjects = cursor2.objs;
+// Keep fetching until cursor.done...
+```
+
+---
+
+## Future API Exploration
+
+Alternative designs to consider later:
+
+### `get.lazy` on Result
+
+```javascript
+// Instead of db.exec().cursor(), access cursor via .get
+const cursor = db.exec('SELECT * FROM users').get.lazy(100);  // Returns cursor instead of all rows
+// or with batchSize in spl (browser) options
+const cursor = db.exec('SELECT * FROM users').get.lazy.objs
+```
+
+**Pros**: Consistent with existing `.get.rows`, `.get.objs` pattern
+**Cons**: Result object would need reference to pending statement
+
+---
+
+## Transaction Isolation Considerations
+
+**Important**: Multiple cursors on the same connection share transaction context.
+
+| Scenario | Behavior |
+|----------|----------|
+| Cursor A reads, Cursor B reads | Both see same snapshot (within same transaction) |
+| Cursor A reads, Cursor B writes | Cursor A may see B's changes (no isolation) |
+| Cursor A reads, external write | Depends on transaction/WAL mode |
+
+### Implications
+
+1. **Read-only cursors** (typical use case): Safe to have multiple concurrent cursors
+2. **Mixed read/write**: Changes from one cursor visible to others immediately
+3. **No row-level locking**: SQLite uses database-level locking, not row-level
+
+### Recommendations
+
+- Document that cursors share transaction state
+- For isolation, user should use explicit transactions: `BEGIN IMMEDIATE` before opening cursors
+- Consider adding `cursor({ readonly: true })` option for future optimization
+- WAL mode provides better concurrent read behavior
+
+---
+
+## Resource Lifecycle & Cleanup
+
+This is a **critical design concern**, especially for the browser where we cannot rely on garbage collection to clean up worker-side resources.
+
+### The Core Problem
+
+```
+┌─────────────────────┐                    ┌─────────────────────┐
+│    Main Thread      │                    │       Worker        │
+├─────────────────────┤                    ├─────────────────────┤
+│                     │                    │                     │
+│  cursor proxy ──────┼─── messages ──────►│  sqlite3_stmt       │
+│  (JS object)        │                    │  (real resource)    │
+│                     │                    │                     │
+│  goes out of        │                    │  ??? never          │
+│  scope... GC'd      │                    │  finalized          │
+│                     │                    │  MEMORY LEAK        │
+└─────────────────────┘                    └─────────────────────┘
+```
+
+The worker has **no way to know** when the main thread's proxy object is garbage collected.
+
+### Eager vs Lazy Resource Ownership
+
+| Mode | Where Data Lives | Worker State After Return | Leak Risk |
+|------|------------------|---------------------------|-----------|
+| **Eager** (`get.rows`) | Main thread (transferred) | None | ✅ No leak |
+| **Lazy** (cursor) | Worker (stmt open) | Holds `sqlite3_stmt` | ❌ Leaks if not drained |
+
+With eager fetching, data is transferred to main thread and worker holds nothing. With lazy cursors, the worker retains the open statement until explicitly finalized or exhausted.
+
+### Possible Solutions
+
+#### 1. Single Cursor/Result Per DB (Simplest) ⭐
+
+```javascript
+// Only ONE pending statement allowed per db
+// New exec() auto-finalizes previous
+const cursor1 = db.exec('SELECT * FROM a').cursor();
+const cursor2 = db.exec('SELECT * FROM b').cursor();  // cursor1 auto-finalized
+```
+
+| Pros | Cons |
+|------|------|
+| No reference counting needed | Can't iterate two result sets simultaneously |
+| No cursor IDs to manage | |
+| Trivial cleanup logic | |
+| Matches 99% of real use cases | |
+
+**Implementation**: Single `_pendingStmt` per db. New `exec()` calls `sqlite3_finalize()` on previous.
+
+#### 2. Explicit Close Required
+
+```javascript
+const cursor = db.exec('SELECT...').cursor();
+try {
+    while (!cursor.done) { /* ... */ }
+} finally {
+    cursor.close();  // REQUIRED - user's responsibility
+}
+```
+
+| Pros | Cons |
+|------|------|
+| Deterministic cleanup | Users forget to close |
+| Matches RAII pattern | Exceptions can skip cleanup |
+| Allows multiple concurrent cursors | No enforcement mechanism |
+
+#### 3. Callback/Scoped Pattern
+
+```javascript
+db.withCursor('SELECT...', [params], (cursor) => {
+    while (!cursor.done) {
+        console.log(cursor.objs);
+    }
+});  // Auto-finalized after callback returns
+```
+
+| Pros | Cons |
+|------|------|
+| Guaranteed cleanup | Callback style awkward |
+| Works with sync and async | Nesting hell with multiple cursors |
+| Clear ownership boundaries | Doesn't compose well with async/await |
+
+#### 4. FinalizationRegistry (Browser Only)
+
+**Note**: Only relevant for browser implementation where main thread cannot directly access worker-side resources. In Node.js, resources are in the same thread and can be cleaned up directly.
+
+```javascript
+// Browser main thread
+const registry = new FinalizationRegistry((cursorId) => {
+    worker.postMessage({ fn: 'cursor.finalize', id: cursorId });
+});
+
+function createCursorProxy(cursorId) {
+    const proxy = { /* cursor methods */ };
+    registry.register(proxy, cursorId);  // Clean up when proxy is GC'd
+    return proxy;
+}
+```
+
+| Pros | Cons |
+|------|------|
+| Automatic, transparent | GC timing non-deterministic |
+| No user action required | Hard to test (can't force GC) |
+| Good browser support (Chrome 84+, Firefox 79+, Safari 14.1+) | Spec warns against relying on it for "correctness" |
+| Page close is fine (worker dies anyway, OS reclaims) | |
+
+**When FinalizationRegistry is appropriate for this use case**:
+
+The spec warning ("don't rely on this for correctness") applies when cleanup *must* happen before some operation. For cursor cleanup, we only need *eventual* cleanup to prevent unbounded memory growth:
+
+| Scenario | Outcome | Problem? |
+|----------|---------|----------|
+| Cursor abandoned, page open | GC eventually runs, finalizer cleans up | ✅ Works |
+| Cursor abandoned, page closed | Worker terminated, OS reclaims | ✅ No leak |
+| Long pause before GC | Memory temporarily higher | ⚠️ Minor, transient |
+
+**Verdict**: Suitable as a **safety net** for browser multi-cursor support, not as the sole cleanup mechanism. Pair with optional explicit `close()` for users who need deterministic cleanup.
+
+#### 5. Max Cursors + LRU Eviction
+
+```javascript
+// Worker maintains: Map<cursorId, { stmt, lastAccess, dbId }>
+// When cursors.size > MAX_CURSORS, finalize least recently used
+const MAX_CURSORS_PER_DB = 10;
+```
+
+| Pros | Cons |
+|------|------|
+| Bounded memory usage | Surprising behavior (cursor silently invalidated) |
+| Handles forgetful users | Added complexity |
+| Configurable limits | Arbitrary limit choice |
+
+#### 6. Timeout-Based Cleanup
+
+```javascript
+// Worker: if cursor not accessed for N seconds, auto-finalize
+const CURSOR_IDLE_TIMEOUT_MS = 30000;
+```
+
+| Pros | Cons |
+|------|------|
+| Handles abandoned cursors | Long iterations might timeout |
+| No user action required | Unpredictable for users |
+| Bounded leak duration | Adds timer complexity |
+
+### Recommended Approach: Layered Strategy
+
+#### Layer 1: Single Pending Statement Per DB (Default)
+
+For the initial implementation, enforce **one pending statement per db connection**:
+
+```javascript
+// This "just works" - no leaks possible
+const cursor = db.exec('SELECT * FROM users').cursor();
+while (!cursor.done) { ... }
+
+// Or if user forgets to drain:
+db.exec('SELECT * FROM a').cursor();  // opens cursor
+db.exec('SELECT * FROM b');           // auto-closes previous, no leak
+db.close();                           // also auto-closes any pending
+```
+
+**Why this works**:
+- Matches how most users actually query (one at a time)
+- Zero reference counting complexity
+- Impossible to leak - next operation cleans up previous
+- No IDs needed in worker (just one `_pendingStmt` per db)
+
+#### Layer 2: Explicit Multi-Cursor (Future, Opt-in)
+
+If users genuinely need multiple concurrent cursors, require explicit lifecycle management:
+
+```javascript
+// Opt-in to complexity via named cursors
+const cursor1 = db.exec('SELECT * FROM a').cursor({ name: 'cur1' });
+const cursor2 = db.exec('SELECT * FROM b').cursor({ name: 'cur2' });
+// Both remain open until explicitly closed or db.close()
+cursor1.close();
+cursor2.close();
+```
+
+Or use the callback pattern for guaranteed cleanup:
+
+```javascript
+await db.withCursor('SELECT * FROM users', [], async (cursor) => {
+    while (!cursor.done) {
+        await processBatch(cursor.objs);
+    }
+});  // Cursor guaranteed finalized here
+```
+
+#### Browser Implementation: FinalizationRegistry as Safety Net
+
+For browser multi-cursor support, use FinalizationRegistry as a fallback for cursors that aren't explicitly closed:
+
+```javascript
+// Browser: belt-and-suspenders approach
+const cursor = db.exec('SELECT...').cursor();
+
+// Option A: Rely on FinalizationRegistry (automatic, eventual)
+// When cursor proxy is GC'd, worker receives cleanup message
+
+// Option B: Explicit close (deterministic, immediate)
+cursor.close();
+
+// Both work. Explicit close is faster, but forgotten cursors
+// still get cleaned up eventually via FinalizationRegistry.
+```
+
+This doesn't apply to Node.js where resources are in the same thread and cleanup is straightforward.
+
+### Browser-Specific Considerations
+
+| Event | Cleanup Behavior |
+|-------|------------------|
+| `db.close()` | Finalize all pending statements for that db |
+| New `exec()` on same db | Finalize previous pending statement |
+| Cursor exhausted (`.done` = true) | Auto-finalize |
+| Worker terminated | OS reclaims memory (not a leak, but abrupt) |
+| Page unload | Worker terminated, see above |
+| Tab backgrounded | No automatic cleanup (cursors remain open) |
+
+### Questions to Resolve Before Implementation
+
+1. **Do we ever need multiple concurrent cursors per db?**
+   - If no → Single-cursor-per-db is sufficient, dramatically simpler
+   - If yes → Need explicit lifecycle (close/callback) or accept leak risk
+
+2. **Should eager Results also become "pending" with lazy exec (Option C)?**
+   - Currently: `exec()` fetches all, returns immediately
+   - With Option C: `exec()` steps once, `.get` fetches rest
+   - This means even eager access leaves state until `.get` is called
+
+3. **Error on cursor access after invalidation?**
+   ```javascript
+   const cursor = db.exec('SELECT...').cursor();
+   db.exec('SELECT...');  // cursor invalidated
+   cursor.rows;  // Error? Empty array? Undefined behavior?
+   ```
+   Recommendation: Throw clear error "Cursor invalidated by subsequent exec()"
+
+4. **Should `cursor.close()` exist even in single-cursor mode?**
+   - Pro: Explicit cleanup without needing another exec()
+   - Pro: Familiar pattern for users from other libraries
+   - Con: Suggests close() is required (it isn't in single-cursor mode)
+
+---
+
+## Implementation Checklist
+
+*Note: Checklist depends on which API option is chosen (A, B, or C).*
+
+### Core (spl.js) - Sync API for Node.js
+
+**For Option C (Python-style lazy exec):**
+- [ ] Modify `exec()` to step ONCE and detect SQLITE_ROW vs SQLITE_DONE
+- [ ] Add `_pendingStmt`, `_pendingColumns`, `_firstRow` state variables
+- [ ] Modify `.get` getter to consume pending statement lazily
+- [ ] Implement `cursor(batchSize)` method that returns cursor object
+- [ ] Implement `createCursor()` with `.cols`, `.rows`, `.objs`, `.flat`, `.done` getters
+- [ ] Auto-finalize cursor when exhausted
+- [ ] Finalize pending statement on new `exec()` call
+- [ ] Finalize all pending statements on `db.close()`
+
+**For Options A or B:**
+- [ ] Implement `db.cursor()` method (Option A) or `exec(..., {cursor})` flag (Option B)
+- [ ] Implement `createCursor()` with getters
+- [ ] Handle cleanup scenarios
+
+### Worker (spl-worker.js) - Bridge
+- [ ] Add cursor state management (Map of cursor ID → cursor object)
+- [ ] Add `cursor.cols` handler (returns column names)
+- [ ] Add `cursor.fetch` handler (returns next batch as rows)
+- [ ] Add `cursor.done` handler (returns exhaustion status)
+- [ ] Handle format conversion (rows/objs/flat) on worker side
+
+### Browser (spl-web.js) - Async API
+- [ ] Wrap cursor operations in Thenable pattern
+- [ ] Implement cursor proxy with async getters
+- [ ] Add transferables support for ArrayBuffer columns in batches
+
+### Testing & Documentation
+- [ ] Write tests for cursor iteration until done
+- [ ] Test auto-cleanup when exhausted
+- [ ] Test cleanup on new exec() call
+- [ ] Test cleanup on db.close()
+- [ ] Test transaction isolation behavior
+- [ ] Document cursor API in README
+- [ ] Document auto-cleanup behavior