@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 +73 -5
- package/data-core.js +212 -0
- package/index.d.ts +199 -5
- package/index.js +352 -98
- package/package.json +6 -1
- package/progress.js +233 -0
- package/ui.js +5 -2
- package/vite.d.ts +5 -3
- package/vite.js +179 -18
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
|
|
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/`
|
|
201
|
-
|
|
202
|
-
|
|
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> & {
|
|
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
|
-
/**
|
|
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> & {
|
|
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(
|
|
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
|