@quereus/quereus 0.1.0

package/dist/src/core/database-options.js

@@ -0,0 +1,211 @@
+/**
+ * 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';
+const log = createLogger('core:options');
+/**
+ * Centralized options manager with event notifications and registration
+ */
+export class DatabaseOptionsManager {
+    options = new Map();
+    definitions = new Map();
+    aliases = new Map(); // alias -> canonical key
+    /**
+     * Register an option with its definition
+     */
+    registerOption(key, definition) {
+        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, value) {
+        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) {
+        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) {
+        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) {
+        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) {
+        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;
+    }
+    /**
+     * Get all current options
+     */
+    getAllOptions() {
+        const result = {};
+        for (const [key, value] of this.options) {
+            result[key] = value;
+        }
+        return result;
+    }
+    /**
+     * Get all registered option definitions
+     */
+    getOptionDefinitions() {
+        const result = {};
+        for (const [key, definition] of this.definitions) {
+            result[key] = { ...definition };
+        }
+        return result;
+    }
+    resolveKey(key) {
+        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;
+    }
+    convertValue(value, definition, originalKey) {
+        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);
+        }
+    }
+    convertToBoolean(value, key) {
+        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);
+    }
+    convertToNumber(value, key) {
+        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);
+    }
+    convertToObject(value, key) {
+        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);
+    }
+    valuesEqual(a, b) {
+        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;
+    }
+    notifyListener(key, oldValue, newValue) {
+        const definition = this.definitions.get(key);
+        if (definition?.onChange) {
+            const event = { key, oldValue, newValue };
+            try {
+                definition.onChange(event);
+            }
+            catch (error) {
+                log('Error in option change listener for %s: %s', key, error);
+            }
+        }
+    }
+}
+//# sourceMappingURL=database-options.js.map

package/dist/src/core/database-options.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"database-options.js","sourceRoot":"","sources":["../../../src/core/database-options.ts"],"names":[],"mappings":"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"}

package/dist/src/core/database.d.ts

@@ -0,0 +1,214 @@
+import { type SqlParameters, type SqlValue } from '../common/types.js';
+import type { VirtualTableModule } from '../vtab/module.js';
+import { Statement } from './statement.js';
+import { SchemaManager } from '../schema/manager.js';
+import type { TableSchema } from '../schema/table.js';
+import type { FunctionSchema } from '../schema/function.js';
+import { type CollationFunction } from '../util/comparison.js';
+import * as AST from '../parser/ast.js';
+import type { PlanNode } from '../planner/nodes/plan-node.js';
+import type { DebugOptions } from '../planner/planning-context.js';
+import { Optimizer } from '../planner/optimizer.js';
+import { DatabaseOptionsManager } from './database-options.js';
+/**
+ * Represents a connection to an Quereus database (in-memory in this port).
+ * Manages schema, prepared statements, virtual tables, and functions.
+ */
+export declare class Database {
+    readonly schemaManager: SchemaManager;
+    private isOpen;
+    private statements;
+    private isAutocommit;
+    private inTransaction;
+    private activeConnections;
+    private inImplicitTransaction;
+    readonly optimizer: Optimizer;
+    readonly options: DatabaseOptionsManager;
+    constructor();
+    /**
+     * Prepares an SQL statement for execution.
+     * @param sql The SQL string to prepare.
+     * @returns A Statement object.
+     * @throws QuereusError on failure (e.g., syntax error).
+     */
+    prepare(sql: string): Statement;
+    /**
+     * Executes one or more SQL statements directly.
+     * @param sql The SQL string(s) to execute.
+     * @param params Optional parameters to bind.
+     * @returns A Promise resolving when execution completes.
+     * @throws QuereusError on failure.
+     */
+    exec(sql: string, params?: SqlParameters): Promise<void>;
+    /**
+     * Registers a virtual table module.
+     * @param name The name of the module.
+     * @param module The module implementation.
+     * @param auxData Optional client data passed to xCreate/xConnect.
+     */
+    registerVtabModule(name: string, module: VirtualTableModule<any, any>, auxData?: unknown): void;
+    /**
+     * Begins a transaction.
+     * @param mode Transaction mode ('deferred', 'immediate', or 'exclusive').
+     */
+    beginTransaction(mode?: 'deferred' | 'immediate' | 'exclusive'): Promise<void>;
+    /**
+     * Commits the current transaction.
+     */
+    commit(): Promise<void>;
+    /**
+     * Rolls back the current transaction.
+     */
+    rollback(): Promise<void>;
+    /**
+     * Closes the database connection and releases resources.
+     * @returns A promise resolving on completion.
+     */
+    close(): Promise<void>;
+    /**
+     * Checks if the database connection is in autocommit mode.
+     */
+    getAutocommit(): boolean;
+    /**
+     * Programmatically defines or replaces a table in the 'main' schema.
+     * This is an alternative/supplement to using `CREATE TABLE`.
+     * @param definition The schema definition for the table.
+     */
+    defineTable(definition: TableSchema): void;
+    /**
+     * Registers a user-defined scalar function.
+     *
+     * @param name The name of the SQL function.
+     * @param options Configuration: { numArgs: number, deterministic?: boolean, flags?: number }.
+     * @param func The JavaScript function implementation.
+     */
+    createScalarFunction(name: string, options: {
+        numArgs: number;
+        deterministic?: boolean;
+        flags?: number;
+    }, func: (...args: any[]) => SqlValue): void;
+    /**
+     * Registers a user-defined aggregate function.
+     *
+     * @param name The name of the SQL function.
+     * @param options Configuration: { numArgs: number, flags?: number, initialState?: any }.
+     * @param stepFunc The function called for each row (accumulator, ...args) => newAccumulator.
+     * @param finalFunc The function called at the end (accumulator) => finalResult.
+     */
+    createAggregateFunction(name: string, options: {
+        numArgs: number;
+        flags?: number;
+        initialState?: any;
+    }, stepFunc: (acc: any, ...args: any[]) => any, finalFunc: (acc: any) => SqlValue): void;
+    /**
+     * Registers a function using a pre-defined FunctionSchema.
+     * This is the lower-level registration method.
+     *
+     * @param schema The FunctionSchema object describing the function.
+     */
+    registerFunction(schema: FunctionSchema): void;
+    /** Sets only the name of the default module. */
+    setDefaultVtabName(name: string): void;
+    /** Sets the default args directly. */
+    setDefaultVtabArgs(args: Record<string, SqlValue>): void;
+    /**
+     * Gets the default virtual table module name and arguments.
+     * @returns An object containing the module name and arguments.
+     */
+    getDefaultVtabModule(): {
+        name: string;
+        args: Record<string, SqlValue>;
+    };
+    /**
+     * Set database configuration options
+     * @param option The option name
+     * @param value The option value
+     */
+    setOption(option: string, value: any): void;
+    /**
+     * Get database configuration option value
+     * @param option The option name
+     * @returns The option value
+     */
+    getOption(option: string): any;
+    /**
+     * Registers a user-defined collation sequence.
+     * @param name The name of the collation sequence (case-insensitive).
+     * @param func The comparison function (a, b) => number (-1, 0, 1).
+     * @example
+     * // Example: Create a custom collation for phone numbers
+     * db.registerCollation('PHONENUMBER', (a, b) => {
+     *   // Normalize phone numbers by removing non-digit characters
+     *   const normalize = (phone) => phone.replace(/\D/g, '');
+     *   const numA = normalize(a);
+     *   const numB = normalize(b);
+     *   return numA < numB ? -1 : numA > numB ? 1 : 0;
+     * });
+     *
+     * // Then use it in SQL:
+     * // SELECT * FROM contacts ORDER BY phone COLLATE PHONENUMBER;
+     */
+    registerCollation(name: string, func: CollationFunction): void;
+    /**
+     * Prepares, binds parameters, executes, and yields result rows for a query.
+     * This is a high-level convenience method for iterating over query results.
+     * The underlying statement is automatically finalized when iteration completes
+     * or if an error occurs.
+     *
+     * @param sql The SQL query string to execute.
+     * @param params Optional parameters to bind (array for positional, object for named).
+     * @yields Each result row as an object (`Record<string, SqlValue>`).
+     * @returns An `AsyncIterableIterator` yielding result rows.
+     * @throws MisuseError if the database is closed.
+     * @throws QuereusError on prepare/bind/execution errors.
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   for await (const user of db.eval("SELECT * FROM users WHERE status = ?", ["active"])) {
+     *     console.log(`Active user: ${user.name}`);
+     *   }
+     * } catch (e) {
+     *   console.error("Query failed:", e);
+     * }
+     * ```
+     */
+    eval(sql: string, params?: SqlParameters | SqlValue[]): AsyncIterable<Record<string, SqlValue>>;
+    getPlan(sqlOrAst: string | AST.AstNode): PlanNode;
+    /**
+     * Gets a detailed JSON representation of the query plan for debugging.
+     * @param sql The SQL statement to plan.
+     * @returns JSON string containing the detailed plan tree.
+     */
+    getDebugPlan(sql: string): string;
+    /**
+     * Prepares a statement with debug options enabled.
+     * @param sql The SQL statement to prepare.
+     * @param debug Debug options to enable.
+     * @returns A Statement with debug capabilities.
+     */
+    prepareDebug(sql: string, debug: DebugOptions): Statement;
+    /**
+     * Disconnects and removes all active connections.
+     * Called during database close.
+     */
+    private disconnectAllConnections;
+    private checkOpen;
+    /** Helper to execute simple commands (BEGIN, COMMIT, ROLLBACK) internally
+     * This method is for commands that don't produce rows and don't need complex parameter handling.
+    */
+    private execSimple;
+    /**
+     * Begin an implicit transaction and coordinate with virtual table connections
+     */
+    private beginImplicitTransaction;
+    /**
+     * Commit an implicit transaction and coordinate with virtual table connections
+     */
+    private commitImplicitTransaction;
+    /**
+     * Rollback an implicit transaction and coordinate with virtual table connections
+     */
+    private rollbackImplicitTransaction;
+}
+//# sourceMappingURL=database.d.ts.map

package/dist/src/core/database.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"database.d.ts","sourceRoot":"","sources":["../../../src/core/database.ts"],"names":[],"mappings":"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"}