@quereus/quereus 0.1.0

package/src/util/patterns.ts

@@ -0,0 +1,56 @@
+import { createLogger } from '../common/logger.js';
+
+const log = createLogger('util:patterns');
+const errorLog = log.extend('error');
+
+/**
+ * Simple LIKE pattern matching implementation.
+ * Supports SQL LIKE patterns:
+ * - % matches any sequence of characters (including empty sequence)
+ * - _ matches any single character
+ *
+ * @param pattern The LIKE pattern
+ * @param text The text to match against
+ * @returns true if the text matches the pattern, false otherwise
+ */
+export function simpleLike(pattern: string, text: string): boolean {
+	// Escape regex special characters except % and _
+	const escapedPattern = pattern.replace(/[.*+^${}()|[\]\\]/g, '\\$&');
+	// Convert SQL LIKE wildcards to regex equivalents
+	const regexPattern = escapedPattern.replace(/%/g, '.*').replace(/_/g, '.');
+
+	try {
+		const regex = new RegExp(`^${regexPattern}$`);
+		return regex.test(text);
+	} catch (e) {
+		errorLog('Invalid LIKE pattern converted to regex: ^%s$, %O', regexPattern, e);
+		return false;
+	}
+}
+
+/**
+ * Simple GLOB pattern matching implementation.
+ * Supports SQL GLOB patterns:
+ * - * matches any sequence of characters (including empty sequence)
+ * - ? matches any single character
+ *
+ * @param pattern The GLOB pattern
+ * @param text The text to match against
+ * @returns true if the text matches the pattern, false otherwise
+ */
+export function simpleGlob(pattern: string, text: string): boolean {
+	// Escape regex special characters except * and ?
+	const escapedPattern = pattern.replace(/[.*+^${}()|[\]\\]/g, '\\$&');
+	// Convert SQL GLOB wildcards to regex equivalents
+	const regexPattern = escapedPattern
+		.replace(/\\\*/g, '.*')
+		.replace(/\\\?/g, '.');
+
+	try {
+		const regex = new RegExp(`^${regexPattern}$`);
+		return regex.test(text);
+	} catch (e) {
+		errorLog('Invalid GLOB pattern converted to regex: ^%s$, %O', regexPattern, e);
+		return false;
+	}
+}

package/src/util/plan-formatter.ts

@@ -0,0 +1,51 @@
+import type { ScalarPlanNode } from '../planner/nodes/plan-node.js';
+import { expressionToString } from './ast-stringify.js';
+import type { ScalarType } from '../common/datatype.js';
+import { SqlDataType } from '../common/types.js';
+
+/**
+ * Convert a ScalarPlanNode to its string representation for use in plan descriptions.
+ */
+export function formatExpression(node: ScalarPlanNode): string {
+	return expressionToString(node.expression);
+}
+
+/**
+ * Convert multiple ScalarPlanNodes to a comma-separated string.
+ */
+export function formatExpressionList(nodes: readonly ScalarPlanNode[]): string {
+	return nodes.map(formatExpression).join(', ');
+}
+
+/**
+ * Format a scalar type to a simple string representation.
+ */
+export function formatScalarType(type: ScalarType): string {
+	if (type.datatype !== undefined) {
+		return SqlDataType[type.datatype];
+	}
+	return SqlDataType[type.affinity];
+}
+
+/**
+ * Format projection for display (expression with optional alias).
+ */
+export function formatProjection(expr: ScalarPlanNode, alias?: string): string {
+	const exprStr = formatExpression(expr);
+	return alias && alias !== exprStr ? `${exprStr} AS ${alias}` : exprStr;
+}
+
+/**
+ * Format sort key for display.
+ */
+export function formatSortKey(
+	expr: ScalarPlanNode,
+	direction: 'asc' | 'desc',
+	nulls?: 'first' | 'last'
+): string {
+	const parts = [formatExpression(expr), direction.toUpperCase()];
+	if (nulls) {
+		parts.push(`NULLS ${nulls.toUpperCase()}`);
+	}
+	return parts.join(' ');
+}

package/src/util/plugin-loader.ts

@@ -0,0 +1,69 @@
+import type { Database } from '../core/database.js';
+import type { PluginManifest } from '../vtab/manifest.js';
+import { StatusCode, type SqlValue } from '../common/types.js';
+import { quereusError } from '../common/errors.js';
+
+/**
+ * Dynamically loads and registers a plugin module
+ *
+ * @param url The URL to the ES module (can be https:// or file:// URL)
+ * @param db The Database instance to register the module with
+ * @param config Configuration values to pass to the module
+ * @returns The plugin's manifest if available
+ */
+export async function dynamicLoadModule(
+	url: string,
+	db: Database,
+	config: Record<string, SqlValue> = {}
+): Promise<PluginManifest | undefined> {
+	try {
+		// Add cache-busting timestamp for development
+		const moduleUrl = new URL(url);
+		if (moduleUrl.protocol === 'file:' || moduleUrl.hostname === 'localhost') {
+			moduleUrl.searchParams.set('t', Date.now().toString());
+		}
+
+		// Dynamic import with Vite ignore comment for bundler compatibility
+		const mod = await import(/* @vite-ignore */ moduleUrl.toString());
+
+		// Validate module structure
+		if (typeof mod.default !== 'function') {
+			quereusError(`Module at ${url} has no default export function`, StatusCode.FORMAT);
+		}
+
+		// Call the module's register function with the database and config
+		await mod.default(db, config);
+
+		// Return the manifest if available
+		return mod.manifest as PluginManifest | undefined;
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		quereusError(`Failed to load plugin from ${url}: ${message}`);
+	}
+}
+
+/**
+ * Validates that a URL is likely to be a valid plugin module
+ *
+ * @param url The URL to validate
+ * @returns true if the URL appears valid
+ */
+export function validatePluginUrl(url: string): boolean {
+	try {
+		const parsed = new URL(url);
+
+		// Allow https:// and file:// protocols
+		if (!['https:', 'file:'].includes(parsed.protocol)) {
+			return false;
+		}
+
+		// Must end with .js or .mjs
+		if (!/\.(m?js)$/i.test(parsed.pathname)) {
+			return false;
+		}
+
+		return true;
+	} catch {
+		return false;
+	}
+}

package/src/util/row-descriptor.ts

@@ -0,0 +1,105 @@
+import type { RowDescriptor, Attribute } from '../planner/nodes/plan-node.js';
+import type { Row } from '../common/types.js';
+import { SqlDataType } from '../common/types.js';
+
+/**
+ * Utility to build a RowDescriptor (attributeId → columnIndex mapping)
+ * for any relational plan node.
+ */
+export function buildRowDescriptor(attributes: Attribute[]): RowDescriptor {
+  const descriptor: RowDescriptor = [];
+  attributes.forEach((attr, index) => {
+    descriptor[attr.id] = index;
+  });
+  return descriptor;
+}
+
+/**
+ * Creates OLD and NEW row descriptors for mutation operations.
+ * Returns descriptors where OLD columns are at indices 0..n-1 and NEW columns at n..2n-1
+ */
+export function buildOldNewRowDescriptors(
+	oldAttributes: Attribute[],
+	newAttributes: Attribute[]
+): {
+	oldRowDescriptor: RowDescriptor;
+	newRowDescriptor: RowDescriptor;
+	flatRowDescriptor: RowDescriptor;
+} {
+	const oldRowDescriptor: RowDescriptor = [];
+	const newRowDescriptor: RowDescriptor = [];
+	const flatRowDescriptor: RowDescriptor = [];
+
+	// OLD attributes occupy indices 0..n-1
+	oldAttributes.forEach((attr, index) => {
+		oldRowDescriptor[attr.id] = index;
+		flatRowDescriptor[attr.id] = index;
+	});
+
+	// NEW attributes occupy indices n..2n-1
+	newAttributes.forEach((attr, index) => {
+		const flatIndex = oldAttributes.length + index;
+		newRowDescriptor[attr.id] = index;
+		flatRowDescriptor[attr.id] = flatIndex;
+	});
+
+	return { oldRowDescriptor, newRowDescriptor, flatRowDescriptor };
+}
+
+/**
+ * Composes a flat row from OLD and NEW row values.
+ * Result format: [oldCol0, oldCol1, ..., oldColN, newCol0, newCol1, ..., newColN]
+ */
+export function composeOldNewRow(oldRow: Row | null, newRow: Row | null, columnCount: number): Row {
+	const flatRow: Row = new Array(columnCount * 2);
+
+	// Fill OLD section (indices 0..n-1)
+	for (let i = 0; i < columnCount; i++) {
+		flatRow[i] = oldRow ? oldRow[i] : null;
+	}
+
+	// Fill NEW section (indices n..2n-1)
+	for (let i = 0; i < columnCount; i++) {
+		flatRow[columnCount + i] = newRow ? newRow[i] : null;
+	}
+
+	return flatRow;
+}
+
+/**
+ * Extracts NEW values from a flat OLD/NEW row
+ */
+export function extractNewRowFromFlat(flatRow: Row, columnCount: number): Row {
+	return flatRow.slice(columnCount, columnCount * 2);
+}
+
+/**
+ * Extracts OLD values from a flat OLD/NEW row
+ */
+export function extractOldRowFromFlat(flatRow: Row, columnCount: number): Row {
+	return flatRow.slice(0, columnCount);
+}
+
+/**
+ * Helper to build Attribute array from flatRowDescriptor for DML nodes.
+ * This is used by UpdateNode and DeleteNode to expose their flat row layout.
+ */
+export function buildAttributesFromFlatDescriptor(flatRowDescriptor: RowDescriptor): Attribute[] {
+	const attributes: Attribute[] = [];
+	for (const attrIdStr in flatRowDescriptor) {
+		const attrId = parseInt(attrIdStr);
+		const index = flatRowDescriptor[attrId];
+		attributes[index] = {
+			id: attrId,
+			name: `attr_${attrId}`,
+			type: {
+				typeClass: 'scalar' as const,
+				affinity: SqlDataType.TEXT,
+				nullable: true,
+				isReadOnly: false
+			},
+			sourceRelation: 'unknown'
+		};
+	}
+	return attributes;
+}

package/src/util/serialization.ts

@@ -0,0 +1,45 @@
+/**
+ * Utility functions for safe serialization, particularly handling BigInt and Uint8Arrays.
+ */
+import { createLogger } from '../common/logger.js';
+
+const log = createLogger('util:serialization');
+const errorLog = log.extend('error');
+
+export function jsonStringify(obj: any, space?: string | number): string {
+  return JSON.stringify(
+		obj,
+		(_, value) => {
+			if (typeof value === 'bigint') {
+				// Convert to number if it's within safe integer limits for JSON
+				if (value >= BigInt(Number.MIN_SAFE_INTEGER) && value <= BigInt(Number.MAX_SAFE_INTEGER)) {
+					return Number(value);
+				}
+				// Otherwise, convert to string (without 'n' suffix for standard JSON)
+				return value.toString();
+			} else if (value instanceof Uint8Array) {
+				return `0x${Buffer.from(value).toString('hex')}`; // Keep existing Uint8Array handling
+			}
+			return value;
+		},
+		space
+	);
+}
+
+/**
+ * Safely stringifies an object to JSON, converting BigInts to strings
+ * ending with 'n' to avoid serialization errors.
+ *
+ * @param obj The object to stringify.
+ * @param space Optional spacing argument for JSON.stringify.
+ * @returns JSON string representation.
+ */
+export function safeJsonStringify(obj: any, space?: string | number): string {
+  try {
+    return jsonStringify(obj, space);
+  } catch (e) {
+    // Fallback in case of unexpected stringify errors
+    errorLog("safeJsonStringify failed:", e);
+    return `[Unserializable Object: ${e instanceof Error ? e.message : String(e)}]`;
+  }
+}

package/src/util/working-table-iterable.ts

@@ -0,0 +1,30 @@
+import type { Row } from '../common/types.js';
+import type { RuntimeContext } from '../runtime/types.js';
+import type { RowDescriptor } from '../planner/nodes/plan-node.js';
+
+/**
+ * A reusable async iterable for working table data that can be iterated multiple times.
+ * Similar to CachedIterable but for runtime-generated working table data.
+ * Used primarily in recursive CTE execution where the working table needs to be
+ * accessed multiple times during recursive iterations.
+ */
+export class WorkingTableIterable implements AsyncIterable<Row> {
+	constructor(
+		private rows: Row[],
+		private rctx: RuntimeContext,
+		private rowDescriptor: RowDescriptor
+	) {}
+
+	async *[Symbol.asyncIterator](): AsyncIterator<Row> {
+		for (const row of this.rows) {
+			// Set up context for this row using the CTE row descriptor
+			this.rctx.context.set(this.rowDescriptor, () => row);
+			try {
+				yield row;
+			} finally {
+				// Clean up context
+				this.rctx.context.delete(this.rowDescriptor);
+			}
+		}
+	}
+}

package/src/vtab/best-access-plan.ts

@@ -0,0 +1,270 @@
+/**
+ * Modern, type-safe replacement for xBestIndex API
+ * Provides better type safety, clearer intent, and extensibility for future optimizations
+ */
+
+import { quereusError } from '../common/errors.js';
+import { StatusCode, type SqlDataType, type SqlValue } from '../common/types.js';
+
+/**
+ * Constraint operators that can be pushed down to virtual tables
+ */
+export type ConstraintOp = '=' | '>' | '>=' | '<' | '<=' | 'MATCH' | 'LIKE' | 'GLOB' | 'IS NULL' | 'IS NOT NULL';
+
+/**
+ * Column metadata provided to virtual tables for planning
+ */
+export interface ColumnMeta {
+	/** Column index in the table */
+	index: number;
+	/** Column name */
+	name: string;
+	/** SQL type information */
+	type: SqlDataType;
+	/** Whether this column is part of the primary key */
+	isPrimaryKey: boolean;
+	/** Whether this column has a unique constraint */
+	isUnique: boolean;
+}
+
+/**
+ * A predicate constraint extracted from WHERE clause
+ */
+export interface PredicateConstraint {
+	/** Column index this constraint applies to */
+	columnIndex: number;
+	/** Constraint operator */
+	op: ConstraintOp;
+	/** Constant value if this is a column-constant comparison */
+	value?: SqlValue;
+	/** Whether this constraint can be used by the virtual table */
+	usable: boolean;
+}
+
+/**
+ * Ordering specification for ORDER BY clauses
+ */
+export interface OrderingSpec {
+	/** Column index to order by */
+	columnIndex: number;
+	/** True for descending order, false for ascending */
+	desc: boolean;
+	/** Whether NULL values should come first or last */
+	nullsFirst?: boolean;
+}
+
+/**
+ * Request object passed to getBestAccessPlan containing query planning information
+ */
+export interface BestAccessPlanRequest {
+	/** Column metadata for the table */
+	columns: readonly ColumnMeta[];
+	/** Extracted predicate constraints from WHERE clause */
+	filters: readonly PredicateConstraint[];
+	/** Required ordering that ancestor nodes need (ORDER BY) */
+	requiredOrdering?: readonly OrderingSpec[];
+	/** LIMIT value known at plan time */
+	limit?: number | null;
+	/** Estimated rows hint from planner (may be unknown) */
+	estimatedRows?: number;
+}
+
+/**
+ * Result object returned by getBestAccessPlan describing the chosen query plan
+ */
+export interface BestAccessPlanResult {
+	/** Which filters were handled by the virtual table (parallel to filters array) */
+	handledFilters: readonly boolean[];
+	/** Optional JavaScript filter function for residual predicates */
+	residualFilter?: (row: any) => boolean;
+	/** Estimated cost in arbitrary virtual CPU units */
+	cost: number;
+	/** Estimated number of rows this plan will return */
+	rows: number | undefined;
+	/** Ordering guaranteed by this access plan */
+	providesOrdering?: readonly OrderingSpec[];
+	/** Whether this plan guarantees unique rows (helps DISTINCT optimization) */
+	isSet?: boolean;
+	/** Free-text explanation for debugging */
+	explains?: string;
+}
+
+/**
+ * Builder class for constructing access plan results
+ */
+export class AccessPlanBuilder {
+	private result: Partial<BestAccessPlanResult> = {};
+
+	/**
+	 * Create a full table scan access plan
+	 */
+	static fullScan(estimatedRows: number): AccessPlanBuilder {
+		return new AccessPlanBuilder()
+			.setCost(estimatedRows * 1.0) // Sequential scan cost
+			.setRows(estimatedRows)
+			.setExplanation('Full table scan');
+	}
+
+	/**
+	 * Create an equality match access plan (index seek)
+	 */
+	static eqMatch(matchedRows: number, indexCost: number = 0.5): AccessPlanBuilder {
+		return new AccessPlanBuilder()
+			.setCost(indexCost + matchedRows * 0.3)
+			.setRows(matchedRows)
+			.setIsSet(matchedRows <= 1)
+			.setExplanation('Index equality seek');
+	}
+
+	/**
+	 * Create a range scan access plan
+	 */
+	static rangeScan(estimatedRows: number, indexCost: number = 0.3): AccessPlanBuilder {
+		return new AccessPlanBuilder()
+			.setCost(indexCost + estimatedRows * 0.5)
+			.setRows(estimatedRows)
+			.setExplanation('Index range scan');
+	}
+
+	/**
+	 * Set the estimated cost of this access plan
+	 */
+	setCost(cost: number): this {
+		this.result.cost = cost;
+		return this;
+	}
+
+	/**
+	 * Set the estimated number of rows
+	 */
+	setRows(rows: number | undefined): this {
+		this.result.rows = rows;
+		return this;
+	}
+
+	/**
+	 * Set which filters are handled by this plan
+	 */
+	setHandledFilters(handledFilters: readonly boolean[]): this {
+		this.result.handledFilters = handledFilters;
+		return this;
+	}
+
+	/**
+	 * Set the ordering provided by this plan
+	 */
+	setOrdering(ordering: readonly OrderingSpec[]): this {
+		this.result.providesOrdering = ordering;
+		return this;
+	}
+
+	/**
+	 * Set whether this plan produces unique rows
+	 */
+	setIsSet(isSet: boolean): this {
+		this.result.isSet = isSet;
+		return this;
+	}
+
+	/**
+	 * Set an explanation for debugging
+	 */
+	setExplanation(explanation: string): this {
+		this.result.explains = explanation;
+		return this;
+	}
+
+	/**
+	 * Set a residual filter function
+	 */
+	setResidualFilter(filter: (row: any) => boolean): this {
+		this.result.residualFilter = filter;
+		return this;
+	}
+
+	/**
+	 * Build the final access plan result
+	 */
+	build(): BestAccessPlanResult {
+		// Ensure required fields are set
+		if (this.result.cost === undefined) {
+			quereusError('Access plan cost must be set', StatusCode.INTERNAL);
+		}
+		if (this.result.handledFilters === undefined) {
+			this.result.handledFilters = [];
+		}
+
+		return this.result as BestAccessPlanResult;
+	}
+}
+
+/**
+ * Validation function for access plan results
+ * Throws if the plan violates basic contracts
+ */
+export function validateAccessPlan(
+	request: BestAccessPlanRequest,
+	result: BestAccessPlanResult
+): void {
+	// Validate handledFilters array length
+	if (result.handledFilters.length !== request.filters.length) {
+		quereusError(
+			`handledFilters length (${result.handledFilters.length}) must match filters length (${request.filters.length})`,
+			StatusCode.FORMAT
+		);
+	}
+
+	// Validate cost is non-negative
+	if (result.cost < 0) {
+		quereusError(`Access plan cost cannot be negative: ${result.cost}`, StatusCode.INTERNAL);
+	}
+
+	// Validate rows is non-negative if specified
+	if (result.rows !== undefined && result.rows < 0) {
+		quereusError(`Access plan rows cannot be negative: ${result.rows}`, StatusCode.INTERNAL);
+	}
+
+	// Validate ordering column indexes
+	if (result.providesOrdering) {
+		for (const order of result.providesOrdering) {
+			if (order.columnIndex < 0 || order.columnIndex >= request.columns.length) {
+				quereusError(
+					`Invalid ordering column index ${order.columnIndex}, must be 0-${request.columns.length - 1}`,
+					StatusCode.FORMAT
+				);
+			}
+		}
+	}
+}
+
+/**
+ * Helper to convert old IndexConstraint to new PredicateConstraint
+ * @deprecated Use direct PredicateConstraint construction instead
+ */
+export function convertIndexConstraint(
+	constraint: any, // Old IndexConstraint type
+	value?: SqlValue
+): PredicateConstraint {
+	// Map old constraint operators to new ones
+	const opMap: Record<string, ConstraintOp> = {
+		'EQ': '=',
+		'GT': '>',
+		'GE': '>=',
+		'LT': '<',
+		'LE': '<=',
+		'MATCH': 'MATCH',
+		'LIKE': 'LIKE',
+		'GLOB': 'GLOB',
+		'ISNULL': 'IS NULL',
+		'ISNOTNULL': 'IS NOT NULL'
+	};
+
+	const op = opMap[constraint.op] || '=';
+
+	return {
+		columnIndex: constraint.iColumn,
+		op,
+		value,
+		usable: constraint.usable
+	};
+}

package/src/vtab/connection.ts

@@ -0,0 +1,36 @@
+import { MaybePromise } from "../common/types.js";
+
+/**
+ * Generic interface for VirtualTable connections that support transactions.
+ * This allows different vtab modules to implement their own connection strategies
+ * while providing a consistent interface for transaction operations.
+ */
+export interface VirtualTableConnection {
+	/** Unique identifier for this connection */
+	readonly connectionId: string;
+
+	/** Name of the table this connection is associated with */
+	readonly tableName: string;
+
+	// Transaction methods
+	/** Begins a transaction on this connection */
+	begin(): MaybePromise<void>;
+
+	/** Commits the current transaction */
+	commit(): MaybePromise<void>;
+
+	/** Rolls back the current transaction */
+	rollback(): MaybePromise<void>;
+
+	/** Creates a savepoint with the given index */
+	createSavepoint(index: number): MaybePromise<void>;
+
+	/** Releases a savepoint with the given index */
+	releaseSavepoint(index: number): MaybePromise<void>;
+
+	/** Rolls back to a savepoint with the given index */
+	rollbackToSavepoint(index: number): MaybePromise<void>;
+
+	/** Disconnects and cleans up this connection */
+	disconnect(): MaybePromise<void>;
+}

package/src/vtab/filter-info.ts

@@ -0,0 +1,23 @@
+import type { SqlValue } from '../common/types.js';
+import type { IndexConstraint, IndexInfo } from './index-info.js';
+
+/**
+ * Structure to pass all necessary filter and planning information
+ * to a virtual table's xOpen method when cursors are not used.
+ */
+export interface FilterInfo {
+	/** The index number chosen by xBestIndex (output of xBestIndex) */
+	idxNum: number;
+	/** The index string chosen by xBestIndex (output of xBestIndex) */
+	idxStr: string | null;
+	/** Array of WHERE clause constraints (input to xBestIndex/xOpen) */
+	constraints: ReadonlyArray<{ constraint: IndexConstraint, argvIndex: number }>;
+	/** Values for ?. argvIndex in constraints (input to xOpen) */
+	args: ReadonlyArray<SqlValue>;
+	/**
+	 * The IndexInfo object AFTER xBestIndex has populated its output fields
+	 * (aConstraintUsage, orderByConsumed, estimatedCost, estimatedRows, idxFlags).
+	 * This is needed by xOpen to understand how constraints were used by the planner.
+	 */
+	indexInfoOutput: IndexInfo;
+}