foldkit-remote 0.6.0 → 0.7.0

package/dist/index.mjs

@@ -1344,12 +1344,6 @@ const assembleRelation = (store, value, relation) => {
 * Entities: the descriptor an application declares, refs, ref pages, and
 * patches, with the codecs that carry refs on the wire.
 */
-/**
-* Relations are **references**, never inline target schemas: a ref cannot
-* reconstruct a full entity, and dereferencing is a store concern. Because the
-* target schema is not inlined, recursive relations cannot arise through the
-* schema graph.
-*/
 const refCodec = (entity) => Schema.Struct({
 	entity: Schema.String,
 	id: Schema.String
@@ -2457,9 +2451,10 @@ const withoutQueryLoading = (loading, identity) => {
 * leaves its mark behind, and a connection released with that mark would read
 * `Loading` forever the next time something asked for it before sending.
 */
-const prunedQueryLoading = (loading, roots) => {
+const prunedLoading = (loading, roots, reached) => {
+	if (loading.size === 0) return loading;
 	const named = new Set(roots.connections.map((root) => connectionMark(root.identity)));
-	const kept = [...loading].filter((mark) => !mark.startsWith(connectionPrefix) || named.has(mark));
+	const kept = [...loading].filter((mark) => mark.startsWith(connectionPrefix) ? named.has(mark) : reached().has(markEntity(mark)));
 	return kept.length === loading.size ? loading : new Set(kept);
 };
 /**
@@ -2589,12 +2584,14 @@ const updateRemote = (model, message) => {
 			};
 		case "RetentionChanged": {
 			const retained = gc(model, message.roots);
+			let reachedKeys;
+			const reached = () => reachedKeys ??= reachable(model.entities, message.roots, model.connections, model.optimistic, model.mutations.pending);
 			return {
 				...model,
 				...retained,
 				refresh: prunedRefresh(model.refresh, retained),
-				failures: prunedFailures(model, message.roots),
-				loading: prunedQueryLoading(model.loading, message.roots)
+				failures: prunedFailures(model.failures, message.roots, reached),
+				loading: prunedLoading(model.loading, message.roots, reached)
 			};
 		}
 		case "Hydrated": {
@@ -2606,9 +2603,11 @@ const updateRemote = (model, message) => {
 				})),
 				stale: true
 			}]);
+			const written = Object.entries(message.entities).flatMap(([key, entry]) => message.merge === "replace" || !(key in model.entities) ? [...entry.present].map((field) => `${key}\u0000${field}`) : []);
 			return {
 				...model,
 				entities: RemotePersistence.mergeStores(model.entities, message.entities, message.merge),
+				failures: withoutFieldFailures(model.failures, written),
 				connections: message.merge === "replace" ? {
 					...model.connections,
 					...Object.fromEntries(restored)
@@ -2621,7 +2620,7 @@ const updateRemote = (model, message) => {
 		case "RefreshStarted": {
 			const asked = message.requests.reduce((store, request) => isTombstone(store, entityKey(request.entity, request.id)) ? remove(store, entityKey(request.entity, request.id)) : store, model.entities);
 			const entities = setStale(asked, marksOf(message.requests), true);
-			const failures = withoutFieldFailures(model.failures, fieldMarks(message.requests));
+			const failures = withoutFieldFailures(model.failures, reachedMarks(model.entities, message.requests));
 			return entities === model.entities && failures === model.failures ? model : {
 				...model,
 				entities,
@@ -2737,7 +2736,6 @@ const updateRemote = (model, message) => {
 			};
 		case "QueryFailed": return {
 			...model,
-			connections: message.connection in model.connections ? setConnectionStale(model.connections, message.connection, false) : model.connections,
 			failures: {
 				...model.failures,
 				connections: {
@@ -2793,6 +2791,35 @@ const patchedMarks = function* (patches) {
 	for (const patch of patches) for (const field of Object.keys(patch.values)) yield fieldMark(patch.entity, patch.id, field);
 };
 /**
+* Every field a read's requests reach: their own, and through each relation
+* the store already holds, the fields they ask of its targets. A request with
+* a relation riding on it names no target id; the store does, and a failure
+* recorded on a target is reached only this way.
+*/
+const reachedMarks = (store, requests) => {
+	const marks = [];
+	const walked = /* @__PURE__ */ new Map();
+	const walk = (entity, id, requirement) => {
+		const key = entityKey(entity, id);
+		const seen = walked.get(key) ?? /* @__PURE__ */ new Set();
+		if (seen.has(requirement)) return;
+		seen.add(requirement);
+		walked.set(key, seen);
+		for (const field of requirement.fields) {
+			marks.push(fieldMark(entity, id, field));
+			const nested = requirement.relations?.[field];
+			if (nested === void 0) continue;
+			const value = readField(store, key, field);
+			if (value._tag === "None") continue;
+			for (const ref of targetsOf(value.value, nested)) walk(ref.entity, ref.id, nested);
+		}
+	};
+	for (const request of requests) walk(request.entity, request.id, request);
+	return marks;
+};
+/** The entity key a field mark belongs to. */
+const markEntity = (mark) => mark.slice(0, mark.indexOf("\0"));
+/**
 * The failures of what the roots still reach. A released connection's or
 * entity's failure goes with it, so asking for it again later asks the server
 * again rather than repeating an error that may no longer hold.
@@ -2802,12 +2829,10 @@ const patchedMarks = function* (patches) {
 * which is exactly a value whose first read failed: it is still on screen,
 * behind the parent that refers to it.
 */
-const prunedFailures = (model, roots) => {
-	const { failures } = model;
+const prunedFailures = (failures, roots, reached) => {
 	const named = new Set(roots.connections.map((root) => root.identity));
 	const connections = Object.entries(failures.connections).filter(([identity]) => named.has(identity));
-	const kept = Object.keys(failures.fields).length === 0 ? /* @__PURE__ */ new Set() : reachable(model.entities, roots, model.connections, model.optimistic, model.mutations.pending);
-	const fields = Object.entries(failures.fields).filter(([mark]) => kept.has(mark.slice(0, mark.indexOf("\0"))));
+	const fields = Object.keys(failures.fields).length === 0 ? [] : Object.entries(failures.fields).filter(([mark]) => reached().has(markEntity(mark)));
 	return connections.length === Object.keys(failures.connections).length && fields.length === Object.keys(failures.fields).length ? failures : {
 		connections: Object.fromEntries(connections),
 		fields: Object.fromEntries(fields)
@@ -2816,6 +2841,32 @@ const prunedFailures = (model, roots) => {
 /** Whether this field's last read failed and nothing has settled it since. */
 const isFieldFailed = (model, entity, id, field) => fieldMark(entity, id, field) in model.failures.fields;
 /**
+* Whether a read is fetching any field `relation` reads of an entity, its own
+* or, through each relation the store holds, its targets'. A value whose owner
+* is being fetched is loading, not `Initial`: nothing is missing a fetch.
+*/
+const isLoadingThrough = (model, entity, id, relation) => {
+	if (model.loading.size === 0) return false;
+	const walked = /* @__PURE__ */ new Map();
+	const walk = (target, targetId, requirement) => {
+		const key = entityKey(target, targetId);
+		const seen = walked.get(key) ?? /* @__PURE__ */ new Set();
+		if (seen.has(requirement)) return false;
+		seen.add(requirement);
+		walked.set(key, seen);
+		for (const field of requirement.fields) {
+			if (model.loading.has(fieldMark(target, targetId, field))) return true;
+			const nested = requirement.relations?.[field];
+			if (nested === void 0) continue;
+			const value = readField(model.entities, key, field);
+			if (value._tag === "None") continue;
+			for (const ref of targetsOf(value.value, nested)) if (walk(ref.entity, ref.id, nested)) return true;
+		}
+		return false;
+	};
+	return walk(entity, id, relation);
+};
+/**
 * The first failure among the fields `relation` reads of an entity, following
 * each relation the store holds into its targets, as `assemble` does. A read
 * that consults it shows `Failed` for a related entity's failure too, rather
@@ -3077,6 +3128,26 @@ const askedOf = (projection) => projection === void 0 ? nothingAsked : {
 	connections: connectionsOf(projection)
 };
 /**
+* Whether `outer` asks for everything `inner` does of one entity: each field,
+* each relation's own slice of its target, and each page window alike.
+*/
+const sliceCovers = (outer, inner) => outer.entity === inner.entity && inner.fields.every((field) => outer.fields.includes(field)) && Object.entries(inner.relations ?? {}).every(([field, relation]) => {
+	const wider = outer.relations?.[field];
+	return wider !== void 0 && sliceCovers(wider, relation);
+}) && Object.entries(inner.windows ?? {}).every(([field, window]) => outer.windows?.[field] !== void 0 && stableStringify(outer.windows[field]) === stableStringify(window));
+/**
+* Whether what `outer` asks includes everything `inner` asks: each list with
+* the slice it selects of its rows, and each entity with the slice it reads,
+* relations included. A Surface that shows a read is one whose projection
+* asks for all of it; one that reads part of it cannot be why it is fetched.
+* A Surface that asks for one entity in several pieces is already one
+* requirement here: projection metadata unions them per entity and id.
+*/
+const covers = (outer, inner) => {
+	const { connections, requirements } = outer;
+	return inner.connections.every((connection) => connections.some((wider) => wider.identity === connection.identity && (connection.select === void 0 || wider.select !== void 0 && sliceCovers(wider.select, connection.select)))) && inner.requirements.every((requirement) => requirements.some((wider) => wider.id === requirement.id && sliceCovers(wider, requirement)));
+};
+/**
 * Plans what a projection asks against the Model. A connection the Model holds
 * fresh contributes its visible items' selected fields to the entity plan; one
 * it does not hold, or holds stale, is a query to run (its items are planned
@@ -3369,6 +3440,21 @@ const Remote = {
 	/** Whether a Message is one of Remote's, by tag. */
 	reduces: isRemoteMessage,
 	/**
+	* A patch of one entity's values, for a mutation's `optimistic` list or an
+	* overlay. Takes a `foldkit-entity` Entity or a Remote descriptor alike, so
+	* the domain you declared once is the one you patch:
+	* `Remote.patch(Project, 'p1', { name: 'Apollo II' })`. Values are the
+	* fields' wire shape, as the server writes them; a relation is its ref key
+	* (`'User:u1'`).
+	*/
+	patch: (entity, id, values) => descriptorOf(entity).patch(id, values),
+	/**
+	* A reference to one entity, for `ConnectionChange` and anything else that
+	* names a row: `Remote.ref(Project, 'p3')`. Either kind of entity, as with
+	* `Remote.patch`.
+	*/
+	ref: (entity, id) => descriptorOf(entity).ref(id),
+	/**
 	* Declares a Remote domain and binds it to its place in the application Model
 	* in one step; the result carries the application-facing operations. The
 	* descriptor alone is `Remote.define`, the binding alone `Remote.at`.
@@ -3433,7 +3519,7 @@ const Remote = {
 					error: failure,
 					previous: present.value
 				} : present;
-				if (isLoading(remote, selection.entity, id, relation.fields)) return { _tag: "Loading" };
+				if (isLoadingThrough(remote, selection.entity, id, relation)) return { _tag: "Loading" };
 				return failure === void 0 ? { _tag: "Initial" } : {
 					_tag: "Failed",
 					error: failure
@@ -3795,7 +3881,7 @@ const bindDomain = (definition, store) => {
 				if (remote.loading.size === 0) return void 0;
 				for (const edge of visibleItems(connection, ref.identity, remote.optimistic.overlays, remote.entities)) {
 					if (edge.ref.entity !== relation.entity) continue;
-					if (isLoading(remote, edge.ref.entity, edge.ref.id, relation.fields)) return { _tag: "Loading" };
+					if (isLoadingThrough(remote, edge.ref.entity, edge.ref.id, relation)) return { _tag: "Loading" };
 				}
 			};
 			const readPage = (remote, connection) => {
@@ -3931,6 +4017,59 @@ const bindDomain = (definition, store) => {
 				}
 			};
 		},
+		why: (model, projection, options) => {
+			const state = projection.read(model);
+			const asked = askedOf(projection);
+			const reading = options?.surfaces === void 0 ? void 0 : Object.values(options.surfaces).filter((active) => {
+				const shown = active.projectionOf(model);
+				return shown !== void 0 && covers(askedOf(shown), asked);
+			}).map((active) => active.name);
+			const withSurfaces = reading === void 0 ? {} : { surfaces: reading };
+			switch (state._tag) {
+				case "Ready": return {
+					state: state._tag,
+					message: "Everything it selects is here.",
+					...withSurfaces
+				};
+				case "Refreshing": return {
+					state: state._tag,
+					message: "It is shown while a newer value is fetched.",
+					...withSurfaces
+				};
+				case "Loading": return {
+					state: state._tag,
+					message: "A request for it is in flight.",
+					...withSurfaces
+				};
+				case "NotFound": return {
+					state: state._tag,
+					message: "The server answered without it: it does not exist, or this principal may not see it.",
+					...withSurfaces
+				};
+				case "Failed": return {
+					state: state._tag,
+					message: state.error._tag === "DecodeError" ? `What the server sent does not decode against the Selection: ${state.error.message}` : `Its request failed: ${state.error.message}. Nothing retries a failed read on its own; Data.refresh asks again.`,
+					...withSurfaces
+				};
+				case "Initial":
+					if (reading === void 0) return {
+						state: state._tag,
+						reason: "Unknown",
+						message: "Nothing is fetching it. Pass the active record you give Data.subscriptions as `surfaces` to tell whether an active Surface reads it."
+					};
+					return reading.length === 0 ? {
+						state: state._tag,
+						reason: "NotObserved",
+						message: "No active Surface reads it, so nothing fetches it. Include it in a Surface that is active for this Model, in the record given to Data.subscriptions.",
+						surfaces: reading
+					} : {
+						state: state._tag,
+						reason: "NotFetching",
+						message: `${reading.join(", ")} ${reading.length === 1 ? "reads it and is" : "read it and are"} active, yet nothing is fetching it. Remote's Subscriptions are most likely not installed: give the runtime Data.subscriptions (or Data.wiring) and a RemoteClient.`,
+						surfaces: reading
+					};
+			}
+		},
 		filtered: (model, over, by, input) => {
 			assertRegistered(bound, "Query", definition.registry.queries, by.name);
 			const filters = by.body?.entity.name;
@@ -4054,6 +4193,6 @@ const pageSize = (window, key) => {
 	return size === void 0 ? {} : { [key]: size };
 };
 //#endregion
-export { ConnectionChange, ConnectionChangeSchema, Entity, IDENTITY_SEPARATOR, Live, LiveChange, LiveEdge, LiveRequirement, MAX_FIELDS_PER_REQUEST, MAX_RELATION_DEPTH, Mutate, Mutation, MutationRequest, MutationResult, NormalizedEntity, PageSize, Query, QueryEdge, QueryRequest, QueryResult, QueryRpc, RELATION_ALIAS, REMOTE_CACHE_VERSION, REMOTE_PROTOCOL_VERSION, Read, ReadBatch, ReadBatchResult, ReadRequest, RelationAnnotation, RelationEntityAnnotation, RelationRequest, Remote, RemoteClient, RemoteConnections, RemoteData, RemoteLiveError, RemoteMutationError, RemotePersistence, RemotePolicy, RemoteProtocolError, RemoteQueryError, RemoteReadError, RemoteRequirements, RemoteRpc, Requirement, Selection, WindowSchema, WireBoundary, addLayer, addOverlay, aliasedField, applyConnectionEvent, applyEntityEvent, assemble, beginMutation, beginOptimistic, belongsEncoded, classifyLive, clearStale, coalesceQueries, coalesceReads, coalescedLayer, connectionChangeOf, connectionIdentity, connectionsOf, cursor, edge, emptyConnection, emptyLiveState, emptyMutationState, emptyOptimistic, emptyRefresh, emptyStore, entityKey, entry, failMutation, failureOf, gc, hasField, hasNext, hasPrevious, initialRemoteModel, inspectEntity, inspectRemote, isFieldFailed, isFieldStale, isGapped, isLoading, isQueryLoading, isRefPage, isRemoteMessage, isTombstone, items, liveEventOf, liveHasNext, liveHasPrevious, markStale, matching, merge, missingFields, mutateRemote, mutationStatus, noFailures, pageSchema, plan, pruneOverlays, reachable, readField, reconcileMutation, refParts, refreshIsInFlight, refreshedAt, refsIn, relationAlias, relationOf, relationShape, remoteDataSchema, remoteError, remoteErrorSchema, remoteMessageCases, remoteMessageSchema, remoteModelSchema, remove, removeLayer, removeOverlay, requirementKey, requirementsOf, retentionRootsSchema, schemaOf, segment, setStale, settleFailure, settleSuccess, shouldWake, stableStringify, targetsOf, terminal, tombstone, unknown, updateRemote, visibleItems, visibleStore, windowKey, withRefreshRequested, writeEntities, writeEntity, writeRead };
+export { ConnectionChange, ConnectionChangeSchema, Entity, IDENTITY_SEPARATOR, Live, LiveChange, LiveEdge, LiveRequirement, MAX_FIELDS_PER_REQUEST, MAX_RELATION_DEPTH, Mutate, Mutation, MutationRequest, MutationResult, NormalizedEntity, PageSize, Query, QueryEdge, QueryRequest, QueryResult, QueryRpc, RELATION_ALIAS, REMOTE_CACHE_VERSION, REMOTE_PROTOCOL_VERSION, Read, ReadBatch, ReadBatchResult, ReadRequest, RelationAnnotation, RelationEntityAnnotation, RelationRequest, Remote, RemoteClient, RemoteConnections, RemoteData, RemoteLiveError, RemoteMutationError, RemotePersistence, RemotePolicy, RemoteProtocolError, RemoteQueryError, RemoteReadError, RemoteRequirements, RemoteRpc, Requirement, Selection, WindowSchema, WireBoundary, addLayer, addOverlay, aliasedField, applyConnectionEvent, applyEntityEvent, assemble, beginMutation, beginOptimistic, belongsEncoded, classifyLive, clearStale, coalesceQueries, coalesceReads, coalescedLayer, connectionChangeOf, connectionIdentity, connectionsOf, cursor, edge, emptyConnection, emptyLiveState, emptyMutationState, emptyOptimistic, emptyRefresh, emptyStore, entityKey, entry, failMutation, failureOf, gc, hasField, hasNext, hasPrevious, initialRemoteModel, inspectEntity, inspectRemote, isFieldFailed, isFieldStale, isGapped, isLoading, isLoadingThrough, isQueryLoading, isRefPage, isRemoteMessage, isTombstone, items, liveEventOf, liveHasNext, liveHasPrevious, markStale, matching, merge, missingFields, mutateRemote, mutationStatus, noFailures, pageSchema, plan, pruneOverlays, reachable, readField, reconcileMutation, refParts, refreshIsInFlight, refreshedAt, refsIn, relationAlias, relationOf, relationShape, remoteDataSchema, remoteError, remoteErrorSchema, remoteMessageCases, remoteMessageSchema, remoteModelSchema, remove, removeLayer, removeOverlay, requirementKey, requirementsOf, retentionRootsSchema, schemaOf, segment, setStale, settleFailure, settleSuccess, shouldWake, stableStringify, targetsOf, terminal, tombstone, unknown, updateRemote, visibleItems, visibleStore, windowKey, withRefreshRequested, writeEntities, writeEntity, writeRead };
 
 //# sourceMappingURL=index.mjs.map