@quereus/quereus 0.1.0

package/src/vtab/index-info.ts

@@ -0,0 +1,84 @@
+import { IndexConstraintOp } from '../common/constants.js';
+
+/**
+ * Information about a specific constraint in the WHERE clause
+ */
+export interface IndexConstraint {
+	/** Column index constrained (0 based) */
+	iColumn: number;
+	/** Constraint operator (EQ, GT, etc.) */
+	op: IndexConstraintOp;
+	/** True if the constraint expression is usable */
+	usable: boolean;
+	/** Internal offset used by Quereus - ignore in xBestIndex */
+	iTermOffset?: number;
+}
+
+/**
+ * Information about a term in the ORDER BY clause
+ */
+export interface IndexOrderBy {
+	/** Column index */
+	iColumn: number;
+	/** True for DESC, False for ASC */
+	desc: boolean;
+}
+
+/**
+ * Usage information for a constraint, filled by xBestIndex
+ */
+export interface IndexConstraintUsage {
+	/** If >0, constraint value becomes the (argvIndex-1)-th arg to xFilter */
+	argvIndex: number;
+	/** If true, Quereus might skip re-checking this constraint */
+	omit: boolean;
+}
+
+/**
+ * Structure passed to xBestIndex method containing information about
+ * WHERE and ORDER BY clauses relevant to the virtual table.
+ * The xBestIndex method must fill the output fields to describe the chosen query plan.
+ */
+export interface IndexInfo {
+	// --- Inputs ---
+
+	/** Number of entries in aConstraint */
+	nConstraint: number;
+	/** Array of WHERE clause constraints */
+	aConstraint: ReadonlyArray<IndexConstraint>;
+
+	/** Number of terms in the ORDER BY clause */
+	nOrderBy: number;
+	/** Array of ORDER BY terms */
+	aOrderBy: ReadonlyArray<IndexOrderBy>;
+
+	/** Mask of columns used by the statement (bit N set if column N is used) */
+	colUsed: bigint;
+
+	// --- Outputs ---
+
+	/** Usage details for each constraint */
+	aConstraintUsage: IndexConstraintUsage[];
+
+	/** Number identifying the chosen index strategy (passed to xFilter) */
+	idxNum: number;
+	/** String identifying the chosen index strategy (passed to xFilter) */
+	idxStr: string | null;
+
+	/** True if output from xFilter/xNext will satisfy ORDER BY */
+	orderByConsumed: boolean;
+
+	/** Estimated cost of this strategy (lower is better) */
+	estimatedCost: number;
+	/** Estimated number of rows returned by this strategy */
+	estimatedRows: bigint;
+
+	/** Mask of SQLITE_INDEX_SCAN_* flags */
+	idxFlags: number;
+}
+
+/** Flags for IndexInfo.idxFlags */
+export enum IndexScanFlags {
+	/** Scan visits at most 1 row */
+	UNIQUE = 0x0001,
+}

package/src/vtab/manifest.ts

@@ -0,0 +1,37 @@
+import type { SqlValue } from '../common/types.js';
+
+/**
+ * Configuration setting definition for a plugin
+ */
+export interface PluginSetting {
+	key: string;                    // "path"
+	label: string;                  // "JSON Path"
+	type: 'string' | 'number' | 'boolean' | 'select';
+	default?: SqlValue;
+	options?: SqlValue[];           // for select type
+	help?: string;
+}
+
+/**
+ * Plugin manifest that describes the plugin's metadata and configuration options
+ */
+export interface PluginManifest {
+	name: string;                   // "JSON_TABLE"
+	version: string;                // "1.0.0"
+	author?: string;
+	description?: string;
+	pragmaPrefix?: string;          // default = name, used for PRAGMA commands
+	settings?: PluginSetting[];     // configuration options
+	capabilities?: string[];        // e.g. ['scan', 'index', 'write']
+}
+
+/**
+ * Plugin record used for persistence across sessions
+ */
+export interface PluginRecord {
+	id: string;                     // UUID for this installation
+	url: string;                    // Full URL to the ES module
+	enabled: boolean;               // Whether to load at startup
+	manifest?: PluginManifest;      // Cached after first successful load
+	config: Record<string, SqlValue>; // User-configured values
+}

package/src/vtab/memory/connection.ts

@@ -0,0 +1,73 @@
+import type { VirtualTableConnection } from '../connection.js';
+import type { MemoryTableConnection } from './layer/connection.js';
+import { createLogger } from '../../common/logger.js';
+
+const log = createLogger('vtab:memory:vtab-connection');
+
+/**
+ * VirtualTableConnection implementation for memory tables.
+ * Wraps the existing MemoryTableConnection to provide the generic interface.
+ */
+export class MemoryVirtualTableConnection implements VirtualTableConnection {
+	public readonly connectionId: string;
+	public readonly tableName: string;
+	private memoryConnection: MemoryTableConnection;
+
+	constructor(tableName: string, memoryConnection: MemoryTableConnection) {
+		this.connectionId = `memory-${tableName}-${memoryConnection.connectionId}`;
+		this.tableName = tableName;
+		this.memoryConnection = memoryConnection;
+	}
+
+	/** Begins a transaction on this connection */
+	begin(): void {
+		log(`BEGIN transaction on connection ${this.connectionId}`);
+		this.memoryConnection.begin();
+	}
+
+	/** Commits the current transaction */
+	async commit(): Promise<void> {
+		log(`COMMIT transaction on connection ${this.connectionId}`);
+		await this.memoryConnection.commit();
+	}
+
+	/** Rolls back the current transaction */
+	rollback(): void {
+		log(`ROLLBACK transaction on connection ${this.connectionId}`);
+		this.memoryConnection.rollback();
+	}
+
+	/** Creates a savepoint with the given index */
+	createSavepoint(index: number): void {
+		log(`CREATE SAVEPOINT ${index} on connection ${this.connectionId}`);
+		this.memoryConnection.createSavepoint(index);
+	}
+
+	/** Releases a savepoint with the given index */
+	releaseSavepoint(index: number): void {
+		log(`RELEASE SAVEPOINT ${index} on connection ${this.connectionId}`);
+		this.memoryConnection.releaseSavepoint(index);
+	}
+
+	/** Rolls back to a savepoint with the given index */
+	rollbackToSavepoint(index: number): void {
+		log(`ROLLBACK TO SAVEPOINT ${index} on connection ${this.connectionId}`);
+		this.memoryConnection.rollbackToSavepoint(index);
+	}
+
+	/** Disconnects and cleans up this connection */
+	async disconnect(): Promise<void> {
+		log(`DISCONNECT connection ${this.connectionId}`);
+		// The MemoryTableConnection doesn't have a disconnect method,
+		// but we can clear any pending transaction state
+		if (this.memoryConnection.pendingTransactionLayer) {
+			log(`Rolling back pending transaction on disconnect for ${this.connectionId}`);
+			this.memoryConnection.rollback();
+		}
+	}
+
+	/** Gets the underlying MemoryTableConnection for internal use */
+	getMemoryConnection(): MemoryTableConnection {
+		return this.memoryConnection;
+	}
+}

package/src/vtab/memory/index.ts

@@ -0,0 +1,178 @@
+import { BTree } from 'inheritree';
+import { StatusCode, type Row, type SqlValue } from '../../common/types.js';
+import { compareSqlValues } from '../../util/comparison.js';
+import type { BTreeKeyForPrimary, BTreeKeyForIndex, MemoryIndexEntry } from './types.js';
+import type { IndexColumnSchema as IndexColumnSpec } from '../../schema/table.js'; // Renamed for clarity
+import type { ColumnSchema } from '../../schema/column.js';
+import { quereusError } from '../../common/errors.js';
+
+/** Definition for creating a memory index (matches IndexSchema columns usually) */
+export interface IndexSpec {
+	name?: string;
+	columns: ReadonlyArray<IndexColumnSpec>;
+}
+
+/** Functions for extracting and comparing index keys */
+interface IndexKeyFunctions {
+	keyFromRow: (row: Row) => BTreeKeyForIndex;
+	compareKeys: (a: BTreeKeyForIndex, b: BTreeKeyForIndex) => number;
+}
+
+/** Represents a secondary index within a MemoryTable */
+export class MemoryIndex {
+	public readonly name: string | undefined;
+	public readonly specColumns: ReadonlyArray<IndexColumnSpec>;
+	public readonly keyFromRow: (row: Row) => BTreeKeyForIndex;
+	public readonly compareKeys: (a: BTreeKeyForIndex, b: BTreeKeyForIndex) => number;
+	public data: BTree<BTreeKeyForIndex, MemoryIndexEntry>;
+
+	constructor(spec: IndexSpec, allTableColumnsSchema: ReadonlyArray<ColumnSchema>, baseInheritreeTable?: BTree<BTreeKeyForIndex, MemoryIndexEntry>) {
+		this.name = spec.name;
+		this.specColumns = Object.freeze(spec.columns.map(c => ({ ...c })));
+
+		this.validateColumnIndexes(allTableColumnsSchema);
+
+		const keyFunctions = this.createIndexKeyFunctions();
+		this.keyFromRow = keyFunctions.keyFromRow;
+		this.compareKeys = keyFunctions.compareKeys;
+
+		this.data = this.createBTree(baseInheritreeTable);
+	}
+
+	private validateColumnIndexes(allTableColumnsSchema: ReadonlyArray<ColumnSchema>): void {
+		const hasInvalidIndex = this.specColumns.some(sc =>
+			sc.index < 0 || sc.index >= allTableColumnsSchema.length
+		);
+
+		if (hasInvalidIndex) {
+			quereusError(`Invalid column index in index '${this.name ?? '(unnamed)'}'.`, StatusCode.INTERNAL);
+		}
+	}
+
+	private createIndexKeyFunctions(): IndexKeyFunctions {
+		if (this.specColumns.length === 1) {
+			return this.createSingleColumnKeyFunctions();
+		} else {
+			return this.createCompositeColumnKeyFunctions();
+		}
+	}
+
+	private createSingleColumnKeyFunctions(): IndexKeyFunctions {
+		const specCol = this.specColumns[0];
+		const colSchemaIndex = specCol.index;
+		const collation = specCol.collation || 'BINARY';
+		const descMultiplier = specCol.desc ? -1 : 1;
+
+		const keyFromRow = (row: Row): BTreeKeyForIndex => {
+			this.validateRowLength(row, colSchemaIndex);
+			return row[colSchemaIndex];
+		};
+
+		const compareKeys = (a: BTreeKeyForIndex, b: BTreeKeyForIndex): number => {
+			return compareSqlValues(a as SqlValue, b as SqlValue, collation) * descMultiplier;
+		};
+
+		return { keyFromRow, compareKeys };
+	}
+
+	private createCompositeColumnKeyFunctions(): IndexKeyFunctions {
+		const localSpecColumns = this.specColumns;
+
+		const keyFromRow = (row: Row): BTreeKeyForIndex => {
+			return localSpecColumns.map(sc => {
+				this.validateRowLength(row, sc.index);
+				return row[sc.index];
+			});
+		};
+
+		const compareKeys = (a: BTreeKeyForIndex, b: BTreeKeyForIndex): number => {
+			const arrA = a as SqlValue[];
+			const arrB = b as SqlValue[];
+
+			for (let i = 0; i < localSpecColumns.length; i++) {
+				if (i >= arrA.length || i >= arrB.length) {
+					return arrA.length - arrB.length;
+				}
+
+				const specCol = localSpecColumns[i];
+				const comparison = compareSqlValues(arrA[i], arrB[i], specCol.collation || 'BINARY');
+
+				if (comparison !== 0) {
+					return specCol.desc ? -comparison : comparison;
+				}
+			}
+			return 0;
+		};
+
+		return { keyFromRow, compareKeys };
+	}
+
+	private validateRowLength(row: Row, columnIndex: number): void {
+		if (columnIndex < 0 || columnIndex >= row.length) {
+			quereusError(`Index key col index ${columnIndex} OOB for row len ${row.length}`, StatusCode.INTERNAL);
+		}
+	}
+
+	private createBTree(baseInheritreeTable?: BTree<BTreeKeyForIndex, MemoryIndexEntry>): BTree<BTreeKeyForIndex, MemoryIndexEntry> {
+		return new BTree<BTreeKeyForIndex, MemoryIndexEntry>(
+			(entry: MemoryIndexEntry) => entry.indexKey,
+			this.compareKeys,
+			baseInheritreeTable
+		);
+	}
+
+	/** Adds a mapping from index key to primary key */
+	addEntry(indexKey: BTreeKeyForIndex, primaryKey: BTreeKeyForPrimary): void {
+		const path = this.data.find(indexKey);
+		if (path.on) {
+			// Entry exists, add to the existing set of primary keys
+			const existingEntry = this.data.at(path)!;
+			existingEntry.primaryKeys.add(primaryKey);
+		} else {
+			// Create new entry with a Set containing the primary key
+			const newEntry: MemoryIndexEntry = {
+				indexKey,
+				primaryKeys: new Set([primaryKey])
+			};
+			this.data.insert(newEntry);
+		}
+	}
+
+	/** Removes a mapping from index key to primary key */
+	removeEntry(indexKey: BTreeKeyForIndex, primaryKey: BTreeKeyForPrimary): void {
+		const path = this.data.find(indexKey);
+		if (path.on) {
+			const entry = this.data.at(path)!;
+			entry.primaryKeys.delete(primaryKey);
+
+			// If no primary keys remain, remove the entire entry
+			if (entry.primaryKeys.size === 0) {
+				this.data.deleteAt(path);
+			}
+		}
+	}
+
+	/** Returns the primary keys for a given index key */
+	getPrimaryKeys(indexKey: BTreeKeyForIndex): BTreeKeyForPrimary[] {
+		const entry = this.data.get(indexKey);
+		return entry ? Array.from(entry.primaryKeys) : [];
+	}
+
+	/** Gets the count of unique index values */
+	get size(): number {
+		return this.data.getCount();
+	}
+
+	/** Clears all entries from the index */
+	clear(): void {
+		const base = (this.data as any).baseTable as BTree<BTreeKeyForIndex, MemoryIndexEntry> | undefined;
+		this.data = this.createBTree(base);
+	}
+
+	/** Clears the base inheritance for this index (used during layer collapse) */
+	clearBase(): void {
+		if (typeof (this.data as any).clearBase === 'function') {
+			(this.data as any).clearBase();
+		}
+	}
+}

package/src/vtab/memory/layer/base-cursor.ts

@@ -0,0 +1,124 @@
+import type { ScanPlan } from './scan-plan.js';
+import type { BaseLayer } from './base.js';
+import type { BTreeKey, BTreeKeyForPrimary, BTreeKeyForIndex } from '../types.js';
+import { IndexConstraintOp } from '../../../common/constants.js';
+import { compareSqlValues } from '../../../util/comparison.js';
+import { StatusCode, type Row } from '../../../common/types.js';
+import { safeIterate } from './safe-iterate.js';
+import { QuereusError } from '../../../common/errors.js';
+
+export async function* scanBaseLayer(
+	layer: BaseLayer,
+	plan: ScanPlan
+): AsyncIterable<Row> {
+	const { primaryKeyExtractorFromRow: keyFromEntry, primaryKeyComparator } = layer.getPkExtractorsAndComparators(layer.getSchema());
+	const isEqPlan = plan.equalityKey !== undefined;
+
+	const planAppliesToKey = (key: BTreeKey, keyIsIndexKey: boolean): boolean => {
+		const comparator = keyIsIndexKey
+			? layer.secondaryIndexes.get(plan.indexName)?.compareKeys
+			: primaryKeyComparator;
+		if (!comparator) return true;
+
+		if (plan.equalityKey !== undefined) return comparator(key, plan.equalityKey) === 0;
+
+		const keyForBoundComparison = Array.isArray(key) ? key[0] : key;
+		if (plan.lowerBound && (keyForBoundComparison !== undefined && keyForBoundComparison !== null)) {
+			const cmp = compareSqlValues(keyForBoundComparison, plan.lowerBound.value);
+			if (cmp < 0 || (cmp === 0 && plan.lowerBound.op === IndexConstraintOp.GT)) return false;
+		}
+		if (plan.upperBound && (keyForBoundComparison !== undefined && keyForBoundComparison !== null)) {
+			const cmp = compareSqlValues(keyForBoundComparison, plan.upperBound.value);
+			if (cmp > 0 || (cmp === 0 && plan.upperBound.op === IndexConstraintOp.LT)) return false;
+		}
+		return true;
+	};
+
+	if (plan.indexName === 'primary') {
+		const tree = layer.primaryTree; // BTree<BTreeKeyForPrimary, PrimaryModificationValue> from inheritree
+
+		if (isEqPlan && plan.equalityKey !== undefined) {
+			const value = tree.get(plan.equalityKey as BTreeKeyForPrimary);
+			if (value && planAppliesToKey(plan.equalityKey as BTreeKeyForPrimary, false)) {
+				yield value as Row;
+			}
+			return;
+		}
+
+		// Determine start key for range scans
+		let startKey: { value: BTreeKeyForPrimary } | undefined;
+		if (plan.lowerBound) {
+			startKey = { value: plan.lowerBound.value as BTreeKeyForPrimary };
+		}
+
+		// Create mutation-safe iterator with range support
+		for await (const value of safeIterate(tree, !plan.descending, startKey)) {
+			const row = value as Row;
+			const primaryKey = keyFromEntry(row);
+			if (!planAppliesToKey(primaryKey, false)) {
+				// If we're doing an ascending scan and we've passed the upper bound, we can break early
+				if (!plan.descending && plan.upperBound) {
+					const keyForComparison = Array.isArray(primaryKey) ? primaryKey[0] : primaryKey;
+					const cmp = compareSqlValues(keyForComparison, plan.upperBound.value);
+					if (cmp > 0 || (cmp === 0 && plan.upperBound.op === IndexConstraintOp.LT)) {
+						break;
+					}
+				}
+				continue;
+			}
+			yield row;
+		}
+	} else { // Secondary Index Scan
+		const secondaryIndex = layer.secondaryIndexes.get(plan.indexName);
+		if (!secondaryIndex) throw new QuereusError(`Secondary index '${plan.indexName}' not found in BaseLayer.`, StatusCode.INTERNAL);
+
+		const indexTree = secondaryIndex.data; // BTree<BTreeKeyForIndex, MemoryIndexEntry> from inheritree
+
+		if (isEqPlan && plan.equalityKey !== undefined) {
+			const indexEntry = indexTree.get(plan.equalityKey as BTreeKeyForIndex);
+			if (indexEntry && planAppliesToKey(indexEntry.indexKey, true)) {
+				for (const pk of indexEntry.primaryKeys) {
+					const value = layer.primaryTree.get(pk);
+					if (value) {
+						yield value as Row;
+					}
+				}
+			}
+			return;
+		}
+
+		// Use mutation-safe iterator for secondary index iteration with range support
+		const isAscending = !plan.descending;
+
+		// Determine start key for range scans on secondary index
+		let startKey: { value: BTreeKeyForIndex } | undefined;
+		if (plan.lowerBound) {
+			startKey = { value: plan.lowerBound.value as BTreeKeyForIndex };
+		}
+
+		for await (const indexEntry of safeIterate(indexTree, isAscending, startKey)) {
+			if (!planAppliesToKey(indexEntry.indexKey, true)) {
+				// Early termination for ascending scans past upper bound
+				if (isAscending && plan.upperBound) {
+					const keyForComparison = Array.isArray(indexEntry.indexKey) ? indexEntry.indexKey[0] : indexEntry.indexKey;
+					const cmp = compareSqlValues(keyForComparison, plan.upperBound.value);
+					if (cmp > 0 || (cmp === 0 && plan.upperBound.op === IndexConstraintOp.LT)) {
+						break;
+					}
+				}
+				continue;
+			}
+			for (const pk of indexEntry.primaryKeys) {
+				const value = layer.primaryTree.get(pk);
+				if (value) {
+					yield value as Row;
+				}
+			}
+		}
+	}
+}
+
+// LayerCursorInternal interface is removed as this file now exports an async generator.
+// If TransactionLayerCursorInternal needs a common interface with this for its parentCursor,
+// that interface would describe an AsyncIterable<Row> with perhaps getCurrentPrimaryKey() if still needed.
+// For now, let parentCursor in TransactionLayerCursorInternal be AsyncIterable<Row>.