@quereus/quereus 0.6.1 → 0.6.3

package/src/common/type-inference.ts

@@ -15,13 +15,21 @@ export function getLiteralSqlType(v: SqlValue): SqlDataType {
 }
 
 /**
- * Infer LogicalType from a SqlValue
+ * Infer LogicalType from a SqlValue for parameters.
+ * Uses JavaScript type to determine the logical type:
+ * - null → NULL
+ * - number (integer) → INTEGER
+ * - number (float) → REAL
+ * - bigint → INTEGER
+ * - boolean → BOOLEAN
+ * - string → TEXT
+ * - Uint8Array → BLOB
  */
 export function inferLogicalTypeFromValue(v: SqlValue): LogicalType {
 	if (v === null) return NULL_TYPE;
 	if (typeof v === 'number') {
-		// For now, all numbers are REAL. Could check Number.isInteger() for INTEGER_TYPE
-		return REAL_TYPE;
+		// Distinguish INTEGER from REAL based on Number.isInteger()
+		return Number.isInteger(v) ? INTEGER_TYPE : REAL_TYPE;
 	}
 	if (typeof v === 'bigint') return INTEGER_TYPE;
 	if (typeof v === 'boolean') return BOOLEAN_TYPE;

package/src/core/database.ts

@@ -43,6 +43,7 @@ import { DeclaredSchemaManager } from '../schema/declared-schema-manager.js';
 import { analyzeRowSpecific } from '../planner/analysis/constraint-extractor.js';
 import { DeferredConstraintQueue } from '../runtime/deferred-constraint-queue.js';
 import { type LogicalType } from '../types/logical-type.js';
+import { getParameterTypes } from './param.js';
 
 const log = createLogger('core:database');
 const warnLog = log.extend('warn');
@@ -196,21 +197,50 @@ export class Database {
 
 	/**
 	 * Prepares an SQL statement for execution.
+	 *
 	 * @param sql The SQL string to prepare.
+	 * @param paramsOrTypes Optional parameter values (to infer types) or explicit type map.
+	 *   - If SqlParameters: Parameter types are inferred from the values
+	 *   - If Map<string|number, ScalarType>: Explicit type hints for parameters
+	 *   - If undefined: Parameters default to TEXT type
 	 * @returns A Statement object.
 	 * @throws QuereusError on failure (e.g., syntax error).
+	 *
+	 * @example
+	 * // Infer types from initial values
+	 * const stmt = db.prepare('INSERT INTO users (id, name) VALUES (?, ?)', [1, 'Alice']);
+	 *
+	 * @example
+	 * // Explicit param types
+	 * const types = new Map([
+	 *   [1, { typeClass: 'scalar', logicalType: INTEGER_TYPE, nullable: false }],
+	 *   [2, { typeClass: 'scalar', logicalType: TEXT_TYPE, nullable: false }]
+	 * ]);
+	 * const stmt = db.prepare('INSERT INTO users (id, name) VALUES (?, ?)', types);
 	 */
-	prepare(sql: string): Statement {
+	prepare(sql: string, paramsOrTypes?: SqlParameters | SqlValue[] | Map<string | number, ScalarType>): Statement {
 		this.checkOpen();
 		log('Preparing SQL (new runtime): %s', sql);
 
 		// Statement constructor defers planning/compilation until first step or explicit compile()
-		const stmt = new Statement(this, sql);
+		const stmt = new Statement(this, sql, 0, paramsOrTypes);
 
 		this.statements.add(stmt);
 		return stmt;
 	}
 
+	/**
+	 * Executes a query and returns the first result row as an object.
+	 * @param sql The SQL query string to execute.
+	 * @param params Optional parameters to bind.
+	 * @returns A Promise resolving to the first result row as an object, or undefined if no rows.
+	 * @throws QuereusError on failure.
+	 */
+	get(sql: string, params?: SqlParameters | SqlValue[]): Promise<Record<string, SqlValue> | undefined> {
+		const stmt = this.prepare(sql, params);
+		return stmt.get(params);
+	}
+
 	/**
 	 * Executes one or more SQL statements directly.
 	 * @param sql The SQL string(s) to execute.
@@ -902,17 +932,22 @@ export class Database {
 	}
 
 	/** @internal */
-	_buildPlan(statements: AST.Statement[], params?: SqlParameters | SqlValue[]) {
+	_buildPlan(statements: AST.Statement[], paramsOrTypes?: SqlParameters | SqlValue[] | Map<string | number, ScalarType>) {
 		const globalScope = new GlobalScope(this.schemaManager);
 
-		// TODO: way to generate type hints from parameters?  Maybe we should extract that from the expression context?
+		// If we received parameter values, infer their types
+		// If we received explicit parameter types, use them as-is
+		const parameterTypes = paramsOrTypes instanceof Map
+			? paramsOrTypes
+			: getParameterTypes(paramsOrTypes);
+
 		// This ParameterScope is for the entire batch. It has globalScope as its parent.
-		const parameterScope = new ParameterScope(globalScope);
+		const parameterScope = new ParameterScope(globalScope, parameterTypes);
 
 		const ctx: PlanningContext = {
 			db: this,
 			schemaManager: this.schemaManager,
-			parameters: params ?? {},
+			parameters: paramsOrTypes instanceof Map ? {} : (paramsOrTypes ?? {}),
 			scope: parameterScope,
 			cteNodes: new Map(),
 			schemaDependencies: new BuildTimeDependencyTracker(),

package/src/core/param.ts

@@ -2,7 +2,23 @@ import type { ScalarType } from '../common/datatype.js';
 import { type SqlParameters, type SqlValue } from '../common/types.js';
 import { inferLogicalTypeFromValue } from '../common/type-inference.js';
 
-export function getParameterTypeHints(params: SqlParameters | undefined): Map<string | number, ScalarType> | undefined {
+/**
+ * Generate type hints for parameters based on their JavaScript values.
+ * This is used during planning to assign strong types to parameters.
+ *
+ * Type inference rules:
+ * - null → NULL
+ * - number (integer) → INTEGER
+ * - number (float) → REAL
+ * - bigint → INTEGER
+ * - boolean → BOOLEAN
+ * - string → TEXT
+ * - Uint8Array → BLOB
+ *
+ * @param params The parameter values (positional array or named object)
+ * @returns Map of parameter keys to their inferred ScalarTypes
+ */
+export function getParameterTypes(params: SqlParameters | undefined): Map<string | number, ScalarType> | undefined {
 	let results: Map<string | number, ScalarType> | undefined;
 	if (params) {
 		results = new Map<string | number, ScalarType>();
@@ -22,6 +38,12 @@ export function getParameterTypeHints(params: SqlParameters | undefined): Map<st
 	return results;
 }
 
+/**
+ * Infer the ScalarType for a parameter value based on its JavaScript type.
+ *
+ * @param value The parameter value
+ * @returns The inferred ScalarType
+ */
 function getParameterScalarType(value: SqlValue): ScalarType {
 	const logicalType = inferLogicalTypeFromValue(value);
 

package/src/core/statement.ts

@@ -14,6 +14,8 @@ import { isAsyncIterable } from '../runtime/utils.js';
 import { generateInstructionProgram, serializePlanTree } from '../planner/debug.js';
 import { EmissionContext } from '../runtime/emission-context.js';
 import type { SchemaDependency } from '../planner/planning-context.js';
+import { getParameterTypes } from './param.js';
+import { getPhysicalType, physicalTypeName } from '../types/logical-type.js';
 
 const log = createLogger('core:statement');
 const errorLog = log.extend('error');
@@ -35,13 +37,21 @@ export class Statement {
 	private needsCompile = true;
 	private columnDefCache = new Cached<DeepReadonly<ColumnDef>[]>(() => this.getColumnDefs());
 	private schemaChangeUnsubscriber: (() => void) | null = null;
+	/** Parameter types established at prepare time (either explicit or inferred from initial values) */
+	private parameterTypes: Map<string | number, ScalarType> | undefined = undefined;
 
 	/**
 	 * @internal - Use db.prepare().
 	 * The `sqlOrAstBatch` can be a single SQL string (parsed internally) or a pre-parsed batch.
 	 * `initialAstIndex` is for internal use when db.prepare might create one Statement per AST in a batch.
+	 * `paramsOrTypes` can be initial parameter values (to infer types) or explicit types.
 	 */
-	constructor(db: Database, sqlOrAstBatch: string | ASTStatement[], initialAstIndex: number = 0) {
+	constructor(
+		db: Database,
+		sqlOrAstBatch: string | ASTStatement[],
+		initialAstIndex: number = 0,
+		paramsOrTypes?: SqlParameters | SqlValue[] | Map<string | number, ScalarType>
+	) {
 		this.db = db;
 		if (typeof sqlOrAstBatch === 'string') {
 			this.originalSql = sqlOrAstBatch;
@@ -58,6 +68,23 @@ export class Statement {
 			this.originalSql = this.astBatch.map(s => s.toString()).join('; '); // TODO: replace with better AST stringification
 		}
 
+		// Handle explicit parameter types or initial values
+		if (paramsOrTypes instanceof Map) {
+			// Explicit parameter types provided
+			this.parameterTypes = paramsOrTypes;
+		} else if (paramsOrTypes !== undefined) {
+			// Initial parameter values - infer types and bind them
+			this.parameterTypes = getParameterTypes(paramsOrTypes);
+			// Also bind the initial values
+			if (Array.isArray(paramsOrTypes)) {
+				paramsOrTypes.forEach((value, index) => {
+					this.boundArgs[index + 1] = value;
+				});
+			} else {
+				Object.assign(this.boundArgs, paramsOrTypes);
+			}
+		}
+
 		if (this.astBatch.length === 0 && initialAstIndex === 0) {
 			// No statements to run, effectively. nextStatement will return false.
 			this.astBatchIndex = -1;
@@ -80,6 +107,7 @@ export class Statement {
 			this.emissionContext = null;
 			this.needsCompile = true;
 			this.columnDefCache.clear();
+			this.parameterTypes = undefined;
 			return true;
 		} else {
 			return false;
@@ -105,7 +133,16 @@ export class Statement {
 		let plan: BlockNode | undefined;
 		try {
 			const currentAst = this.getAstStatement();
-			const planResult = this.db._buildPlan([currentAst], this.boundArgs);
+
+			// On first compilation, establish the parameter types
+			// Use explicit types if provided, otherwise infer from bound args
+			if (this.parameterTypes === undefined) {
+				// Infer types from current bound args
+				this.parameterTypes = getParameterTypes(this.boundArgs);
+			}
+
+			// Pass parameter types directly to planning
+			const planResult = this.db._buildPlan([currentAst], this.parameterTypes);
 			// eslint-disable-next-line @typescript-eslint/no-explicit-any
 			const dependencies = (planResult as any).schemaDependencies; // Extract dependencies from planning context
 			plan = this.db.optimizer.optimize(planResult, this.db) as BlockNode;
@@ -227,6 +264,9 @@ export class Statement {
 
 		if (params) this.bindAll(params);
 
+		// Validate parameter types before execution
+		this.validateParameterTypes();
+
 		this.busy = true;
 		try {
 			const blockPlanNode = this.compile();
@@ -283,14 +323,14 @@ export class Statement {
 	}
 
 	/**
-	 * Clears all bound parameter values, setting them to NULL.
+	 * Clears all bound parameter values.
+	 * Note: This does NOT trigger recompilation - parameter types are preserved.
 	 */
 	clearBindings(): this {
 		this.validateStatement("clear bindings for");
 		if (this.busy) throw new MisuseError("Statement busy, reset first");
 		this.boundArgs = {};
-		this.emissionContext = null;
-		this.needsCompile = true;
+		// Don't set needsCompile - parameter types are preserved
 		return this;
 	}
 
@@ -417,6 +457,50 @@ export class Statement {
 		return this.astBatch[this.astBatchIndex];
 	}
 
+	/**
+	 * Validates that bound parameters match the expected types from compilation.
+	 * Validates that the JavaScript value is compatible with the physical type of the declared logical type.
+	 * @throws QuereusError if parameter types don't match
+	 */
+	private validateParameterTypes(): void {
+		if (!this.parameterTypes) return; // No parameter types established yet
+
+		for (const [key, expectedType] of this.parameterTypes.entries()) {
+			const value = this.boundArgs[key];
+
+			// Allow undefined/missing parameters (they'll be caught at runtime if required)
+			if (value === undefined) continue;
+
+			// NULL is compatible with any nullable type
+			if (value === null) {
+				if (!expectedType.nullable) {
+					throw new QuereusError(
+						`Parameter type mismatch for ${typeof key === 'number' ? `?${key}` : `:${key}`}: ` +
+						`expected non-nullable ${expectedType.logicalType.name}, got NULL`,
+						StatusCode.MISMATCH
+					);
+				}
+				continue;
+			}
+
+			// Get the physical type of the declared logical type
+			const expectedPhysicalType = expectedType.logicalType.physicalType;
+
+			// Get the physical type directly from the JavaScript value
+			const actualPhysicalType = getPhysicalType(value);
+
+			// Check if physical types are compatible
+			if (actualPhysicalType !== expectedPhysicalType) {
+				throw new QuereusError(
+					`Parameter type mismatch for ${typeof key === 'number' ? `?${key}` : `:${key}`}: ` +
+					`expected ${expectedType.logicalType.name} (physical: ${physicalTypeName(expectedPhysicalType)}), ` +
+					`got value with physical type ${physicalTypeName(actualPhysicalType)}`,
+					StatusCode.MISMATCH
+				);
+			}
+		}
+	}
+
 	/**
 	 * Gets a detailed JSON representation of the query plan for debugging.
 	 * @returns JSON string containing the detailed plan tree.