@makoai/app-sdk 2.12.0 → 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
@@ -173,6 +173,32 @@ for the whole heap, and `pressure`.
173
173
  - A failed `__data/index.json` is kept for 10 s. A query that needs no binding still
174
174
  answers. A query that fails then shows the index failure and retries.
175
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
+
176
202
  ### Loading cost (2.8)
177
203
 
178
204
  - `useDuckDB` downloads only the bindings its SQL names. A missed name (for
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
package/index.d.ts CHANGED
@@ -263,11 +263,16 @@ 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
  /**
@@ -275,7 +280,8 @@ export function withConnection<T>(fn: (conn: DuckDBConnection) => Promise<T>): P
275
280
  * concurrent callers share the download). Resolves with the table name.
276
281
  * Each call counts as a read for eviction. Under memory pressure the table
277
282
  * may become a view over its parquet (same name and rows, slower to query);
278
- * a binding loaded this way is never dropped outright.
283
+ * a binding loaded this way is never dropped outright. Keeps the engine for the
284
+ * page's life, like getDuckDB().
279
285
  */
280
286
  export function ensureBinding(name: string): Promise<string>;
281
287
 
package/index.js CHANGED
@@ -20,6 +20,7 @@ import {
20
20
  missingBinding,
21
21
  mentionedBindings,
22
22
  quoteIdent,
23
+ isReadOnlySql,
23
24
  readsCatalog,
24
25
  quoteString,
25
26
  crashedEngineError,
@@ -35,7 +36,7 @@ import {
35
36
  * in a page (or this export) says which SDK a deployed app actually runs.
36
37
  * Kept in step with package.json by snapshot.test.mjs.
37
38
  */
38
- export const SDK_VERSION = "2.12.0";
39
+ export const SDK_VERSION = "2.13.0";
39
40
  if (typeof window !== "undefined") {
40
41
  try {
41
42
  window.__MAKO_APP_SDK__ = SDK_VERSION;
@@ -60,12 +61,29 @@ const DUCKDB_ESM =
60
61
  // ---------------------------------------------------------------------------
61
62
  let dbPromise = null;
62
63
  let liveEngine = null; // the resolved dbPromise: errors from an older one are history
64
+ // createWorker() makes a new object URL per call and never revokes it, so each
65
+ // reboot after a release would leak the worker script (about 742 KiB). One URL
66
+ // per page, also one download fewer in a frame with no HTTP cache. Not through
67
+ // the download gate: the CDN being down says nothing about Mako's server.
68
+ let workerUrl = null;
69
+ function startWorker(duckdb, script) {
70
+ if (typeof Worker === "undefined") return duckdb.createWorker(script);
71
+ workerUrl ??= fetch(script).then(async res => {
72
+ if (!res.ok) throw new Error("The DuckDB worker could not be loaded (HTTP " + res.status + ")");
73
+ return URL.createObjectURL(await res.blob());
74
+ });
75
+ workerUrl.catch(() => {
76
+ workerUrl = null;
77
+ });
78
+ return workerUrl.then(url => new Worker(url));
79
+ }
80
+
63
81
  function getDb() {
64
82
  if (!dbPromise) {
65
83
  dbPromise = (async () => {
66
84
  const duckdb = await import(/* @vite-ignore */ DUCKDB_ESM);
67
85
  const bundle = await duckdb.selectBundle(duckdb.getJsDelivrBundles());
68
- const worker = await duckdb.createWorker(bundle.mainWorker);
86
+ const worker = await startWorker(duckdb, bundle.mainWorker);
69
87
  const db = new duckdb.AsyncDuckDB(new duckdb.VoidLogger(), worker);
70
88
  await db.instantiate(bundle.mainModule, bundle.pthreadWorker);
71
89
  // read_parquet lives in an extension DuckDB fetches on first use
@@ -568,8 +586,99 @@ async function duckdbBytes(engine) {
568
586
  }
569
587
  }
570
588
 
571
- // Hook for whoever wants the figure (the host frame, in a later step).
572
- function reportMemory() {}
589
+ // ---------------------------------------------------------------------------
590
+ // Across apps (2.13). Each app frame has its own DuckDB and its own WASM heap,
591
+ // so evicting inside one frame frees nothing for the next app opened. The SDK
592
+ // tells Mako's shell what its heap holds; the shell keeps one budget across its
593
+ // app frames and asks the least recently shown ones to release. A WASM heap
594
+ // never shrinks: demoting a table frees DuckDB's accounting and leaves the bytes
595
+ // reserved. So release means ending the worker, and the report is the most this
596
+ // worker has held. It is measuredBytes, not bindingBytes: an app's own tables
597
+ // sit in the same renderer. Parquet stays here as Blobs ("parked"): the next read
598
+ // boots a new engine and decodes from them, with no download and no gate.
599
+ //
600
+ // A worker can end only when nothing lives in it but bindings. App code that may
601
+ // hold the engine or keep its own state there keeps it for the page's life
602
+ // (keepEngine), says so in its reports, and the shell asks another frame.
603
+ //
604
+ // A release is not a crash: it never counts against MAX_RESTARTS, never reruns a
605
+ // hook, and leaves the gate and the download slots alone. They describe the
606
+ // server. Nothing in flight also means no load holds a slot.
607
+ // ---------------------------------------------------------------------------
608
+ const MEMORY_MESSAGE = "mako-app:duckdb-memory";
609
+ const RELEASE_MESSAGE = "mako-host:duckdb-release";
610
+ const inFrame = typeof window !== "undefined" && window.parent != null && window.parent !== window;
611
+ const parked = new Map(); // name -> Blob of a binding whose engine was released
612
+ let engineKept = false;
613
+ let heapBytes = 0; // the most this worker has held: its heap never gives it back
614
+ let busy = 0; // hooks, withConnection calls and queries in flight
615
+ let reportedBytes = null;
616
+ let reportedKept = false;
617
+
618
+ function reportMemory() {
619
+ heapBytes = Math.max(heapBytes, measuredBytes);
620
+ if (!inFrame || (heapBytes === reportedBytes && engineKept === reportedKept)) return;
621
+ reportedBytes = heapBytes;
622
+ reportedKept = engineKept;
623
+ try {
624
+ window.parent.postMessage({ type: MEMORY_MESSAGE, bytes: heapBytes, canRelease: !engineKept }, "*");
625
+ } catch {
626
+ /* a host that is not Mako: nothing to tell */
627
+ }
628
+ }
629
+
630
+ /** Something only this worker has may exist from now on: never end it. */
631
+ function keepEngine() {
632
+ if (engineKept) return;
633
+ engineKept = true;
634
+ reportMemory();
635
+ }
636
+
637
+ /**
638
+ * The host's ask: give the memory back. Nothing in flight: park every Blob and
639
+ * end the worker. Rows already on screen stay (they are plain JS); the next
640
+ * query reboots. Busy: skipped, and the host asks again. A kept engine stays. So
641
+ * does one with a crash restart due: that ends it and reruns the panels that saw
642
+ * the crash, which a release would not.
643
+ */
644
+ async function releaseEngine() {
645
+ const idle = () => !engineKept && !restartTimer && busy === 0 && loading.size === 0 && refreshes.size === 0;
646
+ const current = dbPromise;
647
+ if (!current || !idle()) return;
648
+ const engine = await current;
649
+ await catalog(async () => {
650
+ if (dbPromise !== current || !idle()) return;
651
+ // From here to dbPromise = null runs without a yield: no query can grab
652
+ // the old engine in between. liveEngine goes too: a crash report from this
653
+ // engine must not restart the next one.
654
+ for (const [name, entry] of entries) if (entry.blob) parked.set(name, entry.blob);
655
+ entries.clear();
656
+ registered.clear();
657
+ loadedBindings.clear();
658
+ liveEngine = null;
659
+ dbPromise = null;
660
+ measuredBytes = 0;
661
+ heapBytes = 0;
662
+ pressureUntil = 0; // the next engine starts with an empty heap
663
+ clearTimeout(pressureTimer);
664
+ reportMemory();
665
+ await engine.terminate().catch(() => {});
666
+ });
667
+ }
668
+
669
+ if (inFrame) {
670
+ window.addEventListener("message", event => {
671
+ // Only the frame's own parent may ask. The ask can do no harm beyond a
672
+ // slower next query, so the parent's origin (Mako's, whatever host it
673
+ // runs on) is not pinned here.
674
+ if (event.source !== window.parent) return;
675
+ const data = event.data;
676
+ if (!data || data.type !== RELEASE_MESSAGE) return;
677
+ releaseEngine().catch(() => {
678
+ /* the next ask, or the next load's trim, tries again */
679
+ });
680
+ });
681
+ }
573
682
 
574
683
  /** The least recently read binding that passes `test` and nothing holds. */
575
684
  function leastRecent(test, pinnedToo = false) {
@@ -803,7 +912,14 @@ async function loadBinding(name, bust) {
803
912
  db.catch(() => {});
804
913
  loading.add(name);
805
914
  try {
806
- const buf = await downloadBinding(name, bust, patch => setProgress(name, patch));
915
+ // Parked by a release: the same bytes, no download (unless a refresh made
916
+ // them stale). A Blob can stop being readable: then it downloads.
917
+ const kept = parked.get(name);
918
+ parked.delete(name);
919
+ const parkedBytes = kept && !bust ? await kept.arrayBuffer().catch(() => null) : null;
920
+ const buf = parkedBytes
921
+ ? new Uint8Array(parkedBytes)
922
+ : await downloadBinding(name, bust, patch => setProgress(name, patch));
807
923
  setProgress(name, { phase: "loading_duckdb" });
808
924
  const engine = await db;
809
925
  // Made before the buffer goes to the worker: the copy a demotion reads.
@@ -941,17 +1057,24 @@ export async function getBindingMemory() {
941
1057
  * close or terminate it: every hook on the page reads from it.
942
1058
  */
943
1059
  export function getDuckDB() {
1060
+ keepEngine();
944
1061
  return getDb();
945
1062
  }
946
1063
 
947
1064
  /** Run `fn` with a fresh connection to the shared DuckDB; always closed after. */
948
1065
  export async function withConnection(fn) {
949
- const db = await getDb();
950
- const conn = await db.connect();
1066
+ keepEngine();
1067
+ busy++;
951
1068
  try {
952
- return await fn(conn);
1069
+ const db = await getDb();
1070
+ const conn = await db.connect();
1071
+ try {
1072
+ return await fn(conn);
1073
+ } finally {
1074
+ await conn.close();
1075
+ }
953
1076
  } finally {
954
- await conn.close();
1077
+ busy--;
955
1078
  }
956
1079
  }
957
1080
 
@@ -963,6 +1086,7 @@ export async function withConnection(fn) {
963
1086
  * view over its parquet (same name, same rows, slower); it is never dropped.
964
1087
  */
965
1088
  export async function ensureBinding(name) {
1089
+ keepEngine(); // its contract: the name stays readable, by code the SDK cannot see
966
1090
  externalBindings.add(name);
967
1091
  await registerBinding(name);
968
1092
  return name;
@@ -973,11 +1097,12 @@ export async function ensureBinding(name) {
973
1097
  * The next query or ensureBinding() downloads it again.
974
1098
  */
975
1099
  export async function unloadBinding(name) {
1100
+ parked.delete(name);
1101
+ knownBindings.delete(name);
976
1102
  const pending = registered.get(name);
977
1103
  if (!pending) return;
978
1104
  registered.delete(name);
979
1105
  externalBindings.delete(name);
980
- knownBindings.delete(name);
981
1106
  await pending.catch(() => {});
982
1107
  if (registered.has(name)) return; // read again meanwhile: it stays
983
1108
  const engine = await getDb();
@@ -1217,22 +1342,31 @@ async function runSql(sql, rowLimit, format, reads) {
1217
1342
 
1218
1343
  async function runSqlOnce(sql, rowLimit, format) {
1219
1344
  const cap = rowLimit === null ? Infinity : (rowLimit ?? DEFAULT_ROW_LIMIT);
1220
- const db = await getDb();
1221
- const conn = await db.connect();
1345
+ const writes = !isReadOnlySql(sql);
1346
+ if (writes) keepEngine(); // CREATE TABLE journal_t: only this worker has it
1347
+ busy++; // before the await: a release must not end the engine under it
1222
1348
  try {
1223
- const table = await conn.query(sql);
1224
- const rowCount = table.numRows;
1225
- if (format === "arrow") {
1226
- // The Arrow Table as DuckDB returned it: no row objects, no
1227
- // normalization, no row limit.
1228
- return { rows: table, fields: table.schema.fields.map(f => f.name), rowCount, truncated: false };
1349
+ const db = await getDb();
1350
+ const conn = await db.connect();
1351
+ try {
1352
+ const table = await conn.query(sql);
1353
+ // No load follows to measure what the app just made, and the report owes it.
1354
+ if (writes) catalog(() => measureNow(db)).catch(() => {});
1355
+ const rowCount = table.numRows;
1356
+ if (format === "arrow") {
1357
+ // The Arrow Table as DuckDB returned it: no row objects, no
1358
+ // normalization, no row limit.
1359
+ return { rows: table, fields: table.schema.fields.map(f => f.name), rowCount, truncated: false };
1360
+ }
1361
+ const { rows, fields } = toPlainRows(table, cap);
1362
+ return { rows, fields, rowCount, truncated: rowCount > rows.length };
1363
+ } catch (error) {
1364
+ throw markEngineError(error, db);
1365
+ } finally {
1366
+ await conn.close();
1229
1367
  }
1230
- const { rows, fields } = toPlainRows(table, cap);
1231
- return { rows, fields, rowCount, truncated: rowCount > rows.length };
1232
- } catch (error) {
1233
- throw markEngineError(error, db);
1234
1368
  } finally {
1235
- await conn.close();
1369
+ busy--;
1236
1370
  }
1237
1371
  }
1238
1372
 
@@ -1261,7 +1395,9 @@ function restartEngine() {
1261
1395
  registered.clear();
1262
1396
  loadedBindings.clear();
1263
1397
  measuredBytes = 0;
1398
+ heapBytes = 0;
1264
1399
  pressureUntil = 0;
1400
+ reportMemory();
1265
1401
  old.terminate().catch(() => {});
1266
1402
  setBindingState({ ...bindingState, version: bindingState.version + 1 });
1267
1403
  }
@@ -1332,7 +1468,14 @@ function useAsyncQuery(run, deps, isRefreshing) {
1332
1468
  setState(s => (isRefresh && s.data !== null ? { ...s, refreshing: true } : EMPTY));
1333
1469
  }
1334
1470
  const held = [];
1471
+ // From the first await to the last. Between a hook's load and its query
1472
+ // nothing else is in flight, and a release there would end the engine
1473
+ // holding the table the query is about to read.
1474
+ busy++;
1335
1475
  const settled = run(name => held.push(pin(name)));
1476
+ settled.catch(() => {}).finally(() => {
1477
+ busy--;
1478
+ });
1336
1479
  settled.then(
1337
1480
  result => {
1338
1481
  if (active) setState({ ...result, error: null, loading: false, refreshing: false });
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@makoai/app-sdk",
3
- "version": "2.12.0",
3
+ "version": "2.13.0",
4
4
  "description": "Mako app SDK: data bindings (useQuery/useDuckDB), URL state, theme, and the house dashboard kit (/ui).",
5
5
  "license": "MIT",
6
6
  "repository": {