@quereus/quereus 0.7.2 → 0.7.4

package/src/util/hash.ts

@@ -1,90 +0,0 @@
-/**
- * Hash and encoding utilities
- */
-
-/**
- * Computes FNV-1a hash of a string (64-bit variant)
- * Returns an 8-byte array representing the hash
- * 
- * FNV-1a is a fast, non-cryptographic hash function with good distribution.
- * See: http://www.isthe.com/chongo/tech/comp/fnv/
- */
-export function fnv1aHash(str: string): Uint8Array {
-	// FNV-1a 64-bit parameters
-	// Using two 32-bit integers to represent 64-bit hash (JavaScript limitation)
-	let hashHigh = 0xcbf29ce4; // Upper 32 bits of FNV offset basis
-	let hashLow = 0x84222325;  // Lower 32 bits of FNV offset basis
-	
-	const fnvPrimeHigh = 0x00000100; // Upper 32 bits of FNV prime
-	const fnvPrimeLow = 0x000001b3;  // Lower 32 bits of FNV prime
-
-	for (let i = 0; i < str.length; i++) {
-		const charCode = str.charCodeAt(i);
-		
-		// XOR with byte (handle multi-byte characters)
-		hashLow ^= charCode & 0xff;
-		
-		// Multiply by FNV prime (64-bit multiplication using 32-bit parts)
-		const aHigh = hashHigh;
-		const aLow = hashLow;
-		
-		hashLow = (aLow * fnvPrimeLow) >>> 0;
-		hashHigh = (aHigh * fnvPrimeLow + aLow * fnvPrimeHigh + (hashLow / 0x100000000)) >>> 0;
-		hashLow = hashLow >>> 0;
-		
-		// Handle high byte of character if present
-		if (charCode > 0xff) {
-			hashLow ^= (charCode >>> 8) & 0xff;
-			const bHigh = hashHigh;
-			const bLow = hashLow;
-			hashLow = (bLow * fnvPrimeLow) >>> 0;
-			hashHigh = (bHigh * fnvPrimeLow + bLow * fnvPrimeHigh + (hashLow / 0x100000000)) >>> 0;
-			hashLow = hashLow >>> 0;
-		}
-	}
-
-	// Convert to 8-byte array
-	const bytes = new Uint8Array(8);
-	bytes[0] = (hashHigh >>> 24) & 0xff;
-	bytes[1] = (hashHigh >>> 16) & 0xff;
-	bytes[2] = (hashHigh >>> 8) & 0xff;
-	bytes[3] = hashHigh & 0xff;
-	bytes[4] = (hashLow >>> 24) & 0xff;
-	bytes[5] = (hashLow >>> 16) & 0xff;
-	bytes[6] = (hashLow >>> 8) & 0xff;
-	bytes[7] = hashLow & 0xff;
-	
-	return bytes;
-}
-
-/**
- * Converts a byte array to base64url encoding
- * (URL-safe base64 without padding: uses - and _ instead of + and /, no = padding)
- * 
- * Base64url is defined in RFC 4648 Section 5.
- */
-export function toBase64Url(bytes: Uint8Array): string {
-	const base64Chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_';
-	let result = '';
-	
-	for (let i = 0; i < bytes.length; i += 3) {
-		// Get 3 bytes (24 bits) and convert to 4 base64 characters (6 bits each)
-		const byte1 = bytes[i];
-		const byte2 = i + 1 < bytes.length ? bytes[i + 1] : 0;
-		const byte3 = i + 2 < bytes.length ? bytes[i + 2] : 0;
-		
-		const triplet = (byte1 << 16) | (byte2 << 8) | byte3;
-		
-		result += base64Chars[(triplet >>> 18) & 0x3f];
-		result += base64Chars[(triplet >>> 12) & 0x3f];
-		if (i + 1 < bytes.length) {
-			result += base64Chars[(triplet >>> 6) & 0x3f];
-		}
-		if (i + 2 < bytes.length) {
-			result += base64Chars[triplet & 0x3f];
-		}
-	}
-	
-	return result;
-}
-

package/src/util/latches.ts

@@ -1,47 +0,0 @@
-/**
- * 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;
-	}
-}

package/src/util/mutation-statement.ts

@@ -1,135 +0,0 @@
-import type { Row, SqlValue } from '../common/types.js';
-import type { TableSchema } from '../schema/table.js';
-import type * as AST from '../parser/ast.js';
-import { insertToString, updateToString, deleteToString } from './ast-stringify.js';
-
-/**
- * Builds a deterministic INSERT statement for mutation logging.
- * Creates an AST and uses insertToString for consistency.
- */
-export function buildInsertStatement(
-	tableSchema: TableSchema,
-	newRow: Row,
-	contextRow?: Row
-): string {
-	// Build INSERT AST
-	const stmt: AST.InsertStmt = {
-		type: 'insert',
-		table: { type: 'identifier', name: tableSchema.name },
-		columns: tableSchema.columns.map(col => col.name),
-		values: [newRow.map(sqlValueToLiteralExpr)],
-		contextValues: buildContextAssignments(tableSchema, contextRow)
-	};
-
-	return insertToString(stmt);
-}
-
-/**
- * Builds a deterministic UPDATE statement for mutation logging.
- */
-export function buildUpdateStatement(
-	tableSchema: TableSchema,
-	newRow: Row,
-	oldKeyValues: Row,
-	contextRow?: Row
-): string {
-	const pkDef = tableSchema.primaryKeyDefinition;
-
-	// Build UPDATE AST
-	const stmt: AST.UpdateStmt = {
-		type: 'update',
-		table: { type: 'identifier', name: tableSchema.name },
-		contextValues: buildContextAssignments(tableSchema, contextRow),
-		assignments: tableSchema.columns.map((col, idx) => ({
-			column: col.name,
-			value: sqlValueToLiteralExpr(newRow[idx])
-		})),
-		where: buildWhereClause(pkDef, oldKeyValues, tableSchema)
-	};
-
-	return updateToString(stmt);
-}
-
-/**
- * Builds a deterministic DELETE statement for mutation logging.
- */
-export function buildDeleteStatement(
-	tableSchema: TableSchema,
-	oldKeyValues: Row,
-	contextRow?: Row
-): string {
-	const pkDef = tableSchema.primaryKeyDefinition;
-
-	// Build DELETE AST
-	const stmt: AST.DeleteStmt = {
-		type: 'delete',
-		table: { type: 'identifier', name: tableSchema.name },
-		contextValues: buildContextAssignments(tableSchema, contextRow),
-		where: buildWhereClause(pkDef, oldKeyValues, tableSchema)
-	};
-
-	return deleteToString(stmt);
-}
-
-/**
- * Converts a SqlValue to a LiteralExpr AST node.
- */
-function sqlValueToLiteralExpr(value: SqlValue): AST.LiteralExpr {
-	return {
-		type: 'literal',
-		value: value
-	};
-}
-
-/**
- * Builds context assignments from context row values.
- */
-function buildContextAssignments(
-	tableSchema: TableSchema,
-	contextRow?: Row
-): AST.ContextAssignment[] | undefined {
-	if (!contextRow || contextRow.length === 0 || !tableSchema.mutationContext) {
-		return undefined;
-	}
-
-	return tableSchema.mutationContext.map((ctx, idx) => ({
-		name: ctx.name,
-		value: sqlValueToLiteralExpr(contextRow[idx])
-	}));
-}
-
-/**
- * Builds a WHERE clause for primary key matching.
- * Returns an AND expression of pk_col = value for each PK column.
- */
-function buildWhereClause(
-	pkDef: TableSchema['primaryKeyDefinition'],
-	keyValues: Row,
-	tableSchema: TableSchema
-): AST.Expression {
-	const conditions: AST.Expression[] = pkDef.map((pkCol, idx) => ({
-		type: 'binary' as const,
-		operator: '=' as const,
-		left: { type: 'column' as const, name: tableSchema.columns[pkCol.index].name },
-		right: sqlValueToLiteralExpr(keyValues[idx])
-	}));
-
-	if (conditions.length === 0) {
-		// Table has no primary key - return a tautology (WHERE 1)
-		// Note: UPDATE/DELETE without row identification will affect all rows
-		return { type: 'literal', value: 1 };
-	}
-
-	if (conditions.length === 1) {
-		return conditions[0];
-	}
-
-	// Build nested AND expressions: (a AND b) AND c AND ...
-	return conditions.reduce((acc, cond) => ({
-		type: 'binary' as const,
-		operator: 'and' as const,
-		left: acc,
-		right: cond
-	}));
-}
-

package/src/util/patterns.ts

@@ -1,56 +0,0 @@
-import { createLogger } from '../common/logger.js';
-
-const log = createLogger('util:patterns');
-const errorLog = log.extend('error');
-
-/**
- * Simple LIKE pattern matching implementation.
- * Supports SQL LIKE patterns:
- * - % matches any sequence of characters (including empty sequence)
- * - _ matches any single character
- *
- * @param pattern The LIKE pattern
- * @param text The text to match against
- * @returns true if the text matches the pattern, false otherwise
- */
-export function simpleLike(pattern: string, text: string): boolean {
-	// Escape regex special characters except % and _
-	const escapedPattern = pattern.replace(/[.*+^${}()|[\]\\]/g, '\\$&');
-	// Convert SQL LIKE wildcards to regex equivalents
-	const regexPattern = escapedPattern.replace(/%/g, '.*').replace(/_/g, '.');
-
-	try {
-		const regex = new RegExp(`^${regexPattern}$`);
-		return regex.test(text);
-	} catch (e) {
-		errorLog('Invalid LIKE pattern converted to regex: ^%s$, %O', regexPattern, e);
-		return false;
-	}
-}
-
-/**
- * Simple GLOB pattern matching implementation.
- * Supports SQL GLOB patterns:
- * - * matches any sequence of characters (including empty sequence)
- * - ? matches any single character
- *
- * @param pattern The GLOB pattern
- * @param text The text to match against
- * @returns true if the text matches the pattern, false otherwise
- */
-export function simpleGlob(pattern: string, text: string): boolean {
-	// Escape regex special characters except * and ?
-	const escapedPattern = pattern.replace(/[.*+^${}()|[\]\\]/g, '\\$&');
-	// Convert SQL GLOB wildcards to regex equivalents
-	const regexPattern = escapedPattern
-		.replace(/\\\*/g, '.*')
-		.replace(/\\\?/g, '.');
-
-	try {
-		const regex = new RegExp(`^${regexPattern}$`);
-		return regex.test(text);
-	} catch (e) {
-		errorLog('Invalid GLOB pattern converted to regex: ^%s$, %O', regexPattern, e);
-		return false;
-	}
-}

package/src/util/plan-formatter.ts

@@ -1,48 +0,0 @@
-import type { ScalarPlanNode } from '../planner/nodes/plan-node.js';
-import { expressionToString } from './ast-stringify.js';
-import type { ScalarType } from '../common/datatype.js';
-import { SqlDataType } from '../common/types.js';
-
-/**
- * Convert a ScalarPlanNode to its string representation for use in plan descriptions.
- */
-export function formatExpression(node: ScalarPlanNode): string {
-	return expressionToString(node.expression);
-}
-
-/**
- * Convert multiple ScalarPlanNodes to a comma-separated string.
- */
-export function formatExpressionList(nodes: readonly ScalarPlanNode[]): string {
-	return nodes.map(formatExpression).join(', ');
-}
-
-/**
- * Format a scalar type to a simple string representation.
- */
-export function formatScalarType(type: ScalarType): string {
-	return type.logicalType.name;
-}
-
-/**
- * Format projection for display (expression with optional alias).
- */
-export function formatProjection(expr: ScalarPlanNode, alias?: string): string {
-	const exprStr = formatExpression(expr);
-	return alias && alias !== exprStr ? `${exprStr} AS ${alias}` : exprStr;
-}
-
-/**
- * Format sort key for display.
- */
-export function formatSortKey(
-	expr: ScalarPlanNode,
-	direction: 'asc' | 'desc',
-	nulls?: 'first' | 'last'
-): string {
-	const parts = [formatExpression(expr), direction.toUpperCase()];
-	if (nulls) {
-		parts.push(`NULLS ${nulls.toUpperCase()}`);
-	}
-	return parts.join(' ');
-}

package/src/util/plugin-helper.ts

@@ -1,110 +0,0 @@
-/**
- * Plugin registration helper for static plugin loading
- * 
- * This module provides utilities for registering plugins without dynamic imports,
- * which is useful for React Native and other environments where dynamic imports
- * are not supported.
- */
-
-import type { Database } from '../core/database.js';
-import type { PluginRegistrations } from '../vtab/manifest.js';
-import type { SqlValue } from '../common/types.js';
-
-/**
- * Plugin function type - what a plugin exports as its default export
- */
-export type PluginFunction = (
-	db: Database,
-	config?: Record<string, SqlValue>
-) => Promise<PluginRegistrations> | PluginRegistrations;
-
-/**
- * Register a plugin's components with the database.
- * 
- * This is a helper function for static plugin loading that handles calling
- * the plugin function and registering all returned components (vtables,
- * functions, collations, types) with the database.
- * 
- * @param db Database instance to register with
- * @param plugin Plugin function (the default export from a plugin module)
- * @param config Optional configuration object to pass to the plugin
- * 
- * @example
- * ```typescript
- * import { Database } from '@quereus/quereus';
- * import { registerPlugin } from '@quereus/quereus';
- * import myPlugin from './plugins/my-plugin';
- * 
- * const db = new Database();
- * await registerPlugin(db, myPlugin, { apiKey: 'secret' });
- * ```
- * 
- * @example
- * ```typescript
- * // Register multiple plugins
- * await registerPlugin(db, stringFunctions);
- * await registerPlugin(db, customCollations);
- * await registerPlugin(db, jsonTable, { cacheSize: 100 });
- * ```
- */
-export async function registerPlugin(
-	db: Database,
-	plugin: PluginFunction,
-	config: Record<string, SqlValue> = {}
-): Promise<void> {
-	// Call the plugin function to get registrations
-	const registrations = await plugin(db, config);
-
-	// Register virtual table modules
-	if (registrations.vtables) {
-		for (const vtable of registrations.vtables) {
-			try {
-				db.registerVtabModule(vtable.name, vtable.module, vtable.auxData);
-			} catch (error) {
-				throw new Error(
-					`Failed to register vtable module '${vtable.name}': ${error instanceof Error ? error.message : String(error)}`
-				);
-			}
-		}
-	}
-
-	// Register functions
-	if (registrations.functions) {
-		for (const func of registrations.functions) {
-			try {
-				db.registerFunction(func.schema);
-			} catch (error) {
-				throw new Error(
-					`Failed to register function '${func.schema.name}/${func.schema.numArgs}': ${error instanceof Error ? error.message : String(error)}`
-				);
-			}
-		}
-	}
-
-	// Register collations
-	if (registrations.collations) {
-		for (const collation of registrations.collations) {
-			try {
-				db.registerCollation(collation.name, collation.func);
-			} catch (error) {
-				throw new Error(
-					`Failed to register collation '${collation.name}': ${error instanceof Error ? error.message : String(error)}`
-				);
-			}
-		}
-	}
-
-	// Register types
-	if (registrations.types) {
-		for (const type of registrations.types) {
-			try {
-				db.registerType(type.name, type.definition);
-			} catch (error) {
-				throw new Error(
-					`Failed to register type '${type.name}': ${error instanceof Error ? error.message : String(error)}`
-				);
-			}
-		}
-	}
-}
-

package/src/util/row-descriptor.ts

@@ -1,105 +0,0 @@
-import type { RowDescriptor, Attribute } from '../planner/nodes/plan-node.js';
-import type { Row } from '../common/types.js';
-import { TEXT_TYPE } from '../types/builtin-types.js';
-
-/**
- * Utility to build a RowDescriptor (attributeId → columnIndex mapping)
- * for any relational plan node.
- */
-export function buildRowDescriptor(attributes: readonly Attribute[]): RowDescriptor {
-  const descriptor: RowDescriptor = [];
-  attributes.forEach((attr, index) => {
-    descriptor[attr.id] = index;
-  });
-  return descriptor;
-}
-
-/**
- * Creates OLD and NEW row descriptors for mutation operations.
- * Returns descriptors where OLD columns are at indices 0..n-1 and NEW columns at n..2n-1
- */
-export function buildOldNewRowDescriptors(
-	oldAttributes: Attribute[],
-	newAttributes: Attribute[]
-): {
-	oldRowDescriptor: RowDescriptor;
-	newRowDescriptor: RowDescriptor;
-	flatRowDescriptor: RowDescriptor;
-} {
-	const oldRowDescriptor: RowDescriptor = [];
-	const newRowDescriptor: RowDescriptor = [];
-	const flatRowDescriptor: RowDescriptor = [];
-
-	// OLD attributes occupy indices 0..n-1
-	oldAttributes.forEach((attr, index) => {
-		oldRowDescriptor[attr.id] = index;
-		flatRowDescriptor[attr.id] = index;
-	});
-
-	// NEW attributes occupy indices n..2n-1
-	newAttributes.forEach((attr, index) => {
-		const flatIndex = oldAttributes.length + index;
-		newRowDescriptor[attr.id] = index;
-		flatRowDescriptor[attr.id] = flatIndex;
-	});
-
-	return { oldRowDescriptor, newRowDescriptor, flatRowDescriptor };
-}
-
-/**
- * Composes a flat row from OLD and NEW row values.
- * Result format: [oldCol0, oldCol1, ..., oldColN, newCol0, newCol1, ..., newColN]
- */
-export function composeOldNewRow(oldRow: Row | null, newRow: Row | null, columnCount: number): Row {
-	const flatRow: Row = new Array(columnCount * 2);
-
-	// Fill OLD section (indices 0..n-1)
-	for (let i = 0; i < columnCount; i++) {
-		flatRow[i] = oldRow ? oldRow[i] : null;
-	}
-
-	// Fill NEW section (indices n..2n-1)
-	for (let i = 0; i < columnCount; i++) {
-		flatRow[columnCount + i] = newRow ? newRow[i] : null;
-	}
-
-	return flatRow;
-}
-
-/**
- * Extracts NEW values from a flat OLD/NEW row
- */
-export function extractNewRowFromFlat(flatRow: Row, columnCount: number): Row {
-	return flatRow.slice(columnCount, columnCount * 2);
-}
-
-/**
- * Extracts OLD values from a flat OLD/NEW row
- */
-export function extractOldRowFromFlat(flatRow: Row, columnCount: number): Row {
-	return flatRow.slice(0, columnCount);
-}
-
-/**
- * Helper to build Attribute array from flatRowDescriptor for DML nodes.
- * This is used by UpdateNode and DeleteNode to expose their flat row layout.
- */
-export function buildAttributesFromFlatDescriptor(flatRowDescriptor: RowDescriptor): Attribute[] {
-	const attributes: Attribute[] = [];
-	for (const attrIdStr in flatRowDescriptor) {
-		const attrId = parseInt(attrIdStr);
-		const index = flatRowDescriptor[attrId];
-		attributes[index] = {
-			id: attrId,
-			name: `attr_${attrId}`,
-			type: {
-				typeClass: 'scalar' as const,
-				logicalType: TEXT_TYPE,
-				nullable: true,
-				isReadOnly: false
-			},
-			sourceRelation: 'unknown'
-		};
-	}
-	return attributes;
-}

package/src/util/serialization.ts

@@ -1,47 +0,0 @@
-/**
- * Utility functions for safe serialization, particularly handling BigInt and Uint8Arrays.
- */
-
-/* eslint-disable @typescript-eslint/no-explicit-any */
-import { createLogger } from '../common/logger.js';
-
-const log = createLogger('util:serialization');
-const errorLog = log.extend('error');
-
-export function jsonStringify(obj: any, space?: string | number): string {
-  return JSON.stringify(
-		obj,
-		(_, value) => {
-			if (typeof value === 'bigint') {
-				// Convert to number if it's within safe integer limits for JSON
-				if (value >= BigInt(Number.MIN_SAFE_INTEGER) && value <= BigInt(Number.MAX_SAFE_INTEGER)) {
-					return Number(value);
-				}
-				// Otherwise, convert to string (without 'n' suffix for standard JSON)
-				return value.toString();
-			} else if (value instanceof Uint8Array) {
-				return `0x${Buffer.from(value).toString('hex')}`; // Keep existing Uint8Array handling
-			}
-			return value;
-		},
-		space
-	);
-}
-
-/**
- * Safely stringifies an object to JSON, converting BigInts to strings
- * ending with 'n' to avoid serialization errors.
- *
- * @param obj The object to stringify.
- * @param space Optional spacing argument for JSON.stringify.
- * @returns JSON string representation.
- */
-export function safeJsonStringify(obj: any, space?: string | number): string {
-  try {
-    return jsonStringify(obj, space);
-  } catch (e) {
-    // Fallback in case of unexpected stringify errors
-    errorLog("safeJsonStringify failed:", e);
-    return `[Unserializable Object: ${e instanceof Error ? e.message : String(e)}]`;
-  }
-}

package/src/util/sql-literal.ts

@@ -1,22 +0,0 @@
-import type { SqlValue } from '../common/types.js';
-import { expressionToString } from './ast-stringify.js';
-import type * as AST from '../parser/ast.js';
-
-/**
- * Converts a SqlValue to its SQL literal string representation.
- * This is used for mutation logging to create deterministic, replayable SQL statements.
- * Uses the existing expressionToString function for consistency.
- *
- * @param value The value to convert to a SQL literal
- * @returns SQL literal string representation
- */
-export function sqlValueToLiteral(value: SqlValue): string {
-	// Create a literal expression AST node and use expressionToString
-	const literalExpr: AST.LiteralExpr = {
-		type: 'literal',
-		value: value
-	};
-
-	return expressionToString(literalExpr);
-}
-