@makoai/app-sdk 2.15.0 → 2.16.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 +30 -0
- package/data-core.js +19 -0
- package/index.js +15 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -42,6 +42,36 @@ const { refresh, refreshing } = useQuery("latest_sales");
|
|
|
42
42
|
</button>
|
|
43
43
|
```
|
|
44
44
|
|
|
45
|
+
### Performance: SQL does the work
|
|
46
|
+
|
|
47
|
+
One 193k-row app froze ~10 s on every filter click. It loaded the binding
|
|
48
|
+
with `useQuery` and filtered it in a component. The rules:
|
|
49
|
+
|
|
50
|
+
1. Filters, joins and aggregation run in SQL through `useDuckDB(sql)`, filters
|
|
51
|
+
in the `WHERE` clause. Only the rows a panel draws come back to JS.
|
|
52
|
+
`withConnection` serves a result several panels share. `useQuery(name)` is
|
|
53
|
+
for bindings under ~10k rows or already aggregated to what the page shows.
|
|
54
|
+
2. One query per panel. Each panel returns a skeleton of its final size while
|
|
55
|
+
`loading`, never a "0" or an empty chart. Filter controls update on the
|
|
56
|
+
click frame; panels read filters through `useDeferredValue` or
|
|
57
|
+
`startTransition`.
|
|
58
|
+
3. Measure before calling a UI done: the clicked control updates in under
|
|
59
|
+
50 ms, no main-thread task runs over 200 ms during a filter change.
|
|
60
|
+
4. Keep bindings small: aggregate in the binding, drop unused columns, split
|
|
61
|
+
a binding when one view needs far more rows.
|
|
62
|
+
5. One engine: never a private parquet reader or a second DuckDB.
|
|
63
|
+
|
|
64
|
+
```tsx
|
|
65
|
+
const f = useDeferredValue(country);
|
|
66
|
+
const q = useDuckDB(`select day, sum(revenue) r from latest_sales
|
|
67
|
+
where country = '${f.replace(/'/g, "''")}' group by 1 order by 1`);
|
|
68
|
+
if (q.loading) return <div className="skeleton" style={{ height: 280 }} />;
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
In dev (`import.meta.env.DEV`), `useQuery` logs one `console.warn` per
|
|
72
|
+
binding that returns more than 20,000 rows, pointing to
|
|
73
|
+
`useDuckDB` (2.16+). Production builds never warn.
|
|
74
|
+
|
|
45
75
|
### Which SDK is running: `SDK_VERSION` (2.9+)
|
|
46
76
|
|
|
47
77
|
`import { SDK_VERSION } from "@makoai/app-sdk"` is this package's version.
|
package/data-core.js
CHANGED
|
@@ -360,3 +360,22 @@ export function retryDelayMs(error, retries) {
|
|
|
360
360
|
const wait = table[retries] ?? Infinity;
|
|
361
361
|
return Math.max(wait, typeof error.retryAfterMs === "number" ? error.retryAfterMs : 0);
|
|
362
362
|
}
|
|
363
|
+
|
|
364
|
+
/** Rows past which `useQuery` warns in dev: a page that filters this many in JS janks. */
|
|
365
|
+
export const LARGE_QUERY_ROWS = 20000;
|
|
366
|
+
|
|
367
|
+
/**
|
|
368
|
+
* The dev-console warning for a `useQuery` that handed JS `rows` rows, or null
|
|
369
|
+
* at or under `limit`. The fix is SQL: `useDuckDB` filters and aggregates in
|
|
370
|
+
* DuckDB and returns only what a panel draws.
|
|
371
|
+
*/
|
|
372
|
+
export function largeQueryWarning(name, rows, limit = LARGE_QUERY_ROWS) {
|
|
373
|
+
if (!(rows > limit)) return null;
|
|
374
|
+
return (
|
|
375
|
+
"[@makoai/app-sdk] useQuery(" + JSON.stringify(String(name)) + ") returned " +
|
|
376
|
+
rows.toLocaleString("en-US") + " rows to JS. Filtering or aggregating them in a component " +
|
|
377
|
+
"blocks the main thread on every filter change. Run filters, joins and aggregation in SQL " +
|
|
378
|
+
"with useDuckDB(\"select … from " + quoteIdent(name) + " where …\"), one query per panel, " +
|
|
379
|
+
"so only the rows a panel draws come back. (Dev-only warning, shown once per binding.)"
|
|
380
|
+
);
|
|
381
|
+
}
|
package/index.js
CHANGED
|
@@ -29,6 +29,7 @@ import {
|
|
|
29
29
|
toPlainRows,
|
|
30
30
|
parseBindingSnapshot,
|
|
31
31
|
snapshotUrl,
|
|
32
|
+
largeQueryWarning,
|
|
32
33
|
} from "./data-core.js";
|
|
33
34
|
|
|
34
35
|
/**
|
|
@@ -36,7 +37,7 @@ import {
|
|
|
36
37
|
* in a page (or this export) says which SDK a deployed app actually runs.
|
|
37
38
|
* Kept in step with package.json by snapshot.test.mjs.
|
|
38
39
|
*/
|
|
39
|
-
export const SDK_VERSION = "2.
|
|
40
|
+
export const SDK_VERSION = "2.16.0";
|
|
40
41
|
if (typeof window !== "undefined") {
|
|
41
42
|
try {
|
|
42
43
|
window.__MAKO_APP_SDK__ = SDK_VERSION;
|
|
@@ -1680,6 +1681,18 @@ function useSnapshotPreview(name, enabled, rowLimit) {
|
|
|
1680
1681
|
return preview;
|
|
1681
1682
|
}
|
|
1682
1683
|
|
|
1684
|
+
// Vite replaces import.meta.env with { DEV: false, … } in every build, so this
|
|
1685
|
+
// is false in production and outside Vite (import.meta.env undefined).
|
|
1686
|
+
const DEV_BUILD = Boolean(import.meta.env && import.meta.env.DEV);
|
|
1687
|
+
const warnedLarge = new Set();
|
|
1688
|
+
function warnIfLarge(name, rows) {
|
|
1689
|
+
if (!DEV_BUILD || warnedLarge.has(name)) return;
|
|
1690
|
+
const message = largeQueryWarning(name, rows);
|
|
1691
|
+
if (!message) return;
|
|
1692
|
+
warnedLarge.add(name);
|
|
1693
|
+
console.warn(message);
|
|
1694
|
+
}
|
|
1695
|
+
|
|
1683
1696
|
export function useQuery(name, opts) {
|
|
1684
1697
|
bootEngine();
|
|
1685
1698
|
const rowLimit = opts ? opts.rowLimit : undefined;
|
|
@@ -1690,6 +1703,7 @@ export function useQuery(name, opts) {
|
|
|
1690
1703
|
hold(name);
|
|
1691
1704
|
await registerBinding(name);
|
|
1692
1705
|
const r = await runSql("SELECT * FROM " + quoteIdent(name), rowLimit, undefined, new Set([name]));
|
|
1706
|
+
warnIfLarge(name, r.rows.length);
|
|
1693
1707
|
return { data: r.rows, fields: r.fields, truncated: r.truncated, rowCount: r.rowCount };
|
|
1694
1708
|
},
|
|
1695
1709
|
[name, rowLimit],
|