@jsenv/navi 0.29.11 → 0.29.14

package/docs/resource.md

@@ -0,0 +1,267 @@
+# resource()
+
+`resource()` models REST state: a reactive store of items, one action per REST
+callback, and — this is the part most often missed — parent/child relations.
+
+```js
+import { resource } from "@jsenv/navi";
+
+const GAME = resource("game", {
+  GET: ({ id }) => fetchJson(`/games/${id}`),
+  GET_MANY: () => fetchJson(`/games`),
+  POST: (game) => fetchJson(`/games`, { method: "POST", body: game }),
+  PUT: ({ id, ...game }) =>
+    fetchJson(`/games/${id}`, { method: "PUT", body: game }),
+  PATCH: ({ id, ...props }) =>
+    fetchJson(`/games/${id}`, { method: "PATCH", body: props }),
+  DELETE: ({ id }) => fetchJson(`/games/${id}`, { method: "DELETE" }),
+});
+```
+
+Each callback returns the data to upsert into the store:
+
+| Callback                 | Returns                           |
+| ------------------------ | --------------------------------- |
+| GET / POST / PUT / PATCH | the full item object, `{ id, … }` |
+| DELETE                   | the id, or `{ id }`               |
+| GET_MANY / POST_MANY / … | an array of item objects          |
+
+Actions are read in components through the action system (`useAsyncData`,
+`<Button action>`, …) — see [actions.md](./actions.md).
+
+## Relations: pick one of the four methods
+
+A backend sub-route (`/games/:id/candidates`, `/games/:id/candidates/:userId/seen`)
+is a relation. Model it with a relationship method. Do **not** encode it as an
+`op`/`type` discriminator inside a single verb's callback:
+
+```js
+// ✗ the anti-pattern this page exists to prevent
+PATCH: ({ id, op, ...rest }) => {
+  if (op === "candidate") return fetchJson(`/games/${id}/candidates`, …);
+  if (op === "score") return fetchJson(`/games/${id}/score`, …);
+  …
+};
+```
+
+One verb dispatching on a string gives up everything the store does for you:
+per-operation action state (loading/error per button), per-relation autorerun,
+and a child collection that other components can 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                                                                                                         |
+
+Singular vs plural is about the relation, not the verb: `.one`/`.scopedOne` for a
+single sub-object, `.many`/`.scopedMany` for a collection.
+
+## Callback return contracts
+
+These are not guessable — each relationship method has its own shape.
+
+### `.one(propertyName, childResource, { GET, PUT, DELETE })`
+
+The callback returns the **parent** object with the child nested inside:
+
+```js
+const USER_SESSION = USER.one("session", SESSION, {
+  GET: async ({ id }) => {
+    const session = await fetchJson(`/users/${id}/session`);
+    return { id, session }; // { id, session: { id: 10, token: "abc" } }
+  },
+  DELETE: async ({ id }) => {
+    await fetchJson(`/users/${id}/session`, { method: "DELETE" });
+    return id; // property becomes null
+  },
+});
+```
+
+`session: null` in the returned parent means "no relation". A parent GET/POST
+that embeds the child inline works too — the property setter upserts it.
+
+### `.many(propertyName, childResource, restCallbacks)`
+
+GET_MANY returns the **parent** object with the array nested inside; DELETE
+returns the pair of ids:
+
+```js
+const USER_FRIENDS = USER.many("friends", USER, {
+  GET_MANY: async ({ id }) => {
+    const friends = await fetchJson(`/users/${id}/friends`);
+    return { id, friends }; // { id, friends: [{ id: 2 }, { id: 3 }] }
+  },
+  POST: async ({ id, friendId }) =>
+    fetchJson(`/users/${id}/friends`, { method: "POST", body: { friendId } }),
+  DELETE: async ({ id, friendId }) => {
+    await fetchJson(`/users/${id}/friends/${friendId}`, { method: "DELETE" });
+    return [id, friendId]; // [parentId, childId]
+  },
+  DELETE_MANY: async ({ id, friendIds }) => {
+    await fetchJson(`/users/${id}/friends`, {
+      method: "DELETE",
+      body: { friendIds },
+    });
+    return [id, friendIds]; // [parentId, [childId, …]]
+  },
+});
+```
+
+The singular POST/PUT/PATCH callbacks return the **child** object. It is upserted
+into the child store, but it does not join the parent's array on its own: the
+array is the backend's, and only a GET_MANY refresh rewrites it.
+
+### `.scopedOne(propertyName, { idKey, GET, POST, PUT, PATCH, DELETE })`
+
+Every callback returns `[ownerId, props | null]`:
+
+```js
+const USER_PROFILE = USER.scopedOne("profile", {
+  GET: async ({ id }) => [id, await fetchJson(`/users/${id}/profile`)],
+  PATCH: async ({ id, ...props }) => [
+    id,
+    await fetchJson(`/users/${id}/profile`, { method: "PATCH", body: props }),
+  ],
+  DELETE: async ({ id }) => {
+    await fetchJson(`/users/${id}/profile`, { method: "DELETE" });
+    return [id, null];
+  },
+});
+```
+
+The property is `null` until a callback provides data. `ownerId` may be
+`{ [uniqueKey]: value }` when the owner is known by an alternate key rather than
+its id.
+
+### `.scopedMany(propertyName, { idKey, GET, GET_MANY, POST, PUT, PATCH, DELETE, … })`
+
+Every callback returns `[ownerId, ...rest]`:
+
+```js
+const GAME_CANDIDATES = GAME.scopedMany("candidates", {
+  idKey: "user_id",
+  GET_MANY: async ({ id }) => [id, await fetchJson(`/games/${id}/candidates`)],
+  POST: async ({ id, ...body }) => [
+    id,
+    await fetchJson(`/games/${id}/candidates`, { method: "POST", body }),
+  ],
+  PUT: async ({ id, oldUserId, ...props }) => [id, oldUserId, props], // id rename
+  DELETE: async ({ id, user_id }) => {
+    await fetchJson(`/games/${id}/candidates/${user_id}`, { method: "DELETE" });
+    return [id, user_id];
+  },
+});
+```
+
+| Callback           | Returns                                                |
+| ------------------ | ------------------------------------------------------ |
+| GET / POST / PATCH | `[ownerId, props]`                                     |
+| PUT (id rename)    | `[ownerId, oldId, props]`                              |
+| DELETE             | `[ownerId, childId]`                                   |
+| any `*_MANY`       | `[ownerId, itemArray]` — replaces the whole collection |
+| DELETE_MANY        | `[ownerId, [childId, …]]`                              |
+
+`idKey` names the child's own key inside its owner (`user_id` above); it defaults
+to `"id"`.
+
+## When the backend answers a sub-route with the whole parent
+
+This is the common REST shape, and it is the reason `op` dispatch feels
+attractive: a full-parent response absorbs into a parent `PATCH` with no
+thinking. Model the relation anyway and absorb the response in the callback —
+`resource()` gives a plural callback for exactly this: **any `*_MANY` callback
+replaces the collection wholesale**.
+
+```js
+const GAME_CANDIDATES = GAME.scopedMany("candidates", {
+  idKey: "user_id",
+  GET_MANY: async ({ id }) => {
+    const game = await fetchJson(`/games/${id}/candidates`);
+    return [game.id, game.candidates];
+  },
+  // the backend returns the refreshed game, not the created candidate:
+  // POST_MANY resyncs the collection from it in one shot
+  POST_MANY: async ({ id, ...body }) => {
+    const game = await fetchJson(`/games/${id}/candidates`, {
+      method: "POST",
+      body,
+    });
+    return [game.id, game.candidates];
+  },
+});
+```
+
+For `.many()`, the equivalent is its GET_MANY callback, which already takes the
+parent object with the array nested inside — return the response untouched.
+
+Deletion is the exception: `DELETE`/`DELETE_MANY` drop by id rather than replace,
+so return `[ownerId, deletedId]` using the id you already have in the params,
+and ignore the full parent the backend sent back.
+
+Fields of the parent that come back in such a response (a `status`, a `score`)
+are not applied by the relation callback — it only writes the relation. If the
+parent's own fields change too, either let the parent GET rerun (see below) or
+`store.upsert()` the parent explicitly.
+
+## Relations and autorerun
+
+Relationship mutations do **not** invalidate their parent by default. The exact
+rules, verified by `src/state/rest/tests/resource_graph_parent_rerun.test.js`:
+
+- `.scopedMany` child **POST** reruns the owner's singular `GET` — but only when
+  the last GET response actually embedded that property. GET_MANY on the parent
+  is never rerun by a child POST (a list of parents is not stale because one of
+  them gained a child).
+- `.scopedMany` child **PUT / PATCH / DELETE** rerun nothing: the callback result
+  already carries the updated child.
+- `.scopedOne` mutations rerun nothing, ever — the result is the new value.
+- `.one` / `.many` children live in an independent store; mutating them never
+  reruns the parent. Declare it explicitly with `dependencies` if you need it
+  (see [resource_dependencies.md](./resource_dependencies.md)).
+- Within a relationship resource, the usual defaults still apply: its own
+  `GET_MANY` reruns after its own `POST`; its `GET` is reset (not rerun) by its
+  `DELETE`. Override per relation with `rerunOn`/`dependencies`, which every
+  relationship method accepts.
+
+Splitting a sub-resource out of a parent `PATCH` therefore changes the refresh
+graph: what used to be refreshed by the parent's own response is now refreshed
+only by these rules. When a parent field genuinely depends on a child mutation,
+say so with `dependencies` rather than relying on a rerun that will not happen.
+
+## Binding params instead of wrapping in an arrow
+
+Every action exposes `bindParams()`, which returns an action instance with its
+own state. Pass that instance to a component:
+
+```jsx
+// ✓ loading, error and disabled states come for free
+<Button action={GAME_CANDIDATES.POST.bindParams({ id: game.id, user_id })}>
+  Accept
+</Button>
+```
+
+```jsx
+// ✗ an inline arrow throws away the per-params action state
+<Button
+  action={async () => {
+    await acceptCandidate(game.id, user_id);
+  }}
+>
+  Accept
+</Button>
+```
+
+The arrow works, but nothing tracks it: no per-row spinner, no error surfaced on
+the button that caused it, no deduplication of concurrent runs, no autorerun of
+the actions this mutation should invalidate. See [actions.md](./actions.md).
+
+## See also
+
+- [resource_with_params.md](./resource_with_params.md) — `withParams()` and
+  isolated lifecycles
+- [resource_dependencies.md](./resource_dependencies.md) — cross-resource
+  autorerun
+- [actions.md](./actions.md) — action lifecycle, `bindParams`, `useAsyncData`

package/docs/resource_dependencies.md

@@ -0,0 +1,103 @@
+# Resource Dependencies Documentation
+
+The `withParams` method now supports cross-resource dependencies, allowing you to set up autoreload relationships between different resources.
+
+## Basic Usage
+
+```js
+const role = resource("role", {
+  GET_MANY: () => fetchRoles(),
+  POST: (data) => createRole(data),
+  DELETE: (id) => deleteRole(id),
+});
+
+const database = resource("database", {
+  GET_MANY: () => fetchDatabases(),
+  POST: (data) => createDatabase(data),
+  DELETE: (id) => deleteDatabase(id),
+});
+
+const tables = resource("tables", {
+  GET_MANY: () => fetchTables(),
+  POST: (data) => createTable(data),
+  DELETE: (id) => deleteTable(id),
+});
+
+// Create a parameterized resource with cross-resource dependencies
+const ROLE_WITH_OWNERSHIP = role.withParams(
+  { owners: true },
+  {
+    dependencies: [role, database, tables],
+  },
+);
+```
+
+## How It Works
+
+When you specify `dependencies`, any non-GET action (POST, PUT, PATCH, DELETE) on the dependency resources will trigger an autoreload of the GET_MANY actions in the parameterized resource.
+
+### Autoreload Behavior
+
+- **Triggering Actions**: Any POST, PUT, PATCH, or DELETE on dependency resources
+- **Target Actions**: GET_MANY actions in the parameterized resource (same param scope only)
+- **Scope Isolation**: Only actions with the same parameter scope are affected
+
+### Example Scenarios
+
+1. **Creating a table**: `tables.POST.load(newTableData)` → triggers `ROLE_WITH_OWNERSHIP.GET_MANY` reload
+2. **Deleting a database**: `database.DELETE.load(dbId)` → triggers `ROLE_WITH_OWNERSHIP.GET_MANY` reload
+3. **Updating a role**: `role.PUT.load(roleData)` → triggers `ROLE_WITH_OWNERSHIP.GET_MANY` reload
+
+## Advanced Usage
+
+### Parameterized Dependencies
+
+You can also use parameterized resources as dependencies:
+
+```js
+const recentTables = tables.withParams({ recent: true });
+const adminTables = tables.withParams({ owner: "admin" });
+
+const ROLE_WITH_RECENT_OWNERSHIP = role.withParams(
+  { owners: true },
+  {
+    dependencies: [recentTables], // Only affected by recent tables
+  },
+);
+
+const ROLE_WITH_ADMIN_OWNERSHIP = role.withParams(
+  { owners: true },
+  {
+    dependencies: [adminTables], // Only affected by admin tables
+  },
+);
+```
+
+### Custom Autoreload Settings
+
+You can also customize the autoreload behavior:
+
+```js
+const ROLE_WITH_OWNERSHIP = role.withParams(
+  { owners: true },
+  {
+    dependencies: [role, database, tables],
+    autoreloadGetManyAfter: ["POST", "DELETE", "PUT"], // Custom trigger verbs
+    autoreloadGetAfter: false, // Disable GET autoreload
+  },
+);
+```
+
+## Implementation Details
+
+- **Global Registry**: Dependencies are tracked in a global registry to enable cross-resource communication
+- **Memory Management**: The system uses WeakSets to avoid memory leaks
+- **Async Execution**: Autoreloads are triggered asynchronously with `setTimeout` to ensure proper sequencing
+- **Parameter Isolation**: Each parameter scope maintains its own autoreload behavior
+
+## Benefits
+
+1. **Reactive Updates**: Automatically keep related data in sync across different resources
+2. **Parameter Isolation**: Avoid unwanted cross-contamination between different parameter sets
+3. **Flexible Dependencies**: Mix and match regular and parameterized resources as dependencies
+4. **Performance**: Only reload what's actually needed based on the dependency graph

package/docs/resource_with_params.md

@@ -0,0 +1,80 @@
+# Resource `withParams()` Method
+
+Creates a parameterized version of a resource with isolated autoreload behavior. Solves cross-contamination where actions with different parameters incorrectly trigger each other's autoreload.
+
+## Problem & Solution
+
+Without `withParams()`:
+
+```javascript
+const ROLE = resource("role", {
+  GET_MANY: (params) => fetchRoles(params),
+  DELETE: (params) => deleteRole(params),
+});
+
+// These actions interfere with each other
+await ROLE.GET_MANY.bindParams({ admin: true });
+await ROLE.DELETE.bindParams({ id: 123 }); // ❌ Reloads both admin and non-admin queries
+```
+
+With `withParams()`:
+
+```javascript
+const adminRoles = ROLE.withParams({ admin: true });
+const guestRoles = ROLE.withParams({ admin: false });
+
+await adminRoles.DELETE({ id: 123 }); // ✅ Only reloads admin queries
+```
+
+## API
+
+### `resource.withParams(params)`
+
+**Parameters:** `params` (Object, required) - Parameters to bind to all actions
+
+**Returns:** New resource instance with parameter-bound actions and isolated autoreload
+
+**Throws:** Error if params is empty
+
+## Autoreload Hierarchy
+
+Actions follow a parent-child hierarchy where child scopes reload their parents:
+
+```javascript
+const ROLE = resource("role", { GET_MANY: () => fetch("/roles") });
+const ROLE_ADMIN = ROLE.withParams({ type: "admin" });
+const ROLE_ADMIN_MALE = ROLE_ADMIN.withParams({ gender: "male" });
+
+// Si ROLE_ADMIN_MALE.POST() est exécuté, il recharge :
+// ✅ ROLE_ADMIN_MALE.GET_MANY (même scope: { type: "admin", gender: "male" })
+// ✅ ROLE_ADMIN.GET_MANY (parent scope: { type: "admin" })
+// ✅ ROLE.GET_MANY (root parent: {})
+// ❌ Ne recharge PAS femaleAdmin.GET_MANY ({ type: "admin", gender: "female" })
+
+// Si ROLE_ADMIN.POST() est exécuté, il recharge :
+// ✅ ROLE_ADMIN.GET_MANY (même scope: { type: "admin" })
+// ✅ ROLE.GET_MANY (root parent: {})
+// ❌ Ne recharge PAS ROLE_ADMIN_MALE.GET_MANY (enfant, pas parent)
+
+// Si ROLE.POST() est exécuté, il recharge :
+// ✅ ROLE.GET_MANY (même scope: {})
+// ❌ Ne recharge PAS ROLE_ADMIN.GET_MANY ni ROLE_ADMIN_MALE.GET_MANY (enfants, pas parents)
+```
+
+## Chaining
+
+```javascript
+const maleAdmins = USER.withParams({ role: "admin" }).withParams({
+  gender: "male",
+});
+
+// Equivalent to:
+const maleAdmins = USER.withParams({ role: "admin", gender: "male" });
+```
+
+## Key Features
+
+- **Isolation**: Different parameter sets have separate autoreload behavior
+- **Hierarchy**: Child scopes reload parent scopes automatically
+- **Shared Store**: All parameterized resources use the same data store
+- **Efficient**: Parameter comparison is cached for performance

package/package.json

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