@quereus/quereus 0.7.3 → 0.7.4

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

@@ -1,38 +0,0 @@
-import type { Row } from '../common/types.js';
-import type { RuntimeContext } from '../runtime/types.js';
-import type { RowDescriptor } from '../planner/nodes/plan-node.js';
-import { withRowContextGenerator } from '../runtime/context-helpers.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> {
-		// Convert rows array to async iterable
-		async function* rowsIterable(rows: Row[]): AsyncIterable<Row> {
-			for (const row of rows) {
-				yield row;
-			}
-		}
-
-		// Use the helper to manage context
-		yield* withRowContextGenerator(
-			this.rctx,
-			this.rowDescriptor,
-			rowsIterable(this.rows),
-			async function* (row) {
-				yield row;
-			}
-		);
-	}
-}
-

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

@@ -1,244 +0,0 @@
-/**
- * Modern, type-safe replacement for xBestIndex API
- * Provides better type safety, clearer intent, and extensibility for future optimizations
- */
-
-/* eslint-disable @typescript-eslint/no-explicit-any */
-import { quereusError } from '../common/errors.js';
-import { StatusCode, type SqlValue } from '../common/types.js';
-import type { LogicalType } from '../types/logical-type.js';
-
-/**
- * Constraint operators that can be pushed down to virtual tables
- */
-export type ConstraintOp = '=' | '>' | '>=' | '<' | '<=' | 'MATCH' | 'LIKE' | 'GLOB' | 'IS NULL' | 'IS NOT NULL' | 'IN' | 'NOT IN';
-
-/**
- * Column metadata provided to virtual tables for planning
- */
-export interface ColumnMeta {
-	/** Column index in the table */
-	index: number;
-	/** Column name */
-	name: string;
-	/** Logical type information */
-	type: LogicalType;
-	/** 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[];
-	/** Name of the index that provides the ordering (if any) */
-	orderingIndexName?: string;
-	/** 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
-				);
-			}
-		}
-	}
-}
-
-

package/src/vtab/connection.ts

@@ -1,36 +0,0 @@
-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

@@ -1,23 +0,0 @@
-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;
-}

package/src/vtab/index-info.ts

@@ -1,84 +0,0 @@
-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

@@ -1,86 +0,0 @@
-/* eslint-disable @typescript-eslint/no-explicit-any */
-import type { SqlValue } from '../common/types.js';
-import type { FunctionSchema } from '../schema/function.js';
-import type { CollationFunction } from '../util/comparison.js';
-import type { TypePluginInfo } from '../types/plugin-interface.js';
-
-// Re-export TypePluginInfo so it can be imported from this module
-export type { TypePluginInfo };
-
-/**
- * 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;
-}
-
-/**
- * Virtual table module registration info
- */
-export interface VTablePluginInfo {
-	name: string;                   // module name for registration
-	module: any;                   // the VirtualTableModule implementation
-	auxData?: unknown;             // optional auxiliary data
-}
-
-/**
- * Function registration info
- */
-export interface FunctionPluginInfo {
-	schema: FunctionSchema;        // complete function schema
-}
-
-/**
- * Collation registration info
- */
-export interface CollationPluginInfo {
-	name: string;                  // collation name
-	func: CollationFunction;       // comparison function
-}
-
-/**
- * Plugin registration items - what the plugin wants to register
- */
-export interface PluginRegistrations {
-	vtables?: VTablePluginInfo[];
-	functions?: FunctionPluginInfo[];
-	collations?: CollationPluginInfo[];
-	types?: TypePluginInfo[];
-}
-
-/**
- * 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 type indicators (for UI display)
-	provides?: {
-		vtables?: string[];         // names of vtable modules provided
-		functions?: string[];       // names of functions provided
-		collations?: string[];      // names of collations provided
-		types?: string[];           // names of types provided
-	};
-}
-
-/**
- * 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

@@ -1,73 +0,0 @@
-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;
-	}
-}