@quereus/quereus 0.1.0

package/src/schema/schema.ts

@@ -0,0 +1,199 @@
+import type { TableSchema } from './table.js';
+import type { FunctionSchema } from './function.js';
+import { getFunctionKey } from './function.js';
+import type { ViewSchema } from './view.js';
+import { quereusError, QuereusError } from '../common/errors.js';
+import { createLogger } from '../common/logger.js';
+
+const log = createLogger('schema:schema');
+
+/**
+ * Represents a single database schema (e.g., "main", "temp").
+ * Contains collections of tables, functions, etc. defined within that schema.
+ */
+export class Schema {
+	public readonly name: string;
+	private tables: Map<string, TableSchema> = new Map();
+	private functions: Map<string, FunctionSchema> = new Map();
+	private views: Map<string, ViewSchema> = new Map();
+
+	/**
+	 * Creates a new schema instance
+	 *
+	 * @param name The schema name (e.g. "main", "temp")
+	 */
+	constructor(name: string) {
+		this.name = name;
+	}
+
+	/**
+	 * Retrieves a table schema definition
+	 *
+	 * @param tableName The name of the table (case-insensitive)
+	 * @returns The table schema or undefined if not found
+	 */
+	getTable(tableName: string): TableSchema | undefined {
+		return this.tables.get(tableName.toLowerCase());
+	}
+
+	/**
+	 * Adds or replaces a table definition in the schema
+	 *
+	 * @param table The table schema object
+	 * @throws QuereusError if a view with the same name exists
+	 */
+	addTable(table: TableSchema): void {
+		// Ensure no view conflict
+		if (this.views.has(table.name.toLowerCase())) {
+			throw new QuereusError(`Schema '${this.name}': Cannot add table '${table.name}', a view with the same name already exists.`);
+		}
+		this.tables.set(table.name.toLowerCase(), table);
+	}
+
+	/**
+	 * Returns an iterator over all tables in the schema
+	 *
+	 * @returns Iterator of table schemas
+	 */
+	getAllTables(): IterableIterator<TableSchema> {
+		return this.tables.values();
+	}
+
+	/**
+	 * Removes a table definition from the schema
+	 *
+	 * @param tableName The name of the table to remove
+	 * @returns true if found and removed, false otherwise
+	 */
+	removeTable(tableName: string): boolean {
+		const key = tableName.toLowerCase();
+		const exists = this.tables.has(key);
+		if (exists) {
+			this.tables.delete(key);
+		}
+		return exists;
+	}
+
+	/**
+	 * Clears all tables (does not call VTable disconnect/destroy)
+	 */
+	clearTables(): void {
+		this.tables.clear();
+	}
+
+	/**
+	 * Adds or replaces a view definition in the schema
+	 *
+	 * @param view The view schema to add
+	 * @throws Error if view's schema name doesn't match or a table with same name exists
+	 */
+	addView(view: ViewSchema): void {
+		if (view.schemaName !== this.name) {
+			quereusError(`View ${view.name} has wrong schema name ${view.schemaName}, expected ${this.name}`);
+		}
+		if (this.tables.has(view.name.toLowerCase())) {
+			throw new QuereusError(`Schema '${this.name}': Cannot add view '${view.name}', a table with the same name already exists.`);
+		}
+		this.views.set(view.name.toLowerCase(), view);
+		log(`Added/Updated view '%s' in schema '%s'`, view.name, this.name);
+	}
+
+	/**
+	 * Gets a view definition by name (case-insensitive)
+	 *
+	 * @param viewName The view name to look up
+	 * @returns The view schema or undefined if not found
+	 */
+	getView(viewName: string): ViewSchema | undefined {
+		return this.views.get(viewName.toLowerCase());
+	}
+
+	/**
+	 * Returns an iterator over all views in the schema
+	 *
+	 * @returns Iterator of view schemas
+	 */
+	getAllViews(): IterableIterator<ViewSchema> {
+		return this.views.values();
+	}
+
+	/**
+	 * Removes a view definition from the schema
+	 *
+	 * @param viewName The name of the view to remove
+	 * @returns true if found and removed, false otherwise
+	 */
+	removeView(viewName: string): boolean {
+		const key = viewName.toLowerCase();
+		const exists = this.views.has(key);
+		if (exists) {
+			log(`Removed view '%s' from schema '%s'`, viewName, this.name);
+			this.views.delete(key);
+		}
+		return exists;
+	}
+
+	/**
+	 * Clears all views
+	 */
+	clearViews(): void {
+		this.views.clear();
+	}
+
+	/**
+	 * Adds or replaces a function definition in the schema
+	 * Calls the destructor for any existing function being replaced
+	 *
+	 * @param func The function schema to add
+	 */
+	addFunction(func: FunctionSchema): void {
+		const key = getFunctionKey(func.name, func.numArgs);
+		this.functions.set(key, func);
+		log(`Added/Updated function '%s' in schema '%s'`, `${func.name}/${func.numArgs}`, this.name);
+	}
+
+	/**
+	 * Gets a function definition by name and argument count (case-insensitive name)
+	 * First checks for exact argument count match, then tries variable args (-1)
+	 *
+	 * @param name The function name
+	 * @param numArgs The number of arguments
+	 * @returns The function schema or undefined if not found
+	 */
+	getFunction(name: string, numArgs: number): FunctionSchema | undefined {
+		const key = getFunctionKey(name, numArgs);
+		const varArgsKey = getFunctionKey(name, -1);
+		return this.functions.get(key) ?? this.functions.get(varArgsKey);
+	}
+
+	/**
+	 * @internal Returns iterator over managed functions
+	 */
+	_getAllFunctions(): IterableIterator<FunctionSchema> {
+		return this.functions.values();
+	}
+
+	/**
+	 * Removes a function definition, calling its destructor if needed
+	 *
+	 * @param name The function name
+	 * @param numArgs The number of arguments
+	 * @returns true if found and removed, false otherwise
+	 */
+	removeFunction(name: string, numArgs: number): boolean {
+		const key = getFunctionKey(name, numArgs);
+		const func = this.functions.get(key);
+		if (func) {
+			log(`Removed function '%s' from schema '%s'`, `${name}/${numArgs}`, this.name);
+			return this.functions.delete(key);
+		}
+		return false;
+	}
+
+	/**
+	 * Clears all functions, calling destructors if needed
+	 */
+	clearFunctions(): void {
+		this.functions.clear();
+	}
+}

package/src/schema/table.ts

@@ -0,0 +1,364 @@
+import type { ColumnSchema } from './column.js';
+import type { VirtualTableModule } from '../vtab/module.js';
+import { MemoryTableModule } from '../vtab/memory/module.js';
+import type { Expression } from '../parser/ast.js';
+import { type ColumnDef, type TableConstraint } from '../parser/ast.js';
+import { getAffinity } from '../common/type-inference.js';
+import { SqlDataType, StatusCode, type SqlValue } from '../common/types.js';
+import type * as AST from '../parser/ast.js';
+import { quereusError, QuereusError } from '../common/errors.js';
+import { createLogger } from '../common/logger.js';
+
+const log = createLogger('schema:table');
+const warnLog = log.extend('warn');
+
+/**
+ * Represents the schema definition of a table (real or virtual).
+ */
+export interface TableSchema {
+	/** Table name */
+	name: string;
+	/** Schema name (e.g., "main", "temp") */
+	schemaName: string;
+	/** Ordered list of column definitions */
+	columns: ReadonlyArray<ColumnSchema>;
+	/** Map from column name (lowercase) to column index */
+	columnIndexMap: ReadonlyMap<string, number>;
+	/** Definition of the primary key, including order and direction */
+	primaryKeyDefinition: ReadonlyArray<PrimaryKeyColumnDefinition>;
+	/** CHECK constraints defined on the table or its columns */
+	checkConstraints: ReadonlyArray<RowConstraintSchema>;
+	/** Reference to the registered module */
+	vtabModule: VirtualTableModule<any, any>;
+	/** If virtual, aux data passed during module registration */
+	vtabAuxData?: unknown;
+	/** If virtual, the arguments passed in CREATE VIRTUAL TABLE */
+	vtabArgs?: Record<string, SqlValue>;
+	/** If virtual, the name the module was registered with */
+	vtabModuleName: string;
+	/** Whether the table is a temporary table */
+	isTemporary?: boolean;
+	/** Whether the table is a view */
+	isView: boolean;
+	/** Whether the table is a subquery source */
+	subqueryAST?: AST.SelectStmt;
+	/** If virtual, the view definition */
+	viewDefinition?: AST.SelectStmt;
+	/** Table-level constraints */
+	tableConstraints?: readonly TableConstraint[];
+	/** Definitions of secondary indexes (relevant for planning) */
+	indexes?: ReadonlyArray<IndexSchema>;
+	/** Estimated number of rows in the table (for query planning) */
+	readonly estimatedRows?: number;
+	/** Whether the table is read-only */
+	isReadOnly?: boolean;	// default false
+	/** Foreign key constraints (parsed but not yet enforced by engine) */
+	// foreignKeys?: ReadonlyArray<ForeignKeyConstraintSchema>;
+	/** Unique constraints (beyond primary key) */
+	// uniqueConstraints?: ReadonlyArray<ConstraintSchema>;
+}
+
+/**
+ * Builds a map from column names to their indices in the columns array
+ *
+ * @param columns Array of column schemas
+ * @returns Map of lowercase column names to their indices
+ */
+export function buildColumnIndexMap(columns: ReadonlyArray<ColumnSchema>): Map<string, number> {
+	const map = new Map<string, number>();
+	columns.forEach((col, index) => {
+		map.set(col.name.toLowerCase(), index);
+	});
+	return map;
+}
+
+/**
+ * Extracts just the column indices from a primary key definition
+ *
+ * @param pkDef Primary key definition array
+ * @returns Array of column indices that form the primary key
+ */
+export function getPrimaryKeyIndices(pkDef: ReadonlyArray<PrimaryKeyColumnDefinition>): ReadonlyArray<number> {
+	return Object.freeze(pkDef.map(def => def.index));
+}
+
+/**
+ * Converts a parsed ColumnDef AST node into a runtime ColumnSchema object
+ *
+ * @param def Column definition AST node
+ * @param defaultNotNull Whether columns should be NOT NULL by default (Third Manifesto approach)
+ * @returns A runtime ColumnSchema object
+ */
+export function columnDefToSchema(def: ColumnDef, defaultNotNull: boolean = true): ColumnSchema {
+	const schema: Partial<ColumnSchema> & { name: string } = {
+		name: def.name,
+		affinity: getAffinity(def.dataType),
+		notNull: defaultNotNull, // Default based on Third Manifesto principles
+		primaryKey: false,
+		pkOrder: 0,
+		defaultValue: null,
+		collation: 'BINARY',
+		generated: false,
+	};
+
+	for (const constraint of def.constraints ?? []) {
+		switch (constraint.type) {
+			case 'primaryKey':
+				schema.primaryKey = true;
+				break;
+			case 'notNull':
+				schema.notNull = true;
+				break;
+			case 'null':
+				schema.notNull = false;
+				break;
+			case 'unique':
+				break;
+			case 'default':
+				schema.defaultValue = constraint.expr;
+				break;
+			case 'collate':
+				schema.collation = constraint.collation;
+				break;
+			case 'generated':
+				schema.generated = true;
+				break;
+		}
+	}
+
+	// PK implies NOT NULL (always, regardless of default)
+	if (schema.primaryKey) {
+		schema.notNull = true;
+	}
+
+	// If no explicit nullability constraint and default is nullable,
+	// we need to check if there's an explicit NULL declaration
+	// Note: SQL doesn't have explicit NULL constraints in standard syntax,
+	// so this primarily affects the default behavior
+
+	// Assign a default pkOrder if it's a PK but order isn't specified elsewhere
+	if (schema.primaryKey && schema.pkOrder === 0) {
+		schema.pkOrder = 1;
+	}
+
+	return schema as ColumnSchema;
+}
+
+/**
+ * Defines a column in an index
+ */
+export interface IndexColumnSchema {
+	/** Column index in TableSchema.columns */
+	index: number;
+	/** Whether the index should sort in descending order */
+	desc?: boolean;	// default false
+	/** Optional collation sequence for the column */
+	collation?: string;
+}
+
+/**
+ * Represents an index definition
+ */
+export interface IndexSchema {
+	/** Index name */
+	name: string;
+	/** Columns in the index */
+	columns: ReadonlyArray<IndexColumnSchema>;
+}
+
+/**
+ * Creates a basic TableSchema with minimal configuration
+ *
+ * @param name Table name
+ * @param columns Array of column name and type objects
+ * @param pkColNames Optional array of primary key column names
+ * @param defaultNotNull Whether columns should be NOT NULL by default (defaults to true for Third Manifesto compliance)
+ * @returns A frozen TableSchema object
+ */
+export function createBasicSchema(name: string, columns: { name: string, type: string }[], pkColNames?: string[], defaultNotNull: boolean = true): Readonly<TableSchema> {
+	const columnSchemas = columns.map(c => columnDefToSchema({
+		name: c.name,
+		dataType: c.type,
+		constraints: []
+	}, defaultNotNull));
+	const columnIndexMap = buildColumnIndexMap(columnSchemas);
+	const pkDef = pkColNames
+		? pkColNames.map(pkName => {
+			const idx = columnIndexMap.get(pkName.toLowerCase());
+			if (idx === undefined) quereusError(`PK column ${pkName} not found`);
+			return { index: idx, desc: false };
+		})
+		: [];
+
+	const defaultMemoryModule = new MemoryTableModule();
+
+	return Object.freeze({
+		name: name,
+		schemaName: 'main',
+		columns: columnSchemas,
+		columnIndexMap: columnIndexMap,
+		primaryKeyDefinition: pkDef,
+		checkConstraints: [] as RowConstraintSchema[],
+		indexes: [],
+		vtabModule: defaultMemoryModule,
+		vtabAuxData: null,
+		vtabArgs: {},
+		vtabModuleName: 'memory',
+		isTemporary: false,
+		isView: false,
+		subqueryAST: undefined,
+		viewDefinition: undefined,
+		tableConstraints: [],
+		primaryKey: pkDef.map(def => columnSchemas[def.index].name),
+	});
+}
+
+/** Bitmask for row operations */
+export const enum RowOp {
+	INSERT = 1,
+	UPDATE = 2,
+	DELETE = 4
+}
+export type RowOpMask = RowOp;
+export const DEFAULT_ROWOP_MASK = RowOp.INSERT | RowOp.UPDATE;
+
+/**
+ * Converts an array of row operations to a bitmask
+ *
+ * @param list Optional array of operation types
+ * @returns A bitmask representing the operations
+ */
+export function opsToMask(list?: AST.RowOp[]): RowOpMask {
+	if (!list || list.length === 0) {
+		return DEFAULT_ROWOP_MASK;
+	}
+	let mask: RowOpMask = 0 as RowOpMask;
+	list.forEach(op => {
+		switch (op) {
+			case 'insert': mask |= RowOp.INSERT; break;
+			case 'update': mask |= RowOp.UPDATE; break;
+			case 'delete': mask |= RowOp.DELETE; break;
+		}
+	});
+	return mask;
+}
+
+/**
+ * Represents a CHECK constraint with operation flags
+ */
+export interface RowConstraintSchema {
+	/** Optional constraint name */
+	name?: string;
+	/** Constraint expression */
+	expr: Expression;
+	/** Bitmask of operations the constraint applies to */
+	operations: RowOpMask;
+}
+
+export interface PrimaryKeyColumnDefinition {
+	index: number;
+	desc?: boolean;	// default false
+	autoIncrement?: boolean;
+	collation?: string;
+}
+
+/**
+ * Helper to parse primary key from AST column and table constraints.
+ * @param columns Parsed column definitions from AST.
+ * @param constraints Parsed table constraints from AST.
+ * @returns A ReadonlyArray defining the primary key columns (index and direction), or undefined.
+ * @throws QuereusError if multiple primary keys are defined or PK column not found.
+ */
+export function findPKDefinition(
+	columns: ReadonlyArray<ColumnSchema>,
+	constraints: ReadonlyArray<AST.TableConstraint> | undefined,
+): ReadonlyArray<PrimaryKeyColumnDefinition> {
+	const columnPK = findColumnPKDefinition(columns);
+	const constraintPK = findConstraintPKDefinition(columns, constraints);
+
+	if (constraintPK && columnPK) {
+		throw new QuereusError("Cannot define both table-level and column-level PRIMARY KEYs", StatusCode.CONSTRAINT);
+	}
+
+	let finalPkDef = constraintPK ?? columnPK;
+
+	if (!finalPkDef) {
+		// Quereus-specific behavior: Include all columns in the primary key when no explicit primary key is defined
+		// This differs from SQLite which would use the first INTEGER column or an implicit rowid
+		// This design choice ensures predictable behavior and avoids potential confusion with SQLite's implicit rules
+		warnLog(`No PRIMARY KEY explicitly defined. Including all columns in primary key.`);
+		finalPkDef = Object.freeze(
+			columns.map((col, index) => ({
+				index,
+				desc: false,
+				collation: col.collation || 'BINARY'
+			}))
+		);
+	}
+
+	// Don't require NOT NULL, we want to be more flexible
+
+	return finalPkDef as ReadonlyArray<PrimaryKeyColumnDefinition>;
+}
+
+function findConstraintPKDefinition(
+	columns: readonly ColumnSchema[],
+	constraints: readonly TableConstraint[] | undefined
+): PrimaryKeyColumnDefinition[] | undefined {
+	const colMap = buildColumnIndexMap(columns);
+	let constraintPKs: PrimaryKeyColumnDefinition[] | undefined;
+
+	if (constraints) {
+		for (const constraint of constraints) {
+			if (constraint.type === 'primaryKey') {
+				if (constraintPKs) {
+					throw new QuereusError("Multiple table-level PRIMARY KEY constraints defined", StatusCode.CONSTRAINT);
+				}
+				if (!constraint.columns || constraint.columns.length === 0) {
+					// An empty column list is fine; means table can have 0-1 rows
+					constraintPKs = [];
+				} else {
+					constraintPKs = constraint.columns.map(colInfo => {
+						const colIndex = colMap.get(colInfo.name.toLowerCase());
+						if (colIndex === undefined) {
+							throw new QuereusError(`PRIMARY KEY column '${colInfo.name}' not found in table definition`, StatusCode.ERROR);
+						}
+						return {
+							index: colIndex,
+							desc: colInfo.direction === 'desc',
+							collation: columns[colIndex].collation || 'BINARY'
+						};
+					});
+				}
+			}
+		}
+	}
+	return constraintPKs;
+}
+
+function findColumnPKDefinition(columns: ReadonlyArray<ColumnSchema>): ReadonlyArray<PrimaryKeyColumnDefinition> | undefined {
+	const pkCols = columns
+		.map((col, index) => ({ ...col, originalIndex: index }))
+		.filter(col => col.primaryKey)
+		.sort((a, b) => a.pkOrder - b.pkOrder);
+
+	if (pkCols.length > 1 && pkCols.some(col => col.pkOrder === 0)) {
+		warnLog("Multiple column-level PRIMARY KEYs defined without explicit pkOrder; consider a table-level PRIMARY KEY for composite keys.");
+	}
+
+	if (pkCols.length > 1) {
+		warnLog('Multiple columns defined as PRIMARY KEY at column level. Forming a composite key.');
+	}
+
+	if (pkCols.length === 0) {
+		return undefined;
+	}
+
+	return Object.freeze(pkCols.map(col => ({
+		index: col.originalIndex,
+		desc: col.affinity === SqlDataType.INTEGER && (col as any).autoIncrement ? false : (col as any).pkDirection === 'desc',
+		autoIncrement: col.affinity === SqlDataType.INTEGER && !!((col as any).autoIncrement),
+		collation: col.collation || 'BINARY'
+	})));
+}
+

package/src/schema/view.ts

@@ -0,0 +1,19 @@
+import type * as AST from '../parser/ast.js';
+
+/**
+ * Represents the schema definition of a database view.
+ * Views are stored SELECT statements that act like virtual tables.
+ */
+export interface ViewSchema {
+	/** The name of the view */
+	name: string;
+	/** The name of the schema this view belongs to (e.g., 'main') */
+	schemaName: string;
+	/** The original SQL text used to create the view */
+	sql: string;
+	/** The parsed SELECT statement AST that defines the view's logic */
+	selectAst: AST.SelectStmt;
+	/** Columns explicitly defined in CREATE VIEW (e.g., CREATE VIEW v(a,b) AS...) */
+	columns?: ReadonlyArray<string>; // Optional list of explicitly named columns
+	// Add any other relevant metadata later if needed
+}

package/src/schema/window-function.ts

@@ -0,0 +1,54 @@
+import type { ScalarType } from '../common/datatype.js';
+import type { SqlValue } from '../common/types.js';
+
+export interface WindowFunctionSchema {
+	name: string;                    // 'ROW_NUMBER', 'RANK', 'SUM', etc.
+	argCount: number | 'variadic';   // Number of arguments, or 'variadic' for any
+	returnType: ScalarType;          // Return type
+	requiresOrderBy: boolean;        // Whether ORDER BY is required
+	kind: 'ranking' | 'aggregate' | 'value' | 'navigation';
+
+	// Optional custom step/final hooks for aggregate-style windows
+	step?: (state: any, value: SqlValue) => any;
+	final?: (state: any, rowCount: number) => SqlValue;
+}
+
+// Global registry for window functions
+const windowRegistry = new Map<string, WindowFunctionSchema>();
+
+export function registerWindowFunction(schema: WindowFunctionSchema): void {
+	windowRegistry.set(schema.name.toLowerCase(), schema);
+}
+
+export function resolveWindowFunction(name: string): WindowFunctionSchema | undefined {
+	return windowRegistry.get(name.toLowerCase());
+}
+
+export function isWindowFunction(name: string): boolean {
+	return windowRegistry.has(name.toLowerCase());
+}
+
+export function getAllWindowFunctions(): WindowFunctionSchema[] {
+	return Array.from(windowRegistry.values());
+}
+
+// Helper to create ranking function state
+export function createRankingState() {
+	return {
+		rowNumber: 0,
+		rank: 0,
+		denseRank: 0,
+		lastValues: null as SqlValue[] | null
+	};
+}
+
+// Helper for aggregate window function state
+export function createAggregateState(schema: WindowFunctionSchema) {
+	if (schema.step && schema.final) {
+		return {
+			accumulator: null,
+			rowCount: 0
+		};
+	}
+	return null;
+}