@lotics/app-sdk 0.109.0 → 0.110.0

package/AGENTS.md

@@ -14,7 +14,7 @@ This file is the index. The **exact type** of anything is its shipped declaratio
 
 | Doc | Read it for |
 |---|---|
-| [docs/data_fetching.md](./docs/data_fetching.md) | The reads: `useQuery(alias, params, opts)` — its rows (`limit`), numbered pages (`page`), a keyset feed (`more`), its `total` or the total alone, with `total: { by }` a count per value of one column — `useQueries` for reads known only at render, `queryAll` outside React, `exportQuery` for a file of them the server makes; every hook answers one `QueryState`. The ROW type (`RowOf` — the alias's projected columns and nothing else), runtime `sort`/`filter` keys, cell readers (`row.*`, `readSelect`, `readMembers`, `readLinks`, `readFiles`, `readLocked`, `readCreatedAt`/`readUpdatedAt`), the SDK's own cache — **arrival revalidates** — **realtime push**, a write drawn on every read from the press, a count as its own full scan, and the search-as-you-type and record-picker patterns. |
+| [docs/data_fetching.md](./docs/data_fetching.md) | The reads: `useQuery(alias, params, opts)` — its rows (`limit`), numbered pages (`page`), a keyset feed (`more`), its `total` or the total alone, with `total: { by }` a count per value of one column and `total: { where }` a count per named filter, from one scan — `useQueries` for reads known only at render, `queryAll` outside React, `exportQuery` for a file of them the server makes; every hook answers one `QueryState`. The ROW type (`RowOf` — the alias's projected columns and nothing else), runtime `sort`/`filter` keys, cell readers (`row.*`, `readSelect`, `readMembers`, `readLinks`, `readFiles`, `readLocked`, `readCreatedAt`/`readUpdatedAt`), the SDK's own cache — **arrival revalidates** — **realtime push**, a write drawn on every read from the press, a count as its own full scan, and the search-as-you-type and record-picker patterns. |
 | [docs/queries.md](./docs/queries.md) | **The query engine reference** — AST node kinds, per-field-type operators, filters/params/pruning, free-text search, combining tables, shaping (aggregates, date buckets, windows), runtime refinement bounds, limits and the efficiency playbook. |
 | [docs/mutations.md](./docs/mutations.md) | `useWorkflow` (the ONLY write path; `useWorkflows` for writes that are data), the `WorkflowResult` resolve-never-throw contract (`field_errors`), typed inputs, every write drawn on every read from the press — predicted from the workflow's own steps, taken back on a refusal, `pending` meanwhile — the re-read a successful write triggers over the tables its body names, diff-before-update, locked records, `useNewRecord`, read-after-write ordering (`writesSettled()`), `useRecording`, `useRecordings` over several aliases. |
 | [docs/workflows.md](./docs/workflows.md) | **The workflow-BODY reference** — the JS subset a body may use, opaque `fld_*`/`opt_*` keys, every step form, the accepted sugar, helpers, record-write surfaces, the traps and the verify loop. |

package/dist/index.js

@@ -30975,13 +30975,25 @@ function pageOf(mocked, call) {
 function countOf(mocked, by) {
   return { total: mocked.length, ...by === void 0 ? {} : { counts: countsOf(mocked, by) } };
 }
+function within(filter2, named) {
+  return filter2 === void 0 ? named : { node_type: "group", logic: "and", children: [filter2, named] };
+}
+function mockCount(alias, call) {
+  const mocked = getMockRows(alias, { params: call.params, filter: call.filter });
+  if (mocked === null) return null;
+  const where = Object.entries(call.where ?? {});
+  const named = where.map(([, one]) => getMockRows(alias, { params: call.params, filter: within(call.filter, one) }) ?? []);
+  const answer = (rows, each) => call.where === void 0 ? countOf(rows, call.by) : { total: rows.length, counts: Object.fromEntries(where.map(([name], at2) => [name, each[at2]?.length ?? 0])) };
+  if (Array.isArray(mocked) && named.every((one) => Array.isArray(one))) return answer(mocked, named.filter((one) => Array.isArray(one)));
+  return Promise.all([mocked, ...named]).then(([rows = [], ...each]) => answer(rows, each));
+}
 function knownRows(alias, call) {
   const mocked = getMockRows(alias, call);
   return Array.isArray(mocked) ? pageOf(mocked, call) : void 0;
 }
 function knownCount(alias, call) {
-  const mocked = getMockRows(alias, { params: call.params, filter: call.filter });
-  return Array.isArray(mocked) ? countOf(mocked, call.by) : void 0;
+  const counted = mockCount(alias, call);
+  return counted === null || counted instanceof Promise ? void 0 : counted;
 }
 async function askRows(key, alias, askedAt, call, since = askedAt) {
   const mocked = getMockRows(alias, call);
@@ -30998,18 +31010,22 @@ async function askRows(key, alias, askedAt, call, since = askedAt) {
   return answer;
 }
 async function askCount(key, alias, askedAt, call) {
-  const mocked = getMockRows(alias, { params: call.params, filter: call.filter });
-  if (mocked !== null) return countOf(await mocked, call.by);
+  const mocked = mockCount(alias, call);
+  if (mocked !== null) return mocked;
   const answer = await rpc("query", {
     alias,
     params: call.params,
     count: true,
     ...call.filter === void 0 ? {} : { filter: call.filter },
-    ...call.by === void 0 ? {} : { count_by: call.by }
+    ...call.by === void 0 ? {} : { count_by: call.by },
+    ...call.where === void 0 ? {} : { count_where: call.where }
   });
   noteAnswer(key, alias, askedAt, []);
   return answer;
 }
+function namedCounts(named) {
+  return { rows: Object.fromEntries(named.map(([name, one]) => [name, one.rows])), pending: named.some(([, one]) => one.pending) };
+}
 var feedWants = /* @__PURE__ */ new Map();
 function ignore() {
 }
@@ -31022,7 +31038,8 @@ function useQuery(alias, params = {}, opts = {}) {
   const filter2 = opts.filter;
   const wantsRows = opts.rows ?? true;
   const totalAsked = opts.total ?? opts.page !== void 0;
-  const by = typeof totalAsked === "object" ? totalAsked.by : void 0;
+  const by = typeof totalAsked === "object" && "by" in totalAsked ? totalAsked.by : void 0;
+  const where = typeof totalAsked === "object" && "where" in totalAsked ? totalAsked.where : void 0;
   const call = JSON.stringify([params, filter2 ?? null, sort ?? null]);
   const mocking = hasMockFlag();
   const [paging, setPaging] = useState3({ call, page: 0 });
@@ -31077,11 +31094,12 @@ function useQuery(alias, params = {}, opts = {}) {
     feedWants.set(feedKey, heldPages + 1);
     feed.refetch();
   }, [feedKey, feedHasMore, heldPages, feed]);
-  const countKey = !enabled || totalAsked === false ? null : JSON.stringify(["count", alias, JSON.stringify([params, filter2 ?? null]), by ?? null]);
-  const count = useKey(countKey, (askedAt) => askCount(countKey ?? "", alias, askedAt, { params, filter: filter2, by }), {
+  const countKey = !enabled || totalAsked === false ? null : JSON.stringify(["count", alias, JSON.stringify([params, filter2 ?? null]), by ?? null, where ?? null]);
+  const countCall = { params, ...filter2 === void 0 ? {} : { filter: filter2 }, ...by === void 0 ? {} : { by }, ...where === void 0 ? {} : { where } };
+  const count = useKey(countKey, (askedAt) => askCount(countKey ?? "", alias, askedAt, countCall), {
     focus,
     aliases: [alias],
-    known: mocking ? () => knownCount(alias, { params, filter: filter2, by }) : void 0
+    known: mocking ? () => knownCount(alias, countCall) : void 0
   });
   const version3 = useWrittenVersion();
   const drawn2 = useMemo3(() => {
@@ -31097,9 +31115,10 @@ function useQuery(alias, params = {}, opts = {}) {
   const counted = useMemo3(() => {
     if (count.data === void 0) return void 0;
     const total2 = overlayCount(alias, params, filter2, count.askedAt, count.data.total);
-    const counts = by === void 0 || count.data.counts === void 0 ? void 0 : overlayCounts(alias, params, filter2, by, count.askedAt, count.data.counts);
+    const answered2 = count.data.counts;
+    const counts = answered2 === void 0 ? void 0 : where !== void 0 ? namedCounts(Object.entries(where).map(([name, one]) => [name, overlayCount(alias, params, within(filter2, one), count.askedAt, answered2[name] ?? 0)])) : by === void 0 ? void 0 : overlayCounts(alias, params, filter2, by, count.askedAt, answered2);
     return { total: total2.rows, counts: counts?.rows, pending: total2.pending || (counts?.pending ?? false) };
-  }, [alias, call, by, count.data, count.askedAt, version3]);
+  }, [alias, call, countKey, count.data, count.askedAt, version3]);
   const total = counted?.total;
   const pageCount = opts.page === void 0 || total === void 0 ? void 0 : Math.max(1, Math.ceil(total / opts.page));
   const pageHasMore = opts.page === void 0 ? false : total !== void 0 ? (page + 1) * opts.page < total : drawn2.rows.length === opts.page;

package/dist/queries.d.ts

@@ -89,10 +89,13 @@ export interface QueryOptions<C extends string = string> {
     more?: number;
     /**
      * The total the rows come to — a count of the whole set, its own read, so the rows never wait for it —
-     * or with `by` a count per value of that column from the same scan. On by default with `page`.
+     * with `by` a count per value of that column from the same scan, or with `where` a count per named filter
+     * of the rows it keeps within the set, every one from the same scan. On by default with `page`.
      */
     total?: boolean | {
         by: C;
+    } | {
+        where: Readonly<Record<string, QueryFilter<C>>>;
     };
     /** `false` reads no rows: a total alone. Default `true`. */
     rows?: boolean;
@@ -103,7 +106,8 @@ export interface QueryState<R> {
     truncated: boolean;
     /** The whole set's count, where `total` is asked; `undefined` until it answers. */
     total: number | undefined;
-    /** Rows per value of `total.by`, keyed as a row carries it (an option's `opt_…`); a value no row holds is absent. */
+    /** Rows per value of `total.by`, keyed as a row carries it (an option's `opt_…`), a value no row holds absent;
+     *  or per name of `total.where`. */
     counts: Readonly<Record<string, number>> | undefined;
     /** Only the first read of a key with nothing to show; a re-read and a new key keep the rows on screen. */
     loading: boolean;

package/docs/data_fetching.md

@@ -21,7 +21,7 @@ untyped. It is written from the app's live bindings by `lotics app create --cust
 | `useQuery(alias, params?, opts?)` | `rows` up to the server's cap, or the first `limit` | a detail read, a dashboard block, a combobox's top-N — anything that is not a long list |
 | `useQuery(alias, params?, { page: n })` | one numbered page of `n` rows, `total`, `pageCount`, `setPage` | numbered, jumpable pages |
 | `useQuery(alias, params?, { more: n })` | accumulated `rows` + `loadMore` | infinite scroll / "load more" feeds |
-| `useQuery(alias, params?, { rows: false, total: true })` | `total` only, no rows (`total: { by: column }` adds `counts`) | a facet chip, a queue badge, an "N awaiting approval" tile — the size of a set you are not listing |
+| `useQuery(alias, params?, { rows: false, total: true })` | `total` only, no rows (`total: { by: column }` or `total: { where: { name: filter } }` adds `counts`) | a facet chip, a queue badge, an "N awaiting approval" tile — the size of a set you are not listing |
 | `useQueries(calls, opts?)` | one state per `{ alias, params?, filter?, sort?, aggregate?, total?, rows? }`, in order — a `sort` orders that call's rows before the cap cuts them | reads that are DATA — a list known only at render, one read per item, or one count per stage (`rows: false, total: true`, each state's `.total`); the deploy's alias scan reads a list as dynamic, so every alias in it is still declared. With `aggregate` a call answers the groups of its filtered rows instead of the rows ([queries](./queries.md)) |
 | `queryAll(alias, params?, { filter, sort })` | a promise of every row | outside React, for a job that must hold the whole narrowed set in the browser (the ids an act runs on): it asks page after page until the server says the set ended, never stopping at the 10,000-row cap. The server's rows as stored — no write of this app is drawn over them |
 | `exportQuery(alias, { params, filter, sort, tabs?, report, file })` | a promise of the file | every row the narrowed set holds, made into one file by the server — no row reaches the browser. `tabs` (2 to 5, each `{ tab, label, filter?, sort? }`) are each read as the export's own rows are — same query and params, under the tab's own filter and sort (absent, the declared order) — and a template reads each one's rows under its `tab`, a name none of the report's keys nor the template's `rows` key holds. `report` is `{ title, lines, readings, dates?, period?, per?, filename? }` — `dates` each date filter's `{ from?, to? }` by field alias, each bound a day (`yyyy-MM-dd`) or a minute of one (`yyyy-MM-ddTHH:mm`) with no zone; `period` the tabs' `{ from, to }`, bounds of the same form; `per` the value the report was picked for, in the reader's words; `filename` the file's name in the template grammar over one value each — `title`, `at` (the moment the server made the file), `dates.<field>.from` or `.to`, `period.from` or `.to`, `per`, `lines | lookup:<n>` — at most 200 bytes once filled (absent, the template's name, or `title`); `file` is `{ kind: "workbook", language, sheet, columns }` (the default report workbook, its head closing with the moment the server made it, each column `{ key, header, type }` an output column of the query — a `number` one on a number column, a `date` one on a date or datetime; with `tabs`, one sheet per tab named by its `label` in place of `sheet`) or `{ kind: "template", template }`, one the query declares under `templates` by name ([queries](./queries.md)). Past 20,000 rows, in any tab, it rejects, never cuts; each caller makes at most 60 exports a minute. The file's `url` is signed for the caller: open it with `openExternal` |
@@ -63,7 +63,15 @@ const { total, counts } = useQuery("orders", { q }, { rows: false, total: { by:
 // counts?.["opt_shipped"] — the rows in that stage over the whole set, however few are loaded
 ```
 
-A `useQueries` call's `total` is `true` or absent — it takes no `by`.
+Several counts of one set — a tab each, a share each — are **one read with `total: { where }`**: each
+named filter's rows within the read's `filter`, as `counts` by name, from the same scan.
+
+```tsx
+const { total, counts } = useQuery("orders", {}, { rows: false, total: { where: { late: lateFilter, mine: mineFilter } } });
+// counts?.late, counts?.mine — one scan, however many names
+```
+
+A `useQueries` call's `total` is `true` or absent — it takes no `by` or `where`.
 
 ### Why not hand-roll it
 

package/docs/mutations.md

@@ -526,7 +526,7 @@ every read before the request answers:
   leaves it; a created row it admits joins it, standing by the read's order (the call's `sort`,
   then the query's own) where its sort cells are numbers or dates, else first. A row the read does
   not hold that a write may move into it waits for the server, and `pending` says so.
-- **Totals.** A `total`, a count per value (`total: { by }`), a group asked with `aggregate` or
+- **Totals.** A `total`, a count per value (`total: { by }`) or per named filter (`total: { where }`), a group asked with `aggregate` or
   declared by the query, and a parent's count or sum rollup move by exactly what the written row adds
   or takes away; a group the last row leaves is gone, and a count per value gains the value a row
   first holds. A mean, an extreme, a distinct count, a group by day, an aggregate with its own

package/docs/queries.md

@@ -844,7 +844,10 @@ template as derived nodes, in this order: `filter` (narrow) → `sort` (order)
 - **`count: true`** — returns `{ total }` only: a COUNT over the *filtered* set, ignoring
   sort/limit/offset. Drives "Page 1 of N". With **`count_by: "<column>"`** the same scan also
   returns `counts` — rows per value of that projected column (a multi-value row under each value,
-  a row holding none in `total` only); a column whose values are not plain (a link) → 400. It is a
+  a row holding none in `total` only); a column whose values are not plain (a link) → 400. With
+  **`count_where: { <name>: <filter> }`** (not beside `count_by`) the same scan returns `counts` by
+  name — the rows each filter keeps within `filter`, each filter bounded and resolved as `filter` is,
+  at most 32. It is a
   **second full execution** of the template — sent only where a read asks for its `total`, and
   one count serves every read of the same set ([data_fetching](./data_fetching.md)).
 - **`aggregate: { by?, day?, sum? }`** — the groups of the *filtered* set in place of its rows: one

package/docs/security.md

@@ -111,7 +111,7 @@ Listing members (`useMembers`) takes an authenticated member of the app's own or
 
 ## What runtime refinement cannot widen
 
-The query RPC accepts runtime `filter` and `sort` (for search boxes, sortable tables, pickers) — but these are **bounded to the named query's output columns**. A `field_key` naming a column the query does not project is rejected, so a caller can never filter or sort by — and thereby probe — a field the author didn't expose. The caller's `limit` is clamped to the server row cap, params fill the template's *value holes* only — filter values and the search term; tables, joins, and projections are author-fixed — and `count` mode returns a total — with `count_by`, one per value of a projected column — over the same bounded filter. Full mechanics in [queries](./queries.md).
+The query RPC accepts runtime `filter` and `sort` (for search boxes, sortable tables, pickers) — but these are **bounded to the named query's output columns**. A `field_key` naming a column the query does not project is rejected, so a caller can never filter or sort by — and thereby probe — a field the author didn't expose. The caller's `limit` is clamped to the server row cap, params fill the template's *value holes* only — filter values and the search term; tables, joins, and projections are author-fixed — and `count` mode returns a total — with `count_by`, one per value of a projected column; with `count_where`, one per named filter, each bounded as `filter` is — over the same bounded filter. Full mechanics in [queries](./queries.md).
 
 **Warning — templated free-text search is not output-bounded.** A `search` term in the query template (typically a `{{params.q}}` hole) matches against the record's **whole search document**: every searchable field of the table — text, numbers, dates (in three formats), select option names, member names, linked-record display text, formula/rollup/lookup values, and autonumbers (only booleans, buttons, and file fields are excluded). It is *not* restricted to the columns the query projects. A caller who controls the search term can therefore probe the *contents* of unprojected fields by watching which rows match — a row-membership oracle. Put a `search` hole only in queries over tables where every searchable field is acceptable to probe for that audience; for a search box over a table with sensitive unprojected fields, use runtime `filter` with `contains` on the projected columns instead, or AND the `search` with a template `contains` OR-group over the fields that may be probed — every row that group matches also matches the search, so the pair answers only for those fields.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/app-sdk",
-  "version": "0.109.0",
+  "version": "0.110.0",
   "description": "The SDK a Lotics custom-code app reads and writes through \u2014 typed hooks over the host bridge, cell readers, mount() and AppRouter",
   "type": "module",
   "exports": {