@makoai/app-sdk 2.8.0 → 2.9.1

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
@@ -42,6 +42,34 @@ const { refresh, refreshing } = useQuery("latest_sales");
42
42
  </button>
43
43
  ```
44
44
 
45
+ ### Which SDK is running: `SDK_VERSION` (2.9+)
46
+
47
+ `import { SDK_VERSION } from "@makoai/app-sdk"` is this package's version.
48
+ Importing the SDK also sets `window.__MAKO_APP_SDK__` to it. In DevTools,
49
+ switch the console context to the app's frame and read
50
+ `__MAKO_APP_SDK__` to see which release a deployed app's build resolved.
51
+
52
+ ### Preview rows while the parquet loads (2.9+, opt-in)
53
+
54
+ ```tsx
55
+ const { data, loading, preview } = useQuery("latest_sales", { snapshot: true });
56
+ // loading && preview → paint preview.data as a skeleton table
57
+ // !loading → data is the full binding; preview is null
58
+ ```
59
+
60
+ Every build writes its first 500 rows (200 KiB cap) next to the parquet as
61
+ `__data/<name>.snapshot.json`. With `snapshot: true` the hook fetches it once
62
+ per page (skipped when the parquet is already loaded) and exposes it as
63
+ `preview` = `{ data, fields, rowCount, truncated, builtAt }`. `data` and
64
+ `loading` behave exactly as without the option, and a failed load clears
65
+ `preview`. Preview values have the same types as `data` (DATE →
66
+ `"YYYY-MM-DD"`, TIMESTAMP → ISO 8601, a 64-bit integer past 2^53 → BigInt).
67
+ The snapshot is the first N rows of the build stream in the query's own
68
+ order, with no `ORDER BY` guarantee. Use it for a skeleton or first paint.
69
+ Never aggregate it. `preview` is null when a binding has no snapshot (built
70
+ before 2.9's server release, live, a laptop draft still building, or a
71
+ DECIMAL/LIST/STRUCT column). Without the option no snapshot is fetched.
72
+
45
73
  `useDuckDB(...).refresh()` refreshes every binding; `refreshBinding(name)` /
46
74
  `refreshBindings()` do the same outside a component. A refresh POSTs to
47
75
  `__data/<name>/refresh`, the data URL's sibling, so whoever serves the app's
@@ -246,8 +274,9 @@ import { makoData } from "@makoai/app-sdk/vite";
246
274
  export default defineConfig({ plugins: [react(), makoData()] });
247
275
  ```
248
276
 
249
- `makoData()` answers `__data/index.json` (the app's `bindings/*.sql`) and
250
- `__data/<name>.parquet` during `vite dev` from the Mako API, and what it asks
277
+ `makoData()` answers `__data/index.json` (the app's `bindings/*.sql`),
278
+ `__data/<name>.parquet` and `__data/<name>.snapshot.json` during `vite dev`
279
+ from the Mako API, and what it asks
251
280
  for is **your local binding file**: it sends the text of
252
281
  `bindings/<name>.sql` and gets back the parquet of exactly that query, run
253
282
  read-only through the workspace connection its front matter names. When the
@@ -257,6 +286,10 @@ from your text and hands it back without storing it — nobody else, and no
257
286
  published viewer, ever sees uncommitted SQL. Building needs edit access to the
258
287
  app; read-only members get committed artifacts. `POST __data/<name>/refresh`
259
288
  (the SDK's `refresh()`) rebuilds from the local text on demand.
289
+ `__data/<name>.snapshot.json` is asked for by the same text: the API answers
290
+ with the snapshot of exactly the stored artifact that text maps to, and 404
291
+ while a draft still needs building. An edited query never paints the
292
+ committed query's preview. Snapshots are not cached locally.
260
293
 
261
294
  Builds run as jobs: the plugin asks for one (`async`), gets a job id back at
262
295
  once, and polls it until the parquet is ready — so a query that runs for
package/data-core.js CHANGED
@@ -210,3 +210,91 @@ export function toPlainRows(table, cap) {
210
210
  }
211
211
  return { rows, fields };
212
212
  }
213
+
214
+ // ---------------------------------------------------------------------------
215
+ // Snapshot: `__data/<name>.snapshot.json`, the first N rows of the build
216
+ // stream, written next to the parquet (api/src/services/binding-snapshot.ts).
217
+ // The server already applied toPlainRows's rules (DATE → "YYYY-MM-DD",
218
+ // TIMESTAMP → ISO 8601). JSON cannot carry two things the parquet path can
219
+ // produce, so the server writes them as strings and this decoder restores
220
+ // them: a 64-bit integer past 2^53 (BigInt) and a non-finite float (NaN,
221
+ // ±Infinity). The server writes no snapshot at all for a column type JSON
222
+ // cannot reproduce (DECIMAL, LIST, STRUCT, …), and any type this decoder does
223
+ // not know rejects the whole snapshot — the app then waits for the parquet.
224
+ // ---------------------------------------------------------------------------
225
+ export const SNAPSHOT_VERSION = 1;
226
+
227
+ const SNAPSHOT_INT64 = new Set(["BIGINT", "UBIGINT"]);
228
+ const SNAPSHOT_FLOAT = new Set(["DOUBLE", "FLOAT"]);
229
+ const SNAPSHOT_PLAIN = new Set([
230
+ "BOOLEAN",
231
+ "TINYINT",
232
+ "SMALLINT",
233
+ "INTEGER",
234
+ "UTINYINT",
235
+ "USMALLINT",
236
+ "UINTEGER",
237
+ "VARCHAR",
238
+ "DATE",
239
+ "TIMESTAMP",
240
+ "TIMESTAMP_S",
241
+ "TIMESTAMP_MS",
242
+ "TIMESTAMP_NS",
243
+ "TIMESTAMP WITH TIME ZONE",
244
+ ]);
245
+
246
+ function snapshotDecoder(type) {
247
+ if (SNAPSHOT_INT64.has(type)) {
248
+ return v => (typeof v === "string" ? BigInt(v) : v);
249
+ }
250
+ if (SNAPSHOT_FLOAT.has(type)) {
251
+ return v => (typeof v === "string" ? Number(v) : v);
252
+ }
253
+ if (SNAPSHOT_PLAIN.has(type)) return v => v;
254
+ return null;
255
+ }
256
+
257
+ export function snapshotUrl(name) {
258
+ return "__data/" + encodeURIComponent(name) + ".snapshot.json";
259
+ }
260
+
261
+ /**
262
+ * A snapshot body as `{ data, fields, rowCount, truncated, builtAt }`, rows
263
+ * decoded to what the parquet path yields for the same values. Null when the
264
+ * body is malformed, from another version, or names a type this SDK does not
265
+ * decode — the caller then waits for the parquet as if there were none.
266
+ */
267
+ export function parseBindingSnapshot(body, rowLimit) {
268
+ if (!body || typeof body !== "object" || body.version !== SNAPSHOT_VERSION) return null;
269
+ if (!Array.isArray(body.rows) || !Array.isArray(body.fields)) return null;
270
+ const rowCount = Number(body.rowCount);
271
+ if (!Number.isInteger(rowCount) || rowCount < 0) return null;
272
+ const names = [];
273
+ const decoders = [];
274
+ for (const field of body.fields) {
275
+ if (!field || typeof field.name !== "string" || !field.name) return null;
276
+ const decode = snapshotDecoder(String(field.type));
277
+ if (!decode) return null;
278
+ names.push(field.name);
279
+ decoders.push(decode);
280
+ }
281
+ const cap = rowLimit === null ? Infinity : rowLimit == null ? Infinity : rowLimit;
282
+ const data = [];
283
+ for (const row of body.rows) {
284
+ if (!row || typeof row !== "object" || Array.isArray(row)) return null;
285
+ if (data.length >= cap) break;
286
+ const out = {};
287
+ for (let i = 0; i < names.length; i++) {
288
+ const v = row[names[i]];
289
+ out[names[i]] = v == null ? null : decoders[i](v);
290
+ }
291
+ data.push(out);
292
+ }
293
+ return {
294
+ data,
295
+ fields: names,
296
+ rowCount,
297
+ truncated: data.length < rowCount,
298
+ builtAt: typeof body.builtAt === "string" ? body.builtAt : null,
299
+ };
300
+ }
package/index.d.ts CHANGED
@@ -135,6 +135,31 @@ export interface DuckDBState<Row = Record<string, unknown>>
135
135
  export interface QueryOptions {
136
136
  rowLimit?: number | null;
137
137
  }
138
+ export interface UseQueryOptions extends QueryOptions {
139
+ /**
140
+ * Opt in to the preview: fetch `__data/<name>.snapshot.json` (the first
141
+ * rows of the last build, no DuckDB-WASM needed) while the parquet loads,
142
+ * and expose it as `preview`. `data`, `loading`, `phase` and every other
143
+ * field behave exactly as without it. Default false.
144
+ */
145
+ snapshot?: boolean;
146
+ }
147
+ /**
148
+ * The first rows of the binding's last build, for a skeleton or a first
149
+ * paint. The first N rows of the build stream in the query's own order: not
150
+ * a sample, not sorted, not filtered. Never aggregate it.
151
+ */
152
+ export interface QueryPreview<Row = Record<string, unknown>> {
153
+ /** At most a few hundred rows, typed exactly as `data` will be. */
154
+ data: Row[];
155
+ fields: string[];
156
+ /** Rows in the whole build, not in `data`. */
157
+ rowCount: number;
158
+ /** True when `data` holds fewer rows than `rowCount`. */
159
+ truncated: boolean;
160
+ /** ISO 8601, when the snapshot's build ran; null when unknown. */
161
+ builtAt: string | null;
162
+ }
138
163
  export interface DuckDBOptions extends QueryOptions {
139
164
  /**
140
165
  * "arrow": `data` is DuckDB's Arrow Table as returned (no row objects, no
@@ -168,15 +193,34 @@ export interface MakoLocation {
168
193
  searchParams: URLSearchParams;
169
194
  }
170
195
 
171
- /** Rows of a named data binding (bindings/<name>.sql, materialized). */
196
+ /**
197
+ * Rows of a named data binding (bindings/<name>.sql, materialized).
198
+ *
199
+ * With `{ snapshot: true }` the result also carries `preview`: the snapshot
200
+ * rows while `loading` is true and no error has arrived, null otherwise.
201
+ * `data` stays null until the full parquet is in, so code that sums or
202
+ * filters `data` never sees a prefix.
203
+ */
172
204
  export function useQuery<Row = Record<string, unknown>>(
173
205
  name: string,
174
- opts?: QueryOptions,
206
+ opts: UseQueryOptions & { snapshot: true },
175
207
  ): QueryState<Row> & {
176
208
  refresh: () => Promise<RefreshResult>;
177
209
  /** The binding's own progress record (null when it is not loading). */
178
210
  progress: BindingProgress | null;
211
+ preview: QueryPreview<Row> | null;
179
212
  };
213
+ export function useQuery<Row = Record<string, unknown>>(
214
+ name: string,
215
+ opts?: UseQueryOptions,
216
+ ): QueryState<Row> & {
217
+ refresh: () => Promise<RefreshResult>;
218
+ /** The binding's own progress record (null when it is not loading). */
219
+ progress: BindingProgress | null;
220
+ };
221
+
222
+ /** This package's version at runtime; pages also get `window.__MAKO_APP_SDK__`. */
223
+ export const SDK_VERSION: string;
180
224
 
181
225
  /**
182
226
  * Analytical SQL over the app's bindings; table names are binding names.
@@ -321,3 +365,15 @@ export function useSearchParams(): [
321
365
  ) => void,
322
366
  ];
323
367
  export function navigate(to: string, opts?: { replace?: boolean }): void;
368
+ /**
369
+ * The Mako shortcut a keydown stands for ("mod+k" for Cmd/Ctrl+K), or null.
370
+ * Inside Mako the SDK forwards these to the host, because a cross-origin
371
+ * app frame keeps its keystrokes from Mako's own listeners.
372
+ */
373
+ export function hostShortcutFor(event: {
374
+ key: string;
375
+ metaKey: boolean;
376
+ ctrlKey: boolean;
377
+ altKey: boolean;
378
+ shiftKey: boolean;
379
+ }): "mod+k" | null;
package/index.js CHANGED
@@ -23,8 +23,24 @@ import {
23
23
  readsCatalog,
24
24
  quoteString,
25
25
  toPlainRows,
26
+ parseBindingSnapshot,
27
+ snapshotUrl,
26
28
  } from "./data-core.js";
27
29
 
30
+ /**
31
+ * This package's version, visible at runtime: `window.__MAKO_APP_SDK__`
32
+ * in a page (or this export) says which SDK a deployed app actually runs.
33
+ * Kept in step with package.json by snapshot.test.mjs.
34
+ */
35
+ export const SDK_VERSION = "2.9.1";
36
+ if (typeof window !== "undefined") {
37
+ try {
38
+ window.__MAKO_APP_SDK__ = SDK_VERSION;
39
+ } catch {
40
+ /* a frozen window: nothing to stamp */
41
+ }
42
+ }
43
+
28
44
  const DEFAULT_ROW_LIMIT = 500000;
29
45
  const DUCKDB_ESM =
30
46
  "https://cdn.jsdelivr.net/npm/@duckdb/duckdb-wasm@1.29.0/+esm";
@@ -202,6 +218,7 @@ async function loadBinding(name, bust) {
202
218
  } finally {
203
219
  await engine.dropFile(file).catch(() => {});
204
220
  }
221
+ loadedBindings.add(name);
205
222
  } finally {
206
223
  // A refresh owns the record until its reload is done (refreshBinding).
207
224
  if (!refreshes.has(name)) setProgress(name, null);
@@ -209,6 +226,7 @@ async function loadBinding(name, bust) {
209
226
  }
210
227
 
211
228
  const registered = new Map(); // name -> Promise<void>
229
+ const loadedBindings = new Set(); // names whose table is in DuckDB
212
230
  // Refreshed on the server while never loaded on this page: the next load
213
231
  // must skip any cache between here and the server.
214
232
  const staleBindings = new Set();
@@ -266,6 +284,7 @@ export async function unloadBinding(name) {
266
284
  const pending = registered.get(name);
267
285
  if (!pending) return;
268
286
  registered.delete(name);
287
+ loadedBindings.delete(name);
269
288
  await pending.catch(() => {});
270
289
  await withConnection(conn => conn.query("DROP TABLE IF EXISTS " + quoteIdent(name)));
271
290
  }
@@ -555,9 +574,53 @@ function hookProgress(record, state) {
555
574
  };
556
575
  }
557
576
 
577
+ // ---------------------------------------------------------------------------
578
+ // Snapshot preview — opt-in with useQuery(name, { snapshot: true }). The
579
+ // server writes the first N rows of each build next to its parquet as
580
+ // `__data/<name>.snapshot.json`. It is the first N rows of the build stream
581
+ // in whatever order the query produced them, so it is a skeleton for the
582
+ // first paint, never data: `data` stays null and `loading` stays true until
583
+ // the table is in DuckDB (through every load phase), and `preview`
584
+ // disappears the moment either the rows or an error arrive. One request per
585
+ // binding per page, none once the table is already loaded; a binding
586
+ // without a snapshot is one cheap 404.
587
+ // ---------------------------------------------------------------------------
588
+ const snapshots = new Map(); // name -> Promise<body | null>
589
+ function loadSnapshot(name) {
590
+ if (!snapshots.has(name)) {
591
+ snapshots.set(
592
+ name,
593
+ fetch(snapshotUrl(name))
594
+ .then(r => (r.ok ? r.json() : null))
595
+ .catch(() => null),
596
+ );
597
+ }
598
+ return snapshots.get(name);
599
+ }
600
+
601
+ function useSnapshotPreview(name, enabled, rowLimit) {
602
+ const [preview, setPreview] = React.useState(null);
603
+ React.useEffect(() => {
604
+ setPreview(null);
605
+ if (!enabled || loadedBindings.has(name)) return;
606
+ let active = true;
607
+ loadSnapshot(name).then(body => {
608
+ if (!active || loadedBindings.has(name)) return;
609
+ const parsed = parseBindingSnapshot(body, rowLimit);
610
+ if (parsed) setPreview(parsed);
611
+ });
612
+ return () => {
613
+ active = false;
614
+ };
615
+ }, [name, enabled, rowLimit]);
616
+ return preview;
617
+ }
618
+
558
619
  export function useQuery(name, opts) {
559
620
  bootEngine();
560
621
  const rowLimit = opts ? opts.rowLimit : undefined;
622
+ const withSnapshot = Boolean(opts && opts.snapshot);
623
+ const preview = useSnapshotPreview(name, withSnapshot, rowLimit);
561
624
  const state = useAsyncQuery(
562
625
  async () => {
563
626
  await registerBinding(name);
@@ -569,7 +632,12 @@ export function useQuery(name, opts) {
569
632
  );
570
633
  const progress = useBindingProgress(name);
571
634
  const refresh = React.useCallback(() => refreshBinding(name), [name]);
572
- return { ...state, ...hookProgress(progress, state), progress, refresh };
635
+ const result = { ...state, ...hookProgress(progress, state), progress, refresh };
636
+ if (!withSnapshot) return result;
637
+ // Only while nothing final is on screen: not next to rows, not next to an
638
+ // error (a failed load must not leave preview rows looking final).
639
+ result.preview = state.loading && state.data === null && state.error === null ? preview : null;
640
+ return result;
573
641
  }
574
642
 
575
643
  /**
@@ -722,6 +790,41 @@ export function navigate(to, opts) {
722
790
  }
723
791
  }
724
792
 
793
+ // ---------------------------------------------------------------------------
794
+ // Host shortcuts — keys that belong to Mako, not the app.
795
+ //
796
+ // On its own origin (<appId>.makousercontent.com) the app is a cross-origin
797
+ // frame: a keydown while it has focus reaches only this document, so Mako's
798
+ // Cmd/Ctrl+K never fired. Hand the shortcut to the host instead, the same
799
+ // way navigate() hands over the query. Capture phase, so an app's own
800
+ // handlers cannot swallow it first.
801
+ // ---------------------------------------------------------------------------
802
+ export function hostShortcutFor(event) {
803
+ if (!(event.metaKey || event.ctrlKey) || event.altKey || event.shiftKey) {
804
+ return null;
805
+ }
806
+ return typeof event.key === "string" && event.key.toLowerCase() === "k"
807
+ ? "mod+k"
808
+ : null;
809
+ }
810
+
811
+ if (typeof window !== "undefined" && window.parent !== window) {
812
+ window.addEventListener(
813
+ "keydown",
814
+ event => {
815
+ const key = hostShortcutFor(event);
816
+ if (!key) return;
817
+ event.preventDefault();
818
+ try {
819
+ window.parent.postMessage({ type: "mako-app:shortcut", key }, "*");
820
+ } catch {
821
+ // A host that is not Mako: nothing to tell.
822
+ }
823
+ },
824
+ true,
825
+ );
826
+ }
827
+
725
828
  export function useLocation() {
726
829
  const [loc, setLoc] = React.useState(readLocation);
727
830
  React.useEffect(() => {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@makoai/app-sdk",
3
- "version": "2.8.0",
3
+ "version": "2.9.1",
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": {
package/vite.js CHANGED
@@ -609,12 +609,55 @@ export function makoData(options = {}) {
609
609
  }
610
610
  }
611
611
 
612
+ // `__data/<name>.snapshot.json` — the preview for
613
+ // useQuery(name, { snapshot: true }). It must describe the parquet
614
+ // this server is serving, never another definition's: with a local
615
+ // binding file the API is asked by its TEXT (dev-snapshot answers only
616
+ // for the stored artifact dev-build would answer that text with, and
617
+ // 404 while a draft still needs building); without one, the committed
618
+ // artifact by name, as fetchArtifact serves it. Never cached here, and
619
+ // every failure is a 404: the SDK then just waits for the parquet.
620
+ async function serveSnapshot(name, res) {
621
+ const none = () => json(res, 404, { error: "Snapshot not available" });
622
+ if (problems.length) return none();
623
+ const source = options.materialize === false || devBuildUnsupported ? null : readSource(name);
624
+ const base = `${appBase()}/bindings/${encodeURIComponent(name)}`;
625
+ try {
626
+ const r =
627
+ source === null
628
+ ? await apiFetch(`${base}/snapshot`, { headers: await headers() })
629
+ : await apiFetch(`${base}/dev-snapshot`, {
630
+ method: "POST",
631
+ headers: { ...(await headers()), "content-type": "application/json" },
632
+ body: JSON.stringify({
633
+ source,
634
+ ...(ctx.dbtEnvironment ? { dbtEnvironment: ctx.dbtEnvironment } : {}),
635
+ }),
636
+ });
637
+ if (!r.ok) return none();
638
+ const buf = Buffer.from(await r.arrayBuffer());
639
+ res.setHeader("content-type", "application/json; charset=utf-8");
640
+ res.setHeader("content-length", String(buf.length));
641
+ res.setHeader("cache-control", "no-store");
642
+ res.setHeader("x-mako-data", "api");
643
+ return res.end(buf);
644
+ } catch {
645
+ return none();
646
+ }
647
+ }
648
+
612
649
  server.middlewares.use(async (req, res, next) => {
613
650
  const [pathname, query = ""] = (req.url || "").split("?");
614
651
  if (pathname === "/__data/index.json") {
615
652
  return json(res, 200, listBindings(ctx.bindingsDir));
616
653
  }
617
654
  if (pathname === "/__data/viewer.json") return serveViewer(res);
655
+ const snap = /^\/__data\/([^/]+)\.snapshot\.json$/.exec(pathname);
656
+ if (snap) {
657
+ const name = decodeURIComponent(snap[1]);
658
+ if (!BINDING_NAME.test(name)) return json(res, 400, { error: "invalid binding name" });
659
+ return serveSnapshot(name, res);
660
+ }
618
661
  const match = /^\/__data\/([^/]+)(\.parquet|\/refresh)$/.exec(pathname);
619
662
  if (!match) return next();
620
663
  const name = decodeURIComponent(match[1]);