@makoai/app-sdk 2.11.1 → 2.12.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 +80 -3
- package/data-core.js +45 -0
- package/index.d.ts +50 -1
- package/index.js +911 -73
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -89,17 +89,90 @@ Never import `@duckdb/duckdb-wasm`, `hyparquet` or `apache-arrow` parquet
|
|
|
89
89
|
readers in an app. Use the page's engine through the SDK:
|
|
90
90
|
|
|
91
91
|
```ts
|
|
92
|
-
import { getDuckDB, withConnection, ensureBinding, unloadBinding, fetchBindingBytes, useDuckDB } from "@makoai/app-sdk";
|
|
92
|
+
import { getDuckDB, withConnection, ensureBinding, unloadBinding, fetchBindingBytes, useDuckDB, getBindingMemory, setBindingMemoryBudget } from "@makoai/app-sdk";
|
|
93
93
|
|
|
94
94
|
const big = useDuckDB("select lat, lng from listings", { format: "arrow" }); // data: Arrow Table
|
|
95
95
|
const table = await ensureBinding("valuations"); // loaded once, returns "valuations"
|
|
96
96
|
const n = await withConnection(c => c.query(`select count(*) from ${table}`));
|
|
97
97
|
await unloadBinding("valuations"); // free its memory
|
|
98
98
|
const bytes = await fetchBindingBytes("valuations", { onProgress: p => p && console.log(p.phase, p.bytes, p.bytesTotal) });
|
|
99
|
+
const mem = await getBindingMemory(); // { usedBytes, budgetBytes, bindings }
|
|
100
|
+
await setBindingMemoryBudget(800 * 1024 ** 2); // cap binding tables at 800 MiB
|
|
99
101
|
const db = await getDuckDB(); // shared: never close() or terminate()
|
|
100
102
|
await db.registerFileBuffer("valuations.parquet", bytes); // read_parquet with your own options
|
|
101
103
|
```
|
|
102
104
|
|
|
105
|
+
### Memory: least recently read goes first (2.12)
|
|
106
|
+
|
|
107
|
+
Each app frame has its own DuckDB with a 3.1 GiB heap. Before 2.12 every
|
|
108
|
+
binding table stayed in it for good, and an app with many bindings ran out
|
|
109
|
+
of memory. Now bindings aim to stay under a 1.5 GiB budget, and the rest of the
|
|
110
|
+
heap is for queries.
|
|
111
|
+
|
|
112
|
+
| 8 panels over 15 shards (6M rows, 23 columns) | Heap for bindings | All 8 panels |
|
|
113
|
+
| --- | --- | --- |
|
|
114
|
+
| Tables | 2,068 MiB | 5.3 s |
|
|
115
|
+
| Views over the parquet in the heap | about 150 MiB | 7.4 s |
|
|
116
|
+
|
|
117
|
+
- The budget counts what the SDK placed. Your own tables do not shrink it.
|
|
118
|
+
- A new table lands if the parquet's metadata says it fits, after evicting tables
|
|
119
|
+
no one holds, least recently read first. It is an estimate, so the budget can
|
|
120
|
+
overshoot (measured: 1,700 MiB against 1,536).
|
|
121
|
+
- A mostly empty heap lets one table past the budget, up to twice its size. An
|
|
122
|
+
app with one large parquet keeps table speed.
|
|
123
|
+
- A binding that does not fit lands as a view: same name, same rows, slower. A
|
|
124
|
+
later read makes it a table when there is room, with no download.
|
|
125
|
+
- A table you changed loses the change when it becomes a view. The view reads the
|
|
126
|
+
parquet again. Copy a binding to your own table before you `UPDATE` or `ALTER` it.
|
|
127
|
+
- The parquet stays in JS memory as a Blob, so a table can become a view with no
|
|
128
|
+
download. Past 512 MiB of Blobs, the oldest unpinned views are dropped and
|
|
129
|
+
download again on their next read. If a Blob stops being readable, its table is
|
|
130
|
+
dropped and downloads again on its next read.
|
|
131
|
+
- Parquet copies in the heap stop at 2.5 GiB. Past it, the least recently read view
|
|
132
|
+
goes, even a pinned one, and downloads again on its next read. A parquet with no
|
|
133
|
+
room fails with a clear error.
|
|
134
|
+
- A binding a mounted `useQuery`/`useDuckDB` reads is pinned: it goes last.
|
|
135
|
+
`ensureBinding` bindings can become views but are never dropped.
|
|
136
|
+
- "Out of Memory" on a hook's query demotes unpinned tables, then the pinned tables
|
|
137
|
+
that query reads, and runs again until it answers or none is left. Other panels'
|
|
138
|
+
tables stay. For the next minute no table grows back past what is left, then
|
|
139
|
+
pinned views promote by themselves. `withConnection` does not retry: your `fn`
|
|
140
|
+
may not be safe to run twice.
|
|
141
|
+
- A mounted hook whose query still fails on memory reruns after 1, 2, 4, 8 and 15 s,
|
|
142
|
+
then waits. Another hook letting go of its bindings, a budget change, or the tab
|
|
143
|
+
coming back starts one more run. A hidden tab never reruns. The error stays up
|
|
144
|
+
until a run answers.
|
|
145
|
+
- Do not `registerFileHandle` a Blob with `BROWSER_FILEREADER`. In duckdb-wasm
|
|
146
|
+
1.29.0 its size is lost when the allocator returns a pointer past 2 GiB, and
|
|
147
|
+
reads fail with "too small to be a Parquet file". Use `registerFileBuffer`.
|
|
148
|
+
- A hook's query can name at most 50 bindings. A double-read `UNION ALL` of about 60
|
|
149
|
+
overflows the WASM stack and breaks the engine for every panel, so the SDK refuses
|
|
150
|
+
it with a clear error. `withConnection` and `getDuckDB()` have no such check.
|
|
151
|
+
- If the engine traps anyway, a hook's query restarts it, at most once a minute and
|
|
152
|
+
3 times a page. Every panel reruns and every binding downloads again. A
|
|
153
|
+
`getDuckDB()` handle held across a restart is dead: call it again.
|
|
154
|
+
|
|
155
|
+
`setBindingMemoryBudget(bytes)` changes the 1.5 GiB default. `getBindingMemory()`
|
|
156
|
+
shows what is loaded, oldest first, `bindingBytes` against the budget, `usedBytes`
|
|
157
|
+
for the whole heap, and `pressure`.
|
|
158
|
+
|
|
159
|
+
### Failed downloads (2.12)
|
|
160
|
+
|
|
161
|
+
- A page runs at most 12 downloads at once, and one after a failure.
|
|
162
|
+
- A rejected fetch, a 429 or a 503 closes a page-wide gate for 1, 3, 9, 27, then
|
|
163
|
+
60 s, with jitter. Past 3 failures in a row, a request while it is closed fails
|
|
164
|
+
at once with no network. Any other answer opens it.
|
|
165
|
+
- A download tries 3 times, on the first request and on the signed download alike,
|
|
166
|
+
and only until headers arrive. A `retryAfterMs` up to 30 s sets the wait.
|
|
167
|
+
- A mounted hook then reruns after 5, 20 and 60 s, or after `retryAfterMs` if that
|
|
168
|
+
is longer. Then it waits for the tab or the network to come back, or for another
|
|
169
|
+
request to get an answer.
|
|
170
|
+
- A failed build never runs again by itself: not a `failed` event, whatever its
|
|
171
|
+
text, and not a build stream cut halfway. Other HTTP statuses and SQL errors stay
|
|
172
|
+
as they are too. A new query or a reload asks again.
|
|
173
|
+
- A failed `__data/index.json` is kept for 10 s. A query that needs no binding still
|
|
174
|
+
answers. A query that fails then shows the index failure and retries.
|
|
175
|
+
|
|
103
176
|
### Loading cost (2.8)
|
|
104
177
|
|
|
105
178
|
- `useDuckDB` downloads only the bindings its SQL names. A missed name (for
|
|
@@ -107,8 +180,12 @@ await db.registerFileBuffer("valuations.parquet", bytes); // read_parquet with
|
|
|
107
180
|
and the query re-runs. `SHOW TABLES` / `information_schema` load all.
|
|
108
181
|
- Each binding is decoded once into a DuckDB table and its file buffer is
|
|
109
182
|
freed. A refresh swaps the table in one commit, so a running query never
|
|
110
|
-
sees it missing. A table costs about
|
|
111
|
-
|
|
183
|
+
sees it missing. A table costs about 15 bytes a cell (400k rows x 23 columns:
|
|
184
|
+
138 MiB from a 10 MiB parquet).
|
|
185
|
+
- Tables are evicted least recently read first (2.12). Over the memory
|
|
186
|
+
budget (default 1.5 GiB of DuckDB's 3.1 GiB heap), the oldest table becomes
|
|
187
|
+
a view over its compressed parquet. Its next read turns it back into a table
|
|
188
|
+
without a download when it fits. See Memory above.
|
|
112
189
|
- The DuckDB engine and its parquet extension start loading on the first
|
|
113
190
|
data hook render, in parallel with the first binding download.
|
|
114
191
|
- Rows decode column by column: 149k rows x 16 columns in 190 ms, down
|
package/data-core.js
CHANGED
|
@@ -298,3 +298,48 @@ export function parseBindingSnapshot(body, rowLimit) {
|
|
|
298
298
|
builtAt: typeof body.builtAt === "string" ? body.builtAt : null,
|
|
299
299
|
};
|
|
300
300
|
}
|
|
301
|
+
|
|
302
|
+
/**
|
|
303
|
+
* Whether `error` is DuckDB running out of memory. duckdb-wasm hands errors
|
|
304
|
+
* across its worker as plain Errors with no type or code (measured on 1.29.0:
|
|
305
|
+
* `{ name: "Error", message }`), so DuckDB's message, which starts with its
|
|
306
|
+
* error type ("Out of Memory Error: failed to allocate …" or "… could not
|
|
307
|
+
* allocate block …"), is the only signal there is. Anchored: a Binder Error can
|
|
308
|
+
* quote the same words from the SQL, and a server's build error can too, so the
|
|
309
|
+
* SDK asks this only of errors from its own conn.query.
|
|
310
|
+
*/
|
|
311
|
+
export function isOutOfMemoryError(error) {
|
|
312
|
+
const message = error instanceof Error ? error.message : String(error ?? "");
|
|
313
|
+
return /^Out of Memory Error\b/.test(message);
|
|
314
|
+
}
|
|
315
|
+
|
|
316
|
+
/**
|
|
317
|
+
* Whether `error` is the WASM engine itself breaking: a trap, or the bad_cast of a
|
|
318
|
+
* corrupted heap. Anchored for the same reason. `Conversion Error: ... "unreachable"`
|
|
319
|
+
* quotes a value.
|
|
320
|
+
*/
|
|
321
|
+
export function crashedEngineError(error) {
|
|
322
|
+
const message = error instanceof Error ? error.message : String(error ?? "");
|
|
323
|
+
return /^(Invalid Error: std::bad_cast|null function|memory access out of bounds|table index is out of bounds|unreachable|Maximum call stack size exceeded)/.test(message);
|
|
324
|
+
}
|
|
325
|
+
|
|
326
|
+
// When a mounted hook runs a failed query again. The tag is set where the error
|
|
327
|
+
// was caught, never read from its text: "memory" by the SDK's own conn.query,
|
|
328
|
+
// "network" by a request that got no usable answer. A build's failure carries no
|
|
329
|
+
// tag, because asking again runs the warehouse query again.
|
|
330
|
+
const RETRY_MS = {
|
|
331
|
+
memory: [1000, 2000, 4000, 8000, 15000],
|
|
332
|
+
network: [5000, 20000, 60000],
|
|
333
|
+
};
|
|
334
|
+
|
|
335
|
+
/**
|
|
336
|
+
* Ms until retry number `retries` (from 0). Infinity: only a sign that the answer
|
|
337
|
+
* could differ (see wakeRetries). null: leave the error up. A server's
|
|
338
|
+
* `retryAfterMs` is a floor.
|
|
339
|
+
*/
|
|
340
|
+
export function retryDelayMs(error, retries) {
|
|
341
|
+
const table = RETRY_MS[error?.retry];
|
|
342
|
+
if (!table) return null;
|
|
343
|
+
const wait = table[retries] ?? Infinity;
|
|
344
|
+
return Math.max(wait, typeof error.retryAfterMs === "number" ? error.retryAfterMs : 0);
|
|
345
|
+
}
|
package/index.d.ts
CHANGED
|
@@ -273,12 +273,61 @@ export function withConnection<T>(fn: (conn: DuckDBConnection) => Promise<T>): P
|
|
|
273
273
|
/**
|
|
274
274
|
* Load a binding into the shared DuckDB as a table (once per page;
|
|
275
275
|
* concurrent callers share the download). Resolves with the table name.
|
|
276
|
+
* Each call counts as a read for eviction. Under memory pressure the table
|
|
277
|
+
* may become a view over its parquet (same name and rows, slower to query);
|
|
278
|
+
* a binding loaded this way is never dropped outright.
|
|
276
279
|
*/
|
|
277
280
|
export function ensureBinding(name: string): Promise<string>;
|
|
278
281
|
|
|
279
|
-
/** Drop a loaded binding's table to free memory; the next read reloads it. */
|
|
282
|
+
/** Drop a loaded binding's table (or view) to free memory; the next read reloads it. */
|
|
280
283
|
export function unloadBinding(name: string): Promise<void>;
|
|
281
284
|
|
|
285
|
+
/** 1.5 GiB: what binding tables may hold in DuckDB unless the app says otherwise. */
|
|
286
|
+
export const DEFAULT_BINDING_MEMORY_BUDGET: number;
|
|
287
|
+
/** 512 MiB: the compressed parquet copies kept for demoted bindings. */
|
|
288
|
+
export const DEFAULT_BINDING_BLOB_BUDGET: number;
|
|
289
|
+
|
|
290
|
+
/**
|
|
291
|
+
* Cap what bindings may hold in this frame's DuckDB, in bytes (default 1.5 GiB,
|
|
292
|
+
* half of the 3.1 GiB heap; queries need the rest). Tables an app made itself do
|
|
293
|
+
* not count. Checked with an estimate from parquet metadata before each load, so
|
|
294
|
+
* it can overshoot (measured: 1,700 MiB). Past it, the least recently read unpinned
|
|
295
|
+
* tables become views over a heap copy of their parquet, and a new binding lands as
|
|
296
|
+
* a view if that is not enough. A read promotes a view back to a table when it
|
|
297
|
+
* fits, without a download. `blobBytes` caps the parquet kept in JS memory (default
|
|
298
|
+
* 512 MiB); past it the oldest unpinned views are dropped and download again when
|
|
299
|
+
* read. `Infinity` turns a cap off. Resolves once the engine is back under the new
|
|
300
|
+
* cap, and ends any memory pressure.
|
|
301
|
+
*/
|
|
302
|
+
export function setBindingMemoryBudget(bytes: number, opts?: { blobBytes?: number }): Promise<void>;
|
|
303
|
+
|
|
304
|
+
export interface BindingMemory {
|
|
305
|
+
/**
|
|
306
|
+
* The frame's whole heap now: duckdb_memory(), with an app's own tables, plus the
|
|
307
|
+
* parquet copies views read. Query scratch never shows.
|
|
308
|
+
*/
|
|
309
|
+
usedBytes: number;
|
|
310
|
+
/** What the SDK placed, the figure the budget caps. It can pass the budget: the check is an estimate. */
|
|
311
|
+
bindingBytes: number;
|
|
312
|
+
budgetBytes: number;
|
|
313
|
+
blobBudgetBytes: number;
|
|
314
|
+
/** A query ran out of memory in the last minute: tables stay at what relief left. */
|
|
315
|
+
pressure: boolean;
|
|
316
|
+
/** Every loaded binding, least recently read first. */
|
|
317
|
+
bindings: {
|
|
318
|
+
name: string;
|
|
319
|
+
/** "table": decoded in the heap. "view": decoded from its parquet copy in the heap on each query. */
|
|
320
|
+
storage: "table" | "view";
|
|
321
|
+
/** Read by a mounted hook or a query in flight: evicted last. */
|
|
322
|
+
pinned: boolean;
|
|
323
|
+
/** The compressed copy kept for a demotion; null once dropped. */
|
|
324
|
+
parquetBytes: number | null;
|
|
325
|
+
}[];
|
|
326
|
+
}
|
|
327
|
+
|
|
328
|
+
/** What the binding tables hold right now, for a debug panel or a test. */
|
|
329
|
+
export function getBindingMemory(): Promise<BindingMemory>;
|
|
330
|
+
|
|
282
331
|
/**
|
|
283
332
|
* The binding's raw parquet bytes, not registered anywhere — for an app with
|
|
284
333
|
* its own reader (register them via getDuckDB().registerFileBuffer to use
|