@quereus/quereus 0.2.0 → 0.4.0

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

@@ -1,8 +1,26 @@
 import { PlanNode, type UnaryRelationalNode, type RelationalPlanNode, type Attribute, type TableDescriptor, isRelationalNode } from './plan-node.js';
-import type { RelationType } from '../../common/datatype.js';
+import type { RelationType, ScalarType } from '../../common/datatype.js';
+import { SqlDataType } from '../../common/types.js';
 import { PlanNodeType } from './plan-node-type.js';
 import type { Scope } from '../scopes/scope.js';
 import { Cached } from '../../util/cached.js';
+import type { CTECapable } from '../framework/characteristics.js';
+
+/**
+ * Narrow contract that any node must satisfy to be placed in the CTE lookup map
+ * while planning.  Both regular `CTENode`s and the internal placeholder used
+ * for the recursive working table satisfy this contract.
+ */
+export interface CTEScopeNode extends PlanNode {
+    /** Lower-cased CTE name */
+    readonly cteName: string;
+
+    /** Column metadata produced by this CTE when referenced */
+    getAttributes(): readonly Attribute[];
+
+    /** Relation type for the CTE output */
+    getType(): RelationType;
+}
 
 /**
  * Common interface for all CTE nodes (regular and recursive)
@@ -19,7 +37,7 @@ export interface CTEPlanNode extends UnaryRelationalNode {
  * Plan node for Common Table Expressions (CTEs).
  * This represents a single CTE definition within a WITH clause.
  */
-export class CTENode extends PlanNode implements CTEPlanNode {
+export class CTENode extends PlanNode implements CTEPlanNode, CTEScopeNode, CTECapable {
 	readonly nodeType = PlanNodeType.CTE;
 	readonly tableDescriptor: TableDescriptor = {}; // Identity object for table context lookup
 
@@ -42,18 +60,21 @@ export class CTENode extends PlanNode implements CTEPlanNode {
 	private buildAttributes(): Attribute[] {
 		const queryAttributes = this.source.getAttributes();
 		const queryType = this.source.getType();
+		// eslint-disable-next-line @typescript-eslint/no-explicit-any
 		const columnNames = this.columns || queryType.columns.map((c: any) => c.name);
 
 		return columnNames.map((name: string) => {
 			const srcAttr = queryAttributes.find(a => a.name.toLowerCase() === name.toLowerCase());
+			// eslint-disable-next-line @typescript-eslint/no-explicit-any
 			let resolvedType: any = srcAttr?.type;
 			if (!resolvedType) {
+				// eslint-disable-next-line @typescript-eslint/no-explicit-any
 				const colMeta = queryType.columns.find((c: any) => c.name.toLowerCase() === name.toLowerCase());
 				resolvedType = colMeta?.type;
 			}
 			// Fallback: generic TEXT scalar if nothing else is available (should not normally happen)
 			if (!resolvedType) {
-				resolvedType = { typeClass: 'scalar', affinity: 'TEXT', nullable: true, isReadOnly: false } as any;
+				resolvedType = { typeClass: 'scalar', affinity: SqlDataType.TEXT, nullable: true, isReadOnly: false } satisfies ScalarType;
 			}
 			return {
 				id: srcAttr?.id ?? PlanNode.nextAttrId(),
@@ -70,6 +91,7 @@ export class CTENode extends PlanNode implements CTEPlanNode {
 			typeClass: 'relation',
 			isReadOnly: false,
 			isSet: queryType.isSet, // CTEs preserve the set/bag nature of their query
+			// eslint-disable-next-line @typescript-eslint/no-explicit-any
 			columns: this.getAttributes().map((attr: any) => ({
 				name: attr.name,
 				type: attr.type
@@ -79,7 +101,7 @@ export class CTENode extends PlanNode implements CTEPlanNode {
 		};
 	}
 
-	getAttributes(): Attribute[] {
+	getAttributes(): readonly Attribute[] {
 		return this.attributesCache.value;
 	}
 
@@ -123,6 +145,10 @@ export class CTENode extends PlanNode implements CTEPlanNode {
 		);
 	}
 
+	getCTESource(): RelationalPlanNode {
+		return this.source;
+	}
+
 	override toString(): string {
 		const recursiveText = this.isRecursive ? 'RECURSIVE ' : '';
 		const columnsText = this.columns ? `(${this.columns.join(', ')})` : '';

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

@@ -43,7 +43,7 @@ export class CTEReferenceNode extends PlanNode implements RelationalPlanNode {
 		const relationName = this.alias || this.source.cteName;
 		// Only use fresh IDs when we have an alias that differs from the CTE name
 		const useFreshIds = this.alias !== undefined && this.alias.toLowerCase() !== this.source.cteName.toLowerCase();
-		return this.source.getAttributes().map((attr: any) => ({
+		return this.source.getAttributes().map((attr) => ({
 			id: useFreshIds ? PlanNode.nextAttrId() : attr.id,
 			name: attr.name,
 			type: attr.type,
@@ -58,7 +58,7 @@ export class CTEReferenceNode extends PlanNode implements RelationalPlanNode {
 			typeClass: 'relation',
 			isReadOnly: false,
 			isSet: cteType.isSet,
-			columns: this.getAttributes().map((attr: any) => ({
+			columns: this.getAttributes().map(attr => ({
 				name: attr.name,
 				type: attr.type
 			})),

package/src/planner/nodes/declarative-schema.ts

@@ -0,0 +1,221 @@
+import { PlanNode, type VoidNode, type RelationalPlanNode, Attribute } from './plan-node.js';
+import { PlanNodeType } from './plan-node-type.js';
+import type { Scope } from '../scopes/scope.js';
+import type * as AST from '../../parser/ast.js';
+import { RelationType, type VoidType } from '../../common/datatype.js';
+import { SqlDataType } from '../../common/types.js';
+
+/**
+ * DECLARE SCHEMA statement plan node
+ */
+export class DeclareSchemaNode extends PlanNode implements VoidNode {
+	override readonly nodeType = PlanNodeType.DeclareSchema;
+
+	constructor(
+		scope: Scope,
+		public readonly statementAst: AST.DeclareSchemaStmt
+	) {
+		super(scope, 1);
+	}
+
+	getType(): VoidType {
+		return { typeClass: 'void' };
+	}
+
+	getChildren(): PlanNode[] {
+		return [];
+	}
+
+	withChildren(_newChildren: readonly PlanNode[]): PlanNode {
+		return new DeclareSchemaNode(this.scope, this.statementAst);
+	}
+
+	override toString(): string {
+		return `DECLARE SCHEMA ${this.statementAst.schemaName || 'main'}`;
+	}
+
+	override getLogicalAttributes(): Record<string, unknown> {
+		return {
+			type: 'declareSchema',
+			schemaName: this.statementAst.schemaName || 'main',
+			itemCount: this.statementAst.items.length
+		};
+	}
+}
+
+/**
+ * DIFF SCHEMA statement plan node - returns DDL statements as rows
+ */
+export class DiffSchemaNode extends PlanNode implements RelationalPlanNode {
+	override readonly nodeType = PlanNodeType.DiffSchema;
+
+	constructor(
+		scope: Scope,
+		public readonly statementAst: AST.DiffSchemaStmt
+	) {
+		super(scope, 1);
+	}
+
+	getType(): RelationType {
+		return {
+			typeClass: 'relation',
+			isReadOnly: true,
+			isSet: false, // DDL statements can have duplicates (though unlikely)
+			columns: [
+				{
+					name: 'ddl',
+					type: {
+						typeClass: 'scalar',
+						affinity: SqlDataType.TEXT,
+						nullable: false,
+						isReadOnly: true,
+					},
+					generated: true,
+				}
+			],
+			keys: [],
+			rowConstraints: [],
+		};
+	}
+
+	get estimatedRows(): number | undefined {
+		return 10; // Estimated number of migration statements
+	}
+
+	getAttributes(): Attribute[] {
+		return this.getType().columns.map((column) => ({
+			id: PlanNode.nextAttrId(),
+			name: column.name,
+			type: column.type,
+			sourceRelation: `${this.nodeType}:${this.id}`
+		}));
+	}
+
+	getChildren(): PlanNode[] {
+		return [];
+	}
+
+	withChildren(_newChildren: readonly PlanNode[]): PlanNode {
+		return new DiffSchemaNode(this.scope, this.statementAst);
+	}
+
+	override toString(): string {
+		return `DIFF SCHEMA ${this.statementAst.schemaName || 'main'}`;
+	}
+
+	override getLogicalAttributes(): Record<string, unknown> {
+		return {
+			type: 'diffSchema',
+			schemaName: this.statementAst.schemaName || 'main'
+		};
+	}
+}
+
+/**
+ * APPLY SCHEMA statement plan node
+ */
+export class ApplySchemaNode extends PlanNode implements VoidNode {
+	override readonly nodeType = PlanNodeType.ApplySchema;
+
+	constructor(
+		scope: Scope,
+		public readonly statementAst: AST.ApplySchemaStmt
+	) {
+		super(scope, 1);
+	}
+
+	getType(): VoidType {
+		return { typeClass: 'void' };
+	}
+
+	getChildren(): PlanNode[] {
+		return [];
+	}
+
+	withChildren(_newChildren: readonly PlanNode[]): PlanNode {
+		return new ApplySchemaNode(this.scope, this.statementAst);
+	}
+
+	override toString(): string {
+		return `APPLY SCHEMA ${this.statementAst.schemaName || 'main'}${this.statementAst.withSeed ? ' WITH SEED' : ''}`;
+	}
+
+	override getLogicalAttributes(): Record<string, unknown> {
+		return {
+			type: 'applySchema',
+			schemaName: this.statementAst.schemaName || 'main',
+			withSeed: this.statementAst.withSeed || false
+		};
+	}
+}
+
+/**
+ * EXPLAIN SCHEMA statement plan node - returns result rows with hash info
+ */
+export class ExplainSchemaNode extends PlanNode implements RelationalPlanNode {
+	override readonly nodeType = PlanNodeType.ExplainSchema;
+
+	constructor(
+		scope: Scope,
+		public readonly statementAst: AST.ExplainSchemaStmt
+	) {
+		super(scope, 1);
+	}
+
+	getType(): RelationType {
+		return {
+			typeClass: 'relation',
+			isReadOnly: true,
+			isSet: true,
+			columns: [
+				{
+					name: 'info',
+					type: {
+						typeClass: 'scalar',
+						affinity: SqlDataType.TEXT,
+						nullable: false,
+						isReadOnly: true,
+					},
+					generated: true,
+				}
+			],
+			keys: [[]],
+			rowConstraints: [],
+		};
+	}
+
+	get estimatedRows(): number | undefined {
+		return 1;
+	}
+
+	getAttributes(): Attribute[] {
+		return this.getType().columns.map((column) => ({
+			id: PlanNode.nextAttrId(),
+			name: column.name,
+			type: column.type,
+			sourceRelation: `${this.nodeType}:${this.id}`
+		}));
+	}
+
+	getChildren(): PlanNode[] {
+		return [];
+	}
+
+	withChildren(_newChildren: readonly PlanNode[]): PlanNode {
+		return new ExplainSchemaNode(this.scope, this.statementAst);
+	}
+
+	override toString(): string {
+		return `EXPLAIN SCHEMA ${this.statementAst.schemaName || 'main'}`;
+	}
+
+	override getLogicalAttributes(): Record<string, unknown> {
+		return {
+			type: 'explainSchema',
+			schemaName: this.statementAst.schemaName || 'main',
+			version: this.statementAst.version
+		};
+	}
+}
+
+

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

@@ -1,96 +1,102 @@
-import type { Scope } from '../scopes/scope.js';
-import { PlanNode, type RelationalPlanNode, type Attribute, type RowDescriptor, type PhysicalProperties, isRelationalNode } 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 { buildAttributesFromFlatDescriptor } from '../../util/row-descriptor.js';
-
-/**
- * Represents a DELETE statement in the logical query plan.
- */
-export class DeleteNode extends PlanNode implements RelationalPlanNode {
-  override readonly nodeType = PlanNodeType.Delete;
-
-  constructor(
-    scope: Scope,
-    public readonly table: TableReferenceNode,
-    public readonly source: RelationalPlanNode, // Typically a FilterNode wrapping a TableReferenceNode
-    public readonly oldRowDescriptor?: RowDescriptor, // For constraint checking
-    public readonly flatRowDescriptor?: RowDescriptor,
-  ) {
-    super(scope);
-  }
-
-	getType(): RelationType {
-		return this.source.getType();
-	}
-
-  getAttributes(): Attribute[] {
-    if (this.flatRowDescriptor && Object.keys(this.flatRowDescriptor).length > 0) {
-      return buildAttributesFromFlatDescriptor(this.flatRowDescriptor);
-    }
-    // Fallback to source attributes for backward compatibility
-    return this.source.getAttributes();
-  }
-
-  getRelations(): readonly [RelationalPlanNode, TableReferenceNode] {
-    // The source provides keys to be deleted, table is the target of deletions.
-    return [this.source, this.table];
-  }
-
-  getChildren(): readonly PlanNode[] {
-    // Return the source relation as a child so optimizer can traverse it
-    return [this.source];
-  }
-
-  withChildren(newChildren: readonly PlanNode[]): PlanNode {
-    if (newChildren.length !== 1) {
-      throw new Error(`DeleteNode expects 1 child (source), got ${newChildren.length}`);
-    }
-
-    const newSource = newChildren[0] as RelationalPlanNode;
-    if (!isRelationalNode(newSource)) {
-      throw new Error('DeleteNode: child must be a RelationalPlanNode');
-    }
-
-    if (newSource === this.source) {
-      return this;
-    }
-
-    return new DeleteNode(
-      this.scope,
-      this.table,
-      newSource,
-      this.oldRowDescriptor,
-      this.flatRowDescriptor
-    );
-  }
-
-  computePhysical(): Partial<PhysicalProperties> {
-    return {
-      readonly: false,  // DELETE has side effects
-      estimatedRows: this.source.estimatedRows
-    };
-  }
-
-  get estimatedRows(): number | undefined {
-    return this.source.estimatedRows;
-  }
-
-  override toString(): string {
-    return `DELETE FROM ${this.table.tableSchema.name}`;
-  }
-
-  override getLogicalAttributes(): Record<string, unknown> {
-    const props: Record<string, unknown> = {
-      table: this.table.tableSchema.name,
-      schema: this.table.tableSchema.schemaName
-    };
-
-    if (this.flatRowDescriptor) {
-      props.hasFlatRowDescriptor = true;
-    }
-
-    return props;
-  }
-}
+import type { Scope } from '../scopes/scope.js';
+import { PlanNode, type RelationalPlanNode, type ScalarPlanNode, type Attribute, type RowDescriptor, type PhysicalProperties, isRelationalNode } 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 { buildAttributesFromFlatDescriptor } from '../../util/row-descriptor.js';
+
+/**
+ * Represents a DELETE statement in the logical query plan.
+ */
+export class DeleteNode extends PlanNode implements RelationalPlanNode {
+  override readonly nodeType = PlanNodeType.Delete;
+
+  constructor(
+    scope: Scope,
+    public readonly table: TableReferenceNode,
+    public readonly source: RelationalPlanNode, // Typically a FilterNode wrapping a TableReferenceNode
+    public readonly oldRowDescriptor?: RowDescriptor, // For constraint checking
+    public readonly flatRowDescriptor?: RowDescriptor,
+    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[] {
+    if (this.flatRowDescriptor && Object.keys(this.flatRowDescriptor).length > 0) {
+      return buildAttributesFromFlatDescriptor(this.flatRowDescriptor);
+    }
+    // Fallback to source attributes for backward compatibility
+    return this.source.getAttributes();
+  }
+
+  getRelations(): readonly [RelationalPlanNode, TableReferenceNode] {
+    // The source provides keys to be deleted, table is the target of deletions.
+    return [this.source, this.table];
+  }
+
+  getChildren(): readonly PlanNode[] {
+    // Return the source relation as a child so optimizer can traverse it
+    return [this.source];
+  }
+
+  withChildren(newChildren: readonly PlanNode[]): PlanNode {
+    if (newChildren.length !== 1) {
+      throw new Error(`DeleteNode expects 1 child (source), got ${newChildren.length}`);
+    }
+
+    const newSource = newChildren[0] as RelationalPlanNode;
+    if (!isRelationalNode(newSource)) {
+      throw new Error('DeleteNode: child must be a RelationalPlanNode');
+    }
+
+    if (newSource === this.source) {
+      return this;
+    }
+
+    return new DeleteNode(
+      this.scope,
+      this.table,
+      newSource,
+      this.oldRowDescriptor,
+      this.flatRowDescriptor,
+      this.mutationContextValues,
+      this.contextAttributes,
+      this.contextDescriptor
+    );
+  }
+
+  computePhysical(): Partial<PhysicalProperties> {
+    return {
+      readonly: false,  // DELETE has side effects
+      estimatedRows: this.source.estimatedRows
+    };
+  }
+
+  get estimatedRows(): number | undefined {
+    return this.source.estimatedRows;
+  }
+
+  override toString(): string {
+    return `DELETE FROM ${this.table.tableSchema.name}`;
+  }
+
+  override getLogicalAttributes(): Record<string, unknown> {
+    const props: Record<string, unknown> = {
+      table: this.table.tableSchema.name,
+      schema: this.table.tableSchema.schemaName
+    };
+
+    if (this.flatRowDescriptor) {
+      props.hasFlatRowDescriptor = true;
+    }
+
+    return props;
+  }
+}

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

@@ -1,9 +1,9 @@
 import { PlanNodeType } from './plan-node-type.js';
-import { PlanNode, type RelationalPlanNode, type UnaryRelationalNode, type Attribute, isRelationalNode } from './plan-node.js';
+import { PlanNode, type RelationalPlanNode, type UnaryRelationalNode, type Attribute, isRelationalNode, type PhysicalProperties } from './plan-node.js';
 import type { RelationType } from '../../common/datatype.js';
 import type { Scope } from '../scopes/scope.js';
 import { quereusError } from '../../common/errors.js';
-import { StatusCode } from '../../index.js';
+import { StatusCode } from '../../common/types.js';
 
 /**
  * Represents a DISTINCT operation that eliminates duplicate rows.
@@ -29,12 +29,11 @@ export class DistinctNode extends PlanNode implements UnaryRelationalNode {
     const sourceType = this.source.getType();
     return {
       ...sourceType,
-			// TODO: ensure that formed key is represented in the type
-      isSet: true // DISTINCT guarantees uniqueness
+      isSet: true
     };
   }
 
-  getAttributes(): Attribute[] {
+  getAttributes(): readonly Attribute[] {
     // DISTINCT preserves the same attributes as its source
     return this.source.getAttributes();
   }
@@ -64,7 +63,22 @@ export class DistinctNode extends PlanNode implements UnaryRelationalNode {
   }
 
   override getLogicalAttributes(): Record<string, unknown> {
-    return { };
+    const colCount = this.source.getAttributes().length;
+    const allColsKey = [Array.from({ length: colCount }, (_, i) => i)];
+    return {
+      uniqueKeys: allColsKey
+    };
+  }
+
+  computePhysical(childrenPhysical: PhysicalProperties[]): Partial<PhysicalProperties> {
+    const sourcePhysical = childrenPhysical[0];
+    const colCount = this.source.getAttributes().length;
+    const allColsKey = [Array.from({ length: colCount }, (_, i) => i)];
+    return {
+      uniqueKeys: allColsKey,
+      estimatedRows: this.estimatedRows,
+      ordering: sourcePhysical?.ordering,
+    };
   }
 
   withChildren(newChildren: readonly PlanNode[]): PlanNode {

package/src/planner/nodes/dml-executor-node.ts

@@ -4,7 +4,7 @@ import { PlanNodeType } from './plan-node-type.js';
 import type { TableReferenceNode } from './reference.js';
 import type { RelationType } from '../../common/datatype.js';
 import type { ConflictResolution } from '../../common/constants.js';
-import { RowOp } from '../../parser/ast.js';
+import { RowOp } from '../../common/types.js';
 
 /**
  * Executes actual database insert/update/delete operations after constraint validation.
@@ -28,7 +28,7 @@ export class DmlExecutorNode extends PlanNode implements RelationalPlanNode {
     return this.source.getType();
   }
 
-  getAttributes(): Attribute[] {
+  getAttributes(): readonly Attribute[] {
     return this.source.getAttributes();
   }
 

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

@@ -0,0 +1,50 @@
+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';
+
+/**
+ * Represents dropping a global integrity assertion.
+ * This is a DDL operation that removes an assertion from the schema.
+ */
+export class DropAssertionNode extends PlanNode implements VoidNode {
+  override readonly nodeType = PlanNodeType.DropAssertion;
+
+  constructor(
+    scope: Scope,
+    public readonly name: string,
+    public readonly ifExists: boolean,
+  ) {
+    super(scope);
+  }
+
+  getType(): VoidType {
+    return { typeClass: 'void' };
+  }
+
+  getChildren(): readonly PlanNode[] {
+    return [];
+  }
+
+  withChildren(newChildren: readonly PlanNode[]): PlanNode {
+    if (newChildren.length !== 0) {
+      throw new Error(`DropAssertionNode expects 0 children, got ${newChildren.length}`);
+    }
+    return this; // No children, so no change
+  }
+
+  override toString(): string {
+    return `DROP ASSERTION ${this.name}`;
+  }
+
+  override getLogicalAttributes(): Record<string, unknown> {
+    return {
+      name: this.name,
+      ifExists: this.ifExists,
+    };
+  }
+
+  override computePhysical(_children: readonly PhysicalProperties[]): Partial<PhysicalProperties> {
+    return { readonly: false };
+  }
+}

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

@@ -25,6 +25,7 @@ export class DropTableNode extends VoidNode {
     return {
       table: this.statementAst.name.name,
       schema: this.statementAst.name.schema,
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
       statement: expressionToString(this.statementAst as any)
     };
   }