@lotics/app-sdk 0.58.5 → 0.59.0

package/docs/queries.md

@@ -583,7 +583,7 @@ the table.
 
 ## 8. Shaping: group, buckets, window, fan-out
 
-### The 20 aggregate operations
+### The 21 aggregate operations
 
 `group` and `window` share one operation vocabulary. `count` is `COUNT(*)` (no `input_column`);
 everything else requires an `input_column` whose type must be compatible — checked at deploy:
@@ -599,10 +599,38 @@ everything else requires an `input_column` whose type must be compatible — che
 | `percent_filled`, `percent_empty` | any except boolean | number | **fraction 0–1**, not 0–100; NULL for an empty group |
 | `unique`, `percent_unique` | text, number, date/datetime, select, select_member, select_record_link, files, json¹ | number | distinct **present** values; array cells compare as whole arrays |
 | `checked`, `unchecked`, `percent_checked`, `percent_unchecked` | boolean | number | `unchecked` counts false **or** empty |
+| `string_agg` | text, select | **text** | the distinct present values joined — the only operation returning values rather than a count. `group` only |
 
 ¹ opaque `json` columns support only the presence-counting six (`empty`/`filled`/`unique` and
 their `percent_*` forms).
 
+**`string_agg` — a summary column, not a dataset.** Every other operation counts or reduces to a
+number; this one joins the values, so a child set answers "which ones?" in the parent row (the
+sizes on a shipment, the tags on a ticket) without a second query.
+
+```jsonc
+{ "output": "sizes", "type": "text", "operation": "string_agg", "input_column": "size",
+  "distinct": true, "separator": ", ", "max_values": 20 }
+```
+
+- **`type` must be `text`** — declaring anything else is rejected at deploy.
+- **`distinct`** defaults to **true**: three containers sized 40HC/40HC/20DC give `20DC, 40HC`.
+  Pass `false` to keep every occurrence. Values are always sorted, so the column doesn't
+  reshuffle between reads.
+- **`max_values`** (default 20, max 100) caps the emitted values so an unbounded child set can't
+  produce a giant cell. It is a silent cap — pair it with a `unique` aggregate over the same
+  column to render an honest `+N more`.
+- **`separator`** defaults to `", "` (max 8 chars).
+- Empty values are dropped by the same emptiness contract below, so a partly-blank column
+  doesn't emit empty slots. A group with nothing present yields NULL.
+- **`group` only** — it is not in the OVER-legal set, because deduplication and window frames
+  are mutually exclusive in SQL. Setting `distinct` / `separator` / `max_values` on any other
+  operation is rejected rather than ignored.
+
+It is deliberately **not** a rollup field type: a rollup persists its value into record data and
+rewrites it on every child change, and an unbounded concatenation does not belong in a stored
+cell. Query-time only.
+
 **The one emptiness contract.** `filled`/`empty`/`unique`/`percent_*` use the same definition
 of "present" as the filter layer's `is_empty` and the `isEmpty` source: array-valued cells are
 empty at NULL / JSON `null` / `[]`; text at NULL or blank (whitespace-only); opaque json at
@@ -643,8 +671,8 @@ A `window` node carries two independent column lists — **`aggregates`** (frame
 **`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**
+ordered-set aggregate; `unique`/`percent_unique`/`string_agg` 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.
 
 **`functions` — ranking / navigation.** Each is `{ "output", "fn", … }` (its own arg shape, no

package/package.json

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