@makoai/app-sdk 2.7.3 → 2.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -29,8 +29,8 @@ import { useQuery, useDuckDB, useSearchParams, useTheme } from "@makoai/app-sdk"
29
29
  // Rows of bindings/<name>.sql, materialized to parquet by Mako.
30
30
  const { data, loading, error } = useQuery("latest_sales");
31
31
 
32
- // Analytical SQL over every binding (DuckDB-WASM in the browser; table
33
- // names are binding names).
32
+ // Analytical SQL over the bindings (DuckDB-WASM in the browser; table
33
+ // names are binding names). Only the bindings the SQL names download.
34
34
  const totals = useDuckDB("select country, sum(revenue) r from latest_sales group by 1");
35
35
 
36
36
  // Rematerialize on demand: re-runs the binding's query on the warehouse,
@@ -55,9 +55,75 @@ or 502 with the query's error.
55
55
  `useTheme` follows the OS preference. Theme tokens (`--background`,
56
56
  `--chart-1`, …) match the ones the scaffold's `styles.css` declares.
57
57
 
58
+ ### Custom data work: one engine (2.8)
59
+
60
+ Never import `@duckdb/duckdb-wasm`, `hyparquet` or `apache-arrow` parquet
61
+ readers in an app. Use the page's engine through the SDK:
62
+
63
+ ```ts
64
+ import { getDuckDB, withConnection, ensureBinding, unloadBinding, fetchBindingBytes, useDuckDB } from "@makoai/app-sdk";
65
+
66
+ const big = useDuckDB("select lat, lng from listings", { format: "arrow" }); // data: Arrow Table
67
+ const table = await ensureBinding("valuations"); // loaded once, returns "valuations"
68
+ const n = await withConnection(c => c.query(`select count(*) from ${table}`));
69
+ await unloadBinding("valuations"); // free its memory
70
+ const bytes = await fetchBindingBytes("valuations", { onProgress: p => p && console.log(p.phase, p.bytes, p.bytesTotal) });
71
+ const db = await getDuckDB(); // shared: never close() or terminate()
72
+ await db.registerFileBuffer("valuations.parquet", bytes); // read_parquet with your own options
73
+ ```
74
+
75
+ ### Loading cost (2.8)
76
+
77
+ - `useDuckDB` downloads only the bindings its SQL names. A missed name (for
78
+ example `query_table('x')`) loads when DuckDB reports the table missing,
79
+ and the query re-runs. `SHOW TABLES` / `information_schema` load all.
80
+ - Each binding is decoded once into a DuckDB table and its file buffer is
81
+ freed. A refresh swaps the table in one commit, so a running query never
82
+ sees it missing. A table costs about 3x the parquet in memory (10 MB of
83
+ parquet, 149k rows: 33 MB).
84
+ - The DuckDB engine and its parquet extension start loading on the first
85
+ data hook render, in parallel with the first binding download.
86
+ - Rows decode column by column: 149k rows x 16 columns in 190 ms, down
87
+ from 740 ms. Values are unchanged (DATE as `YYYY-MM-DD`, TIMESTAMP as
88
+ ISO 8601, BigInt as Number when safe).
89
+
58
90
  Data arrives from `__data/<name>.parquet`, relative to the page — the same
59
91
  path in Mako's sandbox, in a published app, and on a laptop.
60
92
 
93
+ ### What a load is waiting on: `phase` (SDK ≥ 2.7.4)
94
+
95
+ `useQuery` and `useDuckDB` return `phase` while `loading` or `refreshing`,
96
+ plus `rowsWritten`, `bytes` and `bytesTotal` when known. Caption a progress
97
+ bar with `bindingPhaseLabel(...)`:
98
+
99
+ ```tsx
100
+ import { useQuery, bindingPhaseLabel } from "@makoai/app-sdk";
101
+
102
+ const q = useQuery("latest_sales");
103
+ if (q.loading) return <Spinner label={bindingPhaseLabel(q)} />;
104
+ // "Building from warehouse · 120,000 rows" → "Getting download link"
105
+ // → "Downloading · 3.1 MB of 10.0 MB" → "Loading into DuckDB" → "Running query"
106
+ ```
107
+
108
+ | Stage (`bindingPhaseStage`) | Phases | What is happening |
109
+ | --- | --- | --- |
110
+ | `building` | `queued`, `querying_warehouse`, `writing_parquet`, `uploading` | Mako runs the query on the warehouse. Seconds to minutes. Only a refresh, a laptop dev build or a sandbox live binding builds. |
111
+ | `linking` | `resolving`, `signing` | The file exists. Mako finds it and signs its download link. Under a second. |
112
+ | `downloading` | `downloading` | The browser fetches the parquet. |
113
+ | `loading` | `loading_duckdb` | DuckDB-WASM boots and registers the file. |
114
+ | `querying` | `running_sql` | Your SQL runs. |
115
+ | `waiting` | `requesting`, `checking` | Sent; the server has not said which yet. |
116
+
117
+ The SDK learns the server-side phases on the same request: it sends
118
+ `Accept: application/x-ndjson`, and a server that knows phases answers one
119
+ JSON event per line, ending with `{"phase":"ready", …}` (a stored file's
120
+ event carries the signed `url` and `timings`) or `{"phase":"failed",
121
+ "status", "error"}`. A server that predates this answers as before, and the
122
+ SDK still reports `requesting` → `downloading` → `loading_duckdb`.
123
+ `refreshBinding(name, { onProgress })` hears every phase of one refresh;
124
+ `useBindingProgress()` lists every pending binding. `RefreshAllButton`
125
+ captions each running source with its phase.
126
+
61
127
  ### Who is looking: `useViewer()`
62
128
 
63
129
  ```tsx
@@ -197,9 +263,11 @@ once, and polls it until the parquet is ready — so a query that runs for
197
263
  minutes is waited for instead of failing when a proxy cuts the request at
198
264
  100 s. `pollIntervalMs` / `buildTimeoutMs` tune the wait (1 s, 30 min).
199
265
 
200
- Results are cached under `node_modules/.mako-data/` for five minutes
201
- (`revalidateMs`; `?refresh` bypasses), next to a fingerprint of the text they
202
- were built from: after an edit the cache is never served, however long
266
+ Results are cached under `node_modules/.mako-data/` next to a fingerprint of
267
+ the text they were built from. A cached copy of the current text is served
268
+ at once. Once it is older than `revalidateMs` (five minutes), it is also
269
+ rebuilt in the background for the next load. `?refresh` waits for a
270
+ build. A copy from other text is never served: after an edit the cache is never served, however long
203
271
  `revalidateMs` is, and while the API is unreachable a stale copy is served
204
272
  only if it was built from the same text. It is `apply: "serve"` only —
205
273
  production builds never load it.
package/data-core.js ADDED
@@ -0,0 +1,212 @@
1
+ // Pure helpers behind @makoai/app-sdk's data hooks — no React and no
2
+ // DuckDB, so `node --test` can cover them without installing anything.
3
+
4
+ /** A SQL identifier, double-quoted (DuckDB folds case either way). */
5
+ export function quoteIdent(name) {
6
+ return '"' + String(name).replace(/"/g, '""') + '"';
7
+ }
8
+
9
+ /** A SQL string literal. */
10
+ export function quoteString(value) {
11
+ return "'" + String(value).replace(/'/g, "''") + "'";
12
+ }
13
+
14
+ // String literals and comments first (skipped), then quoted and bare
15
+ // identifiers (kept).
16
+ const SQL_TOKENS = /'(?:[^']|'')*'|--[^\n]*|\/\*[\s\S]*?\*\/|"((?:[^"]|"")+)"|([A-Za-z_][A-Za-z0-9_$]*)/g;
17
+
18
+ /**
19
+ * The staged bindings whose names appear as identifiers in `sql`. A hint,
20
+ * not a parse: a column that shares a binding's name costs one extra
21
+ * download; a reference it misses is caught by the retry on DuckDB's
22
+ * "Table with name … does not exist" error.
23
+ */
24
+ export function mentionedBindings(sql, names) {
25
+ if (!names.length) return [];
26
+ const byLower = new Map();
27
+ for (const n of names) {
28
+ const key = n.toLowerCase();
29
+ if (!byLower.has(key)) byLower.set(key, n);
30
+ }
31
+ const found = new Set();
32
+ for (const m of String(sql).matchAll(SQL_TOKENS)) {
33
+ const ident = m[1] != null ? m[1].replace(/""/g, '"') : m[2];
34
+ if (ident == null) continue;
35
+ const hit = byLower.get(ident.toLowerCase());
36
+ if (hit) found.add(hit);
37
+ }
38
+ return [...found];
39
+ }
40
+
41
+ // Queries that list tables instead of naming them (SHOW TABLES,
42
+ // information_schema, duckdb_tables() …) see every binding, as they did when
43
+ // all of them were registered up front.
44
+ const CATALOG_QUERY = /\b(?:information_schema|duckdb_(?:tables|columns|views|constraints|indexes)|sqlite_master|pg_catalog|show_tables)\b|\bshow\s+(?:all\s+)?tables\b/i;
45
+ export function readsCatalog(sql) {
46
+ return CATALOG_QUERY.test(String(sql));
47
+ }
48
+
49
+ /**
50
+ * The binding a DuckDB "Table with name X does not exist" error is about —
51
+ * X itself when the index lists it, else its case-insensitive match (DuckDB
52
+ * folds identifier case). null for any other error, or a name no binding has.
53
+ */
54
+ export function missingBinding(message, names) {
55
+ const m = /Table with name (.+?) does not exist/.exec(String(message));
56
+ if (!m) return null;
57
+ const table = m[1];
58
+ if (names.includes(table)) return table;
59
+ const lower = table.toLowerCase();
60
+ return names.find(n => n.toLowerCase() === lower) ?? null;
61
+ }
62
+
63
+ // Arrow → plain JS, with the types apps actually want. DuckDB hands DATE and
64
+ // TIMESTAMP columns to JS as epoch milliseconds; v1 apps (JSON over the wire)
65
+ // always saw strings, and a migrated formatDate() that did
66
+ // new Date(`${d}T00:00:00`) on a number threw and unmounted the whole app
67
+ // (apps.md §15.4). So: DATE → "YYYY-MM-DD", TIMESTAMP → ISO 8601, BigInt →
68
+ // Number when it fits. Everything else passes through untouched.
69
+ const DATE = 1;
70
+ const TIMESTAMP = 2;
71
+ const OTHER = 0;
72
+ function columnKind(field) {
73
+ const type = String(field.type);
74
+ if (type.startsWith("Date")) return DATE;
75
+ if (type.startsWith("Timestamp")) return TIMESTAMP;
76
+ return OTHER;
77
+ }
78
+
79
+ // Fast paths for the two column types that dominate decode time. Each
80
+ // reads Arrow's buffers directly and yields exactly what Arrow's getter
81
+ // would; a chunk it does not fully understand returns null and the column
82
+ // takes the general path (Arrow's own iterator).
83
+ const UTF8 = 5; // arrow Type.Utf8
84
+ const TIMESTAMP_TYPE = 10; // arrow Type.Timestamp
85
+ const MAX_SAFE = Number.MAX_SAFE_INTEGER;
86
+ let textDecoder = null;
87
+ function plainChunks(source, typeId) {
88
+ const chunks = source.data;
89
+ if (!Array.isArray(chunks) || !chunks.length) return null;
90
+ for (const d of chunks) {
91
+ if (!d || !d.type || d.type.typeId !== typeId || d.offset !== 0) return null;
92
+ if (d.nullCount > 0 && typeof d.getValid !== "function") return null;
93
+ }
94
+ return chunks;
95
+ }
96
+
97
+ // Utf8: Arrow runs a TextDecoder per cell. A chunk whose bytes are all
98
+ // ASCII decodes in one call and slices by offset — the same strings.
99
+ function asciiColumn(source, n) {
100
+ const chunks = plainChunks(source, UTF8);
101
+ if (!chunks) return null;
102
+ textDecoder ??= new TextDecoder();
103
+ const out = new Array(n);
104
+ let r = 0;
105
+ for (const d of chunks) {
106
+ const { values, valueOffsets, length } = d;
107
+ if (!(values instanceof Uint8Array) || !(valueOffsets instanceof Int32Array)) return null;
108
+ const start = valueOffsets[0];
109
+ const end = valueOffsets[length];
110
+ for (let i = start; i < end; i++) if (values[i] > 0x7f) return null;
111
+ const text = textDecoder.decode(values.subarray(start, end));
112
+ const nulls = d.nullCount > 0;
113
+ for (let i = 0; i < length && r < n; i++) {
114
+ out[r++] = nulls && !d.getValid(i)
115
+ ? null
116
+ : text.slice(valueOffsets[i] - start, valueOffsets[i + 1] - start);
117
+ }
118
+ }
119
+ return out;
120
+ }
121
+
122
+ // Timestamp: Arrow divides BigInts per cell (getTimestampMicrosecond is
123
+ // `Number(v / 1000n) + Number(v % 1000n) / 1000`). Within ±2^53 the same
124
+ // quotient and remainder are exact in doubles, so the same two IEEE
125
+ // operations give the same millisecond value. A value outside that range
126
+ // sends the column to the general path.
127
+ function timestampColumn(source, n) {
128
+ const chunks = plainChunks(source, TIMESTAMP_TYPE);
129
+ if (!chunks) return null;
130
+ const out = new Array(n);
131
+ let r = 0;
132
+ for (const d of chunks) {
133
+ const { values, length } = d;
134
+ if (!(values instanceof BigInt64Array)) return null;
135
+ const unit = d.type.unit; // 0 s, 1 ms, 2 µs, 3 ns
136
+ if (unit !== 0 && unit !== 1 && unit !== 2 && unit !== 3) return null;
137
+ const nulls = d.nullCount > 0;
138
+ for (let i = 0; i < length && r < n; i++) {
139
+ if (nulls && !d.getValid(i)) {
140
+ out[r++] = null;
141
+ continue;
142
+ }
143
+ const v = Number(values[i]);
144
+ if (v > MAX_SAFE || v < -MAX_SAFE) return null;
145
+ let ms;
146
+ if (unit === 0) ms = 1000 * v;
147
+ else if (unit === 1) ms = v;
148
+ else {
149
+ const div = unit === 2 ? 1000 : 1000000;
150
+ const rem = v % div;
151
+ ms = (v - rem) / div + rem / div;
152
+ }
153
+ out[r++] = new Date(ms).toISOString();
154
+ }
155
+ }
156
+ return out;
157
+ }
158
+
159
+ /**
160
+ * An Arrow table as `{ rows, fields }`: one plain object per row, keyed by
161
+ * column name, values normalized as above, at most `cap` rows.
162
+ *
163
+ * Column by column: each column's values come from Arrow's own vector
164
+ * iterator (the same getter a row proxy's `row[name]` calls), so the output
165
+ * is identical to walking `for (const row of table)` — without a Proxy trap
166
+ * and a field-name lookup per cell, and with each distinct DATE formatted
167
+ * once. 149k rows × 16 columns: 740 ms before, 190 ms after (Chromium).
168
+ */
169
+ export function toPlainRows(table, cap) {
170
+ const schemaFields = table.schema.fields;
171
+ const fields = schemaFields.map(f => f.name);
172
+ const limit = cap == null ? Infinity : cap;
173
+ const n = Math.max(0, Math.min(table.numRows, limit));
174
+ const rows = new Array(n);
175
+ for (let r = 0; r < n; r++) rows[r] = {};
176
+ for (let c = 0; c < fields.length; c++) {
177
+ const name = fields[c];
178
+ // A row proxy resolves a name to its FIRST column; a duplicated name
179
+ // reads that column's values (decoded with this column's type).
180
+ const source = table.getChildAt(fields.indexOf(name));
181
+ const kind = columnKind(schemaFields[c]);
182
+ let r = 0;
183
+ if (n === 0 || !source) {
184
+ for (; r < n; r++) rows[r][name] = undefined;
185
+ continue;
186
+ }
187
+ const fast =
188
+ kind === OTHER ? asciiColumn(source, n) : kind === TIMESTAMP ? timestampColumn(source, n) : null;
189
+ if (fast) {
190
+ for (; r < n; r++) rows[r][name] = fast[r];
191
+ continue;
192
+ }
193
+ const dates = kind === DATE ? new Map() : null;
194
+ for (const v of source) {
195
+ if (r >= n) break;
196
+ let out = v;
197
+ if (v != null) {
198
+ if (kind === DATE) {
199
+ out = dates.get(v);
200
+ if (out === undefined) {
201
+ out = new Date(Number(v)).toISOString().slice(0, 10);
202
+ dates.set(v, out);
203
+ }
204
+ } else if (kind === TIMESTAMP) out = new Date(Number(v)).toISOString();
205
+ else if (typeof v === "bigint" && v >= Number.MIN_SAFE_INTEGER && v <= Number.MAX_SAFE_INTEGER)
206
+ out = Number(v);
207
+ }
208
+ rows[r++][name] = out;
209
+ }
210
+ }
211
+ return { rows, fields };
212
+ }
package/index.d.ts CHANGED
@@ -1,5 +1,88 @@
1
1
  import type * as React from "react";
2
2
 
3
+ /**
4
+ * What a pending binding load is waiting on (SDK ≥ 2.7.4).
5
+ *
6
+ * - `requesting`: sent, the server has not said yet (or predates phases).
7
+ * - `queued`, `checking`, `querying_warehouse`, `writing_parquet`,
8
+ * `uploading`: Mako is BUILDING the file from the warehouse (seconds to
9
+ * minutes). Only a refresh, a laptop dev build or a sandbox live binding
10
+ * builds; a published app never builds on a read.
11
+ * - `resolving`, `signing`: the file exists; Mako is finding it and signing
12
+ * its download link (well under a second).
13
+ * - `downloading`, `loading_duckdb`, `running_sql`: the browser's own work.
14
+ */
15
+ export type BindingPhase =
16
+ | "requesting"
17
+ | "queued"
18
+ | "checking"
19
+ | "querying_warehouse"
20
+ | "writing_parquet"
21
+ | "uploading"
22
+ | "resolving"
23
+ | "signing"
24
+ | "downloading"
25
+ | "loading_duckdb"
26
+ | "running_sql";
27
+
28
+ /** The phases grouped by the wait a person cares about. */
29
+ export type BindingStage =
30
+ | "waiting"
31
+ | "building"
32
+ | "linking"
33
+ | "downloading"
34
+ | "loading"
35
+ | "querying";
36
+
37
+ /** One binding's progress while it loads or refreshes. */
38
+ export interface BindingProgress {
39
+ phase: BindingPhase;
40
+ /** Rows written so far while building; null when the server does not say. */
41
+ rowsWritten?: number | null;
42
+ /** Building: the file's size. Downloading: bytes received so far. */
43
+ bytes?: number | null;
44
+ /** Downloading: the file's size, when the server sent Content-Length. */
45
+ bytesTotal?: number | null;
46
+ }
47
+
48
+ /** Several bindings at once (useDuckDB): the slowest wait, sums, a count. */
49
+ export interface CombinedBindingProgress {
50
+ phase: BindingPhase;
51
+ rowsWritten: number | null;
52
+ bytes: number | null;
53
+ bytesTotal: number | null;
54
+ pending: number;
55
+ }
56
+
57
+ export const BINDING_PHASES: readonly BindingPhase[];
58
+ export const BINDING_PHASE_LABELS: Record<BindingPhase, string>;
59
+ /** "Building from warehouse", "Getting download link", "Downloading", "Loading into DuckDB", … */
60
+ export const BINDING_STAGE_LABELS: Record<BindingStage, string>;
61
+ export function bindingPhaseStage(phase: BindingPhase | string | null | undefined): BindingStage | null;
62
+ /**
63
+ * A progress-bar caption: the stage label plus rows or bytes when known,
64
+ * e.g. "Building from warehouse · 120,000 rows", "Downloading · 3.1 of 10.0 MB".
65
+ * Empty when nothing is pending. Pass a hook's state (`bindingPhaseLabel(q)`)
66
+ * or a progress record.
67
+ */
68
+ export function bindingPhaseLabel(
69
+ progress:
70
+ | BindingPhase
71
+ | {
72
+ phase: BindingPhase | null;
73
+ rowsWritten?: number | null;
74
+ bytes?: number | null;
75
+ bytesTotal?: number | null;
76
+ }
77
+ | null
78
+ | undefined,
79
+ ): string;
80
+
81
+ /** One binding's progress, or null when it is not loading. */
82
+ export function useBindingProgress(name: string): BindingProgress | null;
83
+ /** Every pending binding's progress, by name. */
84
+ export function useBindingProgress(): Record<string, BindingProgress>;
85
+
3
86
  /** What a refresh built — the server's answer to `POST __data/<name>/refresh`. */
4
87
  export interface RefreshResult {
5
88
  binding: string;
@@ -27,6 +110,17 @@ export interface QueryState<Row = Record<string, unknown>> {
27
110
  /** A refresh is in flight; `data` still holds the previous rows. */
28
111
  refreshing: boolean;
29
112
  truncated: boolean;
113
+ /**
114
+ * What `loading` / `refreshing` is waiting on; null when neither is true.
115
+ * Caption it with `bindingPhaseLabel(phase)`.
116
+ */
117
+ phase: BindingPhase | null;
118
+ /** While building: rows written so far, when the server says. */
119
+ rowsWritten: number | null;
120
+ /** While building: file size; while downloading: bytes received. */
121
+ bytes: number | null;
122
+ /** While downloading: the file's size, when known. */
123
+ bytesTotal: number | null;
30
124
  /**
31
125
  * Rematerialize the data behind this query and re-run it. Rejects with a
32
126
  * `RefreshError` — the rows on screen are untouched when it does.
@@ -41,6 +135,31 @@ export interface DuckDBState<Row = Record<string, unknown>>
41
135
  export interface QueryOptions {
42
136
  rowLimit?: number | null;
43
137
  }
138
+ export interface DuckDBOptions extends QueryOptions {
139
+ /**
140
+ * "arrow": `data` is DuckDB's Arrow Table as returned (no row objects, no
141
+ * date/BigInt normalization, `rowLimit` ignored). Default "rows".
142
+ */
143
+ format?: "rows" | "arrow";
144
+ }
145
+
146
+ /**
147
+ * The page's shared DuckDB-WASM engine (`AsyncDuckDB` from
148
+ * @duckdb/duckdb-wasm 1.29), typed loosely so the SDK needs no dependency.
149
+ * Never close() or terminate() it: every hook on the page reads from it.
150
+ */
151
+ export interface SharedDuckDB {
152
+ connect(): Promise<DuckDBConnection>;
153
+ registerFileBuffer(name: string, buffer: Uint8Array): Promise<void>;
154
+ dropFile(name: string): Promise<void>;
155
+ [key: string]: unknown;
156
+ }
157
+ export interface DuckDBConnection {
158
+ /** Resolves with an Arrow Table. */
159
+ query(sql: string): Promise<any>;
160
+ close(): Promise<void>;
161
+ [key: string]: unknown;
162
+ }
44
163
  export interface MakoLocation {
45
164
  pathname: string;
46
165
  search: string;
@@ -53,19 +172,94 @@ export interface MakoLocation {
53
172
  export function useQuery<Row = Record<string, unknown>>(
54
173
  name: string,
55
174
  opts?: QueryOptions,
56
- ): QueryState<Row> & { refresh: () => Promise<RefreshResult> };
175
+ ): QueryState<Row> & {
176
+ refresh: () => Promise<RefreshResult>;
177
+ /** The binding's own progress record (null when it is not loading). */
178
+ progress: BindingProgress | null;
179
+ };
57
180
 
58
- /** Analytical SQL over the app's bindings; table names are binding names. */
181
+ /**
182
+ * Analytical SQL over the app's bindings; table names are binding names.
183
+ * Since 2.8 only the bindings the SQL names are downloaded (each decoded
184
+ * once into a DuckDB table); one it misses loads on DuckDB's "table does
185
+ * not exist" and the query re-runs. Catalog queries (SHOW TABLES,
186
+ * information_schema) load every binding.
187
+ */
59
188
  export function useDuckDB<Row = Record<string, unknown>>(
60
189
  sql: string,
61
- opts?: QueryOptions,
62
- ): DuckDBState<Row> & { refresh: () => Promise<RefreshResult[]> };
190
+ opts?: QueryOptions & { format?: "rows" },
191
+ ): DuckDBState<Row> & {
192
+ refresh: () => Promise<RefreshResult[]>;
193
+ /** The slowest pending binding's wait, with sums; null when none. */
194
+ progress: CombinedBindingProgress | null;
195
+ /** Every pending binding's progress, by name. */
196
+ bindings: Record<string, BindingProgress>;
197
+ };
198
+ export function useDuckDB(
199
+ sql: string,
200
+ opts: DuckDBOptions & { format: "arrow" },
201
+ ): Omit<DuckDBState, "data"> & {
202
+ /** The Arrow Table (apache-arrow 17) DuckDB returned. */
203
+ data: any | null;
204
+ refresh: () => Promise<RefreshResult[]>;
205
+ /** The slowest pending binding's wait, with sums; null when none. */
206
+ progress: CombinedBindingProgress | null;
207
+ /** Every pending binding's progress, by name. */
208
+ bindings: Record<string, BindingProgress>;
209
+ };
210
+
211
+ export interface RefreshOptions {
212
+ /**
213
+ * Every phase of this refresh: the build, then the reload (link,
214
+ * download, DuckDB), then `null` once it settles.
215
+ */
216
+ onProgress?: (progress: BindingProgress | null) => void;
217
+ }
218
+
219
+ /**
220
+ * The page's shared DuckDB, booted on first call. Use it for anything the
221
+ * hooks do not cover instead of importing @duckdb/duckdb-wasm, hyparquet or
222
+ * apache-arrow readers. Never close or terminate it.
223
+ */
224
+ export function getDuckDB(): Promise<SharedDuckDB>;
225
+
226
+ /** Run `fn` on a fresh connection to the shared DuckDB; closed afterwards. */
227
+ export function withConnection<T>(fn: (conn: DuckDBConnection) => Promise<T>): Promise<T>;
228
+
229
+ /**
230
+ * Load a binding into the shared DuckDB as a table (once per page;
231
+ * concurrent callers share the download). Resolves with the table name.
232
+ */
233
+ export function ensureBinding(name: string): Promise<string>;
234
+
235
+ /** Drop a loaded binding's table to free memory; the next read reloads it. */
236
+ export function unloadBinding(name: string): Promise<void>;
237
+
238
+ /**
239
+ * The binding's raw parquet bytes, not registered anywhere — for an app with
240
+ * its own reader (register them via getDuckDB().registerFileBuffer to use
241
+ * read_parquet options). Rejects like a failed load (`status`, message).
242
+ */
243
+ export function fetchBindingBytes(
244
+ name: string,
245
+ opts?: {
246
+ fresh?: boolean;
247
+ /**
248
+ * The same phases a hook reports (requesting → resolving/signing or a
249
+ * build → downloading with `bytes` / `bytesTotal`), then `null`.
250
+ */
251
+ onProgress?: (progress: BindingProgress | null) => void;
252
+ },
253
+ ): Promise<Uint8Array>;
63
254
 
64
255
  /**
65
256
  * Rematerialize one binding on demand and reload it everywhere it is used.
66
257
  * Concurrent calls for the same binding share one request.
67
258
  */
68
- export function refreshBinding(name: string): Promise<RefreshResult>;
259
+ export function refreshBinding(
260
+ name: string,
261
+ opts?: RefreshOptions,
262
+ ): Promise<RefreshResult>;
69
263
 
70
264
  /**
71
265
  * Refresh several bindings — all of them when `names` is omitted. Every one