docs: ce que le hook du SDK rend vraiment, la ou le depot disait un set nu

Six endroits affirmaient au present que `useShape` rend un `DeepSignalSet` nu.
C-est vrai de la revision citee, faux de celle contre laquelle ce paquet est
construit - et deux de ces six PORTAIENT une decision de provenance :

- `ShapeQuery kind=invention` etait justifie par "aucun type amont ne porte
  d-etat de chargement", alors que `isLoading` en porte un. Le kind tient, mais
  pour l-autre raison : ce qui n-a de contrepartie nulle part est le troisieme
  etat, la lecture ECHOUEE, parce qu-un `orm_start_graph` refuse n-est qu-un
  `console.error` et laisse une attente eternelle a tous les niveaux.
- l-annotation `announced-not-written` de `useShapeQuery` posait la meme
  premisse fausse. La direction annoncee ne bouge pas ; sa premisse si.

Ajoutee aussi l-instruction d-injection qui ne resolvait pas : l-export `.` de
`@ng-org/orm` pointe sur `core`, qui n-exporte aucun `useShape`. Il est sur
`/react` (export par defaut) ou `reactUseShape` sur `/all`.
This commit is contained in:
Sylvain Duchesne
2026-09-24 18:28:24 +02:00
parent 3a8941159f
commit e16fd6a707
6 changed files with 53 additions and 28 deletions
+17 -9
View File
@@ -85,21 +85,29 @@ change** to any document in scope.
```ts
useShape<T extends BaseType>(
shape: ShapeType<T>,
scope: Scope | string | undefined,
): DeepSignalSet<T>
conf: RdfOrmConfig<T> | string | undefined,
): ShapeResult // { data, promise, subscription, isLoading, nextPage?, previousPage? }
```
- `shape` — the ORM shape type (generated from a SHEX shape). Names the entity type
and the properties to materialize.
- `scope` — where to read: a `{ graphs, subjects }` scope object or a NURI string.
- `conf` — where to read and how: the ORM's `RdfOrmConfig` (a `{ graphs, subjects }`
scope plus `where`, `orderBy`, `pageSize`, `maxActivePages`) or a NURI string.
**Not to be confused with this library's `Scope`** (`types.ts`), which is the
literal union `public | protected | private` naming a store. Same word, two
meanings: the ORM's is a read target, ours is a placement.
`undefined` yields an empty read.
- **Returns** a `DeepSignalSet<T>` — a **live reactive set**. Iterate it like a set;
the component re-renders whenever the set changes.
`undefined` yields an empty read, with `data`, `promise` and `subscription` all
`undefined` and `isLoading` false.
- **Returns** the ORM's own result object, read-filtered. Read the objects off
**`data`** — a **live reactive set** (an ordered array once `orderBy` is asked for),
which the component re-renders on — or `await promise` for the same collection once
it has arrived. `isLoading` says whether the initial payload is still outstanding.
`subscription` is REFUSED here: it is the ORM's own handle, which reads and writes
with no capability filter at all, and this library does not hand it on.
Verified surface in `nextgraph-rs`:
Verified surface in `nextgraph-rs` — the CITED revision, which returns the collection
itself; the BUILD returns it inside a result object, which is the signature above and the
gap the provenance anchor records:
`sdk/js/orm/src/frontendAdapters/react/useShape.ts` (`useShape`, line 86) →
`OrmSubscription` (`sdk/js/orm/src/connector/GraphOrmSubscription.ts`), which calls
`ng.orm_start_graph(...)` with a callback, applies the initial materialized objects
@@ -116,8 +124,8 @@ alongside the React one (`sdk/js/orm/src/frontendAdapters/{vue,svelte}/`).
1. **An initial value.** On subscribe, the ORM materializes the current objects in
scope and delivers them first (`AppResponseV0::GraphOrmInitial`,
`engine/verifier/src/orm/graph/initialize.rs:113`). The hook returns them as the
initial `DeepSignalSet`.
`engine/verifier/src/orm/graph/initialize.rs:113`). The hook publishes them as
`data`, the initial `DeepSignalSet`.
2. **A stream of updates.** On every subsequent commit affecting the scope — local or
remote — the ORM pushes a patch (`AppResponseV0::GraphOrmUpdate`), the connector
applies it to the `DeepSignalSet`, and the component re-renders. No refetch, no