@quereus/quereus 0.16.4 → 0.17.1

package/dist/src/core/database.js

@@ -1,5 +1,5 @@
 import { createLogger } from '../common/logger.js';
-import { MisuseError, quereusError, QuereusError } from '../common/errors.js';
+import { MisuseError, QuereusError } from '../common/errors.js';
 import { StatusCode } from '../common/types.js';
 import { Statement } from './statement.js';
 import { SchemaManager } from '../schema/manager.js';
@@ -7,11 +7,12 @@ import { BUILTIN_FUNCTIONS } from '../func/builtins/index.js';
 import { createScalarFunction, createAggregateFunction } from '../func/registration.js';
 import { FunctionFlags } from '../common/constants.js';
 import { MemoryTableModule } from '../vtab/memory/module.js';
-import { BINARY_COLLATION, getCollation, NOCASE_COLLATION, registerCollation, RTRIM_COLLATION } from '../util/comparison.js';
-import { Parser, ParseError } from '../parser/parser.js';
+import { BINARY_COLLATION, NOCASE_COLLATION, RTRIM_COLLATION } from '../util/comparison.js';
+import { Parser } from '../parser/parser.js';
 import { buildBlock } from '../planner/building/block.js';
 import { emitPlanNode } from '../runtime/emitters.js';
 import { Scheduler } from '../runtime/scheduler.js';
+import { RowContextMap } from '../runtime/context-helpers.js';
 import { BuildTimeDependencyTracker } from '../planner/planning-context.js';
 import { ParameterScope } from '../planner/scopes/param.js';
 import { GlobalScope } from '../planner/scopes/global.js';
@@ -23,13 +24,35 @@ import { registerBuiltinWindowFunctions } from '../func/builtins/builtin-window-
 import { DatabaseOptionsManager } from './database-options.js';
 import { DeclaredSchemaManager } from '../schema/declared-schema-manager.js';
 import { DeferredConstraintQueue } from '../runtime/deferred-constraint-queue.js';
+import { registerType as registerTypeInRegistry } from '../types/registry.js';
 import { getParameterTypes } from './param.js';
 import { rowToObject } from './utils.js';
+import { wrapAsyncIterator } from '../util/async-iterator.js';
 import { DatabaseEventEmitter, } from './database-events.js';
 import { TransactionManager } from './database-transaction.js';
 import { AssertionEvaluator } from './database-assertions.js';
 const log = createLogger('core:database');
 const errorLog = log.extend('error');
+/** Parse a comma-separated schema path string into an array of trimmed, non-empty names. */
+function parseSchemaPath(pathString) {
+    if (!pathString)
+        return undefined;
+    const parts = pathString.split(',').map(s => s.trim()).filter(s => s.length > 0);
+    return parts.length > 0 ? parts : undefined;
+}
+/** Extract a VTableEventEmitter from a module if it supports one. */
+function tryGetEventEmitter(module) {
+    const asSource = module;
+    if (typeof asSource.getEventEmitter !== 'function')
+        return undefined;
+    const emitter = asSource.getEventEmitter();
+    if (!emitter || typeof emitter !== 'object')
+        return undefined;
+    const typed = emitter;
+    if (typeof typed.onDataChange !== 'function' && typeof typed.onSchemaChange !== 'function')
+        return undefined;
+    return emitter;
+}
 /**
  * Represents a connection to an Quereus database (in-memory in this port).
  * Manages schema, prepared statements, virtual tables, and functions.
@@ -57,6 +80,8 @@ export class Database {
     transactionManager;
     /** Assertion evaluation */
     assertionEvaluator;
+    /** Per-database collation registry */
+    collations = new Map();
     constructor() {
         this.schemaManager = new SchemaManager(this);
         this.declaredSchemaManager = new DeclaredSchemaManager();
@@ -64,11 +89,6 @@ export class Database {
         log("Database instance created.");
         // Register built-in functions
         this.registerBuiltinFunctions();
-        // Register default virtual table modules via SchemaManager
-        // The SchemaManager.defaultVTabModuleName is already initialized (e.g. to 'memory')
-        // No need to set defaultVtabModuleName explicitly here unless it's different from SchemaManager's init value.
-        // this.schemaManager.setDefaultVTabModuleName('memory'); // Already 'memory' by default in SchemaManager
-        // this.schemaManager.setDefaultVTabArgs([]); // Already [] by default in SchemaManager
         this.schemaManager.registerModule('memory', new MemoryTableModule());
         // Register built-in collations
         this.registerDefaultCollations();
@@ -176,6 +196,12 @@ export class Database {
             defaultValue: false,
             description: 'Enable plan stack tracing',
         });
+        this.options.registerOption('foreign_keys', {
+            type: 'boolean',
+            defaultValue: false,
+            aliases: ['fk_enforcement'],
+            description: 'Enable foreign key constraint enforcement (default off for backwards compatibility)',
+        });
     }
     /** @internal Registers default built-in SQL functions */
     registerBuiltinFunctions() {
@@ -192,10 +218,10 @@ export class Database {
     }
     /** @internal Registers default collation sequences */
     registerDefaultCollations() {
-        // Register the built-in collations
-        registerCollation('BINARY', BINARY_COLLATION);
-        registerCollation('NOCASE', NOCASE_COLLATION);
-        registerCollation('RTRIM', RTRIM_COLLATION);
+        // Register the built-in collations into per-instance registry
+        this.collations.set('BINARY', BINARY_COLLATION);
+        this.collations.set('NOCASE', NOCASE_COLLATION);
+        this.collations.set('RTRIM', RTRIM_COLLATION);
         log("Default collations registered (BINARY, NOCASE, RTRIM)");
     }
     /**
@@ -341,6 +367,21 @@ export class Database {
     _isImplicitTransaction() {
         return this.transactionManager.isImplicitTransaction();
     }
+    /**
+     * Commits or rolls back an implicit transaction based on success.
+     * No-op if no implicit transaction is active.
+     * @internal
+     */
+    async _finalizeImplicitTransaction(success) {
+        if (this.transactionManager.isImplicitTransaction()) {
+            if (success) {
+                await this._commitTransaction();
+            }
+            else {
+                await this._rollbackTransaction();
+            }
+        }
+    }
     /**
      * Upgrades an implicit transaction to explicit.
      * @internal
@@ -354,18 +395,26 @@ export class Database {
      * Used as the innermost execution primitive.
      */
     async _executeSingleStatement(statementAst, params) {
-        const plan = this._buildPlan([statementAst], params);
+        const { plan } = this._buildPlan([statementAst], params);
         if (plan.statements.length === 0)
             return; // No-op for this AST
         const optimizedPlan = this.optimizer.optimize(plan, this);
         const emissionContext = new EmissionContext(this);
         const rootInstruction = emitPlanNode(optimizedPlan, emissionContext);
         const scheduler = new Scheduler(rootInstruction);
+        // Normalize array params to a record keyed by 1-based index, matching Statement.bindAll
+        let boundArgs = {};
+        if (Array.isArray(params)) {
+            params.forEach((value, index) => { boundArgs[index + 1] = value; });
+        }
+        else if (params) {
+            boundArgs = { ...params };
+        }
         const runtimeCtx = {
             db: this,
             stmt: undefined,
-            params: params ?? {},
-            context: new Map(),
+            params: boundArgs,
+            context: new RowContextMap(),
             tableContexts: new Map(),
             tracer: this.instructionTracer,
             enableMetrics: this.options.getBooleanOption('runtime_stats'),
@@ -386,15 +435,7 @@ export class Database {
      * Parses SQL into a statement batch.
      */
     _parseSql(sql) {
-        const parser = new Parser();
-        try {
-            return parser.parseAll(sql);
-        }
-        catch (e) {
-            if (e instanceof ParseError)
-                throw new QuereusError(`Parse error: ${e.message}`, StatusCode.ERROR, e);
-            throw e;
-        }
+        return new Parser().parseAll(sql);
     }
     // ============================================================================
     // Statement Execution - Public API
@@ -465,6 +506,21 @@ export class Database {
      */
     registerModule(name, module, auxData) {
         this.checkOpen();
+        if (typeof name !== 'string' || !name) {
+            throw new MisuseError('registerModule: name must be a non-empty string');
+        }
+        if (!module || typeof module !== 'object') {
+            throw new MisuseError('registerModule: module must be an object');
+        }
+        if (typeof module.create !== 'function') {
+            throw new MisuseError('registerModule: module.create must be a function');
+        }
+        if (typeof module.connect !== 'function') {
+            throw new MisuseError('registerModule: module.connect must be a function');
+        }
+        if (typeof module.destroy !== 'function') {
+            throw new MisuseError('registerModule: module.destroy must be a function');
+        }
         this.schemaManager.registerModule(name, module, auxData);
         // Check if the module has a getEventEmitter method and hook it up
         this.hookModuleEvents(name, module);
@@ -474,18 +530,10 @@ export class Database {
      * @internal
      */
     hookModuleEvents(name, module) {
-        // Check if module has getEventEmitter method
-        const getEmitter = module.getEventEmitter;
-        if (typeof getEmitter === 'function') {
-            const emitter = getEmitter.call(module);
-            if (emitter && typeof emitter === 'object') {
-                // Check if emitter has the expected methods
-                const vtabEmitter = emitter;
-                if (typeof vtabEmitter.onDataChange === 'function' || typeof vtabEmitter.onSchemaChange === 'function') {
-                    this.eventEmitter.hookModuleEmitter(name, emitter);
-                    log('Hooked event emitter for module: %s', name);
-                }
-            }
+        const emitter = tryGetEventEmitter(module);
+        if (emitter) {
+            this.eventEmitter.hookModuleEmitter(name, emitter);
+            log('Hooked event emitter for module: %s', name);
         }
     }
     // ============================================================================
@@ -608,6 +656,8 @@ export class Database {
         const finalizePromises = Array.from(this.statements).map(stmt => stmt.finalize());
         await Promise.allSettled(finalizePromises); // Wait even if some fail
         this.statements.clear();
+        // Clean up assertion evaluator (unsubscribe schema change listener, clear plan cache)
+        this.assertionEvaluator.dispose();
         // Clear schemas, ensuring VTabs are potentially disconnected
         // This will also call destroy on VTabs via SchemaManager.clearAll -> schema.clearTables -> schemaManager.dropTable
         this.schemaManager.clearAll();
@@ -638,6 +688,18 @@ export class Database {
         }
         this.schemaManager.getMainSchema().addTable(definition);
     }
+    /** Wraps function registration with consistent error logging and re-throw. */
+    registerFunctionWithErrorHandling(funcType, funcName, numArgs, register) {
+        try {
+            register();
+        }
+        catch (e) {
+            errorLog(`Failed to register ${funcType} function ${funcName}/${numArgs}: %O`, e);
+            if (e instanceof QuereusError)
+                throw e;
+            throw new QuereusError(`Failed to register ${funcType} function ${funcName}/${numArgs}: ${e instanceof Error ? e.message : String(e)}`, StatusCode.ERROR, e instanceof Error ? e : undefined);
+        }
+    }
     /**
      * Registers a user-defined scalar function.
      *
@@ -650,16 +712,9 @@ export class Database {
         const baseFlags = (options.deterministic ? FunctionFlags.DETERMINISTIC : 0) | FunctionFlags.UTF8;
         const flags = options.flags ?? baseFlags;
         const schema = createScalarFunction({ name, numArgs: options.numArgs, flags }, func);
-        try {
+        this.registerFunctionWithErrorHandling('scalar', name, options.numArgs, () => {
             this.schemaManager.getMainSchema().addFunction(schema);
-        }
-        catch (e) {
-            errorLog(`Failed to register scalar function ${name}/${options.numArgs}: %O`, e);
-            if (e instanceof Error)
-                throw e;
-            else
-                quereusError(String(e));
-        }
+        });
     }
     /**
      * Registers a user-defined aggregate function.
@@ -673,16 +728,9 @@ export class Database {
         this.checkOpen();
         const flags = options.flags ?? FunctionFlags.UTF8;
         const schema = createAggregateFunction({ name, numArgs: options.numArgs, flags, initialValue: options.initialState }, stepFunc, finalFunc);
-        try {
+        this.registerFunctionWithErrorHandling('aggregate', name, options.numArgs, () => {
             this.schemaManager.getMainSchema().addFunction(schema);
-        }
-        catch (e) {
-            errorLog(`Failed to register aggregate function ${name}/${options.numArgs}: %O`, e);
-            if (e instanceof Error)
-                throw e;
-            else
-                quereusError(String(e));
-        }
+        });
     }
     /**
      * Registers a function using a pre-defined FunctionSchema.
@@ -692,16 +740,35 @@ export class Database {
      */
     registerFunction(schema) {
         this.checkOpen();
-        try {
-            this.schemaManager.getMainSchema().addFunction(schema);
+        if (!schema || typeof schema !== 'object') {
+            throw new MisuseError('registerFunction: schema must be an object');
         }
-        catch (e) {
-            errorLog(`Failed to register function ${schema.name}/${schema.numArgs}: %O`, e);
-            if (e instanceof Error)
-                throw e;
-            else
-                quereusError(String(e));
+        if (typeof schema.name !== 'string' || !schema.name) {
+            throw new MisuseError('registerFunction: schema.name must be a non-empty string');
         }
+        if (!Number.isInteger(schema.numArgs) || schema.numArgs < -1) {
+            throw new MisuseError('registerFunction: schema.numArgs must be an integer >= -1');
+        }
+        // Validate that appropriate implementation functions exist
+        if ('stepFunction' in schema) {
+            if (typeof schema.stepFunction !== 'function') {
+                throw new MisuseError('registerFunction: aggregate schema.stepFunction must be a function');
+            }
+            if (typeof schema.finalizeFunction !== 'function') {
+                throw new MisuseError('registerFunction: aggregate schema.finalizeFunction must be a function');
+            }
+        }
+        else if ('implementation' in schema) {
+            if (typeof schema.implementation !== 'function') {
+                throw new MisuseError('registerFunction: schema.implementation must be a function');
+            }
+        }
+        else {
+            throw new MisuseError('registerFunction: schema must have implementation (scalar/TVF) or stepFunction+finalizeFunction (aggregate)');
+        }
+        this.registerFunctionWithErrorHandling('user', schema.name, schema.numArgs, () => {
+            this.schemaManager.getMainSchema().addFunction(schema);
+        });
     }
     /** Sets only the name of the default module. */
     setDefaultVtabName(name) {
@@ -756,8 +823,7 @@ export class Database {
      */
     getSchemaPath() {
         this.checkOpen();
-        const pathString = this.options.getStringOption('schema_path');
-        return pathString.split(',').map(s => s.trim()).filter(s => s.length > 0);
+        return parseSchemaPath(this.options.getStringOption('schema_path')) ?? [];
     }
     /**
      * Set database configuration options
@@ -800,8 +866,18 @@ export class Database {
      */
     registerCollation(name, func) {
         this.checkOpen();
-        registerCollation(name, func);
-        log('Registered collation: %s', name);
+        if (typeof name !== 'string' || !name) {
+            throw new MisuseError('registerCollation: name must be a non-empty string');
+        }
+        if (typeof func !== 'function') {
+            throw new MisuseError('registerCollation: func must be a function');
+        }
+        const upperName = name.toUpperCase();
+        if (this.collations.has(upperName)) {
+            log('Overwriting existing collation: %s', upperName);
+        }
+        this.collations.set(upperName, func);
+        log('Registered collation: %s', upperName);
     }
     /**
      * Registers a custom logical type.
@@ -821,8 +897,31 @@ export class Database {
      */
     registerType(name, definition) {
         this.checkOpen();
-        const { registerType } = require('../types/registry.js');
-        registerType(name, definition);
+        if (typeof name !== 'string' || !name) {
+            throw new MisuseError('registerType: name must be a non-empty string');
+        }
+        if (!definition || typeof definition !== 'object') {
+            throw new MisuseError('registerType: definition must be an object');
+        }
+        if (typeof definition.name !== 'string' || !definition.name) {
+            throw new MisuseError('registerType: definition.name must be a non-empty string');
+        }
+        // Validate physicalType is a valid enum value (0-5)
+        if (typeof definition.physicalType !== 'number' || !Number.isInteger(definition.physicalType) || definition.physicalType < 0 || definition.physicalType > 5) {
+            throw new MisuseError('registerType: definition.physicalType must be a valid PhysicalType enum value (0-5)');
+        }
+        if (definition.name.toLowerCase() !== name.toLowerCase()) {
+            throw new QuereusError(`Type name mismatch: registerType('${name}', ...) does not match definition.name '${definition.name}'`, StatusCode.ERROR);
+        }
+        try {
+            registerTypeInRegistry(definition);
+        }
+        catch (e) {
+            errorLog('Failed to register type %s: %O', name, e);
+            if (e instanceof QuereusError)
+                throw e;
+            throw new QuereusError(`Failed to register type '${name}': ${e instanceof Error ? e.message : String(e)}`, StatusCode.ERROR, e instanceof Error ? e : undefined);
+        }
         log('Registered type: %s', name);
     }
     /**
@@ -843,7 +942,7 @@ export class Database {
     }
     /** @internal Gets a registered collation function */
     _getCollation(name) {
-        return getCollation(name);
+        return this.collations.get(name.toUpperCase());
     }
     _queueDeferredConstraintRow(baseTable, constraintName, row, descriptor, evaluator, connectionId, contextRow, contextDescriptor) {
         this.deferredConstraints.enqueue(baseTable, constraintName, row, descriptor, evaluator, connectionId, contextRow, contextDescriptor);
@@ -869,15 +968,17 @@ export class Database {
     _recordUpdate(baseTable, oldKey, newKey) {
         this.transactionManager.recordUpdate(baseTable, oldKey, newKey);
     }
-    /** Savepoint change tracking */
-    _beginSavepointLayer() {
-        this.transactionManager.beginSavepointLayer();
+    /** Create a named savepoint, returning its depth index */
+    _createSavepoint(name) {
+        return this.transactionManager.createSavepoint(name);
     }
-    _rollbackSavepointLayer() {
-        this.transactionManager.rollbackSavepointLayer();
+    /** Release a named savepoint (merges layers down to target), returns target depth */
+    _releaseSavepoint(name) {
+        return this.transactionManager.releaseSavepoint(name);
     }
-    _releaseSavepointLayer() {
-        this.transactionManager.releaseSavepointLayer();
+    /** Rollback to a named savepoint (discards layers down to target) */
+    _rollbackToSavepoint(name) {
+        return this.transactionManager.rollbackToSavepoint(name);
     }
     _clearChangeLog() {
         this.transactionManager.clearChangeLog();
@@ -910,56 +1011,7 @@ export class Database {
      * ```
      */
     eval(sql, params) {
-        // Create the generator that does the actual work
-        const generator = this._evalGenerator(sql, params);
-        // Track whether the transaction has been finalized
-        let transactionFinalized = false;
-        // Helper to finalize the implicit transaction (idempotent)
-        const finalizeImplicitTransaction = async (commit) => {
-            if (transactionFinalized)
-                return;
-            transactionFinalized = true;
-            if (this.transactionManager.isImplicitTransaction()) {
-                if (commit) {
-                    await this._commitTransaction();
-                }
-                else {
-                    await this._rollbackTransaction();
-                }
-            }
-        };
-        // Wrap the generator to intercept return() and throw()
-        const wrappedIterator = {
-            [Symbol.asyncIterator]() {
-                return this;
-            },
-            async next() {
-                return generator.next();
-            },
-            async return(value) {
-                // Called on early termination (break, return, etc.)
-                // Commit the implicit transaction before delegating to the generator
-                try {
-                    await finalizeImplicitTransaction(true);
-                }
-                finally {
-                    // Delegate to generator.return() to trigger cleanup (finally block)
-                    return generator.return(value);
-                }
-            },
-            async throw(error) {
-                // Called when an error is thrown into the iterator
-                // Rollback the implicit transaction before delegating
-                try {
-                    await finalizeImplicitTransaction(false);
-                }
-                finally {
-                    // Delegate to generator.throw() to propagate the error
-                    return generator.throw(error);
-                }
-            }
-        };
-        return wrappedIterator;
+        return wrapAsyncIterator(this._evalGenerator(sql, params), (commit) => this._finalizeImplicitTransaction(commit));
     }
     /**
      * Internal generator for eval() that yields result rows.
@@ -968,27 +1020,20 @@ export class Database {
      */
     async *_evalGenerator(sql, params) {
         this.checkOpen();
-        // Acquire mutex for the entire iteration
         const releaseMutex = await this._acquireExecMutex();
         let stmt = null;
-        let normalCompletion = false;
         try {
-            // Execute - transactions are started JIT by runtime when needed
             stmt = this.prepare(sql);
             if (stmt.astBatch.length === 0) {
-                // No statements, yield nothing.
-                normalCompletion = true;
                 return;
             }
             if (stmt.astBatch.length > 1) {
                 // Multi-statement batch: execute all but the last statement,
                 // then yield results from the last statement
                 const batch = this._parseSql(sql);
-                // Execute all statements except the last one
                 for (let i = 0; i < batch.length - 1; i++) {
                     await this._executeSingleStatement(batch[i], params);
                 }
-                // Now prepare and execute the last statement to yield its results
                 const lastStmt = new Statement(this, [batch[batch.length - 1]]);
                 this.statements.add(lastStmt);
                 try {
@@ -1002,25 +1047,11 @@ export class Database {
                 }
             }
             else {
-                // Single statement: execute and yield results
                 const names = stmt.getColumnNames();
                 for await (const row of stmt._iterateRowsRaw(params)) {
                     yield rowToObject(row, names);
                 }
             }
-            normalCompletion = true;
-            // Commit implicit transaction on normal completion
-            // (The wrapper also handles this for early termination via return())
-            if (this.transactionManager.isImplicitTransaction()) {
-                await this._commitTransaction();
-            }
-        }
-        catch (err) {
-            // Rollback implicit transaction on error
-            if (this.transactionManager.isImplicitTransaction()) {
-                await this._rollbackTransaction();
-            }
-            throw err;
         }
         finally {
             if (stmt) {
@@ -1040,7 +1071,7 @@ export class Database {
                 ast = parser.parse(originalSqlString);
             }
             catch (err) {
-                const error = err instanceof Error ? err : new Error(String(err));
+                const error = err instanceof QuereusError ? err : new QuereusError(String(err), StatusCode.ERROR, err instanceof Error ? err : undefined);
                 errorLog("Failed to parse SQL for query plan: %O", error);
                 throw error;
             }
@@ -1048,7 +1079,7 @@ export class Database {
         else {
             ast = sqlOrAst;
         }
-        const plan = this._buildPlan([ast]);
+        const { plan } = this._buildPlan([ast]);
         if (plan.statements.length === 0)
             return plan; // No-op for this AST
         return this.optimizer.optimize(plan, this);
@@ -1086,7 +1117,6 @@ export class Database {
         this.checkOpen();
         log('Preparing SQL with debug options: %s', sql);
         const stmt = new Statement(this, sql);
-        // Set debug options on the statement
         stmt._debugOptions = debug;
         this.statements.add(stmt);
         return stmt;
@@ -1116,21 +1146,22 @@ export class Database {
         // This ParameterScope is for the entire batch. It has globalScope as its parent.
         const parameterScope = new ParameterScope(globalScope, parameterTypes);
         // Get default schema path from options
-        const schemaPathString = this.options.getStringOption('schema_path');
-        const schemaPath = schemaPathString ? schemaPathString.split(',').map(s => s.trim()).filter(s => s.length > 0) : undefined;
+        const schemaPath = parseSchemaPath(this.options.getStringOption('schema_path'));
+        const schemaDependencies = new BuildTimeDependencyTracker();
         const ctx = {
             db: this,
             schemaManager: this.schemaManager,
             parameters: paramsOrTypes instanceof Map ? {} : (paramsOrTypes ?? {}),
             scope: parameterScope,
             cteNodes: new Map(),
-            schemaDependencies: new BuildTimeDependencyTracker(),
+            schemaDependencies,
             schemaCache: new Map(),
             cteReferenceCache: new Map(),
             outputScopes: new Map(),
             schemaPath
         };
-        return buildBlock(ctx, statements);
+        const plan = buildBlock(ctx, statements);
+        return { plan, schemaDependencies };
     }
     /**
      * @internal Registers an active VirtualTable connection for transaction management.
@@ -1226,5 +1257,9 @@ export class Database {
     async runGlobalAssertions() {
         await this.assertionEvaluator.runGlobalAssertions();
     }
+    /** @internal Invalidate cached assertion plan (called on DROP ASSERTION) */
+    invalidateAssertionCache(name) {
+        this.assertionEvaluator.invalidateAssertion(name);
+    }
 }
 //# sourceMappingURL=database.js.map