@quereus/quereus 0.1.0

package/src/util/cached.ts

@@ -0,0 +1,25 @@
+/** Minimalistic caching utility. */
+export class Cached<T> {
+	private cachedValue: T | undefined;
+
+	constructor(private readonly compute: () => T) {}
+
+	get value(): T {
+		if (this.cachedValue === undefined) {	// More strict than truthy
+			this.cachedValue = this.compute();
+		}
+		return this.cachedValue;
+	}
+
+	set value(value: T) {
+		this.cachedValue = value;
+	}
+
+	get hasValue(): boolean {
+		return this.cachedValue !== undefined;
+	}
+
+	clear() {
+		this.cachedValue = undefined;
+	}
+}

package/src/util/coercion.ts

@@ -0,0 +1,113 @@
+import type { SqlValue } from '../common/types.js';
+
+/**
+ * SQL type coercion utilities.
+ * Different SQL contexts have different coercion rules.
+ */
+
+/**
+ * Attempts to convert a value to a number if it's a numeric string.
+ * Returns the original value if conversion is not appropriate.
+ * Used for comparison contexts where numeric strings should be treated as numbers.
+ */
+export function tryCoerceToNumber(value: SqlValue): SqlValue {
+	if (typeof value === 'string' && value.trim() !== '') {
+		// Try to parse as number
+		const trimmed = value.trim();
+		const asNumber = Number(trimmed);
+		if (!isNaN(asNumber) && isFinite(asNumber)) {
+			// Check if it's an integer or float
+			return Number.isInteger(asNumber) ? Math.trunc(asNumber) : asNumber;
+		}
+	}
+	return value;
+}
+
+/**
+ * Converts a value to a number for arithmetic contexts.
+ * Non-numeric strings become 0 (SQL arithmetic semantics).
+ * Used for +, -, *, /, % operations.
+ */
+export function coerceToNumberForArithmetic(value: SqlValue): number {
+	if (typeof value === 'number') {
+		return value;
+	} else if (typeof value === 'boolean') {
+		return value ? 1 : 0;
+	} else if (typeof value === 'string') {
+		const parsed = Number(value.trim());
+		return isNaN(parsed) ? 0 : parsed; // Non-numeric strings become 0
+	} else {
+		return 0; // Blobs, null, etc. become 0
+	}
+}
+
+/**
+ * Performs SQL type coercion for comparison operations.
+ * If one operand is numeric and the other is text that can be converted to a number,
+ * converts the text to a number before comparison.
+ */
+export function coerceForComparison(v1: SqlValue, v2: SqlValue): [SqlValue, SqlValue] {
+	// If either value is null, no coercion needed
+	if (v1 === null || v2 === null) {
+		return [v1, v2];
+	}
+
+	const v1IsNumeric = typeof v1 === 'number' || typeof v1 === 'bigint' || typeof v1 === 'boolean';
+	const v2IsNumeric = typeof v2 === 'number' || typeof v2 === 'bigint' || typeof v2 === 'boolean';
+	const v1IsText = typeof v1 === 'string';
+	const v2IsText = typeof v2 === 'string';
+
+	// Case 1: v1 is numeric, v2 is text -> try to convert v2 to numeric
+	if (v1IsNumeric && v2IsText) {
+		const coercedV2 = tryCoerceToNumber(v2);
+		return [v1, coercedV2];
+	}
+
+	// Case 2: v1 is text, v2 is numeric -> try to convert v1 to numeric
+	if (v1IsText && v2IsNumeric) {
+		const coercedV1 = tryCoerceToNumber(v1);
+		return [coercedV1, v2];
+	}
+
+	// No coercion needed or possible
+	return [v1, v2];
+}
+
+/**
+ * Coerces a value for aggregate function arguments.
+ * Most aggregate functions should accept numeric strings as numbers.
+ * For COUNT, no coercion needed. For SUM/AVG, numeric strings should be converted.
+ */
+export function coerceForAggregate(value: SqlValue, functionName: string): SqlValue {
+	// COUNT and similar functions don't need numeric coercion
+	if (functionName.toUpperCase() === 'COUNT' ||
+		functionName.toUpperCase() === 'GROUP_CONCAT' ||
+		functionName.toUpperCase().startsWith('JSON_')) {
+		return value;
+	}
+
+	// Numeric aggregates (SUM, AVG, MIN, MAX) should coerce numeric strings
+	if (typeof value === 'string' && value.trim() !== '') {
+		const coerced = tryCoerceToNumber(value);
+		return coerced;
+	}
+
+	return value;
+}
+
+/**
+ * Determines if a value should be treated as numeric in the given context.
+ */
+export function isNumericValue(value: SqlValue): boolean {
+	if (value === null) return false;
+	if (typeof value === 'number' || typeof value === 'bigint' || typeof value === 'boolean') {
+		return true;
+	}
+	if (typeof value === 'string') {
+		const trimmed = value.trim();
+		if (trimmed === '') return false;
+		const asNumber = Number(trimmed);
+		return !isNaN(asNumber) && isFinite(asNumber);
+	}
+	return false;
+}

package/src/util/comparison.ts

@@ -0,0 +1,437 @@
+import type { Row, SqlValue } from '../common/types.js';
+import { createLogger } from '../common/logger.js';
+
+const log = createLogger('util:comparison');
+const warnLog = log.extend('warn');
+
+/**
+ * Function type for SQLite collation functions.
+ * Takes two strings and returns a comparison result (-1, 0, 1)
+ */
+export type CollationFunction = (a: string, b: string) => number;
+
+// Map to store registered collations
+const collations = new Map<string, CollationFunction>();
+
+/**
+ * Binary (default) collation function.
+ * Performs standard lexicographical comparison of strings.
+ */
+export const BINARY_COLLATION: CollationFunction = (a, b) => {
+	return a < b ? -1 : a > b ? 1 : 0;
+};
+
+/**
+ * Case-insensitive collation function.
+ * Compares strings after converting them to lowercase.
+ */
+export const NOCASE_COLLATION: CollationFunction = (a, b) => {
+	const lowerA = a.toLowerCase();
+	const lowerB = b.toLowerCase();
+	return lowerA < lowerB ? -1 : lowerA > lowerB ? 1 : 0;
+};
+
+/**
+ * Right-trim collation function.
+ * Compares strings after removing trailing spaces.
+ */
+export const RTRIM_COLLATION: CollationFunction = (a, b) => {
+	let lenA = a.length;
+	let lenB = b.length;
+
+	while (lenA > 0 && a[lenA - 1] === ' ') lenA--;
+	while (lenB > 0 && b[lenB - 1] === ' ') lenB--;
+
+	const minLen = Math.min(lenA, lenB);
+	for (let i = 0; i < minLen; i++) {
+		if (a[i] !== b[i]) {
+			return a[i] < b[i] ? -1 : 1;
+		}
+	}
+
+	return lenA - lenB;
+};
+
+// Register built-in collations
+collations.set('BINARY', BINARY_COLLATION);
+collations.set('NOCASE', NOCASE_COLLATION);
+collations.set('RTRIM', RTRIM_COLLATION);
+
+/**
+ * Registers a collation function with the given name.
+ * @param name The name of the collation (case-insensitive)
+ * @param func The collation function to register
+ */
+export function registerCollation(name: string, func: CollationFunction): void {
+    const upperName = name.toUpperCase();
+    if (collations.has(upperName)) {
+        warnLog(`Overwriting existing collation: %s`, upperName);
+    }
+    collations.set(upperName, func);
+}
+
+/**
+ * Gets a registered collation function by name.
+ * @param name The collation name (case-insensitive)
+ * @returns The collation function, or undefined if not found
+ */
+export function getCollation(name: string): CollationFunction | undefined {
+	return collations.get(name.toUpperCase());
+}
+
+/**
+ * Resolves a collation name to its function. Optimized for hot path usage.
+ * @param collationName The collation name
+ * @returns The collation function (defaults to BINARY if not found)
+ */
+export function resolveCollation(collationName: string): CollationFunction {
+	if (collationName === 'BINARY') return BINARY_COLLATION; // Fast path for most common case
+	const func = collations.get(collationName.toUpperCase());
+	if (!func) {
+		warnLog(`Unknown collation requested: %s. Falling back to BINARY.`, collationName);
+		return BINARY_COLLATION;
+	}
+	return func;
+}
+
+/**
+ * Evaluates a JavaScript value according to simplified, JS-idiomatic truthiness rules.
+ * - null/undefined are false
+ * - boolean is its own value
+ * - number: 0 is false, non-zero is true
+ * - bigint: 0n is false, non-zero is true
+ * - string: empty string is false, non-empty is true
+ * - Uint8Array (BLOB): always false
+ *
+ * @param value The value to evaluate
+ * @returns True or false
+ */
+export function evaluateIsTrue(value: SqlValue): boolean {
+	if (value === null || value === undefined) {
+		return false;
+	}
+	switch (typeof value) {
+		case 'boolean':
+			return value;
+		case 'number':
+			return value !== 0;
+		case 'bigint':
+			return value !== 0n;
+		case 'string':
+			return value.length > 0;
+		case 'object':
+			if (value instanceof Uint8Array) {
+				return false;
+			}
+			return false;
+		default:
+			return false;
+	}
+}
+
+/** Represents SQLite storage classes for comparison purposes */
+enum StorageClass {
+	NULL = 0,
+	NUMERIC = 1, // INTEGER or REAL
+	TEXT = 2,
+	BLOB = 3,
+	UNKNOWN = 99
+}
+
+/**
+ * Determines the effective storage class for comparison, converting boolean to numeric.
+ * Optimized with early returns for common cases.
+ */
+function getStorageClass(v: SqlValue): StorageClass {
+	if (v === null) return StorageClass.NULL; // Most common null check
+
+	const type = typeof v;
+	// Fast path for numbers (most common non-null case)
+	if (type === 'number') return StorageClass.NUMERIC;
+	if (type === 'string') return StorageClass.TEXT;
+	if (type === 'boolean' || type === 'bigint') return StorageClass.NUMERIC;
+	if (type === 'object' && v instanceof Uint8Array) return StorageClass.BLOB;
+
+	return StorageClass.UNKNOWN;
+}
+
+/**
+ * Returns the SQLite fundamental datatype name of a value.
+ * @param v The value
+ * @returns The datatype name as a string
+ */
+export function getSqlDataTypeName(v: SqlValue): 'null' | 'integer' | 'real' | 'text' | 'blob' {
+	if (v === null || v === undefined) return 'null';
+	const type = typeof v;
+	if (type === 'boolean') return 'integer';
+	if (type === 'number') {
+		return Number.isInteger(v) ? 'integer' : 'real';
+	}
+	if (type === 'bigint') return 'integer';
+	if (type === 'string') return 'text';
+	if (type === 'object' && v instanceof Uint8Array) return 'blob';
+	return 'null';
+}
+
+/**
+ * Fast path comparison for two numbers (most common case).
+ * @param a First number
+ * @param b Second number
+ * @returns -1 if a < b, 0 if a === b, 1 if a > b
+ */
+function compareNumbers(a: number | bigint, b: number | bigint): number {
+	return a < b ? -1 : a > b ? 1 : 0;
+}
+
+/**
+ * Optimized comparison for same-type values.
+ * @param a First value
+ * @param b Second value
+ * @param storageClass The storage class of both values
+ * @param collationFunc The collation function (for TEXT types)
+ * @returns -1 if a < b, 0 if a === b, 1 if a > b
+ */
+function compareSameType(a: SqlValue, b: SqlValue, storageClass: StorageClass, collationFunc: CollationFunction): number {
+	switch (storageClass) {
+		case StorageClass.NUMERIC: {
+			// Convert booleans to numbers inline for efficiency
+			const valA = typeof a === 'boolean' ? (a ? 1 : 0) : a as number | bigint;
+			const valB = typeof b === 'boolean' ? (b ? 1 : 0) : b as number | bigint;
+			return compareNumbers(valA, valB);
+		}
+		case StorageClass.TEXT: {
+			return collationFunc(a as string, b as string);
+		}
+		case StorageClass.BLOB: {
+			const blobA = a as Uint8Array;
+			const blobB = b as Uint8Array;
+			const len = Math.min(blobA.length, blobB.length);
+			for (let i = 0; i < len; i++) {
+				if (blobA[i] !== blobB[i]) {
+					return blobA[i] < blobB[i] ? -1 : 1;
+				}
+			}
+			return blobA.length < blobB.length ? -1 : blobA.length > blobB.length ? 1 : 0;
+		}
+		default: {
+			return 0;
+		}
+	}
+}
+
+/**
+ * Compares two SQLite values based on SQLite's comparison rules.
+ * Follows SQLite's type ordering: NULL < Numeric < TEXT < BLOB
+ *
+ * @param a First value
+ * @param b Second value
+ * @param collationName The collation to use for text comparison (defaults to BINARY)
+ * @returns -1 if a < b, 0 if a === b, 1 if a > b
+ */
+export function compareSqlValues(a: SqlValue, b: SqlValue, collationName: string = 'BINARY'): number {
+	const collationFunc = collationName === 'BINARY' ? BINARY_COLLATION : resolveCollation(collationName);
+	return compareSqlValuesFast(a, b, collationFunc);
+}
+
+/**
+ * Optimized version of compareSqlValues that takes a pre-resolved collation function.
+ * This avoids the collation lookup on every call.
+ *
+ * @param a First value
+ * @param b Second value
+ * @param collationFunc Pre-resolved collation function
+ * @returns -1 if a < b, 0 if a === b, 1 if a > b
+ */
+export function compareSqlValuesFast(a: SqlValue, b: SqlValue, collationFunc: CollationFunction): number {
+	const classA = getStorageClass(a);
+	const classB = getStorageClass(b);
+
+	// Fast path: NULL comparisons
+	if (classA === StorageClass.NULL) {
+		return classB === StorageClass.NULL ? 0 : -1;
+	}
+	if (classB === StorageClass.NULL) {
+		return 1;
+	}
+
+	// Fast path: same type comparison
+	if (classA === classB) {
+		return compareSameType(a, b, classA, collationFunc);
+	}
+
+	// Different types: compare by storage class ordering
+	return classA - classB;
+}
+
+/**
+ * Direction flags for optimized comparisons (avoids string comparison in hot path)
+ */
+export const enum SortDirection {
+	ASC = 0,
+	DESC = 1
+}
+
+/**
+ * NULL ordering flags for optimized comparisons
+ */
+export const enum NullsOrdering {
+	DEFAULT = 0,  // Use SQLite default (nulls first for ASC, nulls last for DESC)
+	FIRST = 1,
+	LAST = 2
+}
+
+/**
+ * Highly optimized comparison function for ORDER BY operations.
+ * Takes pre-resolved collation function and numeric flags to avoid string comparisons.
+ *
+ * @param a First value
+ * @param b Second value
+ * @param direction Sort direction (SortDirection.ASC or SortDirection.DESC)
+ * @param nullsOrdering NULL ordering (NullsOrdering enum)
+ * @param collationFunc Pre-resolved collation function
+ * @returns -1 if a < b, 0 if a === b, 1 if a > b (after applying direction and null ordering)
+ */
+export function compareWithOrderByFast(
+	a: SqlValue,
+	b: SqlValue,
+	direction: SortDirection,
+	nullsOrdering: NullsOrdering,
+	collationFunc: CollationFunction
+): number {
+	let comparison: number;
+
+	// Fast path: both values are non-NULL (most common case)
+	if (a !== null && b !== null) {
+		comparison = compareSqlValuesFast(a, b, collationFunc);
+	} else if (a === null && b === null) {
+		comparison = 0;
+	} else if (a === null) {
+		// Handle NULL ordering with numeric flags (faster than string comparison)
+		if (nullsOrdering === NullsOrdering.LAST) {
+			comparison = 1; // nulls last
+		} else if (nullsOrdering === NullsOrdering.FIRST) {
+			comparison = -1; // nulls first
+		} else {
+			// Default behavior: nulls first for ASC, nulls last for DESC
+			comparison = direction === SortDirection.DESC ? 1 : -1;
+		}
+	} else { // b === null
+		if (nullsOrdering === NullsOrdering.LAST) {
+			comparison = -1; // nulls last (b is null, so a comes first)
+		} else if (nullsOrdering === NullsOrdering.FIRST) {
+			comparison = 1; // nulls first (b is null, so b comes first)
+		} else {
+			// Default behavior: nulls first for ASC, nulls last for DESC
+			comparison = direction === SortDirection.DESC ? -1 : 1;
+		}
+	}
+
+	// Apply DESC direction (branchless when direction is ASC)
+	return direction === SortDirection.DESC ? -comparison : comparison;
+}
+
+/**
+ * Compares two SQL values with ORDER BY semantics including direction and NULL ordering.
+ * This consolidates the comparison logic used by both sort and window operations.
+ *
+ * @param a First value
+ * @param b Second value
+ * @param direction Sort direction ('asc' or 'desc')
+ * @param nullsOrdering Explicit NULLS ordering ('first', 'last', or undefined for default)
+ * @param collationName The collation to use for text comparison (defaults to BINARY)
+ * @returns -1 if a < b, 0 if a === b, 1 if a > b (after applying direction and null ordering)
+ */
+export function compareWithOrderBy(
+	a: SqlValue,
+	b: SqlValue,
+	direction: 'asc' | 'desc' = 'asc',
+	nullsOrdering?: 'first' | 'last',
+	collationName: string = 'BINARY'
+): number {
+	// Convert to optimized flags and use fast path
+	const directionFlag = direction === 'desc' ? SortDirection.DESC : SortDirection.ASC;
+	const nullsFlag = nullsOrdering === 'first' ? NullsOrdering.FIRST :
+	                  nullsOrdering === 'last' ? NullsOrdering.LAST :
+	                  NullsOrdering.DEFAULT;
+	const collationFunc = collationName === 'BINARY' ? BINARY_COLLATION : resolveCollation(collationName);
+
+	return compareWithOrderByFast(a, b, directionFlag, nullsFlag, collationFunc);
+}
+
+/**
+ * Factory function to create optimized comparison functions for repeated use.
+ * Pre-resolves collation and converts string flags to numeric for maximum performance.
+ *
+ * @param direction Sort direction ('asc' or 'desc')
+ * @param nullsOrdering Explicit NULLS ordering ('first', 'last', or undefined for default)
+ * @param collationName The collation to use for text comparison (defaults to BINARY)
+ * @returns An optimized comparison function
+ */
+export function createOrderByComparator(
+	direction: 'asc' | 'desc' = 'asc',
+	nullsOrdering?: 'first' | 'last',
+	collationName: string = 'BINARY'
+): (a: SqlValue, b: SqlValue) => number {
+	const collationFunc = collationName === 'BINARY' ? BINARY_COLLATION : resolveCollation(collationName);
+	return createOrderByComparatorFast(direction, nullsOrdering, collationFunc);
+}
+
+/**
+ * Optimized factory function that takes a pre-resolved collation function.
+ * This is the most efficient option when the collation function is already available.
+ *
+ * @param direction Sort direction ('asc' or 'desc')
+ * @param nullsOrdering Explicit NULLS ordering ('first', 'last', or undefined for default)
+ * @param collationFunc Pre-resolved collation function
+ * @returns An optimized comparison function
+ */
+export function createOrderByComparatorFast(
+	direction: 'asc' | 'desc' = 'asc',
+	nullsOrdering?: 'first' | 'last',
+	collationFunc: CollationFunction = BINARY_COLLATION
+): (a: SqlValue, b: SqlValue) => number {
+	const directionFlag = direction === 'desc' ? SortDirection.DESC : SortDirection.ASC;
+	const nullsFlag = nullsOrdering === 'first' ? NullsOrdering.FIRST :
+	                  nullsOrdering === 'last' ? NullsOrdering.LAST :
+	                  NullsOrdering.DEFAULT;
+
+	// Return a closure that captures the pre-resolved values
+	return (a: SqlValue, b: SqlValue): number => {
+		return compareWithOrderByFast(a, b, directionFlag, nullsFlag, collationFunc);
+	};
+}
+
+/**
+ * Determines if a SqlValue is truthy for filter purposes.
+ * In SQL semantics:
+ * - NULL is falsy
+ * - 0 (number) is falsy
+ * - Empty string is falsy
+ * - false (boolean) is falsy
+ * - Everything else is truthy
+ */
+export function isTruthy(value: SqlValue): boolean {
+	return (typeof value === 'string') ? value.length > 0 : !!value;
+}
+/**
+ * Compares two rows for SQL DISTINCT semantics.
+ * Returns -1, 0, or 1 for BTree ordering.
+ */
+export function compareRows(a: Row, b: Row): number {
+	// Let's assume correct rows
+	// if (a.length !== b.length) {
+	// 	return a.length - b.length;
+	// }
+	// Compare each value using SQL semantics
+	for (let i = 0; i < a.length; i++) {
+		const comparison = compareSqlValues(a[i], b[i]);
+		if (comparison !== 0) {
+			return comparison;
+		}
+	}
+	return 0;
+}
+
+// TODO: The main remaining task for comparison is implementing SQLite's
+// type affinity rules (which affect how values are treated BEFORE comparison)
+// and handling different TEXT collations.

package/src/util/environment.ts

@@ -0,0 +1,52 @@
+/**
+ * Cross-platform environment variable utilities
+ * Works in Node.js, browsers, and React Native
+ */
+
+import { createLogger } from '../common/logger.js';
+
+/**
+ * Cross-platform environment variable accessor
+ * Works in Node.js, browsers, and React Native
+ *
+ * @param key The environment variable name
+ * @returns The environment variable value or undefined if not found
+ */
+export function getEnvVar(key: string): string | undefined {
+	// Node.js environment
+	if (typeof process !== 'undefined' && process.env) {
+		return process.env[key];
+	}
+
+	// Browser environment - check if globalThis has the variable
+	// This allows setting environment variables like: globalThis.DEBUG = "quereus:*"
+	if (typeof globalThis !== 'undefined' && (globalThis as any)[key]) {
+		return (globalThis as any)[key];
+	}
+
+	// React Native or other environments might set environment variables differently
+	// For now, return undefined for unsupported environments
+	return undefined;
+}
+
+/**
+ * Check if debug logging is enabled for a specific namespace
+ * Uses the debug library's own enabled property via createLogger
+ *
+ * @param namespace The debug namespace to check (without the 'quereus:' prefix)
+ * @returns true if debug logging is enabled for the namespace
+ */
+export function isDebugEnabled(namespace: string): boolean {
+	const logger = createLogger(namespace);
+	return logger.enabled;
+}
+
+/**
+ * Check if a feature flag is enabled
+ *
+ * @param flagName The feature flag name
+ * @returns true if the flag is set to 'true'
+ */
+export function isFeatureEnabled(flagName: string): boolean {
+	return getEnvVar(flagName) === 'true';
+}

package/src/util/latches.ts

@@ -0,0 +1,47 @@
+/**
+ * Lightweight implementation of a mutex lock queue for managing concurrent access.
+ */
+export class Latches {
+	// Stores the promise representing the completion of the last queued operation for a key.
+	private static lockQueues = new Map<string, Promise<void>>();
+
+	/**
+	 * Acquires a lock for the given key. Waits if another operation holds the lock.
+	 * Returns a release function that must be called to release the lock.
+	 *
+	 * @param key A unique string identifier for the resource to lock.
+	 *            Should use `ClassName.methodName:${id}` format to avoid conflicts.
+	 * @returns A function that must be called to release the lock
+	 */
+	static async acquire(key: string): Promise<() => void> {
+		// Get the promise the current operation needs to wait for (if any)
+		const currentTail = this.lockQueues.get(key) ?? Promise.resolve();
+
+		let resolveNewTail!: () => void;
+		// Create the promise that the *next* operation will wait for
+		const newTail = new Promise<void>(resolve => {
+			resolveNewTail = resolve;
+		});
+
+		// Immediately set the new promise as the tail for this key
+		this.lockQueues.set(key, newTail);
+
+		// Wait for the previous operation (if any) to complete
+		await currentTail;
+
+		// Return the function to release *this* lock
+		const release = () => {
+			// Signal that this operation is complete
+			resolveNewTail();
+
+			// If this promise is still the current tail in the map,
+			// it means no other operation queued up behind this one while it was running.
+			// We can safely remove the entry from the map to prevent unbounded growth.
+			if (this.lockQueues.get(key) === newTail) {
+				this.lockQueues.delete(key);
+			}
+		};
+
+		return release;
+	}
+}