@jsenv/navi 0.30.24 → 0.30.26

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

@@ -229,6 +229,10 @@ delay to hide it:
 
 A "check now" wired to `run()` therefore checks nothing, silently.
 
+`run()`, `rerun()` and `prerun()` answer the way the callback does: a promise when it is asynchronous, even
+when `run()` joins an answer the instance already holds, so `ACTION.run().catch(…)`
+holds in every state; the data itself, synchronously, when it is synchronous.
+
 ### Aborting saves resources, it does not undo
 
 `abort()` cancels what can still be cancelled — a `fetch` wired to the

package/docs/dynamic_import.md

@@ -112,6 +112,24 @@ render.**
    };
    ```
 
+   The binding `actionRunEffect` returns holds the state's question: while the
+   state says no, it has nothing to ask, and a reader on it waits forever. That
+   is right when the state is the only thing that asks. When something else asks
+   too (a reader with `run: true` that does not follow that state, the code of a
+   section every profile with cups draws, asked ahead because mine has some),
+   the effect runs the action and the readers read the question that always
+   stands, `true` for a param-less action. Both are the same instance, so the
+   code is fetched once:
+
+   ```jsx
+   const PALMARES_CODE_ACTION = createAction(() =>
+     import("./palmares.jsx").then((m) => m.Palmares),
+   );
+   actionRunEffect(PALMARES_CODE_ACTION, () => myCupsSignal.value.length > 0);
+   const PALMARES_CODE = PALMARES_CODE_ACTION.bindParams(true);
+   // useAsyncData(PALMARES_CODE, { run: hasPalmares, loading: true })
+   ```
+
 3. **Nothing above the component asks** → `useAsyncData` with a function, the
    fallback: the component's own existence is the only thing that asks, so the
    request is its own, for the life of the instance.

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

package/package.json

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