@lotics/app-sdk 0.87.0 → 0.87.3

package/docs/data_fetching.md

@@ -153,6 +153,23 @@ server validates system conditions by `type` and never reads `field_key` on them
   number, while `error !== null`. Note a key CHANGE resets this: a new `params`/`filter`/`sort`
   is a fresh key with no prior rows, so the "last successful rows stay rendered" behaviour above
   does not save you.
+- **Never state an ABSENCE from `rows` without gating on `loading`.** The sibling of the rule
+  above, and it bites earlier: while the first request is in flight `rows` is `[]`, so
+  `rows.find(…)` returns nothing and any code shaped `if (!found) → "there is no X"` prints a
+  confident denial of something that is merely not here yet. It corrects itself when the data
+  lands, which is exactly what makes it ship: the author sees the settled screen, and only a
+  reader opening the surface cold sees the half-second where every requirement reads as missing.
+  A record drawer did this to five document rows at once — each rendering a red "missing" badge
+  and a blocking callout — so the loudest thing on the screen was, briefly, entirely false.
+  Gate the derivation, not the display: compute nothing while `loading`, and reserve the space with
+  a `Skeleton` so the layout does not jump when the answer arrives.
+
+  Watch for the second source of a legitimate empty: `enabled: false` never sends a request, so
+  `rows` is `[]` and `loading` is `false` **forever**. A detail query gated on a parent selection
+  (`{ enabled: vehicleId != null }`) therefore satisfies "not loading, no rows" while the real
+  fact is that nothing was asked. Read the gate itself — `loading || vehicleId == null` — and say
+  what is actually missing, which is the parent, not the children.
+
 - **`refetch()`** re-runs the query. A successful `useWorkflow` call already re-reads the mounted
   queries on its own (see [./mutations.md](./mutations.md)), so reach for this only where a write
   cannot have told you: a poll, a value that changes without anything on this screen writing, or a

package/docs/workflows.md

@@ -73,8 +73,8 @@ compile-time "cannot find name", not a runtime `undefined`.
 | `record` | button + table-lifecycle workflows | the record the trigger fired on (merged data on update) |
 | `prev_record` | table `*_update` / `*_delete` | the prior record state — same shape as `record`, link descent included |
 | `changes` | table `*_update` | per-field diff — a *partial* map, so read it `changes["fld_x"]?.next_value` / `?.prev_value` |
-| `index` | inside a `for-of` body | the current 0-based iteration index |
-| `<bind_name>` | inside a `for-of` body | the current item |
+| `index` | inside a `for-of` body | the current 0-based iteration index — always the **innermost** loop's. To use an outer loop's index in a nested body, bind it in the outer one (`const outerIdx = index;`) and read that |
+| `<bind_name>` | inside a `for-of` body | the current item. Each loop keeps its own, so a nested body reads the outer loop's item by its own bind name |
 | `<step_id>` | after the step | that step's output (`rows.records`, `approval.status`, …) |
 | `<let_name>` | its block | a mutable `let` binding |
 | `<param>` | inside a helper callback | that lambda's parameter |
@@ -602,6 +602,84 @@ if (!current_member_in_any_group(["grp_managers"])) {
 
 Full model, including what a public app must never expose: [security](./security.md).
 
+## Every `await` is a round trip
+
+A body runs **strictly sequentially**. There is no `Promise.all`, and independent reads do not
+overlap — three `get_record` calls that need nothing from each other still cost three trips, in
+order. So the thing to count when a workflow feels slow is not how much data moves but **how many
+tool calls it makes**, and the two cheapest wins are always the same: don't fetch what you already
+have, and don't write one row at a time.
+
+**A write costs more than a read.** A create or update drags its computed-field cascades, rollups
+and `after_*` hooks behind it before the call returns, so trimming reads is worth less than
+trimming writes. Reach for the write-side reductions first.
+
+### Batch every write — and build the array INLINE
+
+`create_records` takes an ARRAY. N rows written one call at a time is N round trips plus N cascade
+passes; the same N rows in one call is one of each.
+
+The catch is where you build that array, and it is not obvious. **Write the literal inside the
+call**, so it is typed by the `records` parameter:
+
+```js
+// ONE trip. The array literal is contextually typed by `records`, so "opt_bVPEMB"
+// stays the literal the table's write type wants.
+await create_records({
+  records: concat(
+    coRaVao ? [{ fld_khoan: "opt_bVPEMB", fld_tien: giaRaVao, fld_chuyen: [i.chuyen_id] }] : [],
+    coVeSinh ? [{ fld_khoan: "opt_nx0KAL", fld_tien: giaVeSinh, fld_chuyen: [i.chuyen_id] }] : [],
+  ),
+  table_id: "tbl_…",
+});
+```
+
+Accumulating into a variable first does **not** work, and the two errors it produces point away
+from the fix:
+
+```js
+let rows = [];
+for (const g of gia.records) {
+  rows = concat(rows, [{ fld_khoan: "opt_bVPEMB", … }]);   // widens to `string`
+}
+await create_records({ records: rows, … });
+// TS2322: Type '{ fld_khoan: string; … }[]' is not assignable to 'readonly …RecordWrite[]'.
+//   Type 'string' is not assignable to '"opt_bVPEMB" | "opt_nx0KAL" | … | null'.
+```
+
+`concat` widens a select's option key to `string` the moment it leaves the literal, and the obvious
+repair — `let rows: SomeRecordWrite[] = []` — is rejected by the next pass, because the stored body
+is parsed as a JS subset and type syntax is not in it. The way through is not an annotation: it is
+to let the call site supply the type. Keep the loop for FINDING values and put the writing after it.
+
+### Don't buy the same row twice
+
+- **A record you already read is already in hand.** The authorization preamble usually reads the
+  triggering record; a later `get_record` on the same id is a second trip for a value sitting in a
+  variable.
+- **Don't read back what you just computed.** A total you derived from the rows you are writing is
+  cheaper to sum in the body than to re-read from a computed field afterwards.
+- **`create_records` returns `{ created, record_ids }` — ids only.** When you need a
+  server-generated value (an auto-number), read it back with `get_record` on the returned id, never
+  a filtered `query_records` that scans for the row you just made: the filtered form is both an
+  extra scan and wrong under concurrency, since a row created between your write and your read
+  matches the same filter.
+
+### Keep expensive steps off the path the caller waits on
+
+`generate_pdf_from_template` and `agent` are the two steps that dominate a body's wall clock. Ask
+whether the person pressing the button needs that artifact **at that instant**. A document that is
+printed later belongs in the workflow that prints it — moving it there also removes the reads that
+existed only to feed it, which is usually where the round trips were hiding.
+
+### Measuring, if you do
+
+`query_workflow_executions` records `started_at` / `completed_at` per run, which is the server's own
+duration with your network and CLI startup excluded. **Run-to-run variance is large** — the same
+body measured twice, minutes apart, can differ by a second — so compare medians of several runs,
+and interleave the two versions rather than measuring one after the other. A single before/after
+pair will happily show an improvement that is only drift.
+
 ## Traps
 
 The rules that are easy to get wrong because the failing code looks correct.

package/package.json

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