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
@@ -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
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
/**
|
||||
* Does a live `useShape` read reach the DEPLOYED broker, and does deleting from the set it
|
||||
* returns reach the document?
|
||||
* publishes on `data` reach the document?
|
||||
*
|
||||
* Standalone, and deliberately outside `e2e/run.ts`: what it measures is the PUBLISHED
|
||||
* `useShape` - the collection an application reads off the `data` member of what the ORM
|
||||
|
||||
@@ -8,8 +8,8 @@
|
||||
* It was `watchShape` until `1.0.0-dev.5`. That name has ZERO occurrences upstream, and
|
||||
* it spent `watch`, a verb the ORM has already spent on signal observation
|
||||
* (`watch as watchDeepSignal`). The target's own name is `useShapeQuery`, and what it
|
||||
* returns is the snapshot below rather than the bare `DeepSignalSet` today's `useShape`
|
||||
* hands back - announced by NextGraph's developers and on record in
|
||||
* returns is the snapshot below rather than the two states today's `useShape` hands back -
|
||||
* announced by NextGraph's developers and on record in
|
||||
* `.project/rules/nextgraph/surface-mirrors-the-sdk.md`, which is what the annotation on
|
||||
* the function cites. Deviating TOWARD an announced target is alignment; the rest of the
|
||||
* surface is what will catch up:
|
||||
@@ -29,10 +29,12 @@
|
||||
* whole-dataset marker `did:ng:i` are now read by the engine, literally, and this module
|
||||
* does not interpret them at all - so the three readings are upstream's, not ours.
|
||||
*
|
||||
* It does NOT delegate to the SDK's `useShape`: that is React's hook, it returns a bare
|
||||
* `DeepSignalSet`, and a set cannot carry the request state this surface exists to
|
||||
* publish. What is taken from the SDK is the QUERY; the observable, the snapshot and the
|
||||
* state tracking stay here.
|
||||
* It does NOT delegate to the SDK's `useShape`: that is React's hook, callable only from a
|
||||
* render, and what it hands back carries two states where this surface publishes three. Its
|
||||
* `isLoading` says whether the initial payload has arrived and has no value for "it never
|
||||
* will" - a refused read and a slow one are the same answer there - and there is no error
|
||||
* state to carry one. What is taken from the SDK is the QUERY; the observable, the snapshot
|
||||
* and the state tracking stay here.
|
||||
*
|
||||
* -- What stays ours, and why ----------------------------------------------
|
||||
* 1. **The three states.** `readyPromise` is the ORM's own answer to "has the initial
|
||||
@@ -190,7 +192,7 @@ import type { BaseType, ShapeType } from "@ng-org/shex-orm";
|
||||
* (never `undefined`), and its items are the SHAPE's own objects - what the ORM
|
||||
* returns, carrying `@id`, `@graph` and the shape's readable predicates.
|
||||
*/
|
||||
// @provenance ShapeQuery kind=invention level=none ref=none - no upstream type carries load state; `RdfOrmSubscription.readyPromise` expresses pending-vs-ready and nothing else (built with `resolve` alone, and a refused `orm_start_graph` is only `console.error`'d - a failed read is an eternal pending), so `isError` has no counterpart at any level
|
||||
// @provenance ShapeQuery kind=invention level=none ref=none - no upstream type carries a FAILED read. The React hook's result carries a load state (`isLoading`) beside its data, so pending-vs-ready has a counterpart; what has none is the third state, because `readyPromise` is built with `resolve` alone and a refused `orm_start_graph` is only `console.error`'d - a failed read is an eternal pending at every level, so `isError` is answered nowhere
|
||||
export interface ShapeQuery<T extends BaseType = BaseType> {
|
||||
/** The objects of the requested shape/scope. Empty array when none (never undefined).
|
||||
* When `isError`, this is the last read that ANSWERED - kept, not cleared, because an
|
||||
@@ -213,7 +215,7 @@ export interface ShapeQuery<T extends BaseType = BaseType> {
|
||||
}
|
||||
|
||||
/** The observable a caller binds with `useSyncExternalStore` (phase B). */
|
||||
// @provenance ShapeObservable kind=invention level=none ref=none - no upstream observable exists; the ORM exposes a hook returning a DeepSignalSet and nothing else
|
||||
// @provenance ShapeObservable kind=invention level=none ref=none - no upstream observable exists; the ORM exposes a React hook and a subscription class, neither of which a caller subscribes to with `getSnapshot`/`subscribe`
|
||||
export interface ShapeObservable<T extends BaseType = BaseType> {
|
||||
/** The current snapshot. STABLE across calls until it actually changes (so
|
||||
* `useSyncExternalStore` does not loop): the same reference is returned until a
|
||||
@@ -281,7 +283,7 @@ function sameFailure(a: unknown, b: unknown): boolean {
|
||||
* {@link ShapeObservable.refetch}) - that is what opens the shape query; before then
|
||||
* `getSnapshot` reports the initial pending snapshot.
|
||||
*/
|
||||
// @provenance useShapeQuery kind=announced-not-written level=3 ref=.project/rules/nextgraph/surface-mirrors-the-sdk.md:useShapeQuery announced-by=nextgraph-developers@2026-09-16 - the SDK ships `useShape` returning a bare `DeepSignalSet`; the announced direction is a `useShapeQuery` returning a TanStack-shaped snapshot
|
||||
// @provenance useShapeQuery kind=announced-not-written level=3 ref=.project/rules/nextgraph/surface-mirrors-the-sdk.md:useShapeQuery announced-by=nextgraph-developers@2026-09-16 - the SDK ships `useShape`, whose result carries data and a load state and no failure; the announced direction is a `useShapeQuery` returning a TanStack-shaped snapshot
|
||||
export function useShapeQuery<T extends BaseType = BaseType>(
|
||||
shapeType: ShapeType<T>,
|
||||
scope: Scope,
|
||||
|
||||
Reference in New Issue
Block a user