@lotics/app-sdk 0.82.3 → 0.83.1

package/AGENTS.md

@@ -16,7 +16,7 @@ signature; open the file.**
 |---|---|
 | [docs/recipes.md](./docs/recipes.md) | Task-shaped how-tos for the actions whose mechanism is not guessable from the hooks — returning a generated file, returning structured data, parameterized lookups, composable optional filters, cell decoding, testing an AI action without spending credits. |
 | [docs/queries.md](./docs/queries.md) | **The query engine authoring reference** — AST node kinds, per-field-type operator support, filters/params/pruning, free-text search, combining tables (join/union/link/`unnest`/`record_id`), shaping (aggregates, date buckets, windows), runtime refinement bounds, limits & the efficiency playbook. |
-| [docs/data_fetching.md](./docs/data_fetching.md) | The three read hooks (`useQuery`/`useInfiniteQuery`/`usePaginatedQuery`), the `QueryRow` shape (projected columns `unknown`; `__source_record_id`/`__source_table_id` typed but optional), cell readers (`row.*`, `readSelect`, `readMembers`, `readLinks`, `readFiles`, `readLocked`), `useFieldOptions`, caching — **arrival revalidates** (a re-mount renders cache *and* refreshes it in the background, `loading` never flips) — **realtime push** (a table one of your queries reads changes and that query refetches within about a second, alias-precise, records-only, host-embedded apps only), data discipline, the pagination count as a second full execution (and `total` to suppress it), the search-as-you-type + record-picker patterns. |
+| [docs/data_fetching.md](./docs/data_fetching.md) | The four read hooks (`useQuery`/`useInfiniteQuery`/`usePaginatedQuery`/`useCount` — the last for a number with no rows, sharing the `(alias, params, filter)` count key the paginated hook uses, so a list and a badge over one set buy one count; a count is a full scan and stays its OWN request so rows paint without waiting for it, and `rows.length` is never a count since rows truncate silently at 10,000), the `QueryRow` shape (projected columns `unknown`; `__source_record_id`/`__source_table_id` typed but optional), cell readers (`row.*`, `readSelect`, `readMembers`, `readLinks`, `readFiles`, `readLocked`), `useFieldOptions`, caching — **arrival revalidates** (a re-mount renders cache *and* refreshes it in the background, `loading` never flips) — **realtime push** (a table one of your queries reads changes and that query refetches within about a second, alias-precise, records-only, host-embedded apps only), data discipline, the pagination count as a second full execution (and `total` to suppress it), the search-as-you-type + record-picker patterns. |
 | [docs/mutations.md](./docs/mutations.md) | `useWorkflow` (the ONLY write path), the `WorkflowResult` resolve-never-throw contract, typed inputs, diff-before-update, locked records, `useOptimistic`, `useNewRecord` (client-minted `rec_*` id so a new-record surface never remounts on its first save), read-after-write ordering (a re-read must not overtake an in-flight write). |
 | [docs/workflows.md](./docs/workflows.md) | **The workflow-BODY authoring reference** — the JS subset a `src/workflows/<alias>.ts` body may use: the parse-at-save/never-execute model, opaque `fld_*`/`opt_*` keys, expression sources + link descent, every step form (tool call, `agent`, waits, `validate`, `return`), the accepted sugar and its canonical lowering, helpers + callback rules, record-write surfaces, the traps, the bright line, and the verify loop — `check` (the only local gate: the app's own `npm run typecheck` never sees a body) → `dry_run_workflow` (static green is not a run) → `set`. |
 | [docs/files.md](./docs/files.md) | Files end to end — `useFileUpload`, `useAttachments`, `readFiles`/presigned URLs (**a bearer credential for the bytes** — never logged, reported, or persisted), workflow-generated files, **naming a zip's entries** (`{ id, name }` per file — a file name, never a path), preview pairing, filter operators, the server-side delivery bounds. **Uploads declare a `fidelity`** (`standard` / `high` / `original`) — the app picks how much of the image survives storage; use `high` whenever text must stay legible. |

package/dist/src/hooks.d.ts

@@ -189,6 +189,19 @@ export interface InfiniteQueryOptions extends BaseQueryOptions {
     /** Rows per page. `loadMore()` appends the next page. */
     pageSize: number;
 }
+/**
+ * Options for `useCount` — one number, no rows.
+ *
+ * `sort` and `pageSize` are absent rather than ignored. A count is a single-row
+ * COUNT over the filtered set; ordering it and paginating it are meaningless,
+ * and an option a hook silently drops is worse than one that will not compile.
+ */
+export type CountOptions = Omit<BaseQueryOptions, "sort">;
+/** Return value of `useCount` — the size of a filtered set, and nothing else. */
+interface CountState extends QueryStateBase {
+    /** Rows in the filtered set. `undefined` until the count resolves. */
+    total: number | undefined;
+}
 /** Options for `usePaginatedQuery` — page-model with a total. */
 export interface PaginatedQueryOptions extends BaseQueryOptions {
     /** Rows per page. Default 25. */
@@ -386,6 +399,43 @@ export declare function useInfiniteQuery(alias: string, params?: Record<string,
  */
 export declare function usePaginatedQuery<K extends keyof AppQueries & string>(alias: K, ...args: QueryArgs<K, PaginatedQueryOptions>): PaginatedQueryState<QueryRow>;
 export declare function usePaginatedQuery(alias: string, params?: Record<string, unknown>, opts?: PaginatedQueryOptions): PaginatedQueryState<QueryRow>;
+/**
+ * HOW MANY rows a query matches — one number, no rows fetched.
+ *
+ * The shape behind a facet chip, a queue badge, a "N awaiting approval" tile:
+ * the screen wants the size of a set it is not listing. Reach for it instead of
+ * the two things that used to stand in for it, both of which are worse:
+ *
+ * - `usePaginatedQuery(alias, params, { pageSize: 1 })` buys a row nobody
+ *   renders — two requests for one integer, against a server that bounds how
+ *   many app queries run at once.
+ * - A hand-rolled `rpc("query", { count: true })` is one request and leaves the
+ *   cache: it does not dedupe with the page beside it, does not revalidate on
+ *   focus, and never hears the host's post-write refetch. The number then goes
+ *   stale over a set that has moved while everything around it updates, which
+ *   is the failure worth avoiding — a count that is quietly wrong costs more
+ *   than a count that costs a request.
+ *
+ * ONE COUNT PER FILTERED SET. The cache key is `(alias, params, filter)` — the
+ * very key `usePaginatedQuery` counts under — so a table and a badge over the
+ * same set issue ONE count between them, and a page click or a re-sort reuses
+ * it (a count is sort- and page-independent).
+ *
+ * **N counts over one source should not be N hooks.** Each declared query
+ * re-executes its whole `from` tree, so four facets mounted as four `useCount`s
+ * are four full scans that land in the same burst. When the counts differ only
+ * by a bucket the rows can be grouped on, one `group` query returns them all in
+ * a single scan and folds client-side (queries.md §10) — and its figure can be
+ * handed to `usePaginatedQuery`'s `total` so the list stops counting too. This
+ * hook is for the count that has no sibling to group with.
+ *
+ * ```tsx
+ * const { total } = useCount("orders", { q }, { filter: unpaidFilter });
+ * return <Badge label={total == null ? "…" : `${total}`} />;
+ * ```
+ */
+export declare function useCount<K extends keyof AppQueries & string>(alias: K, ...args: QueryArgs<K, CountOptions>): CountState;
+export declare function useCount(alias: string, params?: Record<string, unknown>, opts?: CountOptions): CountState;
 /** A file the host has stored and resolved serving URLs for. */
 export interface UploadedFile {
     id: string;

package/dist/src/hooks.js

@@ -85,6 +85,28 @@ function useHostRefetch(alias, refetch, mockRows) {
         });
     }, [alias, refetch, mockRows]);
 }
+/**
+ * THE COUNT READ, defined once — used by `usePaginatedQuery` for its page total
+ * and by `useCount` for a bare number.
+ *
+ * Both must agree on the SWR key and on the request body, byte for byte: that
+ * identity is what makes a table and a badge over the same set buy ONE count
+ * between them. Two hand-copied literals would hold today and diverge the first
+ * time one is edited, and the failure is silent — nothing breaks, the screen
+ * just quietly issues two full scans where it used to issue one. So there is one
+ * definition and no opportunity to disagree.
+ *
+ * The key omits PAGE and SORT deliberately: a count is independent of both, so
+ * page clicks and re-sorts reuse it. `active: false` yields a null key, and SWR
+ * issues nothing for a null key — which is how a caller-supplied total, a
+ * disabled hook and a fixture all suppress the request.
+ */
+function useCountRead(alias, params, filter, active, revalidateOnFocus) {
+    const key = active
+        ? ["app-query-count", alias, params ?? {}, filter ?? null]
+        : null;
+    return useSWR(key, () => rpc("query", { alias, params: params ?? {}, filter, count: true }), swrConfig(revalidateOnFocus));
+}
 export function useQuery(alias, params, opts) {
     const pageSize = opts?.pageSize;
     const enabled = opts?.enabled ?? true;
@@ -251,13 +273,9 @@ export function usePaginatedQuery(alias, params, opts) {
     }), 
     // Keep the previous page's rows on screen while the next page loads.
     { keepPreviousData: true, ...swrConfig(revalidateOnFocus) });
-    // Count key omits page AND sort — one count per result-set identity, reused
-    // across page clicks and re-sorts. Null when the caller supplies the total:
-    // SWR issues nothing for a null key, so the second scan never happens.
-    const countKey = mockRows || !enabled || callerOwnsTotal
-        ? null
-        : ["app-query-count", alias, params ?? {}, filter ?? null];
-    const countSwr = useSWR(countKey, () => rpc("query", { alias, params: params ?? {}, filter, count: true }), swrConfig(revalidateOnFocus));
+    // Not counted when the caller supplies the total, when the hook is disabled,
+    // or under a fixture — see `useCountRead` for why the key drops page and sort.
+    const countSwr = useCountRead(alias, params, filter, !mockRows && enabled && !callerOwnsTotal, revalidateOnFocus);
     const rows = mockRows ?? rowsSwr.data?.rows ?? [];
     // A supplied `null` reads out as `undefined` — "not known yet" is one state
     // to the consumer whether the hook is counting or the caller is.
@@ -287,6 +305,28 @@ export function usePaginatedQuery(alias, params, opts) {
         refetch,
     };
 }
+export function useCount(alias, params, opts) {
+    const enabled = opts?.enabled ?? true;
+    const revalidateOnFocus = opts?.revalidateOnFocus ?? true;
+    const filter = opts?.filter;
+    const mockRows = getMockRows(alias);
+    // The SAME read `usePaginatedQuery` uses for its total — one definition, so a
+    // list and a badge over one set can never drift into two scans.
+    const countSwr = useCountRead(alias, params, filter, !mockRows && enabled, revalidateOnFocus);
+    const refetch = useCallback(() => {
+        void countSwr.mutate();
+    }, [countSwr]);
+    useHostRefetch(alias, refetch, mockRows);
+    return {
+        // Under a fixture the whole set is the fixture, so its length IS the count —
+        // the same substitution every other hook makes for `rows`.
+        total: mockRows ? mockRows.length : countSwr.data?.total,
+        loading: mockRows ? false : countSwr.isLoading,
+        isValidating: mockRows ? false : countSwr.isValidating,
+        error: countSwr.error?.message ?? null,
+        refetch,
+    };
+}
 /**
  * Upload files from an app. The bytes are stored via a presigned
  * direct-to-storage upload the host mediates; the API server never proxies

package/dist/src/index.d.ts

@@ -16,8 +16,8 @@
  */
 export { mount } from "./mount.js";
 export type { MountOptions } from "./mount.js";
-export { useWorkflow, useQuery, useInfiniteQuery, usePaginatedQuery, useFieldOptions, useFileUpload, useAttachments, useMembers, useAgentRun, useAgentRuns, useAiContext, buildChoiceOutput, } from "./hooks.js";
-export type { QueryRow, UploadedFile, AttachedFile, BaseQueryOptions, QueryOptions, InfiniteQueryOptions, PaginatedQueryOptions, QuerySortKey, QueryFilter, QueryFilterCondition, QueryFilterFieldCondition, QueryFilterRecordIdCondition, QueryFilterGroup, WorkflowResult, MembersOptions, AgentRunOptions, UseAgentRun, AgentRunLanding, AgentRunRecord, AgentRunState, AgentUIPart, PendingChoice, ChoiceQuestion, ChoiceOption, AskUserChoiceOutput, FieldOptions, FieldOptionsState, FieldOptionsOptions, } from "./hooks.js";
+export { useWorkflow, useQuery, useInfiniteQuery, usePaginatedQuery, useCount, useFieldOptions, useFileUpload, useAttachments, useMembers, useAgentRun, useAgentRuns, useAiContext, buildChoiceOutput, } from "./hooks.js";
+export type { QueryRow, UploadedFile, AttachedFile, BaseQueryOptions, QueryOptions, InfiniteQueryOptions, PaginatedQueryOptions, CountOptions, QuerySortKey, QueryFilter, QueryFilterCondition, QueryFilterFieldCondition, QueryFilterRecordIdCondition, QueryFilterGroup, WorkflowResult, MembersOptions, AgentRunOptions, UseAgentRun, AgentRunLanding, AgentRunRecord, AgentRunState, AgentUIPart, PendingChoice, ChoiceQuestion, ChoiceOption, AskUserChoiceOutput, FieldOptions, FieldOptionsState, FieldOptionsOptions, } from "./hooks.js";
 export { useComments, useCommentCounts } from "./comments.js";
 export type { AppComment, AppCommentFile, CommentsState, UseCommentsArgs, CommentCountsState, UseCommentCountsArgs, } from "./comments.js";
 export { useViewer } from "./viewer.js";

package/dist/src/index.js

@@ -15,7 +15,7 @@
  * not raw HTML/CSS. See `docs/apps.md` → "Styling & components".
  */
 export { mount } from "./mount.js";
-export { useWorkflow, useQuery, useInfiniteQuery, usePaginatedQuery, useFieldOptions, useFileUpload, useAttachments, useMembers, useAgentRun, useAgentRuns, useAiContext, buildChoiceOutput, } from "./hooks.js";
+export { useWorkflow, useQuery, useInfiniteQuery, usePaginatedQuery, useCount, useFieldOptions, useFileUpload, useAttachments, useMembers, useAgentRun, useAgentRuns, useAiContext, buildChoiceOutput, } from "./hooks.js";
 export { useComments, useCommentCounts } from "./comments.js";
 export { useViewer } from "./viewer.js";
 export { useConfig } from "./config.js";

package/docs/data_fetching.md

@@ -23,9 +23,54 @@ per the manifest. Each hook is a thin wrapper over the host RPC bridge with an S
 | `useQuery(alias, params?, opts?)` | one fetch, `rows` | a detail read, a dashboard block, a combobox's top-N — anything that is not a long list |
 | `useInfiniteQuery(alias, params?, opts?)` | accumulated `rows` + `loadMore` | infinite scroll / "load more" feeds |
 | `usePaginatedQuery(alias, params?, opts?)` | one page of `rows` + `total` | numbered, jumpable pages behind `@lotics/ui` `Pagination` |
+| `useCount(alias, params?, opts?)` | `total` only, no rows | a facet chip, a queue badge, an "N awaiting approval" tile — the size of a set you are not listing |
 
 One job each — don't overload one. `useQuery` with a big `pageSize` is not pagination; a
-`usePaginatedQuery` whose pages you concatenate yourself is `useInfiniteQuery` done by hand.
+`usePaginatedQuery` whose pages you concatenate yourself is `useInfiniteQuery` done by hand;
+and a `usePaginatedQuery` with `pageSize: 1` whose rows you drop is `useCount` buying a page
+nobody renders — **two** requests for one integer, since that hook fetches a page AND a count.
+
+`useCount` takes no `sort` and no `pageSize`: a count is a single-row COUNT over the filtered
+set, so ordering and paginating it are meaningless. They are absent from `CountOptions` rather
+than ignored — an option a hook silently drops is worse than one that will not compile.
+
+### One count per filtered set
+
+`useCount` counts under the SAME cache key `usePaginatedQuery` counts under —
+`(alias, params, filter)`. A table and a badge over the same set therefore issue **one** count
+between them, and page clicks and re-sorts reuse it (a count is page- and sort-independent):
+
+```tsx
+// One count total, not two — same alias, same params, same filter.
+const { rows, total, setPage } = usePaginatedQuery("orders", { q }, { pageSize: 25 });
+const { total: sameNumber } = useCount("orders", { q });
+```
+
+**A count is not free, and it is not fast.** It re-executes the whole `from` tree and scans the
+entire filtered set, where a page stops at `pageSize` — measured on one register, the COUNT ran
+*longer* than the page beside it. That is why it is a request of its own rather than something
+folded into the page response: rows paint the moment they arrive, and the number fills in
+behind them. Fold the two together and every table waits for its own count before showing a
+single row.
+
+Do not reach for it N times over one source. Each declared query re-executes its whole `from`
+tree, so four facets mounted as four `useCount`s are four full scans landing in one burst
+against the server's concurrency gate. When the counts differ only by a bucket the rows can be
+grouped on, **one `group` query returns them all in a single scan** and folds client-side
+([queries](./queries.md) §10), and its figure can be handed to `usePaginatedQuery`'s `total` so
+the list stops counting too. `useCount` is for the count with no sibling to group with.
+
+### Why not hand-roll it
+
+A direct `rpc("query", { …, count: true })` is one request and looks equivalent. It is not: it
+leaves the cache, so it does not dedupe with the page beside it, does not revalidate on focus,
+and never hears the host's post-write refetch. The number then goes stale over a set that has
+moved while everything around it updates — and a count that is quietly wrong costs more than a
+count that costs a request.
+
+And never count client-side from `useQuery(...).rows.length`: rows are capped at 10,000 per
+response and truncation is **silent**, so the number is right in development and wrong in
+production with no error ([queries](./queries.md) §10).
 
 ## Shared option surface
 

package/docs/queries.md

@@ -376,6 +376,12 @@ A `QuerySource` appears in `project.columns[].source`, `unpivot.passthrough[].so
 | `{ "link": { "source": "customer", "field": "Company name" } }` | A field on the **first** linked record of a `select_record_link` field (correlated per-row subquery) | the target field's type |
 | `{ "expression": "…" }` | jexpr escape hatch (below) | declared |
 
+**Every variant in that table except the bare field key and `record_id` needs an explicit
+`"type"` beside `"source"`, whatever the Output type column says it yields.** That column
+describes the VALUE; the compiler infers a type only for a passthrough and for identity, and
+rejects the column otherwise — so `{ "isNotEmpty": … }` is a boolean you still have to declare
+as one. `record_id` is the sole exception, and declaring anything but `text` on it is rejected.
+
 ### Link extraction — the fine print
 
 `{ link: { source, field } }` requires a direct `from_table` parent, and `source` must be a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/app-sdk",
-  "version": "0.82.3",
+  "version": "0.83.1",
   "description": "Runtime SDK for Lotics custom-code apps \u2014 typed hooks, postMessage bridge, mount entry point",
   "type": "module",
   "exports": {