@quereus/quereus 0.2.0 → 0.4.0

package/src/vtab/module.ts

@@ -1,140 +1,170 @@
-import type { Database } from '../core/database.js'; // Assuming Database class exists
-import type { VirtualTable } from './table.js';
-import type { IndexInfo } from './index-info.js';
-import type { ColumnDef } from '../parser/ast.js'; // <-- Add parser AST import
-import type { TableSchema, IndexSchema } from '../schema/table.js'; // Add import for TableSchema and IndexSchema
-import type { BestAccessPlanRequest, BestAccessPlanResult } from './best-access-plan.js';
-
-/**
- * Base interface for module-specific configuration passed to xCreate/xConnect.
- * Modules should define their own interface extending this if they need options.
- */
-// eslint-disable-next-line @typescript-eslint/no-empty-object-type
-export interface BaseModuleConfig {}
-
-/**
- * Interface defining the methods for a virtual table module implementation.
- * The module primarily acts as a factory for connection-specific VirtualTable instances.
- *
- * @template TTable The specific type of VirtualTable managed by this module.
- * @template TConfig The type defining module-specific configuration options.
- */
-export interface VirtualTableModule<
-	TTable extends VirtualTable,
-	TConfig extends BaseModuleConfig = BaseModuleConfig
-> {
-
-	/**
-	 * Creates the persistent definition of a virtual table.
-	 * Called by CREATE VIRTUAL TABLE to define schema and initialize storage.
-	 *
-	 * @param db The database connection
-	 * @param tableSchema The schema definition for the table being created
-	 * @returns The new VirtualTable instance
-	 * @throws QuereusError on failure
-	 */
-	xCreate(
-		db: Database,
-		tableSchema: TableSchema,
-	): TTable;
-
-	/**
-	 * Connects to an existing virtual table definition.
-	 * Called when the schema is loaded or a connection needs to interact with the table.
-	 *
-	 * @param db The database connection
-	 * @param pAux Client data passed during module registration
-	 * @param moduleName The name the module was registered with
-	 * @param schemaName The name of the database schema
-	 * @param tableName The name of the virtual table to connect to
-	 * @param options Module-specific configuration options from the original CREATE VIRTUAL TABLE
-	 * @returns The connection-specific VirtualTable instance
-	 * @throws QuereusError on failure
-	 */
-	xConnect(
-		db: Database,
-		pAux: unknown,
-		moduleName: string,
-		schemaName: string,
-		tableName: string,
-		options: TConfig
-	): TTable;
-
-	/**
-	 * Modern, type-safe access planning interface.
-	 * Preferred over xBestIndex for new implementations.
-	 *
-	 * @param db The database connection
-	 * @param tableInfo The schema information for the table being planned
-	 * @param request Planning request with constraints and requirements
-	 * @returns Access plan result describing the chosen strategy
-	 */
-	getBestAccessPlan?(
-		db: Database,
-		tableInfo: TableSchema,
-		request: BestAccessPlanRequest
-	): BestAccessPlanResult;
-
-	/**
-	 * Determines the best query plan for a given set of constraints and orderings.
-	 * This method MUST be synchronous for performance. It modifies the passed IndexInfo object.
-	 *
-	 * @deprecated Use getBestAccessPlan instead for better type safety and extensibility
-	 * @param db The database connection
-	 * @param tableInfo The schema information for the table being planned
-	 * @param indexInfo Input constraints/orderings and output plan details
-	 * @returns StatusCode.OK on success, or an error code
-	 */
-	xBestIndex(db: Database, tableInfo: TableSchema, indexInfo: IndexInfo): number;
-
-	/**
-	 * Destroys the underlying persistent representation of the virtual table.
-	 * Called by DROP TABLE.
-	 *
-	 * @param db The database connection
-	 * @param pAux Client data passed during module registration
-	 * @param moduleName The name the module was registered with
-	 * @param schemaName The name of the database schema
-	 * @param tableName The name of the virtual table being destroyed
-	 * @throws QuereusError on failure
-	 */
-	xDestroy(
-		db: Database,
-		pAux: unknown,
-		moduleName: string,
-		schemaName: string,
-		tableName: string
-	): Promise<void>;
-
-	/**
-	 * Creates an index on a virtual table.
-	 * Called by CREATE INDEX.
-	 *
-	 * @param db The database connection
-	 * @param schemaName The name of the database schema
-	 * @param tableName The name of the virtual table
-	 * @param indexSchema The schema definition for the index being created
-	 * @throws QuereusError on failure
-	 */
-	xCreateIndex?(
-		db: Database,
-		schemaName: string,
-		tableName: string,
-		indexSchema: IndexSchema
-	): Promise<void>;
-
-	/**
-	 * Checks for shadow table name conflicts
-	 * @param name The name to check
-	 * @returns true if the name would conflict
-	 */
-	xShadowName?(name: string): boolean;
-}
-
-/**
- * Defines the structure for schema change information passed to xAlterSchema
- */
-export type SchemaChangeInfo =
-	| { type: 'addColumn'; columnDef: ColumnDef }
-	| { type: 'dropColumn'; columnName: string }
-	| { type: 'renameColumn'; oldName: string; newName: string; newColumnDefAst?: ColumnDef };
+import type { Database } from '../core/database.js'; // Assuming Database class exists
+import type { VirtualTable } from './table.js';
+import type { IndexInfo } from './index-info.js';
+import type { ColumnDef } from '../parser/ast.js'; // <-- Add parser AST import
+import type { TableSchema, IndexSchema } from '../schema/table.js'; // Add import for TableSchema and IndexSchema
+import type { BestAccessPlanRequest, BestAccessPlanResult } from './best-access-plan.js';
+import type { PlanNode } from '../planner/nodes/plan-node.js';
+
+/**
+ * Base interface for module-specific configuration passed to xCreate/xConnect.
+ * Modules should define their own interface extending this if they need options.
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export interface BaseModuleConfig {}
+
+/**
+ * Assessment result from a module's supports() method indicating
+ * whether it can execute a plan subtree and at what cost.
+ */
+export interface SupportAssessment {
+	/** Estimated cost comparable to local evaluation cost */
+	cost: number;
+	/** Optional context data persisted for the emitter */
+	ctx?: unknown;
+}
+
+/**
+ * Interface defining the methods for a virtual table module implementation.
+ * The module primarily acts as a factory for connection-specific VirtualTable instances.
+ *
+ * @template TTable The specific type of VirtualTable managed by this module.
+ * @template TConfig The type defining module-specific configuration options.
+ */
+export interface VirtualTableModule<
+	TTable extends VirtualTable,
+	TConfig extends BaseModuleConfig = BaseModuleConfig
+> {
+
+	/**
+	 * Creates the persistent definition of a virtual table.
+	 * Called by CREATE VIRTUAL TABLE to define schema and initialize storage.
+	 *
+	 * @param db The database connection
+	 * @param tableSchema The schema definition for the table being created
+	 * @returns The new VirtualTable instance
+	 * @throws QuereusError on failure
+	 */
+	xCreate(
+		db: Database,
+		tableSchema: TableSchema,
+	): TTable;
+
+	/**
+	 * Connects to an existing virtual table definition.
+	 * Called when the schema is loaded or a connection needs to interact with the table.
+	 *
+	 * @param db The database connection
+	 * @param pAux Client data passed during module registration
+	 * @param moduleName The name the module was registered with
+	 * @param schemaName The name of the database schema
+	 * @param tableName The name of the virtual table to connect to
+	 * @param options Module-specific configuration options from the original CREATE VIRTUAL TABLE
+	 * @returns The connection-specific VirtualTable instance
+	 * @throws QuereusError on failure
+	 */
+	xConnect(
+		db: Database,
+		pAux: unknown,
+		moduleName: string,
+		schemaName: string,
+		tableName: string,
+		options: TConfig
+	): TTable;
+
+	/**
+	 * Determines if this module can execute a plan subtree starting at the given node.
+	 * Used for query push-down to virtual table modules that support arbitrary queries.
+	 *
+	 * @param node The root node of the subtree to evaluate
+	 * @returns Assessment with cost and optional context, or undefined if not supported
+	 */
+	supports?(
+		node: PlanNode
+	): SupportAssessment | undefined;
+
+	/**
+	 * Modern, type-safe access planning interface.
+	 * Preferred over xBestIndex for new implementations.
+	 *
+	 * @param db The database connection
+	 * @param tableInfo The schema information for the table being planned
+	 * @param request Planning request with constraints and requirements
+	 * @returns Access plan result describing the chosen strategy
+	 */
+	getBestAccessPlan?(
+		db: Database,
+		tableInfo: TableSchema,
+		request: BestAccessPlanRequest
+	): BestAccessPlanResult;
+
+	/**
+	 * Determines the best query plan for a given set of constraints and orderings.
+	 * This method MUST be synchronous for performance. It modifies the passed IndexInfo object.
+	 *
+	 * @deprecated Use getBestAccessPlan instead for better type safety and extensibility
+	 * @param db The database connection
+	 * @param tableInfo The schema information for the table being planned
+	 * @param indexInfo Input constraints/orderings and output plan details
+	 * @returns StatusCode.OK on success, or an error code
+	 */
+	xBestIndex(db: Database, tableInfo: TableSchema, indexInfo: IndexInfo): number;
+
+	/**
+	 * Destroys the underlying persistent representation of the virtual table.
+	 * Called by DROP TABLE.
+	 *
+	 * @param db The database connection
+	 * @param pAux Client data passed during module registration
+	 * @param moduleName The name the module was registered with
+	 * @param schemaName The name of the database schema
+	 * @param tableName The name of the virtual table being destroyed
+	 * @throws QuereusError on failure
+	 */
+	xDestroy(
+		db: Database,
+		pAux: unknown,
+		moduleName: string,
+		schemaName: string,
+		tableName: string
+	): Promise<void>;
+
+	/**
+	 * Creates an index on a virtual table.
+	 * Called by CREATE INDEX.
+	 *
+	 * @param db The database connection
+	 * @param schemaName The name of the database schema
+	 * @param tableName The name of the virtual table
+	 * @param indexSchema The schema definition for the index being created
+	 * @throws QuereusError on failure
+	 */
+	xCreateIndex?(
+		db: Database,
+		schemaName: string,
+		tableName: string,
+		indexSchema: IndexSchema
+	): Promise<void>;
+
+	/**
+	 * Checks for shadow table name conflicts
+	 * @param name The name to check
+	 * @returns true if the name would conflict
+	 */
+	xShadowName?(name: string): boolean;
+}
+
+/**
+ * Defines the structure for schema change information passed to xAlterSchema
+ */
+export type SchemaChangeInfo =
+	| { type: 'addColumn'; columnDef: ColumnDef }
+	| { type: 'dropColumn'; columnName: string }
+	| { type: 'renameColumn'; oldName: string; newName: string; newColumnDefAst?: ColumnDef };
+
+/**
+ * Type alias for the common usage pattern where specific table and config types are not known.
+ * Use this for storage scenarios like the SchemaManager where modules of different types are stored together.
+ * eslint-disable-next-line @typescript-eslint/no-explicit-any
+ */
+export type AnyVirtualTableModule = VirtualTableModule<any, any>;

package/src/vtab/table.ts

@@ -1,143 +1,162 @@
-import type { VirtualTableModule, SchemaChangeInfo } from './module.js';
-import type { Database } from '../core/database.js';
-import type { TableSchema } from '../schema/table.js';
-import type { MaybePromise, Row } from '../common/types.js';
-import type { IndexSchema } from '../schema/table.js';
-import type { FilterInfo } from './filter-info.js';
-import type { RowOp } from '../parser/ast.js';
-import type { VirtualTableConnection } from './connection.js';
-
-/**
- * Base class representing a virtual table instance.
- * Module implementations should subclass this to provide specific table behavior.
- */
-export abstract class VirtualTable {
-	public readonly module: VirtualTableModule<any, any>;
-	public readonly db: Database;
-	public readonly tableName: string;
-	public readonly schemaName: string;
-	public errorMessage?: string;
-	public tableSchema?: TableSchema;
-
-	constructor(db: Database, module: VirtualTableModule<any, any>, schemaName: string, tableName: string) {
-		this.db = db;
-		this.module = module;
-		this.schemaName = schemaName;
-		this.tableName = tableName;
-	}
-
-	/**
-	 * Sets an error message for the VTable
-	 * @param message The error message string
-	 */
-	protected setErrorMessage(message: string | undefined): void {
-		this.errorMessage = message;
-	}
-
-	/**
-	 * Disconnects from this virtual table connection instance
-	 * Called when the database connection closes or the statement is finalized
-	 * @throws QuereusError on failure
-	 */
-	abstract xDisconnect(): Promise<void>;
-
-	/**
-	 * (Optional) Opens a direct data stream for this virtual table based on filter criteria.
-	 * This is an alternative to the cursor-based xOpen/filter/next model.
-	 * @param filterInfo Information from xBestIndex and query parameters.
-	 * @returns An AsyncIterable yielding Row tuples.
-	 * @throws QuereusError on failure
-	 */
-	xQuery?(filterInfo: FilterInfo): AsyncIterable<Row>;
-
-	/**
-	 * Performs an INSERT, UPDATE, or DELETE operation
-	 * @param operation The operation to perform (insert, update, delete)
-	 * @param values For INSERT/UPDATE, the values to insert/update. For DELETE, undefined
-	 * @param oldKeyValues For UPDATE/DELETE, the old key values of the row to modify. Undefined for INSERT
-	 * @returns new row for INSERT/UPDATE, undefined for DELETE
-	 * @throws QuereusError or ConstraintError on failure
-	 */
-	abstract xUpdate(
-		operation: RowOp,
-		values: Row | undefined,
-		oldKeyValues?: Row
-	): Promise<Row | undefined>;
-
-	/**
-	 * (Optional) Creates a new connection for transaction support.
-	 * If implemented, this enables proper transaction isolation for this table.
-	 * @returns A new VirtualTableConnection instance
-	 */
-	createConnection?(): MaybePromise<VirtualTableConnection>;
-
-	/**
-	 * (Optional) Gets the current connection for this table instance.
-	 * Used when the table maintains a single connection internally.
-	 * @returns The current VirtualTableConnection instance, if any
-	 */
-	getConnection?(): VirtualTableConnection | undefined;
-
-	/**
-	 * Begins a transaction on this virtual table
-	 */
-	xBegin?(): Promise<void>;
-
-	/**
-	 * Syncs changes within the virtual table transaction
-	 */
-	xSync?(): Promise<void>;
-
-	/**
-	 * Commits the virtual table transaction
-	 */
-	xCommit?(): Promise<void>;
-
-	/**
-	 * Rolls back the virtual table transaction
-	 */
-	xRollback?(): Promise<void>;
-
-	/**
-	 * Renames the virtual table
-	 * @param newName The new name for the table
-	 */
-	xRename?(newName: string): Promise<void>;
-
-	/**
-	 * Begins a savepoint
-	 * @param savepointIndex The savepoint identifier
-	 */
-	xSavepoint?(savepointIndex: number): Promise<void>;
-
-	/**
-	 * Releases a savepoint
-	 * @param savepointIndex The savepoint identifier
-	 */
-	xRelease?(savepointIndex: number): Promise<void>;
-
-	/**
-	 * Rolls back to a savepoint
-	 * @param savepointIndex The savepoint identifier
-	 */
-	xRollbackTo?(savepointIndex: number): Promise<void>;
-
-	/**
-	 * Modifies the schema of this virtual table
-	 * @param changeInfo Object describing the schema modification
-	 * @throws QuereusError or ConstraintError on failure
-	 */
-	xAlterSchema?(changeInfo: SchemaChangeInfo): Promise<void>;
-
-	/**
-	 * Creates a secondary index on the virtual table
-	 * @param indexInfo The index definition
-	 */
-	xCreateIndex?(indexInfo: IndexSchema): Promise<void>;
-
-	/**
-	 * Drops a secondary index from the virtual table
-	 * @param indexName The name of the index to drop
-	 */
-	xDropIndex?(indexName: string): Promise<void>;
-}
+import type { AnyVirtualTableModule, SchemaChangeInfo } from './module.js';
+import type { Database } from '../core/database.js';
+import type { TableSchema } from '../schema/table.js';
+import type { MaybePromise, Row } from '../common/types.js';
+import type { IndexSchema } from '../schema/table.js';
+import type { FilterInfo } from './filter-info.js';
+import type { RowOp } from '../common/types.js';
+import type { ConflictResolution } from '../common/constants.js';
+import type { VirtualTableConnection } from './connection.js';
+import type { PlanNode } from '../planner/nodes/plan-node.js';
+
+/**
+ * Base class representing a virtual table instance.
+ * Module implementations should subclass this to provide specific table behavior.
+ */
+export abstract class VirtualTable {
+	public readonly module: AnyVirtualTableModule;
+	public readonly db: Database;
+	public readonly tableName: string;
+	public readonly schemaName: string;
+	public errorMessage?: string;
+	public tableSchema?: TableSchema;
+
+	constructor(db: Database, module: AnyVirtualTableModule, schemaName: string, tableName: string) {
+		this.db = db;
+		this.module = module;
+		this.schemaName = schemaName;
+		this.tableName = tableName;
+	}
+
+	/**
+	 * Sets an error message for the VTable
+	 * @param message The error message string
+	 */
+	protected setErrorMessage(message: string | undefined): void {
+		this.errorMessage = message;
+	}
+
+	/**
+	 * Disconnects from this virtual table connection instance
+	 * Called when the database connection closes or the statement is finalized
+	 * @throws QuereusError on failure
+	 */
+	abstract xDisconnect(): Promise<void>;
+
+	/**
+	 * (Optional) Opens a direct data stream for this virtual table based on filter criteria.
+	 * This is an alternative to the cursor-based xOpen/filter/next model.
+	 * @param filterInfo Information from xBestIndex and query parameters.
+	 * @returns An AsyncIterable yielding Row tuples.
+	 * @throws QuereusError on failure
+	 */
+	xQuery?(filterInfo: FilterInfo): AsyncIterable<Row>;
+
+	/**
+	 * Executes a pushed-down plan subtree.
+	 * Called when the module indicated support via supports() method.
+	 *
+	 * @param db The database connection
+	 * @param plan The plan node to execute
+	 * @param ctx Optional context from supports() assessment
+	 * @returns Async iterable of rows resulting from the plan execution
+	 */
+	xExecutePlan?(
+		db: Database,
+		plan: PlanNode,
+		ctx?: unknown
+	): AsyncIterable<Row>;
+
+	/**
+	 * Performs an INSERT, UPDATE, or DELETE operation
+	 * @param operation The operation to perform (insert, update, delete)
+	 * @param values For INSERT/UPDATE, the values to insert/update. For DELETE, undefined
+	 * @param oldKeyValues For UPDATE/DELETE, the old key values of the row to modify. Undefined for INSERT
+	 * @param onConflict Conflict resolution mode (defaults to ABORT if unspecified)
+	 * @returns new row for INSERT/UPDATE, undefined for DELETE
+	 * @throws QuereusError or ConstraintError on failure
+	 */
+	abstract xUpdate(
+		operation: RowOp,
+		values: Row | undefined,
+		oldKeyValues?: Row,
+		onConflict?: ConflictResolution
+	): Promise<Row | undefined>;
+
+	/**
+	 * (Optional) Creates a new connection for transaction support.
+	 * If implemented, this enables proper transaction isolation for this table.
+	 * @returns A new VirtualTableConnection instance
+	 */
+	createConnection?(): MaybePromise<VirtualTableConnection>;
+
+	/**
+	 * (Optional) Gets the current connection for this table instance.
+	 * Used when the table maintains a single connection internally.
+	 * @returns The current VirtualTableConnection instance, if any
+	 */
+	getConnection?(): VirtualTableConnection | undefined;
+
+	/**
+	 * Begins a transaction on this virtual table
+	 */
+	xBegin?(): Promise<void>;
+
+	/**
+	 * Syncs changes within the virtual table transaction
+	 */
+	xSync?(): Promise<void>;
+
+	/**
+	 * Commits the virtual table transaction
+	 */
+	xCommit?(): Promise<void>;
+
+	/**
+	 * Rolls back the virtual table transaction
+	 */
+	xRollback?(): Promise<void>;
+
+	/**
+	 * Renames the virtual table
+	 * @param newName The new name for the table
+	 */
+	xRename?(newName: string): Promise<void>;
+
+	/**
+	 * Begins a savepoint
+	 * @param savepointIndex The savepoint identifier
+	 */
+	xSavepoint?(savepointIndex: number): Promise<void>;
+
+	/**
+	 * Releases a savepoint
+	 * @param savepointIndex The savepoint identifier
+	 */
+	xRelease?(savepointIndex: number): Promise<void>;
+
+	/**
+	 * Rolls back to a savepoint
+	 * @param savepointIndex The savepoint identifier
+	 */
+	xRollbackTo?(savepointIndex: number): Promise<void>;
+
+	/**
+	 * Modifies the schema of this virtual table
+	 * @param changeInfo Object describing the schema modification
+	 * @throws QuereusError or ConstraintError on failure
+	 */
+	xAlterSchema?(changeInfo: SchemaChangeInfo): Promise<void>;
+
+	/**
+	 * Creates a secondary index on the virtual table
+	 * @param indexInfo The index definition
+	 */
+	xCreateIndex?(indexInfo: IndexSchema): Promise<void>;
+
+	/**
+	 * Drops a secondary index from the virtual table
+	 * @param indexName The name of the index to drop
+	 */
+	xDropIndex?(indexName: string): Promise<void>;
+}