@quereus/quereus 0.1.0

package/src/planner/nodes/array-index-node.ts

@@ -0,0 +1,50 @@
+import { PlanNodeType } from './plan-node-type.js';
+import { PlanNode, type ZeroAryScalarNode } from './plan-node.js';
+import type { ScalarType } from '../../common/datatype.js';
+import type { Scope } from '../scopes/scope.js';
+import type * as AST from '../../parser/ast.js';
+
+/**
+ * Represents direct access to a value in a row by array index.
+ * This is used when we know the exact position of a value in the output row.
+ */
+export class ArrayIndexNode extends PlanNode implements ZeroAryScalarNode {
+	override readonly nodeType = PlanNodeType.ArrayIndex;
+	public readonly expression: AST.Expression;
+
+	constructor(
+		scope: Scope,
+		public readonly index: number,
+		public readonly type: ScalarType
+	) {
+		super(scope);
+		// Create a synthetic expression for this array access
+		this.expression = {
+			type: 'literal',
+			value: `[${index}]`
+		} as AST.LiteralExpr;
+	}
+
+	getType(): ScalarType {
+		return this.type;
+	}
+
+	getChildren(): readonly [] {
+		return [];
+	}
+
+	getRelations(): readonly [] {
+		return [];
+	}
+
+	withChildren(newChildren: readonly PlanNode[]): PlanNode {
+		if (newChildren.length !== 0) {
+			throw new Error(`ArrayIndexNode expects 0 children, got ${newChildren.length}`);
+		}
+		return this; // No children, so no change
+	}
+
+	override toString(): string {
+		return `[${this.index}]`;
+	}
+}

package/src/planner/nodes/block.ts

@@ -0,0 +1,80 @@
+import { PlanNodeType } from './plan-node-type.js';
+import { PlanNode, type RelationalPlanNode } from './plan-node.js';
+import type { BaseType } from '../../common/datatype.js';
+import type { Scope } from '../scopes/scope.js';
+import type { SqlParameters } from '../../common/types.js';
+
+/**
+ * Represents a block of one or more statements to be executed in sequence.
+ * This is the root of most SQL query plans.
+ */
+export class BlockNode extends PlanNode {
+  override readonly nodeType = PlanNodeType.Block;
+
+  constructor(
+    scope: Scope,
+    public readonly statements: PlanNode[],
+    /** Snapshot of parameters utilized by the block. */
+    public readonly parameters: SqlParameters,
+    estimatedCostOverride?: number
+  ) {
+    // Cost: sum of all statement costs
+    const totalCost = statements.reduce((sum, stmt) => sum + stmt.getTotalCost(), 0);
+    super(scope, estimatedCostOverride ?? totalCost);
+  }
+
+  getType(): BaseType {
+    // A block doesn't have a well-defined type; it's context-dependent
+    return { typeClass: 'void' };
+  }
+
+  getChildren(): readonly PlanNode[] {
+    return this.statements;
+  }
+
+  getRelations(): readonly RelationalPlanNode[] {
+    return this.statements.filter(s => s.getType().typeClass === "relation") as unknown as readonly RelationalPlanNode[];
+  }
+
+  override toString(): string {
+    return `${this.statements.length} statements`;
+  }
+
+  override getLogicalAttributes(): Record<string, unknown> {
+    return {
+      numStatements: this.statements.length,
+      statementTypes: this.statements.map(stmt => stmt.nodeType),
+      parameters: Object.keys(this.parameters)
+    };
+  }
+
+  get estimatedRows(): number | undefined {
+    return this.getRelations().reduce((acc, s) => acc + (s.estimatedRows ?? 0), 0);
+  }
+
+  withChildren(newChildren: readonly PlanNode[]): PlanNode {
+    // Check if statements changed
+    if (newChildren.length !== this.statements.length) {
+      // Create new instance with new statements
+      return new BlockNode(
+        this.scope,
+        [...newChildren],
+        this.parameters
+      );
+    }
+
+    // Check if any individual statement changed
+    const statementsChanged = newChildren.some((child, i) => child !== this.statements[i]);
+
+    if (!statementsChanged) {
+      return this;
+    }
+
+    // Create new instance with updated statements
+    return new BlockNode(
+      this.scope,
+      [...newChildren],
+      this.parameters
+    );
+  }
+}

package/src/planner/nodes/cache-node.ts

@@ -0,0 +1,94 @@
+import { PlanNodeType } from './plan-node-type.js';
+import { PlanNode, type RelationalPlanNode, type UnaryRelationalNode, type Attribute } from './plan-node.js';
+import type { RelationType } from '../../common/datatype.js';
+import type { Scope } from '../scopes/scope.js';
+import { StatusCode } from '../../common/types.js';
+import { quereusError } from '../../common/errors.js';
+
+export type CacheStrategy = 'memory' | 'spill'; // Future: spill-to-disk
+
+/**
+ * CacheNode provides smart caching for any relational input.
+ *
+ * This node materializes its input on first iteration and serves
+ * subsequent iterations from the cached result. It implements
+ * smart threshold-based policies to avoid excessive memory usage.
+ */
+export class CacheNode extends PlanNode implements UnaryRelationalNode {
+	readonly nodeType = PlanNodeType.Cache;
+
+	constructor(
+		scope: Scope,
+		public readonly source: RelationalPlanNode,
+		public readonly strategy: CacheStrategy = 'memory',
+		public readonly threshold: number = 10000,  // Rows before switching to pass-through
+		estimatedCostOverride?: number
+	) {
+		super(scope, estimatedCostOverride);
+	}
+
+	// Cache preserves source attributes exactly
+	getAttributes(): Attribute[] {
+		return this.source.getAttributes();
+	}
+
+	getType(): RelationType {
+		const sourceType = this.source.getType();
+		// Cache preserves all properties of the source relation
+		return {
+			...sourceType,
+			// Note: Caching doesn't change the logical properties
+			// but may affect physical properties like ordering
+		};
+	}
+
+	getChildren(): readonly [RelationalPlanNode] {
+		return [this.source];
+	}
+
+	getRelations(): readonly [RelationalPlanNode] {
+		return [this.source];
+	}
+
+	withChildren(newChildren: readonly PlanNode[]): PlanNode {
+		if (newChildren.length !== 1) {
+			quereusError(`CacheNode expects 1 child, got ${newChildren.length}`, StatusCode.INTERNAL);
+		}
+
+		const [newSource] = newChildren;
+
+		// Type check
+		if (!('getAttributes' in newSource) || typeof (newSource as any).getAttributes !== 'function') {
+			quereusError('CacheNode: child must be a RelationalPlanNode', StatusCode.INTERNAL);
+		}
+
+		// Return same instance if nothing changed
+		if (newSource === this.source) {
+			return this;
+		}
+
+		// Create new instance preserving attributes (cache preserves source attributes exactly)
+		return new CacheNode(
+			this.scope,
+			newSource as RelationalPlanNode,
+			this.strategy,
+			this.threshold
+		);
+	}
+
+	get estimatedRows(): number | undefined {
+		return this.source.estimatedRows;
+	}
+
+	override toString(): string {
+		return `CACHE (${this.strategy}, threshold=${this.threshold})`;
+	}
+
+	override getLogicalAttributes(): Record<string, unknown> {
+		return {
+			strategy: this.strategy,
+			threshold: this.threshold,
+			sourceNodeType: this.source.nodeType
+		};
+	}
+}

package/src/planner/nodes/constraint-check-node.ts

@@ -0,0 +1,95 @@
+import type { Scope } from '../scopes/scope.js';
+import { PlanNode, type RelationalPlanNode, type Attribute, type RowDescriptor } from './plan-node.js';
+import { PlanNodeType } from './plan-node-type.js';
+import type { TableReferenceNode } from './reference.js';
+import type { RelationType } from '../../common/datatype.js';
+import type { RowOp } from '../../schema/table.js';
+
+/**
+ * Represents constraint checking for DML operations.
+ * This node validates constraints against rows flowing through it.
+ */
+export class ConstraintCheckNode extends PlanNode implements RelationalPlanNode {
+  override readonly nodeType = PlanNodeType.ConstraintCheck;
+
+  constructor(
+    scope: Scope,
+    public readonly source: RelationalPlanNode,
+    public readonly table: TableReferenceNode,
+    public readonly operation: RowOp,
+    public readonly oldRowDescriptor?: RowDescriptor,
+    public readonly newRowDescriptor?: RowDescriptor,
+  ) {
+    super(scope);
+  }
+
+  getType(): RelationType {
+    return this.source.getType();
+  }
+
+  getAttributes(): Attribute[] {
+    // ConstraintCheck passes through the same attributes as its source
+    return this.source.getAttributes();
+  }
+
+  getRelations(): readonly [RelationalPlanNode, TableReferenceNode] {
+    return [this.source, this.table];
+  }
+
+  getChildren(): readonly PlanNode[] {
+    return [this.source];
+  }
+
+  withChildren(newChildren: readonly PlanNode[]): PlanNode {
+    if (newChildren.length !== 1) {
+      throw new Error(`ConstraintCheckNode expects 1 child, got ${newChildren.length}`);
+    }
+
+    const [newSource] = newChildren;
+
+    // Type check
+    if (!('getAttributes' in newSource) || typeof (newSource as any).getAttributes !== 'function') {
+      throw new Error('ConstraintCheckNode: child must be a RelationalPlanNode');
+    }
+
+    // Return same instance if nothing changed
+    if (newSource === this.source) {
+      return this;
+    }
+
+    // Create new instance
+    return new ConstraintCheckNode(
+      this.scope,
+      newSource as RelationalPlanNode,
+      this.table,
+      this.operation,
+      this.oldRowDescriptor,
+      this.newRowDescriptor
+    );
+  }
+
+  get estimatedRows(): number | undefined {
+    return this.source.estimatedRows;
+  }
+
+  override toString(): string {
+    const opName = this.operation === 1 ? 'INSERT' :
+                   this.operation === 2 ? 'UPDATE' :
+                   this.operation === 4 ? 'DELETE' : 'UNKNOWN';
+    return `CHECK CONSTRAINTS ON ${opName}`;
+  }
+
+  override getLogicalAttributes(): Record<string, unknown> {
+    const opName = this.operation === 1 ? 'INSERT' :
+                   this.operation === 2 ? 'UPDATE' :
+                   this.operation === 4 ? 'DELETE' : 'UNKNOWN';
+
+    return {
+      table: this.table.tableSchema.name,
+      schema: this.table.tableSchema.schemaName,
+      operation: opName,
+      hasOldDescriptor: !!this.oldRowDescriptor,
+      hasNewDescriptor: !!this.newRowDescriptor,
+    };
+  }
+}

package/src/planner/nodes/create-index-node.ts

@@ -0,0 +1,37 @@
+import type * as AST from '../../parser/ast.js';
+import type { Scope } from '../scopes/scope.js';
+import { VoidNode } from './plan-node.js';
+import { PlanNodeType } from './plan-node-type.js';
+import { expressionToString } from '../../util/ast-stringify.js';
+
+/**
+ * Represents a CREATE INDEX statement in the logical query plan.
+ */
+export class CreateIndexNode extends VoidNode {
+  override readonly nodeType = PlanNodeType.CreateIndex;
+
+  constructor(
+    scope: Scope,
+    public readonly statementAst: AST.CreateIndexStmt,
+  ) {
+    super(scope);
+  }
+
+  override toString(): string {
+    const uniquePrefix = this.statementAst.isUnique ? 'UNIQUE ' : '';
+    return `CREATE ${uniquePrefix}INDEX ${this.statementAst.index.name} ON ${this.statementAst.table.name}`;
+  }
+
+  override getLogicalAttributes(): Record<string, unknown> {
+    return {
+      index: this.statementAst.index.name,
+      table: this.statementAst.table.name,
+      schema: this.statementAst.table.schema,
+      isUnique: this.statementAst.isUnique,
+      ifNotExists: this.statementAst.ifNotExists,
+      columns: this.statementAst.columns.map(col => col.name || expressionToString(col.expr!)),
+      hasWhereClause: !!this.statementAst.where,
+      statement: expressionToString(this.statementAst as any) // Convert AST to string
+    };
+  }
+}

package/src/planner/nodes/create-table-node.ts

@@ -0,0 +1,31 @@
+import type * as AST from '../../parser/ast.js';
+import type { Scope } from '../scopes/scope.js';
+import { VoidNode } from './plan-node.js';
+import { PlanNodeType } from './plan-node-type.js';
+import { expressionToString } from '../../util/ast-stringify.js';
+
+/**
+ * Represents a CREATE TABLE statement in the logical query plan.
+ */
+export class CreateTableNode extends VoidNode {
+  override readonly nodeType = PlanNodeType.CreateTable;
+
+  constructor(
+    scope: Scope,
+		public readonly statementAst: AST.CreateTableStmt,
+  ) {
+    super(scope);
+  }
+
+  override toString(): string {
+    return `CREATE TABLE ${this.statementAst.table.name}`;
+  }
+
+  override getLogicalAttributes(): Record<string, unknown> {
+    return {
+      table: this.statementAst.table.name,
+      schema: this.statementAst.table.schema,
+      statement: expressionToString(this.statementAst as any) // Convert AST to string
+    };
+  }
+}

package/src/planner/nodes/create-view-node.ts

@@ -0,0 +1,40 @@
+import type * as AST from '../../parser/ast.js';
+import { VoidNode } from './plan-node.js';
+import { PlanNodeType } from './plan-node-type.js';
+import type { Scope } from '../scopes/scope.js';
+
+/**
+ * Plan node for CREATE VIEW statements.
+ * Creates a new view definition in the schema.
+ */
+export class CreateViewNode extends VoidNode {
+	readonly nodeType = PlanNodeType.CreateView;
+
+	constructor(
+		scope: Scope,
+		public readonly viewName: string,
+		public readonly schemaName: string,
+		public readonly ifNotExists: boolean,
+		public readonly columns: string[] | undefined,
+		public readonly selectStmt: AST.SelectStmt,
+		public readonly sql: string
+	) {
+		super(scope, 1); // Low cost for DDL operations
+	}
+
+	override toString(): string {
+		const ifNotExistsClause = this.ifNotExists ? 'IF NOT EXISTS ' : '';
+		const columnsClause = this.columns ? `(${this.columns.join(', ')})` : '';
+		return `CREATE VIEW ${ifNotExistsClause}${this.schemaName}.${this.viewName}${columnsClause}`;
+	}
+
+	override getLogicalAttributes(): Record<string, unknown> {
+		return {
+			viewName: this.viewName,
+			schemaName: this.schemaName,
+			ifNotExists: this.ifNotExists,
+			columns: this.columns,
+			selectSql: this.sql
+		};
+	}
+}

package/src/planner/nodes/cte-node.ts

@@ -0,0 +1,111 @@
+import { PlanNode, type UnaryRelationalNode, type RelationalPlanNode, type Attribute, type TableDescriptor } from './plan-node.js';
+import type { RelationType } from '../../common/datatype.js';
+import { PlanNodeType } from './plan-node-type.js';
+import type { Scope } from '../scopes/scope.js';
+import { Cached } from '../../util/cached.js';
+
+/**
+ * Common interface for all CTE nodes (regular and recursive)
+ */
+export interface CTEPlanNode extends UnaryRelationalNode {
+	readonly cteName: string;
+	readonly columns: string[] | undefined;
+	readonly materializationHint: 'materialized' | 'not_materialized' | undefined;
+	readonly isRecursive: boolean;
+	readonly tableDescriptor: TableDescriptor;
+}
+
+/**
+ * Plan node for Common Table Expressions (CTEs).
+ * This represents a single CTE definition within a WITH clause.
+ */
+export class CTENode extends PlanNode implements CTEPlanNode {
+	readonly nodeType = PlanNodeType.CTE;
+	readonly tableDescriptor: TableDescriptor = {}; // Identity object for table context lookup
+
+	private attributesCache: Cached<Attribute[]>;
+	private typeCache: Cached<RelationType>;
+
+	constructor(
+		scope: Scope,
+		public readonly cteName: string,
+		public readonly columns: string[] | undefined,
+		public readonly source: RelationalPlanNode,
+		public readonly materializationHint: 'materialized' | 'not_materialized' | undefined,
+		public readonly isRecursive: boolean = false
+	) {
+		super(scope, source.getTotalCost() + 10); // Add small overhead for CTE materialization
+		this.attributesCache = new Cached(() => this.buildAttributes());
+		this.typeCache = new Cached(() => this.buildType());
+	}
+
+	private buildAttributes(): Attribute[] {
+		const queryAttributes = this.source.getAttributes();
+
+		// Use explicit column names if provided, otherwise use query output column names
+		const queryType = this.source.getType();
+		const columnNames = this.columns || queryType.columns.map((c: any) => c.name);
+
+		return queryAttributes.map((attr: any, index: number) => ({
+			id: PlanNode.nextAttrId(),
+			name: columnNames[index] || attr.name,
+			type: attr.type,
+			sourceRelation: `cte:${this.cteName}`
+		}));
+	}
+
+	private buildType(): RelationType {
+		const queryType = this.source.getType();
+		return {
+			typeClass: 'relation',
+			isReadOnly: false,
+			isSet: queryType.isSet, // CTEs preserve the set/bag nature of their query
+			columns: this.getAttributes().map((attr: any) => ({
+				name: attr.name,
+				type: attr.type
+			})),
+			keys: [], // CTEs don't have inherent keys
+			rowConstraints: []
+		};
+	}
+
+	getAttributes(): Attribute[] {
+		return this.attributesCache.value;
+	}
+
+	getType(): RelationType {
+		return this.typeCache.value;
+	}
+
+	getChildren(): readonly [] {
+		return [];
+	}
+
+	getRelations(): readonly [RelationalPlanNode] {
+		return [this.source];
+	}
+
+	withChildren(newChildren: readonly PlanNode[]): PlanNode {
+		if (newChildren.length !== 0) {
+			throw new Error(`CTENode expects 0 children, got ${newChildren.length}`);
+		}
+		return this; // No children in getChildren(), source is accessed via getRelations()
+	}
+
+	override toString(): string {
+		const recursiveText = this.isRecursive ? 'RECURSIVE ' : '';
+		const columnsText = this.columns ? `(${this.columns.join(', ')})` : '';
+		const materializationText = this.materializationHint ? ` ${this.materializationHint.toUpperCase()}` : '';
+		return `${recursiveText}CTE ${this.cteName}${columnsText}${materializationText}`;
+	}
+
+	override getLogicalAttributes(): Record<string, unknown> {
+		return {
+			cteName: this.cteName,
+			columns: this.columns,
+			materializationHint: this.materializationHint,
+			isRecursive: this.isRecursive,
+			queryType: this.getType()
+		};
+	}
+}

package/src/planner/nodes/cte-reference-node.ts

@@ -0,0 +1,89 @@
+import { PlanNode, type UnaryRelationalNode, type RelationalPlanNode, type Attribute } from './plan-node.js';
+import type { RelationType } from '../../common/datatype.js';
+import { PlanNodeType } from './plan-node-type.js';
+import type { Scope } from '../scopes/scope.js';
+import type { CTEPlanNode } from './cte-node.js';
+import { Cached } from '../../util/cached.js';
+
+/**
+ * Plan node for referencing a CTE in a FROM clause.
+ * This points to a materialized CTE result.
+ */
+export class CTEReferenceNode extends PlanNode implements UnaryRelationalNode {
+	readonly nodeType = PlanNodeType.CTEReference;
+
+	private attributesCache: Cached<Attribute[]>;
+	private typeCache: Cached<RelationType>;
+
+	constructor(
+		scope: Scope,
+		public readonly source: CTEPlanNode,
+		public readonly alias?: string
+	) {
+		super(scope, 5); // Low cost since CTEs are materialized
+		this.attributesCache = new Cached(() => this.buildAttributes());
+		this.typeCache = new Cached(() => this.buildType());
+	}
+
+	private buildAttributes(): Attribute[] {
+		// Preserve original attribute IDs from the CTE to ensure proper context resolution
+		// especially important for recursive CTEs where working table substitution occurs
+		return this.source.getAttributes().map((attr: any) => ({
+			id: attr.id, // Preserve original ID instead of creating new one
+			name: attr.name,
+			type: attr.type,
+			sourceRelation: `cte_ref:${this.source.cteName}`
+		}));
+	}
+
+	private buildType(): RelationType {
+		const cteType = this.source.getType();
+		return {
+			typeClass: 'relation',
+			isReadOnly: false,
+			isSet: cteType.isSet,
+			columns: this.getAttributes().map((attr: any) => ({
+				name: attr.name,
+				type: attr.type
+			})),
+			keys: [], // CTE references don't have inherent keys
+			rowConstraints: []
+		};
+	}
+
+	getAttributes(): Attribute[] {
+		return this.attributesCache.value;
+	}
+
+	getType(): RelationType {
+		return this.typeCache.value;
+	}
+
+	getChildren(): readonly [] {
+		return [];
+	}
+
+	getRelations(): readonly [RelationalPlanNode] {
+		return [this.source];
+	}
+
+	withChildren(newChildren: readonly PlanNode[]): PlanNode {
+		if (newChildren.length !== 0) {
+			throw new Error(`CTEReferenceNode expects 0 children, got ${newChildren.length}`);
+		}
+		return this; // No children in getChildren(), source is accessed via getRelations()
+	}
+
+	override toString(): string {
+		const aliasText = this.alias ? ` AS ${this.alias}` : '';
+		return `CTE_REF ${this.source.cteName}${aliasText}`;
+	}
+
+	override getLogicalAttributes(): Record<string, unknown> {
+		return {
+			cteName: this.source.cteName,
+			alias: this.alias,
+			materializationHint: this.source.materializationHint
+		};
+	}
+}