@quereus/quereus 0.7.3 → 0.7.4

package/src/common/datatype.ts

@@ -1,85 +0,0 @@
-import type { Expression } from "../parser/ast.js";
-import type { DeepReadonly } from "./types.js";
-import type { LogicalType } from "../types/logical-type.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 logical type defining semantics and behavior */
-	logicalType: LogicalType;
-	/** 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;
-	/** 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

@@ -1,189 +0,0 @@
-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 Error & { cause?: Error }).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/json-types.ts

@@ -1,16 +0,0 @@
-/* eslint-disable @typescript-eslint/no-explicit-any */
-/**
- * Represents a JSON-compatible value structure
- *
- * This type represents the valid JSON value space that can result from
- * JSON.parse() or be passed to JSON.stringify(). It excludes JavaScript
- * values that cannot be represented in JSON (undefined, functions, symbols, etc.)
- */
-export type JSONValue =
-	| string
-	| number
-	| boolean
-	| null
-	| JSONValue[]
-	| { [key: string]: JSONValue };
-/* eslint-enable @typescript-eslint/no-explicit-any */

package/src/common/logger.ts

@@ -1,97 +0,0 @@
-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}`);
-}
-
-/**
- * Enable Quereus debug logging programmatically.
- *
- * This is particularly useful in environments like React Native where
- * environment variables are not available at runtime.
- *
- * @param pattern - Debug pattern to enable (default: 'quereus:*')
- *   Examples:
- *   - 'quereus:*' - all Quereus logs
- *   - 'quereus:vtab:*' - virtual table operations
- *   - 'quereus:vtab:memory' - memory table operations only
- *   - 'quereus:planner' - query planner logs
- *   - 'quereus:runtime' - VDBE execution (very verbose)
- *   - 'quereus:*,-quereus:runtime' - all except verbose runtime
- * @param logFn - Optional custom log function. Defaults to console.log.
- *   Useful in environments where console.debug may be filtered.
- *
- * @example
- * ```typescript
- * import { enableLogging } from '@quereus/quereus';
- *
- * // Enable all Quereus logs
- * enableLogging();
- *
- * // Enable only memory table logs
- * enableLogging('quereus:vtab:memory');
- *
- * // Enable all logs with custom output (e.g., React Native)
- * enableLogging('quereus:*', console.log.bind(console));
- * ```
- */
-export function enableLogging(
-	pattern: string = `${BASE_NAMESPACE}:*`,
-	logFn?: (...args: unknown[]) => void
-): void {
-	if (logFn) {
-		debug.log = logFn;
-	}
-	debug.enable(pattern);
-}
-
-/**
- * Disable all Quereus debug logging.
- *
- * @example
- * ```typescript
- * import { disableLogging } from '@quereus/quereus';
- *
- * disableLogging();
- * ```
- */
-export function disableLogging(): void {
-	debug.disable();
-}
-
-/**
- * Check if logging is enabled for a specific namespace.
- *
- * @param namespace - The namespace to check (without 'quereus:' prefix)
- * @returns true if logging is enabled for this namespace
- *
- * @example
- * ```typescript
- * import { isLoggingEnabled } from '@quereus/quereus';
- *
- * if (isLoggingEnabled('vtab:memory')) {
- *   // Perform expensive debug operations
- * }
- * ```
- */
-export function isLoggingEnabled(namespace: string): boolean {
-	return debug.enabled(`${BASE_NAMESPACE}:${namespace}`);
-}

package/src/common/type-inference.ts

@@ -1,39 +0,0 @@
-import { SqlDataType, type SqlValue } from "./types.js";
-import type { LogicalType } from "../types/logical-type.js";
-import { NULL_TYPE, INTEGER_TYPE, REAL_TYPE, TEXT_TYPE, BLOB_TYPE, BOOLEAN_TYPE } from "../types/builtin-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;
-}
-
-/**
- * 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') {
-		// 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;
-	if (typeof v === 'string') return TEXT_TYPE;
-	if (v instanceof Uint8Array) return BLOB_TYPE;
-	return BLOB_TYPE;
-}

package/src/common/types.ts

@@ -1,151 +0,0 @@
-import type { RuntimeContext } from '../runtime/types.js';
-
-export type MaybePromise<T> = T | Promise<T>;
-
-export type DeepReadonly<T> = { readonly [P in keyof T]: DeepReadonly<T[P]> };
-
-/**
- * Represents the primitive scalar types Quereus can handle internally in this implementation.
- * These are the values that can be stored in Quereus columns and passed as parameters.
- */
-export type SqlValue = string | number | bigint | boolean | Uint8Array | null;
-
-/**
- * Represents a row of data, which is an array of SqlValue.
- */
-export type Row = SqlValue[];
-
-/**
- * Represents a value that can be expected as an input in the runtime environment.
- * This type can be a scalar value, or an async iterable of rows (cursor).
- */
-export type RuntimeValue = SqlValue | Row | AsyncIterable<Row> | ((ctx: RuntimeContext) => OutputValue)
-
-/** Represents a value that can be output from an instruction or program. */
-export type OutputValue = MaybePromise<RuntimeValue>;
-
-export type SqlParameters = Record<string, SqlValue> | SqlValue[];
-
-/**
- * Standard status/error codes that significantly match SQLite.
- * Used for error handling and determining operation results.
- */
-export enum StatusCode {
-	OK = 0,
-	ERROR = 1,
-	INTERNAL = 2,
-	PERM = 3,
-	ABORT = 4,
-	BUSY = 5,
-	LOCKED = 6,
-	NOMEM = 7,
-	READONLY = 8,
-	INTERRUPT = 9,
-	IOERR = 10,
-	CORRUPT = 11,
-	NOTFOUND = 12,
-	FULL = 13,
-	CANTOPEN = 14,
-	PROTOCOL = 15,
-	EMPTY = 16,
-	SCHEMA = 17,
-	TOOBIG = 18,
-	CONSTRAINT = 19,
-	MISMATCH = 20,
-	MISUSE = 21,
-	NOLFS = 22,
-	AUTH = 23,
-	FORMAT = 24,
-	RANGE = 25,
-	NOTADB = 26,
-	NOTICE = 27,
-	WARNING = 28,
-	SYNTAX = 29,
-	UNSUPPORTED = 30,
-}
-
-/**
- * Fundamental SQLite compatible datatypes/affinity types.
- * These determine how values are stored and compared within the database.
- */
-export enum SqlDataType {
-	NULL = 0,
-	INTEGER = 1,
-	REAL = 2,
-	TEXT = 3,
-	BLOB = 4,
-	NUMERIC = 6, // For DECIMAL, NUMERIC with precision/scale
-	BOOLEAN = 7, // For explicit BOOLEAN columns (future, not standard SQLite)
-}
-
-export type CompareFn = (a: SqlValue, b: SqlValue) => number;
-
-export interface DatabaseInfo {
-	path: string | ':memory:';
-	isOpen: boolean;
-	isReadonly: boolean;
-	inTransaction: boolean;
-	name: string;
-}
-
-/**
- * Shared configuration object that can be used by multiple databases
- */
-export interface DatabaseConfig {
-	/**
-	 * Open the database in read-only mode
-	 * @default false
-	 */
-	readonly?: boolean;
-
-	/**
-	 * Register default functions
-	 * @default true
-	 */
-	registerDefaultFunctions?: boolean;
-
-	/**
-	 * Maximum number of retries when opening the database
-	 * @default 3
-	 */
-	maxRetries?: number;
-
-	/**
-	 * Enable WAL mode (Write-Ahead Logging)
-	 * @default true for file databases, false for in-memory
-	 */
-	enableWAL?: boolean;
-
-	/**
-	 * Synchronous setting ('OFF' | 'NORMAL' | 'FULL' | 'EXTRA')
-	 * @default 'NORMAL' with WAL, 'FULL' without WAL
-	 */
-	synchronous?: 'OFF' | 'NORMAL' | 'FULL' | 'EXTRA';
-
-	/**
-	 * Journal mode ('DELETE' | 'TRUNCATE' | 'PERSIST' | 'MEMORY' | 'WAL' | 'OFF')
-	 * @default 'WAL' if enableWAL is true, 'DELETE' otherwise
-	 */
-	journalMode?: 'DELETE' | 'TRUNCATE' | 'PERSIST' | 'MEMORY' | 'WAL' | 'OFF';
-
-	/**
-	 * Cache size in pages (negative value = KB)
-	 * @default -2048 (2MB)
-	 */
-	cacheSize?: number;
-
-	/**
-	 * Page size in bytes (must be power of 2, 512-65536)
-	 * @default 4096
-	 */
-	pageSize?: number;
-
-	/**
-	 * Foreign key constraint enforcement
-	 * @default true
-	 */
-	foreignKeys?: boolean;
-}
-export type RowOp = 'insert' | 'update' | 'delete';
-
-export type { JSONValue } from './json-types.js';