@quereus/quereus 0.1.0

package/src/common/types.ts

@@ -0,0 +1,148 @@
+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;
+}

package/src/core/database-options.ts

@@ -0,0 +1,258 @@
+/**
+ * Centralized database options management with event-driven updates
+ */
+
+import { createLogger } from '../common/logger.js';
+import { QuereusError } from '../common/errors.js';
+import { StatusCode } from '../common/types.js';
+import type { SqlValue } from '../common/types.js';
+
+const log = createLogger('core:options');
+
+export type OptionValue = boolean | string | number | Record<string, SqlValue>;
+export type OptionType = 'boolean' | 'string' | 'number' | 'object';
+
+export interface OptionDefinition {
+	type: OptionType;
+	defaultValue: OptionValue;
+	aliases?: string[];
+	description?: string;
+	onChange?: OptionChangeListener;
+}
+
+export interface OptionChangeEvent {
+	key: string;
+	oldValue: OptionValue;
+	newValue: OptionValue;
+}
+
+export type OptionChangeListener = (event: OptionChangeEvent) => void;
+
+/**
+ * Centralized options manager with event notifications and registration
+ */
+export class DatabaseOptionsManager {
+	private options = new Map<string, OptionValue>();
+	private definitions = new Map<string, OptionDefinition>();
+	private aliases = new Map<string, string>(); // alias -> canonical key
+
+	/**
+	 * Register an option with its definition
+	 */
+	registerOption(key: string, definition: OptionDefinition): void {
+		if (this.definitions.has(key)) {
+			throw new QuereusError(`Option ${key} is already registered`, StatusCode.INTERNAL);
+		}
+
+		this.definitions.set(key, definition);
+		this.options.set(key, definition.defaultValue);
+
+		// Register aliases
+		if (definition.aliases) {
+			for (const alias of definition.aliases) {
+				if (this.aliases.has(alias.toLowerCase())) {
+					throw new QuereusError(`Option alias ${alias} is already registered`, StatusCode.INTERNAL);
+				}
+				this.aliases.set(alias.toLowerCase(), key);
+			}
+		}
+
+		log('Registered option %s (type: %s, default: %j)', key, definition.type, definition.defaultValue);
+	}
+
+	/**
+	 * Set an option value and notify listeners
+	 */
+	setOption(key: string, value: any): void {
+		const canonicalKey = this.resolveKey(key);
+		if (!canonicalKey) {
+			throw new QuereusError(`Unknown option: ${key}`, StatusCode.ERROR);
+		}
+
+		const definition = this.definitions.get(canonicalKey)!;
+		const convertedValue = this.convertValue(value, definition, key);
+		const oldValue = this.options.get(canonicalKey)!;
+
+		if (this.valuesEqual(oldValue, convertedValue)) {
+			return; // No change
+		}
+
+		this.options.set(canonicalKey, convertedValue);
+		log('Option %s changed: %j → %j', canonicalKey, oldValue, convertedValue);
+
+		// Notify listener if registered
+		this.notifyListener(canonicalKey, oldValue, convertedValue);
+	}
+
+	/**
+	 * Get an option value
+	 */
+	getOption(key: string): OptionValue {
+		const canonicalKey = this.resolveKey(key);
+		if (!canonicalKey) {
+			throw new QuereusError(`Unknown option: ${key}`, StatusCode.ERROR);
+		}
+
+		return this.options.get(canonicalKey)!;
+	}
+
+	/**
+	 * Get a boolean option value with type safety
+	 */
+	getBooleanOption(key: string): boolean {
+		const value = this.getOption(key);
+		if (typeof value !== 'boolean') {
+			throw new QuereusError(`Option ${key} is not a boolean (got ${typeof value})`, StatusCode.INTERNAL);
+		}
+		return value;
+	}
+
+	/**
+	 * Get a string option value with type safety
+	 */
+	getStringOption(key: string): string {
+		const value = this.getOption(key);
+		if (typeof value !== 'string') {
+			throw new QuereusError(`Option ${key} is not a string (got ${typeof value})`, StatusCode.INTERNAL);
+		}
+		return value;
+	}
+
+	/**
+	 * Get an object option value with type safety
+	 */
+	getObjectOption(key: string): Record<string, any> {
+		const value = this.getOption(key);
+		if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+			throw new QuereusError(`Option ${key} is not an object (got ${typeof value})`, StatusCode.INTERNAL);
+		}
+		return value as Record<string, any>;
+	}
+
+
+
+	/**
+	 * Get all current options
+	 */
+	getAllOptions(): Record<string, OptionValue> {
+		const result: Record<string, OptionValue> = {};
+		for (const [key, value] of this.options) {
+			result[key] = value;
+		}
+		return result;
+	}
+
+	/**
+	 * Get all registered option definitions
+	 */
+	getOptionDefinitions(): Record<string, OptionDefinition> {
+		const result: Record<string, OptionDefinition> = {};
+		for (const [key, definition] of this.definitions) {
+			result[key] = { ...definition };
+		}
+		return result;
+	}
+
+	private resolveKey(key: string): string | null {
+		const lowerKey = key.toLowerCase();
+
+		// Check if it's an alias
+		const aliasTarget = this.aliases.get(lowerKey);
+		if (aliasTarget) {
+			return aliasTarget;
+		}
+
+		// Check if it's a direct key
+		for (const registeredKey of this.definitions.keys()) {
+			if (registeredKey.toLowerCase() === lowerKey) {
+				return registeredKey;
+			}
+		}
+
+		return null;
+	}
+
+	private convertValue(value: any, definition: OptionDefinition, originalKey: string): OptionValue {
+		switch (definition.type) {
+			case 'boolean':
+				return this.convertToBoolean(value, originalKey);
+			case 'string':
+				return String(value);
+			case 'number':
+				return this.convertToNumber(value, originalKey);
+			case 'object':
+				return this.convertToObject(value, originalKey);
+			default:
+				throw new QuereusError(`Unknown option type: ${definition.type}`, StatusCode.INTERNAL);
+		}
+	}
+
+	private convertToBoolean(value: any, key: string): boolean {
+		if (typeof value === 'boolean') {
+			return value;
+		}
+		if (typeof value === 'string') {
+			const lower = value.toLowerCase();
+			if (lower === 'true' || lower === '1' || lower === 'on' || lower === 'yes') {
+				return true;
+			}
+			if (lower === 'false' || lower === '0' || lower === 'off' || lower === 'no') {
+				return false;
+			}
+		}
+		if (typeof value === 'number') {
+			return value !== 0;
+		}
+		throw new QuereusError(`Invalid boolean value for option ${key}: ${value}`, StatusCode.ERROR);
+	}
+
+	private convertToNumber(value: any, key: string): number {
+		if (typeof value === 'number') {
+			return value;
+		}
+		if (typeof value === 'string') {
+			const num = Number(value);
+			if (!isNaN(num)) {
+				return num;
+			}
+		}
+		throw new QuereusError(`Invalid number value for option ${key}: ${value}`, StatusCode.ERROR);
+	}
+
+	private convertToObject(value: any, key: string): Record<string, SqlValue> {
+		if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+			return value;
+		}
+		if (typeof value === 'string') {
+			try {
+				const parsed = JSON.parse(value);
+				if (typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)) {
+					return parsed;
+				}
+			} catch {
+				// Fall through to error
+			}
+		}
+		throw new QuereusError(`Invalid object value for option ${key}: ${value}`, StatusCode.ERROR);
+	}
+
+	private valuesEqual(a: OptionValue, b: OptionValue): boolean {
+		if (a === b) return true;
+		if (typeof a === 'object' && typeof b === 'object' && a !== null && b !== null) {
+			return JSON.stringify(a) === JSON.stringify(b);
+		}
+		return false;
+	}
+
+	private notifyListener(key: string, oldValue: OptionValue, newValue: OptionValue): void {
+		const definition = this.definitions.get(key);
+		if (definition?.onChange) {
+			const event: OptionChangeEvent = { key, oldValue, newValue };
+			try {
+				definition.onChange(event);
+			} catch (error) {
+				log('Error in option change listener for %s: %s', key, error);
+			}
+		}
+	}
+}