@lotics/app-sdk 0.87.1 → 0.87.4

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/mutations.md

@@ -321,7 +321,8 @@ await update_records({
 
 `set` still writes every key it carries — `null` in `set` **clears** the field; `null`/absent in
 `set_skip_null` **skips** it. The full write surface (`set`, `set_skip_null`, the surgical
-`add_to`/`remove_from`/`replace` ops, `field_edits`, and the exact value shape per field type)
+`add_to`/`remove_from`/`replace` ops, `increment`, `field_edits`, and the exact value shape per
+field type)
 is [workflows](./workflows.md#writing-records).
 
 ## Refetch after a mutation
@@ -446,7 +447,9 @@ Why a full-form snapshot save is a bug, not a style choice — three independent
    append is the system's rather than a person's — an upload settling, a workflow attaching a
    generated document — name the ITEMS with `add_to` / `remove_from`
    ([workflows](./workflows.md#writing-records)) and the write path resolves them against the
-   record as it stands.
+   record as it stands. A running total is the scalar form of the same defect: two writers both
+   read 100, both subtract 10, both write 90, and one sale is gone with no error anywhere. Name
+   the DELTA with `increment`.
 
 ```tsx
 // load: snapshot the editable fields from the row

package/docs/workflows.md

@@ -482,31 +482,38 @@ differ from `<` / `>` (code-unit order) and from the database's collation.
 
 ## Writing records
 
-`update_records` carries four composable surfaces. A field may appear in **at most one** of them.
+`update_records` carries five composable surfaces. A field may appear in **at most one** of them.
 
 | Surface | Shape | Effect |
 |---|---|---|
 | `set` | `{ fld_x: value }` | write the whole value. `null` **clears** the field |
 | `set_skip_null` | `{ fld_x: value }` | same shape, but `null`/`undefined` entries are **dropped** — absent means "leave unchanged" |
 | `add_to` / `remove_from` / `replace` | `{ fld_x: [items] }` | surgical edits on multi-value fields (files, multi select, multi member, record links) |
-| `field_edits` | `[{ field, op, value }]` | the same surgical ops with the field named by a **string expression** — the only way to target a field chosen at run time |
-
-`add_to` / `remove_from` are RELATIVE: the server resolves them against the record as it stands
-when the write lands, inside the lock it already takes. Two runs appending to one field at the
-same time therefore each keep their item — which reading the field and writing the whole array
-back through `set` does not, since both fold onto the array they read and the later write drops
-the earlier, both reporting success. Parallel runs are ordinary (a trigger firing twice, an agent
-emitting two calls in one step), so reach for the ops rather than a read-modify-write whenever
-the workflow is ADDING to a field rather than stating it.
+| `increment` | `{ fld_x: delta }` | move a **number** field by a signed amount. Negative decrements; there is no separate decrement op |
+| `field_edits` | `[{ field, op, value }]` | the multi-value ops with the field named by a **string expression** — the only way to target a field chosen at run time. `increment` has no value-form: its payload is a scalar, not an item list |
+
+`add_to`, `remove_from` and `increment` are RELATIVE: the server resolves them against the record
+as it stands when the write lands, inside the lock it already takes. Two runs changing one field at
+the same time therefore each keep their effect — which reading the field and writing the result back
+through `set` does not, since both fold onto the value they read and the later write drops the
+earlier, both reporting success. On a stock count that is a sale that vanishes. Parallel runs are
+ordinary (a trigger firing twice, an agent emitting two calls in one step), so reach for the ops
+rather than a read-modify-write whenever the workflow is CHANGING a field by an amount rather than
+stating its value.
+
+`increment` counts an empty or unset field as 0, so a first decrement leaves a negative — oversold,
+and visibly so. It is rejected on formula, rollup, lookup and autonumber fields: those come from
+their own definition, so change what they aggregate instead.
 
 Inside `set` and `create_records.records`: `null` clears (persisted), `undefined` or an omitted
 key preserves. So passing a possibly-null read straight through is safe. Use
 `coalesce(x, fallback)` only when you want a real fallback, never to "strip" null.
 
 `set_skip_null` is what turns a bag of optional workflow inputs into a diff-write without a guard
-per field; naming the same field in both `set` and `set_skip_null` is an error, and an
-all-dropped `set_skip_null` with no other surface is a no-op (no records touched, no
-`before_update` hooks). Why diffs and not snapshots, plus locked records and the
+per field; naming the same field in both `set` and `set_skip_null` is an error. A call whose
+surfaces all resolve to nothing — an all-dropped `set_skip_null`, an op object with no entries —
+is a no-op: no records touched, no `before_update` hooks. So a conditionally-built op object needs
+no guard around the call. Why diffs and not snapshots, plus locked records and the
 `request_locked_record_change` path: [mutations](./mutations.md#diff-before-update--send-only-what-changed).
 
 **A `null` optional input is a CLEAR, and `set_skip_null` drops it.** The caller has three states
@@ -602,6 +609,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.1",
+  "version": "0.87.4",
   "description": "Runtime SDK for Lotics custom-code apps \u2014 typed hooks, postMessage bridge, mount entry point",
   "type": "module",
   "exports": {