@quereus/quereus 0.7.3 → 0.7.4

package/src/func/context.ts

@@ -1,258 +0,0 @@
-import { createLogger } from '../common/logger.js';
-import { type SqlValue, StatusCode } from '../common/types.js';
-import { QuereusError } from '../common/errors.js';
-import type { Database } from '../core/database.js';
-
-/**
- * Represents the execution context passed to user-defined SQL functions
- * (scalar, aggregate, window) and to virtual table methods.
- * Provides methods for setting results and accessing auxiliary data.
- *
- * Methods that set a result should be the last action in a function
- * implementation. Setting multiple results or setting a result then
- * throwing an error leads to undefined behavior.
- */
-export interface QuereusContext {
-	/**
-	 * Sets the result of the function to a BLOB value.
-	 * @param value The BLOB data
-	 * @param destructor Optional hint that influences whether the engine copies the buffer
-	 */
-	resultBlob(value: Uint8Array, destructor?: unknown): void;
-
-	/**
-	 * Sets the result of the function to a floating-point value.
-	 * @param value The double value
-	 */
-	resultDouble(value: number): void;
-
-	/**
-	 * Causes the function to return an error state.
-	 * @param message The error message
-	 * @param code Optional error code (defaults to ERROR)
-	 */
-	resultError(message: string, code?: StatusCode): void;
-
-	/**
-	 * Sets the result of the function to a 32-bit integer value.
-	 * For larger integers, use resultInt64.
-	 * @param value The integer value
-	 */
-	resultInt(value: number): void;
-
-	/**
-	 * Sets the result of the function to a 64-bit integer value.
-	 * @param value The bigint value
-	 */
-	resultInt64(value: bigint): void;
-
-	/**
-	 * Sets the result of the function to SQL NULL.
-	 */
-	resultNull(): void;
-
-	/**
-	 * Sets the result of the function to a TEXT value.
-	 * @param value The string value
-	 * @param destructor Optional hint that influences whether the engine copies the string
-	 */
-	resultText(value: string, destructor?: unknown): void;
-
-	/**
-	 * Sets the result of the function to the provided SqlValue.
-	 * @param value The SqlValue to set as the result
-	 */
-	resultValue(value: SqlValue): void;
-
-	/**
-	 * Sets the result to a zero-filled BLOB of a specified size.
-	 * @param n The desired size of the zeroblob in bytes
-	 */
-	resultZeroblob(n: number): void;
-
-	/**
-	 * Sets the application-defined subtype for the result value.
-	 * @param subtype An unsigned integer representing the subtype
-	 */
-	resultSubtype(subtype: number): void;
-
-	/**
-	 * Returns the user data associated with the function registration.
-	 * @returns The user data specified during registration
-	 */
-	getUserData(): unknown;
-
-	/**
-	 * Returns the Database connection associated with this context.
-	 * @returns The database connection
-	 */
-	getDbConnection(): Database;
-
-	/**
-	 * Gets auxiliary data previously associated with a function argument.
-	 * Used for caching computations across multiple calls with the same arguments.
-	 * @param N The argument index (0-based)
-	 * @returns The stored auxiliary data, or undefined if none exists
-	 */
-	getAuxData(N: number): unknown;
-
-	/**
-	 * Sets auxiliary data associated with a specific function argument.
-	 * @param N The argument index (0-based)
-	 * @param data The data to store
-	 * @param destructor Optional cleanup function called when the data is discarded
-	 */
-	setAuxData(N: number, data: unknown, destructor?: (data: unknown) => void): void;
-
-	/**
-	 * Retrieves the context (accumulator) for an aggregate function.
-	 * @param createIfNotFound If true and no context exists, creates a new empty object
-	 * @returns The aggregate context for the current group, or undefined
-	 */
-	// eslint-disable-next-line @typescript-eslint/no-explicit-any
-	getAggregateContext<T = any>(createIfNotFound?: boolean): T | undefined;
-
-	/**
-	 * Sets the context (accumulator) for an aggregate function.
-	 * @param context The new state for the aggregate context
-	 */
-	// eslint-disable-next-line @typescript-eslint/no-explicit-any
-	setAggregateContext<T = any>(context: T): void;
-}
-
-const log = createLogger('func:context');
-const errorLog = log.extend('error');
-
-/**
- * Concrete implementation of QuereusContext used by the engine.
- * @internal
- */
-export class FunctionContext implements QuereusContext {
-	private _result: SqlValue | undefined = undefined;
-	private _result_set = false;
-	private _error: QuereusError | null = null;
-	private _subtype: number = 0;
-	private userData: unknown;
-	private db: Database;
-	private auxData: Map<number, { data: unknown, destructor?: (data: unknown) => void }> = new Map();
-	// eslint-disable-next-line @typescript-eslint/no-explicit-any
-	private _aggregateContext: any | undefined = undefined;
-
-	constructor(db: Database, userData?: unknown) {
-		this.db = db;
-		this.userData = userData;
-	}
-
-	/**
-	 * @internal Gets the function result or throws if in error state
-	 */
-	_getResult(): SqlValue | null {
-		if (this._error) throw this._error;
-		return this._result_set ? this._result! : null;
-	}
-
-	/**
-	 * @internal Gets the error if one occurred
-	 */
-	_getError(): QuereusError | null { return this._error; }
-
-	/**
-	 * @internal Gets the result subtype
-	 */
-	_getSubtype(): number { return this._subtype; }
-
-	/**
-	 * @internal Resets the context for reuse
-	 */
-	_clear(): void {
-		this._result = undefined;
-		this._result_set = false;
-		this._error = null;
-		this._subtype = 0;
-	}
-
-	/**
-	 * @internal Sets the aggregate context reference from VDBE
-	 */
-	// eslint-disable-next-line @typescript-eslint/no-explicit-any
-	_setAggregateContextRef(contextRef: any | undefined): void {
-		this._aggregateContext = contextRef;
-	}
-
-	/**
-	 * @internal Gets the potentially modified aggregate context
-	 */
-	// eslint-disable-next-line @typescript-eslint/no-explicit-any
-	_getAggregateContextRef(): any | undefined {
-		return this._aggregateContext;
-	}
-
-	private setResult(value: SqlValue) {
-		if (this._result_set || this._error) return;
-		this._result = value;
-		this._result_set = true;
-	}
-
-	resultBlob(value: Uint8Array): void { this.setResult(value); }
-	resultDouble(value: number): void { this.setResult(value); }
-	resultError(message: string, code: StatusCode = StatusCode.ERROR): void {
-		if (this._result_set || this._error) return;
-		this._error = new QuereusError(message, code);
-	}
-	resultInt(value: number): void { this.setResult(Math.trunc(value)); }
-	resultInt64(value: bigint): void { this.setResult(value); }
-	resultNull(): void { this.setResult(null); }
-	resultText(value: string): void { this.setResult(value); }
-	resultValue(value: SqlValue): void { this.setResult(value); }
-	resultZeroblob(n: number): void { this.setResult(new Uint8Array(n)); }
-	resultSubtype(subtype: number): void { this._subtype = subtype >>> 0; }
-
-	getUserData(): unknown { return this.userData; }
-	getDbConnection(): Database { return this.db; }
-
-	getAuxData(N: number): unknown {
-		return this.auxData.get(N)?.data;
-	}
-
-	setAuxData(N: number, data: unknown, destructor?: (data: unknown) => void): void {
-		if (this._error) return;
-		const existing = this.auxData.get(N);
-		if (existing?.destructor && existing.data !== data) {
-			try { existing.destructor(existing.data); } catch (e) {
-				errorLog("Internal: AuxData destructor failed: %O", e);
-			}
-		}
-		if (data === undefined && destructor === undefined) {
-			this.auxData.delete(N);
-		} else {
-			this.auxData.set(N, { data, destructor });
-		}
-	}
-
-	// eslint-disable-next-line @typescript-eslint/no-explicit-any
-	getAggregateContext<T = any>(createIfNotFound: boolean = false): T | undefined {
-		if (this._aggregateContext === undefined && createIfNotFound) {
-			return {} as T;
-		}
-		return this._aggregateContext as T | undefined;
-	}
-
-	// eslint-disable-next-line @typescript-eslint/no-explicit-any
-	setAggregateContext<T = any>(context: T): void {
-		this._aggregateContext = context;
-	}
-
-	/**
-	 * @internal Cleans up auxiliary data during statement reset/finalize
-	 */
-	_cleanupAuxData(): void {
-		this.auxData.forEach(entry => {
-			if (entry.destructor) {
-				try { entry.destructor(entry.data); } catch (e) {
-					errorLog("Internal: AuxData destructor failed: %O", e);
-				}
-			}
-		});
-		this.auxData.clear();
-	}
-}

package/src/func/registration.ts

@@ -1,201 +0,0 @@
-import type { AggregateFinalizer, AggregateReducer, IntegratedTableValuedFunc, ScalarFunc, TableValuedFunc, ScalarFunctionSchema,
-	TableValuedFunctionSchema, AggregateFunctionSchema } from '../schema/function.js';
-import { FunctionFlags } from '../common/constants.js';
-import type { ScalarType, RelationType } from '../common/datatype.js';
-import { REAL_TYPE } from '../types/builtin-types.js';
-import type { LogicalType } from '../types/logical-type.js';
-import type { DeepReadonly } from '../common/types.js';
-
-/**
- * Configuration options for scalar functions
- */
-interface ScalarFuncOptions {
-	/** Function name as it will be called in SQL */
-	name: string;
-	/** Number of arguments, or -1 for variable number */
-	numArgs: number;
-	/** Function behavior flags */
-	flags?: FunctionFlags;
-	/** Whether the function is deterministic (affects caching) */
-	deterministic?: boolean;
-	/** Return type information */
-	returnType?: ScalarType;
-	/**
-	 * Optional type inference function for polymorphic functions.
-	 * If provided, this function will be called at planning time to determine
-	 * the return type based on the actual argument types.
-	 */
-	inferReturnType?: (argTypes: ReadonlyArray<DeepReadonly<LogicalType>>) => ScalarType;
-	/**
-	 * Optional argument type validation function.
-	 * If provided, this function will be called at planning time to validate
-	 * that the argument types are acceptable for this function.
-	 */
-	validateArgTypes?: (argTypes: ReadonlyArray<DeepReadonly<LogicalType>>) => boolean;
-}
-
-/**
- * Configuration options for table-valued functions
- */
-interface TableValuedFuncOptions {
-	/** Function name as it will be called in SQL */
-	name: string;
-	/** Number of arguments, or -1 for variable number */
-	numArgs: number;
-	/** Function behavior flags */
-	flags?: FunctionFlags;
-	/** Whether the function is deterministic (affects caching) */
-	deterministic?: boolean;
-	/** Return type (relation) information */
-	returnType?: RelationType;
-}
-
-/* Interim values for aggregate functions don't have to be SqlValue; they can be anything */
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export type AggValue = any;
-
-/**
- * Configuration options for aggregate functions
- */
-interface AggregateFuncOptions {
-	/** Function name as it will be called in SQL */
-	name: string;
-	/** Number of arguments, or -1 for variable number */
-	numArgs: number;
-	/** Function behavior flags */
-	flags?: FunctionFlags;
-	/** Whether the function is deterministic (affects caching) */
-	deterministic?: boolean;
-	/** Initial accumulator value */
-	initialValue?: AggValue;
-	/** Return type information */
-	returnType?: ScalarType;
-	/**
-	 * Optional type inference function for polymorphic aggregate functions.
-	 * If provided, this function will be called at planning time to determine
-	 * the return type based on the actual argument types.
-	 */
-	inferReturnType?: (argTypes: ReadonlyArray<DeepReadonly<LogicalType>>) => ScalarType;
-	/**
-	 * Optional argument type validation function.
-	 * If provided, this function will be called at planning time to validate
-	 * that the argument types are acceptable for this function.
-	 */
-	validateArgTypes?: (argTypes: ReadonlyArray<DeepReadonly<LogicalType>>) => boolean;
-}
-
-/**
- * Creates a function schema for a scalar SQL function.
- * This is the primary way to register scalar functions in Quereus.
- *
- * @param options Configuration options for the function
- * @param jsFunc The JavaScript implementation function
- * @returns A FunctionSchema ready for registration
- */
-export function createScalarFunction(options: ScalarFuncOptions, jsFunc: ScalarFunc): ScalarFunctionSchema {
-	const returnType: ScalarType = options.returnType ?? {
-		typeClass: 'scalar',
-		logicalType: REAL_TYPE,
-		nullable: true,
-		isReadOnly: true
-	};
-
-	return {
-		name: options.name,
-		numArgs: options.numArgs,
-		flags: options.flags ?? (FunctionFlags.UTF8 | (options.deterministic !== false ? FunctionFlags.DETERMINISTIC : 0)),
-		returnType,
-		implementation: jsFunc,
-		inferReturnType: options.inferReturnType,
-		validateArgTypes: options.validateArgTypes
-	};
-}
-
-/**
- * Creates a function schema for a table-valued function.
- * Table-valued functions return AsyncIterable<Row> and can be used in FROM clauses.
- *
- * @param options Configuration options for the function
- * @param jsFunc The JavaScript implementation function
- * @returns A FunctionSchema ready for registration
- */
-export function createTableValuedFunction(options: TableValuedFuncOptions, jsFunc: TableValuedFunc): TableValuedFunctionSchema {
-	const returnType: RelationType = options.returnType ?? {
-		typeClass: 'relation',
-		isReadOnly: true,
-		isSet: false, // Table functions can return duplicates by default
-		columns: [],
-		keys: [],
-		rowConstraints: []
-	};
-
-	return {
-		name: options.name,
-		numArgs: options.numArgs,
-		flags: options.flags ?? (FunctionFlags.UTF8 | (options.deterministic !== false ? FunctionFlags.DETERMINISTIC : 0)),
-		returnType,
-		implementation: jsFunc
-	};
-}
-
-/**
- * Creates a function schema for an integrated table-valued function.
- * Integrated functions receive the database instance as their first parameter.
- *
- * @param options Configuration options for the function
- * @param jsFunc The JavaScript implementation function
- * @returns A FunctionSchema ready for registration
- */
-export function createIntegratedTableValuedFunction(options: TableValuedFuncOptions, jsFunc: IntegratedTableValuedFunc): TableValuedFunctionSchema {
-	const returnType: RelationType = options.returnType ?? {
-		typeClass: 'relation',
-		isReadOnly: true,
-		isSet: false, // Table functions can return duplicates by default
-		columns: [],
-		keys: [],
-		rowConstraints: []
-	};
-
-	return {
-		name: options.name,
-		numArgs: options.numArgs,
-		flags: options.flags ?? (FunctionFlags.UTF8 | (options.deterministic !== false ? FunctionFlags.DETERMINISTIC : 0)),
-		returnType,
-		implementation: jsFunc,
-		isIntegrated: true
-	};
-}
-
-/**
- * Creates a function schema for an aggregate function.
- * Aggregate functions use a step/finalize pattern to accumulate values.
- *
- * @param options Configuration options for the function
- * @param stepFunc Function called for each row
- * @param finalizeFunc Function called to get final result
- * @returns A FunctionSchema ready for registration
- */
-export function createAggregateFunction(
-	options: AggregateFuncOptions,
-	stepFunc: AggregateReducer,
-	finalizeFunc: AggregateFinalizer
-): AggregateFunctionSchema {
-	const returnType: ScalarType = options.returnType ?? {
-		typeClass: 'scalar',
-		logicalType: REAL_TYPE,
-		nullable: true,
-		isReadOnly: true
-	};
-
-	return {
-		name: options.name,
-		numArgs: options.numArgs,
-		flags: options.flags ?? (FunctionFlags.UTF8 | (options.deterministic !== false ? FunctionFlags.DETERMINISTIC : 0)),
-		returnType,
-		stepFunction: stepFunc,
-		finalizeFunction: finalizeFunc,
-		initialValue: options.initialValue,
-		inferReturnType: options.inferReturnType,
-		validateArgTypes: options.validateArgTypes
-	};
-}

package/src/index.ts

@@ -1,172 +0,0 @@
-/**
- * Quereus - A TypeScript SQL Engine
- *
- * This module provides a TypeScript implementation of a SQL database engine
- * with support for virtual tables and the full SQL query language.
- */
-
-// Core database functionality
-export { Database } from './core/database.js';
-export { Statement } from './core/statement.js';
-
-// Common data types and constants
-export { StatusCode, SqlDataType } from './common/types.js';
-export type { SqlValue, SqlParameters, Row, MaybePromise, RowOp } from './common/types.js';
-export { ConflictResolution, IndexConstraintOp, VTabConfig, FunctionFlags } from './common/constants.js';
-export { QuereusError, MisuseError, ConstraintError, unwrapError, formatErrorChain, getPrimaryError } from './common/errors.js';
-export type { ErrorInfo } from './common/errors.js';
-
-// Virtual Table API
-export { VirtualTable } from './vtab/table.js';
-export type { UpdateArgs } from './vtab/table.js';
-export type { VirtualTableConnection } from './vtab/connection.js';
-export { MemoryTableModule } from './vtab/memory/module.js';
-export type { IndexInfo, IndexConstraint, IndexConstraintUsage, IndexOrderBy } from './vtab/index-info.js';
-export { IndexScanFlags } from './vtab/index-info.js';
-export type { FilterInfo } from './vtab/filter-info.js';
-export type { BaseModuleConfig, SchemaChangeInfo } from './vtab/module.js';
-
-// Best Access Plan API (modern vtable planning interface)
-export type {
-	BestAccessPlanRequest,
-	BestAccessPlanResult,
-	ConstraintOp,
-	ColumnMeta,
-	PredicateConstraint,
-	OrderingSpec
-} from './vtab/best-access-plan.js';
-export { AccessPlanBuilder, validateAccessPlan } from './vtab/best-access-plan.js';
-
-// Collation and comparison functions
-export type { CollationFunction } from './util/comparison.js';
-export {
-	// Collation registration and lookup
-	BINARY_COLLATION,
-	NOCASE_COLLATION,
-	RTRIM_COLLATION,
-	registerCollation,
-	getCollation,
-	resolveCollation,
-	// Core comparison functions (critical for module implementations)
-	compareSqlValues,
-	compareSqlValuesFast,
-	compareRows,
-	compareTypedValues,
-	createTypedComparator,
-	// ORDER BY comparison utilities
-	compareWithOrderBy,
-	compareWithOrderByFast,
-	createOrderByComparator,
-	createOrderByComparatorFast,
-	SortDirection,
-	NullsOrdering,
-	// Truthiness evaluation
-	evaluateIsTrue,
-	isTruthy,
-	// Type introspection
-	getSqlDataTypeName
-} from './util/comparison.js';
-
-// Type system
-export type { LogicalType, CollationFunction as TypeCollationFunction } from './types/logical-type.js';
-export { PhysicalType } from './types/logical-type.js';
-export {
-	NULL_TYPE,
-	INTEGER_TYPE,
-	REAL_TYPE,
-	TEXT_TYPE,
-	BLOB_TYPE,
-	BOOLEAN_TYPE,
-	NUMERIC_TYPE,
-	ANY_TYPE
-} from './types/builtin-types.js';
-export {
-	DATE_TYPE,
-	TIME_TYPE,
-	DATETIME_TYPE,
-	TIMESPAN_TYPE
-} from './types/temporal-types.js';
-export { JSON_TYPE } from './types/json-type.js';
-export {
-	typeRegistry,
-	registerType,
-	getType,
-	getTypeOrDefault,
-	inferType
-} from './types/registry.js';
-export {
-	validateValue,
-	parseValue,
-	validateAndParse,
-	isValidForType,
-	tryParse
-} from './types/validation.js';
-
-// SQL Parser and Compiler
-export { Parser } from './parser/parser.js';
-export { Lexer, TokenType, KEYWORDS } from './parser/lexer.js';
-export { ParseError } from './parser/parser.js';
-
-// Schema management
-export { SchemaManager } from './schema/manager.js';
-export type { TableSchema, IndexSchema as TableIndexSchema } from './schema/table.js';
-export type { ColumnSchema } from './schema/column.js';
-
-// Runtime utilities
-export { isAsyncIterable, getAsyncIterator, asyncIterableToArray } from './runtime/utils.js';
-
-// Function registration utilities
-export {
-	createScalarFunction,
-	createTableValuedFunction,
-	createAggregateFunction
-} from './func/registration.js';
-
-export type {
-	ScalarFunc,
-	TableValuedFunc,
-	AggregateReducer,
-	AggregateFinalizer,
-	FunctionSchema
-} from './schema/function.js';
-
-// Coercion utilities (for module implementations)
-export {
-	tryCoerceToNumber,
-	coerceToNumberForArithmetic,
-	coerceForComparison,
-	coerceForAggregate,
-	isNumericValue
-} from './util/coercion.js';
-
-// Utility functions
-export { Latches } from './util/latches.js';
-
-// Plugin helper for static loading (React Native, etc.)
-export { registerPlugin } from './util/plugin-helper.js';
-export type { PluginFunction } from './util/plugin-helper.js';
-
-// Initialize runtime emitters (this ensures they are registered)
-import './runtime/register.js';
-
-// Re-export virtual table framework
-export type { VirtualTableModule } from './vtab/module.js';
-
-// Re-export plugin manifest types (for plugin authors, but not the loader)
-export type {
-	PluginManifest,
-	PluginRecord,
-	PluginSetting,
-	VTablePluginInfo,
-	FunctionPluginInfo,
-	CollationPluginInfo,
-	TypePluginInfo,
-	PluginRegistrations
-} from './vtab/manifest.js';
-
-// Debug and development utilities
-export { serializePlanTree, formatPlanTree, formatPlanSummary, serializePlanTreeWithOptions } from './planner/debug.js';
-export type { PlanDisplayOptions } from './planner/debug.js';
-
-// Logging control (for environments like React Native where env vars aren't available)
-export { enableLogging, disableLogging, isLoggingEnabled } from './common/logger.js';