@quereus/quereus 0.7.2 → 0.7.4

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

@@ -1,267 +0,0 @@
-import { PlanNodeType } from './plan-node-type.js';
-import { PlanNode, type RelationalPlanNode, type ScalarPlanNode, type UnaryRelationalNode, type Attribute, isRelationalNode, type PhysicalProperties } from './plan-node.js';
-import { ColumnReferenceNode } from './reference.js';
-import type { RelationType } from '../../common/datatype.js';
-import type { Scope } from '../scopes/scope.js';
-import { Cached } from '../../util/cached.js';
-import { formatExpressionList } from '../../util/plan-formatter.js';
-import { StatusCode } from '../../common/types.js';
-import { quereusError } from '../../common/errors.js';
-import type { AggregationCapable } from '../framework/characteristics.js';
-
-export interface AggregateExpression {
-  expression: ScalarPlanNode;
-  alias: string;
-}
-
-/**
- * Logical node representing an aggregate operation.
- * Requires transformation to StreamAggregateNode or HashAggregateNode by optimizer.
- */
-export class AggregateNode extends PlanNode implements UnaryRelationalNode, AggregationCapable {
-  override readonly nodeType = PlanNodeType.Aggregate;
-
-  private outputTypeCache: Cached<RelationType>;
-  private attributesCache: Cached<Attribute[]>;
-
-  constructor(
-    scope: Scope,
-    public readonly source: RelationalPlanNode,
-    public readonly groupBy: readonly ScalarPlanNode[],
-    public readonly aggregates: readonly AggregateExpression[],
-    estimatedCostOverride?: number,
-    public readonly preserveAttributeIds?: readonly Attribute[]
-  ) {
-    super(scope, estimatedCostOverride ?? source.getTotalCost());
-
-    this.outputTypeCache = new Cached(() => this.buildOutputType());
-    this.attributesCache = new Cached(() => this.buildAttributes());
-  }
-
-  // Helper function to extract a meaningful name from a GROUP BY expression
-  private getGroupByColumnName(expr: ScalarPlanNode, index: number): string {
-    // If it's a column reference, use the column name
-    if (expr.nodeType === PlanNodeType.ColumnReference) {
-      const colRef = expr as ColumnReferenceNode;
-      return colRef.expression.name;
-    }
-    // Otherwise, use a generic name
-    return `group_${index}`;
-  }
-
-  private buildOutputType(): RelationType {
-    // Build the output relation type based on group by columns and aggregates
-    const columns = [
-      // Group by columns come first
-      ...this.groupBy.map((expr, index) => ({
-        name: this.getGroupByColumnName(expr, index),
-        type: expr.getType(),
-        generated: false
-      })),
-      // Then aggregate columns
-      ...this.aggregates.map(agg => ({
-        name: agg.alias,
-        type: agg.expression.getType(),
-        generated: true
-      }))
-    ];
-
-    // Determine if result is a set
-    // - Without GROUP BY: always produces exactly 1 row, so it's a set
-    // - With GROUP BY: produces one row per unique group, so it's a set
-    const isSet = true;
-
-    return {
-      typeClass: 'relation',
-      columns,
-      keys: [], // No keys for aggregate results
-      rowConstraints: [], // No row constraints for aggregate results
-      isReadOnly: true,
-      isSet
-    };
-  }
-
-  private buildAttributes(): Attribute[] {
-    // If we have preserved attribute IDs, use them
-    if (this.preserveAttributeIds) {
-      return this.preserveAttributeIds.slice(); // Return a copy
-    }
-
-    const attributes: Attribute[] = [];
-
-    // Group by columns come first
-    this.groupBy.forEach((expr, index) => {
-      const name = this.getGroupByColumnName(expr, index);
-      attributes.push({
-        id: PlanNode.nextAttrId(),
-        name,
-        type: expr.getType(),
-        sourceRelation: `${this.nodeType}:${this.id}`,
-        relationName: 'aggregate' // AggregateNode creates new relation context
-      });
-    });
-
-    // Then aggregate columns
-    this.aggregates.forEach((agg) => {
-      attributes.push({
-        id: PlanNode.nextAttrId(),
-        name: agg.alias,
-        type: agg.expression.getType(),
-        sourceRelation: `${this.nodeType}:${this.id}`,
-        relationName: 'aggregate' // AggregateNode creates new relation context
-      });
-    });
-
-    return attributes;
-  }
-
-  getType(): RelationType {
-    return this.outputTypeCache.value;
-  }
-
-  getAttributes(): readonly Attribute[] {
-    return this.attributesCache.value;
-  }
-
-  getChildren(): readonly PlanNode[] {
-    return [this.source, ...this.groupBy, ...this.aggregates.map(agg => agg.expression)];
-  }
-
-  getRelations(): readonly [RelationalPlanNode] {
-    return [this.source];
-  }
-
-  withChildren(newChildren: readonly PlanNode[]): PlanNode {
-    const expectedLength = 1 + this.groupBy.length + this.aggregates.length;
-    if (newChildren.length !== expectedLength) {
-      quereusError(`AggregateNode expects ${expectedLength} children, got ${newChildren.length}`, StatusCode.INTERNAL);
-    }
-
-    const [newSource, ...restChildren] = newChildren;
-    const newGroupBy = restChildren.slice(0, this.groupBy.length);
-    const newAggregateExpressions = restChildren.slice(this.groupBy.length);
-
-    // Type check
-    if (!isRelationalNode(newSource)) {
-      quereusError('AggregateNode: first child must be a RelationalPlanNode', StatusCode.INTERNAL);
-    }
-
-    // Check if anything changed
-    const sourceChanged = newSource !== this.source;
-    const groupByChanged = newGroupBy.some((expr, i) => expr !== this.groupBy[i]);
-    const aggregatesChanged = newAggregateExpressions.some((expr, i) => expr !== this.aggregates[i].expression);
-
-    if (!sourceChanged && !groupByChanged && !aggregatesChanged) {
-      return this;
-    }
-
-    // Build new aggregates array
-    const newAggregates = newAggregateExpressions.map((expr, i) => ({
-      expression: expr as ScalarPlanNode,
-      alias: this.aggregates[i].alias
-    }));
-
-    // Create new instance that preserves original attribute IDs
-    return new AggregateNode(
-      this.scope,
-      newSource as RelationalPlanNode,
-      newGroupBy as ScalarPlanNode[],
-      newAggregates,
-      undefined, // estimatedCostOverride
-      this.getAttributes() // Preserve original attribute IDs
-    );
-  }
-
-  get estimatedRows(): number | undefined {
-    const sourceRows = this.source.estimatedRows;
-    if (sourceRows === undefined) return undefined;
-
-    // If we have GROUP BY, the output rows depend on the number of distinct groups
-    // For now, we'll use a conservative estimate
-    if (this.groupBy.length > 0) {
-      // Estimate that we'll have at most sourceRows/2 groups, but at least 1
-      return Math.max(1, Math.floor(sourceRows / 2));
-    } else {
-      // No GROUP BY means we're aggregating the entire table into a single row
-      return 1;
-    }
-  }
-
-  computePhysical(childrenPhysical: PhysicalProperties[]): Partial<PhysicalProperties> {
-    const sourcePhysical = childrenPhysical[0];
-    const groupCount = this.groupBy.length;
-    // If there is a GROUP BY, the group-by columns form a unique key on the output
-    // Output attribute indices for group-by are 0..groupCount-1 per buildAttributes
-    const uniqueKeys = groupCount > 0 ? [Array.from({ length: groupCount }, (_, i) => i)] : [[]];
-    return {
-      uniqueKeys,
-      estimatedRows: this.estimatedRows,
-      ordering: sourcePhysical?.ordering,
-    };
-  }
-
-  override toString(): string {
-    const parts: string[] = [];
-
-    if (this.groupBy.length > 0) {
-      parts.push(`GROUP BY ${formatExpressionList(this.groupBy)}`);
-    }
-
-    if (this.aggregates.length > 0) {
-      const aggregatesStr = this.aggregates.map(agg =>
-        `${agg.expression.toString()} AS ${agg.alias}`
-      ).join(', ');
-      parts.push(`AGG ${aggregatesStr}`);
-    }
-
-    return parts.join('  ');
-  }
-
-  override getLogicalAttributes(): Record<string, unknown> {
-    const props: Record<string, unknown> = {};
-
-    if (this.groupBy.length > 0) {
-      props.groupBy = this.groupBy.map(expr => expr.toString());
-    }
-
-    if (this.aggregates.length > 0) {
-      props.aggregates = this.aggregates.map(agg => ({
-        expression: agg.expression.toString(),
-        alias: agg.alias
-      }));
-    }
-
-    // Expose logical unique keys: group-by columns (0..groupCount-1) or [[]] for global aggregate
-    const groupCount = this.groupBy.length;
-    (props as any).uniqueKeys = groupCount > 0 ? [Array.from({ length: groupCount }, (_, i) => i)] : [[]];
-    return props;
-  }
-
-  // AggregationCapable interface implementation
-  getGroupingKeys(): readonly ScalarPlanNode[] {
-    return this.groupBy;
-  }
-
-  getAggregateExpressions(): readonly { expr: ScalarPlanNode; alias: string; attributeId: number }[] {
-    const attributes = this.getAttributes();
-    const groupByCount = this.groupBy.length;
-
-    return this.aggregates.map((agg, index) => ({
-      expr: agg.expression,
-      alias: agg.alias,
-      attributeId: attributes[groupByCount + index].id
-    }));
-  }
-
-  requiresOrdering(): boolean {
-    return this.groupBy.length > 0; // Only requires ordering if we have GROUP BY
-  }
-
-  canStreamAggregate(): boolean {
-    return true; // AggregateNode can always be converted to streaming
-  }
-
-	getSource(): RelationalPlanNode {
-		return this.source;
-	}
-}

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

@@ -1,50 +0,0 @@
-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}]`
-		} satisfies 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

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

@@ -1,103 +0,0 @@
-import { PlanNodeType } from './plan-node-type.js';
-import { PlanNode, type RelationalPlanNode, type UnaryRelationalNode, type Attribute, isRelationalNode } 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';
-import type { CacheCapable } from '../framework/characteristics.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, CacheCapable {
-	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(): readonly 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 (!isRelationalNode(newSource)) {
-			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;
-	}
-
-	getCacheStrategy(): string {
-		return this.strategy;
-	}
-
-	isCached(): boolean {
-		return true;
-	}
-
-	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

@@ -1,138 +0,0 @@
-import type { Scope } from '../scopes/scope.js';
-import { PlanNode, type RelationalPlanNode, type Attribute, type RowDescriptor, type ScalarPlanNode, isRelationalNode, isScalarNode } 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 { RowOpFlag } from '../../schema/table.js';
-import type { RowConstraintSchema } from '../../schema/table.js';
-
-export interface ConstraintCheck {
-  constraint: RowConstraintSchema;  // The constraint metadata
-  expression: ScalarPlanNode;       // Pre-built expression node
-  deferrable?: boolean;
-  initiallyDeferred?: boolean;
-  containsSubquery: boolean;        // Cached result of subquery detection
-}
-
-/**
- * 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: RowOpFlag,
-    public readonly oldRowDescriptor: RowDescriptor | undefined,
-    public readonly newRowDescriptor: RowDescriptor | undefined,
-    public readonly flatRowDescriptor: RowDescriptor,
-    public readonly constraintChecks: ConstraintCheck[],
-    public readonly mutationContextValues?: Map<string, ScalarPlanNode>, // Mutation context value expressions
-    public readonly contextAttributes?: Attribute[], // Mutation context attributes
-    public readonly contextDescriptor?: RowDescriptor, // Mutation context row descriptor
-  ) {
-    super(scope);
-  }
-
-  getType(): RelationType {
-    return this.source.getType();
-  }
-
-  getAttributes(): readonly 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[] {
-    const children: PlanNode[] = [this.source];
-    // Add all constraint expression nodes as children so optimizer can see them
-    this.constraintChecks.forEach(check => {
-      children.push(check.expression);
-    });
-    return children;
-  }
-
-  withChildren(newChildren: readonly PlanNode[]): PlanNode {
-    const expectedChildren = 1 + this.constraintChecks.length;
-    if (newChildren.length !== expectedChildren) {
-      throw new Error(`ConstraintCheckNode expects ${expectedChildren} children, got ${newChildren.length}`);
-    }
-
-    const [newSource, ...newConstraintExprs] = newChildren;
-
-    // Type check the source
-    if (!isRelationalNode(newSource)) {
-      throw new Error('ConstraintCheckNode: first child must be a RelationalPlanNode');
-    }
-
-    // Type check constraint expressions
-    for (let i = 0; i < newConstraintExprs.length; i++) {
-      const expr = newConstraintExprs[i];
-      if (!isScalarNode(expr)) {
-        throw new Error(`ConstraintCheckNode: constraint child ${i + 1} must be a ScalarPlanNode`);
-      }
-    }
-
-    // Return same instance if nothing changed
-    if (newSource === this.source &&
-        newConstraintExprs.every((expr, i) => expr === this.constraintChecks[i].expression)) {
-      return this;
-    }
-
-    // Rebuild constraint checks with new expressions
-    const newConstraintChecks = this.constraintChecks.map((check, i) => ({
-      ...check,
-      expression: newConstraintExprs[i] as ScalarPlanNode
-    }));
-
-    // Create new instance
-    return new ConstraintCheckNode(
-      this.scope,
-      newSource as RelationalPlanNode,
-      this.table,
-      this.operation,
-      this.oldRowDescriptor,
-      this.newRowDescriptor,
-      this.flatRowDescriptor,
-      newConstraintChecks,
-      this.mutationContextValues,
-      this.contextAttributes,
-      this.contextDescriptor
-    );
-  }
-
-  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';
-    const constraintCount = this.constraintChecks.length;
-    return `CHECK ${constraintCount} 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,
-      constraintCount: this.constraintChecks.length,
-      constraintNames: this.constraintChecks.map(c => c.constraint.name || '_unnamed'),
-      hasOldDescriptor: !!this.oldRowDescriptor,
-      hasNewDescriptor: !!this.newRowDescriptor,
-    };
-  }
-}

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

@@ -1,51 +0,0 @@
-import type { Scope } from '../scopes/scope.js';
-import { PlanNode, type VoidNode, type PhysicalProperties } from './plan-node.js';
-import { PlanNodeType } from './plan-node-type.js';
-import type { VoidType } from '../../common/datatype.js';
-import type * as AST from '../../parser/ast.js';
-
-/**
- * Represents creating a global integrity assertion.
- * This is a DDL operation that adds an assertion to the schema.
- */
-export class CreateAssertionNode extends PlanNode implements VoidNode {
-  override readonly nodeType = PlanNodeType.CreateAssertion;
-
-  constructor(
-    scope: Scope,
-    public readonly name: string,
-    public readonly checkExpression: AST.Expression,
-  ) {
-    super(scope);
-  }
-
-  getType(): VoidType {
-    return { typeClass: 'void' };
-  }
-
-  getChildren(): readonly PlanNode[] {
-    return [];
-  }
-
-  withChildren(newChildren: readonly PlanNode[]): PlanNode {
-    if (newChildren.length !== 0) {
-      throw new Error(`CreateAssertionNode expects 0 children, got ${newChildren.length}`);
-    }
-    return this; // No children, so no change
-  }
-
-  override toString(): string {
-    return `CREATE ASSERTION ${this.name}`;
-  }
-
-  override getLogicalAttributes(): Record<string, unknown> {
-    return {
-      name: this.name,
-      checkExpression: this.checkExpression.toString?.() || 'complex expression',
-    };
-  }
-
-  override computePhysical(_children: readonly PhysicalProperties[]): Partial<PhysicalProperties> {
-    return { readonly: false };
-  }
-}