@quereus/quereus 0.1.0 → 0.2.1

package/src/core/database.ts

@@ -26,12 +26,13 @@ import { ParameterScope } from '../planner/scopes/param.js';
 import { GlobalScope } from '../planner/scopes/global.js';
 import type { PlanNode } from '../planner/nodes/plan-node.js';
 import { registerEmitters } from '../runtime/register.js';
-import { serializePlanTree } from '../planner/debug.js';
+import { serializePlanTree, formatPlanTree } from '../planner/debug.js';
 import type { DebugOptions } from '../planner/planning-context.js';
 import { EmissionContext } from '../runtime/emission-context.js';
 import { Optimizer, DEFAULT_TUNING } from '../planner/optimizer.js';
 import { registerBuiltinWindowFunctions } from '../func/builtins/builtin-window-functions.js';
 import { DatabaseOptionsManager } from './database-options.js';
+import type { InstructionTracer } from '../runtime/types.js';
 
 const log = createLogger('core:database');
 const warnLog = log.extend('warn');
@@ -52,6 +53,7 @@ export class Database {
 	private inImplicitTransaction = false; // Track if we're in an implicit transaction
 	public readonly optimizer: Optimizer;
 	public readonly options: DatabaseOptionsManager;
+	private instructionTracer: InstructionTracer | undefined;
 
 	constructor() {
 		this.schemaManager = new SchemaManager(this);
@@ -145,6 +147,12 @@ export class Database {
 				log('Default column nullability changed to: %s', value);
 			}
 		});
+
+		this.options.registerOption('trace_plan_stack', {
+			type: 'boolean',
+			defaultValue: false,
+			description: 'Enable plan stack tracing',
+		});
 	}
 
 	/** @internal Registers default built-in SQL functions */
@@ -247,6 +255,7 @@ export class Database {
 						params: params ?? {},
 						context: new Map(),
 						tableContexts: new Map(),
+						tracer: this.instructionTracer,
 						enableMetrics: this.options.getBooleanOption('runtime_stats'),
 					};
 
@@ -547,6 +556,24 @@ export class Database {
 		log('Registered collation: %s', name);
 	}
 
+	/**
+	 * Sets the instruction tracer for this database.
+	 * The tracer will be used for all statement executions.
+	 * @param tracer The instruction tracer to use, or null to disable tracing.
+	 */
+	setInstructionTracer(tracer: InstructionTracer | undefined): void {
+		this.instructionTracer = tracer;
+		log('Instruction tracer %s', tracer ? 'enabled' : 'disabled');
+	}
+
+	/**
+	 * Gets the current instruction tracer for this database.
+	 * @returns The instruction tracer, or undefined if none is set.
+	 */
+	getInstructionTracer(): InstructionTracer | undefined {
+		return this.instructionTracer;
+	}
+
 	/** @internal Gets a registered collation function */
 	_getCollation(name: string): CollationFunction | undefined {
 		return getCollation(name);
@@ -625,14 +652,27 @@ export class Database {
 	}
 
 	/**
-	 * Gets a detailed JSON representation of the query plan for debugging.
+	 * Gets a detailed representation of the query plan for debugging.
 	 * @param sql The SQL statement to plan.
-	 * @returns JSON string containing the detailed plan tree.
+	 * @param options Optional formatting options. If not provided, uses concise tree format.
+	 * @returns String containing the formatted plan tree.
 	 */
-	getDebugPlan(sql: string): string {
+	getDebugPlan(sql: string, options?: { verbose?: boolean; expandNodes?: string[]; maxDepth?: number }): string {
 		this.checkOpen();
 		const plan = this.getPlan(sql);
-		return serializePlanTree(plan);
+		
+		if (options?.verbose) {
+			// Use the original detailed JSON format
+			return serializePlanTree(plan);
+		} else {
+			// Use the new concise tree format
+			return formatPlanTree(plan, {
+				concise: true,
+				expandNodes: options?.expandNodes || [],
+				maxDepth: options?.maxDepth,
+				showPhysical: true
+			});
+		}
 	}
 
 	/**
@@ -683,8 +723,10 @@ export class Database {
 			schemaManager: this.schemaManager,
 			parameters: params ?? {},
 			scope: parameterScope,
+			cteNodes: new Map(),
 			schemaDependencies: new BuildTimeDependencyTracker(),
-			schemaCache: new Map()
+			schemaCache: new Map(),
+			cteReferenceCache: new Map()
 		};
 
 		return buildBlock(ctx, statements);

package/src/core/statement.ts

@@ -12,7 +12,6 @@ import type { RuntimeContext } from '../runtime/types.js';
 import { Cached } from '../util/cached.js';
 import { isAsyncIterable } from '../runtime/utils.js';
 import { generateInstructionProgram, serializePlanTree } from '../planner/debug.js';
-import type { InstructionTracer } from '../runtime/types.js';
 import { EmissionContext } from '../runtime/emission-context.js';
 import type { SchemaDependency } from '../planner/planning-context.js';
 
@@ -241,6 +240,7 @@ export class Statement {
 				params: this.boundArgs,
 				context: new Map(),
 				tableContexts: new Map(),
+				tracer: this.db.getInstructionTracer(),
 				enableMetrics: this.db.getOption('runtime_metrics'),
 			};
 
@@ -438,53 +438,5 @@ export class Statement {
 
 		return generateInstructionProgram(scheduler.instructions, scheduler.destinations);
 	}
-
-	/**
-	 * Executes with runtime instruction tracing enabled.
-	 * @param params Optional parameters to bind.
-	 * @param tracer Optional custom tracer for collecting trace data.
-	 */
-	async *iterateRowsWithTrace(params?: SqlParameters | SqlValue[], tracer?: InstructionTracer): AsyncIterable<Row> {
-		this.validateStatement("iterate rows with trace for");
-		if (this.busy) throw new MisuseError("Statement busy, another iteration may be in progress or reset needed.");
-		if (params) this.bindAll(params);
-		this.busy = true;
-
-		try {
-			const blockPlanNode = this.compile();
-			if (!blockPlanNode.statements.length) return;
-
-			const emissionContext = this.getEmissionContext();
-			const rootInstruction = emitPlanNode(blockPlanNode, emissionContext);
-			const scheduler = new Scheduler(rootInstruction);
-			const runtimeCtx: RuntimeContext = {
-				db: this.db,
-				stmt: this,
-				params: this.boundArgs,
-				context: new Map(),
-				tableContexts: new Map(),
-				tracer: tracer,
-				enableMetrics: this.db.getOption('runtime_metrics'),
-			};
-
-			const results = await scheduler.run(runtimeCtx);
-			if (results) {
-				if (Array.isArray(results) && results.length) {
-					const lastStatementOutput = results[results.length - 1];
-					if (isAsyncIterable(lastStatementOutput)) {
-						yield* lastStatementOutput as AsyncIterable<Row>;
-					}
-				} else if (isAsyncIterable(results)) {
-					yield* results as AsyncIterable<Row>;
-				}
-			}
-		} catch (e: any) {
-			errorLog('Runtime execution failed in iterateRowsWithTrace for current statement: %O', e);
-			if (e instanceof QuereusError) throw e;
-			throw new QuereusError(`Execution error: ${e.message}`, StatusCode.ERROR, e);
-		} finally {
-			this.busy = false;
-		}
-	}
 }
 

package/src/func/builtins/explain.ts

@@ -75,10 +75,6 @@ export const queryPlanFunc = createIntegratedTableValuedFunction(
 					op = node.nodeType.replace(/Node$/, '').toUpperCase();
 
 					switch (node.nodeType) {
-						case 'TableScan':
-							objectName = node.source?.tableSchema?.name || null;
-							alias = node.alias || null;
-							break;
 						case 'TableFunctionCall':
 							objectName = node.functionName;
 							alias = node.alias || null;
@@ -287,13 +283,6 @@ export const stackTraceFunc = createIntegratedTableValuedFunction(
 							vars: { statementCount: node.statements?.length || 0 }
 						});
 						break;
-					case 'TableScan':
-						stack.push({
-							name: 'buildTableScan',
-							location: 'building/table.ts:buildTableScan',
-							vars: { tableName: node.source?.tableSchema?.name || 'unknown' }
-						});
-						break;
 					case 'Filter':
 						stack.push({
 							name: 'buildFilter',

package/src/index.ts

@@ -11,16 +11,41 @@ export { Statement } from './core/statement.js';
 
 // Common data types and constants
 export { StatusCode, SqlDataType } from './common/types.js';
-export type { SqlValue, SqlParameters, Row } from './common/types.js';
-export { ConflictResolution } from './common/constants.js';
+export type { SqlValue, SqlParameters, Row, MaybePromise, RowOp } from './common/types.js';
+export { ConflictResolution, IndexConstraintOp, VTabConfig, FunctionFlags } from './common/constants.js';
 export { QuereusError, MisuseError, ConstraintError, unwrapError, formatErrorChain, getPrimaryError } from './common/errors.js';
 export type { ErrorInfo } from './common/errors.js';
 
 // Virtual Table API
 export { VirtualTable } from './vtab/table.js';
+export type { VirtualTableConnection } from './vtab/connection.js';
 export { MemoryTableModule } from './vtab/memory/module.js';
-export type { IndexInfo, IndexConstraint, IndexConstraintUsage, IndexOrderBy, IndexScanFlags } from './vtab/index-info.js';
+export type { IndexInfo, IndexConstraint, IndexConstraintUsage, IndexOrderBy } from './vtab/index-info.js';
+export { IndexScanFlags } from './vtab/index-info.js';
 export type { FilterInfo } from './vtab/filter-info.js';
+export type { BaseModuleConfig, SchemaChangeInfo } from './vtab/module.js';
+
+// Best Access Plan API (modern vtable planning interface)
+export type {
+	BestAccessPlanRequest,
+	BestAccessPlanResult,
+	ConstraintOp,
+	ColumnMeta,
+	PredicateConstraint,
+	OrderingSpec
+} from './vtab/best-access-plan.js';
+export { AccessPlanBuilder, validateAccessPlan } from './vtab/best-access-plan.js';
+
+// Collation functions
+export type { CollationFunction } from './util/comparison.js';
+export {
+	BINARY_COLLATION,
+	NOCASE_COLLATION,
+	RTRIM_COLLATION,
+	registerCollation,
+	getCollation,
+	resolveCollation
+} from './util/comparison.js';
 
 // SQL Parser and Compiler
 export { Parser } from './parser/parser.js';
@@ -58,10 +83,19 @@ import './runtime/register.js';
 
 // Re-export plugin system
 export { dynamicLoadModule, validatePluginUrl } from './util/plugin-loader.js';
-export type { PluginManifest, PluginRecord, PluginSetting } from './vtab/manifest.js';
+export type {
+	PluginManifest,
+	PluginRecord,
+	PluginSetting,
+	VTablePluginInfo,
+	FunctionPluginInfo,
+	CollationPluginInfo,
+	PluginRegistrations
+} from './vtab/manifest.js';
 
 // Re-export virtual table framework
 export type { VirtualTableModule } from './vtab/module.js';
 
 // Debug and development utilities
-export { serializePlanTree } from './planner/debug.js';
+export { serializePlanTree, formatPlanTree, formatPlanSummary, serializePlanTreeWithOptions } from './planner/debug.js';
+export type { PlanDisplayOptions } from './planner/debug.js';

package/src/parser/ast.ts

@@ -1,4 +1,4 @@
-import type { MaybePromise, SqlValue } from '../common/types.js';
+import type { MaybePromise, RowOp, SqlValue } from '../common/types.js';
 import type { ConflictResolution } from '../common/constants.js';
 
 /**
@@ -13,7 +13,7 @@ export interface AstNode {
 		| 'rollback' | 'table' | 'join' | 'savepoint' | 'release' | 'functionSource' | 'with' | 'commonTableExpr' | 'pragma'
 		| 'collate' | 'primaryKey' | 'notNull' | 'null' | 'unique' | 'check' | 'default' | 'foreignKey' | 'generated' | 'windowFunction'
 		| 'windowDefinition' | 'windowFrame' | 'currentRow' | 'unboundedPreceding' | 'unboundedFollowing' | 'preceding' | 'following'
-		| 'subquerySource' | 'mutatingSubquerySource' | 'case' | 'in' | 'exists' | 'values';
+		| 'subquerySource' | 'mutatingSubquerySource' | 'case' | 'in' | 'exists' | 'values' | 'between';
 	loc?: {
 		start: { line: number, column: number, offset: number };
 		end: { line: number, column: number, offset: number };
@@ -23,7 +23,7 @@ export interface AstNode {
 // Expression types
 export type Expression = LiteralExpr | IdentifierExpr | BinaryExpr | UnaryExpr | FunctionExpr | CastExpr
 	| ParameterExpr | SubqueryExpr | ColumnExpr | FunctionSource | CollateExpr | WindowFunctionExpr | CaseExpr
-	| InExpr | ExistsExpr;
+	| InExpr | ExistsExpr | BetweenExpr;
 
 // Literal value expression (number, string, null, etc.)
 export interface LiteralExpr extends AstNode {
@@ -129,6 +129,15 @@ export interface SubqueryExpr extends AstNode {
 	query: SelectStmt;
 }
 
+// BETWEEN expression
+export interface BetweenExpr extends AstNode {
+	type: 'between';
+	expr: Expression;      // Left side of BETWEEN
+	lower: Expression;     // Lower bound
+	upper: Expression;     // Upper bound
+	not?: boolean;         // For NOT BETWEEN
+}
+
 // IN expression
 export interface InExpr extends AstNode {
 	type: 'in';
@@ -347,9 +356,6 @@ export interface ColumnDef {
 	constraints: ColumnConstraint[];
 }
 
-// New type for row operations
-export type RowOp = 'insert' | 'update' | 'delete';
-
 // Column constraint (PRIMARY KEY, NOT NULL, etc.)
 export interface ColumnConstraint extends AstNode {
 	type: 'primaryKey' | 'notNull' | 'null' | 'unique' | 'check' | 'default' | 'foreignKey' | 'collate' | 'generated';

package/src/parser/parser.ts

@@ -2,7 +2,7 @@ import { createLogger } from '../common/logger.js'; // Import logger
 import { Lexer, type Token, TokenType } from './lexer.js';
 import * as AST from './ast.js';
 import { ConflictResolution } from '../common/constants.js';
-import type { SqlValue } from '../common/types.js';
+import type { RowOp, SqlValue } from '../common/types.js';
 import { quereusError } from '../common/errors.js';
 import { StatusCode } from '../common/types.js';
 import { getSyncLiteral } from './utils.js';
@@ -466,7 +466,24 @@ export class Parser {
 				const expr = this.expression();
 				const direction = this.match(TokenType.DESC) ? 'desc' :
 					(this.match(TokenType.ASC) ? 'asc' : 'asc'); // Default to ASC
-				orderBy.push({ expr, direction });
+
+				// Handle NULLS FIRST/LAST
+				let nulls: 'first' | 'last' | undefined;
+				if (this.matchKeyword('NULLS')) {
+					if (this.matchKeyword('FIRST')) {
+						nulls = 'first';
+					} else if (this.matchKeyword('LAST')) {
+						nulls = 'last';
+					} else {
+						throw this.error(this.peek(), "Expected 'FIRST' or 'LAST' after 'NULLS'.");
+					}
+				}
+
+				const orderClause: AST.OrderByClause = { expr, direction };
+				if (nulls) {
+					orderClause.nulls = nulls;
+				}
+				orderBy.push(orderClause);
 			} while (this.match(TokenType.COMMA));
 			lastConsumedToken = this.previous(); // After last order by clause
 		}
@@ -1125,33 +1142,18 @@ export class Parser {
 					}
 				} else if (this.match(TokenType.BETWEEN)) {
 					// NOT BETWEEN
-					const low = this.term();
+					const lower = this.term();
 					this.consume(TokenType.AND, "Expected 'AND' after NOT BETWEEN lower bound.");
-					const high = this.term();
-					const endToken = this.previous(); // End token is end of high expr
-
-					// Create a binary AND expression for the bounds
-					const boundsExpr: AST.BinaryExpr = {
-						type: 'binary',
-						operator: 'AND',
-						left: low,
-						right: high,
-						loc: _createLoc(low.loc?.start ? this.tokens.find(t => t.startOffset === low.loc!.start.offset) ?? this.peek() : this.peek(), endToken)
-					};
-
-					// Create the BETWEEN expression as a binary expression, then wrap in NOT
-					const betweenExpr: AST.BinaryExpr = {
-						type: 'binary',
-						operator: 'BETWEEN',
-						left: expr,
-						right: boundsExpr,
-						loc: _createLoc(startToken, endToken),
-					};
+					const upper = this.term();
+					const endToken = this.previous(); // End token is end of upper expr
 
+					// Create the NOT BETWEEN expression as a dedicated node type
 					expr = {
-						type: 'unary',
-						operator: 'NOT',
-						expr: betweenExpr,
+						type: 'between',
+						expr,
+						lower,
+						upper,
+						not: true,
 						loc: _createLoc(notStartToken, endToken),
 					};
 				} else if (this.match(TokenType.LIKE)) {
@@ -1194,26 +1196,17 @@ export class Parser {
 				};
 			} else if (operatorToken.type === TokenType.BETWEEN) {
 				// Parse BETWEEN expression: expr BETWEEN low AND high
-				const low = this.term();
+				const lower = this.term();
 				this.consume(TokenType.AND, "Expected 'AND' after BETWEEN lower bound.");
-				const high = this.term();
-				const endToken = this.previous(); // End token is end of high expr
+				const upper = this.term();
+				const endToken = this.previous(); // End token is end of upper expr
 
-				// Create a binary AND expression for the bounds
-				const boundsExpr: AST.BinaryExpr = {
-					type: 'binary',
-					operator: 'AND',
-					left: low,
-					right: high,
-					loc: _createLoc(low.loc?.start ? this.tokens.find(t => t.startOffset === low.loc!.start.offset) ?? this.peek() : this.peek(), endToken)
-				};
-
-				// Create the BETWEEN expression as a binary expression
+				// Create the BETWEEN expression as a dedicated node type
 				expr = {
-					type: 'binary',
-					operator: 'BETWEEN',
-					left: expr,
-					right: boundsExpr,
+					type: 'between',
+					expr,
+					lower,
+					upper,
 					loc: _createLoc(startToken, endToken),
 				};
 			} else if (operatorToken.type === TokenType.IN) {
@@ -1617,20 +1610,20 @@ export class Parser {
 					const direction = this.match(TokenType.DESC) ? 'desc' : (this.match(TokenType.ASC) ? 'asc' : 'asc');
 
 					// Handle NULLS FIRST/LAST
-					let nullsOrdering: 'first' | 'last' | undefined;
+					let nulls: 'first' | 'last' | undefined;
 					if (this.matchKeyword('NULLS')) {
 						if (this.matchKeyword('FIRST')) {
-							nullsOrdering = 'first';
+							nulls = 'first';
 						} else if (this.matchKeyword('LAST')) {
-							nullsOrdering = 'last';
+							nulls = 'last';
 						} else {
 							throw this.error(this.peek(), "Expected 'FIRST' or 'LAST' after 'NULLS'.");
 						}
 					}
 
 					const orderClause: AST.OrderByClause = { expr, direction };
-					if (nullsOrdering) {
-						(orderClause as any).nullsOrdering = nullsOrdering;
+					if (nulls) {
+						orderClause.nulls = nulls;
 					}
 					orderBy.push(orderClause);
 				} while (this.match(TokenType.COMMA));
@@ -2454,7 +2447,7 @@ export class Parser {
 			return { type: 'unique', name, onConflict, loc: _createLoc(startToken, endToken) };
 		} else if (this.match(TokenType.CHECK)) {
 			// --- Parse optional ON clause before parentheses --- //
-			let operations: AST.RowOp[] | undefined;
+			let operations: RowOp[] | undefined;
 			if (this.matchKeyword('ON')) {
 				operations = this.parseRowOpList();
 			}
@@ -2533,7 +2526,7 @@ export class Parser {
 			return { type: 'unique', name, columns, onConflict, loc: _createLoc(startToken, endToken) };
 		} else if (this.match(TokenType.CHECK)) {
 			// --- Parse optional ON clause before parentheses --- //
-			let operations: AST.RowOp[] | undefined;
+			let operations: RowOp[] | undefined;
 			if (this.matchKeyword('ON')) {
 				operations = this.parseRowOpList();
 			}
@@ -2704,8 +2697,8 @@ export class Parser {
 	}
 
 			/** Parses the list of operations for CHECK ON */
-	private parseRowOpList(): AST.RowOp[] {
-		const operations: AST.RowOp[] = [];
+	private parseRowOpList(): RowOp[] {
+		const operations: RowOp[] = [];
 
 		// Parse operations in a comma-separated list
 		do {