@haddowg/json-api-query 1.0.0

package/dist/index.cjs

@@ -0,0 +1,836 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/keys.ts
+/**
+* Recursively normalise a params value so semantically-equal params serialise identically:
+* object keys are sorted; arrays keep order (order is meaningful in a list — `sort`, `include`);
+* `undefined` members are dropped (an absent param == an unset one). Primitives pass through.
+* Not JSON.stringify — the key stays a structured tuple so TanStack's structural matching and
+* the devtools see real values, not an opaque string.
+*/
+function normalizeParams(value) {
+	if (value === null || value === void 0) return null;
+	if (Array.isArray(value)) return value.map((v) => normalizeParams(v));
+	if (typeof value === "object") {
+		const out = {};
+		for (const key of Object.keys(value).sort()) {
+			const member = value[key];
+			if (member !== void 0) out[key] = normalizeParams(member);
+		}
+		return out;
+	}
+	if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") return value;
+	return String(value);
+}
+/**
+* Build a deterministic, hierarchical query key from `(type, operation, id?, rel?, params?)`.
+* The fixed-position prefix (`type`, `operation`, then `id`, then `rel`) makes any ancestor a
+* valid invalidation target; params (when present and non-empty) ride a single trailing
+* normalised object so reorderings collapse to one key. An absent/empty params object adds no
+* trailing segment, so a bare `list()` and `list({})` share a key.
+*/
+function keyFor(target, params) {
+	const parts = [target.type, target.operation];
+	if (target.id !== void 0) parts.push(target.id);
+	if (target.rel !== void 0) parts.push(target.rel);
+	if (params !== void 0) {
+		const normalized = normalizeParams(params);
+		if (!isEmptyNormalized(normalized)) parts.push(normalized);
+	}
+	return parts;
+}
+/** True when a normalised params value carries no information (an empty object or array, or null). */
+function isEmptyNormalized(value) {
+	if (value === null) return true;
+	if (Array.isArray(value)) return value.length === 0;
+	if (typeof value === "object") return Object.keys(value).length === 0;
+	return false;
+}
+/** The whole-type subtree prefix (`[type]`) — invalidates every operation/read of a type. */
+function typeKey(type) {
+	return [type];
+}
+/** An operation subtree prefix (`[type, operation]`) — e.g. every `fetchMany` (list) of a type. */
+function operationKey(type, operation) {
+	return [type, operation];
+}
+/**
+* A single-resource subtree prefix (`[type, 'fetchOne', id]`) — matches that resource's reads.
+* Pairs with {@link keyFor} (which places `id` at the same position), so it is a true prefix of
+* every `fetchOne` key for the id regardless of its query params.
+*/
+function resourceKey(type, id) {
+	return [
+		type,
+		"fetchOne",
+		id
+	];
+}
+/**
+* A single-relation read prefix (`[type, operation, id, rel]`) for `fetchRelated` /
+* `fetchRelationship` — matches one parent's reads of one relation, regardless of query params.
+* Pairs with {@link keyFor} (which places `id` then `rel` at fixed positions), so it is a true
+* prefix of every related/relationship key for that `(id, rel)`. Used for TARGETED invalidation of
+* a parent's relation after a relationship mutation (never the type's collection lists — ADR 0003).
+*/
+function relationKey(type, operation, id, rel) {
+	return [
+		type,
+		operation,
+		id,
+		rel
+	];
+}
+/**
+* BOTH read prefixes for one parent's one relation — its related-collection reads
+* (`[type, 'fetchRelated', id, rel]`) AND its relationship-linkage reads
+* (`[type, 'fetchRelationship', id, rel]`). A relation is read over two surfaces, so a single
+* prefix can't cover both; this returns the pair so an app targets every cached page of a
+* `(parent, relation)` — for invalidation or an optimistic membership patch — WITHOUT
+* reconstructing keys (or coupling to the page params a read used). PUBLIC: it is the key helper
+* the relationship-mutation optimistic path and apps share (D35b).
+*/
+function relationReadKeys(type, id, rel) {
+	return [relationKey(type, "fetchRelated", id, rel), relationKey(type, "fetchRelationship", id, rel)];
+}
+/**
+* True when `key` is prefixed by `prefix` (segment-by-segment string equality over the prefix's
+* length). The cache-walking optimistic/invalidation paths use it to find every page variant of a
+* `(parent, relation)` read (whose params ride the key's trailing segment). Mirrors TanStack's own
+* prefix-based `queryKey` matching so a targeted patch and TanStack's `invalidateQueries` agree.
+*/
+function keyHasPrefix(key, prefix) {
+	if (key.length < prefix.length) return false;
+	for (let i = 0; i < prefix.length; i++) if (key[i] !== prefix[i]) return false;
+	return true;
+}
+//#endregion
+//#region src/normalize.ts
+const resourceKey$1 = (type, id) => `${type}:${id}`;
+const isObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+/** A materialised resource's `type`+`id`, when it is a real resource (string type + id). */
+function identity(node) {
+	const { type, id } = node;
+	if (typeof type === "string" && typeof id === "string") return {
+		type,
+		id
+	};
+}
+/**
+* The freshest attributes for a node, read from its `$raw.attributes` (the wire split of
+* attributes from relations). Returns `undefined` when the node carries no `$raw` or no
+* attributes block (a bare identifier view, or an attribute-less resource) — nothing to
+* propagate. Never falls back to enumerating own props, which would conflate relation slots
+* with attributes.
+*/
+function attributesOf(node) {
+	const attrs = node.$raw?.attributes;
+	return isObject(attrs) ? attrs : void 0;
+}
+/**
+* Walk a materialised value (a single resource, an augmented array, a to-one/to-many relation
+* value, or `null`/`undefined`) and visit every reachable resource exactly once. Recurses into
+* each resource's own enumerable relation slots so a deeply-included graph is fully indexed.
+* `seen` guards relation cycles (a node memoised by reference) and keeps the walk linear.
+*/
+function walkResources(value, descriptor, visit, seen = /* @__PURE__ */ new Set()) {
+	if (value === null || value === void 0) return;
+	if (Array.isArray(value)) {
+		for (const member of value) walkResources(member, descriptor, visit, seen);
+		return;
+	}
+	if (!isObject(value)) return;
+	if (seen.has(value)) return;
+	seen.add(value);
+	const node = value;
+	const ident = identity(node);
+	if (ident === void 0) return;
+	visit(node);
+	const relations = descriptor[ident.type]?.relations;
+	if (relations === void 0) return;
+	for (const name of Object.keys(relations)) {
+		const slot = value[name];
+		if (slot !== void 0) walkResources(slot, descriptor, visit, seen);
+	}
+}
+/**
+* Patch one materialised node IN PLACE from `attributes`: overwrite each attribute key on the
+* target's own enumerable props (relations and `type`/`id` are left untouched), and shallow-set
+* any new keys. The non-enumerable `$`-accessors and the per-edge `$pivot`/`$edge` getters are
+* defined separately (closing over the original wire member), so they survive unchanged — a
+* per-edge view keeps its own pivot while its shared attributes update.
+*
+* `$raw` is intentionally NOT mutated: it is the immutable original wire object (the escape
+* hatch). Only the flattened, own-enumerable attribute props — the values consumers read —
+* are patched. Returns whether any value actually changed, so an idempotent re-application
+* (e.g. installNormalization re-running after a factory's own `onSuccess`) reports no change and
+* is not written back / re-notified.
+*/
+function patchNode(target, attributes) {
+	let changed = false;
+	for (const [k, v] of Object.entries(attributes)) if (!(k in target) || target[k] !== v) {
+		target[k] = v;
+		changed = true;
+	}
+	return changed;
+}
+/**
+* Index every resource in `result` by `type:id` → its freshest attributes, then return the
+* set of `type:id`s the result carries. The caller patches every cached query holding any of
+* those keys (see {@link normalize}).
+*/
+function collectAttributes(result, descriptor) {
+	const fresh = /* @__PURE__ */ new Map();
+	walkResources(result, descriptor, (node) => {
+		const ident = identity(node);
+		if (ident === void 0) return;
+		const attributes = attributesOf(node);
+		if (attributes !== void 0) fresh.set(resourceKey$1(ident.type, ident.id), attributes);
+	});
+	return fresh;
+}
+/**
+* Patch every materialised node in `cached` whose `type:id` appears in `fresh`, in place,
+* with the freshest attributes — returning whether any VALUE actually changed. We mutate the
+* cached objects directly (preserving their identity/accessors) rather than rebuilding them, so
+* writing the same reference back triggers TanStack's subscribers without a structural-sharing diff
+* fighting the per-edge views. A node whose attributes already equal `fresh` is a no-op (reports
+* unchanged), so a redundant re-application doesn't write back or re-notify.
+*/
+function patchCached(cached, fresh, descriptor) {
+	let changed = false;
+	walkResources(cached, descriptor, (node) => {
+		const ident = identity(node);
+		if (ident === void 0) return;
+		const attributes = fresh.get(resourceKey$1(ident.type, ident.id));
+		if (attributes !== void 0 && patchNode(node, attributes)) changed = true;
+	});
+	return changed;
+}
+/**
+* Write-through patch (the heart of Strategy 2). Given a freshly-resolved materialised
+* `result`, index its resources by `type:id` and patch every OTHER cached query that holds any
+* of those `type:id`s in place, so a single response updates the same resource everywhere it
+* is cached ("edit once, updates everywhere").
+*
+* Edge-local `$pivot`/`$edge` and a node's identity are preserved (only own-enumerable
+* attribute props are overwritten). Pass `result` from an option factory's `onSuccess` (or use
+* {@link installNormalization} to subscribe to every query/mutation success automatically).
+*
+* `result` is the materialised value the client produced for this response (a resource, a
+* `Collection`, a related collection, or linkage). The same reference may also be the cached
+* entry for the query that produced it — we mutate it too (idempotently), which is harmless and
+* keeps every surface holding that resource consistent.
+*
+* CONTRACT: a single QueryClient must hold caches for ONE descriptor only. The patch matches a
+* cached node purely by `type:id` and rewrites it with `descriptor`'s attribute split, so two
+* descriptors that share a QueryClient and a `type:id` (e.g. a `default` + an `admin` server whose
+* `users` differ) would cross-contaminate. `installNormalization` enforces this for the auto path;
+* when calling `normalize` standalone, give each typed client/server its own QueryClient.
+*/
+function normalize(queryClient, result, descriptor) {
+	const fresh = collectAttributes(result, descriptor);
+	if (fresh.size === 0) return;
+	patchAll(queryClient, fresh, descriptor);
+}
+/**
+* Patch every cached query with a `type:id -> fresh attributes` map. We walk the query cache
+* explicitly and only `setQueryData` back the queries that {@link patchCached} actually mutated —
+* NOT a blanket `setQueriesData({}, ...)`. The blanket form writes data back to every cached
+* query, and TanStack's `setQueryData` unconditionally clears `isInvalidated` on the written
+* query: a normalize pass over one type would silently un-invalidate untouched queries of other
+* types, undoing the create/delete membership invalidation (ADR 0003). Gating the write on the
+* `changed` flag keeps touched queries' in-place identity (so their observers notify) while
+* leaving untouched queries — and their `isInvalidated` flags — completely alone.
+*/
+function patchAll(queryClient, fresh, descriptor) {
+	for (const query of queryClient.getQueryCache().getAll()) {
+		const data = query.state.data;
+		if (data === void 0 || data === null) continue;
+		if (patchCached(data, fresh, descriptor)) queryClient.setQueryData(query.queryKey, data);
+	}
+}
+/**
+* Apply an OPTIMISTIC attribute patch to a single `type:id` across every cached query and return a
+* {@link Snapshot} to roll it back. Mirrors the success path ({@link normalize}) — same in-place
+* attribute overwrite, same edge preservation — but for one known resource whose fresh attributes
+* the caller predicts (an update patch's attribute keys), and it captures the prior state first so
+* an error can restore it. Used by the update / relationship-set mutation factories' `onMutate`.
+*/
+function applyOptimisticPatch(queryClient, type, id, attributes, descriptor) {
+	const key = resourceKey$1(type, id);
+	const edits = [];
+	for (const query of queryClient.getQueryCache().getAll()) {
+		const data = query.state.data;
+		if (data === void 0 || data === null) continue;
+		let touched = false;
+		walkResources(data, descriptor, (node) => {
+			const ident = identity(node);
+			if (ident === void 0 || resourceKey$1(ident.type, ident.id) !== key) return;
+			const target = node;
+			const prior = /* @__PURE__ */ new Map();
+			const added = /* @__PURE__ */ new Set();
+			for (const k of Object.keys(attributes)) if (k in target) prior.set(k, target[k]);
+			else added.add(k);
+			edits.push({
+				target,
+				prior,
+				added,
+				wrote: { ...attributes }
+			});
+			patchNode(target, attributes);
+			touched = true;
+		});
+		if (touched) queryClient.setQueryData(query.queryKey, data);
+	}
+	return { restore() {
+		for (const edit of edits) {
+			for (const [k, v] of edit.prior) if (edit.target[k] === edit.wrote[k]) edit.target[k] = v;
+			for (const k of edit.added) if (edit.target[k] === edit.wrote[k]) delete edit.target[k];
+		}
+	} };
+}
+/**
+* Apply an OPTIMISTIC membership change to EVERY cached read of one parent's one relation — both its
+* related-collection (`fetchRelated`) and its relationship-linkage (`fetchRelationship`) reads,
+* matched BY KEY PREFIX so every page/param variant is covered at once (no coupling to the page
+* params a read used — the pain point D35b removes). The to-many read caches an array of members, so
+* the transform runs over that array; the snapshot restores each touched query's PRIOR data
+* wholesale on error. On settle the factory invalidates the relation subtree, so the server
+* reconciles regardless (a degraded optimistic member — an identifier without attributes — is
+* replaced by the real one). A to-one `set` is handled separately (it caches a single value, not an
+* array).
+*/
+function applyOptimisticMembership(queryClient, type, id, rel, transform) {
+	const prefixes = relationReadKeys(type, id, rel);
+	const edits = [];
+	for (const query of queryClient.getQueryCache().getAll()) {
+		const key = query.queryKey;
+		if (!prefixes.some((prefix) => keyHasPrefix(key, prefix))) continue;
+		const data = query.state.data;
+		if (!Array.isArray(data)) continue;
+		edits.push({
+			key,
+			previous: data
+		});
+		queryClient.setQueryData(key, transform(data));
+	}
+	return { restore() {
+		for (const edit of edits) queryClient.setQueryData(edit.key, edit.previous);
+	} };
+}
+/** True when two refs address the same resource (`type:id`). Ignores `$pivot`/attributes. */
+function sameRef(a, b) {
+	return a.type === b.type && a.id === b.id;
+}
+/**
+* Apply an OPTIMISTIC to-one `set` to every cached relationship/related read of one parent's one
+* relation (by key prefix): swap each cached value to `next` (a bare identifier ref, or `null` to
+* clear), snapshotting the prior value for rollback. A to-one read caches a single value (not an
+* array), so a plain replacement is correct; the settle refetch reconciles a bare identifier into
+* the fully-hydrated resource. `undefined` next means the ref carried no cache identity (an
+* lid-only atomic handle) — the cache is left untouched (the wire write still happens).
+*/
+function applyOptimisticToOne(queryClient, type, id, rel, next) {
+	const prefixes = relationReadKeys(type, id, rel);
+	const edits = [];
+	if (next === void 0) return { restore() {} };
+	for (const query of queryClient.getQueryCache().getAll()) {
+		const key = query.queryKey;
+		if (!prefixes.some((prefix) => keyHasPrefix(key, prefix))) continue;
+		const data = query.state.data;
+		if (Array.isArray(data)) continue;
+		edits.push({
+			key,
+			previous: data
+		});
+		queryClient.setQueryData(key, next);
+	}
+	return { restore() {
+		for (const edit of edits) queryClient.setQueryData(edit.key, edit.previous);
+	} };
+}
+//#endregion
+//#region src/install.ts
+/**
+* Which descriptor is currently installed on a given QueryClient. The normalizer patches a cached
+* query by walking it with the *patch's* descriptor and matching on `type:id`, so two descriptors
+* sharing one QueryClient (e.g. a `default` + an `admin` server whose `users` carry different
+* attribute sets — CONTEXT.md's multi-client case) would cross-contaminate: a read from one would
+* overwrite the other's cached node with foreign attributes. The supported contract is therefore
+* ONE descriptor per QueryClient; this registry enforces it for the auto-install entry point.
+* A `WeakMap` so a discarded QueryClient (and its install record) is garbage-collected.
+*/
+const installed = /* @__PURE__ */ new WeakMap();
+/**
+* Subscribe the normalizer to a QueryClient's query + mutation caches: each time a query or
+* mutation settles successfully, the freshly-resolved data is indexed by `type:id` and patched
+* across every cached query in place (preserving edge-local `$pivot`/`$edge`).
+*
+* A QueryClient may host only ONE descriptor (see {@link installed}): installing a *second*,
+* different descriptor on the same QueryClient throws, because the normalizer cannot safely tell
+* which descriptor a given `type:id` belongs to once two descriptors overlap. Use one QueryClient
+* per typed client/server. Re-installing the *same* descriptor is allowed (idempotent-friendly):
+* it just adds another subscription pair with its own teardown.
+*
+* Re-entrancy is guarded: the patch pass itself sets data on other queries (firing further
+* `success` events), so while a pass runs we ignore the events it generates — otherwise a
+* single response would cascade into a loop. Returns a {@link Teardown} that removes both
+* subscriptions (and clears the install record when this was the active install).
+*/
+function installNormalization(queryClient, descriptor) {
+	const existing = installed.get(queryClient);
+	if (existing !== void 0 && existing !== descriptor) throw new Error("installNormalization: this QueryClient already has a different descriptor installed. A QueryClient may host only one descriptor — use a separate QueryClient per client/server so a normalize pass cannot leak one descriptor’s attributes into another’s cached resources.");
+	installed.set(queryClient, descriptor);
+	let normalizing = false;
+	const run = (data) => {
+		if (normalizing || data === void 0 || data === null) return;
+		normalizing = true;
+		try {
+			normalize(queryClient, data, descriptor);
+		} finally {
+			normalizing = false;
+		}
+	};
+	const unsubscribeQueries = queryClient.getQueryCache().subscribe((event) => {
+		if (event.type === "updated" && event.action.type === "success") run(event.query.state.data);
+	});
+	const unsubscribeMutations = queryClient.getMutationCache().subscribe((event) => {
+		if (event.type === "updated" && event.action.type === "success") run(event.mutation.state.data);
+	});
+	let torn = false;
+	return () => {
+		if (torn) return;
+		torn = true;
+		unsubscribeQueries();
+		unsubscribeMutations();
+		if (installed.get(queryClient) === descriptor) installed.delete(queryClient);
+	};
+}
+//#endregion
+//#region src/mutate.ts
+/**
+* Invalidate the list/collection subtree of a type (`[type, 'fetchMany']`) — refetched after a
+* create/delete changes which resources the collection holds. A prefix match, so every cached
+* list of the type (any filter/sort/page) is marked stale at once.
+*/
+function invalidateLists(queryClient, type) {
+	return queryClient.invalidateQueries({ queryKey: operationKey(type, "fetchMany") });
+}
+/**
+* Invalidate every read OF a single resource on delete: its `fetchOne` reads (so a stale `get`
+* refetches and 404s/clears) AND its own `fetchRelated`/`fetchRelationship` reads (orphaned once
+* the resource is gone — `[type, 'fetchOne', id]` does not prefix those). Prefix matches across
+* include/fields/rel. NOTE: this covers the deleted resource's OWN reads; OTHER resources whose
+* relationship/related queries listed this one as a member are not auto-invalidated here (the
+* binding can't know which parents hold it without a cache scan — invalidate those explicitly, or
+* model the parent's own relationship mutation which DOES target it).
+*/
+function invalidateResource(queryClient, type, id) {
+	return Promise.all([
+		queryClient.invalidateQueries({ queryKey: resourceKey(type, id) }),
+		queryClient.invalidateQueries({ queryKey: [
+			type,
+			"fetchRelated",
+			id
+		] }),
+		queryClient.invalidateQueries({ queryKey: [
+			type,
+			"fetchRelationship",
+			id
+		] })
+	]).then(() => void 0);
+}
+/**
+* Invalidate one parent resource's reads of one relation after a set/replace/add/remove changes
+* that relation's linkage/membership (ADR 0003's TARGETED invalidation). We invalidate exactly:
+*  - the relation's related-collection reads (`[type, 'fetchRelated', id, rel]`),
+*  - the relation's linkage reads (`[type, 'fetchRelationship', id, rel]`),
+*  - the parent resource's own reads (`[type, 'fetchOne', id]`) — whose `?include` of the relation
+*    embeds the now-stale members.
+* It deliberately does NOT touch `[type, 'fetchMany']` (the type's collection lists): a relationship
+* change never alters which resources a collection holds, so scoping to the type would needlessly
+* invalidate every list of the type.
+*/
+function invalidateParentRelations(queryClient, type, id, rel) {
+	return Promise.all([
+		queryClient.invalidateQueries({ queryKey: relationKey(type, "fetchRelated", id, rel) }),
+		queryClient.invalidateQueries({ queryKey: relationKey(type, "fetchRelationship", id, rel) }),
+		queryClient.invalidateQueries({ queryKey: resourceKey(type, id) })
+	]).then(() => void 0);
+}
+/**
+* The create mutation (`POST /{type}`): `mutationFn` runs `client.<type>.create(input, opts)`;
+* on settle the type's list subtree is invalidated (a new member changes collection membership —
+* a patch can't insert it, ADR 0003). The fresh resource is also normalized on success so any
+* query already holding the (server-assigned-id) resource reflects it.
+*
+* No optimistic insert by default: inserting into the right cached lists requires knowing each
+* list's sort/filter/page, which is list-specific — we invalidate instead (the documented,
+* always-correct default). A caller wanting optimism supplies their own `onMutate`.
+*/
+function createMutationOptions(queryClient, client, descriptor, type, opts) {
+	const accessor = client[type];
+	return {
+		mutationFn: (input) => accessor.create(input, opts),
+		onSuccess: (data) => {
+			normalize(queryClient, data, descriptor);
+		},
+		onSettled: () => invalidateLists(queryClient, type)
+	};
+}
+/**
+* The update mutation (`PATCH /{type}/{id}`): `mutationFn` runs
+* `client.<type>.id(id).update(patch, opts)`. An update only changes a node's attributes/linkage,
+* so on success it PATCHES across the cache via {@link normalize} (no refetch). When optimistic,
+* `onMutate` pre-applies the patch's attributes (those keys that are declared attributes of the
+* type — relation slots are skipped) through the normalized patch and snapshots the touched
+* queries; `onError` restores the snapshot.
+*
+* @param optimistic apply the patch's attributes immediately (rolled back on error). Default off.
+*/
+function updateMutationOptions(queryClient, client, descriptor, type, id, opts) {
+	const accessor = client[type];
+	const optimistic = opts?.optimistic === true;
+	const base = {
+		mutationFn: (patch) => accessor.id(id).update(patch, opts),
+		onSuccess: (data) => {
+			normalize(queryClient, data, descriptor);
+		}
+	};
+	if (!optimistic) return base;
+	base.onMutate = (patch) => ({ snapshot: applyOptimisticPatch(queryClient, type, id, attributesFromPatch(descriptor, type, patch), descriptor) });
+	base.onError = (_error, _patch, context) => {
+		context?.snapshot.restore();
+	};
+	return base;
+}
+/**
+* The delete mutation (`DELETE /{type}/{id}`): `mutationFn` runs `client.<type>.id(id).delete()`
+* (resolves `void`). On settle the type's list subtree AND that resource's reads are invalidated
+* (a delete changes collection membership and orphans the resource's `get`, ADR 0003).
+*/
+function deleteMutationOptions(queryClient, client, type, id) {
+	const accessor = client[type];
+	return {
+		mutationFn: () => accessor.id(id).delete(),
+		onSettled: async () => {
+			await invalidateLists(queryClient, type);
+			await invalidateResource(queryClient, type, id);
+		}
+	};
+}
+/** True when `opts` requests the optimistic membership patch. */
+const isOptimistic = (opts) => opts?.optimistic === true;
+/**
+* Coerce a linkage ref (`{type,id}` / `{type,lid}` / a resource view, optionally `$pivot`) to a
+* membership ref for the optimistic array patch. The whole ref is preserved (so a hydrated member
+* carrying attributes yields a rich optimistic row), requiring only a string `type`+`id`. A ref
+* addressed only by `lid` (an atomic handle) has no cache identity, so it is dropped from the
+* optimistic view (it still writes on the wire).
+*/
+function toMembershipRef(ref) {
+	const r = ref;
+	if (typeof r.type !== "string" || typeof r.id !== "string") return;
+	return {
+		...ref,
+		type: r.type,
+		id: r.id
+	};
+}
+/** The membership refs (cache-addressable) of a to-many mutation's variables. */
+const membershipRefs = (refs) => refs.map(toMembershipRef).filter((r) => r !== void 0);
+/**
+* Wire the optimistic membership lifecycle onto a to-many relationship mutation: `onMutate` applies
+* `transform` to the parent's cached related/relationship arrays (snapshotting), `onError` rolls
+* back, `onSettled` invalidates the relation subtree (kept from the base). When not optimistic, the
+* base (invalidate-on-settle only) is returned untouched.
+*/
+function withMembershipOptimism(queryClient, type, id, rel, base, transform, optimistic) {
+	if (!optimistic) return base;
+	return {
+		...base,
+		onMutate: (vars) => ({ snapshot: applyOptimisticMembership(queryClient, type, id, rel, (current) => transform(current, vars)) }),
+		onError: (_error, _vars, context) => {
+			context?.snapshot.restore();
+		}
+	};
+}
+/**
+* A to-one relationship `set` (`PATCH …/relationships/{rel}` with a single ref or `null`):
+* `mutationFn` runs `client.<type>.id(id).rel(rel).set(ref)`. A `set` changes which resource the
+* to-one points at — linkage, not collection membership and not a node attribute — so on settle
+* we invalidate the PARENT's relations subtree (its `fetchRelationship`/`fetchRelated`/included
+* reads refetch). The mutation response (linkage) is also normalized on success. When optimistic,
+* `onMutate` swaps the parent's cached relationship/related reads to the new single value (or `null`)
+* and rolls back on error.
+*/
+function setRelationshipMutationOptions(queryClient, client, descriptor, type, id, rel, opts) {
+	const accessor = client[type];
+	const base = {
+		mutationFn: (ref) => accessor.id(id).rel(rel).set(ref),
+		onSuccess: (data) => {
+			normalize(queryClient, data, descriptor);
+		},
+		onSettled: () => invalidateParentRelations(queryClient, type, id, rel)
+	};
+	if (!isOptimistic(opts)) return base;
+	return {
+		...base,
+		onMutate: (ref) => {
+			const next = ref === null ? void 0 : toMembershipRef(ref);
+			return { snapshot: applyOptimisticToOne(queryClient, type, id, rel, ref === null ? null : next) };
+		},
+		onError: (_error, _ref, context) => {
+			context?.snapshot.restore();
+		}
+	};
+}
+/**
+* A to-many relationship `replace` (`PATCH …/relationships/{rel}` with the full new set):
+* `mutationFn` runs `client.<type>.id(id).rel(rel).replace(refs)`. A full replacement resets the
+* relation's membership, so on settle the parent's relations subtree is invalidated. The
+* mutation response (the new linkage) is normalized on success. When optimistic, the cached
+* membership is swapped to `refs` and rolled back on error.
+*/
+function replaceRelationshipMutationOptions(queryClient, client, descriptor, type, id, rel, opts) {
+	const accessor = client[type];
+	return withMembershipOptimism(queryClient, type, id, rel, {
+		mutationFn: (refs) => accessor.id(id).rel(rel).replace(refs),
+		onSuccess: (data) => {
+			normalize(queryClient, data, descriptor);
+		},
+		onSettled: () => invalidateParentRelations(queryClient, type, id, rel)
+	}, (_current, refs) => membershipRefs(refs), isOptimistic(opts));
+}
+/**
+* A to-many relationship `add` (`POST …/relationships/{rel}`): `mutationFn` runs
+* `client.<type>.id(id).rel(rel).add(refs)`. Adding changes the relation's membership, so on
+* settle the parent's relations subtree is invalidated (a patch can't insert linkage members).
+* When optimistic, the added refs are appended to the cached membership (deduplicated by `type:id`)
+* and rolled back on error.
+*/
+function addRelationshipMutationOptions(queryClient, client, type, id, rel, opts) {
+	const accessor = client[type];
+	return withMembershipOptimism(queryClient, type, id, rel, {
+		mutationFn: (refs) => accessor.id(id).rel(rel).add(refs),
+		onSettled: () => invalidateParentRelations(queryClient, type, id, rel)
+	}, (current, refs) => {
+		const added = membershipRefs(refs);
+		return [...current.filter((m) => !added.some((a) => sameRef(a, m))), ...added];
+	}, isOptimistic(opts));
+}
+/**
+* A to-many relationship `remove` (`DELETE …/relationships/{rel}`): `mutationFn` runs
+* `client.<type>.id(id).rel(rel).remove(refs)`. Removing changes the relation's membership, so on
+* settle the parent's relations subtree is invalidated. When optimistic, the removed refs are
+* dropped from the cached membership and rolled back on error.
+*/
+function removeRelationshipMutationOptions(queryClient, client, type, id, rel, opts) {
+	const accessor = client[type];
+	return withMembershipOptimism(queryClient, type, id, rel, {
+		mutationFn: (refs) => accessor.id(id).rel(rel).remove(refs),
+		onSettled: () => invalidateParentRelations(queryClient, type, id, rel)
+	}, (current, refs) => {
+		const removed = membershipRefs(refs);
+		return current.filter((m) => !removed.some((r) => sameRef(r, m)));
+	}, isOptimistic(opts));
+}
+/**
+* A thin atomic-batch mutation (`POST /operations`): `mutationFn` forwards the `build` callback to
+* `client.atomic(build)`, preserving the client's per-op `const`-tuple result inference (the
+* variables ARE the build callback). On success the materialised results are run through
+* {@link normalize} so any updated resource patches across the cache.
+*
+* INVALIDATION is the caller's responsibility for atomic: a batch can mix creates/updates/deletes
+* across many types, and the recorded ops aren't enumerable after the build runs, so the binding
+* can't know which list subtrees changed membership. Updates self-heal via the success
+* normalization; for a batch that creates/deletes, add an `onSettled` that invalidates the
+* affected `operationKey(type, 'fetchMany')` subtrees (or `queryClient.invalidateQueries()` for a
+* blanket refetch). Kept deliberately minimal — atomic is an escape hatch, not a normalized path.
+*/
+function atomicMutationOptions(queryClient, client, descriptor) {
+	return {
+		mutationFn: (build) => client.atomic(build),
+		onSuccess: (data) => {
+			normalize(queryClient, data, descriptor);
+		}
+	};
+}
+/**
+* Split an update patch into just its ATTRIBUTE keys (for an optimistic node patch): a key is an
+* attribute iff the descriptor declares it under `attributes` for the type. Relation slots and
+* any unknown key are dropped — an optimistic patch only touches a node's shared attributes (the
+* same split {@link normalize}'s real patch honours), never linkage.
+*/
+function attributesFromPatch(descriptor, type, patch) {
+	const attributes = descriptor[type]?.attributes ?? {};
+	const out = {};
+	for (const [key, value] of Object.entries(patch)) if (key in attributes) out[key] = value;
+	return out;
+}
+/**
+* Bind a client + QueryClient to the per-type mutation option factories:
+* `createMutationApi(queryClient, client, descriptor).albums.id('1').update({ optimistic: true })`
+* returns the same `MutationOptions` as the standalone {@link updateMutationOptions}, with the
+* common arguments pre-applied. A Proxy (descriptor-keyed type validity is enforced by the static
+* `MutationApi` shape) — no per-type allocation until first access.
+*/
+function createMutationApi(queryClient, client, descriptor) {
+	const cache = /* @__PURE__ */ new Map();
+	return new Proxy(Object.create(null), { get(_target, prop) {
+		if (typeof prop !== "string") return;
+		let api = cache.get(prop);
+		if (api === void 0) {
+			api = typeMutationApi(queryClient, client, descriptor, prop);
+			cache.set(prop, api);
+		}
+		return api;
+	} });
+}
+/** Build one type's bound mutation option factories (delegates to the standalone factories). */
+function typeMutationApi(queryClient, client, descriptor, type) {
+	return {
+		create: (opts) => createMutationOptions(queryClient, client, descriptor, type, opts),
+		id: (id) => ({
+			update: (opts) => updateMutationOptions(queryClient, client, descriptor, type, id, opts),
+			delete: () => deleteMutationOptions(queryClient, client, type, id),
+			rel: (name) => ({
+				add: (opts) => addRelationshipMutationOptions(queryClient, client, type, id, name, opts),
+				remove: (opts) => removeRelationshipMutationOptions(queryClient, client, type, id, name, opts),
+				replace: (opts) => replaceRelationshipMutationOptions(queryClient, client, descriptor, type, id, name, opts),
+				set: (opts) => setRelationshipMutationOptions(queryClient, client, descriptor, type, id, name, opts)
+			})
+		})
+	};
+}
+//#endregion
+//#region src/read.ts
+/**
+* The collection-list read (`GET /{type}`): options resolving the typed `Collection`, narrowed by
+* `include`/`fields` exactly as `client.<type>.list(query)`. The key is `[type, 'fetchMany',
+* <params>]` — the normalised query rides the trailing segment, so two equal queries share a key.
+*/
+function listQueryOptions(client, type, query) {
+	const accessor = client[type];
+	return {
+		queryKey: keyFor({
+			type,
+			operation: "fetchMany"
+		}, query),
+		queryFn: () => accessor.list(query)
+	};
+}
+/**
+* The single-resource read (`GET /{type}/{id}`): options resolving the typed resource view,
+* narrowed by `include`/`fields` as `client.<type>.get(id, query)`. Key: `[type, 'fetchOne', id,
+* <params>]` — the `id` sits at a fixed position so {@link keyFor}'s prefix matches a resource's
+* reads.
+*/
+function getQueryOptions(client, type, id, query) {
+	const accessor = client[type];
+	return {
+		queryKey: keyFor({
+			type,
+			operation: "fetchOne",
+			id
+		}, query),
+		queryFn: () => accessor.get(id, query)
+	};
+}
+/**
+* The relationship-linkage read (`GET /{type}/{id}/relationships/{rel}`): options resolving the
+* materialised linkage (identifier members), via `client.<type>.id(id).rel(rel).get(query)`. Key:
+* `[type, 'fetchRelationship', id, rel, <params>]`. The result is the client's runtime linkage
+* shape; the relationship endpoint's per-relation value is loose at the `.rel(name)` boundary, so
+* the option resolves `unknown` unless the caller annotates it (parity with the client's runtime).
+*/
+function relationshipQueryOptions(client, type, id, rel, query) {
+	const accessor = client[type];
+	return {
+		queryKey: keyFor({
+			type,
+			operation: "fetchRelationship",
+			id,
+			rel
+		}, query),
+		queryFn: () => accessor.id(id).rel(rel).get(query)
+	};
+}
+/**
+* The related-collection read (`GET /{type}/{id}/{rel}`): options resolving the materialised
+* related resource(s), via `client.<type>.id(id).rel(rel).related(query)`. Key: `[type,
+* 'fetchRelated', id, rel, <params>]`. As with linkage, the related value is loose at the
+* `.rel(name)` boundary, so this resolves `unknown` (parity with the client runtime).
+*/
+function relatedQueryOptions(client, type, id, rel, query) {
+	const accessor = client[type];
+	return {
+		queryKey: keyFor({
+			type,
+			operation: "fetchRelated",
+			id,
+			rel
+		}, query),
+		queryFn: () => accessor.id(id).rel(rel).related(query)
+	};
+}
+/**
+* Bind a client to its per-type read-option factories: `createQueryApi(client).albums.list(query)`
+* returns the same `{ queryKey, queryFn }` as `listQueryOptions(client, 'albums', query)`, with
+* `client`/`type` pre-applied. A Proxy (descriptor-free — type validity is enforced by the static
+* `QueryApi` shape) so no per-type allocation until first access.
+*/
+function createQueryApi(client) {
+	const cache = /* @__PURE__ */ new Map();
+	return new Proxy(Object.create(null), { get(_target, prop) {
+		if (typeof prop !== "string") return;
+		let api = cache.get(prop);
+		if (api === void 0) {
+			api = typeQueryApi(client, prop);
+			cache.set(prop, api);
+		}
+		return api;
+	} });
+}
+/** Build one type's bound read-option factories (delegates to the standalone factories). */
+function typeQueryApi(client, type) {
+	return {
+		list: (query) => listQueryOptions(client, type, query),
+		get: (id, query) => getQueryOptions(client, type, id, query),
+		relationship(id, rel, query) {
+			return relationshipQueryOptions(client, type, id, rel, query);
+		},
+		related(id, rel, query) {
+			return relatedQueryOptions(client, type, id, rel, query);
+		}
+	};
+}
+//#endregion
+exports.addRelationshipMutationOptions = addRelationshipMutationOptions;
+exports.applyOptimisticMembership = applyOptimisticMembership;
+exports.applyOptimisticPatch = applyOptimisticPatch;
+exports.applyOptimisticToOne = applyOptimisticToOne;
+exports.atomicMutationOptions = atomicMutationOptions;
+exports.createMutationApi = createMutationApi;
+exports.createMutationOptions = createMutationOptions;
+exports.createQueryApi = createQueryApi;
+exports.deleteMutationOptions = deleteMutationOptions;
+exports.getQueryOptions = getQueryOptions;
+exports.installNormalization = installNormalization;
+exports.keyFor = keyFor;
+exports.keyHasPrefix = keyHasPrefix;
+exports.listQueryOptions = listQueryOptions;
+exports.normalize = normalize;
+exports.normalizeParams = normalizeParams;
+exports.operationKey = operationKey;
+exports.relatedQueryOptions = relatedQueryOptions;
+exports.relationKey = relationKey;
+exports.relationReadKeys = relationReadKeys;
+exports.relationshipQueryOptions = relationshipQueryOptions;
+exports.removeRelationshipMutationOptions = removeRelationshipMutationOptions;
+exports.replaceRelationshipMutationOptions = replaceRelationshipMutationOptions;
+exports.resourceKey = resourceKey;
+exports.sameRef = sameRef;
+exports.setRelationshipMutationOptions = setRelationshipMutationOptions;
+exports.typeKey = typeKey;
+exports.updateMutationOptions = updateMutationOptions;