@gscdump/engine-duckdb-wasm 1.4.0 → 1.4.1

package/dist/runtime.d.mts

@@ -0,0 +1,210 @@
+import { AnalyzerRegistry } from "@gscdump/engine/analyzer";
+import { Result } from "gscdump/result";
+import { AsyncDuckDB, AsyncDuckDBConnection, DuckDBBundles, DuckDBConfig } from "@duckdb/duckdb-wasm";
+import { AnalysisParams } from "@gscdump/engine/analysis-types";
+interface QueryResult {
+  rows: Record<string, unknown>[];
+  queryMs: number;
+}
+interface AnalyzeResult {
+  results: Record<string, unknown>[];
+  meta: Record<string, unknown>;
+  queryMs: number;
+}
+interface DuckDBWasmBootResult {
+  db: AsyncDuckDB;
+  conn: AsyncDuckDBConnection;
+}
+interface BootDuckDBWasmOptions {
+  /**
+   * DuckDB-WASM logger. Defaults to a `ConsoleLogger` thresholded at
+   * `LogLevel.WARNING`, so real warnings/errors still surface but the per-query
+   * INFO events (START/OK/RUN) — which DuckDB's default `ConsoleLogger()` emits
+   * as raw objects, flooding the host console with dozens of lines per render —
+   * are dropped. Pass `new ConsoleLogger(LogLevel.DEBUG)` to see everything, or
+   * `new VoidLogger()` to silence it entirely.
+   */
+  logger?: unknown;
+  /**
+   * Override the jsDelivr-hosted bundle map. Required in environments where
+   * the default CDN is unreachable or where hosts must serve the WASM +
+   * worker assets themselves (e.g. Cloudflare Workers' 25 MB per-asset cap).
+   */
+  bundles?: DuckDBBundles;
+  /**
+   * Extra DuckDB open config. The browser runtime always forces HTTP files
+   * into range-only mode (reliable HEAD probes, no full HTTP fallback) so a
+   * server that cannot answer bounded reads fails closed.
+   */
+  config?: DuckDBConfig;
+  /**
+   * Cap DuckDB's memory with `SET memory_limit=<value>` right after open (e.g.
+   * `'2GB'`, `'512MB'`). A runaway query then errors with a clean
+   * out-of-memory rather than growing the WASM heap until the tab crashes —
+   * DuckDB has no statement-level timeout, so abandoned queries are otherwise
+   * only stopped by the caller's `AbortSignal` (which the runtime forwards to
+   * `conn.cancelSent()`). Opt-in: omit to keep DuckDB-WASM's default sizing.
+   * Accepts `<number>` with an optional `B`/`KB`/`MB`/`GB`/`TB` suffix.
+   */
+  memoryLimit?: string;
+}
+interface BrowserParquetFile {
+  bytes: Uint8Array;
+  name?: string;
+}
+interface BrowserParquetTable {
+  table: string;
+  files: BrowserParquetFile[];
+}
+interface BrowserParquetUrlTable {
+  table: string;
+  urls: string[];
+}
+interface AttachParquetTablesOptions {
+  db: AsyncDuckDB;
+  conn: AsyncDuckDBConnection;
+  tables: BrowserParquetTable[];
+  schema?: string;
+}
+interface AttachParquetUrlTablesOptions {
+  db: AsyncDuckDB;
+  conn: AsyncDuckDBConnection;
+  tables: BrowserParquetUrlTable[];
+  fetch?: typeof fetch;
+  schema?: string;
+  /**
+   * Request init used only for runtime-owned HEAD / one-byte Range preflights.
+   * DuckDB-WASM's internal HTTP reader cannot receive custom fetch headers;
+   * URL reads must therefore be authorized by the URL itself.
+   */
+  fetchInit?: RequestInit;
+  /**
+   * Caps simultaneous URL preflights. Browser source endpoints should already
+   * return small, coverage-planned URL sets; this is the runtime's local
+   * guard against accidental unbounded attachment.
+   */
+  fetchConcurrency?: number;
+  /** Reject before preflight when the URL set exceeds this many parquet files. */
+  maxFiles?: number;
+  /** Reject before registration when hinted or authoritative bytes exceed budget. */
+  maxBytes?: number;
+  /** Abort signal passed through to URL preflights and registration. */
+  signal?: AbortSignal;
+  /**
+   * How DuckDB reads the parquet bytes:
+   *  - `'http'` (default): register the URL as an HTTP file; DuckDB issues
+   *    its own range reads during query execution. Right for large parquet
+   *    where only some column chunks are touched per query.
+   *  - `'buffer'`: fetch the full file once into an `ArrayBuffer` and register
+   *    it via `registerFileBuffer`. DuckDB makes zero HTTP calls after
+   *    registration — every query reads from the in-memory copy. Right for
+   *    tiny files (e.g. `dates` daily-totals parquet, <50 KB per file) where
+   *    the per-file round-trip overhead dominates the actual bytes moved.
+   */
+  attachMode?: 'http' | 'buffer';
+  /**
+   * When `true` (default), skip per-file HEAD/Range preflight if the URL
+   * carries a signed `?s=<bytes>.<sig>` size hint — the size is already
+   * known and DuckDB will learn `Accept-Ranges` from its first read.
+   * Eliminates one round-trip per file on hosts that mint size hints. Set
+   * `false` to force preflight against URLs whose size you don't trust.
+   */
+  trustSizeHint?: boolean;
+  /**
+   * Manifest version the caller associates with this set of URLs. Returned
+   * on the resulting handle so callers can compare against a fresh manifest
+   * probe without re-attaching. Purely advisory — the runtime never derives
+   * behavior from the value itself.
+   */
+  version?: number | string;
+  /**
+   * Called once per parquet file after it's been fetched and registered with
+   * DuckDB. For URL-backed HTTP files this means "preflighted and registered"
+   * rather than fully downloaded; DuckDB then performs range reads during the
+   * query. Fires in bounded-concurrency completion order, which is still not
+   * guaranteed to match manifest URL order. Used by UI progress indicators to
+   * tick a per-site counter; a no-op default keeps the hot path free.
+   */
+  onFileAttached?: (info: {
+    table: string;
+    index: number;
+    total: number;
+  }) => void;
+}
+/**
+ * Handle returned from {@link attachParquetUrlTables}. Lets callers detach
+ * the created views (for lazy re-attach on a new manifest version) or cheap-
+ * check the embedded version against a fresh probe.
+ */
+interface AttachedTablesHandle {
+  version: number | string | undefined;
+  tables: string[];
+  schema: string;
+  detach: () => Promise<void>;
+}
+interface BrowserAnalysisRuntime {
+  db: AsyncDuckDB;
+  conn: AsyncDuckDBConnection;
+  query: (sql: string, params?: unknown[], signal?: AbortSignal) => Promise<QueryResult>;
+  analyze: (params: AnalysisParams, registry: AnalyzerRegistry, options?: {
+    signal?: AbortSignal;
+  }) => Promise<AnalyzeResult>;
+  /**
+   * Returns true when `expected` doesn't match the version the runtime was
+   * attached with — cheap check callers can run before each query to decide
+   * whether to detach + re-attach against a fresher manifest. Undefined
+   * values on either side compare equal so the no-version path is a no-op.
+   */
+  isStale: (expected: number | string | undefined) => boolean;
+  /** Update the runtime's cached manifest version in-place (e.g. after a re-attach). */
+  setVersion: (version: number | string | undefined) => void;
+  /**
+   * Update the list of attached table names. Lets callers fast-fail in
+   * `analyze()` when a SQL plan references a table that wasn't in the manifest
+   * for this site (e.g. site has only `queries` parquet, analyzer wants
+   * `page_queries`) — surface a clean `AttachedTableMissingError` so the
+   * caller can route to cloud fallback without paying the SQL execution cost.
+   */
+  setAttachedTables: (tables: readonly string[]) => void;
+  close: () => Promise<void>;
+}
+declare class BrowserAttachBudgetExceededError extends Error {
+  name: string;
+}
+interface BrowserAttachError {
+  kind: 'browser-attach-budget-exceeded';
+  message: string;
+  /** Which budget tripped: the file count, the hinted byte plan, or the running byte plan. */
+  budget: 'maxFiles' | 'maxBytes';
+}
+declare const browserAttachErrors: {
+  readonly maxFilesExceeded: (files: number, maxFiles: number) => BrowserAttachError;
+  readonly hintedBytesExceeded: (hintedBytes: number, maxBytes: number) => BrowserAttachError;
+  readonly plannedBytesExceeded: (plannedBytes: number, maxBytes: number) => BrowserAttachError;
+};
+declare function isBrowserAttachError(value: unknown): value is BrowserAttachError;
+declare function bootDuckDBWasm(options?: BootDuckDBWasmOptions): Promise<DuckDBWasmBootResult>;
+declare function attachParquetTables(options: AttachParquetTablesOptions): Promise<void>;
+/**
+ * Errors-as-values core for {@link attachParquetUrlTables}: returns a typed
+ * {@link BrowserAttachError} when the requested file set blows the local file-
+ * count / byte budget, so callers can branch (route the affected tables
+ * server-side) instead of catching an untyped throw. WASM/DuckDB/HTTP IO
+ * failures stay defects and propagate. `attachParquetUrlTables` is the thin
+ * throwing wrapper preserving the historical `BrowserAttachBudgetExceededError`.
+ */
+declare function attachParquetUrlTablesResult(options: AttachParquetUrlTablesOptions): Promise<Result<AttachedTablesHandle, BrowserAttachError>>;
+/**
+ * Attach browser parquet URL tables, throwing
+ * {@link BrowserAttachBudgetExceededError} when the requested set blows the
+ * file-count / byte budget. Thin throwing wrapper over
+ * {@link attachParquetUrlTablesResult}; existing call sites and their
+ * `instanceof BrowserAttachBudgetExceededError` checks keep holding.
+ */
+declare function attachParquetUrlTables(options: AttachParquetUrlTablesOptions): Promise<AttachedTablesHandle>;
+declare function createBrowserAnalysisRuntime(boot: DuckDBWasmBootResult, options?: {
+  schema?: string;
+  version?: number | string;
+  attachedTables?: readonly string[];
+}): BrowserAnalysisRuntime;
+export { AnalyzeResult, AttachParquetTablesOptions, AttachParquetUrlTablesOptions, AttachedTablesHandle, BootDuckDBWasmOptions, BrowserAnalysisRuntime, BrowserAttachBudgetExceededError, BrowserAttachError, BrowserParquetFile, BrowserParquetTable, BrowserParquetUrlTable, DuckDBWasmBootResult, QueryResult, attachParquetTables, attachParquetUrlTables, attachParquetUrlTablesResult, bootDuckDBWasm, browserAttachErrors, createBrowserAnalysisRuntime, isBrowserAttachError };

package/dist/runtime.mjs

@@ -0,0 +1,429 @@
+import { arrowToRows } from "@gscdump/engine/arrow";
+import { runAnalyzerFromSource } from "@gscdump/engine/analyzer";
+import { pgResolverAdapter } from "@gscdump/engine/resolver";
+import { createAttachedTableSource } from "@gscdump/engine/source";
+import { sqlEscape } from "@gscdump/engine/sql";
+import { err, ok, unwrapResult } from "gscdump/result";
+const DEFAULT_ATTACH_FETCH_CONCURRENCY = 2;
+const DEFAULT_ATTACH_MAX_FILES = 32;
+const DEFAULT_ATTACH_MAX_BYTES = 16 * 1024 * 1024;
+let nextAttachId = 0;
+var BrowserAttachBudgetExceededError = class extends Error {
+	name = "BrowserAttachBudgetExceededError";
+};
+const browserAttachErrors = {
+	maxFilesExceeded(files, maxFiles) {
+		return {
+			kind: "browser-attach-budget-exceeded",
+			budget: "maxFiles",
+			message: `browser parquet attach requires ${files} files, above maxFiles=${maxFiles}`
+		};
+	},
+	hintedBytesExceeded(hintedBytes, maxBytes) {
+		return {
+			kind: "browser-attach-budget-exceeded",
+			budget: "maxBytes",
+			message: `browser parquet attach requires ${hintedBytes} hinted bytes, above maxBytes=${maxBytes}`
+		};
+	},
+	plannedBytesExceeded(plannedBytes, maxBytes) {
+		return {
+			kind: "browser-attach-budget-exceeded",
+			budget: "maxBytes",
+			message: `browser parquet attach planned ${plannedBytes} bytes, above maxBytes=${maxBytes}`
+		};
+	}
+};
+function isBrowserAttachError(value) {
+	return typeof value === "object" && value !== null && value.kind === "browser-attach-budget-exceeded" && typeof value.message === "string";
+}
+function browserAttachErrorToException(error) {
+	const exception = new BrowserAttachBudgetExceededError(error.message);
+	exception.browserAttachError = error;
+	return exception;
+}
+function fileName(table, index, provided) {
+	return provided ?? `${table}_${index}.parquet`;
+}
+function attachFileName(attachId, table, index) {
+	return `__gscdump_attach_${attachId}_${fileName(table, index)}`;
+}
+function readParquetViewSql(schema, table, files) {
+	return `CREATE OR REPLACE VIEW ${schema}.${table} AS SELECT * REPLACE (CAST(date AS DATE) AS date) FROM read_parquet([${files.map((name) => `'${sqlEscape(name)}'`).join(", ")}], union_by_name = true)`;
+}
+function positiveInteger(value, fallback, label) {
+	const raw = value ?? fallback;
+	if (!Number.isFinite(raw) || raw < 1) throw new Error(`${label} must be a positive integer`);
+	return Math.floor(raw);
+}
+async function runWithConcurrency(items, concurrency, fn) {
+	let next = 0;
+	let failed = false;
+	async function worker() {
+		while (!failed && next < items.length) {
+			const index = next++;
+			try {
+				await fn(items[index], index);
+			} catch (err) {
+				failed = true;
+				throw err;
+			}
+		}
+	}
+	const rejected = (await Promise.allSettled(Array.from({ length: Math.min(concurrency, items.length) }, worker))).find((result) => result.status === "rejected");
+	if (rejected) throw rejected.reason;
+}
+function sizeHintFromUrl(url) {
+	try {
+		const base = typeof globalThis.location?.href === "string" ? globalThis.location.href : "http://localhost";
+		const raw = new URL(url, base).searchParams.get("s")?.split(".")[0];
+		if (!raw) return null;
+		const size = Number(raw);
+		return Number.isFinite(size) && size >= 0 ? size : null;
+	} catch {
+		return null;
+	}
+}
+function mergeAbortSignals(primary, secondary) {
+	if (!primary) return secondary;
+	if (!secondary) return primary;
+	if (primary.aborted) return primary;
+	if (secondary.aborted) return secondary;
+	const controller = new AbortController();
+	const abort = (signal) => {
+		controller.abort(signal.reason);
+	};
+	primary.addEventListener("abort", () => abort(primary), { once: true });
+	secondary.addEventListener("abort", () => abort(secondary), { once: true });
+	return controller.signal;
+}
+function fetchInitFor(fetchInit, method, signal, extraHeaders) {
+	const { body: _body, method: _method, signal: initSignal, headers: initHeaders, ...rest } = fetchInit ?? {};
+	const headers = new Headers(initHeaders);
+	for (const [key, value] of Object.entries(extraHeaders ?? {})) headers.set(key, value);
+	return {
+		...rest,
+		method,
+		headers,
+		signal: mergeAbortSignals(signal, initSignal ?? void 0)
+	};
+}
+function isAbortError(err) {
+	return typeof err === "object" && err !== null && err.name === "AbortError";
+}
+function parseContentLength(headers) {
+	const raw = headers.get("content-length");
+	if (!raw) return null;
+	const size = Number(raw);
+	return Number.isFinite(size) && size >= 0 ? size : null;
+}
+function parseContentRangeSize(headers) {
+	const raw = headers.get("content-range");
+	if (!raw) return null;
+	const match = /^bytes\s+\d+-\d+\/(\d+)$/i.exec(raw);
+	if (!match) return null;
+	const size = Number(match[1]);
+	return Number.isFinite(size) && size >= 0 ? size : null;
+}
+function supportsRangeReads(headers) {
+	return headers.get("accept-ranges")?.toLowerCase().split(",").map((v) => v.trim()).includes("bytes") === true;
+}
+async function cancelBody(response) {
+	await response.body?.cancel().catch(() => void 0);
+}
+async function preflightHttpUrl(url, fetchImpl, fetchInit, signal) {
+	const head = await fetchImpl(url, fetchInitFor(fetchInit, "HEAD", signal));
+	if (head.ok) {
+		const size = parseContentLength(head.headers);
+		if (size === null) throw new Error(`HEAD ${url} missing Content-Length`);
+		if (!supportsRangeReads(head.headers)) throw new Error(`HEAD ${url} missing Accept-Ranges: bytes`);
+		return size;
+	}
+	await cancelBody(head);
+	if (![
+		403,
+		405,
+		501
+	].includes(head.status)) throw new Error(`HEAD ${url} failed: ${head.status}`);
+	const probe = await fetchImpl(url, fetchInitFor(fetchInit, "GET", signal, { Range: "bytes=0-0" }));
+	try {
+		if (probe.status !== 206) throw new Error(`range probe ${url} failed: ${probe.status}`);
+		const size = parseContentRangeSize(probe.headers);
+		if (size === null) throw new Error(`range probe ${url} missing Content-Range size`);
+		return size;
+	} finally {
+		await cancelBody(probe);
+	}
+}
+function rangeOnlyConfig(config) {
+	return {
+		...config ?? {},
+		filesystem: {
+			reliableHeadRequests: true,
+			allowFullHTTPReads: false,
+			...config?.filesystem ?? {},
+			forceFullHTTPReads: false
+		}
+	};
+}
+async function dropAttachedResources(db, conn, schema, tables, files) {
+	for (const table of tables) await conn.query(`DROP VIEW IF EXISTS ${schema}.${table}`);
+	if (files.length > 0) await db.dropFiles([...files]);
+}
+function parseMemoryLimit(value) {
+	const trimmed = value.trim();
+	if (!/^\d+(?:\.\d+)?\s*(?:B|KB|MB|GB|TB)?$/i.test(trimmed)) throw new Error(`invalid memoryLimit '${value}' — expected e.g. '512MB' or '2GB'`);
+	return trimmed;
+}
+async function bootDuckDBWasm(options = {}) {
+	const { getJsDelivrBundles, selectBundle, AsyncDuckDB, ConsoleLogger, LogLevel } = await import("@duckdb/duckdb-wasm");
+	const bundle = await selectBundle(options.bundles ?? getJsDelivrBundles());
+	const workerUrl = URL.createObjectURL(new Blob([`importScripts("${bundle.mainWorker}");`], { type: "text/javascript" }));
+	const worker = new Worker(workerUrl);
+	const db = new AsyncDuckDB(options.logger ?? new ConsoleLogger(LogLevel.WARNING), worker);
+	try {
+		await db.instantiate(bundle.mainModule, bundle.pthreadWorker);
+		await db.open(rangeOnlyConfig(options.config));
+		const conn = await db.connect();
+		if (options.memoryLimit !== void 0) await conn.query(`SET memory_limit='${parseMemoryLimit(options.memoryLimit)}'`);
+		return {
+			db,
+			conn
+		};
+	} catch (err) {
+		worker.terminate();
+		throw err;
+	} finally {
+		URL.revokeObjectURL(workerUrl);
+	}
+}
+async function attachParquetTables(options) {
+	const { db, conn, tables, schema = "main" } = options;
+	for (const table of tables) {
+		const names = [];
+		for (let i = 0; i < table.files.length; i++) {
+			const file = table.files[i];
+			const name = fileName(table.table, i, file.name);
+			names.push(name);
+			await db.registerFileBuffer(name, file.bytes);
+		}
+		await conn.query(readParquetViewSql(schema, table.table, names));
+	}
+}
+async function attachParquetUrlTablesResult(options) {
+	const { db, conn, tables, fetch: fetchImpl = globalThis.fetch.bind(globalThis), schema = "main", fetchInit, fetchConcurrency, maxFiles, maxBytes, signal, version, onFileAttached, attachMode = "http", trustSizeHint = true } = options;
+	const concurrency = positiveInteger(fetchConcurrency, DEFAULT_ATTACH_FETCH_CONCURRENCY, "fetchConcurrency");
+	const fileBudget = positiveInteger(maxFiles, DEFAULT_ATTACH_MAX_FILES, "maxFiles");
+	const byteBudget = positiveInteger(maxBytes, DEFAULT_ATTACH_MAX_BYTES, "maxBytes");
+	const attachId = nextAttachId++;
+	const flat = [];
+	const counts = {};
+	for (const [table, urls] of tables.map((t) => [t.table, t.urls])) {
+		if (urls.length === 0) continue;
+		counts[table] = urls.length;
+		for (let i = 0; i < urls.length; i++) flat.push({
+			table,
+			url: urls[i],
+			index: i
+		});
+	}
+	if (flat.length > fileBudget) return err(browserAttachErrors.maxFilesExceeded(flat.length, fileBudget));
+	const hintedBytes = flat.reduce((acc, item) => {
+		const hint = sizeHintFromUrl(item.url);
+		return hint === null ? acc : acc + hint;
+	}, 0);
+	if (hintedBytes > byteBudget) return err(browserAttachErrors.hintedBytesExceeded(hintedBytes, byteBudget));
+	const tableFailures = /* @__PURE__ */ new Map();
+	const budgetController = new AbortController();
+	const effectiveSignal = mergeAbortSignals(signal, budgetController.signal);
+	let plannedBytes = 0;
+	const total = flat.length;
+	const prepared = [];
+	try {
+		await runWithConcurrency(flat, concurrency, async ({ table, url, index }) => {
+			if (tableFailures.has(table)) return;
+			effectiveSignal?.throwIfAborted();
+			try {
+				let bytes = null;
+				let body = null;
+				if (attachMode === "buffer") {
+					const res = await fetchImpl(url, fetchInitFor(fetchInit, "GET", effectiveSignal));
+					if (!res.ok) throw new Error(`GET ${url} failed: ${res.status}`);
+					const buf = new Uint8Array(await res.arrayBuffer());
+					body = buf;
+					bytes = buf.byteLength;
+				} else if (trustSizeHint && sizeHintFromUrl(url) !== null) bytes = sizeHintFromUrl(url);
+				else bytes = await preflightHttpUrl(url, fetchImpl, fetchInit, effectiveSignal);
+				plannedBytes += bytes;
+				if (plannedBytes > byteBudget) {
+					const budgetErr = new BrowserAttachBudgetExceededError(`browser parquet attach planned ${plannedBytes} bytes, above maxBytes=${byteBudget}`);
+					budgetController.abort(budgetErr);
+					throw budgetErr;
+				}
+				effectiveSignal?.throwIfAborted();
+				prepared.push({
+					table,
+					url,
+					index,
+					name: attachFileName(attachId, table, index),
+					bytes,
+					body
+				});
+			} catch (err) {
+				if (effectiveSignal?.aborted || err instanceof BrowserAttachBudgetExceededError || isAbortError(err)) throw err;
+				tableFailures.set(table, err instanceof Error ? err : new Error(String(err)));
+			}
+		});
+	} catch (downloadErr) {
+		if (downloadErr instanceof BrowserAttachBudgetExceededError && !signal?.aborted) return err(browserAttachErrors.plannedBytesExceeded(plannedBytes, byteBudget));
+		throw downloadErr;
+	}
+	const { DuckDBDataProtocol } = await import("@duckdb/duckdb-wasm");
+	const attached = [];
+	const registeredFiles = [];
+	try {
+		for (const file of prepared) {
+			if (tableFailures.has(file.table)) continue;
+			effectiveSignal?.throwIfAborted();
+			if (file.body !== null) await db.registerFileBuffer(file.name, file.body);
+			else await db.registerFileURL(file.name, file.url, DuckDBDataProtocol.HTTP, false);
+			registeredFiles.push(file.name);
+			onFileAttached?.({
+				table: file.table,
+				index: file.index,
+				total
+			});
+		}
+		for (const table of Object.keys(counts)) {
+			if (tableFailures.has(table)) continue;
+			const files = prepared.filter((file) => file.table === table).sort((a, b) => a.index - b.index);
+			if (files.length !== counts[table]) continue;
+			effectiveSignal?.throwIfAborted();
+			await conn.query(readParquetViewSql(schema, table, files.map((file) => file.name)));
+			attached.push(table);
+		}
+	} catch (err) {
+		await dropAttachedResources(db, conn, schema, attached, registeredFiles).catch((cleanupErr) => {
+			console.warn("[gscdump/engine-duckdb-wasm] cleanup after failed attach failed", cleanupErr);
+		});
+		throw err;
+	}
+	if (tableFailures.size > 0) for (const [table, err] of tableFailures) console.warn(`[gscdump/engine-duckdb-wasm] dropped table "${table}" — ${err.message}`);
+	let detached = false;
+	return ok({
+		version,
+		tables: attached,
+		schema,
+		async detach() {
+			if (detached) return;
+			detached = true;
+			await dropAttachedResources(db, conn, schema, attached, registeredFiles);
+		}
+	});
+}
+async function attachParquetUrlTables(options) {
+	return unwrapResult(await attachParquetUrlTablesResult(options), browserAttachErrorToException);
+}
+function createBrowserAnalysisRuntime(boot, options = {}) {
+	const { db, conn } = boot;
+	const schema = options.schema ?? "main";
+	let version = options.version;
+	let attachedTables = options.attachedTables;
+	let chain = Promise.resolve();
+	function abortError(signal) {
+		return signal.reason ?? new DOMException("aborted", "AbortError");
+	}
+	function raceSignal(promise, signal) {
+		if (!signal) return promise;
+		if (signal.aborted) return Promise.reject(abortError(signal));
+		return new Promise((resolve, reject) => {
+			const onAbort = () => reject(abortError(signal));
+			signal.addEventListener("abort", onAbort, { once: true });
+			promise.then((value) => {
+				signal.removeEventListener("abort", onAbort);
+				resolve(value);
+			}, (err) => {
+				signal.removeEventListener("abort", onAbort);
+				reject(err);
+			});
+		});
+	}
+	function runExclusive(signal, work) {
+		const next = chain.then(work, work);
+		chain = next.then(() => void 0, () => void 0);
+		return raceSignal(next, signal);
+	}
+	async function cancelOnAbort(signal, work) {
+		if (!signal) return work;
+		if (signal.aborted) throw abortError(signal);
+		const onAbort = () => {
+			conn.cancelSent().catch((error) => {
+				console.warn("[gscdump/engine-duckdb-wasm] failed to cancel aborted query", error);
+			});
+		};
+		signal.addEventListener("abort", onAbort, { once: true });
+		try {
+			return await work;
+		} finally {
+			signal.removeEventListener("abort", onAbort);
+		}
+	}
+	async function runParameterizedDirect(sql, params, signal) {
+		signal?.throwIfAborted();
+		return cancelOnAbort(signal, (async () => {
+			if (!params || params.length === 0) return conn.query(sql);
+			const stmt = await conn.prepare(sql);
+			try {
+				return await stmt.query(...params);
+			} finally {
+				await stmt.close();
+			}
+		})());
+	}
+	return {
+		db,
+		conn,
+		async query(sql, params, signal) {
+			const t0 = performance.now();
+			return {
+				rows: arrowToRows(await runExclusive(signal, () => runParameterizedDirect(sql, params, signal))),
+				queryMs: performance.now() - t0
+			};
+		},
+		async analyze(params, registry, options = {}) {
+			const signal = options.signal;
+			const run = async () => {
+				signal?.throwIfAborted();
+				const t0 = performance.now();
+				const result = await runAnalyzerFromSource(createAttachedTableSource({ query: async (sql, bindParams, innerSignal) => {
+					return arrowToRows(await runParameterizedDirect(sql, bindParams, innerSignal ?? signal));
+				} }, {
+					schema,
+					signal,
+					attachedTables,
+					adapter: pgResolverAdapter
+				}), params, registry);
+				return {
+					results: result.results,
+					meta: result.meta,
+					queryMs: performance.now() - t0
+				};
+			};
+			return runExclusive(signal, run);
+		},
+		isStale(expected) {
+			return expected !== version;
+		},
+		setVersion(next) {
+			version = next;
+		},
+		setAttachedTables(next) {
+			attachedTables = next;
+		},
+		async close() {
+			await conn.close();
+			await db.terminate();
+		}
+	};
+}
+export { BrowserAttachBudgetExceededError, attachParquetTables, attachParquetUrlTables, attachParquetUrlTablesResult, bootDuckDBWasm, browserAttachErrors, createBrowserAnalysisRuntime, isBrowserAttachError };

package/dist/schema.d.mts

@@ -0,0 +1,2 @@
+import { DrizzleSchema as Schema, countries, dates, drizzleSchema as schema, hourly_pages, page_queries, pages, queries } from "@gscdump/engine/schema";
+export { type Schema, countries, dates, hourly_pages, page_queries, pages, queries, schema };

package/dist/schema.mjs

@@ -0,0 +1,2 @@
+import { countries, dates, drizzleSchema as schema, hourly_pages, page_queries, pages, queries } from "@gscdump/engine/schema";
+export { countries, dates, hourly_pages, page_queries, pages, queries, schema };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gscdump/engine-duckdb-wasm",
   "type": "module",
-  "version": "1.4.0",
+  "version": "1.4.1",
   "description": "DuckDB-WASM engine adapter for @gscdump/analysis — typed browser analytics against parquet via R2.",
   "author": {
     "name": "Harlan Wilton",
@@ -45,9 +45,9 @@
   },
   "dependencies": {
     "drizzle-orm": "1.0.0-rc.3",
-    "@gscdump/contracts": "^1.4.0",
-    "@gscdump/engine": "^1.4.0",
-    "gscdump": "^1.4.0"
+    "@gscdump/contracts": "^1.4.1",
+    "@gscdump/engine": "^1.4.1",
+    "gscdump": "^1.4.1"
   },
   "devDependencies": {
     "@duckdb/duckdb-wasm": "1.33.1-dev57.0",