feat!: useShapeQuery prend le Scope du SDK, et un store se nomme par sa reference
This commit is contained in:
Sylvain Duchesne
@@ -0,0 +1,292 @@
|
||||
/**
|
||||
* `useShapeQuery` says "there is nothing" or "I could not find out" — never the first for the second.
|
||||
*
|
||||
* The whole reason this surface exists is one distinction: an application must be able to
|
||||
* tell a scope that is EMPTY from a scope it has not heard back about. `useShape` upstream
|
||||
* cannot — it returns "an empty set, if still loading" — and `useShapeQuery` publishes
|
||||
* `isPending` / `isSuccess` / `isError` precisely to answer the question three ways.
|
||||
*
|
||||
* Until 2026-08-17 it destroyed that distinction on the one input that mattered. Step 1 of
|
||||
* its pipeline asks `listMyEntityDocs` which documents are mine; the failure
|
||||
* was caught, logged, and the empty set flowed on. A barrier over zero documents is
|
||||
* trivially reached, so the surface published `{ data: [], isPending: false, isSuccess:
|
||||
* true }` — the exact snapshot a genuinely empty scope produces, byte for byte. An
|
||||
* application rendered "you have created nothing" for "the store did not answer", which is
|
||||
* the outage this library already shipped twice (`8c8ade7`, `f6d1734`) and closed one layer
|
||||
* down the day before (`90712e0`, which made that very call throw). Catching it here put it
|
||||
* straight back one floor up.
|
||||
*
|
||||
* ── The two questions, and why the second needs its own test ──────────────
|
||||
* A one-shot call rejects and is done. An observable has already handed a list to a
|
||||
* subscriber that RENDERED it, so a failure that arrives afterwards has to say something
|
||||
* about that list — and `data: []` would be the empty answer again, in the one field an
|
||||
* application actually paints. So there are two cases here, not one: the failure BEFORE any
|
||||
* answer, and the failure AFTER one.
|
||||
*
|
||||
* ── The fault is the broker's, and it is one a real one produces ──────────
|
||||
* Nothing here plants a state or reaches in to make a library function throw. The documents
|
||||
* were CREATED through the surface, over the same wallet, in the session before; then the
|
||||
* connection dies — the broker answers normally and stops answering, and every query after
|
||||
* that rejects the way the wasm binding rejects a transport error. Same montage as
|
||||
* `listing-surfaces-failure.test.ts`, one layer up.
|
||||
*/
|
||||
|
||||
import { test, expect, describe, mock, beforeEach, afterAll } from "bun:test";
|
||||
import { configure, useShapeQuery, storeRegistry } from "../src/index";
|
||||
import type { ShapeObservable, ShapeQuery } from "../src/surface/use-shape-query";
|
||||
import { configureStoreRegistry } from "../src/shared-wallet/bootstrap";
|
||||
import { sparqlUpdate } from "../src/surface/docs";
|
||||
import type { NgLike, Nuri, StoreType, UseShapeLike } from "../src/model/types";
|
||||
import { SESSION, forgetEverything, makeWallet, signIn, storeOfType, type Quad } from "./wallet-fake";
|
||||
|
||||
const SHIM = "urn:ng-eventually:shim";
|
||||
/** The Main-branch read of a store — "which documents are in here". Step 1 of the pipeline. */
|
||||
const LISTING_READ = `<${SHIM}:contains>`;
|
||||
|
||||
const RDF_TYPE = "http://www.w3.org/1999/02/22-rdf-syntax-ns#type";
|
||||
const EVENT = "http://festipod.org/Event";
|
||||
const TITLE = "http://festipod.org/title";
|
||||
|
||||
/** A minimal SHEX ShapeType pinning `rdf:type` to {@link EVENT}. */
|
||||
const EventShape = {
|
||||
shape: "http://festipod.org/EventShape",
|
||||
schema: {
|
||||
"http://festipod.org/EventShape": {
|
||||
iri: "http://festipod.org/EventShape",
|
||||
predicates: [{ iri: RDF_TYPE, dataTypes: [{ literals: [EVENT], valType: "iri" }] }],
|
||||
},
|
||||
},
|
||||
};
|
||||
|
||||
/**
|
||||
* Wire the library onto `quads` over a broker that STOPS ANSWERING from the first query
|
||||
* `lostAt` accepts — that one included, and every one after it, for the rest of the page.
|
||||
*
|
||||
* A dropped connection is not selective, so neither is this: the switch decides *when* the
|
||||
* link dies, never *which* call is unlucky. Passing `() => false` is a broker that stays up.
|
||||
*
|
||||
* `doc_subscribe` is carried here rather than left off (`wallet-fake` has none, and the
|
||||
* library then takes its documented no-op open path): with no subscription there is no
|
||||
* `State`, so the sync BARRIER would be skipped instead of crossed, and `isPending` would
|
||||
* fall away for a reason the real platform never gives. It pushes what the platform pushes
|
||||
* — `TabInfo` then `State`, in that order — and a link that is down pushes NOTHING, which
|
||||
* is what a link that is down does.
|
||||
*/
|
||||
function bootPage(quads: Quad[], lostAt: (query: string) => boolean): void {
|
||||
const wallet = makeWallet(quads);
|
||||
let lost = false;
|
||||
const ng = {
|
||||
doc_create: wallet.doc_create,
|
||||
sparql_update: wallet.sparql_update,
|
||||
sparql_query: mock(async (...a: unknown[]) => {
|
||||
if (lost || lostAt(a[1] as string)) {
|
||||
lost = true;
|
||||
throw new Error("BrokerError: connection lost");
|
||||
}
|
||||
return wallet.sparql_query(...a);
|
||||
}),
|
||||
doc_subscribe: mock(async (_nuri: string, _sid: unknown, cb: (r: unknown) => void) => {
|
||||
if (lost) throw new Error("BrokerError: connection lost");
|
||||
setTimeout(() => {
|
||||
if (lost) return;
|
||||
cb({ V0: { TabInfo: {} } });
|
||||
cb({ V0: { State: {} } });
|
||||
}, 0);
|
||||
return () => {};
|
||||
}),
|
||||
};
|
||||
configure({ ng: ng as unknown as NgLike, useShape: (() => {}) as unknown as UseShapeLike });
|
||||
configureStoreRegistry({ getSession: async () => SESSION, normalizeId: (id) => id.trim() });
|
||||
}
|
||||
|
||||
/**
|
||||
* The session before: alice signs in and creates one document carrying one Event, over a
|
||||
* broker that works. Returns the quads the wallet now holds — the durable half that
|
||||
* outlives the page.
|
||||
*/
|
||||
async function aFirstSessionThatCreated(scope: StoreType): Promise<{ quads: Quad[]; note: Nuri }> {
|
||||
const quads: Quad[] = [];
|
||||
forgetEverything();
|
||||
bootPage(quads, () => false);
|
||||
await signIn("alice");
|
||||
const note = await storeRegistry.createEntityDoc(await storeOfType(scope));
|
||||
await sparqlUpdate(
|
||||
SESSION.sessionId,
|
||||
`INSERT DATA { <urn:test:evt> <${RDF_TYPE}> <${EVENT}> ; <${TITLE}> "the note" }`,
|
||||
note,
|
||||
);
|
||||
return { quads, note };
|
||||
}
|
||||
|
||||
/** A first session where alice signs in and creates NOTHING — a genuinely empty scope. */
|
||||
async function aFirstSessionThatCreatedNothing(): Promise<Quad[]> {
|
||||
const quads: Quad[] = [];
|
||||
forgetEverything();
|
||||
bootPage(quads, () => false);
|
||||
await signIn("alice");
|
||||
return quads;
|
||||
}
|
||||
|
||||
/**
|
||||
* What the APPLICATION reads off a snapshot — the whole point of the surface, written the
|
||||
* way a view would branch on it. Four readings, and the two this file is about are
|
||||
* `"nothing"` and `"unknown"`: they must never be the same one.
|
||||
*/
|
||||
type Reading = "still-asking" | "nothing" | "some" | "unknown";
|
||||
function whatTheAppSees(snap: ShapeQuery): Reading {
|
||||
if (snap.isError) return "unknown";
|
||||
if (snap.isPending) return "still-asking";
|
||||
return snap.data.length === 0 ? "nothing" : "some";
|
||||
}
|
||||
|
||||
/** Wait, bounded, for a condition on the observable. A deadline names itself. */
|
||||
async function until(what: string, pred: () => boolean): Promise<void> {
|
||||
const deadline = Date.now() + 2000;
|
||||
while (!pred()) {
|
||||
if (Date.now() > deadline) throw new Error(`deadline waiting for: ${what}`);
|
||||
await new Promise((r) => setTimeout(r, 5));
|
||||
}
|
||||
}
|
||||
|
||||
/** Subscribe like an application does, and wait until the first question has an answer. */
|
||||
async function subscribeAndSettle(
|
||||
obs: ShapeObservable,
|
||||
): Promise<{ renders: () => number; stop: () => void }> {
|
||||
let renders = 0;
|
||||
const stop = obs.subscribe(() => {
|
||||
renders += 1;
|
||||
});
|
||||
await until("the first answer", () => !obs.getSnapshot().isPending);
|
||||
return { renders: () => renders, stop };
|
||||
}
|
||||
|
||||
const ALL_SCOPES: StoreType[] = ["public", "protected", "private"];
|
||||
|
||||
/** The whole local dataset - upstream's own marker, and the reading that still has to
|
||||
* enumerate this identity's documents, which is the step these tests make fail. */
|
||||
const EVERYTHING = { graphs: "did:ng:i" };
|
||||
|
||||
beforeEach(() => {
|
||||
forgetEverything();
|
||||
});
|
||||
afterAll(() => {
|
||||
// The caps registry, the config and the registry caches are PROCESS-WIDE, and `bun test`
|
||||
// runs every file in ONE process — so this teardown is not housekeeping. Caps left behind
|
||||
// put the possession gate in force for a suite that declares none, and `subscribe.test.ts`
|
||||
// is then refused at the door for documents it legitimately owns; a config left behind
|
||||
// hands `access-log.test.ts` this file's `ng`. Both failed exactly that way before this
|
||||
// ran, and neither names use-shape-query anywhere. `forgetEverything` is the whole teardown.
|
||||
forgetEverything();
|
||||
});
|
||||
|
||||
describe("useShapeQuery tells 'there is nothing' from 'I could not find out'", () => {
|
||||
// The NORMAL cases first, and they are not a formality: a surface that reported `isError`
|
||||
// unconditionally would pass every failure case below. These two are what those are a
|
||||
// departure from — and the first of them is the reading that must never be reused for a
|
||||
// failure, so it has to be pinned before anything can be said to differ from it.
|
||||
for (const scope of ALL_SCOPES) {
|
||||
test(`[${scope}] a scope this account never wrote to reads as NOTHING`, async () => {
|
||||
const quads = await aFirstSessionThatCreatedNothing();
|
||||
|
||||
forgetEverything();
|
||||
bootPage(quads, () => false);
|
||||
await signIn("alice");
|
||||
|
||||
const obs = useShapeQuery(EventShape, EVERYTHING) as ShapeObservable;
|
||||
const { stop } = await subscribeAndSettle(obs);
|
||||
|
||||
const snap = obs.getSnapshot();
|
||||
expect(whatTheAppSees(snap)).toBe("nothing");
|
||||
expect(snap.isSuccess).toBe(true);
|
||||
expect(snap.isError).toBe(false);
|
||||
expect(snap.data).toEqual([]);
|
||||
stop();
|
||||
});
|
||||
}
|
||||
|
||||
for (const scope of ALL_SCOPES) {
|
||||
test(`[${scope}] a scope holding a document reads as SOME`, async () => {
|
||||
const { quads } = await aFirstSessionThatCreated(scope);
|
||||
|
||||
forgetEverything();
|
||||
bootPage(quads, () => false);
|
||||
await signIn("alice");
|
||||
|
||||
const obs = useShapeQuery(EventShape, EVERYTHING) as ShapeObservable;
|
||||
const { stop } = await subscribeAndSettle(obs);
|
||||
|
||||
const snap = obs.getSnapshot();
|
||||
expect(whatTheAppSees(snap)).toBe("some");
|
||||
expect(snap.data.map((s) => s.props[TITLE]?.[0])).toEqual(["the note"]);
|
||||
stop();
|
||||
});
|
||||
}
|
||||
|
||||
// The defect. Alice HAS a document; the store cannot be read; the surface used to answer
|
||||
// with the empty-scope snapshot above — same `data`, same `isSuccess`, nothing to tell
|
||||
// them apart. It is the more dangerous of the two failure values, because "you created
|
||||
// nothing" is a sentence an application renders without hesitating.
|
||||
for (const scope of ALL_SCOPES) {
|
||||
test(`[${scope}] a store that does not answer reads as UNKNOWN, not as nothing`, async () => {
|
||||
const { quads } = await aFirstSessionThatCreated(scope);
|
||||
|
||||
let armed = false;
|
||||
forgetEverything();
|
||||
bootPage(quads, (query) => armed && query.includes(LISTING_READ));
|
||||
await signIn("alice");
|
||||
armed = true;
|
||||
|
||||
const obs = useShapeQuery(EventShape, EVERYTHING) as ShapeObservable;
|
||||
const { stop } = await subscribeAndSettle(obs);
|
||||
|
||||
const snap = obs.getSnapshot();
|
||||
expect(whatTheAppSees(snap)).toBe("unknown");
|
||||
expect(snap.isError).toBe(true);
|
||||
expect(snap.isSuccess).toBe(false);
|
||||
expect(snap.isPending).toBe(false);
|
||||
expect(String((snap.error as Error)?.message)).toMatch(/BrokerError/);
|
||||
// Said as the difference itself, since one reading standing in for the other IS the
|
||||
// defect: this is not the snapshot the empty scope publishes.
|
||||
expect(whatTheAppSees(snap)).not.toBe(whatTheAppSees({
|
||||
data: [], isPending: false, isSuccess: true, isError: false, error: undefined,
|
||||
}));
|
||||
stop();
|
||||
});
|
||||
}
|
||||
|
||||
// The half a one-shot call never has to answer: the subscriber has ALREADY rendered a
|
||||
// list when the link dies. The observable cannot un-emit it, so the failure snapshot must
|
||||
// not put `[]` in the field the view paints — that would be the empty answer again,
|
||||
// arriving later and to a screen that has something on it.
|
||||
for (const scope of ALL_SCOPES) {
|
||||
test(`[${scope}] a list already rendered is not replaced by an empty one`, async () => {
|
||||
const { quads } = await aFirstSessionThatCreated(scope);
|
||||
|
||||
let armed = false;
|
||||
forgetEverything();
|
||||
bootPage(quads, (query) => armed && query.includes(LISTING_READ));
|
||||
await signIn("alice");
|
||||
|
||||
const obs = useShapeQuery(EventShape, EVERYTHING) as ShapeObservable;
|
||||
const { renders, stop } = await subscribeAndSettle(obs);
|
||||
expect(whatTheAppSees(obs.getSnapshot())).toBe("some");
|
||||
const rendersBefore = renders();
|
||||
|
||||
// The link dies, and the application asks again — the imperative refresh the surface
|
||||
// publishes for exactly this.
|
||||
armed = true;
|
||||
obs.refetch();
|
||||
await until("the failure to reach the subscriber", () => obs.getSnapshot().isError);
|
||||
|
||||
const snap = obs.getSnapshot();
|
||||
expect(whatTheAppSees(snap)).toBe("unknown");
|
||||
expect(snap.isSuccess).toBe(false);
|
||||
// The list it had is still there — a memory, never offered as a fresh answer.
|
||||
expect(snap.data.map((s) => s.props[TITLE]?.[0])).toEqual(["the note"]);
|
||||
// And the subscriber was TOLD: a view that renders `data` and never re-reads the
|
||||
// load state would otherwise keep showing the list as though it were current.
|
||||
expect(renders()).toBeGreaterThan(rendersBefore);
|
||||
stop();
|
||||
});
|
||||
}
|
||||
});
|
||||
Reference in New Issue
Block a user