@fjader/svelte 0.2.4 → 0.2.5

package/dist/query-engine/categorical-identity.d.ts

@@ -60,6 +60,40 @@ export interface IdentityExec {
     exec(sql: string | string[]): Promise<void>;
     /** Rows as plain objects. Callers adapt whatever their driver returns. */
     queryRows(sql: string): Promise<Array<Record<string, unknown>>>;
+    /**
+     * Whether `table` is known to be a base table (not a view). Only then is a
+     * column's cardinality read from its statistics (#cardinalityFromStats):
+     * on a view, `stats(col) … LIMIT 1` runs the view, and a filtered view
+     * reports its base column's statistics. Absent: never.
+     *
+     * About the table's TYPE, not where it is stored: a table in an attached
+     * file or remote database answers yes (its statistics are metadata either
+     * way). Not a "fast source" test: routing asks that separately
+     * (SourceRouting), and must not reuse this.
+     */
+    isBaseTable?(table: string): boolean;
+    /**
+     * Run statements as one message, returning the last one's rows (the
+     * engine's execBatch). Absent: they run one by one through exec and
+     * queryRows, with the same result.
+     */
+    execBatch?(statements: string[]): Promise<Array<Record<string, unknown>>>;
+    /**
+     * Debug: told of every ensureColumns call (the table, the fields asked for,
+     * performance.now()), before anything is deduplicated. For measuring when
+     * marks ask, e.g. whether one table's fields arrive close enough together
+     * to share a drain.
+     */
+    onRequest?(table: string, fields: string[], time: number): void;
+    /** Debug: one pass of a table's drain started, with the fields it took. */
+    onDrain?(table: string, fields: string[], time: number): void;
+    /**
+     * Whether anything listens to onRequest and onDrain. Checked first, so with
+     * no listener their arguments (a field list, a timestamp) are never built.
+     * The callbacks fire ONLY when this returns true: a host that implements
+     * them must implement this too, or it is never called.
+     */
+    observing?(): boolean;
 }
 /**
  * A thing that can have an identity: a source column, or a fixed SQL expression
@@ -290,14 +324,6 @@ export declare class CategoricalIdentity {
      * before a reset names a row of a dropped dim, and is ignored.
      */
     releaseSynthetic(synthetic: SyntheticId): void;
-    /**
-     * Re-read the dim into the field's value array, mutating in place.
-     *
-     * Re-reading the whole dim rather than only the new rows: categorical
-     * cardinality is small, this runs once per (field, table) pair at setup, and
-     * a full read cannot drift out of sync with the ids the way an incremental
-     * one can if an append is ever missed.
-     */
     /**
      * Bumped whenever a dim's rows change: a table folding in, an Other bucket
      * reserved, a reset. A query that reads a dim (dense padding, an id join)

package/dist/query-engine/categorical-identity.js

@@ -304,19 +304,6 @@ export class CategoricalIdentity {
     presentIds(field, table) {
         return this.#dims.get(field)?.present.get(table)?.ids ?? null;
     }
-    /**
-     * Record which of the dim's ids `table` holds: the ids of its distinct values,
-     * joined as the view joins (NULL to a NULL row, never to a synthetic one).
-     * Once per table, when it folds in.
-     */
-    async #recordPresent(dim, table, expr, src) {
-        const name = `${dim.name}_t_${identityToken(table)}`;
-        await this.#exec.exec(`CREATE OR REPLACE TABLE ${quote(name)} AS ` +
-            `SELECT DISTINCT d.id FROM (SELECT DISTINCT ${expr} AS v FROM ${src}) s ` +
-            `JOIN ${quote(dim.name)} d ON s.v IS NOT DISTINCT FROM d.value AND d.label IS NULL`);
-        const rows = await this.#exec.queryRows(`SELECT id FROM ${quote(name)}`);
-        dim.present.set(table, { name, ids: new Set(rows.map((r) => Number(r.id))) });
-    }
     /** Name of the view that carries id columns for `table`. */
     viewTable(table) {
         return `${identityToken(table)}_v_s${this.#session}`;
@@ -382,6 +369,9 @@ export class CategoricalIdentity {
         const categorical = (fields.categorical ?? []).map(asField);
         if (categorical.length === 0)
             return;
+        if (this.#exec.observing?.()) {
+            this.#exec.onRequest?.(table, categorical.map((f) => f.key), performance.now());
+        }
         let entry = this.#views.get(table);
         if (!entry) {
             entry = { current: new Set(), pending: new Set(), inflight: null, failures: new Map() };
@@ -468,6 +458,10 @@ export class CategoricalIdentity {
                     return;
                 const batch = [...entry.pending];
                 entry.pending.clear();
+                // Per pass: a request arriving during the first build is a second
+                // pass (and a second view build) inside this same call.
+                if (this.#exec.observing?.())
+                    this.#exec.onDrain?.(table, batch, performance.now());
                 const succeeded = [];
                 for (const field of batch) {
                     try {
@@ -650,55 +644,83 @@ export class CategoricalIdentity {
         // The value expression: a quoted column, or a fixed SQL expression. Both
         // are evaluated with only the source table in scope.
         const expr = dim.sql;
-        await this.#checkCardinality(field, expr, src);
-        if (dim.tables.size === 0) {
-            // `label` is NULL for every real value and carries the text for a
-            // synthetic one (see reserveSynthetic). It exists because `value` takes
-            // the SOURCE column's type: on a band axis over a year or a rating
-            // there is no INTEGER that means "Other", and writing the string into
-            // that column is a conversion error, not a fallback.
-            await this.#exec.exec(`CREATE TABLE IF NOT EXISTS ${dimName} AS ` +
-                `SELECT value, NULL::VARCHAR AS label, ` +
-                `(ROW_NUMBER() OVER (ORDER BY value NULLS LAST) - 1)::INT AS id ` +
-                `FROM (SELECT DISTINCT ${expr} AS value FROM ${src})`);
-            // A second statement: CTAS cannot carry a constraint. `value` is unique
-            // by construction here (DISTINCT) and on append (WHERE NOT EXISTS), but
-            // reserveSynthetic is a writer that could break it, and a duplicate
-            // value does not tie-break — #createView joins ON t.field = d.value, so
-            // it FANS OUT every matching source row in every query against the
-            // view. Cheap insurance against a future writer forgetting.
-            //
-            // Synthetic rows hold value NULL, and SQL treats NULLs as distinct
-            // under a unique index, so any number of them coexist here — verified
-            // against DuckDB rather than assumed.
-            await this.#exec.exec(`CREATE UNIQUE INDEX IF NOT EXISTS ${quote(`${dim.name}_value_uq`)} ON ${dimName}(value)`);
-        }
-        else {
-            // Columns named rather than positional: the table has three of them and
-            // a positional INSERT would silently put the id into `label`.
-            await this.#exec.exec(`INSERT INTO ${dimName} (value, label, id) ` +
-                `SELECT s.v, NULL, ((SELECT COALESCE(MAX(id), -1) FROM ${dimName}) + ` +
-                `ROW_NUMBER() OVER (ORDER BY s.v NULLS LAST))::INT ` +
-                `FROM (SELECT DISTINCT ${expr} AS v FROM ${src}) s ` +
-                // IS NOT DISTINCT FROM, so a second table's NULLs find the NULL row
-                // (NULL = NULL is never true, and `=` appended one per table). The
-                // label test keeps a synthetic row, also value NULL, from passing
-                // for it.
-                `WHERE NOT EXISTS (SELECT 1 FROM ${dimName} d ` +
-                `WHERE d.value IS NOT DISTINCT FROM s.v AND d.label IS NULL)`);
-        }
+        await this.#checkCardinality(field, expr, src, table);
+        // The field's statements as ONE message (#batch): sent one by one, each
+        // step went to the back of the queue, behind every other mark's reads
+        // sent meanwhile; at 2M rows the categorical charts trailed the others
+        // by 420-500 ms. The last statement returns the values the JS cache
+        // needs, and this table's present ids with them.
+        const first = dim.tables.size === 0;
+        const presentName = `${dim.name}_t_${identityToken(table)}`;
+        const present = quote(presentName);
+        // `label` is NULL for every real value and carries the text for a
+        // synthetic one (see reserveSynthetic). It exists because `value` takes the
+        // SOURCE column's type: on a band axis over a year or a rating there is no
+        // INTEGER that means "Other", and writing the string into that column is a
+        // conversion error, not a fallback.
+        const statements = first
+            ? [
+                `CREATE TABLE IF NOT EXISTS ${dimName} AS ` +
+                    `SELECT value, NULL::VARCHAR AS label, ` +
+                    `(ROW_NUMBER() OVER (ORDER BY value NULLS LAST) - 1)::INT AS id ` +
+                    `FROM (SELECT DISTINCT ${expr} AS value FROM ${src})`,
+                // A second statement: CTAS cannot carry a constraint. `value` is
+                // unique by construction here (DISTINCT) and on append (WHERE NOT
+                // EXISTS), but reserveSynthetic is a writer that could break it, and
+                // a duplicate value does not tie-break: #createView joins ON
+                // t.field = d.value, so it FANS OUT every matching source row in
+                // every query against the view. Synthetic rows hold value NULL, and
+                // SQL treats NULLs as distinct under a unique index, so any number of
+                // them coexist (verified against DuckDB).
+                `CREATE UNIQUE INDEX IF NOT EXISTS ${quote(`${dim.name}_value_uq`)} ON ${dimName}(value)`,
+                // The table that built the dim holds every real row of it (`chain`
+                // serializes a dim's work, so only one table takes this branch): its
+                // present ids are the real rows, no scan (the NULL row has no label
+                // and is present, as the join finds it; a synthetic row has one).
+                `CREATE OR REPLACE TABLE ${present} AS SELECT id FROM ${dimName} WHERE label IS NULL`,
+                `SELECT id, value, label FROM ${dimName} ORDER BY id`
+            ]
+            : [
+                // Columns named rather than positional: a positional INSERT would
+                // silently put the id into `label`. IS NOT DISTINCT FROM, so a second
+                // table's NULLs find the NULL row; the label test keeps a synthetic
+                // row, also value NULL, from passing for it.
+                `INSERT INTO ${dimName} (value, label, id) ` +
+                    `SELECT s.v, NULL, ((SELECT COALESCE(MAX(id), -1) FROM ${dimName}) + ` +
+                    `ROW_NUMBER() OVER (ORDER BY s.v NULLS LAST))::INT ` +
+                    `FROM (SELECT DISTINCT ${expr} AS v FROM ${src}) s ` +
+                    `WHERE NOT EXISTS (SELECT 1 FROM ${dimName} d ` +
+                    `WHERE d.value IS NOT DISTINCT FROM s.v AND d.label IS NULL)`,
+                // An appending table holds a subset: the ids of its distinct values,
+                // joined as the view joins.
+                `CREATE OR REPLACE TABLE ${present} AS ` +
+                    `SELECT DISTINCT d.id FROM (SELECT DISTINCT ${expr} AS v FROM ${src}) s ` +
+                    `JOIN ${dimName} d ON s.v IS NOT DISTINCT FROM d.value AND d.label IS NULL`,
+                `SELECT id, value, label, id IN (SELECT id FROM ${present}) AS present ` +
+                    `FROM ${dimName} ORDER BY id`
+            ];
+        const rows = await this.#batch(statements);
+        // A reset while the batch ran: its DROPs queued behind it, so these rows
+        // are of dims that no longer exist. Applying them would fill the cleared
+        // state with stale ids.
+        if (this.#generation !== generation)
+            return;
         dim.tables.add(table);
-        await this.#refreshValues(field);
-        await this.#recordPresent(dim, table, expr, src);
-        // The gate above saw ONE table. The dim spans every table that registers
-        // the field, so two tables of 6k each pass it individually and produce a
-        // 12k dim — and the limit is a property of the dim, since that is what
-        // sizes the slot table and therefore what the shared buffer has to hold.
-        // Exact rather than approximate here: the rows exist, COUNT(*) on a
-        // categorical dim is trivial, and this is the number the error should
-        // quote.
+        this.#applyValues(field, rows);
+        const ids = first
+            ? rows.filter((r) => r.label == null).map((r) => Number(r.id))
+            : rows.filter((r) => r.present === true).map((r) => Number(r.id));
+        dim.present.set(table, { name: presentName, ids: new Set(ids) });
         this.#checkDimSize(dim, field, this.identity(field).values.length);
     }
+    /** Statements as one message (IdentityExec.execBatch), or one by one; the last one's rows. */
+    async #batch(statements) {
+        if (this.#exec.execBatch)
+            return this.#exec.execBatch(statements);
+        for (const stmt of statements.slice(0, -1))
+            await this.#exec.exec(stmt);
+        return this.#exec.queryRows(statements[statements.length - 1]);
+    }
     /**
      * Refuse a band axis with more distinct values than can render.
      *
@@ -708,23 +730,62 @@ export class CategoricalIdentity {
      * the setup path that already blocks on one. Here it costs a query only for fields
      * that actually get a dim, and it is where the refusal has to land anyway.
      *
-     * `approx_count_distinct` rather than `COUNT(DISTINCT …)`: one HyperLogLog
-     * pass with no materialization, which matters precisely for the runaway
-     * expression this exists to catch.
+     * For a plain column, its statistics first (#cardinalityFromStats): no scan.
+     * Otherwise `approx_count_distinct` rather than `COUNT(DISTINCT …)`: one
+     * HyperLogLog pass with no materialization, which matters precisely for the
+     * runaway expression this exists to catch.
      *
      * Neither syntax nor result type can answer this question — `year(ts)` is
      * numeric with a tiny distinct set, a CASE can have ten thousand branches —
      * so the count is the only honest gate.
      */
-    async #checkCardinality(field, expr, src) {
-        const rows = await this.#exec.queryRows(`SELECT approx_count_distinct(${expr}) AS n FROM ${src}`);
-        const n = Number(rows[0]?.n ?? 0);
+    async #checkCardinality(field, expr, src, table) {
+        const scan = async () => Number((await this.#exec.queryRows(`SELECT approx_count_distinct(${expr}) AS n FROM ${src}`))[0]
+            ?.n ?? 0);
+        const estimate = await this.#cardinalityFromStats(expr, src, table);
+        let n = estimate ?? (await scan());
+        // Statistics are never shrunk (deletes, updates), so an estimate over the
+        // limit can be stale: confirm it with the scan before refusing. A false
+        // refusal is user-visible; the scan runs only in this rare case.
+        if (estimate != null && n > MAX_IDENTITY_CARDINALITY)
+            n = await scan();
         if (n > MAX_IDENTITY_CARDINALITY) {
             throw new Error(`"${field}" has about ${n} distinct values in this table, over the ` +
                 `${MAX_IDENTITY_CARDINALITY} a categorical scale can render. Use a continuous ` +
                 `scale, bin the values, or reduce them with a transform.`);
         }
     }
+    /**
+     * A plain column's approximate distinct count from DuckDB's column
+     * statistics, without scanning: `stats(col)` reads what DuckDB keeps per
+     * column ("Approx Unique"). Measured on DuckDB-WASM: 1-3 ms, against
+     * 27-28 ms for approx_count_distinct over 2M rows; it agrees with the scan
+     * (167 and 167, 245 and 251). It can undercount a very large set (1.26M for
+     * 2M unique values): still far over the limit, and #checkDimSize counts
+     * the built dim exactly behind it. It can OVERcount, never shrinking after
+     * deletes, so an over-limit answer is confirmed by the scan
+     * (#checkCardinality).
+     *
+     * Base tables only (IdentityExec.isBaseTable): on a view, `stats … LIMIT 1`
+     * runs the view (a view that computes would then run twice, if the column
+     * has no estimate), and a filtered view reports its base column's
+     * statistics. Null for an expression field, a view, or statistics that say
+     * nothing: the caller scans as before.
+     */
+    async #cardinalityFromStats(expr, src, table) {
+        if (!/^"(?:[^"]|"")+"$/.test(expr))
+            return null;
+        if (!this.#exec.isBaseTable?.(table))
+            return null;
+        try {
+            const rows = await this.#exec.queryRows(`SELECT stats(${expr}) AS s FROM ${src} LIMIT 1`);
+            const match = /Approx Unique: (\d+)/.exec(String(rows[0]?.s ?? ''));
+            return match ? Number(match[1]) : null;
+        }
+        catch {
+            return null;
+        }
+    }
     /**
      * Refuse or warn on the DIM's size, which is what actually has to render.
      *
@@ -767,14 +828,6 @@ export class CategoricalIdentity {
                 `and a grid on that axis draws a line per value whether it is displayed or not.`);
         }
     }
-    /**
-     * Re-read the dim into the field's value array, mutating in place.
-     *
-     * Re-reading the whole dim rather than only the new rows: categorical
-     * cardinality is small, this runs once per (field, table) pair at setup, and
-     * a full read cannot drift out of sync with the ids the way an incremental
-     * one can if an append is ever missed.
-     */
     /**
      * Bumped whenever a dim's rows change: a table folding in, an Other bucket
      * reserved, a reset. A query that reads a dim (dense padding, an id join)
@@ -785,8 +838,20 @@ export class CategoricalIdentity {
         return this.#version;
     }
     #version = 0;
+    /**
+     * Re-read the dim into the field's value array, mutating in place.
+     *
+     * Re-reading the whole dim rather than only the new rows: categorical
+     * cardinality is small, this runs once per (field, table) pair at setup, and
+     * a full read cannot drift out of sync with the ids the way an incremental
+     * one can if an append is ever missed.
+     */
     async #refreshValues(field) {
         const rows = await this.#exec.queryRows(`SELECT id, value, label FROM ${quote(this.dimTable(field))} ORDER BY id`);
+        this.#applyValues(field, rows);
+    }
+    /** The dim's rows (`id, value, label`, in id order) into the JS cache. */
+    #applyValues(field, rows) {
         // Ordered by id and dense by construction, so position is the id — and
         // reset() derives value -> id from the same pass, so the two directions
         // cannot disagree.

package/dist/query-engine/debug/query-log.d.ts

@@ -0,0 +1,39 @@
+/**
+ * A statement log for measuring what reaches DuckDB: attach it to an engine,
+ * use the page, then read `report()` or `download()` the raw log.
+ *
+ * Built on `QueryEngine.observeStatements`, so it sees every statement the
+ * engine sends (queries, statements, DESCRIBE, Arrow inserts) with its class.
+ * Times are taken on the main thread when a statement is handed over and when
+ * it settles; while the main thread is busy (decoding, GPU uploads) they read
+ * high. The queue-wait estimate assumes each connection serves its statements
+ * first-in, first-out: a statement starts when it was sent or when the
+ * previous one ON ITS CONNECTION finished, whichever is later. Statements on a
+ * sliced lane interleave with the main connection's in the worker, so their
+ * "work" includes slices spent serving the other.
+ */
+import type { QueryEngine, StatementRecord } from '../QueryEngine';
+/** What a statement is for, from its text: a coarse grouping for reports. */
+export type StatementPurpose = 'describe' | 'ddl' | 'insert' | 'range' | 'data' | 'batch';
+export interface LoggedStatement extends StatementRecord {
+    purpose: StatementPurpose;
+    /** The first table the statement reads, or '?'. */
+    table: string;
+}
+export interface QueryLog {
+    readonly statements: readonly LoggedStatement[];
+    /** Print a summary to the console and return it as rows. */
+    report(): ReportRow[];
+    /** Download the raw log as JSON (to the browser's downloads folder). */
+    download(name: string, extra?: Record<string, unknown>): void;
+    reset(): void;
+    detach(): void;
+}
+export interface ReportRow {
+    group: string;
+    n: number;
+    workMs: number;
+    waitMs: number;
+}
+/** Attach a statement log to an engine. Costs nothing once detached. */
+export declare function attachQueryLog(engine: QueryEngine): QueryLog;

package/dist/query-engine/debug/query-log.js

@@ -0,0 +1,90 @@
+function purposeOf(record) {
+    if (record.kind === 'describe')
+        return 'describe';
+    if (record.kind === 'insert')
+        return 'insert';
+    if (record.kind === 'batch')
+        return 'batch';
+    const s = record.sql.trimStart().toUpperCase();
+    if (/^(CREATE|DROP|INSERT|ALTER|DELETE|UPDATE)/.test(s))
+        return 'ddl';
+    // A scalar summary: min/max aggregates, no GROUP BY, no window.
+    if (/^SELECT/.test(s) && !/GROUP BY/.test(s) && /(MIN|MAX)\(/.test(s) && !/ OVER \(/.test(s)) {
+        return 'range';
+    }
+    return 'data';
+}
+function tableOf(sql) {
+    const m = /FROM\s+"?([A-Za-z_][\w]*)"?/i.exec(sql);
+    return m ? m[1] : '?';
+}
+/** Attach a statement log to an engine. Costs nothing once detached. */
+export function attachQueryLog(engine) {
+    const statements = [];
+    /** Categorical identity requests, in order: when marks asked for which fields. */
+    const identityRequests = [];
+    const detachStatements = engine.observeStatements((record) => {
+        statements.push({ ...record, purpose: purposeOf(record), table: tableOf(record.sql) });
+    });
+    const detachIdentity = engine.observeIdentityRequests((request) => {
+        identityRequests.push(request);
+    });
+    /** Every preagg build step, in order (observeBuilds). Errors as text, for JSON. */
+    const builds = [];
+    const detachBuilds = engine.observeBuilds((event) => {
+        builds.push(event.error === undefined ? event : { ...event, error: String(event.error) });
+    });
+    const detach = () => {
+        detachStatements();
+        detachIdentity();
+        detachBuilds();
+    };
+    const report = () => {
+        const sorted = [...statements].sort((a, b) => a.start - b.start);
+        if (sorted.length === 0)
+            return [];
+        const lastEndOn = { main: 0, lane: 0 };
+        let lastEnd = 0;
+        const groups = new Map();
+        let work = 0;
+        for (const s of sorted) {
+            const conn = s.connection ?? 'main';
+            const start = Math.max(s.start, lastEndOn[conn]);
+            lastEndOn[conn] = Math.max(lastEndOn[conn], s.end);
+            lastEnd = Math.max(lastEnd, s.end);
+            const key = `${conn} ${s.class} ${s.purpose} ${s.table}`;
+            const g = groups.get(key) ?? { group: key, n: 0, workMs: 0, waitMs: 0 };
+            g.n++;
+            g.workMs += s.end - start;
+            g.waitMs += start - s.start;
+            work += s.end - start;
+            groups.set(key, g);
+        }
+        const span = lastEnd - sorted[0].start;
+        const rows = [...groups.values()]
+            .map((g) => ({ ...g, workMs: +g.workMs.toFixed(1), waitMs: +g.waitMs.toFixed(1) }))
+            .sort((a, b) => b.workMs - a.workMs);
+        console.log(`[query-log] ${sorted.length} statements, span ${span.toFixed(0)} ms, work ${work.toFixed(0)} ms`);
+        console.table(rows);
+        return rows;
+    };
+    const download = (name, extra = {}) => {
+        const json = JSON.stringify({ ...extra, statements, identityRequests, builds }, null, 1);
+        const a = document.createElement('a');
+        a.href = URL.createObjectURL(new Blob([json], { type: 'application/json' }));
+        a.download = name;
+        a.click();
+        URL.revokeObjectURL(a.href);
+    };
+    return {
+        statements,
+        report,
+        download,
+        reset: () => {
+            statements.length = 0;
+            identityRequests.length = 0;
+            builds.length = 0;
+        },
+        detach
+    };
+}

package/dist/query-engine/duckdb.d.ts

@@ -1,21 +1,68 @@
 /**
  * DuckDB-WASM initialization — replaces mosaic-core's wasmConnector.
  *
- * Returns a Promise<DuckDBConnection> suitable for passing to setQueryContext().
- * Uses jsdelivr CDN bundles (same as mosaic-core's wasmConnector).
+ * initDuckDB() returns a Promise<DuckDBConnection> suitable for passing to
+ * setQueryContext(). It loads the jsDelivr bundles unless the app passes its own.
  *
- * Uses the fast IPC query path: bypasses duckdb-wasm's Arrow JS deserialization
- * and returns raw Arrow IPC bytes. QueryEngine decodes them with flechette for
- * zero-copy typed arrays that go straight to GPU buffers.
+ * connectionFrom() adapts a duckdb-wasm connection the app created itself, for
+ * apps that need the AsyncDuckDB instance (registerFileBuffer, extensions, …).
  *
- * Safe to call during SSR — returns a permanently pending promise on the
- * server. The component re-runs on the client where Worker is available.
+ * Both use the fast IPC query path: bypasses duckdb-wasm's Arrow JS
+ * deserialization and returns raw Arrow IPC bytes. QueryEngine decodes them with
+ * flechette into typed arrays for the GPU buffers. These are views on the IPC
+ * bytes only up to one record batch: DuckDB-WASM writes a batch per DuckDB vector
+ * (~2k rows), and flechette concatenates a column that spans several.
  */
+import type { AsyncDuckDBConnection, DuckDBBundles } from '@duckdb/duckdb-wasm';
 import type { DuckDBConnection } from './QueryEngine';
+/**
+ * How long the worker runs a sliced statement before serving other messages:
+ * a quick query on another connection waits at most about this long behind a
+ * slow one. Measured in Phase 0: 1 ms at 5 ms, ~50 ms at the default (~100 ms).
+ */
+export declare const QUERY_POLLING_INTERVAL_MS = 5;
+export interface InitDuckDBOptions {
+    /**
+     * DuckDB-WASM bundles to choose from, e.g. served by the app itself:
+     *
+     *   import mvpWasm from '@duckdb/duckdb-wasm/dist/duckdb-mvp.wasm?url';
+     *   import mvpWorker from '@duckdb/duckdb-wasm/dist/duckdb-browser-mvp.worker.js?url';
+     *   …
+     *   initFjader({ bundles: { mvp: { mainModule: mvpWasm, mainWorker: mvpWorker }, eh: … } });
+     *
+     * Only `mvp` is required; selectBundle picks `eh`/`coi` when given and supported.
+     * Relative URLs resolve against the page. Defaults to the jsDelivr bundles.
+     */
+    bundles?: DuckDBBundles;
+}
+/**
+ * Adapt a duckdb-wasm connection to the DuckDBConnection QueryEngine expects,
+ * with the fast IPC query path, and sliced lanes: further connections on the
+ * same database (`openSlicedLane`).
+ *
+ *   const db = new duckdb.AsyncDuckDB(logger, worker);
+ *   await db.instantiate(…);
+ *   await db.open({ query: { queryPollingInterval: 5 } }); // short slices, see below
+ *   await db.registerFileBuffer('cached.parquet', bytes);
+ *   initFjader(connectionFrom(await db.connect(), { pollingIntervalMs: 5 }));
+ *
+ * Sliced statements run in slices of the database's `queryPollingInterval`.
+ * At DuckDB's default (~100 ms) a quick query can wait ~50 ms behind a slow
+ * one; open the database with ~5 ms, as `initDuckDB` does. It is a setting of
+ * the database, which this function cannot change or read: say what you set
+ * as `pollingIntervalMs`. Without it, lanes measure their slices and warn if
+ * they run long.
+ */
+export declare function connectionFrom(conn: AsyncDuckDBConnection, options?: {
+    pollingIntervalMs?: number;
+}): DuckDBConnection;
 /**
  * Initialize DuckDB-WASM and return a connection.
  *
+ * Safe to call during SSR — returns a permanently pending promise on the
+ * server. The component re-runs on the client where Worker is available.
+ *
  * Usage:
  *   const { queryEngine } = setQueryContext(initDuckDB());
  */
-export declare function initDuckDB(): Promise<DuckDBConnection>;
+export declare function initDuckDB(options?: InitDuckDBOptions): Promise<DuckDBConnection>;