@quereus/quereus 0.4.11 → 0.5.0

package/src/types/registry.ts

@@ -0,0 +1,200 @@
+import type { LogicalType } from './logical-type.js';
+import {
+	NULL_TYPE,
+	INTEGER_TYPE,
+	REAL_TYPE,
+	TEXT_TYPE,
+	BLOB_TYPE,
+	BOOLEAN_TYPE,
+	NUMERIC_TYPE,
+	ANY_TYPE,
+} from './builtin-types.js';
+import { DATE_TYPE, TIME_TYPE, DATETIME_TYPE } from './temporal-types.js';
+import { JSON_TYPE } from './json-type.js';
+import { createLogger } from '../common/logger.js';
+
+const log = createLogger('types:registry');
+const warnLog = log.extend('warn');
+const debugLog = log.extend('debug');
+
+/**
+ * Global type registry that maps type names to logical type definitions.
+ */
+class TypeRegistry {
+	private types = new Map<string, LogicalType>();
+
+	constructor() {
+		// Register built-in types
+		this.registerType(NULL_TYPE);
+		this.registerType(INTEGER_TYPE);
+		this.registerType(REAL_TYPE);
+		this.registerType(TEXT_TYPE);
+		this.registerType(BLOB_TYPE);
+		this.registerType(BOOLEAN_TYPE);
+		this.registerType(NUMERIC_TYPE);
+		this.registerType(ANY_TYPE);
+		this.registerType(DATE_TYPE);
+		this.registerType(TIME_TYPE);
+		this.registerType(DATETIME_TYPE);
+		this.registerType(JSON_TYPE);
+
+		// Register common aliases
+		this.types.set('INT', INTEGER_TYPE);
+		this.types.set('BIGINT', INTEGER_TYPE);
+		this.types.set('SMALLINT', INTEGER_TYPE);
+		this.types.set('TINYINT', INTEGER_TYPE);
+		this.types.set('MEDIUMINT', INTEGER_TYPE);
+
+		this.types.set('FLOAT', REAL_TYPE);
+		this.types.set('DOUBLE', REAL_TYPE);
+		this.types.set('DECIMAL', NUMERIC_TYPE);
+
+		this.types.set('VARCHAR', TEXT_TYPE);
+		this.types.set('CHAR', TEXT_TYPE);
+		this.types.set('CHARACTER', TEXT_TYPE);
+		this.types.set('CLOB', TEXT_TYPE);
+		this.types.set('STRING', TEXT_TYPE);
+
+		this.types.set('BOOL', BOOLEAN_TYPE);
+
+		this.types.set('BYTES', BLOB_TYPE);
+		this.types.set('BINARY', BLOB_TYPE);
+		this.types.set('VARBINARY', BLOB_TYPE);
+	}
+
+	/**
+	 * Register a new logical type.
+	 * @param type The logical type to register
+	 */
+	registerType(type: LogicalType): void {
+		const upperName = type.name.toUpperCase();
+		if (this.types.has(upperName)) {
+			warnLog(`Overwriting existing type: ${upperName}`);
+		}
+		this.types.set(upperName, type);
+		debugLog(`Registered type: ${upperName}`);
+	}
+
+	/**
+	 * Get a logical type by name.
+	 * @param name The type name (case-insensitive)
+	 * @returns The logical type, or undefined if not found
+	 */
+	getType(name: string): LogicalType | undefined {
+		return this.types.get(name.toUpperCase());
+	}
+
+	/**
+	 * Get a logical type by name, with fallback to BLOB if not found.
+	 * This matches SQLite's behavior where unknown types default to BLOB affinity.
+	 * @param name The type name (case-insensitive)
+	 * @returns The logical type (defaults to BLOB if not found)
+	 */
+	getTypeOrDefault(name: string | undefined): LogicalType {
+		if (!name) return BLOB_TYPE;
+		return this.getType(name) ?? BLOB_TYPE;
+	}
+
+	/**
+	 * Check if a type is registered.
+	 * @param name The type name (case-insensitive)
+	 * @returns True if the type is registered
+	 */
+	hasType(name: string): boolean {
+		return this.types.has(name.toUpperCase());
+	}
+
+	/**
+	 * Get all registered type names.
+	 * @returns Array of type names
+	 */
+	getTypeNames(): string[] {
+		return Array.from(this.types.keys());
+	}
+
+	/**
+	 * Infer logical type from a type name string.
+	 * This handles SQLite-style type affinity rules where type names can contain
+	 * keywords like "INT", "CHAR", "REAL", etc.
+	 *
+	 * @param typeName The declared type name (e.g., "VARCHAR(100)", "UNSIGNED INT")
+	 * @returns The inferred logical type
+	 */
+	inferType(typeName: string | undefined): LogicalType {
+		if (!typeName) return BLOB_TYPE;
+
+		const upperName = typeName.toUpperCase();
+
+		// First try exact match
+		const exactMatch = this.types.get(upperName);
+		if (exactMatch) return exactMatch;
+
+		// SQLite-style affinity rules
+		// INTEGER affinity: INT
+		if (upperName.includes('INT')) return INTEGER_TYPE;
+
+		// TEXT affinity: CHAR, CLOB, TEXT
+		if (upperName.includes('CHAR') || upperName.includes('CLOB') || upperName.includes('TEXT')) {
+			return TEXT_TYPE;
+		}
+
+		// BLOB affinity: BLOB
+		if (upperName.includes('BLOB')) return BLOB_TYPE;
+
+		// REAL affinity: REAL, FLOA, DOUB
+		if (upperName.includes('REAL') || upperName.includes('FLOA') || upperName.includes('DOUB')) {
+			return REAL_TYPE;
+		}
+
+		// BOOLEAN affinity: BOOL
+		if (upperName.includes('BOOL')) return BOOLEAN_TYPE;
+
+		// NUMERIC affinity: everything else with NUMERIC, DECIMAL
+		if (upperName.includes('NUMERIC') || upperName.includes('DECIMAL')) {
+			return NUMERIC_TYPE;
+		}
+
+		// Default to BLOB (SQLite behavior)
+		debugLog(`Unknown type '${typeName}', defaulting to BLOB`);
+		return BLOB_TYPE;
+	}
+}
+
+// Global singleton instance
+export const typeRegistry = new TypeRegistry();
+
+/**
+ * Register a custom logical type.
+ * @param type The logical type to register
+ */
+export function registerType(type: LogicalType): void {
+	typeRegistry.registerType(type);
+}
+
+/**
+ * Get a logical type by name.
+ * @param name The type name (case-insensitive)
+ * @returns The logical type, or undefined if not found
+ */
+export function getType(name: string): LogicalType | undefined {
+	return typeRegistry.getType(name);
+}
+
+/**
+ * Get a logical type by name, with fallback to BLOB if not found.
+ * @param name The type name (case-insensitive)
+ * @returns The logical type (defaults to BLOB if not found)
+ */
+export function getTypeOrDefault(name: string | undefined): LogicalType {
+	return typeRegistry.getTypeOrDefault(name);
+}
+
+/**
+ * Infer logical type from a type name string.
+ * @param typeName The declared type name
+ * @returns The inferred logical type
+ */
+export function inferType(typeName: string | undefined): LogicalType {
+	return typeRegistry.inferType(typeName);
+}
+

package/src/types/temporal-types.ts

@@ -0,0 +1,167 @@
+import { PhysicalType, type LogicalType } from './logical-type.js';
+import { Temporal } from 'temporal-polyfill';
+
+/**
+ * DATE type - stores ISO 8601 date strings (YYYY-MM-DD)
+ * Uses Temporal.PlainDate for validation and parsing
+ */
+export const DATE_TYPE: LogicalType = {
+	name: 'DATE',
+	physicalType: PhysicalType.TEXT,
+	isTemporal: true,
+
+	validate: (v) => {
+		if (v === null) return true;
+		if (typeof v !== 'string') return false;
+		try {
+			Temporal.PlainDate.from(v);
+			return true;
+		} catch {
+			return false;
+		}
+	},
+
+	parse: (v) => {
+		if (v === null) return null;
+		if (typeof v === 'string') {
+			try {
+				const date = Temporal.PlainDate.from(v);
+				return date.toString(); // ISO 8601 format: YYYY-MM-DD
+			} catch (e) {
+				throw new TypeError(`Cannot convert '${v}' to DATE: ${e instanceof Error ? e.message : String(e)}`);
+			}
+		}
+		if (typeof v === 'number') {
+			// Unix timestamp (milliseconds)
+			const instant = Temporal.Instant.fromEpochMilliseconds(v);
+			return instant.toZonedDateTimeISO('UTC').toPlainDate().toString();
+		}
+		throw new TypeError(`Cannot convert ${typeof v} to DATE`);
+	},
+
+	compare: (a, b) => {
+		if (a === null && b === null) return 0;
+		if (a === null) return -1;
+		if (b === null) return 1;
+		// ISO 8601 dates can be compared lexicographically
+		return (a as string).localeCompare(b as string);
+	},
+
+	supportedCollations: [],
+};
+
+/**
+ * TIME type - stores ISO 8601 time strings (HH:MM:SS or HH:MM:SS.sss)
+ * Uses Temporal.PlainTime for validation and parsing
+ */
+export const TIME_TYPE: LogicalType = {
+	name: 'TIME',
+	physicalType: PhysicalType.TEXT,
+	isTemporal: true,
+
+	validate: (v) => {
+		if (v === null) return true;
+		if (typeof v !== 'string') return false;
+		try {
+			Temporal.PlainTime.from(v);
+			return true;
+		} catch {
+			return false;
+		}
+	},
+
+	parse: (v) => {
+		if (v === null) return null;
+		if (typeof v === 'string') {
+			try {
+				const time = Temporal.PlainTime.from(v);
+				return time.toString(); // ISO 8601 format: HH:MM:SS or HH:MM:SS.sss
+			} catch (e) {
+				throw new TypeError(`Cannot convert '${v}' to TIME: ${e instanceof Error ? e.message : String(e)}`);
+			}
+		}
+		if (typeof v === 'number') {
+			// Seconds since midnight
+			const hours = Math.floor(v / 3600) % 24;
+			const minutes = Math.floor((v % 3600) / 60);
+			const seconds = v % 60;
+			const time = new Temporal.PlainTime(hours, minutes, seconds);
+			return time.toString();
+		}
+		throw new TypeError(`Cannot convert ${typeof v} to TIME`);
+	},
+
+	compare: (a, b) => {
+		if (a === null && b === null) return 0;
+		if (a === null) return -1;
+		if (b === null) return 1;
+		// ISO 8601 times can be compared lexicographically
+		return (a as string).localeCompare(b as string);
+	},
+
+	supportedCollations: [],
+};
+
+/**
+ * DATETIME type - stores ISO 8601 datetime strings (YYYY-MM-DDTHH:MM:SS or with timezone)
+ * Uses Temporal.PlainDateTime for validation and parsing
+ */
+export const DATETIME_TYPE: LogicalType = {
+	name: 'DATETIME',
+	physicalType: PhysicalType.TEXT,
+	isTemporal: true,
+
+	validate: (v) => {
+		if (v === null) return true;
+		if (typeof v !== 'string') return false;
+		try {
+			// Try PlainDateTime first
+			Temporal.PlainDateTime.from(v);
+			return true;
+		} catch {
+			try {
+				// Also accept ZonedDateTime
+				Temporal.ZonedDateTime.from(v);
+				return true;
+			} catch {
+				return false;
+			}
+		}
+	},
+
+	parse: (v) => {
+		if (v === null) return null;
+		if (typeof v === 'string') {
+			try {
+				// Try PlainDateTime first
+				const dt = Temporal.PlainDateTime.from(v);
+				return dt.toString(); // ISO 8601 format: YYYY-MM-DDTHH:MM:SS
+			} catch {
+				try {
+					// Try ZonedDateTime
+					const zdt = Temporal.ZonedDateTime.from(v);
+					return zdt.toString(); // ISO 8601 with timezone
+				} catch (e) {
+					throw new TypeError(`Cannot convert '${v}' to DATETIME: ${e instanceof Error ? e.message : String(e)}`);
+				}
+			}
+		}
+		if (typeof v === 'number') {
+			// Unix timestamp (milliseconds)
+			const instant = Temporal.Instant.fromEpochMilliseconds(v);
+			return instant.toZonedDateTimeISO('UTC').toString();
+		}
+		throw new TypeError(`Cannot convert ${typeof v} to DATETIME`);
+	},
+
+	compare: (a, b) => {
+		if (a === null && b === null) return 0;
+		if (a === null) return -1;
+		if (b === null) return 1;
+		// ISO 8601 datetimes can be compared lexicographically
+		return (a as string).localeCompare(b as string);
+	},
+
+	supportedCollations: [],
+};
+

package/src/types/validation.ts

@@ -0,0 +1,120 @@
+import type { SqlValue } from '../common/types.js';
+import { StatusCode } from '../common/types.js';
+import { QuereusError } from '../common/errors.js';
+import type { LogicalType } from './logical-type.js';
+
+/**
+ * Validate a value against a logical type.
+ * Throws an error if the value is invalid.
+ *
+ * @param value The value to validate
+ * @param type The logical type to validate against
+ * @param columnName Optional column name for better error messages
+ * @returns The validated value
+ * @throws QuereusError if validation fails
+ */
+export function validateValue(
+	value: SqlValue,
+	type: LogicalType,
+	columnName?: string
+): SqlValue {
+	// NULL is always valid
+	if (value === null) return null;
+
+	// Type-specific validation
+	if (type.validate && !type.validate(value)) {
+		const colInfo = columnName ? ` for column '${columnName}'` : '';
+		throw new QuereusError(
+			`Type mismatch${colInfo}: expected ${type.name}, got ${typeof value}`,
+			StatusCode.MISMATCH
+		);
+	}
+
+	return value;
+}
+
+/**
+ * Parse/convert a value to match a logical type.
+ * This performs type conversion and normalization.
+ *
+ * @param value The value to parse
+ * @param type The logical type to convert to
+ * @param columnName Optional column name for better error messages
+ * @returns The parsed/converted value
+ * @throws QuereusError if conversion fails
+ */
+export function parseValue(
+	value: SqlValue,
+	type: LogicalType,
+	columnName?: string
+): SqlValue {
+	// NULL is always valid
+	if (value === null) return null;
+
+	// Type-specific parsing
+	if (type.parse) {
+		try {
+			return type.parse(value);
+		} catch (error) {
+			const colInfo = columnName ? ` for column '${columnName}'` : '';
+			const message = error instanceof Error ? error.message : String(error);
+			throw new QuereusError(
+				`Type conversion failed${colInfo}: ${message}`,
+				StatusCode.MISMATCH
+			);
+		}
+	}
+
+	return value;
+}
+
+/**
+ * Validate and parse a value in one step.
+ * This is the main entry point for type checking at INSERT/UPDATE boundaries.
+ *
+ * @param value The value to validate and parse
+ * @param type The logical type
+ * @param columnName Optional column name for better error messages
+ * @returns The validated and parsed value
+ * @throws QuereusError if validation or parsing fails
+ */
+export function validateAndParse(
+	value: SqlValue,
+	type: LogicalType,
+	columnName?: string
+): SqlValue {
+	// Parse first (which may convert the value)
+	const parsed = parseValue(value, type, columnName);
+
+	// Then validate the parsed result
+	return validateValue(parsed, type, columnName);
+}
+
+/**
+ * Check if a value is compatible with a logical type without throwing.
+ *
+ * @param value The value to check
+ * @param type The logical type
+ * @returns True if the value is valid for the type
+ */
+export function isValidForType(value: SqlValue, type: LogicalType): boolean {
+	if (value === null) return true;
+	if (!type.validate) return true;
+	return type.validate(value);
+}
+
+/**
+ * Try to parse a value, returning null if parsing fails.
+ *
+ * @param value The value to parse
+ * @param type The logical type
+ * @returns The parsed value, or null if parsing fails
+ */
+export function tryParse(value: SqlValue, type: LogicalType): SqlValue | null {
+	try {
+		return parseValue(value, type);
+	} catch {
+		return null;
+	}
+}
+

package/src/util/comparison.ts

@@ -1,14 +1,14 @@
 import type { Row, SqlValue } from '../common/types.js';
 import { createLogger } from '../common/logger.js';
+import type { LogicalType, CollationFunction } from '../types/logical-type.js';
+import { StatusCode } from '../common/types.js';
+import { QuereusError } from '../common/errors.js';
 
 const log = createLogger('util:comparison');
 const warnLog = log.extend('warn');
 
-/**
- * Function type for SQLite collation functions.
- * Takes two strings and returns a comparison result (-1, 0, 1)
- */
-export type CollationFunction = (a: string, b: string) => number;
+// Re-export CollationFunction for backward compatibility
+export type { CollationFunction };
 
 // Map to store registered collations
 const collations = new Map<string, CollationFunction>();
@@ -350,9 +350,11 @@ export function compareWithOrderBy(
 ): number {
 	// Convert to optimized flags and use fast path
 	const directionFlag = direction === 'desc' ? SortDirection.DESC : SortDirection.ASC;
-	const nullsFlag = nullsOrdering === 'first' ? NullsOrdering.FIRST :
-	                  nullsOrdering === 'last' ? NullsOrdering.LAST :
-	                  NullsOrdering.DEFAULT;
+	const nullsFlag = nullsOrdering === 'first'
+		? NullsOrdering.FIRST
+		: nullsOrdering === 'last'
+			? NullsOrdering.LAST
+			: NullsOrdering.DEFAULT;
 	const collationFunc = collationName === 'BINARY' ? BINARY_COLLATION : resolveCollation(collationName);
 
 	return compareWithOrderByFast(a, b, directionFlag, nullsFlag, collationFunc);
@@ -391,9 +393,11 @@ export function createOrderByComparatorFast(
 	collationFunc: CollationFunction = BINARY_COLLATION
 ): (a: SqlValue, b: SqlValue) => number {
 	const directionFlag = direction === 'desc' ? SortDirection.DESC : SortDirection.ASC;
-	const nullsFlag = nullsOrdering === 'first' ? NullsOrdering.FIRST :
-	                  nullsOrdering === 'last' ? NullsOrdering.LAST :
-	                  NullsOrdering.DEFAULT;
+	const nullsFlag = nullsOrdering === 'first'
+		? NullsOrdering.FIRST
+		: nullsOrdering === 'last'
+			? NullsOrdering.LAST
+			: NullsOrdering.DEFAULT;
 
 	// Return a closure that captures the pre-resolved values
 	return (a: SqlValue, b: SqlValue): number => {
@@ -432,6 +436,75 @@ export function compareRows(a: Row, b: Row): number {
 	return 0;
 }
 
-// TODO: The main remaining task for comparison is implementing SQLite's
-// type affinity rules (which affect how values are treated BEFORE comparison)
-// and handling different TEXT collations.
+
+/**
+ * Type-aware comparison function that uses logical type information.
+ * This eliminates runtime type detection and uses type-specific comparison logic.
+ *
+ * @param a First value
+ * @param b Second value
+ * @param typeA Logical type of first value
+ * @param typeB Logical type of second value (should match typeA for strict typing)
+ * @param collation Optional collation function for TEXT types
+ * @returns -1 if a < b, 0 if a === b, 1 if a > b
+ * @throws QuereusError if types don't match (strict typing)
+ */
+export function compareTypedValues(
+	a: SqlValue,
+	b: SqlValue,
+	typeA: LogicalType,
+	typeB: LogicalType,
+	collation?: CollationFunction
+): number {
+	// NULL handling
+	if (a === null && b === null) return 0;
+	if (a === null) return -1;
+	if (b === null) return 1;
+
+	// Type mismatch error (strict typing)
+	if (typeA !== typeB) {
+		throw new QuereusError(
+			`Type mismatch in comparison: ${typeA.name} vs ${typeB.name}`,
+			StatusCode.MISMATCH
+		);
+	}
+
+	// Use type-specific comparison if available
+	if (typeA.compare) {
+		return typeA.compare(a, b, collation);
+	}
+
+	// Fallback to default comparison based on physical type
+	// This shouldn't happen for built-in types, but provides safety for custom types
+	return compareSqlValuesFast(a, b, collation ?? BINARY_COLLATION);
+}
+
+/**
+ * Create a type-aware comparator function for a specific logical type.
+ * This is optimized for use in indexes and sorts where the type is known at creation time.
+ *
+ * @param type The logical type
+ * @param collation Optional collation function for TEXT types
+ * @returns A comparator function
+ */
+export function createTypedComparator(
+	type: LogicalType,
+	collation?: CollationFunction
+): (a: SqlValue, b: SqlValue) => number {
+	// Pre-resolve the comparison function
+	const compareFunc = type.compare;
+
+	if (compareFunc) {
+		// Type has custom comparison
+		return (a: SqlValue, b: SqlValue) => {
+			if (a === null && b === null) return 0;
+			if (a === null) return -1;
+			if (b === null) return 1;
+			return compareFunc(a, b, collation);
+		};
+	}
+
+	// Fallback to default comparison
+	const collationFunc = collation ?? BINARY_COLLATION;
+	return (a: SqlValue, b: SqlValue) => compareSqlValuesFast(a, b, collationFunc);
+}

package/src/util/plugin-loader.ts

@@ -80,6 +80,10 @@ export async function dynamicLoadModule(
 			log('  Registered %d collation(s): %s', registrations.collations.length,
 				registrations.collations.map(c => c.name).join(', '));
 		}
+		if (registrations.types?.length) {
+			log('  Registered %d type(s): %s', registrations.types.length,
+				registrations.types.map(t => t.name).join(', '));
+		}
 
 		// Try to extract manifest from package.json
 		let manifest: PluginManifest | undefined;
@@ -141,6 +145,17 @@ async function registerPluginItems(db: Database, registrations: PluginRegistrati
 			}
 		}
 	}
+
+	// Register types
+	if (registrations.types) {
+		for (const type of registrations.types) {
+			try {
+				db.registerType(type.name, type.definition);
+			} catch (error) {
+				quereusError(`Failed to register type '${type.name}': ${error instanceof Error ? error.message : String(error)}`);
+			}
+		}
+	}
 }
 
 /**
@@ -255,6 +270,10 @@ export async function loadPlugin(
             log('  Registered %d collation(s): %s', registrations.collations.length,
                 registrations.collations.map(c => c.name).join(', '));
         }
+        if (registrations.types?.length) {
+            log('  Registered %d type(s): %s', registrations.types.length,
+                registrations.types.map(t => t.name).join(', '));
+        }
 
         // Try to extract manifest from package.json
         let manifest: PluginManifest | undefined;

package/src/vtab/manifest.ts

@@ -2,6 +2,10 @@
 import type { SqlValue } from '../common/types.js';
 import type { FunctionSchema } from '../schema/function.js';
 import type { CollationFunction } from '../util/comparison.js';
+import type { TypePluginInfo } from '../types/plugin-interface.js';
+
+// Re-export TypePluginInfo so it can be imported from this module
+export type { TypePluginInfo };
 
 /**
  * Configuration setting definition for a plugin
@@ -46,6 +50,7 @@ export interface PluginRegistrations {
 	vtables?: VTablePluginInfo[];
 	functions?: FunctionPluginInfo[];
 	collations?: CollationPluginInfo[];
+	types?: TypePluginInfo[];
 }
 
 /**
@@ -59,12 +64,13 @@ export interface PluginManifest {
 	pragmaPrefix?: string;          // default = name, used for PRAGMA commands
 	settings?: PluginSetting[];     // configuration options
 	capabilities?: string[];        // e.g. ['scan', 'index', 'write']
-	
+
 	// Plugin type indicators (for UI display)
 	provides?: {
 		vtables?: string[];         // names of vtable modules provided
 		functions?: string[];       // names of functions provided
 		collations?: string[];      // names of collations provided
+		types?: string[];           // names of types provided
 	};
 }