@quereus/quereus 0.2.1 → 0.4.5

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

@@ -10,13 +10,29 @@ const log = createLogger('util:plugin-loader');
  * Plugin module interface - what we expect from a plugin module
  */
 export interface PluginModule {
-	/** Plugin manifest with metadata */
-	manifest?: PluginManifest;
-	
 	/** Default export - the plugin registration function */
 	default: (db: Database, config: Record<string, SqlValue>) => Promise<PluginRegistrations> | PluginRegistrations;
 }
 
+/**
+ * Extracts plugin manifest from package.json metadata
+ * Looks for metadata in package.json root fields and quereus.provides/settings
+ */
+function extractManifestFromPackageJson(pkg: any): PluginManifest {
+	const quereus = pkg.quereus || {};
+
+	return {
+		name: pkg.name || 'Unknown Plugin',
+		version: pkg.version || '0.0.0',
+		author: pkg.author,
+		description: pkg.description,
+		pragmaPrefix: quereus.pragmaPrefix,
+		settings: quereus.settings,
+		provides: quereus.provides,
+		capabilities: quereus.capabilities
+	};
+}
+
 /**
  * Dynamically loads and registers a plugin module
  *
@@ -53,7 +69,7 @@ export async function dynamicLoadModule(
 
 		log('Successfully loaded plugin from %s', url);
 		if (registrations.vtables?.length) {
-			log('  Registered %d vtable module(s): %s', registrations.vtables.length, 
+			log('  Registered %d vtable module(s): %s', registrations.vtables.length,
 				registrations.vtables.map(v => v.name).join(', '));
 		}
 		if (registrations.functions?.length) {
@@ -65,8 +81,21 @@ export async function dynamicLoadModule(
 				registrations.collations.map(c => c.name).join(', '));
 		}
 
-		// Return the manifest if available
-		return mod.manifest;
+		// Try to extract manifest from package.json
+		let manifest: PluginManifest | undefined;
+		try {
+			const packageJsonUrl = new URL('package.json', moduleUrl);
+			const packageJsonResponse = await fetch(packageJsonUrl.toString());
+			if (packageJsonResponse.ok) {
+				const pkg = await packageJsonResponse.json();
+				manifest = extractManifestFromPackageJson(pkg);
+			}
+		} catch {
+			// package.json not found or not accessible - that's okay
+			log('Could not load package.json for plugin at %s', url);
+		}
+
+		return manifest;
 	} catch (error) {
 		const message = error instanceof Error ? error.message : String(error);
 		quereusError(`Failed to load plugin from ${url}: ${message}`);
@@ -75,7 +104,7 @@ export async function dynamicLoadModule(
 
 /**
  * Registers all items provided by a plugin
- * 
+ *
  * @param db Database instance to register with
  * @param registrations The items to register
  */
@@ -141,3 +170,199 @@ 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(', '));
+        }
+
+        // Try to extract manifest from package.json
+        let manifest: PluginManifest | undefined;
+        try {
+            // Try to import package.json directly
+            const pkg = await import(`${npm.name}/package.json`, { assert: { type: 'json' } });
+            manifest = extractManifestFromPackageJson(pkg.default);
+        } catch {
+            // package.json not found - that's okay
+            log('Could not load package.json for plugin %s', npm.name);
+        }
+
+        return 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';