@jsenv/navi 0.30.23 → 0.30.25

package/docs/AI_INSTRUCTIONS.md

@@ -89,7 +89,11 @@ start when unsure which export solves a problem.
   (`{ run: true }` is the fallback), `action` versus `uiAction`, an action and a
   command on one press. Before running an action from a component.
 - `resource.md` — `resource()` and its relations (never an `op` discriminator),
-  what each read shows while its params move, `GET_RANGE` (its inclusive `end`,
+  a row pairing an entity with fields of its own (the entity under `.one()`,
+  never spread in), what a copy of a relation keeps, what a parent shows once
+  its `.one()` child is deleted (`onDelete: "cascade"` for a parent that is
+  nothing without it), what each read shows while
+  its params move, `GET_RANGE` (its inclusive `end`,
   the count for the screen around the list, a question following a search
   field), a search as the same `GET_MANY`, `withParams()` scopes and
   `dependencies`, `persist` (and `keepPageOnScreen` for the page on screen), a

package/docs/actions.md

@@ -554,8 +554,8 @@ const SUMMARY = createAction(fetchSummary, {
 });
 ```
 
-After a listed write, its instances that answered, or are still asking, ask
-again; `on` is read as a resource's is
+After a listed write, its instances that answered, are still asking, or failed
+ask again; `on` is read as a resource's is
 ([resource.md](./resource.md#dependencies-rerun-after-another-resource-writes)).
 
 What the server moves on its own — an email that may bounce, an account being

package/docs/list_refresh.md

@@ -236,6 +236,14 @@ changes what re-reads the slices and nothing else — `GET_MANY` still reruns af
 `POST`. `false` turns a key off. A `withParams()` scope or a relation reads its
 own `rerunOn` the same way, against the resource it is declared on.
 
+A write asks again every read that answered, is still out, or failed. A failed
+read has nothing else to bring it back: left out, one bad answer during a deploy
+would keep a count on its old value until the page reloads. The status does not
+matter, since a write can change what a `403` or a `404` answers, so a read that
+keeps failing costs one request and one error per write, and never a retry loop.
+Two reads stay out: an aborted or never-run one, which nobody is waiting for,
+and a head start that failed, which the screen arriving asks for itself.
+
 Adding `PUT`/`PATCH` to `GET_MANY` is the usual over-correction: it costs a
 request and a `loading` pass to obtain something the response already contained.
 When a `PATCH` "doesn't show", the fix is almost always server-side — return the

package/docs/resource.md

@@ -42,6 +42,8 @@ Actions are read in components through the action system (`useAsyncData`,
 - [Callback return contracts](#callback-return-contracts)
 - [When the backend answers a sub-route with the whole parent](#when-the-backend-answers-a-sub-route-with-the-whole-parent)
 - [Relations and autorerun](#relations-and-autorerun)
+- [Reading a relation](#reading-a-relation)
+- [When the child is deleted](#when-the-child-is-deleted)
 - [What a read shows while its params move](#what-a-read-shows-while-its-params-move)
 - [`withParams()`: a scope with reruns of its own](#withparams-a-scope-with-reruns-of-its-own)
   - [`dependencies`: rerun after another resource writes](#dependencies-rerun-after-another-resource-writes)
@@ -434,7 +436,7 @@ A row counts as written only when something in it changed:
 - **A relation** changes its row when the row points at other children; the
   children themselves are followed through the relation — `game.place.label`
   read in a render re-renders it when the place is written, and the game row
-  stays the one it was.
+  stays the one it was ([what a copy of it keeps](#reading-a-relation)).
 - **A value written with `store.upsert()`** is compared by reference: a new
   object is a change, whatever it holds.
 
@@ -461,18 +463,45 @@ second coat: a verb on one relation carrying an id from a **different** relation
 people — is two relations spelled as one, and the one the gesture is about
 (game × group) ends up with no rows and nothing for its row on screen to read.
 
-| Situation                                                                                                     | Use                                                                                                                                 |
-| ------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
-| The child is a first-class entity with its own store, shared across parents (a user referenced by many games) | `.one()` / `.many()`                                                                                                                |
-| The child only exists inside its owner, with no identity outside it (a game's candidates, a table's columns)  | `.scopedOne()` / `.scopedMany()`                                                                                                    |
-| The relation itself carries fields (`candidate_since`, `seen_at`, `slot`)                                     | `.scopedMany()` — those fields belong to the pair; putting them in a shared child store corrupts that entity for every other reader |
-| The backend answers every sub-route with the whole refreshed parent                                           | still model the relation; absorb the response with a plural callback (see below)                                                    |
-| A genuine partial update of the parent itself (cancel a game)                                                 | plain `PATCH` on the parent                                                                                                         |
-| Several writes on the item itself, none of them a sub-object (cancel, archive, mark as seen)                  | one named in [`writes`](#several-writes-on-one-item-writes) each                                                                    |
+| Situation                                                                                                                                | Use                                                                                                                                 |
+| ---------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| The child is a first-class entity with its own store, shared across parents (a user referenced by many games)                            | `.one()` / `.many()`                                                                                                                |
+| The child only exists inside its owner, with no identity outside it (a game's candidates, a table's columns)                             | `.scopedOne()` / `.scopedMany()`                                                                                                    |
+| The relation itself carries fields (`candidate_since`, `seen_at`, `slot`)                                                                | `.scopedMany()` — those fields belong to the pair; putting them in a shared child store corrupts that entity for every other reader |
+| A list whose items pair another resource's entity with fields of their own (my contacts, a club's members, a tournament's registrations) | the pair is the row, under a key of its own, and the entity goes under `.one()` on it; never spread into the row (see below)        |
+| The backend answers every sub-route with the whole refreshed parent                                                                      | still model the relation; absorb the response with a plural callback (see below)                                                    |
+| A genuine partial update of the parent itself (cancel a game)                                                                            | plain `PATCH` on the parent                                                                                                         |
+| Several writes on the item itself, none of them a sub-object (cancel, archive, mark as seen)                                             | one named in [`writes`](#several-writes-on-one-item-writes) each                                                                    |
 
 Singular vs plural is about the relation, not the verb: `.one`/`.scopedOne` for a
 single sub-object, `.many`/`.scopedMany` for a collection.
 
+**A row pairing an entity with fields of its own holds the entity as a
+relation.** One of my contacts is what links me to someone (games together,
+favourite) and that someone, the same user their profile shows. The row is the
+pair, keyed by it: a resource of its own, or a `.scopedMany()` of an owner the
+store holds (a club's members). The person goes under `.one()`:
+
+```js
+// GET /me/contacts → [{ key: "user:12", contact: { … }, user: { id: 12, … } }, …]
+const CONTACT = resource("contact", { idKey: "key", GET_MANY });
+CONTACT.one("user", USER, { onDelete: "cascade" });
+```
+
+The row is nothing without the person, so it leaves when they are deleted
+(`onDelete: "cascade"`, see [When the child is deleted](#when-the-child-is-deleted)).
+
+Spread into the row (`{ ...user, key, contact }`), the person is a second copy
+in another store. Their profile read again, a write on them, a search that finds
+them: none of these reach the row, and the list shows the old person until it is
+read again. A [`dependency`](#dependencies-rerun-after-another-resource-writes)
+rereading the list after every write that might change the person is the same
+copy, refreshed by hand, and it misses the writes nobody listed. A backend
+answering the row flat is reshaped in the callback
+(`({ key, contact, ...user }) => ({ key, contact, user })`). It is the mirror of
+the row above it: the pair's fields written into the entity's store corrupt it
+for every reader, the entity's fields written into the pair's row go stale.
+
 **A write whose effect the response does not carry is a modelling bug, not a
 case for the client to remember.** The row on screen claiming "this happened"
 reads the store, which holds only what responses carried; whatever the screen
@@ -649,7 +678,9 @@ Relationship mutations do **not** invalidate their parent by default. The rules:
 - `.scopedOne` mutations rerun nothing, ever — the result is the new value,
   and whoever reads the property is drawn again with it.
 - `.one` / `.many` children live in an independent store; mutating them never
-  reruns the parent. A `.many()` write changes the parent's array only through
+  reruns the parent. Deleting a `.one()` child removes its parents only when
+  the relation says so ([When the child is deleted](#when-the-child-is-deleted)).
+  A `.many()` write changes the parent's array only through
   the answers naming it (`[parentId, …]`, see
   [Callback return contracts](#callback-return-contracts)); otherwise declare
   it with [`dependencies`](#dependencies-rerun-after-another-resource-writes)
@@ -667,6 +698,84 @@ is a resource of its own, refreshed only by these rules. When a parent field
 depends on a child mutation, say so with `dependencies` rather than relying on a
 rerun that will not happen.
 
+## Reading a relation
+
+`contact.user` is read through the relation each time: in a render, it is the
+child as the store holds it, and the render that read it is drawn again when the
+child is written. The row, and the list holding it, stay the objects they were
+when only a child changes
+([a row counts as written only when something in it changed](#searching-the-same-collection)).
+So anything taken out of a row is a snapshot of that moment, and stays as it
+was:
+
+- `{ ...contact }`, which holds the child the spread found;
+- a child kept in a variable;
+- a value derived in `useMemo(…, [contacts])`: the list does not move when a
+  child does, so the derivation never runs again.
+
+Read the relation where it is drawn. A derivation that has to flatten the rows
+(`{ ...contact.user, contact: contact.contact }`) reads the children at render
+and is keyed on them: a `.one()` child is the same object until it is written,
+and a new one after.
+
+## When the child is deleted
+
+A `.one()` child leaves its store when it is deleted: its `DELETE`, its
+`DELETE_MANY`, or a write named in `writes` with verb `DELETE` (a profile merged
+into another account). Whether its parents leave with it is declared on the
+relation. Declared wrong, the screen draws dead rows: a parent with nothing in
+it, until the parent is read again. A `.many()` needs nothing: a deleted child
+leaves every array holding it. Decide it for every `.one()` by asking what the
+parent is without its child:
+
+| The parent without its child                                                                       | Declare               | Once the child is deleted                                                                  |
+| -------------------------------------------------------------------------------------------------- | --------------------- | ------------------------------------------------------------------------------------------ |
+| Still something: a game whose organizer deleted their account, a message whose author left         | nothing               | the parent stays, and its property reads an empty object until the parent is read again    |
+| Nothing: a row of my contacts (the person), a favourite (the place), a notification about one game | `onDelete: "cascade"` | the parent leaves its store in the same write, and with it every list and range holding it |
+
+The server answers the same question with its foreign key: `ON DELETE CASCADE`
+on the parent's table is `onDelete: "cascade"` here, and `SET NULL` (or a row
+kept pointing at nothing) is the default.
+
+**`onDelete: "cascade"`.** The parent leaves as on a `DELETE` of its own,
+without the action:
+
+- a `GET_MANY` or a `GET_RANGE` holding it stops drawing it, and a `GET` of that
+  row has nothing left to show;
+- nothing listening to the parent's own writes hears it (its `rerunOn`, a
+  `dependencies` naming it): the parent wrote nothing;
+- the parent leaving is a deletion too: a resource pointing at it through a
+  cascading `.one()` of its own loses its rows in turn;
+- a read of the parent that answers the row again brings it back: the server
+  has the last word.
+
+Keep a [`dependencies`](#dependencies-rerun-after-another-resource-writes)
+entry on the child's delete when that delete changes other parents too (a
+merge moves my links onto the account it merged into): the cascade takes away
+at once what is gone, the reread brings what moved. The relation's own `DELETE`
+is not a deletion of the child. It unlinks: the property becomes `null` and the
+parent stays. On a `.one()` declared on a scoped child, `onDelete` throws: a
+scoped item leaves through its owner's callbacks, so the owner is read again
+after the child's delete (`dependencies`), and the item reads an empty object
+until that read answers.
+
+**Left out: the empty object.** A parent outliving its child reads its property
+as an object with no fields, whose `valueOf()` is `null`. A relation that is
+`null` reads the same. It is an object on purpose: `game.organizer.name` reads
+`undefined` rather than throwing, and a binding handed `game.organizer` follows
+the relation, a child arriving later included. But it is **truthy**, and that is
+where screens draw dead things:
+
+- `game.organizer ? <Avatar user={game.organizer} /> : null` draws an avatar of
+  nobody;
+- `{ ...contact.user, key }` spreads into a row holding a key and nothing else,
+  which a name component fills with its fallback ("Anonymous").
+
+Test the child by a field it always has, its id:
+`game.organizer.id ? … : …`. A list that must never draw a parent without its
+child needs the cascade, not a filter in the screen: the filter guesses what the
+store knows, and every other list reading the relation needs the same filter.
+
 ## What a read shows while its params move
 
 A binding following a signal — a route action, `bindParams(signal)` — moves to
@@ -708,7 +817,7 @@ another collection, drawn from its first item
 
 A resource reruns its own reads after its own writes (`rerunOn`, see
 [list_refresh.md](./list_refresh.md#rerunon-verb-by-verb)), and it does so for
-every read of the resource: a `POST` reruns every `GET_MANY` that completed,
+every read of the resource: a `POST` reruns every `GET_MANY` already asked,
 whatever params each one was bound to. Right for one collection, wrong for a
 resource read under several fixed questions at once — the admins and the guests
 of one `USER`, each list on its own screen. A guest created should not send the
@@ -767,8 +876,9 @@ const ROLE_WITH_OWNERS = ROLE.withParams(
 ```
 
 Any write on a listed resource (`POST`, `PUT`, `PATCH`, `DELETE`) reruns the
-completed `GET` and `GET_MANY` of the resource that declared it, and invalidates
-its `GET_RANGE` readers: its own `rerunOn` is about its own writes. A
+`GET` and `GET_MANY` of the resource that declared it, those that failed included
+([which ones](./list_refresh.md#rerunon-verb-by-verb)), and invalidates its
+`GET_RANGE` readers: its own `rerunOn` is about its own writes. A
 dependency is a facade: `DATABASE` and `DATABASE.withParams(…)` are two of them,
 and only writes on the one listed count. Nothing goes the other way, and nothing
 is inferred — a relation that really is a sub-route of the parent is modelled

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jsenv/navi",
-  "version": "0.30.23",
+  "version": "0.30.25",
   "type": "module",
   "description": "Library of components including navigation to create frontend applications",
   "repository": {