@gscdump/engine-duckdb-wasm 0.25.14 → 0.26.0

package/dist/index.d.mts

@@ -4,6 +4,7 @@ import { AnyRelations, EmptyRelations, ExtractTablesWithRelations, Schema as Sch
 import { DrizzleSchema as Schema, countries, dates, drizzleSchema as schema, hourly_pages, page_queries, pages, queries } from "@gscdump/engine/schema";
 import { ScopedRunnerOptions, TableScope } from "@gscdump/engine/scope";
 import { AnalyzerRegistry } from "@gscdump/engine/analyzer";
+import { Result } from "gscdump/result";
 import { ComparisonMode, ResolveWindowOptions, ResolvedWindow, WindowPreset, resolveWindow } from "@gscdump/engine/period";
 import { ArchetypeQuery } from "@gscdump/sdk";
 import { AsyncDuckDB, AsyncDuckDBConnection, DuckDBBundles, DuckDBConfig } from "@duckdb/duckdb-wasm";
@@ -217,6 +218,14 @@ interface DuckDBWasmBootResult {
   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
@@ -354,12 +363,40 @@ interface BrowserAnalysisRuntime {
 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 { type AnalyzeResult, type AttachOpfsTablesOptions, type AttachParquetTablesOptions, type AttachParquetUrlTablesOptions, type AttachedTablesHandle, type BootDuckDBWasmOptions, type BrowserAnalysisRuntime, BrowserAttachBudgetExceededError, type BrowserParquetFile, type BrowserParquetTable, type BrowserParquetUrlTable, type ComparisonMode, type CompiledArchetypeSql, type DuckDBWasmBootResult, type DuckDBWasmClient, DuckDBWasmDatabase, type DuckDBWasmDrizzleDatabase, type InsightRunner, type InsightRunnerOptions, type OpfsAttachedHandle, type OpfsFileProgress, type OpfsParquetFile, type OpfsParquetTable, OpfsQuotaExceededError, type QueryResult, type ResolveWindowOptions, type ResolvedWindow, type Schema, type ScopedRunnerOptions, type StrikingMomentumOptions, type StrikingMomentumRow, type TableScope, type WindowPreset, attachOpfsParquetTables, attachParquetTables, attachParquetUrlTables, bootDuckDBWasm, clearOpfsSnapshotCache, compileArchetypeSql, countries, createBrowserAnalysisRuntime, createClient, createInsightRunner, dates, drizzle, estimateOpfsStorage, hourly_pages, mergeScope, page_queries, pages, queries, requestPersistentStorage, resolveWindow, schema, scopeFor, strikingMomentum, tableForArchetype };
+export { type AnalyzeResult, type AttachOpfsTablesOptions, type AttachParquetTablesOptions, type AttachParquetUrlTablesOptions, type AttachedTablesHandle, type BootDuckDBWasmOptions, type BrowserAnalysisRuntime, BrowserAttachBudgetExceededError, type BrowserAttachError, type BrowserParquetFile, type BrowserParquetTable, type BrowserParquetUrlTable, type ComparisonMode, type CompiledArchetypeSql, type DuckDBWasmBootResult, type DuckDBWasmClient, DuckDBWasmDatabase, type DuckDBWasmDrizzleDatabase, type InsightRunner, type InsightRunnerOptions, type OpfsAttachedHandle, type OpfsFileProgress, type OpfsParquetFile, type OpfsParquetTable, OpfsQuotaExceededError, type QueryResult, type ResolveWindowOptions, type ResolvedWindow, type Schema, type ScopedRunnerOptions, type StrikingMomentumOptions, type StrikingMomentumRow, type TableScope, type WindowPreset, attachOpfsParquetTables, attachParquetTables, attachParquetUrlTables, attachParquetUrlTablesResult, bootDuckDBWasm, browserAttachErrors, clearOpfsSnapshotCache, compileArchetypeSql, countries, createBrowserAnalysisRuntime, createClient, createInsightRunner, dates, drizzle, estimateOpfsStorage, hourly_pages, isBrowserAttachError, mergeScope, page_queries, pages, queries, requestPersistentStorage, resolveWindow, schema, scopeFor, strikingMomentum, tableForArchetype };

package/dist/index.mjs

@@ -9,6 +9,7 @@ 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";
 import { resolveWindow } from "@gscdump/engine/period";
 const METRIC_SQL = {
 	clicks: "SUM(clicks)",
@@ -278,7 +279,7 @@ async function createClient(db, conn) {
 			try {
 				return arrowToRows(await stmt.query(...params));
 			} finally {
-				stmt.close();
+				await stmt.close();
 			}
 		},
 		async close() {
@@ -583,7 +584,7 @@ function readParquetViewSql$1(schema, table, files) {
 function readParquetViewWithOverlaySql(schema, table, lakeFiles, overlayFile) {
 	const overlay = `SELECT * REPLACE (CAST(date AS DATE) AS date) FROM read_parquet(['${overlayFile.replace(/'/g, "''")}'], union_by_name = true)`;
 	if (lakeFiles.length === 0) return `CREATE OR REPLACE VIEW ${schema}.${table} AS ${overlay}`;
-	return `CREATE OR REPLACE VIEW ${schema}.${table} AS ${lakeSelect(lakeFiles)} UNION ALL BY NAME ${overlay} WHERE CAST(date AS DATE) NOT IN (SELECT DISTINCT CAST(date AS DATE) FROM read_parquet([${quoteList(lakeFiles)}], union_by_name = true))`;
+	return `CREATE OR REPLACE VIEW ${schema}.${table} AS WITH lake AS MATERIALIZED (${lakeSelect(lakeFiles)}), lake_dates AS (SELECT DISTINCT date FROM lake) SELECT * FROM lake UNION ALL BY NAME SELECT * FROM (${overlay}) AS overlay WHERE overlay.date NOT IN (SELECT date FROM lake_dates)`;
 }
 async function runWithConcurrency$1(items, concurrency, fn) {
 	let next = 0;
@@ -781,6 +782,37 @@ 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`;
 }
@@ -909,11 +941,11 @@ async function dropAttachedResources(db, conn, schema, tables, files) {
 	if (files.length > 0) await db.dropFiles([...files]);
 }
 async function bootDuckDBWasm(options = {}) {
-	const { getJsDelivrBundles, selectBundle, AsyncDuckDB, ConsoleLogger } = await import("@duckdb/duckdb-wasm");
+	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(), worker);
+	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));
@@ -941,7 +973,7 @@ async function attachParquetTables(options) {
 		await conn.query(readParquetViewSql(schema, table.table, names));
 	}
 }
-async function attachParquetUrlTables(options) {
+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");
@@ -958,52 +990,57 @@ async function attachParquetUrlTables(options) {
 			index: i
 		});
 	}
-	if (flat.length > fileBudget) throw new BrowserAttachBudgetExceededError(`browser parquet attach requires ${flat.length} files, above maxFiles=${fileBudget}`);
+	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) throw new BrowserAttachBudgetExceededError(`browser parquet attach requires ${hintedBytes} hinted bytes, above maxBytes=${byteBudget}`);
+	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 = [];
-	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 err = new BrowserAttachBudgetExceededError(`browser parquet attach planned ${plannedBytes} bytes, above maxBytes=${byteBudget}`);
-				budgetController.abort(err);
-				throw err;
-			}
+	try {
+		await runWithConcurrency(flat, concurrency, async ({ table, url, index }) => {
+			if (tableFailures.has(table)) return;
 			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)));
-		}
-	});
+			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 = [];
@@ -1036,7 +1073,7 @@ async function attachParquetUrlTables(options) {
 	}
 	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 {
+	return ok({
 		version,
 		tables: attached,
 		schema,
@@ -1045,7 +1082,10 @@ async function attachParquetUrlTables(options) {
 			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;
@@ -1147,4 +1187,4 @@ function createBrowserAnalysisRuntime(boot, options = {}) {
 		}
 	};
 }
-export { BrowserAttachBudgetExceededError, DuckDBWasmDatabase, OpfsQuotaExceededError, attachOpfsParquetTables, attachParquetTables, attachParquetUrlTables, bootDuckDBWasm, clearOpfsSnapshotCache, compileArchetypeSql, countries, createBrowserAnalysisRuntime, createClient, createInsightRunner, dates, drizzle, estimateOpfsStorage, hourly_pages, mergeScope, page_queries, pages, queries, requestPersistentStorage, resolveWindow, schema, scopeFor, strikingMomentum, tableForArchetype };
+export { BrowserAttachBudgetExceededError, DuckDBWasmDatabase, OpfsQuotaExceededError, attachOpfsParquetTables, attachParquetTables, attachParquetUrlTables, attachParquetUrlTablesResult, bootDuckDBWasm, browserAttachErrors, clearOpfsSnapshotCache, compileArchetypeSql, countries, createBrowserAnalysisRuntime, createClient, createInsightRunner, dates, drizzle, estimateOpfsStorage, hourly_pages, isBrowserAttachError, mergeScope, page_queries, pages, queries, requestPersistentStorage, resolveWindow, schema, scopeFor, strikingMomentum, tableForArchetype };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gscdump/engine-duckdb-wasm",
   "type": "module",
-  "version": "0.25.14",
+  "version": "0.26.0",
   "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/engine": "0.25.14",
-    "@gscdump/sdk": "0.25.14",
-    "gscdump": "0.25.14"
+    "@gscdump/engine": "0.26.0",
+    "@gscdump/sdk": "0.26.0",
+    "gscdump": "0.26.0"
   },
   "devDependencies": {
     "@duckdb/duckdb-wasm": "^1.32.0",