@quereus/quereus 0.1.0

package/dist/src/vtab/table.d.ts

@@ -0,0 +1,114 @@
+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 declare abstract class VirtualTable {
+    readonly module: VirtualTableModule<any, any>;
+    readonly db: Database;
+    readonly tableName: string;
+    readonly schemaName: string;
+    errorMessage?: string;
+    tableSchema?: TableSchema;
+    constructor(db: Database, module: VirtualTableModule<any, any>, schemaName: string, tableName: string);
+    /**
+     * Sets an error message for the VTable
+     * @param message The error message string
+     */
+    protected setErrorMessage(message: string | undefined): void;
+    /**
+     * 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>;
+}
+//# sourceMappingURL=table.d.ts.map

package/dist/src/vtab/table.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"table.d.ts","sourceRoot":"","sources":["../../../src/vtab/table.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACxE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,KAAK,EAAE,YAAY,EAAE,GAAG,EAAE,MAAM,oBAAoB,CAAC;AAC5D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAC;AAE9D;;;GAGG;AACH,8BAAsB,YAAY;IACjC,SAAgB,MAAM,EAAE,kBAAkB,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;IACrD,SAAgB,EAAE,EAAE,QAAQ,CAAC;IAC7B,SAAgB,SAAS,EAAE,MAAM,CAAC;IAClC,SAAgB,UAAU,EAAE,MAAM,CAAC;IAC5B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,WAAW,CAAC;gBAErB,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,kBAAkB,CAAC,GAAG,EAAE,GAAG,CAAC,EAAE,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM;IAOrG;;;OAGG;IACH,SAAS,CAAC,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI;IAI5D;;;;OAIG;IACH,QAAQ,CAAC,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;IAErC;;;;;;OAMG;IACH,MAAM,CAAC,CAAC,UAAU,EAAE,UAAU,GAAG,aAAa,CAAC,GAAG,CAAC;IAEnD;;;;;;;OAOG;IACH,QAAQ,CAAC,OAAO,CACf,SAAS,EAAE,KAAK,EAChB,MAAM,EAAE,GAAG,GAAG,SAAS,EACvB,YAAY,CAAC,EAAE,GAAG,GAChB,OAAO,CAAC,GAAG,GAAG,SAAS,CAAC;IAE3B;;;;OAIG;IACH,gBAAgB,CAAC,IAAI,YAAY,CAAC,sBAAsB,CAAC;IAEzD;;;;OAIG;IACH,aAAa,CAAC,IAAI,sBAAsB,GAAG,SAAS;IAEpD;;OAEG;IACH,MAAM,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC;IAExB;;OAEG;IACH,KAAK,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC;IAEvB;;OAEG;IACH,OAAO,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC;IAEzB;;OAEG;IACH,SAAS,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC;IAE3B;;;OAGG;IACH,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAExC;;;OAGG;IACH,UAAU,CAAC,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAElD;;;OAGG;IACH,QAAQ,CAAC,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAEhD;;;OAGG;IACH,WAAW,CAAC,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAEnD;;;;OAIG;IACH,YAAY,CAAC,CAAC,UAAU,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;IAE1D;;;OAGG;IACH,YAAY,CAAC,CAAC,SAAS,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAEpD;;;OAGG;IACH,UAAU,CAAC,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAC7C"}

package/dist/src/vtab/table.js

@@ -0,0 +1,26 @@
+/**
+ * Base class representing a virtual table instance.
+ * Module implementations should subclass this to provide specific table behavior.
+ */
+export class VirtualTable {
+    module;
+    db;
+    tableName;
+    schemaName;
+    errorMessage;
+    tableSchema;
+    constructor(db, module, schemaName, tableName) {
+        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
+     */
+    setErrorMessage(message) {
+        this.errorMessage = message;
+    }
+}
+//# sourceMappingURL=table.js.map

package/dist/src/vtab/table.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"table.js","sourceRoot":"","sources":["../../../src/vtab/table.ts"],"names":[],"mappings":"AASA;;;GAGG;AACH,MAAM,OAAgB,YAAY;IACjB,MAAM,CAA+B;IACrC,EAAE,CAAW;IACb,SAAS,CAAS;IAClB,UAAU,CAAS;IAC5B,YAAY,CAAU;IACtB,WAAW,CAAe;IAEjC,YAAY,EAAY,EAAE,MAAoC,EAAE,UAAkB,EAAE,SAAiB;QACpG,IAAI,CAAC,EAAE,GAAG,EAAE,CAAC;QACb,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAC7B,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;IAC5B,CAAC;IAED;;;OAGG;IACO,eAAe,CAAC,OAA2B;QACpD,IAAI,CAAC,YAAY,GAAG,OAAO,CAAC;IAC7B,CAAC;CA4GD"}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@quereus/quereus",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Federated SQL query processor inspired by SQLite",
+  "main": "dist/src/index.js",
+  "types": "./dist/src/index.d.ts",
+  "files": [
+    "src",
+    "dist",
+    "!dist/test",
+    "!**/*.tsbuildinfo"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "import": "./dist/src/index.js"
+    }
+  },
+  "scripts": {
+    "clean": "rm -rf dist",
+    "doc": "npx typedoc -out doc src",
+    "build": "tsc",
+    "lint": "eslint src/**/*.ts test/**/*.ts",
+    "test:all": "cd ../.. && node --import ./packages/quereus/register.mjs node_modules/mocha/bin/mocha.js \"packages/quereus/test/**/*.spec.ts\" --colors",
+    "test": "cd ../.. && node --import ./packages/quereus/register.mjs node_modules/mocha/bin/mocha.js \"packages/quereus/test/**/*.spec.ts\" --colors --bail",
+    "test:single": "cd ../.. && node --import ./packages/quereus/register.mjs node_modules/mocha/bin/mocha.js --bail",
+    "test:plans": "cd ../.. && node --import ./packages/quereus/register.mjs node_modules/mocha/bin/mocha.js \"packages/quereus/test/plan/**/*.spec.ts\" --colors",
+    "prepublishOnly": "npm run build",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@types/chai": "^5.2.2",
+    "@types/debug": "^4.1.12",
+    "@types/node": "^22.15.29",
+    "@types/mocha": "^10.0.10",
+    "@typescript-eslint/eslint-plugin": "^8.33.0",
+    "@typescript-eslint/parser": "^8.33.0",
+    "chai": "^5.2.0",
+    "eslint": "^9.28.0",
+    "eslint-plugin-import": "^2.31.0",
+    "fast-check": "^4.1.1",
+    "mocha": "^11.5.0",
+    "ts-node": "^10.9.2",
+    "tsc-alias": "^1.8.16",
+    "typedoc": "^0.28.5",
+    "typescript": "^5.8.3",
+    "typescript-eslint": "^8.34.1"
+  },
+  "dependencies": {
+    "debug": "^4.4.1",
+    "fast-json-patch": "^3.1.1",
+    "inheritree": "^0.3.2",
+    "temporal-polyfill": "^0.3.0",
+    "uint8arrays": "^5.1.0"
+  },
+  "ts-node": {
+    "esm": true,
+    "experimentalSpecifierResolution": "node"
+  }
+}

package/src/common/constants.ts

@@ -0,0 +1,60 @@
+// Constants for function flags (matching C API where sensible)
+export enum FunctionFlags {
+	UTF8 = 1,
+	// UTF16LE = 2, // Decide if UTF16 support is needed internally
+	// UTF16BE = 3,
+	// UTF16 = 4,
+	DETERMINISTIC = 0x000000800,
+	DIRECTONLY = 0x000080000,
+	INNOCUOUS = 0x000200000,
+	// Add others if needed (SUBTYPE, etc.)
+}
+
+// Constants for VTable configuration
+export enum VTabConfig {
+	CONSTRAINT_SUPPORT = 1,
+	INNOCUOUS = 2,
+	DIRECTONLY = 3,
+	USES_ALL_SCHEMAS = 4,
+}
+
+// Constants for VTable constraint operators
+export enum IndexConstraintOp {
+	EQ = 2,
+	GT = 4,
+	LE = 8,
+	LT = 16,
+	GE = 32,
+	MATCH = 64,
+	LIKE = 65, // Requires a LIKE implementation or delegation
+	GLOB = 66, // Requires a GLOB implementation or delegation
+	REGEXP = 67, // Requires a REGEXP implementation or delegation
+	NE = 68,
+	ISNOT = 69,
+	ISNOTNULL = 70,
+	ISNULL = 71,
+	IS = 72,
+	LIMIT = 73,
+	OFFSET = 74,
+	IN = 75,
+	FUNCTION = 150, // Base for function-based constraints
+}
+
+/**
+ * Defines how to resolve a constraint conflict.
+ * These correspond to SQLite's ON CONFLICT clauses.
+ */
+export enum ConflictResolution {
+	ROLLBACK = 1,
+	ABORT = 2,    // Default
+	FAIL = 3,
+	IGNORE = 4,
+	REPLACE = 5,
+}
+
+// Constants for Changeset operations (matching C API)
+export enum ChangesetOperation {
+	DELETE = 9,
+	INSERT = 18,
+	UPDATE = 23,
+}

package/src/common/datatype.ts

@@ -0,0 +1,86 @@
+import type { Expression } from "../parser/ast.js";
+import type { DeepReadonly, SqlDataType } from "./types.js";
+
+export type TypeClass = 'scalar' | 'relation' | 'list' | 'void';
+
+export type BaseType = DeepReadonly<{
+	typeClass: TypeClass;
+}>
+
+/**
+ * Type information for scalar values.
+ * This is used to determine the type of a scalar value, e.g., for a column reference or a literal.
+ */
+export type ScalarType = DeepReadonly<BaseType & {
+	typeClass: 'scalar';
+	/** The type affinity of the scalar value. */
+	affinity: SqlDataType;
+	/** The optional collation name of the scalar value. */
+	collationName?: string;
+	/** If nullable, null values are allowed and may be encountered in inference contexts too. */
+	nullable: boolean;
+	/** Indicates that it is inferred const, computed, or otherwise immutable.  Missing assumes false. */
+	isReadOnly?: boolean;
+	/** For literals or inferred constants, we can know the specific type */
+	datatype?: SqlDataType;
+	/** TODO: Based on integrity constraints, in some cases we can know of further restrictions on the set of values, which may enabled certain optimizations. */
+	//constraints?: ReadonlyArray<ColumnConstraint>;
+}>
+
+export type ColumnDef = {
+	name: string;
+	type: ScalarType;
+	/** The optional default value for the column. */
+	default?: Expression;
+	/** If true, the column is generated, not stored.  Absent = false. */
+	generated?: boolean;
+}
+
+export type ColRef = {
+	index: number;
+	/** If true, the column is sorted in descending order.  Absent = false. */
+	desc?: boolean;
+}
+/**
+ * Type information for relations.
+ * This is used to determine the type of a relation, e.g., for a table or a subquery.
+ * Foreign keys and externally referencing constraints are not part of the relation type as they are essentially database level.
+ */
+export type RelationType = DeepReadonly<BaseType & {
+	typeClass: 'relation';
+	isReadOnly: boolean;
+	/**
+	 * If true, this relation is guaranteed to be a set (no duplicate rows).
+	 * If false, this relation could be a bag (duplicate rows possible).
+	 * This affects how certain operations (like sorting) handle the data.
+	 */
+	isSet: boolean;
+	columns: ColumnDef[];
+	/** The unique keys of the relation (the primary key is arbitrarily the first one).
+	 * Note that these may or may not be supported by indexes (normally they are), but by definition are unique.
+	 * An empty key means the relation can have exactly 0 or 1 rows (TableDum and TableDee respectively).
+	 */
+	keys: ColRef[][];
+	/** The row constraints of the relation - limited to the relation itself. */
+	rowConstraints: { name?: string, expr: Expression }[];
+}>
+
+export type ListType = DeepReadonly<BaseType & {
+	typeClass: 'list';
+}>
+
+export type VoidType = DeepReadonly<BaseType & {
+	typeClass: 'void';
+}>
+
+export function isRelationType(type: BaseType): type is RelationType {
+	return type.typeClass === 'relation';
+}
+
+export function isScalarType(type: BaseType): type is ScalarType {
+	return type.typeClass === 'scalar';
+}
+
+export function isListType(type: BaseType): type is ListType {
+	return type.typeClass === 'list';
+}

package/src/common/errors.ts

@@ -0,0 +1,189 @@
+import { StatusCode } from './types.js';
+import type { Token } from '../parser/lexer.js';
+
+/**
+ * Base class for Quereus specific errors
+ * Provides location information and status code support
+ */
+export class QuereusError extends Error {
+	public code: number;
+	public cause?: Error;
+	public line?: number;
+	public column?: number;
+
+	constructor(message: string, code: number = StatusCode.ERROR, cause?: Error, line?: number, column?: number) {
+		super(message);
+		this.code = code;
+		this.name = 'QuereusError';
+		this.cause = cause;
+		this.line = line;
+		this.column = column;
+
+		// Enhance message with location if available
+		if (line !== undefined && column !== undefined) {
+			this.message = `${message} (at line ${line}, column ${column})`;
+		}
+
+		// Maintain stack trace in V8
+		if (Error.captureStackTrace) {
+			Error.captureStackTrace(this, QuereusError);
+		}
+	}
+}
+
+/**
+ * Parser-specific error that includes token information
+ * Used during SQL parsing to provide precise error locations
+ */
+export class ParseError extends QuereusError {
+	public token: Token;
+
+	constructor(message: string, token: Token) {
+		super(message, StatusCode.ERROR, undefined, token.startLine, token.startColumn);
+		this.token = token;
+		this.name = 'ParseError';
+	}
+}
+
+/**
+ * Error thrown when a database constraint is violated
+ */
+export class ConstraintError extends QuereusError {
+	constructor(message: string, code: number = StatusCode.CONSTRAINT) {
+		super(message, code);
+		this.name = 'ConstraintError';
+	}
+}
+
+/**
+ * Error thrown for SQL syntax issues
+ */
+export class SyntaxError extends QuereusError {
+	constructor(message: string = "SQL syntax error") {
+		super(message, StatusCode.ERROR);
+		this.name = 'SyntaxError';
+		Object.setPrototypeOf(this, SyntaxError.prototype);
+	}
+}
+
+/**
+ * Error thrown when the API is used incorrectly
+ */
+export class MisuseError extends QuereusError {
+	constructor(message: string = "API misuse") {
+		super(message, StatusCode.MISUSE);
+		this.name = 'MisuseError';
+		Object.setPrototypeOf(this, MisuseError.prototype);
+	}
+}
+
+/**
+ * Helper function to throw a QuereusError with optional location information from AST nodes
+ * @param message Error message
+ * @param code Status code (defaults to ERROR)
+ * @param cause Optional underlying error
+ * @param astNode Optional AST node or object with location information
+ * @returns Never (always throws)
+ */
+export function quereusError(
+	message: string,
+	code: StatusCode = StatusCode.ERROR,
+	cause?: Error,
+	astNode?: { loc?: { start: { line: number; column: number }, end?: { line: number; column: number } } }
+): never {
+	throw new QuereusError(
+		message,
+		code,
+		cause,
+		astNode?.loc?.start.line,
+		astNode?.loc?.start.column
+	);
+}
+
+/**
+ * Information about an error in the error chain
+ */
+export interface ErrorInfo {
+	message: string;
+	code?: number;
+	line?: number;
+	column?: number;
+	name: string;
+	stack?: string;
+}
+
+/**
+ * Recursively unwraps a QuereusError (or any Error) and its causes
+ * @param error The error to unwrap
+ * @returns Array of ErrorInfo objects, with the root error first
+ */
+export function unwrapError(error: Error): ErrorInfo[] {
+	const errorChain: ErrorInfo[] = [];
+	let currentError: Error | undefined = error;
+
+	while (currentError) {
+		const errorInfo: ErrorInfo = {
+			message: currentError.message,
+			name: currentError.name,
+			stack: currentError.stack,
+		};
+
+		// Add QuereusError-specific fields if available
+		if (currentError instanceof QuereusError) {
+			errorInfo.code = currentError.code;
+			errorInfo.line = currentError.line;
+			errorInfo.column = currentError.column;
+		}
+
+		errorChain.push(errorInfo);
+
+		// Move to the next error in the chain
+		currentError = (currentError as any).cause;
+	}
+
+	return errorChain;
+}
+
+/**
+ * Formats an error chain for display
+ * @param errorChain Array of ErrorInfo objects
+ * @param includeStack Whether to include stack traces
+ * @returns Formatted error message
+ */
+export function formatErrorChain(errorChain: ErrorInfo[], includeStack: boolean = false): string {
+	if (errorChain.length === 0) {
+		return 'Unknown error';
+	}
+
+	const lines: string[] = [];
+
+	errorChain.forEach((errorInfo, index) => {
+		const prefix = index === 0 ? 'Error' : `Caused by`;
+		let line = `${prefix}: ${errorInfo.message}`;
+
+		if (errorInfo.line !== undefined && errorInfo.column !== undefined) {
+			line += ` (at line ${errorInfo.line}, column ${errorInfo.column})`;
+		}
+
+		lines.push(line);
+
+		if (includeStack && errorInfo.stack) {
+			lines.push(errorInfo.stack);
+		}
+	});
+
+	return lines.join('\n');
+}
+
+/**
+ * Gets the primary error info (the first error in the chain)
+ * @param error The error to analyze
+ * @returns ErrorInfo for the primary error
+ */
+export function getPrimaryError(error: Error): ErrorInfo {
+	const chain = unwrapError(error);
+	return chain[0] || {
+		message: 'Unknown error',
+		name: 'Error',
+	};
+}

package/src/common/logger.ts

@@ -0,0 +1,23 @@
+import debug from 'debug';
+
+// Base namespace for the project
+const BASE_NAMESPACE = 'quereus';
+
+/**
+ * Creates a namespaced debug logger instance.
+ *
+ * Example: createLogger('compiler') -> returns a debugger for 'quereus:compiler'
+ * Example: createLogger('vtab:memory') -> returns a debugger for 'quereus:vtab:memory'
+ *
+ * Usage:
+ * const log = createLogger('compiler');
+ * log('Compiling statement: %s', sql);
+ * const errorLog = log.extend('error'); // Creates 'quereus:compiler:error'
+ * errorLog('Compilation failed: %O', error);
+ *
+ * @param subNamespace The specific subsystem namespace (e.g., 'parser', 'vdbe:runtime', 'vtab:memory')
+ * @returns A debug instance.
+ */
+export function createLogger(subNamespace: string): debug.Debugger {
+  return debug(`${BASE_NAMESPACE}:${subNamespace}`);
+}

package/src/common/type-inference.ts

@@ -0,0 +1,40 @@
+import { SqlDataType, type SqlValue } from "./types.js";
+
+export function getLiteralSqlType(v: SqlValue): SqlDataType {
+	if (v === null) return SqlDataType.NULL;
+	if (typeof v === 'number') {
+		if (Number.isInteger(v)) return SqlDataType.INTEGER;
+		return SqlDataType.REAL;
+	}
+	if (typeof v === 'bigint') return SqlDataType.INTEGER;
+	if (typeof v === 'string') return SqlDataType.TEXT;
+	if (v instanceof Uint8Array) return SqlDataType.BLOB;
+	return SqlDataType.BLOB;
+}
+
+/**
+ * Determines the column affinity in a similar way to SQLite rules.
+ * @see https://www.sqlite.org/datatype3.html#determination_of_column_affinity
+ *
+ * @param typeName The declared type name (case-insensitive)
+ * @returns The determined SqlDataType affinity
+ */
+export function getAffinity(typeName: string | undefined): SqlDataType {
+	if (!typeName) {
+		return SqlDataType.BLOB;
+	}
+	const typeUpper = typeName.toUpperCase();
+	if (typeUpper.includes('INT')) {
+		return SqlDataType.INTEGER;
+	}
+	if (typeUpper.includes('CHAR') || typeUpper.includes('CLOB') || typeUpper.includes('TEXT')) {
+		return SqlDataType.TEXT;
+	}
+	if (typeUpper.includes('BLOB')) {
+		return SqlDataType.BLOB;
+	}
+	if (typeUpper.includes('REAL') || typeUpper.includes('FLOA') || typeUpper.includes('DOUB')) {
+		return SqlDataType.REAL;
+	}
+	return SqlDataType.NUMERIC; // Default catch-all
+}