@quereus/quereus 0.7.3 → 0.7.5

package/src/planner/scopes/scope.ts

@@ -1,16 +0,0 @@
-import type { PlanNode } from '../nodes/plan-node.js';
-import * as AST from '../../parser/ast.js';
-
-// Create a javascript symbol that represents an ambiguous symbol.
-export const Ambiguous = Symbol();
-
-export type ReferenceCallback = (expression: AST.Expression, currentScope: Scope) => PlanNode;
-
-/**
- * The Scope object provides context for symbol resolution during query planning.
- * It encapsulates the logic for looking up columns, parameters, functions, and CTEs
- * based on the current position in the PlanNode tree.
- */
-export interface Scope {
-	resolveSymbol(symbolKey: string, expression: AST.Expression): PlanNode | typeof Ambiguous | undefined;
-}

package/src/planner/stats/basic-estimates.ts

@@ -1,107 +0,0 @@
-/**
- * Basic row and cost estimation utilities for plan nodes
- * Used when more sophisticated statistics are not available
- */
-
-import type { RelationalPlanNode } from '../nodes/plan-node.js';
-import type { OptimizerTuning } from '../optimizer-tuning.js';
-
-/**
- * Basic row estimation heuristics
- */
-export class BasicRowEstimator {
-	constructor(private readonly tuning: OptimizerTuning) {}
-
-	/**
-	 * Estimate rows for a filter operation
-	 * Default assumes 30% selectivity for most predicates
-	 */
-	estimateFilter(sourceRows: number): number {
-		return Math.max(1, Math.floor(sourceRows * 0.3));
-	}
-
-	/**
-	 * Estimate rows for a join operation
-	 */
-	estimateJoin(leftRows: number, rightRows: number, joinType: string): number {
-		switch (joinType.toLowerCase()) {
-			case 'inner':
-				// Inner join: assume moderate correlation
-				return Math.max(1, Math.floor(leftRows * rightRows * 0.1));
-			case 'left':
-			case 'left outer':
-				// Left join: at least as many as left side
-				return Math.max(leftRows, Math.floor(leftRows * rightRows * 0.1));
-			case 'right':
-			case 'right outer':
-				// Right join: at least as many as right side
-				return Math.max(rightRows, Math.floor(leftRows * rightRows * 0.1));
-			case 'full':
-			case 'full outer':
-				// Full outer join: sum minus overlap
-				return leftRows + rightRows - Math.floor(leftRows * rightRows * 0.1);
-			case 'cross':
-				// Cross join: cartesian product
-				return leftRows * rightRows;
-			default:
-				return Math.max(leftRows, rightRows);
-		}
-	}
-
-	/**
-	 * Estimate rows for aggregation
-	 */
-	estimateAggregate(sourceRows: number, groupByCount: number): number {
-		if (groupByCount === 0) {
-			return 1; // Single aggregate row
-		}
-		// Assume reasonable grouping factor
-		const groupingFactor = Math.min(0.8, Math.max(0.1, groupByCount * 0.2));
-		return Math.max(1, Math.floor(sourceRows * groupingFactor));
-	}
-
-	/**
-	 * Estimate rows for distinct operation
-	 */
-	estimateDistinct(sourceRows: number): number {
-		// Assume moderate duplication - 70% unique rows
-		return Math.max(1, Math.floor(sourceRows * 0.7));
-	}
-
-	/**
-	 * Estimate rows for limit operation
-	 */
-	estimateLimit(sourceRows: number, limit: number, offset: number = 0): number {
-		return Math.min(sourceRows, Math.max(0, limit - offset));
-	}
-
-	/**
-	 * Get default row estimate when no information is available
-	 */
-	getDefaultEstimate(): number {
-		return this.tuning.defaultRowEstimate;
-	}
-}
-
-/**
- * Helper to safely get row estimate from a relational node
- */
-export function getRowEstimate(node: RelationalPlanNode, tuning: OptimizerTuning): number {
-	return node.estimatedRows ?? tuning.defaultRowEstimate;
-}
-
-/**
- * Helper to set row estimate on a node if not already set
- */
-export function ensureRowEstimate(node: RelationalPlanNode, estimate: number): void {
-	if (node.estimatedRows === undefined) {
-		// Use Object.defineProperty to set a non-enumerable property
-		// This maintains the immutability principle while adding metadata
-		Object.defineProperty(node, 'estimatedRows', {
-			value: estimate,
-			writable: false,
-			enumerable: true,
-			configurable: false
-		});
-	}
-}

package/src/planner/stats/index.ts

@@ -1,158 +0,0 @@
-/**
- * Statistics provider abstraction for the Quereus optimizer
- * Provides cardinality estimates and selectivity information for cost-based optimization
- */
-
-import type { ScalarPlanNode } from '../nodes/plan-node.js';
-import type { TableSchema } from '../../schema/table.js';
-import { createLogger } from '../../common/logger.js';
-
-const log = createLogger('optimizer:stats');
-
-/**
- * Statistics provider interface for optimizer
- */
-export interface StatsProvider {
-	/**
-	 * Get estimated row count for a base table
-	 * @param table Table schema
-	 * @returns Estimated row count, or undefined if unknown
-	 */
-	tableRows(table: TableSchema): number | undefined;
-
-	/**
-	 * Get selectivity estimate for a predicate on a table
-	 * @param table Table schema
-	 * @param predicate Predicate expression
-	 * @returns Selectivity factor (0.0 to 1.0), or undefined if unknown
-	 */
-	selectivity(table: TableSchema, predicate: ScalarPlanNode): number | undefined;
-
-	/**
-	 * Get join selectivity estimate
-	 * @param leftTable Left table schema
-	 * @param rightTable Right table schema
-	 * @param joinCondition Join condition
-	 * @returns Join selectivity factor, or undefined if unknown
-	 */
-	joinSelectivity?(leftTable: TableSchema, rightTable: TableSchema, joinCondition: ScalarPlanNode): number | undefined;
-
-	/**
-	 * Get number of distinct values for a column
-	 * @param table Table schema
-	 * @param columnName Column name
-	 * @returns Estimated distinct values, or undefined if unknown
-	 */
-	distinctValues?(table: TableSchema, columnName: string): number | undefined;
-
-	/**
-	 * Get index selectivity information
-	 * @param table Table schema
-	 * @param indexName Index name (if applicable)
-	 * @param predicate Predicate expression
-	 * @returns Index selectivity factor, or undefined if unknown
-	 */
-	indexSelectivity?(table: TableSchema, indexName: string, predicate: ScalarPlanNode): number | undefined;
-}
-
-/**
- * Naive statistics provider using simple heuristics
- * Used as fallback when no better statistics are available
- */
-export class NaiveStatsProvider implements StatsProvider {
-	constructor(
-		private readonly defaultTableRows: number = 1000,
-		private readonly defaultSelectivity: number = 0.3
-	) {
-		log('Created naive stats provider (defaultRows: %d, defaultSelectivity: %f)',
-			defaultTableRows, defaultSelectivity);
-	}
-
-	tableRows(table: TableSchema): number | undefined {
-		// Use table's estimated rows if available, otherwise use default
-		const estimate = table.estimatedRows ?? this.defaultTableRows;
-		log('Table %s estimated rows: %d (source: %s)',
-			table.name, estimate, table.estimatedRows ? 'schema' : 'default');
-		return estimate;
-	}
-
-	selectivity(table: TableSchema, predicate: ScalarPlanNode): number | undefined {
-		// Simple heuristics based on predicate type
-		const selectivity = this.estimatePredicateSelectivity(predicate);
-		log('Predicate selectivity for %s: %f', predicate.nodeType, selectivity);
-		return selectivity;
-	}
-
-	joinSelectivity(leftTable: TableSchema, rightTable: TableSchema, _joinCondition: ScalarPlanNode): number | undefined {
-		// Default join selectivity based on table sizes
-		const leftRows = this.tableRows(leftTable) ?? this.defaultTableRows;
-		const rightRows = this.tableRows(rightTable) ?? this.defaultTableRows;
-
-		// Simple heuristic: smaller table determines selectivity
-		const selectivity = 1.0 / Math.max(leftRows, rightRows, 10);
-		log('Join selectivity between %s and %s: %f', leftTable.name, rightTable.name, selectivity);
-		return Math.min(0.5, selectivity);
-	}
-
-	distinctValues(table: TableSchema, columnName: string): number | undefined {
-		const totalRows = this.tableRows(table);
-		if (!totalRows) return undefined;
-
-		// Heuristic: assume moderate cardinality (50% distinct values)
-		const distinct = Math.max(1, Math.floor(totalRows * 0.5));
-		log('Distinct values for %s.%s: %d', table.name, columnName, distinct);
-		return distinct;
-	}
-
-	indexSelectivity(table: TableSchema, indexName: string, predicate: ScalarPlanNode): number | undefined {
-		// Index selectivity is generally better than table scan
-		const baseSelecivity = this.selectivity(table, predicate) ?? this.defaultSelectivity;
-		const indexSelectivity = baseSelecivity * 0.8; // 20% improvement with index
-		log('Index %s selectivity: %f (base: %f)', indexName, indexSelectivity, baseSelecivity);
-		return indexSelectivity;
-	}
-
-	private estimatePredicateSelectivity(predicate: ScalarPlanNode): number {
-		// Simple heuristics based on node type
-		switch (predicate.nodeType) {
-			case 'BinaryOp':
-				// More selective for equality, less for ranges
-				return 0.1; // Equality-like operations
-			case 'In':
-				return 0.2; // IN clauses
-			case 'Between':
-				return 0.25; // Range queries
-			case 'Like':
-				return 0.3; // Pattern matching
-			case 'IsNull':
-			case 'IsNotNull':
-				return 0.1; // NULL checks are usually selective
-			default:
-				return this.defaultSelectivity;
-		}
-	}
-}
-
-/**
- * Default statistics provider instance
- */
-export const defaultStatsProvider = new NaiveStatsProvider();
-
-/**
- * Create a custom statistics provider
- */
-export function createStatsProvider(
-	tableRowsMap?: Map<string, number>,
-	selectivityMap?: Map<string, number>
-): StatsProvider {
-	return new class implements StatsProvider {
-		tableRows(table: TableSchema): number | undefined {
-			return tableRowsMap?.get(table.name) ?? defaultStatsProvider.tableRows(table);
-		}
-
-		selectivity(table: TableSchema, predicate: ScalarPlanNode): number | undefined {
-			const key = `${table.name}:${predicate.nodeType}`;
-			return selectivityMap?.get(key) ?? defaultStatsProvider.selectivity(table, predicate);
-		}
-	};
-}

package/src/planner/type-utils.ts

@@ -1,87 +0,0 @@
-import type { TableSchema } from '../schema/table.js';
-import type { ColumnSchema } from '../schema/column.js';
-import type { RelationType, ColumnDef, ScalarType, ColRef } from '../common/datatype.js';
-import { SqlDataType, StatusCode, type DeepReadonly, type SqlValue } from '../common/types.js'; // Import SqlValue and ensure SqlDataType is not type-only
-import type { AstNode } from '../parser/ast.js';
-import { QuereusError } from '../common/errors.js';
-import { inferLogicalTypeFromValue } from '../common/type-inference.js';
-
-/**
- * Converts a TableSchema (from src/schema/table.ts) to a RelationType (from src/common/datatype.ts).
- * This is used by PlanNodes that source data directly from a base table.
- */
-export function relationTypeFromTableSchema(tableSchema: TableSchema): RelationType {
-  const columnDefs: ColumnDef[] = tableSchema.columns.map((col: ColumnSchema) => {
-    return {
-      name: col.name,
-      type: {
-				typeClass: 'scalar',
-				logicalType: col.logicalType,
-				collationName: col.collation,
-				nullable: !col.notNull,
-				isReadOnly: false,
-			},
-      generated: col.generated,
-    };
-  });
-
-  // Populate keys from primaryKeyDefinition
-  const keys: ColRef[][] = [];
-  if (tableSchema.primaryKeyDefinition && tableSchema.primaryKeyDefinition.length > 0) {
-    const primaryKey: ColRef[] = tableSchema.primaryKeyDefinition.map(pkCol => ({
-      index: pkCol.index,
-      desc: pkCol.desc,
-    }));
-    keys.push(primaryKey);
-  }
-
-  return {
-    typeClass: 'relation',
-    isReadOnly: !!(tableSchema.isView || tableSchema.isTemporary),
-    isSet: true, // Base tables are sets by definition (enforced by primary keys)
-    columns: columnDefs,
-    keys: keys,
-    // TODO: Populate rowConstraints from tableSchema if/when RelationType supports them
-    rowConstraints: [], // Placeholder
-  };
-}
-
-/**
- * Creates a ScalarType for a given SqlValue, typically for parameters.
- * @param value The SqlValue to determine the type for.
- * @returns A ScalarType representing the inferred type of the value.
- */
-export function getParameterScalarType(value: SqlValue): ScalarType {
-  const logicalType = inferLogicalTypeFromValue(value);
-
-  return {
-    typeClass: 'scalar',
-    logicalType,
-    nullable: true,	// No guarantees about the value, so it's nullable
-    isReadOnly: true, // Parameters are read-only within the query execution context
-  };
-}
-
-export function checkColumnsAssignable(source: DeepReadonly<ColumnDef[]>, target: DeepReadonly<ColumnDef[]>, astNode?: AstNode): void {
-	if (source.length !== target.length) {
-		throw new QuereusError(`Column count mismatch ${(astNode ? astNode.type + ' clause' : '')}.`, StatusCode.ERROR, undefined, astNode?.loc?.start.line, astNode?.loc?.start.column);
-	}
-}
-
-export function checkRelationsAssignable(source: RelationType, target: RelationType, astNode?: AstNode): void {
-	return checkColumnsAssignable(source.columns, target.columns, astNode);
-}
-
-export function columnSchemaToDef(colName: string, colDef: ColumnSchema): ColumnDef {
-	return {
-		name: colName,
-		type: {
-			typeClass: 'scalar',
-			logicalType: colDef.logicalType,
-			collationName: colDef.collation,
-			nullable: !colDef.notNull,
-			isReadOnly: false,
-		},
-		generated: colDef.generated,
-	};
-}

package/src/planner/util/key-utils.ts

@@ -1,46 +0,0 @@
-import type { ColRef } from '../../common/datatype.js';
-
-/**
- * Project unique keys through a projection mapping.
- * - sourceKeys: keys defined on the source relation (arrays of column refs by source column index)
- * - projectionMap: mapping from source column index -> projected column index
- * Returns keys that survive projection (all columns present), with indices remapped to output.
- */
-export function projectKeys(sourceKeys: ReadonlyArray<ReadonlyArray<ColRef>>, projectionMap: ReadonlyMap<number, number>): ColRef[][] {
-	const result: ColRef[][] = [];
-	for (const key of sourceKeys) {
-		const projected: ColRef[] = [];
-		let missing = false;
-		for (const col of key) {
-			const projectedIndex = projectionMap.get(col.index);
-			if (projectedIndex === undefined) {
-				missing = true;
-				break;
-			}
-			projected.push({ index: projectedIndex, desc: col.desc });
-		}
-		if (!missing) {
-			result.push(projected);
-		}
-	}
-	return result;
-}
-
-/**
- * Combine unique keys across a join.
- * - For inner/cross joins: keys from left and right are preserved; right indices are shifted by left column count.
- * - For outer joins: return [] conservatively (null padding may break uniqueness).
- */
-export function combineJoinKeys(leftKeys: ReadonlyArray<ReadonlyArray<ColRef>>, rightKeys: ReadonlyArray<ReadonlyArray<ColRef>>, joinType: 'inner' | 'left' | 'right' | 'full' | 'cross', leftColumnCount: number): ColRef[][] {
-	if (joinType !== 'inner' && joinType !== 'cross') return [];
-	const result: ColRef[][] = [];
-	for (const key of leftKeys) {
-		result.push(key.map(c => ({ index: c.index, desc: c.desc })));
-	}
-	for (const key of rightKeys) {
-		result.push(key.map(c => ({ index: c.index + leftColumnCount, desc: c.desc })));
-	}
-	return result;
-}
-
-

package/src/planner/validation/determinism-validator.ts

@@ -1,104 +0,0 @@
-import { QuereusError } from '../../common/errors.js';
-import { StatusCode } from '../../common/types.js';
-import type { ScalarPlanNode } from '../nodes/plan-node.js';
-import { createLogger } from '../../common/logger.js';
-
-const log = createLogger('planner:validation:determinism');
-
-/**
- * Result of determinism validation. If valid, `error` is undefined.
- * If invalid, contains the information needed to construct an error message.
- */
-export interface DeterminismValidationResult {
-	/** True if the expression is deterministic */
-	valid: boolean;
-	/** String representation of the offending expression (if invalid) */
-	expression?: string;
-}
-
-/**
- * Checks if an expression is deterministic (suitable for constraints and defaults).
- * Returns a result object instead of throwing, allowing the caller to decide how to handle.
- *
- * @param expr The expression plan node to check
- * @returns Validation result indicating if deterministic
- */
-export function checkDeterministic(expr: ScalarPlanNode): DeterminismValidationResult {
-	const physical = expr.physical;
-
-	if (physical.deterministic === false) {
-		log('Non-deterministic expression detected: %s', expr.toString());
-		return {
-			valid: false,
-			expression: expr.toString()
-		};
-	}
-
-	return { valid: true };
-}
-
-/**
- * Validates that an expression is deterministic (suitable for constraints and defaults).
- * Non-deterministic expressions must be passed via mutation context instead.
- *
- * @param expr The expression plan node to validate
- * @param context Description of where the expression is used (e.g., "DEFAULT for column 'created_at'")
- * @throws QuereusError if the expression is non-deterministic
- */
-export function validateDeterministicExpression(
-	expr: ScalarPlanNode,
-	context: string
-): void {
-	log('Validating determinism for: %s', context);
-
-	const result = checkDeterministic(expr);
-
-	if (!result.valid) {
-		throw new QuereusError(
-			`Non-deterministic expression not allowed in ${context}. ` +
-			`Expression: ${result.expression}. ` +
-			`Use mutation context to pass non-deterministic values (e.g., WITH CONTEXT (timestamp = datetime('now'))).`,
-			StatusCode.ERROR
-		);
-	}
-
-	log('Expression is deterministic: %s', expr.toString());
-}
-
-/**
- * Validates that a CHECK constraint expression is deterministic.
- *
- * @param expr The constraint expression plan node
- * @param constraintName The name of the constraint (for error messages)
- * @param tableName The name of the table (for error messages)
- * @throws QuereusError if the expression is non-deterministic
- */
-export function validateDeterministicConstraint(
-	expr: ScalarPlanNode,
-	constraintName: string,
-	tableName: string
-): void {
-	validateDeterministicExpression(
-		expr,
-		`CHECK constraint '${constraintName}' on table '${tableName}'`
-	);
-}
-
-/**
- * Validates that a DEFAULT expression is deterministic.
- *
- * @param expr The default value expression plan node
- * @param columnName The name of the column (for error messages)
- * @param tableName The name of the table (for error messages)
- * @throws QuereusError if the expression is non-deterministic
- */
-export function validateDeterministicDefault(
-	expr: ScalarPlanNode,
-	columnName: string,
-	tableName: string
-): void {
-	validateDeterministicExpression(
-		expr,
-		`DEFAULT for column '${columnName}' in table '${tableName}'`
-	);
-}