@makoai/app-sdk 2.11.1 → 2.13.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,116 @@ 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
+
176
+ ### Memory across apps (2.13)
177
+
178
+ Inside Mako, each app frame posts what its heap holds. Past 2 GiB across the
179
+ open app tabs, Mako asks the least recently shown ones to release, and asks a
180
+ busy frame again 10 s later. A WASM heap never shrinks, so a release ends that
181
+ frame's DuckDB worker. Its rows stay on screen and its parquet stays as Blobs.
182
+ The next query there boots a new engine and reloads its parquet with no
183
+ download. A reboot takes 0.6 s on the app's own origin and 0.6 to 2.6 s in an
184
+ opaque frame, which has no HTTP cache and fetches the 35 MiB WASM again.
185
+
186
+ - A frame keeps its engine for the page's life once app code calls
187
+ `getDuckDB()`, `withConnection()` or `ensureBinding()`, or sends `useDuckDB`
188
+ SQL that is not a plain read (`CREATE TABLE`, `SET`, anything the SDK does
189
+ not recognise). Only that worker has what they made. Mako counts its heap and
190
+ asks another frame, so an app that needs to be a good neighbour sticks to
191
+ read-only `useQuery` and `useDuckDB`.
192
+ - A release is not a crash. It does not count toward the 3 restarts a page gets,
193
+ reruns no panel and leaves the download gate as it is. A parked binding reads
194
+ with no network even while the gate is closed.
195
+ - Frames on an older SDK, the dev-mode preview and apps that boot their own
196
+ DuckDB send no report. Mako cannot count or ask them. An app gets 2.13 on its
197
+ next commit.
198
+ - A report covers tables and parquet copies. Query scratch stays in the heap
199
+ unseen, so the real heap is larger (1037 MiB reported, about 1500 MiB in the
200
+ renderer).
201
+
103
202
  ### Loading cost (2.8)
104
203
 
105
204
  - `useDuckDB` downloads only the bindings its SQL names. A missed name (for
@@ -107,8 +206,12 @@ await db.registerFileBuffer("valuations.parquet", bytes); // read_parquet with
107
206
  and the query re-runs. `SHOW TABLES` / `information_schema` load all.
108
207
  - Each binding is decoded once into a DuckDB table and its file buffer is
109
208
  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).
209
+ sees it missing. A table costs about 15 bytes a cell (400k rows x 23 columns:
210
+ 138 MiB from a 10 MiB parquet).
211
+ - Tables are evicted least recently read first (2.12). Over the memory
212
+ budget (default 1.5 GiB of DuckDB's 3.1 GiB heap), the oldest table becomes
213
+ a view over its compressed parquet. Its next read turns it back into a table
214
+ without a download when it fits. See Memory above.
112
215
  - The DuckDB engine and its parquet extension start loading on the first
113
216
  data hook render, in parallel with the first binding download.
114
217
  - Rows decode column by column: 149k rows x 16 columns in 190 ms, down
package/data-core.js CHANGED
@@ -46,6 +46,23 @@ export function readsCatalog(sql) {
46
46
  return CATALOG_QUERY.test(String(sql));
47
47
  }
48
48
 
49
+ const SQL_NOISE = /'(?:[^']|'')*'|"(?:[^"]|"")*"|--[^\n]*|\/\*[\s\S]*?\*\//g;
50
+ const READ_STATEMENT = /^(?:\(|(?:SELECT|FROM|VALUES|TABLE|DESC|DESCRIBE|SHOW|SUMMARIZE|WITH)\b)/i;
51
+ const WRITE_WORD = /\b(?:INSERT|UPDATE|DELETE|CREATE|DROP|ALTER|MERGE)\b/i;
52
+
53
+ /**
54
+ * Whether `sql` only reads. Anything it does not recognise counts as a write:
55
+ * the cost of a wrong "write" is a frame that keeps its engine, and the cost of
56
+ * a wrong "read" is an app that loses its tables on a release.
57
+ */
58
+ export function isReadOnlySql(sql) {
59
+ return String(sql)
60
+ .replace(SQL_NOISE, " ")
61
+ .split(";")
62
+ .map(statement => statement.trim())
63
+ .every(s => s === "" || (READ_STATEMENT.test(s) && !(/^WITH\b/i.test(s) && WRITE_WORD.test(s))));
64
+ }
65
+
49
66
  /**
50
67
  * The binding a DuckDB "Table with name X does not exist" error is about —
51
68
  * X itself when the index lists it, else its case-insensitive match (DuckDB
@@ -298,3 +315,48 @@ export function parseBindingSnapshot(body, rowLimit) {
298
315
  builtAt: typeof body.builtAt === "string" ? body.builtAt : null,
299
316
  };
300
317
  }
318
+
319
+ /**
320
+ * Whether `error` is DuckDB running out of memory. duckdb-wasm hands errors
321
+ * across its worker as plain Errors with no type or code (measured on 1.29.0:
322
+ * `{ name: "Error", message }`), so DuckDB's message, which starts with its
323
+ * error type ("Out of Memory Error: failed to allocate …" or "… could not
324
+ * allocate block …"), is the only signal there is. Anchored: a Binder Error can
325
+ * quote the same words from the SQL, and a server's build error can too, so the
326
+ * SDK asks this only of errors from its own conn.query.
327
+ */
328
+ export function isOutOfMemoryError(error) {
329
+ const message = error instanceof Error ? error.message : String(error ?? "");
330
+ return /^Out of Memory Error\b/.test(message);
331
+ }
332
+
333
+ /**
334
+ * Whether `error` is the WASM engine itself breaking: a trap, or the bad_cast of a
335
+ * corrupted heap. Anchored for the same reason. `Conversion Error: ... "unreachable"`
336
+ * quotes a value.
337
+ */
338
+ export function crashedEngineError(error) {
339
+ const message = error instanceof Error ? error.message : String(error ?? "");
340
+ 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);
341
+ }
342
+
343
+ // When a mounted hook runs a failed query again. The tag is set where the error
344
+ // was caught, never read from its text: "memory" by the SDK's own conn.query,
345
+ // "network" by a request that got no usable answer. A build's failure carries no
346
+ // tag, because asking again runs the warehouse query again.
347
+ const RETRY_MS = {
348
+ memory: [1000, 2000, 4000, 8000, 15000],
349
+ network: [5000, 20000, 60000],
350
+ };
351
+
352
+ /**
353
+ * Ms until retry number `retries` (from 0). Infinity: only a sign that the answer
354
+ * could differ (see wakeRetries). null: leave the error up. A server's
355
+ * `retryAfterMs` is a floor.
356
+ */
357
+ export function retryDelayMs(error, retries) {
358
+ const table = RETRY_MS[error?.retry];
359
+ if (!table) return null;
360
+ const wait = table[retries] ?? Infinity;
361
+ return Math.max(wait, typeof error.retryAfterMs === "number" ? error.retryAfterMs : 0);
362
+ }
package/index.d.ts CHANGED
@@ -263,22 +263,77 @@ export interface RefreshOptions {
263
263
  /**
264
264
  * The page's shared DuckDB, booted on first call. Use it for anything the
265
265
  * hooks do not cover instead of importing @duckdb/duckdb-wasm, hyparquet or
266
- * apache-arrow readers. Never close or terminate it.
266
+ * apache-arrow readers. Never close or terminate it. Calling it keeps the
267
+ * engine for the page's life: Mako cannot give this frame's heap back when the
268
+ * page runs short (see withConnection, ensureBinding and SQL that writes).
267
269
  */
268
270
  export function getDuckDB(): Promise<SharedDuckDB>;
269
271
 
270
- /** Run `fn` on a fresh connection to the shared DuckDB; closed afterwards. */
272
+ /**
273
+ * Run `fn` on a fresh connection to the shared DuckDB; closed afterwards. Keeps
274
+ * the engine for the page's life, like getDuckDB().
275
+ */
271
276
  export function withConnection<T>(fn: (conn: DuckDBConnection) => Promise<T>): Promise<T>;
272
277
 
273
278
  /**
274
279
  * Load a binding into the shared DuckDB as a table (once per page;
275
280
  * concurrent callers share the download). Resolves with the table name.
281
+ * Each call counts as a read for eviction. Under memory pressure the table
282
+ * may become a view over its parquet (same name and rows, slower to query);
283
+ * a binding loaded this way is never dropped outright. Keeps the engine for the
284
+ * page's life, like getDuckDB().
276
285
  */
277
286
  export function ensureBinding(name: string): Promise<string>;
278
287
 
279
- /** Drop a loaded binding's table to free memory; the next read reloads it. */
288
+ /** Drop a loaded binding's table (or view) to free memory; the next read reloads it. */
280
289
  export function unloadBinding(name: string): Promise<void>;
281
290
 
291
+ /** 1.5 GiB: what binding tables may hold in DuckDB unless the app says otherwise. */
292
+ export const DEFAULT_BINDING_MEMORY_BUDGET: number;
293
+ /** 512 MiB: the compressed parquet copies kept for demoted bindings. */
294
+ export const DEFAULT_BINDING_BLOB_BUDGET: number;
295
+
296
+ /**
297
+ * Cap what bindings may hold in this frame's DuckDB, in bytes (default 1.5 GiB,
298
+ * half of the 3.1 GiB heap; queries need the rest). Tables an app made itself do
299
+ * not count. Checked with an estimate from parquet metadata before each load, so
300
+ * it can overshoot (measured: 1,700 MiB). Past it, the least recently read unpinned
301
+ * tables become views over a heap copy of their parquet, and a new binding lands as
302
+ * a view if that is not enough. A read promotes a view back to a table when it
303
+ * fits, without a download. `blobBytes` caps the parquet kept in JS memory (default
304
+ * 512 MiB); past it the oldest unpinned views are dropped and download again when
305
+ * read. `Infinity` turns a cap off. Resolves once the engine is back under the new
306
+ * cap, and ends any memory pressure.
307
+ */
308
+ export function setBindingMemoryBudget(bytes: number, opts?: { blobBytes?: number }): Promise<void>;
309
+
310
+ export interface BindingMemory {
311
+ /**
312
+ * The frame's whole heap now: duckdb_memory(), with an app's own tables, plus the
313
+ * parquet copies views read. Query scratch never shows.
314
+ */
315
+ usedBytes: number;
316
+ /** What the SDK placed, the figure the budget caps. It can pass the budget: the check is an estimate. */
317
+ bindingBytes: number;
318
+ budgetBytes: number;
319
+ blobBudgetBytes: number;
320
+ /** A query ran out of memory in the last minute: tables stay at what relief left. */
321
+ pressure: boolean;
322
+ /** Every loaded binding, least recently read first. */
323
+ bindings: {
324
+ name: string;
325
+ /** "table": decoded in the heap. "view": decoded from its parquet copy in the heap on each query. */
326
+ storage: "table" | "view";
327
+ /** Read by a mounted hook or a query in flight: evicted last. */
328
+ pinned: boolean;
329
+ /** The compressed copy kept for a demotion; null once dropped. */
330
+ parquetBytes: number | null;
331
+ }[];
332
+ }
333
+
334
+ /** What the binding tables hold right now, for a debug panel or a test. */
335
+ export function getBindingMemory(): Promise<BindingMemory>;
336
+
282
337
  /**
283
338
  * The binding's raw parquet bytes, not registered anywhere — for an app with
284
339
  * its own reader (register them via getDuckDB().registerFileBuffer to use