@quereus/quereus 0.2.0 → 0.4.0

package/src/util/environment.ts

@@ -20,8 +20,8 @@ export function getEnvVar(key: string): string | undefined {
 
 	// 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];
+	if (typeof globalThis !== 'undefined' && (globalThis as Record<string, unknown>)[key]) {
+		return (globalThis as Record<string, unknown>)[key] as string;
 	}
 
 	// React Native or other environments might set environment variables differently

package/src/util/plugin-loader.ts

@@ -141,3 +141,187 @@ export function validatePluginUrl(url: string): boolean {
 }
 
 
+/** Loader options for loadPlugin */
+export interface LoadPluginOptions {
+    /**
+     * Environment hint. Defaults to auto-detection.
+     * 'browser' enables optional CDN resolution when allowCdn is true.
+     */
+    env?: 'auto' | 'browser' | 'node';
+    /**
+     * Allow resolving npm: specs to a public CDN in browser contexts.
+     * Disabled by default (opt-in).
+     */
+    allowCdn?: boolean;
+    /** Which CDN to use when allowCdn is true. Defaults to 'jsdelivr'. */
+    cdn?: 'jsdelivr' | 'unpkg' | 'esm.sh';
+}
+
+/**
+ * High-level plugin loader that accepts npm specs or direct URLs.
+ *
+ * Examples:
+ * - npm:@scope/quereus-plugin-foo@^1
+ * - @scope/quereus-plugin-foo (npm package name)
+ * - https://raw.githubusercontent.com/user/repo/main/plugin.js
+ * - file:///path/to/plugin.js (Node only)
+ */
+export async function loadPlugin(
+    spec: string,
+    db: Database,
+    config: Record<string, SqlValue> = {},
+    options: LoadPluginOptions = {}
+): Promise<PluginManifest | undefined> {
+    const env = options.env && options.env !== 'auto' ? options.env : (isBrowserEnv() ? 'browser' : 'node');
+
+    // Direct URL or file path via dynamicLoadModule
+    if (isUrlLike(spec)) {
+        return await dynamicLoadModule(spec, db, config);
+    }
+
+    // Interpret as npm spec or bare package name
+    const npm = parseNpmSpec(spec);
+    if (!npm) {
+        quereusError(`Invalid plugin spec: ${spec}. Use a URL, file://, or npm package (e.g., npm:@scope/name@version).`, StatusCode.FORMAT);
+    }
+
+    if (env === 'node') {
+        // Resolve using Node ESM resolution. Prefer exported subpath './plugin'.
+        const subpathImport = `${npm.name}/plugin${npm.subpath ?? ''}`;
+        const candidates = [subpathImport, `${npm.name}${npm.subpath ?? ''}`];
+
+        let mod: PluginModule | undefined;
+        let lastErr: unknown = undefined;
+        for (const target of candidates) {
+            try {
+                mod = await import(/* @vite-ignore */ target) as PluginModule;
+                break;
+            } catch (e) {
+                lastErr = e;
+            }
+        }
+
+        if (!mod) {
+            quereusError(
+                `Failed to resolve plugin package '${npm.name}'. Ensure it exports './plugin' or a default module. Last error: ${lastErr instanceof Error ? lastErr.message : String(lastErr)}`
+            );
+        }
+
+        if (typeof mod.default !== 'function') {
+            quereusError(`Resolved module for '${npm.name}' has no default export function`, StatusCode.FORMAT);
+        }
+
+        const registrations = await mod.default(db, config);
+        await registerPluginItems(db, registrations);
+        log('Successfully loaded plugin from package %s', npm.name);
+        if (registrations.vtables?.length) {
+            log('  Registered %d vtable module(s): %s', registrations.vtables.length, 
+                registrations.vtables.map(v => v.name).join(', '));
+        }
+        if (registrations.functions?.length) {
+            log('  Registered %d function(s): %s', registrations.functions.length,
+                registrations.functions.map(f => `${f.schema.name}/${f.schema.numArgs}`).join(', '));
+        }
+        if (registrations.collations?.length) {
+            log('  Registered %d collation(s): %s', registrations.collations.length,
+                registrations.collations.map(c => c.name).join(', '));
+        }
+        return mod.manifest;
+    }
+
+    // Browser path: npm spec requires CDN; only if explicitly allowed
+    if (!options.allowCdn) {
+        quereusError(
+            `Loading npm packages in the browser requires allowCdn=true. Received spec '${spec}'. ` +
+            `Either provide a direct https:// URL to the ESM plugin or enable CDN resolution.`,
+            StatusCode.MISUSE
+        );
+    }
+
+    const cdnUrl = toCdnUrl(npm, options.cdn ?? 'jsdelivr');
+    return await dynamicLoadModule(cdnUrl, db, config);
+}
+
+function isBrowserEnv(): boolean {
+    // Heuristic: presence of document on globalThis implies browser
+    return typeof globalThis !== 'undefined' && typeof (globalThis as unknown as { document?: unknown }).document !== 'undefined';
+}
+
+function isUrlLike(s: string): boolean {
+    try {
+        const u = new URL(s);
+        return u.protocol === 'https:' || u.protocol === 'http:' || u.protocol === 'file:';
+    } catch {
+        return false;
+    }
+}
+
+interface NpmSpec {
+    name: string; // @scope/pkg or pkg
+    version?: string; // optional semver or tag
+    subpath?: string; // optional subpath after package root (rarely used)
+}
+
+function parseNpmSpec(input: string): NpmSpec | null {
+    // Remove optional npm: prefix
+    const raw = input.startsWith('npm:') ? input.slice(4) : input;
+
+    // Quick reject if contains spaces or empty
+    if (!raw || /\s/.test(raw)) return null;
+
+    // Support patterns like:
+    // @scope/name@1.2.3/path   name@^1  name  name/path
+    // Split off subpath (first '/' that is not part of scope)
+    let nameAndVersion = raw;
+    let subpath: string | undefined;
+    if (raw.startsWith('@')) {
+        // Scoped: look for second '/'
+        const secondSlash = raw.indexOf('/', raw.indexOf('/') + 1);
+        if (secondSlash !== -1) {
+            nameAndVersion = raw.slice(0, secondSlash);
+            subpath = raw.slice(secondSlash);
+        }
+    } else {
+        const firstSlash = raw.indexOf('/');
+        if (firstSlash !== -1) {
+            nameAndVersion = raw.slice(0, firstSlash);
+            subpath = raw.slice(firstSlash);
+        }
+    }
+
+    // Now split name@version
+    const atIndex = nameAndVersion.lastIndexOf('@');
+    if (nameAndVersion.startsWith('@')) {
+        // Scoped: the first '@' is part of the scope
+        if (atIndex > 0) {
+            const name = nameAndVersion.slice(0, atIndex);
+            const version = nameAndVersion.slice(atIndex + 1) || undefined;
+            return { name, version, subpath };
+        }
+        return { name: nameAndVersion, subpath };
+    } else {
+        if (atIndex > 0) {
+            const name = nameAndVersion.slice(0, atIndex);
+            const version = nameAndVersion.slice(atIndex + 1) || undefined;
+            return { name, version, subpath };
+        }
+        return { name: nameAndVersion, subpath };
+    }
+}
+
+function toCdnUrl(spec: NpmSpec, cdn: 'jsdelivr' | 'unpkg' | 'esm.sh'): string {
+    const versionSegment = spec.version ? `@${spec.version}` : '';
+    const subpath = spec.subpath ? spec.subpath.replace(/^\//, '') : 'plugin';
+    switch (cdn) {
+        case 'unpkg':
+            return `https://unpkg.com/${spec.name}${versionSegment}/${subpath}`;
+        case 'esm.sh':
+            // esm.sh expects ?path=/subpath or direct subpath after package
+            // Use direct subpath; esm.sh will transform to ESM
+            return `https://esm.sh/${spec.name}${versionSegment}/${subpath}`;
+        case 'jsdelivr':
+        default:
+            return `https://cdn.jsdelivr.net/npm/${spec.name}${versionSegment}/${subpath}`;
+    }
+}
+

package/src/util/row-descriptor.ts

@@ -6,7 +6,7 @@ import { SqlDataType } from '../common/types.js';
  * Utility to build a RowDescriptor (attributeId → columnIndex mapping)
  * for any relational plan node.
  */
-export function buildRowDescriptor(attributes: Attribute[]): RowDescriptor {
+export function buildRowDescriptor(attributes: readonly Attribute[]): RowDescriptor {
   const descriptor: RowDescriptor = [];
   attributes.forEach((attr, index) => {
     descriptor[attr.id] = index;

package/src/util/serialization.ts

@@ -1,6 +1,8 @@
 /**
  * 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');

package/src/vtab/best-access-plan.ts

@@ -3,13 +3,14 @@
  * Provides better type safety, clearer intent, and extensibility for future optimizations
  */
 
+/* eslint-disable @typescript-eslint/no-explicit-any */
 import { quereusError } from '../common/errors.js';
 import { StatusCode, type SqlDataType, type SqlValue } from '../common/types.js';
 
 /**
  * Constraint operators that can be pushed down to virtual tables
  */
-export type ConstraintOp = '=' | '>' | '>=' | '<' | '<=' | 'MATCH' | 'LIKE' | 'GLOB' | 'IS NULL' | 'IS NOT NULL';
+export type ConstraintOp = '=' | '>' | '>=' | '<' | '<=' | 'MATCH' | 'LIKE' | 'GLOB' | 'IS NULL' | 'IS NOT NULL' | 'IN' | 'NOT IN';
 
 /**
  * Column metadata provided to virtual tables for planning

package/src/vtab/manifest.ts

@@ -1,3 +1,4 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
 import type { SqlValue } from '../common/types.js';
 import type { FunctionSchema } from '../schema/function.js';
 import type { CollationFunction } from '../util/comparison.js';

package/src/vtab/memory/index.ts

@@ -1,178 +1,178 @@
-import { BTree } from 'inheritree';
-import { StatusCode, type Row, type SqlValue } from '../../common/types.js';
-import { compareSqlValues } from '../../util/comparison.js';
-import type { BTreeKeyForPrimary, BTreeKeyForIndex, MemoryIndexEntry } from './types.js';
-import type { IndexColumnSchema as IndexColumnSpec } from '../../schema/table.js'; // Renamed for clarity
-import type { ColumnSchema } from '../../schema/column.js';
-import { quereusError } from '../../common/errors.js';
-
-/** Definition for creating a memory index (matches IndexSchema columns usually) */
-export interface IndexSpec {
-	name?: string;
-	columns: ReadonlyArray<IndexColumnSpec>;
-}
-
-/** Functions for extracting and comparing index keys */
-interface IndexKeyFunctions {
-	keyFromRow: (row: Row) => BTreeKeyForIndex;
-	compareKeys: (a: BTreeKeyForIndex, b: BTreeKeyForIndex) => number;
-}
-
-/** Represents a secondary index within a MemoryTable */
-export class MemoryIndex {
-	public readonly name: string | undefined;
-	public readonly specColumns: ReadonlyArray<IndexColumnSpec>;
-	public readonly keyFromRow: (row: Row) => BTreeKeyForIndex;
-	public readonly compareKeys: (a: BTreeKeyForIndex, b: BTreeKeyForIndex) => number;
-	public data: BTree<BTreeKeyForIndex, MemoryIndexEntry>;
-
-	constructor(spec: IndexSpec, allTableColumnsSchema: ReadonlyArray<ColumnSchema>, baseInheritreeTable?: BTree<BTreeKeyForIndex, MemoryIndexEntry>) {
-		this.name = spec.name;
-		this.specColumns = Object.freeze(spec.columns.map(c => ({ ...c })));
-
-		this.validateColumnIndexes(allTableColumnsSchema);
-
-		const keyFunctions = this.createIndexKeyFunctions();
-		this.keyFromRow = keyFunctions.keyFromRow;
-		this.compareKeys = keyFunctions.compareKeys;
-
-		this.data = this.createBTree(baseInheritreeTable);
-	}
-
-	private validateColumnIndexes(allTableColumnsSchema: ReadonlyArray<ColumnSchema>): void {
-		const hasInvalidIndex = this.specColumns.some(sc =>
-			sc.index < 0 || sc.index >= allTableColumnsSchema.length
-		);
-
-		if (hasInvalidIndex) {
-			quereusError(`Invalid column index in index '${this.name ?? '(unnamed)'}'.`, StatusCode.INTERNAL);
-		}
-	}
-
-	private createIndexKeyFunctions(): IndexKeyFunctions {
-		if (this.specColumns.length === 1) {
-			return this.createSingleColumnKeyFunctions();
-		} else {
-			return this.createCompositeColumnKeyFunctions();
-		}
-	}
-
-	private createSingleColumnKeyFunctions(): IndexKeyFunctions {
-		const specCol = this.specColumns[0];
-		const colSchemaIndex = specCol.index;
-		const collation = specCol.collation || 'BINARY';
-		const descMultiplier = specCol.desc ? -1 : 1;
-
-		const keyFromRow = (row: Row): BTreeKeyForIndex => {
-			this.validateRowLength(row, colSchemaIndex);
-			return row[colSchemaIndex];
-		};
-
-		const compareKeys = (a: BTreeKeyForIndex, b: BTreeKeyForIndex): number => {
-			return compareSqlValues(a as SqlValue, b as SqlValue, collation) * descMultiplier;
-		};
-
-		return { keyFromRow, compareKeys };
-	}
-
-	private createCompositeColumnKeyFunctions(): IndexKeyFunctions {
-		const localSpecColumns = this.specColumns;
-
-		const keyFromRow = (row: Row): BTreeKeyForIndex => {
-			return localSpecColumns.map(sc => {
-				this.validateRowLength(row, sc.index);
-				return row[sc.index];
-			});
-		};
-
-		const compareKeys = (a: BTreeKeyForIndex, b: BTreeKeyForIndex): number => {
-			const arrA = a as SqlValue[];
-			const arrB = b as SqlValue[];
-
-			for (let i = 0; i < localSpecColumns.length; i++) {
-				if (i >= arrA.length || i >= arrB.length) {
-					return arrA.length - arrB.length;
-				}
-
-				const specCol = localSpecColumns[i];
-				const comparison = compareSqlValues(arrA[i], arrB[i], specCol.collation || 'BINARY');
-
-				if (comparison !== 0) {
-					return specCol.desc ? -comparison : comparison;
-				}
-			}
-			return 0;
-		};
-
-		return { keyFromRow, compareKeys };
-	}
-
-	private validateRowLength(row: Row, columnIndex: number): void {
-		if (columnIndex < 0 || columnIndex >= row.length) {
-			quereusError(`Index key col index ${columnIndex} OOB for row len ${row.length}`, StatusCode.INTERNAL);
-		}
-	}
-
-	private createBTree(baseInheritreeTable?: BTree<BTreeKeyForIndex, MemoryIndexEntry>): BTree<BTreeKeyForIndex, MemoryIndexEntry> {
-		return new BTree<BTreeKeyForIndex, MemoryIndexEntry>(
-			(entry: MemoryIndexEntry) => entry.indexKey,
-			this.compareKeys,
-			baseInheritreeTable
-		);
-	}
-
-	/** Adds a mapping from index key to primary key */
-	addEntry(indexKey: BTreeKeyForIndex, primaryKey: BTreeKeyForPrimary): void {
-		const path = this.data.find(indexKey);
-		if (path.on) {
-			// Entry exists, add to the existing set of primary keys
-			const existingEntry = this.data.at(path)!;
-			existingEntry.primaryKeys.add(primaryKey);
-		} else {
-			// Create new entry with a Set containing the primary key
-			const newEntry: MemoryIndexEntry = {
-				indexKey,
-				primaryKeys: new Set([primaryKey])
-			};
-			this.data.insert(newEntry);
-		}
-	}
-
-	/** Removes a mapping from index key to primary key */
-	removeEntry(indexKey: BTreeKeyForIndex, primaryKey: BTreeKeyForPrimary): void {
-		const path = this.data.find(indexKey);
-		if (path.on) {
-			const entry = this.data.at(path)!;
-			entry.primaryKeys.delete(primaryKey);
-
-			// If no primary keys remain, remove the entire entry
-			if (entry.primaryKeys.size === 0) {
-				this.data.deleteAt(path);
-			}
-		}
-	}
-
-	/** Returns the primary keys for a given index key */
-	getPrimaryKeys(indexKey: BTreeKeyForIndex): BTreeKeyForPrimary[] {
-		const entry = this.data.get(indexKey);
-		return entry ? Array.from(entry.primaryKeys) : [];
-	}
-
-	/** Gets the count of unique index values */
-	get size(): number {
-		return this.data.getCount();
-	}
-
-	/** Clears all entries from the index */
-	clear(): void {
-		const base = (this.data as any).baseTable as BTree<BTreeKeyForIndex, MemoryIndexEntry> | undefined;
-		this.data = this.createBTree(base);
-	}
-
-	/** Clears the base inheritance for this index (used during layer collapse) */
-	clearBase(): void {
-		if (typeof (this.data as any).clearBase === 'function') {
-			(this.data as any).clearBase();
-		}
-	}
-}
+import { BTree } from 'inheritree';
+import { StatusCode, type Row, type SqlValue } from '../../common/types.js';
+import { compareSqlValues } from '../../util/comparison.js';
+import type { BTreeKeyForPrimary, BTreeKeyForIndex, MemoryIndexEntry } from './types.js';
+import type { IndexColumnSchema as IndexColumnSpec } from '../../schema/table.js'; // Renamed for clarity
+import type { ColumnSchema } from '../../schema/column.js';
+import { quereusError } from '../../common/errors.js';
+
+/** Definition for creating a memory index (matches IndexSchema columns usually) */
+export interface IndexSpec {
+	name?: string;
+	columns: ReadonlyArray<IndexColumnSpec>;
+}
+
+/** Functions for extracting and comparing index keys */
+interface IndexKeyFunctions {
+	keyFromRow: (row: Row) => BTreeKeyForIndex;
+	compareKeys: (a: BTreeKeyForIndex, b: BTreeKeyForIndex) => number;
+}
+
+/** Represents a secondary index within a MemoryTable */
+export class MemoryIndex {
+	public readonly name: string | undefined;
+	public readonly specColumns: ReadonlyArray<IndexColumnSpec>;
+	public readonly keyFromRow: (row: Row) => BTreeKeyForIndex;
+	public readonly compareKeys: (a: BTreeKeyForIndex, b: BTreeKeyForIndex) => number;
+	public data: BTree<BTreeKeyForIndex, MemoryIndexEntry>;
+
+	constructor(spec: IndexSpec, allTableColumnsSchema: ReadonlyArray<ColumnSchema>, baseInheritreeTable?: BTree<BTreeKeyForIndex, MemoryIndexEntry>) {
+		this.name = spec.name;
+		this.specColumns = Object.freeze(spec.columns.map(c => ({ ...c })));
+
+		this.validateColumnIndexes(allTableColumnsSchema);
+
+		const keyFunctions = this.createIndexKeyFunctions();
+		this.keyFromRow = keyFunctions.keyFromRow;
+		this.compareKeys = keyFunctions.compareKeys;
+
+		this.data = this.createBTree(baseInheritreeTable);
+	}
+
+	private validateColumnIndexes(allTableColumnsSchema: ReadonlyArray<ColumnSchema>): void {
+		const hasInvalidIndex = this.specColumns.some(sc =>
+			sc.index < 0 || sc.index >= allTableColumnsSchema.length
+		);
+
+		if (hasInvalidIndex) {
+			quereusError(`Invalid column index in index '${this.name ?? '(unnamed)'}'.`, StatusCode.INTERNAL);
+		}
+	}
+
+	private createIndexKeyFunctions(): IndexKeyFunctions {
+		if (this.specColumns.length === 1) {
+			return this.createSingleColumnKeyFunctions();
+		} else {
+			return this.createCompositeColumnKeyFunctions();
+		}
+	}
+
+	private createSingleColumnKeyFunctions(): IndexKeyFunctions {
+		const specCol = this.specColumns[0];
+		const colSchemaIndex = specCol.index;
+		const collation = specCol.collation || 'BINARY';
+		const descMultiplier = specCol.desc ? -1 : 1;
+
+		const keyFromRow = (row: Row): BTreeKeyForIndex => {
+			this.validateRowLength(row, colSchemaIndex);
+			return row[colSchemaIndex];
+		};
+
+		const compareKeys = (a: BTreeKeyForIndex, b: BTreeKeyForIndex): number => {
+			return compareSqlValues(a as SqlValue, b as SqlValue, collation) * descMultiplier;
+		};
+
+		return { keyFromRow, compareKeys };
+	}
+
+	private createCompositeColumnKeyFunctions(): IndexKeyFunctions {
+		const localSpecColumns = this.specColumns;
+
+		const keyFromRow = (row: Row): BTreeKeyForIndex => {
+			return localSpecColumns.map(sc => {
+				this.validateRowLength(row, sc.index);
+				return row[sc.index];
+			});
+		};
+
+		const compareKeys = (a: BTreeKeyForIndex, b: BTreeKeyForIndex): number => {
+			const arrA = a as SqlValue[];
+			const arrB = b as SqlValue[];
+
+			for (let i = 0; i < localSpecColumns.length; i++) {
+				if (i >= arrA.length || i >= arrB.length) {
+					return arrA.length - arrB.length;
+				}
+
+				const specCol = localSpecColumns[i];
+				const comparison = compareSqlValues(arrA[i], arrB[i], specCol.collation || 'BINARY');
+
+				if (comparison !== 0) {
+					return specCol.desc ? -comparison : comparison;
+				}
+			}
+			return 0;
+		};
+
+		return { keyFromRow, compareKeys };
+	}
+
+	private validateRowLength(row: Row, columnIndex: number): void {
+		if (columnIndex < 0 || columnIndex >= row.length) {
+			quereusError(`Index key col index ${columnIndex} OOB for row len ${row.length}`, StatusCode.INTERNAL);
+		}
+	}
+
+	private createBTree(baseInheritreeTable?: BTree<BTreeKeyForIndex, MemoryIndexEntry>): BTree<BTreeKeyForIndex, MemoryIndexEntry> {
+		return new BTree<BTreeKeyForIndex, MemoryIndexEntry>(
+			(entry: MemoryIndexEntry) => entry.indexKey,
+			this.compareKeys,
+			baseInheritreeTable
+		);
+	}
+
+	/** Adds a mapping from index key to primary key */
+	addEntry(indexKey: BTreeKeyForIndex, primaryKey: BTreeKeyForPrimary): void {
+		const path = this.data.find(indexKey);
+		if (path.on) {
+			// Entry exists, add to the existing set of primary keys
+			const existingEntry = this.data.at(path)!;
+			existingEntry.primaryKeys.add(primaryKey);
+		} else {
+			// Create new entry with a Set containing the primary key
+			const newEntry: MemoryIndexEntry = {
+				indexKey,
+				primaryKeys: new Set([primaryKey])
+			};
+			this.data.insert(newEntry);
+		}
+	}
+
+	/** Removes a mapping from index key to primary key */
+	removeEntry(indexKey: BTreeKeyForIndex, primaryKey: BTreeKeyForPrimary): void {
+		const path = this.data.find(indexKey);
+		if (path.on) {
+			const entry = this.data.at(path)!;
+			entry.primaryKeys.delete(primaryKey);
+
+			// If no primary keys remain, remove the entire entry
+			if (entry.primaryKeys.size === 0) {
+				this.data.deleteAt(path);
+			}
+		}
+	}
+
+	/** Returns the primary keys for a given index key */
+	getPrimaryKeys(indexKey: BTreeKeyForIndex): BTreeKeyForPrimary[] {
+		const entry = this.data.get(indexKey);
+		return entry ? Array.from(entry.primaryKeys) : [];
+	}
+
+	/** Gets the count of unique index values */
+	get size(): number {
+		return this.data.getCount();
+	}
+
+	/** Clears all entries from the index */
+	clear(): void {
+		const base = (this.data as any).baseTable as BTree<BTreeKeyForIndex, MemoryIndexEntry> | undefined;
+		this.data = this.createBTree(base);
+	}
+
+	/** Clears the base inheritance for this index (used during layer collapse) */
+	clearBase(): void {
+		if (typeof (this.data as any).clearBase === 'function') {
+			(this.data as any).clearBase();
+		}
+	}
+}