@gscdump/engine-duckdb-wasm 0.7.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Harlan Wilton
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,73 @@
+# @gscdump/engine-duckdb-wasm
+
+[![npm version](https://img.shields.io/npm/v/@gscdump/engine-duckdb-wasm?color=yellow)](https://npmjs.com/package/@gscdump/engine-duckdb-wasm)
+[![npm downloads](https://img.shields.io/npm/dm/@gscdump/engine-duckdb-wasm?color=yellow)](https://npm.chart.dev/@gscdump/engine-duckdb-wasm)
+[![license](https://img.shields.io/github/license/harlan-zw/gscdump?color=yellow)](https://github.com/harlan-zw/gscdump/blob/main/LICENSE)
+
+> DuckDB-WASM engine adapter for `@gscdump/analysis` — typed browser analytics against parquet via R2.
+
+In-browser DuckDB-WASM connection wrapped as a `SqlQuerySource`. Ships a vendored, stripped-down drizzle-orm DuckDB-WASM adapter (~240 LoC, adapted from `@proj-airi/drizzle-duckdb-wasm`, MIT). Transactions throw — analytics workload is read-only.
+
+Bundle: **10.3 kB / 2.72 kB gzipped**. `@duckdb/duckdb-wasm` is an optional peer dep.
+
+## Install
+
+```bash
+npm install @gscdump/engine-duckdb-wasm @duckdb/duckdb-wasm
+```
+
+## Usage
+
+```ts
+import {
+  attachParquetUrlTables,
+  bootDuckDBWasm,
+  createInsightRunner,
+  resolveWindow,
+  scopeFor,
+  strikingMomentum,
+} from '@gscdump/engine-duckdb-wasm'
+
+const { db, conn } = await bootDuckDBWasm()
+await attachParquetUrlTables(conn, { tables: [{ name: 'gsc_keywords', url: '/r2/keywords.parquet' }] })
+
+const runner = createInsightRunner({ db, conn })
+const window = resolveWindow({ preset: 'last-30d', comparison: 'prev-period' })
+const scope = scopeFor('keywords', { siteId, window })
+
+const rows = await strikingMomentum(runner, { ...scope, limit: 50 })
+```
+
+### Engine source for analyzer dispatch
+
+```ts
+import { createEngine } from '@gscdump/engine-duckdb-wasm'
+
+const source = createEngine({
+  runner: { query: (sql, params) => conn.query(sql, params) },
+})
+```
+
+## Exports
+
+- `createEngine({ runner })` — builds a `SqlQuerySource` over a DuckDB-WASM connection.
+- `createInsightRunner({ db, conn })` — drizzle-orm handle for typed `.select()` / window functions, with `sql\`...\`` raw escape hatch.
+- `bootDuckDBWasm()` / `attachParquetTables()` / `attachParquetUrlTables()` / `attachSingleTable()` / `createBrowserAnalysisRuntime()` / `createDuckDBBundlesFromBase()` / `listAttachedTables()` — browser runtime primitives.
+- `strikingMomentum(runner, options)` — first-class browser insight.
+- `scopeFor(table, { siteId, window })` / `mergeScope()` — tenant scope predicates.
+- `pages` / `keywords` / `page_keywords` / `countries` / `devices` / `schema` — drizzle schema mirroring `gscdump/analytics` `SCHEMAS`. Drift fails loudly at module load.
+- `browserResolverAdapter` — dialect adapter for the resolver kit.
+- `createClient` / `drizzle` / `DuckDBWasmDatabase` — vendored drizzle-orm DuckDB-WASM adapter.
+- `resolveWindow` (re-exported from `@gscdump/engine/period`).
+
+## Related
+
+- [`@gscdump/engine`](../engine) — Storage contracts + dialect-neutral resolver.
+- [`@gscdump/analysis`](../analysis) — Analyzer registry + `analyzeContentGap` (browser semantic).
+- [`@gscdump/engine-duckdb-node`](../engine-duckdb-node) — Node DuckDB counterpart.
+- [`@gscdump/engine-sqlite`](../engine-sqlite) — SQLite / D1 counterpart.
+- [`@gscdump/nuxt-analytics`](../nuxt-analytics) — Nuxt layer that ships this runtime client-side.
+
+## License
+
+[MIT](../../LICENSE)

package/dist/index.d.mts

@@ -0,0 +1,224 @@
+import { Assume, DrizzleConfig, entityKind } from "drizzle-orm";
+import { PgDatabase, PgDialect, PgPreparedQuery, PgQueryResultHKT, PgSession } from "drizzle-orm/pg-core";
+import { QueryRow, SqlQuerySource, pgResolverAdapter as browserResolverAdapter } from "@gscdump/engine/resolver";
+import { DrizzleSchema as Schema, countries, devices, drizzleSchema as schema, keywords, page_keywords, pages } from "@gscdump/engine/schema";
+import * as _$_gscdump_engine_scope0 from "@gscdump/engine/scope";
+import { ScopedRunnerOptions, TableScope } from "@gscdump/engine/scope";
+import { AnalyzerRegistry } from "@gscdump/engine/analyzer";
+import { ComparisonMode, ResolveWindowOptions, ResolvedWindow, WindowPreset, resolveWindow } from "@gscdump/engine/period";
+import { AsyncDuckDB, AsyncDuckDBConnection, DuckDBBundles } from "@duckdb/duckdb-wasm";
+import { AnalysisParams } from "@gscdump/engine/analysis-types";
+interface DuckDBWasmClient {
+  db: AsyncDuckDB;
+  conn: AsyncDuckDBConnection;
+  query: (sql: string, params?: unknown[]) => Promise<Record<string, unknown>[]>;
+  close: () => Promise<void>;
+}
+declare function createClient(db: AsyncDuckDB, conn: AsyncDuckDBConnection): Promise<DuckDBWasmClient>;
+type Row = Record<string, unknown>;
+interface DuckDBWasmQueryResultHKT extends PgQueryResultHKT {
+  type: Assume<this['row'], Row>[];
+}
+declare class DuckDBWasmDatabase<TSchema extends Record<string, unknown> = Record<string, never>> extends PgDatabase<DuckDBWasmQueryResultHKT, TSchema> {
+  static readonly [entityKind]: string;
+}
+interface DuckDBWasmDrizzleDatabase<TSchema extends Record<string, unknown> = Record<string, never>> extends DuckDBWasmDatabase<TSchema> {
+  $client: Promise<DuckDBWasmClient>;
+}
+declare function drizzle<TSchema extends Record<string, unknown> = Record<string, never>>(client: Promise<DuckDBWasmClient> | DuckDBWasmClient, config?: DrizzleConfig<TSchema>): DuckDBWasmDrizzleDatabase<TSchema>;
+interface BrowserQueryRunner {
+  query: (sql: string, params?: unknown[]) => Promise<QueryRow[]>;
+}
+interface EngineConfig {
+  runner: BrowserQueryRunner;
+}
+declare function createEngine(config: EngineConfig): SqlQuerySource;
+interface InsightRunnerOptions {
+  db: AsyncDuckDB;
+  conn: AsyncDuckDBConnection;
+  logger?: boolean;
+}
+interface InsightRunner {
+  db: DuckDBWasmDrizzleDatabase<Schema>;
+  client: Promise<DuckDBWasmClient>;
+  close: () => Promise<void>;
+}
+declare function createInsightRunner(opts: InsightRunnerOptions): Promise<InsightRunner>;
+/**
+ * Build a per-table predicate set from {siteId, window}. The returned
+ * `wherePredicates` composes with user-level filters via `mergeScope`.
+ *
+ * Note: the current SCHEMAS don't include `site_id` on any table (snapshots
+ * are already per-site), so `siteId` is a no-op for now — kept in the API
+ * so consumers can add the predicate without an interface change when
+ * multi-site snapshots land.
+ */
+declare const scopeFor: (table: "pages" | "keywords" | "countries" | "devices" | "page_keywords" | "search_appearance", opts: ScopedRunnerOptions) => TableScope, mergeScope: typeof _$_gscdump_engine_scope0.mergeScope;
+interface StrikingMomentumOptions {
+  /** Anchor date (YYYY-MM-DD). Defaults to today. */
+  anchor?: string;
+  /** Width of each window in days. Default 90. */
+  windowDays?: number;
+  /** Minimum impressions in the prior window for a row to qualify. Default 10. */
+  minPriorImpressions?: number;
+  /** Minimum impressions in the recent window. Default 50. */
+  minRecentImpressions?: number;
+  /** Result limit. Default 20. */
+  limit?: number;
+}
+interface StrikingMomentumRow {
+  query: string;
+  url: string;
+  recent_impr: number;
+  recent_pos: number;
+  prior_impr: number;
+  prior_pos: number;
+  momentum_score: number;
+}
+declare function strikingMomentum(runner: InsightRunner, opts?: StrikingMomentumOptions): Promise<StrikingMomentumRow[]>;
+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 {
+  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;
+}
+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;
+  fetchInit?: RequestInit;
+  /**
+   * 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. Fires in non-deterministic order (Promise.all under the hood).
+   * 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;
+}
+interface AttachSingleTableOptions {
+  db: AsyncDuckDB;
+  conn: AsyncDuckDBConnection;
+  table: string;
+  urls: string[];
+  fetch?: typeof fetch;
+  schema?: string;
+  fetchInit?: RequestInit;
+}
+/**
+ * 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 `keywords` parquet, analyzer wants
+   * `page_keywords`) — 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>;
+}
+/**
+ * Build a `DuckDBBundles` map from a single base URL hosting the standard
+ * DuckDB-WASM asset set (matches the names jsDelivr + `@duckdb/duckdb-wasm`
+ * ship). Callers pointing at a Worker / R2 / self-hosted origin can pass
+ * just the origin instead of duplicating the URL layout across apps.
+ *
+ * Omits `coi` (pthread) by default; most hosts don't serve the
+ * cross-origin-isolation headers needed to use it and requesting a missing
+ * asset fails bundle selection on Safari/Firefox.
+ */
+declare function createDuckDBBundlesFromBase(baseUrl: string, options?: {
+  includeCoi?: boolean;
+}): DuckDBBundles;
+declare function bootDuckDBWasm(options?: BootDuckDBWasmOptions): Promise<DuckDBWasmBootResult>;
+declare function attachParquetTables(options: AttachParquetTablesOptions): Promise<void>;
+declare function attachParquetUrlTables(options: AttachParquetUrlTablesOptions): Promise<AttachedTablesHandle>;
+/**
+ * Incremental attach — fetch + register a single table's URLs and create the
+ * view, without touching any other table. Use this for lazy attach when a
+ * page only needs one of several available tables.
+ */
+declare function attachSingleTable(options: AttachSingleTableOptions): Promise<void>;
+/**
+ * List the views currently attached under `schema` via DuckDB's
+ * `information_schema`. Lets callers decide whether to call
+ * `attachSingleTable` before each query without guessing at state.
+ */
+declare function listAttachedTables(conn: AsyncDuckDBConnection, schema?: string): Promise<string[]>;
+declare function createBrowserAnalysisRuntime(boot: DuckDBWasmBootResult, options?: {
+  schema?: string;
+  version?: number | string;
+  attachedTables?: readonly string[];
+}): BrowserAnalysisRuntime;
+export { type AnalyzeResult, type AttachParquetTablesOptions, type AttachParquetUrlTablesOptions, type AttachSingleTableOptions, type AttachedTablesHandle, type BootDuckDBWasmOptions, type BrowserAnalysisRuntime, type BrowserParquetFile, type BrowserParquetTable, type BrowserParquetUrlTable, type BrowserQueryRunner, type ComparisonMode, type DuckDBWasmBootResult, type DuckDBWasmClient, DuckDBWasmDatabase, type DuckDBWasmDrizzleDatabase, type EngineConfig, type InsightRunner, type InsightRunnerOptions, type QueryResult, type ResolveWindowOptions, type ResolvedWindow, type Schema, type ScopedRunnerOptions, type StrikingMomentumOptions, type StrikingMomentumRow, type TableScope, type WindowPreset, attachParquetTables, attachParquetUrlTables, attachSingleTable, bootDuckDBWasm, browserResolverAdapter, countries, createBrowserAnalysisRuntime, createClient, createDuckDBBundlesFromBase, createEngine, createInsightRunner, devices, drizzle, keywords, listAttachedTables, mergeScope, page_keywords, pages, resolveWindow, schema, scopeFor, strikingMomentum };

package/dist/index.mjs

@@ -0,0 +1,370 @@
+import { arrowToRows } from "@gscdump/engine/arrow";
+import { DefaultLogger, NoopLogger, createTableRelationsHelpers, entityKind, extractTablesRelationalConfig, fillPlaceholders, sql } from "drizzle-orm";
+import { PgDatabase, PgDialect, PgPreparedQuery, PgSession } from "drizzle-orm/pg-core";
+import { createSqlQuerySource, pgResolverAdapter as browserResolverAdapter } from "@gscdump/engine/resolver";
+import { toIsoDate } from "gscdump";
+import { countries, devices, drizzleSchema as schema, keywords, page_keywords, pages } from "@gscdump/engine/schema";
+import { createScopedHelpers } from "@gscdump/engine/scope";
+import { runAnalyzerFromSource } from "@gscdump/engine/analyzer";
+import { createAttachedTableSource } from "@gscdump/engine/source";
+import { sqlEscape } from "@gscdump/engine/sql";
+import { resolveWindow } from "@gscdump/engine/period";
+async function createClient(db, conn) {
+	return {
+		db,
+		conn,
+		async query(sql, params = []) {
+			if (params.length === 0) return arrowToRows(await conn.query(sql));
+			const stmt = await conn.prepare(sql);
+			try {
+				return arrowToRows(await stmt.query(...params));
+			} finally {
+				stmt.close();
+			}
+		},
+		async close() {
+			await conn.close();
+		}
+	};
+}
+var DuckDBWasmPreparedQuery = class extends PgPreparedQuery {
+	static [entityKind] = "DuckDBWasmPreparedQuery";
+	constructor(client, query, logger, queryMetadata, cache) {
+		super(query, cache, queryMetadata);
+		this.client = client;
+		this.logger = logger;
+	}
+	async execute(placeholderValues = {}) {
+		const params = fillPlaceholders(this.query.params, placeholderValues);
+		this.logger.logQuery(this.query.sql, params);
+		return await (await this.client).query(this.query.sql, params);
+	}
+	async all(placeholderValues = {}) {
+		const params = fillPlaceholders(this.query.params, placeholderValues);
+		this.logger.logQuery(this.query.sql, params);
+		return await (await this.client).query(this.query.sql, params);
+	}
+};
+var DuckDBWasmSession = class extends PgSession {
+	static [entityKind] = "DuckDBWasmSession";
+	logger;
+	cache;
+	constructor(client, dialect, _schema, options = {}) {
+		super(dialect);
+		this.client = client;
+		this.options = options;
+		this.logger = options.logger ?? new NoopLogger();
+		this.cache = options.cache;
+	}
+	prepareQuery(query, _fields, _name, _isResponseInArrayMode, _customResultMapper, queryMetadata) {
+		return new DuckDBWasmPreparedQuery(this.client, query, this.logger, queryMetadata, this.cache);
+	}
+	async query(sql, params) {
+		this.logger.logQuery(sql, params);
+		return (await this.client).query(sql, params);
+	}
+	transaction(_transaction, _config) {
+		throw new Error("Transactions are not supported by the DuckDB-WASM drizzle adapter. The analytics workload is read-only; if transactions become necessary, implement PgSession.transaction() in @gscdump/engine-duckdb-wasm.");
+	}
+};
+var DuckDBWasmDatabase = class extends PgDatabase {
+	static [entityKind] = "DuckDBWasmDatabase";
+};
+function drizzle(client, config = {}) {
+	const dialect = new PgDialect({ casing: config.casing });
+	const clientPromise = Promise.resolve(client);
+	let logger;
+	if (config.logger === true) logger = new DefaultLogger();
+	else if (config.logger !== false) logger = config.logger;
+	let schema;
+	if (config.schema) {
+		const tablesConfig = extractTablesRelationalConfig(config.schema, createTableRelationsHelpers);
+		schema = {
+			fullSchema: config.schema,
+			schema: tablesConfig.tables,
+			tableNamesMap: tablesConfig.tableNamesMap
+		};
+	}
+	const db = new DuckDBWasmDatabase(dialect, new DuckDBWasmSession(clientPromise, dialect, schema, { logger }), schema);
+	db.$client = clientPromise;
+	return db;
+}
+function createEngine(config) {
+	const { runner } = config;
+	return createSqlQuerySource({
+		name: "browser",
+		adapter: browserResolverAdapter,
+		execute: (sql, params) => runner.query(sql, params),
+		extraCapabilities: { attachedTables: true }
+	});
+}
+async function strikingMomentum(runner, opts = {}) {
+	const windowDays = opts.windowDays ?? 90;
+	const anchor = opts.anchor ?? toIsoDate(/* @__PURE__ */ new Date());
+	const minPrior = opts.minPriorImpressions ?? 10;
+	const minRecent = opts.minRecentImpressions ?? 50;
+	const limit = opts.limit ?? 20;
+	const windowExpr = sql`
+    WITH pk AS (
+      SELECT
+        query,
+        url,
+        ${page_keywords.date} AS date,
+        ${page_keywords.impressions} AS impressions,
+        ${page_keywords.sum_position} AS sum_position,
+        CASE
+          WHEN ${page_keywords.date} >= (DATE ${sql.raw(`'${anchor}'`)} - INTERVAL ${sql.raw(`${windowDays}`)} DAY)
+          THEN 'recent' ELSE 'prior'
+        END AS period
+      FROM ${page_keywords}
+      WHERE ${page_keywords.date} >= (DATE ${sql.raw(`'${anchor}'`)} - INTERVAL ${sql.raw(`${windowDays * 2}`)} DAY)
+        AND ${page_keywords.date} <  (DATE ${sql.raw(`'${anchor}'`)} + INTERVAL 1 DAY)
+    ),
+    agg AS (
+      SELECT
+        query, url, period,
+        SUM(impressions) AS impr,
+        SUM(sum_position) / NULLIF(SUM(impressions), 0) + 1 AS weighted_pos
+      FROM pk
+      GROUP BY query, url, period
+    ),
+    paired AS (
+      SELECT
+        query, url,
+        MAX(CASE WHEN period = 'recent' THEN impr END) AS recent_impr,
+        MAX(CASE WHEN period = 'recent' THEN weighted_pos END) AS recent_pos,
+        MAX(CASE WHEN period = 'prior' THEN impr END) AS prior_impr,
+        MAX(CASE WHEN period = 'prior' THEN weighted_pos END) AS prior_pos
+      FROM agg
+      GROUP BY query, url
+    ),
+    best AS (
+      SELECT
+        query, url, recent_impr, recent_pos, prior_impr, prior_pos,
+        ROW_NUMBER() OVER (PARTITION BY query ORDER BY recent_impr DESC NULLS LAST) AS rn
+      FROM paired
+      WHERE prior_impr >= ${minPrior} AND recent_impr >= ${minRecent}
+    )
+    SELECT
+      query, url,
+      recent_impr, recent_pos, prior_impr, prior_pos,
+      (prior_pos - recent_pos)
+        * LN(recent_impr + 1)
+        * CASE WHEN recent_pos BETWEEN 8 AND 20 THEN 1.5 ELSE 1.0 END
+      AS momentum_score
+    FROM best
+    WHERE rn = 1
+    ORDER BY momentum_score DESC NULLS LAST
+    LIMIT ${limit}
+  `;
+	return await runner.db.execute(windowExpr);
+}
+async function createInsightRunner(opts) {
+	const client = await createClient(opts.db, opts.conn);
+	const clientPromise = Promise.resolve(client);
+	return {
+		db: drizzle(clientPromise, {
+			schema,
+			logger: opts.logger
+		}),
+		client: clientPromise,
+		close: () => client.close()
+	};
+}
+const { scopeFor, mergeScope } = createScopedHelpers(schema);
+function fileName(table, index, provided) {
+	return provided ?? `${table}_${index}.parquet`;
+}
+function readParquetViewSql(schema, table, files) {
+	return `CREATE OR REPLACE VIEW ${schema}.${table} AS SELECT * FROM read_parquet([${files.map((name) => `'${sqlEscape(name)}'`).join(", ")}], union_by_name = true)`;
+}
+function createDuckDBBundlesFromBase(baseUrl, options = {}) {
+	const base = baseUrl.replace(/\/+$/, "");
+	const bundles = {
+		mvp: {
+			mainModule: `${base}/duckdb-mvp.wasm`,
+			mainWorker: `${base}/duckdb-browser-mvp.worker.js`
+		},
+		eh: {
+			mainModule: `${base}/duckdb-eh.wasm`,
+			mainWorker: `${base}/duckdb-browser-eh.worker.js`
+		}
+	};
+	if (options.includeCoi) bundles.coi = {
+		mainModule: `${base}/duckdb-coi.wasm`,
+		mainWorker: `${base}/duckdb-browser-coi.worker.js`,
+		pthreadWorker: `${base}/duckdb-browser-coi.pthread.worker.js`
+	};
+	return bundles;
+}
+async function bootDuckDBWasm(options = {}) {
+	const { getJsDelivrBundles, selectBundle, AsyncDuckDB, ConsoleLogger } = 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);
+	await db.instantiate(bundle.mainModule, bundle.pthreadWorker);
+	URL.revokeObjectURL(workerUrl);
+	return {
+		db,
+		conn: await db.connect()
+	};
+}
+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 attachParquetUrlTables(options) {
+	const { db, conn, tables, fetch: fetchImpl = globalThis.fetch.bind(globalThis), schema = "main", fetchInit, version, onFileAttached } = options;
+	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
+		});
+	}
+	const tableFailures = /* @__PURE__ */ new Map();
+	const total = flat.length;
+	await Promise.all(flat.map(async ({ table, url, index }) => {
+		if (tableFailures.has(table)) return;
+		await fetchImpl(url, fetchInit).then(async (response) => {
+			if (!response.ok) throw new Error(`fetch ${url} failed: ${response.status}`);
+			const bytes = new Uint8Array(await response.arrayBuffer());
+			await db.registerFileBuffer(fileName(table, index), bytes);
+			onFileAttached?.({
+				table,
+				index,
+				total
+			});
+		}).catch((err) => {
+			tableFailures.set(table, err instanceof Error ? err : new Error(String(err)));
+		});
+	}));
+	const attached = [];
+	for (const table of Object.keys(counts)) {
+		if (tableFailures.has(table)) continue;
+		const names = [];
+		for (let i = 0; i < counts[table]; i++) names.push(fileName(table, i));
+		await conn.query(readParquetViewSql(schema, table, names));
+		attached.push(table);
+	}
+	if (tableFailures.size > 0) for (const [table, err] of tableFailures) console.warn(`[gscdump/engine-duckdb-wasm] dropped table "${table}" — ${err.message}`);
+	return {
+		version,
+		tables: attached,
+		schema,
+		async detach() {
+			for (const table of attached) await conn.query(`DROP VIEW IF EXISTS ${schema}.${table}`);
+		}
+	};
+}
+async function attachSingleTable(options) {
+	const { db, conn, table, urls, fetch: fetchImpl = globalThis.fetch.bind(globalThis), schema = "main", fetchInit } = options;
+	if (urls.length === 0) return;
+	await Promise.all(urls.map(async (url, index) => {
+		const response = await fetchImpl(url, fetchInit);
+		if (!response.ok) throw new Error(`fetch ${url} failed: ${response.status}`);
+		const bytes = new Uint8Array(await response.arrayBuffer());
+		await db.registerFileBuffer(fileName(table, index), bytes);
+	}));
+	const names = urls.map((_, i) => fileName(table, i));
+	await conn.query(readParquetViewSql(schema, table, names));
+}
+async function listAttachedTables(conn, schema = "main") {
+	return arrowToRows(await conn.query(`SELECT table_name FROM information_schema.tables WHERE table_schema = '${sqlEscape(schema)}'`)).map((r) => String(r.table_name));
+}
+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();
+	async function cancelOnAbort(signal, work) {
+		if (!signal) return work;
+		if (signal.aborted) {
+			conn.cancelSent().catch(() => {});
+			throw signal.reason ?? new DOMException("aborted", "AbortError");
+		}
+		const onAbort = () => {
+			conn.cancelSent().catch(() => {});
+		};
+		signal.addEventListener("abort", onAbort, { once: true });
+		try {
+			return await work;
+		} finally {
+			signal.removeEventListener("abort", onAbort);
+		}
+	}
+	async function runParameterized(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 runParameterized(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 runParameterized(sql, bindParams, innerSignal ?? signal));
+				} }, {
+					schema,
+					signal,
+					attachedTables
+				}), params, registry);
+				return {
+					results: result.results,
+					meta: result.meta,
+					queryMs: performance.now() - t0
+				};
+			};
+			const next = chain.then(run, run);
+			chain = next.catch(() => {});
+			return next;
+		},
+		isStale(expected) {
+			return expected !== version;
+		},
+		setVersion(next) {
+			version = next;
+		},
+		setAttachedTables(next) {
+			attachedTables = next;
+		},
+		async close() {
+			await conn.close();
+			await db.terminate();
+		}
+	};
+}
+export { DuckDBWasmDatabase, attachParquetTables, attachParquetUrlTables, attachSingleTable, bootDuckDBWasm, browserResolverAdapter, countries, createBrowserAnalysisRuntime, createClient, createDuckDBBundlesFromBase, createEngine, createInsightRunner, devices, drizzle, keywords, listAttachedTables, mergeScope, page_keywords, pages, resolveWindow, schema, scopeFor, strikingMomentum };

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@gscdump/engine-duckdb-wasm",
+  "type": "module",
+  "version": "0.7.2",
+  "description": "DuckDB-WASM engine adapter for @gscdump/analysis — typed browser analytics against parquet via R2.",
+  "author": {
+    "name": "Harlan Wilton",
+    "email": "harlan@harlanzw.com",
+    "url": "https://harlanzw.com/"
+  },
+  "license": "MIT",
+  "funding": "https://github.com/sponsors/harlan-zw",
+  "homepage": "https://github.com/harlan-zw/gscdump/tree/main/packages/engine-duckdb-wasm#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/harlan-zw/gscdump.git",
+    "directory": "packages/engine-duckdb-wasm"
+  },
+  "bugs": {
+    "url": "https://github.com/harlan-zw/gscdump/issues"
+  },
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "peerDependencies": {
+    "@duckdb/duckdb-wasm": "^1.32.0"
+  },
+  "peerDependenciesMeta": {
+    "@duckdb/duckdb-wasm": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "drizzle-orm": "^0.45.2",
+    "@gscdump/engine": "0.7.2",
+    "gscdump": "0.7.2"
+  },
+  "devDependencies": {
+    "@duckdb/duckdb-wasm": "^1.32.0",
+    "vitest": "^4.1.5"
+  },
+  "scripts": {
+    "build": "obuild",
+    "dev": "obuild --stub",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest"
+  }
+}