@quereus/quereus 0.2.1 → 0.4.5

package/src/planner/nodes/limit-offset.ts

@@ -1,125 +1,144 @@
 import { PlanNodeType } from './plan-node-type.js';
-import { PlanNode, type RelationalPlanNode, type UnaryRelationalNode, type ScalarPlanNode, type Attribute, isRelationalNode } from './plan-node.js';
+import { PlanNode, type RelationalPlanNode, type UnaryRelationalNode, type ScalarPlanNode, type Attribute, isRelationalNode, type PhysicalProperties } from './plan-node.js';
 import type { RelationType } from '../../common/datatype.js';
 import type { Scope } from '../scopes/scope.js';
 import { formatExpression } from '../../util/plan-formatter.js';
 import { quereusError } from '../../common/errors.js';
 import { StatusCode } from '../../common/types.js';
+import type { LimitCapable } from '../framework/characteristics.js';
 
 /**
  * Represents a LIMIT/OFFSET operation.
  * It takes an input relation and returns at most 'limit' rows, skipping 'offset' rows.
  */
-export class LimitOffsetNode extends PlanNode implements UnaryRelationalNode {
-  override readonly nodeType = PlanNodeType.LimitOffset;
-
-  constructor(
-    scope: Scope,
-    public readonly source: RelationalPlanNode,
-    public readonly limit: ScalarPlanNode | undefined,
-    public readonly offset: ScalarPlanNode | undefined,
-    estimatedCostOverride?: number
-  ) {
-    // Cost is proportional to offset + limit (rows we need to process)
-    // We assume limit and offset are constants, but in practice they could be expressions
-    super(scope, estimatedCostOverride ?? source.getTotalCost());
-  }
-
-  getType(): RelationType {
-    // LIMIT/OFFSET preserves the type of the source relation
-    return this.source.getType();
-  }
-
-  getAttributes(): Attribute[] {
-    // LIMIT/OFFSET preserves the same attributes as its source
-    return this.source.getAttributes();
-  }
-
-  getChildren(): readonly PlanNode[] {
-    const children: PlanNode[] = [this.source];
-    if (this.limit) children.push(this.limit);
-    if (this.offset) children.push(this.offset);
-    return children;
-  }
-
-  getRelations(): readonly [RelationalPlanNode] {
-    return [this.source];
-  }
-
-  get estimatedRows(): number | undefined {
-    const sourceRows = this.source.estimatedRows;
-    if (sourceRows === undefined) return undefined;
-
-    // TODO: Evaluate limit/offset if they are constants
-    // For now, assume limit is 100 if specified, otherwise use source rows
-    if (this.limit) {
-      return Math.min(sourceRows, 100);
-    }
-    return sourceRows;
-  }
-
-  override toString(): string {
-    const parts: string[] = [];
-    if (this.limit) parts.push(`LIMIT ${formatExpression(this.limit)}`);
-    if (this.offset) parts.push(`OFFSET ${formatExpression(this.offset)}`);
-    return parts.join(' ');
-  }
-
-  override getLogicalAttributes(): Record<string, unknown> {
-    const props: Record<string, unknown> = {};
-
-    if (this.limit) {
-      props.limit = formatExpression(this.limit);
-    }
-
-    if (this.offset) {
-      props.offset = formatExpression(this.offset);
-    }
-
-    return props;
-  }
-
-  withChildren(newChildren: readonly PlanNode[]): PlanNode {
-    const expectedLength = 1 + (this.limit ? 1 : 0) + (this.offset ? 1 : 0);
-    if (newChildren.length !== expectedLength) {
-      quereusError(`LimitOffsetNode expects ${expectedLength} children, got ${newChildren.length}`, StatusCode.INTERNAL);
-    }
-
-    const [newSource, ...restChildren] = newChildren;
-
-    // Type check
-    if (!isRelationalNode(newSource)) {
-      quereusError('LimitOffsetNode: first child must be a RelationalPlanNode', StatusCode.INTERNAL);
-    }
-
-    // Parse optional limit and offset from remaining children
-    let newLimit: ScalarPlanNode | undefined = undefined;
-    let newOffset: ScalarPlanNode | undefined = undefined;
-    let childIndex = 0;
-
-    if (this.limit) {
-      newLimit = restChildren[childIndex] as ScalarPlanNode;
-      childIndex++;
-    }
-    if (this.offset) {
-      newOffset = restChildren[childIndex] as ScalarPlanNode;
-    }
-
-    // Check if anything changed
-    const sourceChanged = newSource !== this.source;
-    const limitChanged = newLimit !== this.limit;
-    const offsetChanged = newOffset !== this.offset;
-
-    if (!sourceChanged && !limitChanged && !offsetChanged) {
-      return this;
-    }
-
-    // Create new instance preserving attributes (limit/offset preserves source attributes)
-    return new LimitOffsetNode(
-      this.scope,
-      newSource as RelationalPlanNode,
-      newLimit,
-      newOffset
-    );
-  }
+export class LimitOffsetNode extends PlanNode implements UnaryRelationalNode, LimitCapable {
+	override readonly nodeType = PlanNodeType.LimitOffset;
+
+	constructor(
+		scope: Scope,
+		public readonly source: RelationalPlanNode,
+		public readonly limit: ScalarPlanNode | undefined,
+		public readonly offset: ScalarPlanNode | undefined,
+		estimatedCostOverride?: number
+	) {
+		// Cost is proportional to offset + limit (rows we need to process)
+		// We assume limit and offset are constants, but in practice they could be expressions
+		super(scope, estimatedCostOverride ?? source.getTotalCost());
+	}
+
+	// LimitCapable interface
+	getLimitExpression(): ScalarPlanNode | undefined {
+		return this.limit;
+	}
+
+	getOffsetExpression(): ScalarPlanNode | undefined {
+		return this.offset;
+	}
+
+	getType(): RelationType {
+		// LIMIT/OFFSET preserves the type of the source relation
+		return this.source.getType();
+	}
+
+	getAttributes(): readonly Attribute[] {
+		// LIMIT/OFFSET preserves the same attributes as its source
+		return this.source.getAttributes();
+	}
+
+	getChildren(): readonly PlanNode[] {
+		const children: PlanNode[] = [this.source];
+		if (this.limit) children.push(this.limit);
+		if (this.offset) children.push(this.offset);
+		return children;
+	}
+
+	getRelations(): readonly [RelationalPlanNode] {
+		return [this.source];
+	}
+
+	get estimatedRows(): number | undefined {
+		const sourceRows = this.source.estimatedRows;
+		if (sourceRows === undefined) return undefined;
+
+		// TODO: Evaluate limit/offset if they are constants
+		// For now, assume limit is 100 if specified, otherwise use source rows
+		if (this.limit) {
+			return Math.min(sourceRows, 100);
+		}
+		return sourceRows;
+	}
+
+	computePhysical(childrenPhysical: PhysicalProperties[]): Partial<PhysicalProperties> {
+		const sourcePhysical = childrenPhysical[0];
+		return {
+			estimatedRows: this.estimatedRows,
+			ordering: sourcePhysical?.ordering,
+			uniqueKeys: sourcePhysical?.uniqueKeys,
+		};
+	}
+
+	override toString(): string {
+		const parts: string[] = [];
+		if (this.limit) parts.push(`LIMIT ${formatExpression(this.limit)}`);
+		if (this.offset) parts.push(`OFFSET ${formatExpression(this.offset)}`);
+		return parts.join(' ');
+	}
+
+	override getLogicalAttributes(): Record<string, unknown> {
+		const props: Record<string, unknown> = {};
+
+		if (this.limit) {
+			props.limit = formatExpression(this.limit);
+		}
+
+		if (this.offset) {
+			props.offset = formatExpression(this.offset);
+		}
+
+		return props;
+	}
+
+	withChildren(newChildren: readonly PlanNode[]): PlanNode {
+		const expectedLength = 1 + (this.limit ? 1 : 0) + (this.offset ? 1 : 0);
+		if (newChildren.length !== expectedLength) {
+			quereusError(`LimitOffsetNode expects ${expectedLength} children, got ${newChildren.length}`, StatusCode.INTERNAL);
+		}
+
+		const [newSource, ...restChildren] = newChildren;
+
+		// Type check
+		if (!isRelationalNode(newSource)) {
+			quereusError('LimitOffsetNode: first child must be a RelationalPlanNode', StatusCode.INTERNAL);
+		}
+
+		// Parse optional limit and offset from remaining children
+		let newLimit: ScalarPlanNode | undefined = undefined;
+		let newOffset: ScalarPlanNode | undefined = undefined;
+		let childIndex = 0;
+
+		if (this.limit) {
+			newLimit = restChildren[childIndex] as ScalarPlanNode;
+			childIndex++;
+		}
+		if (this.offset) {
+			newOffset = restChildren[childIndex] as ScalarPlanNode;
+		}
+
+		// Check if anything changed
+		const sourceChanged = newSource !== this.source;
+		const limitChanged = newLimit !== this.limit;
+		const offsetChanged = newOffset !== this.offset;
+
+		if (!sourceChanged && !limitChanged && !offsetChanged) {
+			return this;
+		}
+
+		// Create new instance preserving attributes (limit/offset preserves source attributes)
+		return new LimitOffsetNode(
+			this.scope,
+			newSource as RelationalPlanNode,
+			newLimit,
+			newOffset
+		);
+	}
 }

package/src/planner/nodes/plan-node-type.ts

@@ -1,87 +1,95 @@
-export enum PlanNodeType {
-  // Logical Nodes (from builder)
-  Block = 'Block',
-  TableReference = 'TableReference',
-  CTEReference = 'CTEReference',
-  TableSeek = 'TableSeek',
-  Filter = 'Filter',
-  Project = 'Project',
-  Distinct = 'Distinct',
-  Aggregate = 'Aggregate',
-  Window = 'Window',
-  Sort = 'Sort',
-  LimitOffset = 'LimitOffset',
-  Join = 'Join',
-  SetOperation = 'SetOperation',
-  CTE = 'CTE',
-  RecursiveCTE = 'RecursiveCTE',
-  InternalRecursiveCTERef = 'InternalRecursiveCTERef',
-  In = 'In',
-  Exists = 'Exists',
-  Sequencing = 'Sequencing',
-
-  // DML/DDL Nodes
-  Insert = 'Insert',
-  Update = 'Update',
-  UpdateExecutor = 'UpdateExecutor',
-  Delete = 'Delete',
-  ConstraintCheck = 'ConstraintCheck',
-  CreateTable = 'CreateTable',
-  DropTable = 'DropTable',
-  CreateIndex = 'CreateIndex',
-  DropIndex = 'DropIndex',
-  CreateView = 'CreateView',
-  DropView = 'DropView',
-  AlterTable = 'AlterTable',
-  AddConstraint = 'AddConstraint',
-
-  // Physical Nodes (from optimizer)
-  SeqScan = 'SeqScan',              // Physical sequential scan
-  IndexScan = 'IndexScan',          // Physical index scan
-  IndexSeek = 'IndexSeek',          // Physical index seek
-  StreamAggregate = 'StreamAggregate',  // Physical ordered aggregate
-  HashAggregate = 'HashAggregate',      // Physical hash aggregate
-  NestedLoopJoin = 'NestedLoopJoin',
-  HashJoin = 'HashJoin',
-  MergeJoin = 'MergeJoin',
-  Materialize = 'Materialize',      // Materialize intermediate results
-
-  // Scalar expression nodes
-  Literal = 'Literal',
-  ColumnReference = 'ColumnReference',
-  ParameterReference = 'ParameterReference',
-  ArrayIndex = 'ArrayIndex',
-  UnaryOp = 'UnaryOp',
-  BinaryOp = 'BinaryOp',
-  CaseExpr = 'CaseExpr',
-  Cast = 'Cast',
-  Collate = 'Collate',
-  ScalarFunctionCall = 'ScalarFunctionCall',
-  WindowFunctionCall = 'WindowFunctionCall',
-  Between = 'Between',
-  IsNull = 'IsNull',
-  IsNotNull = 'IsNotNull',
-  Like = 'Like',
-  ScalarSubquery = 'ScalarSubquery',
-  TableFunctionReference = 'TableFunctionReference',
-
-  // Special relational nodes
-  Values = 'Values',
-	TableLiteral = "TableLiteral",
-  SingleRow = 'SingleRow',  // For SELECT without FROM
-  TableFunctionCall = 'TableFunctionCall',
-
-  // Transaction control
-  Transaction = 'Transaction',
-  Savepoint = 'Savepoint',
-
-  // Utility
-  Pragma = 'Pragma',
-
-  // Query execution
-  Cache = 'Cache',
-  Sink = 'Sink',
-
-  // RETURNING support
-  Returning = 'Returning',
-}
+export enum PlanNodeType {
+  // Logical Nodes (from builder)
+  Block = 'Block',
+  TableReference = 'TableReference',
+  Retrieve = 'Retrieve',
+  CTEReference = 'CTEReference',
+  TableSeek = 'TableSeek',
+  Filter = 'Filter',
+  Project = 'Project',
+  Distinct = 'Distinct',
+  Aggregate = 'Aggregate',
+  Window = 'Window',
+  Sort = 'Sort',
+  LimitOffset = 'LimitOffset',
+  Join = 'Join',
+  SetOperation = 'SetOperation',
+  CTE = 'CTE',
+  RecursiveCTE = 'RecursiveCTE',
+  InternalRecursiveCTERef = 'InternalRecursiveCTERef',
+  In = 'In',
+  Exists = 'Exists',
+  Sequencing = 'Sequencing',
+
+  // DML/DDL Nodes
+  Insert = 'Insert',
+  Update = 'Update',
+  UpdateExecutor = 'UpdateExecutor',
+  Delete = 'Delete',
+  ConstraintCheck = 'ConstraintCheck',
+  CreateTable = 'CreateTable',
+  DropTable = 'DropTable',
+  CreateIndex = 'CreateIndex',
+  DropIndex = 'DropIndex',
+  CreateView = 'CreateView',
+  DropView = 'DropView',
+  CreateAssertion = 'CreateAssertion',
+  DropAssertion = 'DropAssertion',
+  AlterTable = 'AlterTable',
+  AddConstraint = 'AddConstraint',
+
+  // Physical Nodes (from optimizer)
+  SeqScan = 'SeqScan',              // Physical sequential scan
+  IndexScan = 'IndexScan',          // Physical index scan
+  IndexSeek = 'IndexSeek',          // Physical index seek
+  RemoteQuery = 'RemoteQuery',      // Physical remote query execution
+  StreamAggregate = 'StreamAggregate',  // Physical ordered aggregate
+  HashAggregate = 'HashAggregate',      // Physical hash aggregate
+  NestedLoopJoin = 'NestedLoopJoin',
+  HashJoin = 'HashJoin',
+  MergeJoin = 'MergeJoin',
+  Materialize = 'Materialize',      // Materialize intermediate results
+
+  // Scalar expression nodes
+  Literal = 'Literal',
+  ColumnReference = 'ColumnReference',
+  ParameterReference = 'ParameterReference',
+  ArrayIndex = 'ArrayIndex',
+  UnaryOp = 'UnaryOp',
+  BinaryOp = 'BinaryOp',
+  CaseExpr = 'CaseExpr',
+  Cast = 'Cast',
+  Collate = 'Collate',
+  ScalarFunctionCall = 'ScalarFunctionCall',
+  WindowFunctionCall = 'WindowFunctionCall',
+  Between = 'Between',
+  IsNull = 'IsNull',
+  IsNotNull = 'IsNotNull',
+  Like = 'Like',
+  ScalarSubquery = 'ScalarSubquery',
+  TableFunctionReference = 'TableFunctionReference',
+
+  // Special relational nodes
+  Values = 'Values',
+	TableLiteral = "TableLiteral",
+  SingleRow = 'SingleRow',  // For SELECT without FROM
+  TableFunctionCall = 'TableFunctionCall',
+
+  // Transaction control
+  Transaction = 'Transaction',
+  Savepoint = 'Savepoint',
+
+  // Utility
+  Pragma = 'Pragma',
+  DeclareSchema = 'DeclareSchema',
+  DiffSchema = 'DiffSchema',
+  ApplySchema = 'ApplySchema',
+  ExplainSchema = 'ExplainSchema',
+
+  // Query execution
+  Cache = 'Cache',
+  Sink = 'Sink',
+
+  // RETURNING support
+  Returning = 'Returning',
+}

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

@@ -110,7 +110,7 @@ export abstract class PlanNode {
   private _physical?: PhysicalProperties;
 
   constructor(
-		/** The scope in which this node is planned.  Note that this captures references made through it, so you can tell if a node has dependencies. */
+		/** The scope in which this node is planned. */
     public readonly scope: Scope,
 	  /** Estimated cost to execute this node itself (excluding its children). */
 		public readonly estimatedCost = 0.01
@@ -152,7 +152,7 @@ export abstract class PlanNode {
   /**
    * Get the attributes (columns) produced by this relational node
    */
-  getAttributes?(): Attribute[];
+  getAttributes?(): readonly Attribute[];
 
   /**
    * Get map of attribute ID to producing scalar expression (for constant folding)
@@ -268,11 +268,11 @@ export interface RelationalPlanNode extends PlanNode {
    * Get the attributes (columns) produced by this relational node
    * Each attribute has a unique ID that persists across plan transformations
    */
-  getAttributes(): Attribute[];
+  getAttributes(): readonly Attribute[];
 }
 
 /**
- * Check if a node is relational (can be cached)
+ * Characteristically check if a node is relational (can be cached)
  */
 export function isRelationalNode(node: PlanNode): node is RelationalPlanNode {
 	return node.getType().typeClass === 'relation';
@@ -288,7 +288,7 @@ export interface ScalarPlanNode extends PlanNode {
 }
 
 /**
- * Check if a node is a scalar node
+ * Characteristically check if a node is a scalar node
  */
 export function isScalarNode(node: PlanNode): node is ScalarPlanNode {
 	return node.getType().typeClass === 'scalar';
@@ -356,7 +356,7 @@ export interface NaryScalarNode extends ScalarPlanNode {
  */
 export abstract class ZeroAryRelationalBase extends PlanNode implements ZeroAryRelationalNode {
   abstract getType(): RelationType;
-  abstract getAttributes(): Attribute[];
+  abstract getAttributes(): readonly Attribute[];
 
   getChildren(): readonly PlanNode[] {
     return [];
@@ -380,7 +380,7 @@ export abstract class ZeroAryRelationalBase extends PlanNode implements ZeroAryR
 export abstract class UnaryRelationalBase extends PlanNode implements UnaryRelationalNode {
   abstract readonly source: RelationalPlanNode;
   abstract getType(): RelationType;
-  abstract getAttributes(): Attribute[];
+  abstract getAttributes(): readonly Attribute[];
 
   getChildren(): readonly PlanNode[] {
     return [this.source];
@@ -400,7 +400,7 @@ export abstract class BinaryRelationalBase extends PlanNode implements BinaryRel
   abstract readonly left: RelationalPlanNode;
   abstract readonly right: RelationalPlanNode;
   abstract getType(): RelationType;
-  abstract getAttributes(): Attribute[];
+  abstract getAttributes(): readonly Attribute[];
 
   getChildren(): readonly PlanNode[] {
     return [this.left, this.right];

package/src/planner/nodes/pragma.ts

@@ -5,12 +5,13 @@ import { PlanNodeType } from './plan-node-type.js';
 import { expressionToString } from '../../util/ast-stringify.js';
 import { PlanNode } from './plan-node.js';
 import { RelationType } from '../../common/datatype.js';
+import { Scope } from '../scopes/scope.js';
 
 export class PragmaPlanNode extends PlanNode implements RelationalPlanNode {
 	override readonly nodeType = PlanNodeType.Pragma;
 
 	constructor(
-		scope: any,
+		scope: Scope,
 		public readonly pragmaName: string,
 		public readonly statementAst: AST.PragmaStmt,
 		public readonly value?: SqlValue
@@ -60,7 +61,7 @@ export class PragmaPlanNode extends PlanNode implements RelationalPlanNode {
 				name: column.name, // Use the deduplicated name
 				type: column.type,
 				sourceRelation: `${this.nodeType}:${this.id}`
-			} as Attribute
+			} satisfies Attribute
 		));
 	}
 
@@ -81,7 +82,9 @@ export class PragmaPlanNode extends PlanNode implements RelationalPlanNode {
 
 	override getLogicalAttributes(): Record<string, unknown> {
 		const props: Record<string, unknown> = {
-			pragma: this.pragmaName,
+			type: 'pragma',
+			name: this.statementAst.name,
+			// eslint-disable-next-line @typescript-eslint/no-explicit-any
 			statement: expressionToString(this.statementAst as any)
 		};