@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 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 3x the parquet in memory (10 MB of
111
- parquet, 149k rows: 33 MB).
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