@quereus/isolation 0.2.0

package/README.md

@@ -0,0 +1,216 @@
+# @quereus/isolation
+
+Generic transaction isolation layer for Quereus virtual table modules.
+
+## Overview
+
+The `@quereus/isolation` package provides MVCC-style transaction isolation semantics for any Quereus virtual table module. It wraps existing modules to add:
+
+- **Read-your-own-writes** — See uncommitted changes within your transaction
+- **Snapshot isolation** — Consistent reads throughout the transaction
+- **Savepoint support** — Nested transaction control
+- **ACID semantics** — Full transaction guarantees
+
+This allows module authors to focus on storage concerns while getting isolation "for free."
+
+## Installation
+
+```bash
+yarn add @quereus/isolation @quereus/quereus
+```
+
+## Quick Start
+
+```typescript
+import { Database, MemoryTableModule } from '@quereus/quereus';
+import { IsolationModule } from '@quereus/isolation';
+
+const db = new Database();
+
+// Create any underlying module (memory, store, custom, etc.)
+const memoryModule = new MemoryTableModule();
+
+// Wrap it with the isolation layer
+const isolatedModule = new IsolationModule({
+	underlying: memoryModule,
+});
+
+db.registerModule('isolated', isolatedModule);
+
+// Use it like any other module, but with full isolation
+await db.exec(`CREATE TABLE users (
+	id INTEGER PRIMARY KEY,
+	name TEXT
+) USING isolated`);
+
+await db.exec('BEGIN');
+await db.exec(`INSERT INTO users VALUES (1, 'Alice')`);
+
+// Reads see uncommitted changes
+const user = await db.get('SELECT * FROM users WHERE id = 1');
+console.log(user.name); // 'Alice'
+
+await db.exec('COMMIT'); // Or ROLLBACK
+```
+
+## Architecture
+
+The isolation layer operates at the **row level**, merging query results from two modules:
+
+1. **Overlay module** — Stores uncommitted changes (inserts, updates, deletes as tombstones)
+2. **Underlying module** — Stores committed data
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                   IsolationModule                        │
+│                                                          │
+│  ┌────────────────────────────────────────────────────┐ │
+│  │         Overlay Module (e.g., memory vtab)         │ │
+│  │  - Stores pending inserts, updates, tombstones     │ │
+│  │  - Per-connection isolation                        │ │
+│  └────────────────────────────────────────────────────┘ │
+│                          │                               │
+│                          │ row-level merge               │
+│                          ▼                               │
+│  ┌────────────────────────────────────────────────────┐ │
+│  │           Underlying Module (any)                   │ │
+│  │  - LevelDB / IndexedDB store                       │ │
+│  │  - Custom module without isolation                 │ │
+│  └────────────────────────────────────────────────────┘ │
+└─────────────────────────────────────────────────────────┘
+```
+
+### Key Features
+
+**Per-connection overlay** — Each database instance gets its own overlay storage, ensuring proper isolation between connections.
+
+**Lazy overlay creation** — No memory overhead until the first write in a transaction.
+
+**Configurable overlay module** — Use memory for fast transactions, or persistent storage for large transactions:
+
+```typescript
+import { IsolationModule } from '@quereus/isolation';
+import { MemoryTableModule } from '@quereus/quereus';
+import { StoreModule } from '@quereus/store';
+
+// Fast, ephemeral overlay (default)
+const isolatedModule = new IsolationModule({
+	underlying: myStoreModule,
+	overlay: new MemoryTableModule(),
+});
+
+// Or use persistent overlay for large transactions
+const isolatedModule = new IsolationModule({
+	underlying: myStoreModule,
+	overlay: new StoreModule(tempStoreProvider),
+});
+```
+
+## API
+
+### `IsolationModule`
+
+```typescript
+class IsolationModule implements VirtualTableModule {
+	constructor(config: IsolationModuleConfig);
+	getCapabilities(): ModuleCapabilities;
+}
+```
+
+#### Configuration
+
+```typescript
+interface IsolationModuleConfig {
+	/** Module to wrap with isolation semantics */
+	underlying: VirtualTableModule<any, any>;
+
+	/** Optional overlay module (defaults to MemoryTableModule) */
+	overlay?: VirtualTableModule<any, any>;
+
+	/** Optional tombstone column name (defaults to '_tombstone') */
+	tombstoneColumn?: string;
+}
+```
+
+### Merge Utilities
+
+The package also exports low-level utilities for merging sorted streams:
+
+```typescript
+import { mergeStreams, createMergeEntry, createTombstone } from '@quereus/isolation';
+
+// Merge two sorted streams (overlay and underlying)
+const merged = mergeStreams(overlayStream, underlyingStream, {
+	comparePK: (a, b) => /* compare primary keys */,
+	extractPK: (row) => /* extract PK from row */,
+});
+```
+
+See the [design document](https://github.com/gotchoices/quereus/blob/main/packages/quereus/docs/design-isolation-layer.md) for detailed architecture and implementation notes.
+
+## Use Cases
+
+### Store Module Isolation
+
+The `@quereus/store` package provides a convenience function:
+
+```typescript
+import { createIsolatedStoreModule } from '@quereus/store';
+import { createLevelDBProvider } from '@quereus/plugin-leveldb';
+
+const provider = createLevelDBProvider({ basePath: './data' });
+const module = createIsolatedStoreModule({ provider });
+
+db.registerModule('store', module);
+```
+
+### Custom Module Isolation
+
+Wrap any custom module:
+
+```typescript
+import { IsolationModule } from '@quereus/isolation';
+import { MyCustomModule } from './my-module';
+
+const isolatedModule = new IsolationModule({
+	underlying: new MyCustomModule(),
+});
+```
+
+## Checking Capabilities
+
+```typescript
+const caps = isolatedModule.getCapabilities();
+console.log(caps.isolation);  // true
+console.log(caps.savepoints); // true
+console.log(caps.persistent); // (from underlying module)
+```
+
+## Performance
+
+The isolation layer adds minimal overhead:
+
+- **Fast path** — No overlay merging if no writes have occurred
+- **Point lookups** — O(log n) overlay check + underlying lookup
+- **Range scans** — Streaming merge of sorted results
+
+For performance-critical applications, consider:
+- Using memory overlay for small transactions
+- The memory vtab uses integrated isolation (no separate layer)
+
+## Testing
+
+```bash
+yarn test
+```
+
+## License
+
+MIT
+
+## Related Packages
+
+- [@quereus/quereus](https://www.npmjs.com/package/@quereus/quereus) — Core SQL engine
+- [@quereus/store](https://www.npmjs.com/package/@quereus/store) — Abstract key-value storage
+- [@quereus/plugin-leveldb](https://www.npmjs.com/package/@quereus/plugin-leveldb) — LevelDB storage
+- [@quereus/plugin-indexeddb](https://www.npmjs.com/package/@quereus/plugin-indexeddb) — IndexedDB storage

package/dist/src/index.d.ts

@@ -0,0 +1,8 @@
+export type { MergeEntry, MergeConfig, PKComparator, PKExtractor, SortKeyComparator, SortKeyExtractor } from './merge-types.js';
+export { mergeStreams, createMergeEntry, createTombstone } from './merge-iterator.js';
+export type { IsolationModuleConfig } from './isolation-types.js';
+export type { UnderlyingTableState } from './isolation-module.js';
+export { IsolationModule } from './isolation-module.js';
+export { IsolatedTable } from './isolated-table.js';
+export { IsolatedConnection } from './isolated-connection.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AACA,YAAY,EAAE,UAAU,EAAE,WAAW,EAAE,YAAY,EAAE,WAAW,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAChI,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAGtF,YAAY,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAClE,YAAY,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAGlE,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC"}

package/dist/src/index.js

@@ -0,0 +1,6 @@
+export { mergeStreams, createMergeEntry, createTombstone } from './merge-iterator.js';
+// Isolation layer classes
+export { IsolationModule } from './isolation-module.js';
+export { IsolatedTable } from './isolated-table.js';
+export { IsolatedConnection } from './isolated-connection.js';
+//# sourceMappingURL=index.js.map

package/dist/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAMtF,0BAA0B;AAC1B,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC"}

package/dist/src/isolated-connection.d.ts

@@ -0,0 +1,32 @@
+import type { VirtualTableConnection } from '@quereus/quereus';
+/**
+ * Callback interface for IsolatedTable to receive transaction events.
+ */
+export interface IsolatedTableCallback {
+    onConnectionCommit(): Promise<void>;
+    onConnectionRollback(): Promise<void>;
+    onConnectionSavepoint(index: number): Promise<void>;
+    onConnectionReleaseSavepoint(index: number): Promise<void>;
+    onConnectionRollbackToSavepoint(index: number): Promise<void>;
+}
+/**
+ * Connection wrapper that coordinates transactions across overlay and underlying.
+ * When commit/rollback are called by the database, this connection calls back
+ * to the IsolatedTable to perform flush/clear operations.
+ */
+export declare class IsolatedConnection implements VirtualTableConnection {
+    readonly connectionId: string;
+    readonly tableName: string;
+    private readonly underlyingConnection;
+    private readonly overlayConnection;
+    private readonly tableCallback;
+    constructor(tableName: string, underlyingConnection: VirtualTableConnection | undefined, overlayConnection: VirtualTableConnection | undefined, tableCallback?: IsolatedTableCallback);
+    begin(): Promise<void>;
+    commit(): Promise<void>;
+    rollback(): Promise<void>;
+    createSavepoint(index: number): Promise<void>;
+    releaseSavepoint(index: number): Promise<void>;
+    rollbackToSavepoint(index: number): Promise<void>;
+    disconnect(): Promise<void>;
+}
+//# sourceMappingURL=isolated-connection.d.ts.map

package/dist/src/isolated-connection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"isolated-connection.d.ts","sourceRoot":"","sources":["../../src/isolated-connection.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAK/D;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACrC,kBAAkB,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACpC,oBAAoB,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACtC,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpD,4BAA4B,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3D,+BAA+B,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9D;AAED;;;;GAIG;AACH,qBAAa,kBAAmB,YAAW,sBAAsB;IAChE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAE3B,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAqC;IAC1E,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAqC;IACvE,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAoC;gBAGjE,SAAS,EAAE,MAAM,EACjB,oBAAoB,EAAE,sBAAsB,GAAG,SAAS,EACxD,iBAAiB,EAAE,sBAAsB,GAAG,SAAS,EACrD,aAAa,CAAC,EAAE,qBAAqB;IAShC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAKtB,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAUvB,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAazB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQ7C,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQ9C,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQjD,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;CAIjC"}

package/dist/src/isolated-connection.js

@@ -0,0 +1,71 @@
+let connectionIdCounter = 0;
+/**
+ * Connection wrapper that coordinates transactions across overlay and underlying.
+ * When commit/rollback are called by the database, this connection calls back
+ * to the IsolatedTable to perform flush/clear operations.
+ */
+export class IsolatedConnection {
+    connectionId;
+    tableName;
+    underlyingConnection;
+    overlayConnection;
+    tableCallback;
+    constructor(tableName, underlyingConnection, overlayConnection, tableCallback) {
+        this.connectionId = `isolated-${++connectionIdCounter}`;
+        this.tableName = tableName;
+        this.underlyingConnection = underlyingConnection;
+        this.overlayConnection = overlayConnection;
+        this.tableCallback = tableCallback;
+    }
+    async begin() {
+        await this.underlyingConnection?.begin();
+        await this.overlayConnection?.begin();
+    }
+    async commit() {
+        // Call table's commit logic (flush overlay to underlying)
+        if (this.tableCallback) {
+            await this.tableCallback.onConnectionCommit();
+        }
+        // Then commit the underlying connections
+        await this.overlayConnection?.commit();
+        await this.underlyingConnection?.commit();
+    }
+    async rollback() {
+        // Call table's rollback logic (clear overlay)
+        if (this.tableCallback) {
+            await this.tableCallback.onConnectionRollback();
+        }
+        // Only rollback the overlay - the underlying table should NOT be rolled back
+        // because it only contains committed data (flushed during commit)
+        await this.overlayConnection?.rollback();
+        // Note: We intentionally do NOT rollback underlyingConnection here.
+        // The underlying table only receives writes during commit flush,
+        // and those writes should be committed, not rolled back.
+    }
+    async createSavepoint(index) {
+        if (this.tableCallback) {
+            await this.tableCallback.onConnectionSavepoint(index);
+        }
+        await this.underlyingConnection?.createSavepoint(index);
+        await this.overlayConnection?.createSavepoint(index);
+    }
+    async releaseSavepoint(index) {
+        if (this.tableCallback) {
+            await this.tableCallback.onConnectionReleaseSavepoint(index);
+        }
+        await this.underlyingConnection?.releaseSavepoint(index);
+        await this.overlayConnection?.releaseSavepoint(index);
+    }
+    async rollbackToSavepoint(index) {
+        if (this.tableCallback) {
+            await this.tableCallback.onConnectionRollbackToSavepoint(index);
+        }
+        await this.overlayConnection?.rollbackToSavepoint(index);
+        await this.underlyingConnection?.rollbackToSavepoint(index);
+    }
+    async disconnect() {
+        await this.overlayConnection?.disconnect();
+        await this.underlyingConnection?.disconnect();
+    }
+}
+//# sourceMappingURL=isolated-connection.js.map

package/dist/src/isolated-connection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"isolated-connection.js","sourceRoot":"","sources":["../../src/isolated-connection.ts"],"names":[],"mappings":"AAGA,IAAI,mBAAmB,GAAG,CAAC,CAAC;AAa5B;;;;GAIG;AACH,MAAM,OAAO,kBAAkB;IACrB,YAAY,CAAS;IACrB,SAAS,CAAS;IAEV,oBAAoB,CAAqC;IACzD,iBAAiB,CAAqC;IACtD,aAAa,CAAoC;IAElE,YACC,SAAiB,EACjB,oBAAwD,EACxD,iBAAqD,EACrD,aAAqC;QAErC,IAAI,CAAC,YAAY,GAAG,YAAY,EAAE,mBAAmB,EAAE,CAAC;QACxD,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;QAC3B,IAAI,CAAC,oBAAoB,GAAG,oBAAoB,CAAC;QACjD,IAAI,CAAC,iBAAiB,GAAG,iBAAiB,CAAC;QAC3C,IAAI,CAAC,aAAa,GAAG,aAAa,CAAC;IACpC,CAAC;IAED,KAAK,CAAC,KAAK;QACV,MAAM,IAAI,CAAC,oBAAoB,EAAE,KAAK,EAAE,CAAC;QACzC,MAAM,IAAI,CAAC,iBAAiB,EAAE,KAAK,EAAE,CAAC;IACvC,CAAC;IAED,KAAK,CAAC,MAAM;QACX,0DAA0D;QAC1D,IAAI,IAAI,CAAC,aAAa,EAAE,CAAC;YACxB,MAAM,IAAI,CAAC,aAAa,CAAC,kBAAkB,EAAE,CAAC;QAC/C,CAAC;QACD,yCAAyC;QACzC,MAAM,IAAI,CAAC,iBAAiB,EAAE,MAAM,EAAE,CAAC;QACvC,MAAM,IAAI,CAAC,oBAAoB,EAAE,MAAM,EAAE,CAAC;IAC3C,CAAC;IAED,KAAK,CAAC,QAAQ;QACb,8CAA8C;QAC9C,IAAI,IAAI,CAAC,aAAa,EAAE,CAAC;YACxB,MAAM,IAAI,CAAC,aAAa,CAAC,oBAAoB,EAAE,CAAC;QACjD,CAAC;QACD,6EAA6E;QAC7E,kEAAkE;QAClE,MAAM,IAAI,CAAC,iBAAiB,EAAE,QAAQ,EAAE,CAAC;QACzC,oEAAoE;QACpE,iEAAiE;QACjE,yDAAyD;IAC1D,CAAC;IAED,KAAK,CAAC,eAAe,CAAC,KAAa;QAClC,IAAI,IAAI,CAAC,aAAa,EAAE,CAAC;YACxB,MAAM,IAAI,CAAC,aAAa,CAAC,qBAAqB,CAAC,KAAK,CAAC,CAAC;QACvD,CAAC;QACD,MAAM,IAAI,CAAC,oBAAoB,EAAE,eAAe,CAAC,KAAK,CAAC,CAAC;QACxD,MAAM,IAAI,CAAC,iBAAiB,EAAE,eAAe,CAAC,KAAK,CAAC,CAAC;IACtD,CAAC;IAED,KAAK,CAAC,gBAAgB,CAAC,KAAa;QACnC,IAAI,IAAI,CAAC,aAAa,EAAE,CAAC;YACxB,MAAM,IAAI,CAAC,aAAa,CAAC,4BAA4B,CAAC,KAAK,CAAC,CAAC;QAC9D,CAAC;QACD,MAAM,IAAI,CAAC,oBAAoB,EAAE,gBAAgB,CAAC,KAAK,CAAC,CAAC;QACzD,MAAM,IAAI,CAAC,iBAAiB,EAAE,gBAAgB,CAAC,KAAK,CAAC,CAAC;IACvD,CAAC;IAED,KAAK,CAAC,mBAAmB,CAAC,KAAa;QACtC,IAAI,IAAI,CAAC,aAAa,EAAE,CAAC;YACxB,MAAM,IAAI,CAAC,aAAa,CAAC,+BAA+B,CAAC,KAAK,CAAC,CAAC;QACjE,CAAC;QACD,MAAM,IAAI,CAAC,iBAAiB,EAAE,mBAAmB,CAAC,KAAK,CAAC,CAAC;QACzD,MAAM,IAAI,CAAC,oBAAoB,EAAE,mBAAmB,CAAC,KAAK,CAAC,CAAC;IAC7D,CAAC;IAED,KAAK,CAAC,UAAU;QACf,MAAM,IAAI,CAAC,iBAAiB,EAAE,UAAU,EAAE,CAAC;QAC3C,MAAM,IAAI,CAAC,oBAAoB,EAAE,UAAU,EAAE,CAAC;IAC/C,CAAC;CACD"}

package/dist/src/isolated-table.d.ts

@@ -0,0 +1,219 @@
+import type { Database, MaybePromise, Row, TableIndexSchema as IndexSchema, FilterInfo, SchemaChangeInfo, UpdateArgs, VirtualTableConnection } from '@quereus/quereus';
+import { VirtualTable } from '@quereus/quereus';
+import type { IsolationModule } from './isolation-module.js';
+import { type IsolatedTableCallback } from './isolated-connection.js';
+/**
+ * A table wrapper that provides transaction isolation via an overlay.
+ *
+ * Each IsolatedTable instance accesses a connection-scoped overlay that is:
+ * - Created lazily on first write
+ * - Shared across all IsolatedTable instances in the same transaction
+ * - Stored in the IsolationModule's connection overlay map
+ *
+ * This provides true per-connection isolation - each connection's uncommitted
+ * changes are invisible to other connections, but visible to all queries
+ * within the same connection.
+ *
+ * Reads merge overlay changes with underlying data.
+ * Writes go to overlay only until commit.
+ */
+export declare class IsolatedTable extends VirtualTable implements IsolatedTableCallback {
+    private readonly isolationModule;
+    private readonly underlyingTable;
+    private registeredConnection;
+    constructor(db: Database, module: IsolationModule, underlyingTable: VirtualTable);
+    /**
+     * Gets the tombstone column name from the module.
+     */
+    private get tombstoneColumn();
+    /**
+     * Gets the connection-scoped overlay state, or undefined if no overlay exists yet.
+     */
+    private getOverlayState;
+    /**
+     * Gets the overlay table, or undefined if no overlay exists yet.
+     */
+    private get overlayTable();
+    /**
+     * Gets whether this connection has uncommitted changes.
+     */
+    private get hasChanges();
+    /**
+     * Sets the hasChanges flag in the connection-scoped overlay state.
+     */
+    private setHasChanges;
+    /**
+     * Lazily creates the overlay table on first write.
+     *
+     * The overlay is stored in connection-scoped storage, so it persists
+     * across multiple IsolatedTable instances within the same transaction.
+     *
+     * The schema is obtained from the underlying table at this point,
+     * supporting scenarios where schema is discovered lazily from storage.
+     */
+    private ensureOverlay;
+    /**
+     * Ensures a connection is registered with the database for transaction coordination.
+     * This is called before any read or write operation.
+     */
+    private ensureConnection;
+    /**
+     * Creates a new isolated connection for transaction support.
+     */
+    createConnection(): MaybePromise<VirtualTableConnection>;
+    private createConnectionAsync;
+    /**
+     * Query the table, merging overlay with underlying.
+     *
+     * When overlay is empty or doesn't exist, delegates directly to underlying for efficiency.
+     * When overlay has changes, merges both streams using the appropriate key order.
+     *
+     * For primary key scans: merge by PK order
+     * For secondary index scans: merge by (indexKey, PK) order
+     */
+    query(filterInfo: FilterInfo): AsyncIterable<Row>;
+    /**
+     * Wrapper that ensures connection before merging.
+     */
+    private mergedQueryWithConnection;
+    /**
+     * Performs merged query combining overlay and underlying data.
+     *
+     * Both overlay and underlying are queried with the same FilterInfo (for the overlay,
+     * adjusted for its schema with tombstone column). Both streams return rows in the
+     * same order (by PK for primary scans, by index key for secondary index scans).
+     *
+     * The merge iterator combines them using the appropriate sort key comparator.
+     */
+    private mergedQuery;
+    /**
+     * Parses FilterInfo to determine which index is being used.
+     * Returns null for full table scan or primary key scan, index name for secondary indexes.
+     */
+    private parseIndexFromFilterInfo;
+    /**
+     * Gets the column indices for a secondary index.
+     */
+    private getIndexColumnIndices;
+    /**
+     * Adapts FilterInfo for the overlay table schema (which has an extra tombstone column).
+     * The constraints and index references remain the same since the overlay has matching indexes.
+     */
+    private adaptFilterInfoForOverlay;
+    /**
+     * Queries the overlay table and converts rows to MergeEntry format.
+     *
+     * Uses the same FilterInfo as the underlying query so both streams are in the same order.
+     * For secondary index scans, the sort key includes both the index key and primary key.
+     */
+    private queryOverlayAsMergeEntries;
+    /**
+     * Builds the sort key for a row based on the index being scanned.
+     *
+     * For primary key scans: sort key is the PK
+     * For secondary index scans: sort key is [indexKeyParts..., pkParts...]
+     */
+    private buildSortKey;
+    /**
+     * Builds the merge configuration using this table's key functions.
+     *
+     * For primary key scans: compare by PK
+     * For secondary index scans: compare by (indexKey, PK) using underlying's comparator
+     *
+     * @param indexInfo Which index is being scanned. Defaults to primary key scan.
+     */
+    private buildMergeConfig;
+    /**
+     * Gets the primary key comparator, preferring the underlying table's comparator.
+     */
+    private getComparePK;
+    /**
+     * Builds a sort key comparator for secondary index scans.
+     *
+     * Compares by index key columns first, then by PK columns.
+     */
+    private buildCompareSortKey;
+    /**
+     * Gets the index of the tombstone column in overlay rows.
+     */
+    private getTombstoneColumnIndex;
+    /**
+     * Gets the primary key column indices from the underlying table schema.
+     */
+    getPrimaryKeyIndices(): number[];
+    /**
+     * Performs INSERT, UPDATE, or DELETE on the overlay.
+     * Changes are not visible to underlying until commit.
+     *
+     * The overlay is created lazily on first write, using schema from the underlying table.
+     */
+    update(args: UpdateArgs): Promise<Row | undefined>;
+    /**
+     * Checks if a row with the given primary key exists in the overlay.
+     */
+    private rowExistsInOverlay;
+    /**
+     * Gets a row from the overlay by primary key.
+     */
+    private getOverlayRow;
+    /**
+     * Creates a FilterInfo for a full table scan (no constraints).
+     */
+    private createFullScanFilterInfo;
+    begin(): Promise<void>;
+    sync(): Promise<void>;
+    commit(): Promise<void>;
+    /**
+     * Flushes all overlay changes to the underlying table.
+     * Called during commit to persist changes.
+     *
+     * This method manages the underlying table's transaction lifecycle independently
+     * to ensure that flushed data is committed and won't be rolled back by subsequent
+     * transaction rollbacks.
+     */
+    private flushOverlayToUnderlying;
+    /**
+     * Checks if a row with the given primary key exists in the underlying table.
+     */
+    private rowExistsInUnderlying;
+    rollback(): Promise<void>;
+    /**
+     * Clears the connection-scoped overlay and resets state.
+     */
+    private clearOverlay;
+    savepoint(index: number): Promise<void>;
+    release(index: number): Promise<void>;
+    rollbackTo(index: number): Promise<void>;
+    disconnect(): Promise<void>;
+    rename(newName: string): Promise<void>;
+    alterSchema(changeInfo: SchemaChangeInfo): Promise<void>;
+    createIndex(indexInfo: IndexSchema): Promise<void>;
+    dropIndex(indexName: string): Promise<void>;
+    /**
+     * Returns whether there are pending uncommitted changes.
+     */
+    hasPendingChanges(): boolean;
+    /**
+     * Called by IsolatedConnection when the database commits.
+     * Flushes overlay to underlying and clears overlay.
+     */
+    onConnectionCommit(): Promise<void>;
+    /**
+     * Called by IsolatedConnection when the database rolls back.
+     * Clears overlay without flushing.
+     */
+    onConnectionRollback(): Promise<void>;
+    /**
+     * Called by IsolatedConnection when a savepoint is created.
+     */
+    onConnectionSavepoint(index: number): Promise<void>;
+    /**
+     * Called by IsolatedConnection when a savepoint is released.
+     */
+    onConnectionReleaseSavepoint(index: number): Promise<void>;
+    /**
+     * Called by IsolatedConnection when rolling back to a savepoint.
+     */
+    onConnectionRollbackToSavepoint(index: number): Promise<void>;
+}
+//# sourceMappingURL=isolated-table.d.ts.map

package/dist/src/isolated-table.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"isolated-table.d.ts","sourceRoot":"","sources":["../../src/isolated-table.ts"],"names":[],"mappings":"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"}