foldkit-remote 0.20.0 → 0.22.0

package/dist/resume-Ct5R6yli.d.ts

@@ -0,0 +1,92 @@
+import { s as RemoteModel } from "./model-B6zk1NMB.js";
+import { Result, Schema } from "effect";
+import { Focus, Metadata } from "foldkit-surface";
+/**
+ * Marks a Subscription entry Remote built as one that may start late under
+ * `foldkit-ssr`'s deferred boot (its decision 10): a read with resumed data
+ * plans nothing, a live subscription resumes from the cursor the envelope
+ * carries, and retention running late collects late. Non-enumerable, so the
+ * runtime's iteration of an entry never sees it.
+ */
+declare const DEFERRABLE: unique symbol;
+/** Marks every entry of a record Remote built, lifted or not. */
+declare const markAll: <Entries extends object>(entries: Entries) => Entries;
+/** The captured part of a Remote store, as JSON. */
+declare const RemoteCapture: Schema.Struct<{
+  readonly entities: Schema.$Record<Schema.String, Schema.Struct<{
+    readonly values: Schema.$Record<Schema.String, Schema.Unknown>;
+    readonly present: Schema.$Array<Schema.String>;
+    readonly stale: Schema.$Array<Schema.String>;
+    readonly unavailable: Schema.$Array<Schema.String>;
+    readonly windows: Schema.$Record<Schema.String, Schema.String>;
+    readonly tombstone: Schema.Boolean;
+    readonly updatedAt: Schema.Number;
+  }>>;
+  readonly connections: Schema.$Record<Schema.String, Schema.Struct<{
+    readonly segments: Schema.$Array<Schema.Struct<{
+      readonly edges: Schema.$Array<Schema.Struct<{
+        readonly key: Schema.String;
+        readonly ref: Schema.Struct<{
+          readonly entity: Schema.String;
+          readonly id: Schema.String;
+        }>;
+      }>>;
+      readonly start: Schema.Union<readonly [Schema.TaggedStruct<"Terminal", {}>, Schema.TaggedStruct<"Cursor", {
+        readonly cursor: Schema.String;
+      }>, Schema.TaggedStruct<"Unknown", {}>]>;
+      readonly end: Schema.Union<readonly [Schema.TaggedStruct<"Terminal", {}>, Schema.TaggedStruct<"Cursor", {
+        readonly cursor: Schema.String;
+      }>, Schema.TaggedStruct<"Unknown", {}>]>;
+    }>>;
+    readonly stale: Schema.Boolean;
+  }>>;
+  readonly live: Schema.$Record<Schema.String, Schema.Struct<{
+    readonly cursor: Schema.Number;
+    readonly boundary: Schema.$Record<Schema.String, Schema.Struct<{
+      readonly before: Schema.Number;
+      readonly after: Schema.Number;
+    }>>;
+  }>>;
+}>;
+type RemoteCapture = typeof RemoteCapture.Type;
+/**
+ * Captures what some projections read from a store: the fields each
+ * requirement names, through its relations; each connection whole, and the
+ * fields its selection reads of each item; and each live cursor whose
+ * entities were all captured with the fields it follows.
+ */
+declare const captureRemote: (remote: RemoteModel, projections: ReadonlyArray<{
+  readonly metadata: Metadata;
+}>) => RemoteCapture;
+/**
+ * Sets a capture onto a store: its entities, connections and live cursors
+ * replace any held under the same keys, and nothing else of the store changes.
+ */
+declare const restoreRemote: <Store extends RemoteModel>(remote: Store, capture: RemoteCapture) => Store;
+/**
+ * A resume part, in the shape `foldkit-ssr`'s `SSR.plan` takes in `parts`.
+ * Declared here structurally, so neither package depends on the other.
+ */
+interface RemoteResumePart<AppModel> {
+  readonly id: string;
+  /** The metadata key names whose reads this part resumes. */
+  readonly covers: ReadonlyArray<string>;
+  readonly capture: (model: AppModel, projections: ReadonlyArray<{
+    readonly metadata: Metadata;
+  }>) => unknown;
+  readonly restore: (model: AppModel, value: unknown) => Result.Result<AppModel, string>;
+  /** Whether a Subscription entry is one of this domain's, which may start late. */
+  readonly deferrable: (key: string, entry: unknown) => boolean;
+}
+/**
+ * The resume part for a Remote domain, for `SSR.plan`'s `parts`: it sends
+ * what the plan's active Surfaces read from this domain's store, and nothing
+ * else of it. `id` tells two domains in one application apart.
+ */
+declare const resumePart: <AppModel, Store extends RemoteModel>(domain: {
+  readonly store: Focus<AppModel, Store>;
+}, options?: {
+  readonly id?: string | undefined;
+}) => RemoteResumePart<AppModel>;
+export { markAll as a, captureRemote as i, RemoteCapture as n, restoreRemote as o, RemoteResumePart as r, resumePart as s, DEFERRABLE as t };
+//# sourceMappingURL=resume-Ct5R6yli.d.ts.map

package/dist/resume-Ct5R6yli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resume-Ct5R6yli.d.ts","names":[],"sources":["../src/resume.ts"],"mappings":";;;;;;;;;;cAwEa;;cAGA,UAAW,wBAAsB,SAAW,YAAU;;cAQtD,eAAa,OAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KAKd,uBAAuB,cAAc;;;;;;;cAoCpC,gBAAa,QAChB,aAAW,aACN;WAAyB,UAAU;OAC/C;;;;;cA+FU,gBAAiB,cAAc,aAAW,QAC7C,OAAK,SACJ,kBACR;;;;;UA0Cc,iBAAiB;WACvB;;WAEA,QAAQ;WACR,UACP,OAAO,UACP,aAAa;aAAyB,UAAU;;WAEzC,UAAU,OAAO,UAAU,mBAAmB,OAAO,OAAO;;WAE5D,aAAa,aAAa;;;;;;;cAWxB,aAAc,UAAU,cAAc,aAAW;WACzC,OAAO,MAAM,UAAU;GAAQ;WAC9B;MACnB,iBAAiB"}

package/dist/resume.d.ts

@@ -0,0 +1,2 @@
+import { a as markAll, i as captureRemote, n as RemoteCapture, o as restoreRemote, r as RemoteResumePart, s as resumePart, t as DEFERRABLE } from "./resume-Ct5R6yli.js";
+export { DEFERRABLE, RemoteCapture, RemoteResumePart, captureRemote, markAll, restoreRemote, resumePart };

package/dist/resume.js

@@ -0,0 +1,222 @@
+import { own, put } from "./record.js";
+import { RemoteConnections, RemoteRequirements } from "./requirement.js";
+import { targetsOf } from "./relation.js";
+import { entityKey, readField } from "./store.js";
+import { Result, Schema } from "effect";
+// src/resume.ts
+/**
+* What of Remote's state crosses from a server render to the browser.
+*
+* A page rendered a moment ago sends exactly what its active Surfaces read:
+* for each requirement the fields it names, following relations through the
+* refs the store holds, and each connection whole, with its boundaries, so
+* "load more" knows where the server stopped. A live subscription's cursor
+* crosses with the entities it covers, so a subscription started in the
+* browser resumes where the server's left off.
+*
+* This is not a `Snapshot`, which is built for a cache that survived a reload
+* and deliberately keeps no cursors. Nothing else of `RemoteModel` crosses:
+* loading marks, failures, the mutation ledger, optimistic layers, gaps and
+* retention start from their initial values in the browser.
+*/
+const CapturedEntry = Schema.Struct({
+	values: Schema.Record(Schema.String, Schema.Unknown),
+	present: Schema.Array(Schema.String),
+	stale: Schema.Array(Schema.String),
+	unavailable: Schema.Array(Schema.String),
+	windows: Schema.Record(Schema.String, Schema.String),
+	tombstone: Schema.Boolean,
+	updatedAt: Schema.Number
+});
+const CapturedBoundary = Schema.Union([
+	Schema.TaggedStruct("Terminal", {}),
+	Schema.TaggedStruct("Cursor", { cursor: Schema.String }),
+	Schema.TaggedStruct("Unknown", {})
+]);
+const CapturedConnection = Schema.Struct({
+	segments: Schema.Array(Schema.Struct({
+		edges: Schema.Array(Schema.Struct({
+			key: Schema.String,
+			ref: Schema.Struct({
+				entity: Schema.String,
+				id: Schema.String
+			})
+		})),
+		start: CapturedBoundary,
+		end: CapturedBoundary
+	})),
+	stale: Schema.Boolean
+});
+const CapturedLive = Schema.Struct({
+	cursor: Schema.Number,
+	boundary: Schema.Record(Schema.String, Schema.Struct({
+		before: Schema.Number,
+		after: Schema.Number
+	}))
+});
+/**
+* Marks a Subscription entry Remote built as one that may start late under
+* `foldkit-ssr`'s deferred boot (its decision 10): a read with resumed data
+* plans nothing, a live subscription resumes from the cursor the envelope
+* carries, and retention running late collects late. Non-enumerable, so the
+* runtime's iteration of an entry never sees it.
+*/
+const DEFERRABLE = Symbol.for("foldkit-remote/deferrable");
+/** Marks every entry of a record Remote built, lifted or not. */
+const markAll = (entries) => {
+	for (const entry of Object.values(entries)) Object.defineProperty(entry, DEFERRABLE, {
+		value: true,
+		enumerable: false
+	});
+	return entries;
+};
+/** The captured part of a Remote store, as JSON. */
+const RemoteCapture = Schema.Struct({
+	entities: Schema.Record(Schema.String, CapturedEntry),
+	connections: Schema.Record(Schema.String, CapturedConnection),
+	live: Schema.Record(Schema.String, CapturedLive)
+});
+/** What some projections read, from their metadata. */
+const askedOf = (projections) => ({
+	requirements: projections.flatMap((projection) => RemoteRequirements.get(projection.metadata)),
+	connections: projections.flatMap((projection) => RemoteConnections.get(projection.metadata))
+});
+/** Whether every `entity:id:fields` part of a live stream key was captured with those fields. */
+const liveCovered = (stream, entries) => stream.split("|").every((part) => {
+	const split = part.lastIndexOf(":");
+	const entry = entries.get(part.slice(0, split));
+	const fields = part.slice(split + 1).split(",").filter((field) => field !== "");
+	return entry !== void 0 && fields.every((field) => entry.present.has(field));
+});
+/**
+* Captures what some projections read from a store: the fields each
+* requirement names, through its relations; each connection whole, and the
+* fields its selection reads of each item; and each live cursor whose
+* entities were all captured with the fields it follows.
+*/
+const captureRemote = (remote, projections) => {
+	const store = remote.entities;
+	const entries = /* @__PURE__ */ new Map();
+	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);
+		const stored = store[key];
+		if (stored === void 0) return;
+		const entry = entries.get(key) ?? {
+			values: {},
+			present: /* @__PURE__ */ new Set(),
+			stale: /* @__PURE__ */ new Set(),
+			unavailable: /* @__PURE__ */ new Set(),
+			windows: {},
+			tombstone: stored.tombstone,
+			updatedAt: stored.updatedAt
+		};
+		entries.set(key, entry);
+		for (const field of requirement.fields) {
+			if (stored.unavailable.has(field)) entry.unavailable.add(field);
+			if (!stored.present.has(field)) continue;
+			put(entry.values, field, stored.values[field]);
+			entry.present.add(field);
+			if (stored.stale.has(field)) entry.stale.add(field);
+			const window = own(stored.windows, field);
+			if (window !== void 0) put(entry.windows, field, window);
+			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);
+		}
+	};
+	const asked = askedOf(projections);
+	for (const requirement of asked.requirements) walk(requirement.entity, requirement.id, requirement);
+	const connections = {};
+	for (const { identity, select } of asked.connections) {
+		const connection = remote.connections[identity];
+		if (connection === void 0) continue;
+		connections[identity] = connection;
+		for (const segment of connection.segments) for (const edge of segment.edges) walk(edge.ref.entity, edge.ref.id, select);
+	}
+	const live = {};
+	for (const [stream, state] of Object.entries(remote.live)) if (liveCovered(stream, entries)) live[stream] = state;
+	return {
+		entities: Object.fromEntries([...entries].map(([key, entry]) => [key, {
+			values: entry.values,
+			present: [...entry.present],
+			stale: [...entry.stale],
+			unavailable: [...entry.unavailable],
+			windows: entry.windows,
+			tombstone: entry.tombstone,
+			updatedAt: entry.updatedAt
+		}])),
+		connections: Object.fromEntries(Object.entries(connections).map(([identity, connection]) => [identity, {
+			segments: connection.segments.map((segment) => ({
+				edges: segment.edges.map((edge) => ({
+					key: edge.key,
+					ref: edge.ref
+				})),
+				start: segment.start,
+				end: segment.end
+			})),
+			stale: connection.stale
+		}])),
+		live
+	};
+};
+/**
+* Sets a capture onto a store: its entities, connections and live cursors
+* replace any held under the same keys, and nothing else of the store changes.
+*/
+const restoreRemote = (remote, capture) => ({
+	...remote,
+	entities: {
+		...remote.entities,
+		...Object.fromEntries(Object.entries(capture.entities).map(([key, entry]) => [key, {
+			values: entry.values,
+			present: new Set(entry.present),
+			stale: new Set(entry.stale),
+			unavailable: new Set(entry.unavailable),
+			windows: entry.windows,
+			tombstone: entry.tombstone,
+			updatedAt: entry.updatedAt
+		}]))
+	},
+	connections: {
+		...remote.connections,
+		...Object.fromEntries(Object.entries(capture.connections).map(([identity, connection]) => [identity, {
+			segments: connection.segments.map((segment) => ({
+				edges: segment.edges,
+				start: segment.start,
+				end: segment.end
+			})),
+			stale: connection.stale
+		}]))
+	},
+	live: {
+		...remote.live,
+		...capture.live
+	}
+});
+const encodeCapture = Schema.encodeSync(RemoteCapture);
+const decodeCapture = Schema.decodeUnknownResult(RemoteCapture);
+/**
+* The resume part for a Remote domain, for `SSR.plan`'s `parts`: it sends
+* what the plan's active Surfaces read from this domain's store, and nothing
+* else of it. `id` tells two domains in one application apart.
+*/
+const resumePart = (domain, options = {}) => ({
+	id: options.id ?? "remote",
+	covers: [RemoteRequirements.name, RemoteConnections.name],
+	deferrable: (_key, entry) => typeof entry === "object" && entry !== null && DEFERRABLE in entry,
+	capture: (model, projections) => encodeCapture(captureRemote(domain.store.get(model), projections)),
+	restore: (model, value) => Result.match(decodeCapture(value), {
+		onFailure: (error) => Result.fail(`Remote's state does not decode: ${error.message}`),
+		onSuccess: (capture) => Result.succeed(domain.store.set(model, restoreRemote(domain.store.get(model), capture)))
+	})
+});
+export { DEFERRABLE, RemoteCapture, captureRemote, markAll, restoreRemote, resumePart };
+
+//# sourceMappingURL=resume.js.map

package/dist/resume.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resume.js","names":[],"sources":["../src/resume.ts"],"sourcesContent":["/**\n * What of Remote's state crosses from a server render to the browser.\n *\n * A page rendered a moment ago sends exactly what its active Surfaces read:\n * for each requirement the fields it names, following relations through the\n * refs the store holds, and each connection whole, with its boundaries, so\n * \"load more\" knows where the server stopped. A live subscription's cursor\n * crosses with the entities it covers, so a subscription started in the\n * browser resumes where the server's left off.\n *\n * This is not a `Snapshot`, which is built for a cache that survived a reload\n * and deliberately keeps no cursors. Nothing else of `RemoteModel` crosses:\n * loading marks, failures, the mutation ledger, optimistic layers, gaps and\n * retention start from their initial values in the browser.\n */\nimport { Result, Schema } from 'effect'\nimport type { Focus, Metadata } from 'foldkit-surface'\nimport type { Boundary, Connection, Segment } from './connection.js'\nimport type { LiveState } from './live.js'\nimport type { RemoteModel } from './model.js'\nimport { own, put } from './record.js'\nimport { targetsOf } from './relation.js'\nimport { RemoteConnections, RemoteRequirements, type RelationRequirement } from './requirement.js'\nimport { entityKey, readField, type EntityEntry } from './store.js'\n\nconst CapturedEntry = Schema.Struct({\n  values: Schema.Record(Schema.String, Schema.Unknown),\n  present: Schema.Array(Schema.String),\n  stale: Schema.Array(Schema.String),\n  unavailable: Schema.Array(Schema.String),\n  windows: Schema.Record(Schema.String, Schema.String),\n  tombstone: Schema.Boolean,\n  updatedAt: Schema.Number,\n})\n\nconst CapturedBoundary = Schema.Union([\n  Schema.TaggedStruct('Terminal', {}),\n  Schema.TaggedStruct('Cursor', { cursor: Schema.String }),\n  Schema.TaggedStruct('Unknown', {}),\n])\n\nconst CapturedConnection = Schema.Struct({\n  segments: Schema.Array(\n    Schema.Struct({\n      edges: Schema.Array(\n        Schema.Struct({\n          key: Schema.String,\n          ref: Schema.Struct({ entity: Schema.String, id: Schema.String }),\n        }),\n      ),\n      start: CapturedBoundary,\n      end: CapturedBoundary,\n    }),\n  ),\n  stale: Schema.Boolean,\n})\n\nconst CapturedLive = Schema.Struct({\n  cursor: Schema.Number,\n  boundary: Schema.Record(\n    Schema.String,\n    Schema.Struct({ before: Schema.Number, after: Schema.Number }),\n  ),\n})\n\n/**\n * Marks a Subscription entry Remote built as one that may start late under\n * `foldkit-ssr`'s deferred boot (its decision 10): a read with resumed data\n * plans nothing, a live subscription resumes from the cursor the envelope\n * carries, and retention running late collects late. Non-enumerable, so the\n * runtime's iteration of an entry never sees it.\n */\nexport const DEFERRABLE: unique symbol = Symbol.for('foldkit-remote/deferrable')\n\n/** Marks every entry of a record Remote built, lifted or not. */\nexport const markAll = <Entries extends object>(entries: Entries): Entries => {\n  for (const entry of Object.values(entries)) {\n    Object.defineProperty(entry, DEFERRABLE, { value: true, enumerable: false })\n  }\n  return entries\n}\n\n/** The captured part of a Remote store, as JSON. */\nexport const RemoteCapture = Schema.Struct({\n  entities: Schema.Record(Schema.String, CapturedEntry),\n  connections: Schema.Record(Schema.String, CapturedConnection),\n  live: Schema.Record(Schema.String, CapturedLive),\n})\nexport type RemoteCapture = typeof RemoteCapture.Type\n\ntype MutableEntry = {\n  values: Record<string, unknown>\n  present: Set<string>\n  stale: Set<string>\n  unavailable: Set<string>\n  windows: Record<string, string>\n  tombstone: boolean\n  updatedAt: number\n}\n\n/** What some projections read, from their metadata. */\nconst askedOf = (projections: ReadonlyArray<{ readonly metadata: Metadata }>) => ({\n  requirements: projections.flatMap(projection => RemoteRequirements.get(projection.metadata)),\n  connections: projections.flatMap(projection => RemoteConnections.get(projection.metadata)),\n})\n\n/** Whether every `entity:id:fields` part of a live stream key was captured with those fields. */\nconst liveCovered = (stream: string, entries: ReadonlyMap<string, MutableEntry>): boolean =>\n  stream.split('|').every(part => {\n    const split = part.lastIndexOf(':')\n    const entry = entries.get(part.slice(0, split))\n    const fields = part\n      .slice(split + 1)\n      .split(',')\n      .filter(field => field !== '')\n    return entry !== undefined && fields.every(field => entry.present.has(field))\n  })\n\n/**\n * Captures what some projections read from a store: the fields each\n * requirement names, through its relations; each connection whole, and the\n * fields its selection reads of each item; and each live cursor whose\n * entities were all captured with the fields it follows.\n */\nexport const captureRemote = (\n  remote: RemoteModel,\n  projections: ReadonlyArray<{ readonly metadata: Metadata }>,\n): RemoteCapture => {\n  const store = remote.entities\n  const entries = new Map<string, MutableEntry>()\n  const walked = new Map<string, Set<RelationRequirement>>()\n\n  const walk = (entity: string, id: string, requirement: RelationRequirement): void => {\n    const key = entityKey(entity, id)\n    const seen = walked.get(key) ?? new Set()\n    if (seen.has(requirement)) return\n    seen.add(requirement)\n    walked.set(key, seen)\n    const stored: EntityEntry | undefined = store[key]\n    if (stored === undefined) return\n    const entry = entries.get(key) ?? {\n      values: {},\n      present: new Set<string>(),\n      stale: new Set<string>(),\n      unavailable: new Set<string>(),\n      windows: {},\n      tombstone: stored.tombstone,\n      updatedAt: stored.updatedAt,\n    }\n    entries.set(key, entry)\n    for (const field of requirement.fields) {\n      // A field the server settled without a value is knowledge too: the\n      // browser would otherwise ask for it once more.\n      if (stored.unavailable.has(field)) entry.unavailable.add(field)\n      if (!stored.present.has(field)) continue\n      put(entry.values, field, stored.values[field])\n      entry.present.add(field)\n      if (stored.stale.has(field)) entry.stale.add(field)\n      const window = own(stored.windows, field)\n      if (window !== undefined) put(entry.windows, field, window)\n      const nested = requirement.relations?.[field]\n      if (nested === undefined) continue\n      const value = readField(store, key, field)\n      if (value._tag === 'None') continue\n      for (const ref of targetsOf(value.value, nested)) walk(ref.entity, ref.id, nested)\n    }\n  }\n\n  const asked = askedOf(projections)\n  for (const requirement of asked.requirements) {\n    walk(requirement.entity, requirement.id, requirement)\n  }\n  const connections: Record<string, Connection> = {}\n  for (const { identity, select } of asked.connections) {\n    const connection = remote.connections[identity]\n    if (connection === undefined) continue\n    connections[identity] = connection\n    for (const segment of connection.segments) {\n      for (const edge of segment.edges) walk(edge.ref.entity, edge.ref.id, select)\n    }\n  }\n  const live: Record<string, LiveState> = {}\n  for (const [stream, state] of Object.entries(remote.live)) {\n    if (liveCovered(stream, entries)) live[stream] = state\n  }\n\n  return {\n    entities: Object.fromEntries(\n      [...entries].map(([key, entry]) => [\n        key,\n        {\n          values: entry.values,\n          present: [...entry.present],\n          stale: [...entry.stale],\n          unavailable: [...entry.unavailable],\n          windows: entry.windows,\n          tombstone: entry.tombstone,\n          updatedAt: entry.updatedAt,\n        },\n      ]),\n    ),\n    connections: Object.fromEntries(\n      Object.entries(connections).map(([identity, connection]) => [\n        identity,\n        {\n          segments: connection.segments.map(segment => ({\n            edges: segment.edges.map(edge => ({ key: edge.key, ref: edge.ref })),\n            start: segment.start,\n            end: segment.end,\n          })),\n          stale: connection.stale,\n        },\n      ]),\n    ),\n    live,\n  }\n}\n\n/**\n * Sets a capture onto a store: its entities, connections and live cursors\n * replace any held under the same keys, and nothing else of the store changes.\n */\nexport const restoreRemote = <Store extends RemoteModel>(\n  remote: Store,\n  capture: RemoteCapture,\n): Store => ({\n  ...remote,\n  entities: {\n    ...remote.entities,\n    ...Object.fromEntries(\n      Object.entries(capture.entities).map(([key, entry]) => [\n        key,\n        {\n          values: entry.values,\n          present: new Set(entry.present),\n          stale: new Set(entry.stale),\n          unavailable: new Set(entry.unavailable),\n          windows: entry.windows,\n          tombstone: entry.tombstone,\n          updatedAt: entry.updatedAt,\n        } satisfies EntityEntry,\n      ]),\n    ),\n  },\n  connections: {\n    ...remote.connections,\n    ...Object.fromEntries(\n      Object.entries(capture.connections).map(([identity, connection]) => [\n        identity,\n        {\n          segments: connection.segments.map((segment): Segment => ({\n            edges: segment.edges,\n            start: segment.start as Boundary,\n            end: segment.end as Boundary,\n          })),\n          stale: connection.stale,\n        } satisfies Connection,\n      ]),\n    ),\n  },\n  live: { ...remote.live, ...capture.live },\n})\n\n/**\n * A resume part, in the shape `foldkit-ssr`'s `SSR.plan` takes in `parts`.\n * Declared here structurally, so neither package depends on the other.\n */\nexport interface RemoteResumePart<AppModel> {\n  readonly id: string\n  /** The metadata key names whose reads this part resumes. */\n  readonly covers: ReadonlyArray<string>\n  readonly capture: (\n    model: AppModel,\n    projections: ReadonlyArray<{ readonly metadata: Metadata }>,\n  ) => unknown\n  readonly restore: (model: AppModel, value: unknown) => Result.Result<AppModel, string>\n  /** Whether a Subscription entry is one of this domain's, which may start late. */\n  readonly deferrable: (key: string, entry: unknown) => boolean\n}\n\nconst encodeCapture = Schema.encodeSync(RemoteCapture)\nconst decodeCapture = Schema.decodeUnknownResult(RemoteCapture)\n\n/**\n * The resume part for a Remote domain, for `SSR.plan`'s `parts`: it sends\n * what the plan's active Surfaces read from this domain's store, and nothing\n * else of it. `id` tells two domains in one application apart.\n */\nexport const resumePart = <AppModel, Store extends RemoteModel>(\n  domain: { readonly store: Focus<AppModel, Store> },\n  options: { readonly id?: string | undefined } = {},\n): RemoteResumePart<AppModel> => ({\n  id: options.id ?? 'remote',\n  covers: [RemoteRequirements.name, RemoteConnections.name],\n  deferrable: (_key, entry) => typeof entry === 'object' && entry !== null && DEFERRABLE in entry,\n  capture: (model, projections) =>\n    encodeCapture(captureRemote(domain.store.get(model), projections)),\n  restore: (model, value) =>\n    Result.match(decodeCapture(value), {\n      onFailure: error => Result.fail(`Remote's state does not decode: ${error.message}`),\n      onSuccess: capture =>\n        Result.succeed(domain.store.set(model, restoreRemote(domain.store.get(model), capture))),\n    }),\n})\n"],"mappings":"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"}

package/dist/retain-BfNTvBRb.d.ts

@@ -0,0 +1,48 @@
+import { n as Connection } from "./connection-BRyaJy89.js";
+import { n as EntityKey, r as EntityStore } from "./store-ah2qjcJW.js";
+import { D as MutationState, o as OptimisticState } from "./optimistic-CECsfNGY.js";
+import { a as Requirement, n as RelationRequirement } from "./requirement-D57S2LpH.js";
+/** A connection to keep: its identity, and what a page of it selects of each item, if a projection reads it. */
+interface ConnectionRoot {
+  readonly identity: string;
+  readonly select?: RelationRequirement | undefined;
+}
+interface RetentionRoots {
+  readonly requirements: ReadonlyArray<Requirement>;
+  /** Connections (`QueryRef.identity`) to keep, with their edges' targets and what `select` reaches through them. */
+  readonly connections: ReadonlyArray<ConnectionRoot>;
+}
+interface Retained {
+  readonly entities: EntityStore;
+  readonly connections: Readonly<Record<string, Connection>>;
+  readonly optimistic: OptimisticState;
+}
+/**
+ * The entity keys the roots reach: each root entity, the targets its retained
+ * fields refer to, and recursively the targets a nested relation selects.
+ */
+declare const reachable: (store: EntityStore, roots: RetentionRoots, connections: Readonly<Record<string, Connection>>, optimistic: OptimisticState, pending: ReadonlySet<string>) => ReadonlySet<EntityKey>;
+/**
+ * How many lists, and how many entity reads, stay held after the Surface
+ * showing them goes inactive. Going back to one shows what it held while the
+ * list refetches, rather than reading as if nothing had ever loaded.
+ */
+declare const departedLimit: {
+  readonly connections: 16;
+  readonly requirements: 256;
+};
+/**
+ * The roots retention keeps: the active ones, after the most recently
+ * departed ones `previous` held (oldest first), up to `departedLimit`.
+ */
+declare const recentRoots: (previous: RetentionRoots, active: RetentionRoots) => RetentionRoots;
+/**
+ * Drops every entity the roots do not reach, every connection they do not
+ * name, and every settled overlay on a dropped connection, keeping whatever a
+ * pending request's layer or overlays touch. Pure.
+ */
+declare const gc: (state: Retained & {
+  readonly mutations: MutationState;
+}, roots: RetentionRoots) => Retained;
+export { gc as a, departedLimit as i, Retained as n, reachable as o, RetentionRoots as r, recentRoots as s, ConnectionRoot as t };
+//# sourceMappingURL=retain-BfNTvBRb.d.ts.map

package/dist/retain-BfNTvBRb.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retain-BfNTvBRb.d.ts","names":[],"sources":["../src/retain.ts"],"mappings":";;;;;UAciB;WACN;WACA,SAAS;;UAGH;WACN,cAAc,cAAc;;WAE5B,aAAa,cAAc;;UAGrB;WACN,UAAU;WACV,aAAa,SAAS,eAAe;WACrC,YAAY;;;;;;cAOV,YAAS,OACb,aAAW,OACX,gBAAc,aACR,SAAS,eAAe,cAAY,YACrC,iBAAe,SAClB,wBACR,YAAY;;;;;;cA2DF;WAAkB;WAAiB;;;;;;cAqBnC,cAAW,UAAc,gBAAc,QAAU,mBAAiB;;;;;;cA4BlE,KAAE,OACN;WAAsB,WAAW;GAAe,OAChD,mBACN"}

package/dist/retain.d.ts

@@ -0,0 +1,2 @@
+import { a as gc, i as departedLimit, n as Retained, o as reachable, r as RetentionRoots, s as recentRoots, t as ConnectionRoot } from "./retain-BfNTvBRb.js";
+export { ConnectionRoot, Retained, RetentionRoots, departedLimit, gc, reachable, recentRoots };

package/dist/retain.js

@@ -0,0 +1,107 @@
+import { refsIn } from "./relation.js";
+import { entityKey, readField } from "./store.js";
+// src/retain.ts
+/**
+* The entity keys the roots reach: each root entity, the targets its retained
+* fields refer to, and recursively the targets a nested relation selects.
+*/
+const reachable = (store, roots, connections, optimistic, pending) => {
+	const kept = /* @__PURE__ */ new Set();
+	const rootConnections = new Set(roots.connections.map((root) => root.identity));
+	const walked = /* @__PURE__ */ new Map();
+	const visit = (key, requirement) => {
+		kept.add(key);
+		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) {
+			const value = readField(store, key, field);
+			if (value._tag === "None") continue;
+			const relation = requirement.relations?.[field];
+			for (const ref of refsIn(value.value)) {
+				const target = entityKey(ref.entity, ref.id);
+				if (relation === void 0 || ref.entity !== relation.entity) {
+					kept.add(target);
+					continue;
+				}
+				visit(target, relation);
+			}
+		}
+	};
+	for (const root of roots.requirements) visit(entityKey(root.entity, root.id), root);
+	for (const { identity, select } of roots.connections) for (const segment of connections[identity]?.segments ?? []) for (const edge of segment.edges) {
+		const target = entityKey(edge.ref.entity, edge.ref.id);
+		if (select === void 0 || edge.ref.entity !== select.entity) kept.add(target);
+		else visit(target, select);
+	}
+	for (const layer of optimistic.layers) {
+		if (!pending.has(layer.id)) continue;
+		for (const patch of layer.patches) kept.add(entityKey(patch.entity, patch.id));
+		for (const gone of layer.deletes) kept.add(entityKey(gone.entity, gone.id));
+	}
+	for (const overlay of optimistic.overlays) {
+		if (!pending.has(overlay.id) && !rootConnections.has(overlay.connection)) continue;
+		for (const edge of overlay.edges) kept.add(entityKey(edge.ref.entity, edge.ref.id));
+	}
+	return kept;
+};
+/**
+* How many lists, and how many entity reads, stay held after the Surface
+* showing them goes inactive. Going back to one shows what it held while the
+* list refetches, rather than reading as if nothing had ever loaded.
+*/
+const departedLimit = {
+	connections: 16,
+	requirements: 256
+};
+const requirementKey = (requirement) => JSON.stringify(requirement);
+const connectionKey = (root) => JSON.stringify(root);
+/** The last `limit` of `previous` that `active` does not hold, then all of `active`. */
+const departedThen = (previous, active, key, limit) => {
+	const current = new Set(active.map(key));
+	const departed = previous.filter((value) => !current.has(key(value)));
+	return [...departed.slice(Math.max(0, departed.length - limit)), ...active];
+};
+/**
+* The roots retention keeps: the active ones, after the most recently
+* departed ones `previous` held (oldest first), up to `departedLimit`.
+*/
+const recentRoots = (previous, active) => {
+	const next = {
+		requirements: departedThen(previous.requirements, active.requirements, requirementKey, departedLimit.requirements),
+		connections: departedThen(previous.connections, active.connections, connectionKey, departedLimit.connections)
+	};
+	const same = (a, b, key) => a.length === b.length && a.every((value, i) => key(value) === key(b[i]));
+	return same(previous.requirements, next.requirements, requirementKey) && same(previous.connections, next.connections, connectionKey) ? previous : next;
+};
+/**
+* Drops every entity the roots do not reach, every connection they do not
+* name, and every settled overlay on a dropped connection, keeping whatever a
+* pending request's layer or overlays touch. Pure.
+*/
+const gc = (state, roots) => {
+	const pending = state.mutations.pending;
+	const kept = reachable(state.entities, roots, state.connections, state.optimistic, pending);
+	const entities = keptOf(state.entities, (key) => kept.has(key));
+	const keptConnections = /* @__PURE__ */ new Set([...roots.connections.map((root) => root.identity), ...state.optimistic.overlays.filter((overlay) => pending.has(overlay.id)).map((overlay) => overlay.connection)]);
+	const connections = keptOf(state.connections, (identity) => keptConnections.has(identity));
+	const overlays = state.optimistic.overlays.filter((overlay) => pending.has(overlay.id) || keptConnections.has(overlay.connection));
+	return {
+		entities,
+		connections,
+		optimistic: overlays.length === state.optimistic.overlays.length ? state.optimistic : {
+			layers: state.optimistic.layers,
+			overlays
+		}
+	};
+};
+/** The entries whose key is kept; `record` itself when that is all of them. */
+const keptOf = (record, keep) => {
+	const entries = Object.entries(record);
+	const kept = entries.filter(([key]) => keep(key));
+	return kept.length === entries.length ? record : Object.fromEntries(kept);
+};
+export { departedLimit, gc, reachable, recentRoots };
+
+//# sourceMappingURL=retain.js.map

package/dist/retain.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retain.js","names":[],"sources":["../src/retain.ts"],"sourcesContent":["/**\n * Cache lifetime. Retention roots are the requirements (and connections) the\n * application's active Surfaces observe; `gc` keeps what they reach through\n * the store's refs plus every pending optimistic change, and drops the rest.\n * Roots live outside the Model, so GC arrives as a Message.\n */\nimport type { RelationRequirement, Requirement } from './requirement.js'\nimport { refsIn } from './relation.js'\nimport { entityKey, readField, type EntityKey, type EntityStore } from './store.js'\nimport type { Connection } from './connection.js'\nimport type { OptimisticState } from './optimistic.js'\nimport type { MutationState } from './mutation.js'\n\n/** A connection to keep: its identity, and what a page of it selects of each item, if a projection reads it. */\nexport interface ConnectionRoot {\n  readonly identity: string\n  readonly select?: RelationRequirement | undefined\n}\n\nexport interface RetentionRoots {\n  readonly requirements: ReadonlyArray<Requirement>\n  /** Connections (`QueryRef.identity`) to keep, with their edges' targets and what `select` reaches through them. */\n  readonly connections: ReadonlyArray<ConnectionRoot>\n}\n\nexport interface Retained {\n  readonly entities: EntityStore\n  readonly connections: Readonly<Record<string, Connection>>\n  readonly optimistic: OptimisticState\n}\n\n/**\n * The entity keys the roots reach: each root entity, the targets its retained\n * fields refer to, and recursively the targets a nested relation selects.\n */\nexport const reachable = (\n  store: EntityStore,\n  roots: RetentionRoots,\n  connections: Readonly<Record<string, Connection>>,\n  optimistic: OptimisticState,\n  pending: ReadonlySet<string>,\n): ReadonlySet<EntityKey> => {\n  const kept = new Set<EntityKey>()\n  const rootConnections = new Set(roots.connections.map(root => root.identity))\n  // A target is walked once per relation spec that reaches it: two specs may\n  // select different nested relations of the same entity, and a spec tree is\n  // finite, so this terminates on cyclic data too.\n  const walked = new Map<EntityKey, Set<Omit<Requirement, 'id'>>>()\n  const visit = (key: EntityKey, requirement: Omit<Requirement, 'id'>): void => {\n    kept.add(key)\n    const seen = walked.get(key) ?? new Set()\n    if (seen.has(requirement)) return\n    seen.add(requirement)\n    walked.set(key, seen)\n    for (const field of requirement.fields) {\n      const value = readField(store, key, field)\n      if (value._tag === 'None') continue\n      const relation = requirement.relations?.[field]\n      for (const ref of refsIn(value.value)) {\n        const target = entityKey(ref.entity, ref.id)\n        if (relation === undefined || ref.entity !== relation.entity) {\n          kept.add(target)\n          continue\n        }\n        visit(target, relation)\n      }\n    }\n  }\n  for (const root of roots.requirements) visit(entityKey(root.entity, root.id), root)\n  // A connection root keeps its edges' targets, and what a page's `select`\n  // reaches through them (an item's owner, say), so the page stays readable.\n  for (const { identity, select } of roots.connections) {\n    for (const segment of connections[identity]?.segments ?? []) {\n      for (const edge of segment.edges) {\n        const target = entityKey(edge.ref.entity, edge.ref.id)\n        if (select === undefined || edge.ref.entity !== select.entity) kept.add(target)\n        else visit(target, select)\n      }\n    }\n  }\n  // A pending request's changes are kept whole; a settled overlay (a live or\n  // confirmed insert) is kept only with a retained connection, below.\n  for (const layer of optimistic.layers) {\n    if (!pending.has(layer.id)) continue\n    for (const patch of layer.patches) kept.add(entityKey(patch.entity, patch.id))\n    // A failure brings the row back, as it was.\n    for (const gone of layer.deletes) kept.add(entityKey(gone.entity, gone.id))\n  }\n  for (const overlay of optimistic.overlays) {\n    if (!pending.has(overlay.id) && !rootConnections.has(overlay.connection)) continue\n    for (const edge of overlay.edges) kept.add(entityKey(edge.ref.entity, edge.ref.id))\n  }\n  return kept\n}\n\n/**\n * How many lists, and how many entity reads, stay held after the Surface\n * showing them goes inactive. Going back to one shows what it held while the\n * list refetches, rather than reading as if nothing had ever loaded.\n */\nexport const departedLimit = { connections: 16, requirements: 256 } as const\n\nconst requirementKey = (requirement: Requirement): string => JSON.stringify(requirement)\nconst connectionKey = (root: ConnectionRoot): string => JSON.stringify(root)\n\n/** The last `limit` of `previous` that `active` does not hold, then all of `active`. */\nconst departedThen = <A>(\n  previous: ReadonlyArray<A>,\n  active: ReadonlyArray<A>,\n  key: (value: A) => string,\n  limit: number,\n): ReadonlyArray<A> => {\n  const current = new Set(active.map(key))\n  const departed = previous.filter(value => !current.has(key(value)))\n  return [...departed.slice(Math.max(0, departed.length - limit)), ...active]\n}\n\n/**\n * The roots retention keeps: the active ones, after the most recently\n * departed ones `previous` held (oldest first), up to `departedLimit`.\n */\nexport const recentRoots = (previous: RetentionRoots, active: RetentionRoots): RetentionRoots => {\n  const next = {\n    requirements: departedThen(\n      previous.requirements,\n      active.requirements,\n      requirementKey,\n      departedLimit.requirements,\n    ),\n    connections: departedThen(\n      previous.connections,\n      active.connections,\n      connectionKey,\n      departedLimit.connections,\n    ),\n  }\n  const same = <A>(a: ReadonlyArray<A>, b: ReadonlyArray<A>, key: (value: A) => string) =>\n    a.length === b.length && a.every((value, i) => key(value) === key(b[i]!))\n  return same(previous.requirements, next.requirements, requirementKey) &&\n    same(previous.connections, next.connections, connectionKey)\n    ? previous\n    : next\n}\n\n/**\n * Drops every entity the roots do not reach, every connection they do not\n * name, and every settled overlay on a dropped connection, keeping whatever a\n * pending request's layer or overlays touch. Pure.\n */\nexport const gc = (\n  state: Retained & { readonly mutations: MutationState },\n  roots: RetentionRoots,\n): Retained => {\n  const pending = state.mutations.pending\n  const kept = reachable(state.entities, roots, state.connections, state.optimistic, pending)\n  const entities = keptOf(state.entities, key => kept.has(key))\n  const keptConnections = new Set([\n    ...roots.connections.map(root => root.identity),\n    ...state.optimistic.overlays\n      .filter(overlay => pending.has(overlay.id))\n      .map(overlay => overlay.connection),\n  ])\n  const connections = keptOf(state.connections, identity => keptConnections.has(identity))\n  const overlays = state.optimistic.overlays.filter(\n    overlay => pending.has(overlay.id) || keptConnections.has(overlay.connection),\n  )\n  const optimistic: OptimisticState =\n    overlays.length === state.optimistic.overlays.length\n      ? state.optimistic\n      : { layers: state.optimistic.layers, overlays }\n  return { entities, connections, optimistic }\n}\n\n/** The entries whose key is kept; `record` itself when that is all of them. */\nconst keptOf = <T>(\n  record: Readonly<Record<string, T>>,\n  keep: (key: string) => boolean,\n): Readonly<Record<string, T>> => {\n  const entries = Object.entries(record)\n  const kept = entries.filter(([key]) => keep(key))\n  return kept.length === entries.length ? record : Object.fromEntries(kept)\n}\n"],"mappings":"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"}

package/dist/selection.d.ts

@@ -0,0 +1,2 @@
+import { _ as relationOf, d as Selection, f as SelectionOf, g as pageSchema, h as assemble, m as SelectionValueOf, p as SelectionValue, u as Page, v as unavailableOf } from "./entity-CgsG5Uel.js";
+export { Page, Selection, SelectionOf, SelectionValue, SelectionValueOf, assemble, pageSchema, relationOf, unavailableOf };

package/dist/selection.js

@@ -0,0 +1 @@
+export { n as Selection, r as assemble, i as pageSchema, a as relationOf, o as unavailableOf } from "./entity-DuDxaa3n.js";

package/dist/shown.d.ts

@@ -0,0 +1,20 @@
+import { a as OptimisticOperation, j as PendingPatch } from "./optimistic-CECsfNGY.js";
+import { a as Requirement, n as RelationRequirement, t as ConnectionRequirement } from "./requirement-D57S2LpH.js";
+/** A patch is the one optimistic operation with no tag. */
+export declare const isPatch: (operation: OptimisticOperation) => operation is PendingPatch;
+/** Every field a pending patch shows: those it sets, adds to, and computes. */
+export declare const patchedFields: (patch: PendingPatch) => ReadonlyArray<string>;
+/**
+ * The union, per entity, of every slice the reads ask: each requirement's,
+ * each connection's item `select`, and every relation's target slice under
+ * its own entity too, so a row the answer names is read the way any read
+ * reaches it. Every field the write's own patches show is added: the
+ * prediction is released when the answer lands, so a field it moved that no
+ * Surface reads now (a count on a page left behind) would otherwise read the
+ * value from before the write (#265).
+ */
+export declare const shownOf: (asked: {
+  readonly requirements: ReadonlyArray<Requirement>;
+  readonly connections: ReadonlyArray<ConnectionRequirement>;
+}, predicted: ReadonlyArray<OptimisticOperation>) => ReadonlyArray<RelationRequirement>;
+//# sourceMappingURL=shown.d.ts.map

package/dist/shown.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shown.d.ts","names":[],"sources":["../src/shown.ts"],"mappings":";;;qBAWa,UAAO,WAAe,wBAAsB,aAAa;;qBAIzD,gBAAa,OAAW,iBAAe;;;;;;;;;;qBAevC,UAAO;WAEP,cAAc,cAAc;WAC5B,aAAa,cAAc;GACrC,WACU,cAAc,yBACxB,cAAc"}

package/dist/shown.js

@@ -0,0 +1,40 @@
+import { Requirement } from "./requirement.js";
+// src/shown.ts
+/** A patch is the one optimistic operation with no tag. */
+const isPatch = (operation) => !("_tag" in operation);
+/** Every field a pending patch shows: those it sets, adds to, and computes. */
+const patchedFields = (patch) => [
+	...Object.keys(patch.values),
+	...Object.keys(patch.adds ?? {}),
+	...Object.keys(patch.computes ?? {})
+];
+/**
+* The union, per entity, of every slice the reads ask: each requirement's,
+* each connection's item `select`, and every relation's target slice under
+* its own entity too, so a row the answer names is read the way any read
+* reaches it. Every field the write's own patches show is added: the
+* prediction is released when the answer lands, so a field it moved that no
+* Surface reads now (a count on a page left behind) would otherwise read the
+* value from before the write (#265).
+*/
+const shownOf = (asked, predicted) => {
+	const byEntity = /* @__PURE__ */ new Map();
+	const add = (slice) => {
+		const current = byEntity.get(slice.entity) ?? {
+			entity: slice.entity,
+			fields: []
+		};
+		byEntity.set(slice.entity, Requirement.mergeRelation(current, slice));
+		for (const relation of Object.values(slice.relations ?? {})) add(relation);
+	};
+	for (const requirement of asked.requirements) add(requirement);
+	for (const connection of asked.connections) add(connection.select);
+	for (const patch of predicted.filter(isPatch)) add({
+		entity: patch.entity,
+		fields: [...patchedFields(patch)]
+	});
+	return [...byEntity.values()];
+};
+export { isPatch, patchedFields, shownOf };
+
+//# sourceMappingURL=shown.js.map

package/dist/shown.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shown.js","names":[],"sources":["../src/shown.ts"],"sourcesContent":["/**\n * What a client shows of each entity, sent with a mutation so its answer\n * carries those fields (#245). Per entity rather than per row: the server\n * knows which rows a write changed, the client what it reads of a row of\n * each kind.\n */\nimport type { PendingPatch } from './mutation.js'\nimport type { OptimisticOperation } from './optimistic.js'\nimport { Requirement, type ConnectionRequirement, type RelationRequirement } from './requirement.js'\n\n/** A patch is the one optimistic operation with no tag. */\nexport const isPatch = (operation: OptimisticOperation): operation is PendingPatch =>\n  !('_tag' in operation)\n\n/** Every field a pending patch shows: those it sets, adds to, and computes. */\nexport const patchedFields = (patch: PendingPatch): ReadonlyArray<string> => [\n  ...Object.keys(patch.values),\n  ...Object.keys(patch.adds ?? {}),\n  ...Object.keys(patch.computes ?? {}),\n]\n\n/**\n * The union, per entity, of every slice the reads ask: each requirement's,\n * each connection's item `select`, and every relation's target slice under\n * its own entity too, so a row the answer names is read the way any read\n * reaches it. Every field the write's own patches show is added: the\n * prediction is released when the answer lands, so a field it moved that no\n * Surface reads now (a count on a page left behind) would otherwise read the\n * value from before the write (#265).\n */\nexport const shownOf = (\n  asked: {\n    readonly requirements: ReadonlyArray<Requirement>\n    readonly connections: ReadonlyArray<ConnectionRequirement>\n  },\n  predicted: ReadonlyArray<OptimisticOperation>,\n): ReadonlyArray<RelationRequirement> => {\n  const byEntity = new Map<string, RelationRequirement>()\n  const add = (slice: RelationRequirement): void => {\n    // A merge keeps a slice's own keys only, so a requirement's `id` and `live` stay behind.\n    const current = byEntity.get(slice.entity) ?? { entity: slice.entity, fields: [] }\n    byEntity.set(slice.entity, Requirement.mergeRelation(current, slice))\n    for (const relation of Object.values(slice.relations ?? {})) add(relation)\n  }\n  for (const requirement of asked.requirements) add(requirement)\n  for (const connection of asked.connections) add(connection.select)\n  for (const patch of predicted.filter(isPatch))\n    add({ entity: patch.entity, fields: [...patchedFields(patch)] })\n  return [...byEntity.values()]\n}\n"],"mappings":";;;AAWA,MAAa,WAAW,cACtB,EAAE,UAAU;;AAGd,MAAa,iBAAiB,UAA+C;CAC3E,GAAG,OAAO,KAAK,MAAM,MAAM;CAC3B,GAAG,OAAO,KAAK,MAAM,QAAQ,CAAC,CAAC;CAC/B,GAAG,OAAO,KAAK,MAAM,YAAY,CAAC,CAAC;AACrC;;;;;;;;;;AAWA,MAAa,WACX,OAIA,cACuC;CACvC,MAAM,2BAAW,IAAI,IAAiC;CACtD,MAAM,OAAO,UAAqC;EAEhD,MAAM,UAAU,SAAS,IAAI,MAAM,MAAM,KAAK;GAAE,QAAQ,MAAM;GAAQ,QAAQ,CAAC;EAAE;EACjF,SAAS,IAAI,MAAM,QAAQ,YAAY,cAAc,SAAS,KAAK,CAAC;EACpE,KAAK,MAAM,YAAY,OAAO,OAAO,MAAM,aAAa,CAAC,CAAC,GAAG,IAAI,QAAQ;CAC3E;CACA,KAAK,MAAM,eAAe,MAAM,cAAc,IAAI,WAAW;CAC7D,KAAK,MAAM,cAAc,MAAM,aAAa,IAAI,WAAW,MAAM;CACjE,KAAK,MAAM,SAAS,UAAU,OAAO,OAAO,GAC1C,IAAI;EAAE,QAAQ,MAAM;EAAQ,QAAQ,CAAC,GAAG,cAAc,KAAK,CAAC;CAAE,CAAC;CACjE,OAAO,CAAC,GAAG,SAAS,OAAO,CAAC;AAC9B"}