@lotics/app-sdk 0.48.0 → 0.49.1

package/dist/src/hooks.js

@@ -101,21 +101,28 @@ export function useInfiniteQuery(alias, params, opts) {
     const sort = opts?.sort && opts.sort.length > 0 ? opts.sort : undefined;
     const filter = opts?.filter;
     const mockRows = getMockRows(alias);
+    // Keyset (seek) pagination: each page seeks past the previous page's
+    // `next_cursor` instead of an increasing OFFSET, so deep scrolls stay O(page)
+    // and never skip/duplicate a row as the set shifts. The cursor is opaque; the
+    // server keysets a sortable key (or the id default) and falls back to offset
+    // transparently. `loadMore`/`rows` are unchanged — the cursor is internal.
     const getKey = (index, prev) => {
         if (mockRows || !enabled)
             return null;
-        // Stop once a short page returns.
-        if (index > 0 && (prev == null || prev.rows.length < pageSize))
+        // Stop once a page reports no next cursor (the end).
+        if (index > 0 && (prev == null || prev.next_cursor == null))
             return null;
-        return ["app-query-infinite", alias, params ?? {}, pageSize, sort ?? null, filter ?? null, index];
+        const cursor = index === 0 ? null : (prev?.next_cursor ?? null);
+        return ["app-query-infinite", alias, params ?? {}, pageSize, sort ?? null, filter ?? null, cursor];
     };
     const swr = useSWRInfinite(getKey, (key) => {
-        const index = Number(key[6]);
+        const cursor = key[6];
         return rpc("query", {
             alias,
             params: params ?? {},
             limit: pageSize,
-            offset: index * pageSize,
+            keyset: true,
+            cursor: cursor ?? undefined,
             sort,
             filter,
         });
@@ -126,7 +133,8 @@ export function useInfiniteQuery(alias, params, opts) {
     const pages = (swr.data ?? []).filter((p) => p != null);
     const rows = mockRows ?? pages.flatMap((p) => p.rows ?? []);
     const lastPage = pages.length > 0 ? pages[pages.length - 1] : undefined;
-    const hasMore = lastPage != null && (lastPage.rows?.length ?? 0) === pageSize;
+    // A non-null next_cursor means another page exists; null/absent = the end.
+    const hasMore = lastPage != null && lastPage.next_cursor != null;
     const loadingMore = swr.isValidating && swr.size > pages.length;
     const refetch = useCallback(() => {
         void swr.mutate();

package/docs/queries.md

@@ -246,17 +246,21 @@ addressing is dropped.
 { "kind": "window", "from": { … },
   "partition_by": ["customer_id"],
   "order_by": [{ "field_key": "created", "order": "asc" }],
-  "frame": { "type": "rows", "following": 0 },     // optional
+  "frame": { "type": "rows", "following": 0 },     // optional; frames `aggregates` only
   "aggregates": [{ "output": "running_total", "type": "number",
-                   "operation": "sum", "input_column": "total" }] }
+                   "operation": "sum", "input_column": "total" }],
+  "functions":  [{ "output": "rnk", "fn": "rank" }] }   // ranking / navigation (§8)
 ```
 
-Appends aggregate columns to every input row (input columns pass through). Only the
-**OVER-legal** operation subset is accepted (§8). Frame is `rows`-type only:
-`preceding`/`following` omitted = unbounded, `0` = current row, `N` = N rows. Omitting `frame`
-uses the SQL default — with `order_by` that is a *running* frame (partition start → current
-row, ties included); without `order_by`, the whole partition. Output names must not collide
-with input columns.
+Appends columns to every input row (input columns pass through) from two independent lists:
+**`aggregates`** (frame aggregates — the OVER-legal operation subset, §8) and **`functions`**
+(ranking / navigation: `row_number`, `rank`, `dense_rank`, `percent_rank`, `cume_dist`,
+`ntile`, `lag`, `lead` — §8). At least one list must be non-empty; both may be present. `frame`
+is `rows`-type only (`preceding`/`following` omitted = unbounded, `0` = current row, `N` = N
+rows) and applies **only** to `aggregates`; omitting it uses the SQL default (with `order_by`, a
+*running* frame partition start → current row, ties included; without, the whole partition).
+`functions` are never framed and need a non-empty `order_by`. Output names must not collide with
+input columns.
 
 ### `sort` / `limit` — order and page a derived set
 
@@ -633,17 +637,30 @@ Sort by the bucket column for a time series; filter it with date operators for a
 window. **Always bucket server-side** — shipping raw rows to bucket in JS burns the row cap and
 the timeout for nothing.
 
-### Window functions — the OVER-legal subset
+A `window` node carries two independent column lists — **`aggregates`** (frame aggregates) and
+**`functions`** (ranking / navigation). At least one must be non-empty; a node may carry both.
 
-Only operations that compile to a single legal SQL window call are accepted in `window`:
-**`count`, `sum`, `avg`, `min`, `max`, `earliest`, `latest`, `filled`, `checked`,
-`unchecked`.** The rest cannot take an OVER clause (`median` is an ordered-set aggregate;
-`unique`/`percent_unique` need DISTINCT; `range`/`empty`/`date_range`/`percent_*` compose
-multiple calls) — rejected at deploy.
+**`aggregates` — the OVER-legal aggregate subset.** Only operations that compile to a single
+legal SQL window call are accepted: **`count`, `sum`, `avg`, `min`, `max`, `earliest`, `latest`,
+`filled`, `checked`, `unchecked`.** The rest cannot take an OVER clause (`median` is an
+ordered-set aggregate; `unique`/`percent_unique` need DISTINCT; `range`/`empty`/`date_range`/
+`percent_*` compose multiple calls) — rejected at deploy. The optional `frame` applies **only**
+to these; a `frame` on a window with no `aggregates` is rejected as dead config.
 
-**There are no ranking or navigation functions** — no `row_number`, `rank`, `dense_rank`,
-`lag`, `lead`, `first_value`. **Top-N per group** is emulated with a running count over a
-frame:
+**`functions` — ranking / navigation.** Each is `{ "output", "fn", … }` (its own arg shape, no
+`operation`/`type` — the output type is fixed or inherited). They never take a `frame` and
+**require a non-empty `order_by`** (ranking without an order is nondeterministic):
+
+| `fn` | args | output |
+| --- | --- | --- |
+| `row_number` | — | `number`, non-null. Total order 1..N within the partition; ties broken arbitrarily. |
+| `rank` | — | `number`, non-null. Ties share a rank; the next rank **skips** (1,2,2,4). |
+| `dense_rank` | — | `number`, non-null. Ties share a rank; the next rank does **not** skip (1,2,2,3). |
+| `percent_rank` / `cume_dist` | — | `number`, non-null. Relative position in [0, 1]. |
+| `ntile` | `buckets` (positive int) | `number`, non-null. The row's bucket (1..buckets) splitting the partition into equal groups. |
+| `lag` / `lead` | `input_column`, `offset?` (int ≥ 1, default 1), `default?` (literal) | the input column's type, **nullable**. The value `offset` rows before / after this one; at the partition edge, `default` if given else NULL. `default`'s type must match the input column (checked at deploy). |
+
+**Top-N per group** — rank within each partition, then filter on the derived rank column:
 
 ```jsonc
 { "kind": "filter",
@@ -651,14 +668,15 @@ frame:
     "from": { "kind": "from_table", "table_id": "tbl_orders" },
     "partition_by": ["customer_id"],
     "order_by": [{ "field_key": "total", "order": "desc" }],
-    "frame": { "type": "rows", "following": 0 },        // partition start → current row
-    "aggregates": [{ "output": "rank", "type": "number", "operation": "count" }] },
-  "predicate": { "node_type": "condition", "field_key": "rank",
+    "functions": [{ "output": "rnk", "fn": "rank" }] },
+  "predicate": { "node_type": "condition", "field_key": "rnk",
                  "operator": "less_than_or_equal_to", "value": 3 } }
 ```
 
-`count` over a `ROWS … CURRENT ROW` frame is a row position (`row_number`-like; ties are
-ordered arbitrarily unless the `order_by` is total — add a tiebreaker key for determinism).
+`rank` keeps ties (a 3-way tie for 3rd returns all three). For exactly N rows regardless of
+ties, use `row_number` (with a total `order_by` — add a tiebreaker key for determinism).
+**Delta vs the previous row/period** is `lag` (e.g. a project column `{ "expression": "input.total
+- input.prev_total" }` over a `lag` output).
 
 ### unpivot vs unnest
 
@@ -745,17 +763,26 @@ slice, and within it:
   layer** — `select`/`select_member`/`select_record_link` `has_any_of` / `has_all_of`, and
   `is_current_member`. These compile to containment the JSONB GIN index serves.
 - **Trigram-served:** `from_table.search` (§7).
-- **Partition scan (linear in table size):** everything else — text `contains`/`equals`,
-  number and date range predicates, negations (`has_none_of`, `is_none_of`, `not_*`),
-  emptiness, files predicates. Fine on thousands of rows; on very large tables these dominate
-  latency and are the usual timeout cause.
-
-**Filter shape drives latency.** Lead with a GIN-served membership filter or `search` where you
-can; let the scan-shaped predicates refine the already-narrowed set. Derived-layer filters run
-over the subquery result (no index), so **filter at the source layer whenever the field exists
-there** — the runtime filter is for caller-driven refinement, not for the main cut. (The engine
-pushes eligible filter-over-union predicates down automatically, but don't rely on that for
-other shapes.)
+- **B-tree-served (automatic for deployed queries):** text `equals`, number and date
+  comparisons (exact and range), and `sort` fields — for fields referenced in a **deployed
+  named query's template**. The platform provisions a partial expression index per referenced
+  field automatically: built online on `app deploy` and `app query set`, re-synced daily,
+  capped at 8 per table (fields past the cap fall back to the scan tier, with a server WARN).
+  A `{{params.…}}` value hole doesn't change this — the field key is static in the template,
+  so it still gets its index. Index-seek speed at any table size once provisioned.
+- **Partition scan (linear in table size):** everything else — text `contains`, negations
+  (`has_none_of`, `is_none_of`, `not_*`), emptiness, files predicates, and predicates/sorts on
+  fields that appear **only** in the runtime `filter`/`sort` options rather than the deployed
+  template. Fine on thousands of rows; on very large tables these dominate latency and are the
+  usual timeout cause.
+
+**Filter shape drives latency.** Equality/range/sort predicates in the deployed template are
+index-served; lead with those or a GIN-served membership filter / `search`, and let scan-shaped
+predicates refine the already-narrowed set. Derived-layer filters run over the subquery result
+(no index), so **filter at the source layer whenever the field exists there** — the runtime
+filter is for caller-driven refinement, not for the main cut (a runtime-only field gets no
+managed index). (The engine pushes eligible filter-over-union predicates down automatically,
+but don't rely on that for other shapes.)
 
 ### The authoring rules
 
@@ -885,9 +912,9 @@ Consolidated from the sections above — these describe present engine behavior:
 
 - **No pivot/crosstab node.** Row-values-to-columns happens client-side over grouped results
   (§8).
-- **No ranking or navigation window functions** (`row_number`, `rank`, `lag`, `lead`, …).
-  Top-N per group = the count-over-frame emulation (§8). Window ops are the 10-item OVER-legal
-  subset.
+- **No `first_value`/`last_value`/`nth_value` navigation** — the `functions` set is `row_number`,
+  `rank`, `dense_rank`, `percent_rank`, `cume_dist`, `ntile`, `lag`, `lead` (§8). Frame aggregates
+  remain the 10-item OVER-legal subset.
 - **Offset-only pagination.** Deep pages cost the full skipped prefix; pages can shift under
   concurrent writes (§9).
 - **No collation control.** Text ORDER BY uses the database default collation —

package/package.json

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