@quereus/quereus 0.2.1 → 0.4.5

package/src/core/statement.ts

@@ -106,6 +106,7 @@ export class Statement {
 		try {
 			const currentAst = this.getAstStatement();
 			const planResult = this.db._buildPlan([currentAst], this.boundArgs);
+			// eslint-disable-next-line @typescript-eslint/no-explicit-any
 			const dependencies = (planResult as any).schemaDependencies; // Extract dependencies from planning context
 			plan = this.db.optimizer.optimize(planResult, this.db) as BlockNode;
 
@@ -241,7 +242,7 @@ export class Statement {
 				context: new Map(),
 				tableContexts: new Map(),
 				tracer: this.db.getInstructionTracer(),
-				enableMetrics: this.db.getOption('runtime_metrics'),
+				enableMetrics: Boolean(this.db.getOption('runtime_metrics')),
 			};
 
 			const results = await scheduler.run(runtimeCtx);
@@ -255,6 +256,7 @@ export class Statement {
 					yield* results as AsyncIterable<Row>;
 				}
 			}
+			// eslint-disable-next-line @typescript-eslint/no-explicit-any
 		} catch (e: any) {
 			errorLog('Runtime execution failed in iterateRows for current statement: %O', e);
 			if (e instanceof QuereusError) throw e;

package/src/func/builtins/builtin-window-functions.ts

@@ -1,5 +1,6 @@
 import { registerWindowFunction } from '../../schema/window-function.js';
 import { SqlDataType } from '../../common/types.js';
+import { AggValue } from '../registration.js';
 
 // Built-in window function schemas
 export function registerBuiltinWindowFunctions(): void {
@@ -68,13 +69,13 @@ export function registerBuiltinWindowFunctions(): void {
 		},
 		requiresOrderBy: false,
 		kind: 'aggregate',
-		step: (state: any, value: any) => {
+		step: (state: AggValue, value: AggValue) => {
 			if (state === null || state === undefined) {
 				state = 0;
 			}
 			return value !== null ? state + 1 : state;
 		},
-		final: (state: any) => state || 0
+		final: (state: AggValue) => state || 0
 	});
 
 	registerWindowFunction({
@@ -88,14 +89,14 @@ export function registerBuiltinWindowFunctions(): void {
 		},
 		requiresOrderBy: false,
 		kind: 'aggregate',
-		step: (state: any, value: any) => {
+		step: (state: AggValue, value: AggValue) => {
 			if (value === null) return state;
 			if (state === null || state === undefined) {
 				return Number(value);
 			}
 			return state + Number(value);
 		},
-		final: (state: any) => state
+		final: (state: AggValue) => state
 	});
 
 	registerWindowFunction({
@@ -109,7 +110,7 @@ export function registerBuiltinWindowFunctions(): void {
 		},
 		requiresOrderBy: false,
 		kind: 'aggregate',
-		step: (state: any, value: any) => {
+		step: (state: AggValue, value: AggValue) => {
 			if (value === null) return state;
 			if (!state) {
 				state = { sum: 0, count: 0 };
@@ -118,7 +119,7 @@ export function registerBuiltinWindowFunctions(): void {
 			state.count += 1;
 			return state;
 		},
-		final: (state: any) => state ? state.sum / state.count : null
+		final: (state: AggValue) => state ? state.sum / state.count : null
 	});
 
 	registerWindowFunction({
@@ -132,14 +133,14 @@ export function registerBuiltinWindowFunctions(): void {
 		},
 		requiresOrderBy: false,
 		kind: 'aggregate',
-		step: (state: any, value: any) => {
+		step: (state: AggValue, value: AggValue) => {
 			if (value === null) return state;
 			if (state === null || state === undefined) {
 				return value;
 			}
 			return value < state ? value : state;
 		},
-		final: (state: any) => state
+		final: (state: AggValue) => state
 	});
 
 	registerWindowFunction({
@@ -153,13 +154,13 @@ export function registerBuiltinWindowFunctions(): void {
 		},
 		requiresOrderBy: false,
 		kind: 'aggregate',
-		step: (state: any, value: any) => {
+		step: (state: AggValue, value: AggValue) => {
 			if (value === null) return state;
 			if (state === null || state === undefined) {
 				return value;
 			}
 			return value > state ? value : state;
 		},
-		final: (state: any) => state
+		final: (state: AggValue) => state
 	});
 }

package/src/func/builtins/datetime.ts

@@ -451,3 +451,45 @@ export const strftimeFunc = createScalarFunction(
 		}
 	}
 );
+
+// IsISODate(text)
+export const isISODateFunc = createScalarFunction(
+	{ name: 'IsISODate', numArgs: 1, deterministic: true },
+	(value: SqlValue): SqlValue => {
+		if (typeof value !== 'string') return 0;
+		const s = value.trim();
+		if (!/^\d{4}-\d{2}-\d{2}$/.test(s)) return 0;
+		try {
+			const d = Temporal.PlainDate.from(s);
+			return d.toString() === s ? 1 : 0;
+		} catch {
+			return 0;
+		}
+	}
+);
+
+// IsISODateTime(text)
+export const isISODateTimeFunc = createScalarFunction(
+	{ name: 'IsISODateTime', numArgs: 1, deterministic: true },
+	(value: SqlValue): SqlValue => {
+		if (typeof value !== 'string') return 0;
+		const s = value.trim();
+		// YYYY-MM-DDTHH:MM[:SS[.fraction]] [timezone]
+		const re =
+			/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(?::\d{2}(?:\.\d{1,9})?)?(?:Z|[+-]\d{2}:\d{2})?$/;
+		if (!re.test(s)) return 0;
+		const hasZone = /(?:Z|[+-]\d{2}:\d{2})$/.test(s);
+		try {
+			if (hasZone) {
+				// Zoned ISO string
+				void Temporal.Instant.from(s);
+				return 1;
+			}
+			// Plain ISO local date-time
+			void Temporal.PlainDateTime.from(s);
+			return 1;
+		} catch {
+			return 0;
+		}
+	}
+);

package/src/func/builtins/explain.ts

@@ -6,7 +6,69 @@ import { QuereusError } from "../../common/errors.js";
 import { StatusCode } from "../../common/types.js";
 import type { Database } from "../../core/database.js";
 import { safeJsonStringify } from "../../util/serialization.js";
-import { InstructionTraceEvent } from "../../runtime/types.js";
+import { CollectingInstructionTracer, InstructionTraceEvent } from "../../runtime/types.js";
+import { PlanNode, RelationalPlanNode } from "../../planner/nodes/plan-node.js";
+import { EmissionContext } from "../../runtime/emission-context.js";
+import { emitPlanNode } from "../../runtime/emitters.js";
+import { Scheduler } from "../../runtime/scheduler.js";
+import { analyzeRowSpecific } from "../../planner/analysis/constraint-extractor.js";
+import { Parser } from "../../parser/parser.js";
+import * as AST from "../../parser/ast.js";
+import { GlobalScope } from "../../planner/scopes/global.js";
+import { ParameterScope } from "../../planner/scopes/param.js";
+import type { PlanningContext } from "../../planner/planning-context.js";
+import { BuildTimeDependencyTracker } from "../../planner/planning-context.js";
+import { buildBlock } from "../../planner/building/block.js";
+
+// Helper function to safely get function name from nodes that have it
+function getFunctionName(node: PlanNode): string | null {
+	// Check for nodes that have functionName property
+	if ('functionName' in node && typeof (node as any).functionName === 'string') {
+		return (node as any).functionName;
+	}
+	return null;
+}
+
+// Helper function to safely get alias from nodes that have it
+function getAlias(node: PlanNode): string | null {
+	// Check for nodes that have alias property
+	if ('alias' in node && typeof (node as any).alias === 'string') {
+		return (node as any).alias;
+	}
+	return null;
+}
+
+// Helper function to safely get table name or related identifier
+function getObjectName(node: PlanNode): string | null {
+	// Check for function name first (table functions, scalar functions, etc.)
+	const functionName = getFunctionName(node);
+	if (functionName) {
+		return functionName;
+	}
+
+	// Check for table schema in table reference nodes
+	if ('tableSchema' in node) {
+		const tableSchema = (node as any).tableSchema;
+		if (tableSchema && typeof tableSchema.name === 'string') {
+			return tableSchema.schemaName ? `${tableSchema.schemaName}.${tableSchema.name}` : tableSchema.name;
+		}
+	}
+
+	// Check for CTE name
+	if ('cteName' in node && typeof (node as any).cteName === 'string') {
+		return (node as any).cteName;
+	}
+
+	// Check for view schema in view reference nodes
+	if ('viewSchema' in node) {
+		const viewSchema = (node as any).viewSchema;
+		if (viewSchema && typeof viewSchema.name === 'string') {
+			return viewSchema.schemaName ? `${viewSchema.schemaName}.${viewSchema.name}` : viewSchema.name;
+		}
+	}
+
+	return null;
+}
 
 // Query plan explanation function (table-valued function)
 export const queryPlanFunc = createIntegratedTableValuedFunction(
@@ -47,7 +109,7 @@ export const queryPlanFunc = createIntegratedTableValuedFunction(
 
 			// Traverse the plan tree and yield information about each node
 			let nodeId = 1;
-			const nodeStack: Array<{ node: any; parentId: number | null; level: number }> = [
+			const nodeStack: Array<{ node: PlanNode; parentId: number | null; level: number }> = [
 				{ node: plan, parentId: null, level: 0 }
 			];
 
@@ -64,7 +126,7 @@ export const queryPlanFunc = createIntegratedTableValuedFunction(
 				let objectName: string | null = null;
 				let alias: string | null = null;
 				const estCost = node.estimatedCost || 1.0;
-				const estRows = (node as any).estimatedRows || 10;
+				const estRows = (node as RelationalPlanNode).estimatedRows || 10;
 
 				// Use node's toString() method for detail if available
 				if (typeof node.toString === 'function') {
@@ -74,32 +136,21 @@ export const queryPlanFunc = createIntegratedTableValuedFunction(
 				if (node.nodeType) {
 					op = node.nodeType.replace(/Node$/, '').toUpperCase();
 
-					switch (node.nodeType) {
-						case 'TableFunctionCall':
-							objectName = node.functionName;
-							alias = node.alias || null;
-							break;
-						default:
-							// For other node types, try to extract common properties
-							if (node.alias) {
-								alias = node.alias;
-							}
-							if (node.tableName) {
-								objectName = node.tableName;
-							}
-							if (node.functionName) {
-								objectName = node.functionName;
-							}
-					}
+					// Extract object name and alias using helper functions
+					objectName = getObjectName(node);
+					alias = getAlias(node);
 				}
 
-				// Get logical properties (if available)
+				// Get logical properties using the correct method name
 				let properties: string | null = null;
-				if (node.getLogicalProperties) {
-					const logicalProps = node.getLogicalProperties();
-					if (logicalProps) {
-						properties = safeJsonStringify(logicalProps);
+				const logicalAttributes = node.getLogicalAttributes();
+				if (logicalAttributes && Object.keys(logicalAttributes).length > 0) {
+					// Attach minimal QuickPick diagnostics from optimizer if available
+					const diag = db.optimizer.getLastDiagnostics?.();
+					if (diag?.quickpick) {
+						(logicalAttributes as any).quickpick = diag.quickpick;
 					}
+					properties = safeJsonStringify(logicalAttributes);
 				}
 
 				// Get physical properties (if available)
@@ -124,13 +175,13 @@ export const queryPlanFunc = createIntegratedTableValuedFunction(
 				];
 
 				// Add children to stack (in reverse order so they're processed in correct order)
-				// Note: getChildren() should include all children (both relational and scalar)
-				// Don't add getRelations() separately as it would cause duplication
-				const children = node.getChildren ? node.getChildren() : [];
+				// getChildren() is guaranteed to exist on all PlanNode instances
+				const children = node.getChildren();
 				for (let i = children.length - 1; i >= 0; i--) {
 					nodeStack.push({ node: children[i], parentId: currentId, level });
 				}
 			}
+		// eslint-disable-next-line @typescript-eslint/no-explicit-any
 		} catch (error: any) {
 			// If planning fails, yield an error row
 			yield [1, null, 0, 'ERROR', 'ERROR', `Failed to plan SQL: ${error.message}`, null, null, null, null, null, null];
@@ -170,10 +221,6 @@ export const schedulerProgramFunc = createIntegratedTableValuedFunction(
 			const plan = db.getPlan(sql);
 
 			// Emit the plan to get the instruction tree
-			const { EmissionContext } = await import('../../runtime/emission-context.js');
-			const { emitPlanNode } = await import('../../runtime/emitters.js');
-			const { Scheduler } = await import('../../runtime/scheduler.js');
-
 			const emissionContext = new EmissionContext(db);
 			const rootInstruction = emitPlanNode(plan, emissionContext);
 
@@ -214,6 +261,7 @@ export const schedulerProgramFunc = createIntegratedTableValuedFunction(
 					}
 				}
 			}
+		// eslint-disable-next-line @typescript-eslint/no-explicit-any
 		} catch (error: any) {
 			// If compilation fails, yield an error instruction
 			yield [0, 'ERROR', '[]', `Failed to compile SQL: ${error.message}`, null, 0, null];
@@ -272,7 +320,7 @@ export const stackTraceFunc = createIntegratedTableValuedFunction(
 			});
 
 			// Add frames based on plan node types
-			const addPlanFrames = (node: any, depth: number = 0) => {
+			const addPlanFrames = (node: PlanNode, depth: number = 0) => {
 				if (!node || depth > 10) return; // Prevent infinite recursion
 
 				switch (node.nodeType) {
@@ -280,28 +328,29 @@ export const stackTraceFunc = createIntegratedTableValuedFunction(
 						stack.push({
 							name: 'buildBlock',
 							location: 'building/block.ts:buildBlock',
-							vars: { statementCount: node.statements?.length || 0 }
+							vars: { statementCount: ('statements' in node) ? (node as any).statements?.length || 0 : 0 }
 						});
 						break;
 					case 'Filter':
 						stack.push({
 							name: 'buildFilter',
 							location: 'building/select.ts:buildSelectStmt',
-							vars: { condition: node.condition?.toString() || 'unknown' }
+							vars: { condition: ('condition' in node) ? (node as any).condition?.toString() || 'unknown' : 'unknown' }
 						});
 						break;
 					case 'Project':
 						stack.push({
 							name: 'buildProject',
 							location: 'building/select.ts:buildSelectStmt',
-							vars: { projectionCount: node.projections?.length || 0 }
+							vars: { projectionCount: ('projections' in node) ? (node as any).projections?.length || 0 : 0 }
 						});
 						break;
 				}
 
 				// Recursively add frames for children
-				const children = node.getChildren ? node.getChildren() : [];
-				children.forEach((child: any) => addPlanFrames(child, depth + 1));
+				// getChildren() is guaranteed to exist on all PlanNode instances
+				const children = node.getChildren();
+				children.forEach((child: PlanNode) => addPlanFrames(child, depth + 1));
 			};
 
 			addPlanFrames(plan);
@@ -319,6 +368,7 @@ export const stackTraceFunc = createIntegratedTableValuedFunction(
 					0                            // is_virtual
 				];
 			}
+		// eslint-disable-next-line @typescript-eslint/no-explicit-any
 		} catch (error: any) {
 			// If analysis fails, yield an error frame
 			yield [0, 0, 'error', 'stack_trace', JSON.stringify({ error: error.message })];
@@ -371,12 +421,12 @@ export const executionTraceFunc = createIntegratedTableValuedFunction(
 					instructionDependencies.set(addr, dependencies);
 					instructionOperations.set(addr, description);
 				}
+			// eslint-disable-next-line @typescript-eslint/no-explicit-any
 			} catch (schedulerError: any) {
 				console.warn('Could not get scheduler program info:', schedulerError.message);
 			}
 
 			// Import the CollectingInstructionTracer
-			const { CollectingInstructionTracer } = await import('../../runtime/types.js');
 			const tracer = new CollectingInstructionTracer();
 
 			// Parse the query and execute with tracing
@@ -391,9 +441,9 @@ export const executionTraceFunc = createIntegratedTableValuedFunction(
 				}
 
 				await stmt.finalize();
-			} catch (executionError: any) {
+			} catch (executionError: unknown) {
 				// If execution fails, we might still have some trace events
-				console.warn('Query execution failed during tracing:', executionError.message);
+				console.warn('Query execution failed during tracing:', executionError instanceof Error ? executionError.message : String(executionError));
 			}
 
 			// Get the collected trace events
@@ -484,6 +534,7 @@ export const executionTraceFunc = createIntegratedTableValuedFunction(
 				];
 			}
 
+		// eslint-disable-next-line @typescript-eslint/no-explicit-any
 		} catch (error: any) {
 			// If tracing setup fails, yield an error event
 			yield [
@@ -530,7 +581,6 @@ export const rowTraceFunc = createIntegratedTableValuedFunction(
 
 		try {
 			// Import the CollectingInstructionTracer
-			const { CollectingInstructionTracer } = await import('../../runtime/types.js');
 			const tracer = new CollectingInstructionTracer();
 
 			// Parse the query and execute with tracing
@@ -545,6 +595,7 @@ export const rowTraceFunc = createIntegratedTableValuedFunction(
 				}
 
 				await stmt.finalize();
+			// eslint-disable-next-line @typescript-eslint/no-explicit-any
 			} catch (executionError: any) {
 				// If execution fails, we might still have some trace events
 				console.warn('Query execution failed during row tracing:', executionError.message);
@@ -595,13 +646,13 @@ export const rowTraceFunc = createIntegratedTableValuedFunction(
 				];
 			}
 
-		} catch (error: any) {
+		} catch (error: unknown) {
 			// If tracing setup fails, yield an error event
 			yield [
 				0,                                                        // instruction_index
 				'ROW_TRACE_SETUP',                                       // operation
 				0,                                                       // row_index
-				safeJsonStringify(`Failed to setup row trace: ${error.message}`), // row_data
+				safeJsonStringify(`Failed to setup row trace: ${error instanceof Error ? error.message : String(error)}`), // row_data
 				Date.now(),                                              // timestamp_ms
 				null                                                     // row_count
 			];
@@ -635,3 +686,94 @@ export const schemaSizeFunc = createIntegratedTableValuedFunction(
 		// TODO: Implementation of schemaSizeFunc
 	}
 );
+
+// Explain assertion analysis and prepared parameterization (pre-physical)
+export const explainAssertionFunc = createIntegratedTableValuedFunction(
+	{
+		name: 'explain_assertion',
+		numArgs: 1,
+		deterministic: true,
+		returnType: {
+			typeClass: 'relation',
+			isReadOnly: true,
+			isSet: false,
+			columns: [
+				{ name: 'assertion', type: { typeClass: 'scalar', affinity: SqlDataType.TEXT, nullable: false, isReadOnly: true }, generated: true },
+				{ name: 'relation_key', type: { typeClass: 'scalar', affinity: SqlDataType.TEXT, nullable: false, isReadOnly: true }, generated: true },
+				{ name: 'base', type: { typeClass: 'scalar', affinity: SqlDataType.TEXT, nullable: false, isReadOnly: true }, generated: true },
+				{ name: 'classification', type: { typeClass: 'scalar', affinity: SqlDataType.TEXT, nullable: false, isReadOnly: true }, generated: true },
+				{ name: 'prepared_pk_params', type: { typeClass: 'scalar', affinity: SqlDataType.TEXT, nullable: true, isReadOnly: true }, generated: true }, // JSON array of param names or NULL
+				{ name: 'violation_sql', type: { typeClass: 'scalar', affinity: SqlDataType.TEXT, nullable: false, isReadOnly: true }, generated: true }
+			],
+			keys: [],
+			rowConstraints: []
+		}
+	},
+	async function* (db: Database, assertionName: SqlValue): AsyncIterable<Row> {
+		if (typeof assertionName !== 'string') {
+			throw new QuereusError('explain_assertion(name) requires an assertion name', StatusCode.ERROR);
+		}
+
+		// Find assertion across all schemas
+		const all = db.schemaManager.getAllAssertions();
+		const assertion = all.find(a => a.name.toLowerCase() === assertionName.toLowerCase());
+		if (!assertion) {
+			throw new QuereusError(`Assertion not found: ${assertionName}`, StatusCode.NOTFOUND);
+		}
+
+		const sql = assertion.violationSql;
+
+		// Build pre-physical plan for analysis
+		let ast: AST.Statement;
+		try {
+			const parser = new Parser();
+			ast = parser.parse(sql) as AST.Statement;
+		} catch (e) {
+			throw new QuereusError(`Failed to parse assertion SQL: ${(e as Error).message}`, StatusCode.ERROR, e as Error);
+		}
+
+		const globalScope = new GlobalScope(db.schemaManager);
+		const parameterScope = new ParameterScope(globalScope);
+		const ctx: PlanningContext = {
+			db,
+			schemaManager: db.schemaManager,
+			parameters: {},
+			scope: parameterScope,
+			cteNodes: new Map(),
+			schemaDependencies: new BuildTimeDependencyTracker(),
+			schemaCache: new Map(),
+			cteReferenceCache: new Map(),
+			outputScopes: new Map()
+		};
+
+		const plan = buildBlock(ctx, [ast]);
+		const analyzed = db.optimizer.optimizeForAnalysis(plan, db) as unknown as RelationalPlanNode;
+
+		// Classify row/global per relationKey
+		const classifications = analyzeRowSpecific(analyzed);
+
+		for (const [relationKey, cls] of classifications) {
+			const base = `${relationKey.split('#')[0]}`;
+			let prepared: string | null = null;
+			if (cls === 'row' && base) {
+				// Prepared parameters are PK-based: ["pk0", "pk1", ...]
+				const [schemaName, tableName] = base.split('.');
+				const table = db._findTable(tableName, schemaName);
+				if (table) {
+					const pkCount = table.primaryKeyDefinition.length;
+					const names = Array.from({ length: pkCount }, (_, i) => `pk${i}`);
+					prepared = JSON.stringify(names);
+				}
+			}
+
+			yield [
+				assertion.name,
+				relationKey,
+				base,
+				cls,
+				prepared,
+				sql
+			];
+		}
+	}
+);

package/src/func/builtins/index.ts

@@ -13,12 +13,12 @@ import { lengthFunc, substrFunc, substringFunc, likeFunc, globFunc, trimFunc, lt
 import { countStarFunc, sumFunc, avgFunc, minFunc, maxFunc, countXFunc, groupConcatFuncRev, totalFunc,
 	varPopFunc, varSampFunc, stdDevPopFunc, stdDevSampFunc } from './aggregate.js';
 import type { FunctionSchema } from '../../schema/function.js';
-import { dateFunc, timeFunc, datetimeFunc, juliandayFunc, strftimeFunc } from './datetime.js';
+import { dateFunc, timeFunc, datetimeFunc, juliandayFunc, strftimeFunc, isISODateFunc, isISODateTimeFunc } from './datetime.js';
 import { jsonValidFunc, jsonTypeFunc, jsonExtractFunc, jsonQuoteFunc, jsonArrayFunc, jsonObjectFunc, jsonInsertFunc, jsonReplaceFunc, jsonSetFunc, jsonRemoveFunc,
 	jsonArrayLengthFunc, jsonPatchFunc,
 	jsonGroupArrayFunc, jsonGroupObjectFunc } from './json.js';
 import { generateSeriesFunc } from './generation.js';
-import { queryPlanFunc, schedulerProgramFunc, stackTraceFunc, executionTraceFunc, rowTraceFunc } from './explain.js';
+import { queryPlanFunc, schedulerProgramFunc, stackTraceFunc, executionTraceFunc, rowTraceFunc, explainAssertionFunc } from './explain.js';
 import { schemaFunc, tableInfoFunc, functionInfoFunc } from './schema.js';
 import { jsonEachFunc, jsonTreeFunc } from './json-tvf.js';
 
@@ -82,6 +82,8 @@ export const BUILTIN_FUNCTIONS: FunctionSchema[] = [
 	datetimeFunc,
 	juliandayFunc,
 	strftimeFunc,
+	isISODateFunc,
+	isISODateTimeFunc,
 	// JSON Functions
 	jsonValidFunc,
 	jsonTypeFunc,
@@ -108,6 +110,7 @@ export const BUILTIN_FUNCTIONS: FunctionSchema[] = [
 	stackTraceFunc,
 	executionTraceFunc,
 	rowTraceFunc,
+	explainAssertionFunc,
 	// Schema introspection functions
 	schemaFunc,
 	tableInfoFunc,