foldkit-remote 0.20.0 → 0.22.0

package/dist/answerGaps.d.ts

@@ -0,0 +1,16 @@
+import { i as PredictionMismatch } from "./diagnostics-DHhVYflV.js";
+import { r as EntityStore } from "./store-ah2qjcJW.js";
+import { o as OptimisticState } from "./optimistic-CECsfNGY.js";
+import { a as Requirement } from "./requirement-D57S2LpH.js";
+import { Option } from "effect";
+/**
+ * Each row the request showed (its layer's patches, its insert overlays and
+ * the ones its answer confirmed) with the fields shown on it: those the layer
+ * patched and those `read` asks of it, minus what the store now holds.
+ *
+ * `before` is the optimistic state the answer settled, `after` the one it left;
+ * `visible` is the store as reads see it after; `read` is what the active
+ * Surfaces ask of it after, as planned.
+ */
+export declare const answerGaps: (requestId: string, mutation: Option.Option<string>, before: OptimisticState, after: OptimisticState, visible: EntityStore, read: ReadonlyArray<Requirement>) => ReadonlyArray<PredictionMismatch>;
+//# sourceMappingURL=answerGaps.d.ts.map

package/dist/answerGaps.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"answerGaps.d.ts","names":[],"sources":["../src/answerGaps.ts"],"mappings":";;;;;;;;;;;;;;qBAuBa,aAAU,mBACJ,UACP,OAAO,gBAAc,QACvB,iBAAe,OAChB,iBAAe,SACb,aAAW,MACd,cAAc,iBACnB,cAAc"}

package/dist/answerGaps.js

@@ -0,0 +1,60 @@
+import { PredictionPart, predictionMismatch } from "./diagnostics.js";
+import { patchedFields } from "./shown.js";
+import { entityKey } from "./store.js";
+// src/answerGaps.ts
+/**
+* Each row the request showed (its layer's patches, its insert overlays and
+* the ones its answer confirmed) with the fields shown on it: those the layer
+* patched and those `read` asks of it, minus what the store now holds.
+*
+* `before` is the optimistic state the answer settled, `after` the one it left;
+* `visible` is the store as reads see it after; `read` is what the active
+* Surfaces ask of it after, as planned.
+*/
+const answerGaps = (requestId, mutation, before, after, visible, read) => {
+	const shown = /* @__PURE__ */ new Map();
+	const show = (entity, id, fields) => {
+		const key = entityKey(entity, id);
+		const row = shown.get(key) ?? {
+			entity,
+			id,
+			fields: /* @__PURE__ */ new Set()
+		};
+		for (const field of fields) row.fields.add(field);
+		shown.set(key, row);
+	};
+	for (const layer of before.layers) {
+		if (layer.id !== requestId) continue;
+		for (const patch of layer.patches) show(patch.entity, patch.id, patchedFields(patch));
+	}
+	const confirmed = `confirmed:${requestId}`;
+	for (const overlay of [...before.overlays, ...after.overlays]) {
+		if (overlay.position === "remove") continue;
+		if (overlay.id !== requestId && overlay.id !== confirmed) continue;
+		for (const edge of overlay.edges) show(edge.ref.entity, edge.ref.id, []);
+	}
+	const asked = /* @__PURE__ */ new Set();
+	for (const requirement of read) {
+		const key = entityKey(requirement.entity, requirement.id);
+		if (!shown.has(key)) continue;
+		asked.add(key);
+		show(requirement.entity, requirement.id, requirement.fields);
+	}
+	const gaps = [];
+	for (const [key, row] of shown) {
+		const entry = visible[key];
+		if (entry === void 0 ? !asked.has(key) : entry.tombstone) continue;
+		const fields = [...row.fields].filter((field) => entry === void 0 || !(entry.present.has(field) || entry.unavailable.has(field)));
+		if (fields.length > 0) gaps.push(predictionMismatch(PredictionPart.Gap({
+			requestId,
+			mutation,
+			entity: row.entity,
+			id: row.id,
+			fields
+		})));
+	}
+	return gaps;
+};
+export { answerGaps };
+
+//# sourceMappingURL=answerGaps.js.map

package/dist/answerGaps.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"answerGaps.js","names":[],"sources":["../src/answerGaps.ts"],"sourcesContent":["/**\n * `verifyPredictions`' `Gap`: the fields a mutation's answer left out that the client\n * showed while it was pending. Releasing the layer leaves such a field to be\n * read again, so the row reads `Loading` for a frame, or nothing at all where\n * no Selection reads it. A check for development and tests, which changes\n * nothing it is given.\n */\nimport type { Option } from 'effect'\nimport { PredictionPart, predictionMismatch, type PredictionMismatch } from './diagnostics.js'\nimport type { OptimisticState } from './optimistic.js'\nimport { patchedFields } from './shown.js'\nimport type { Requirement } from './requirement.js'\nimport { entityKey, type EntityStore } from './store.js'\n\n/**\n * Each row the request showed (its layer's patches, its insert overlays and\n * the ones its answer confirmed) with the fields shown on it: those the layer\n * patched and those `read` asks of it, minus what the store now holds.\n *\n * `before` is the optimistic state the answer settled, `after` the one it left;\n * `visible` is the store as reads see it after; `read` is what the active\n * Surfaces ask of it after, as planned.\n */\nexport const answerGaps = (\n  requestId: string,\n  mutation: Option.Option<string>,\n  before: OptimisticState,\n  after: OptimisticState,\n  visible: EntityStore,\n  read: ReadonlyArray<Requirement>,\n): ReadonlyArray<PredictionMismatch> => {\n  const shown = new Map<\n    string,\n    { readonly entity: string; readonly id: string; readonly fields: Set<string> }\n  >()\n  const show = (entity: string, id: string, fields: ReadonlyArray<string>) => {\n    const key = entityKey(entity, id)\n    const row = shown.get(key) ?? { entity, id, fields: new Set<string>() }\n    for (const field of fields) row.fields.add(field)\n    shown.set(key, row)\n  }\n  for (const layer of before.layers) {\n    if (layer.id !== requestId) continue\n    for (const patch of layer.patches) show(patch.entity, patch.id, patchedFields(patch))\n  }\n  const confirmed = `confirmed:${requestId}`\n  for (const overlay of [...before.overlays, ...after.overlays]) {\n    if (overlay.position === 'remove') continue\n    if (overlay.id !== requestId && overlay.id !== confirmed) continue\n    for (const edge of overlay.edges) show(edge.ref.entity, edge.ref.id, [])\n  }\n  const asked = new Set<string>()\n  for (const requirement of read) {\n    const key = entityKey(requirement.entity, requirement.id)\n    if (!shown.has(key)) continue\n    asked.add(key)\n    show(requirement.entity, requirement.id, requirement.fields)\n  }\n  const gaps: Array<PredictionMismatch> = []\n  for (const [key, row] of shown) {\n    const entry = visible[key]\n    // A row nothing holds or reads any longer is not shown: a temporary id\n    // the answer replaced with the server's.\n    if (entry === undefined ? !asked.has(key) : entry.tombstone) continue\n    const fields = [...row.fields].filter(\n      field => entry === undefined || !(entry.present.has(field) || entry.unavailable.has(field)),\n    )\n    if (fields.length > 0)\n      gaps.push(\n        predictionMismatch(\n          PredictionPart.Gap({ requestId, mutation, entity: row.entity, id: row.id, fields }),\n        ),\n      )\n  }\n  return gaps\n}\n"],"mappings":";;;;;;;;;;;;;AAuBA,MAAa,cACX,WACA,UACA,QACA,OACA,SACA,SACsC;CACtC,MAAM,wBAAQ,IAAI,IAGhB;CACF,MAAM,QAAQ,QAAgB,IAAY,WAAkC;EAC1E,MAAM,MAAM,UAAU,QAAQ,EAAE;EAChC,MAAM,MAAM,MAAM,IAAI,GAAG,KAAK;GAAE;GAAQ;GAAI,wBAAQ,IAAI,IAAY;EAAE;EACtE,KAAK,MAAM,SAAS,QAAQ,IAAI,OAAO,IAAI,KAAK;EAChD,MAAM,IAAI,KAAK,GAAG;CACpB;CACA,KAAK,MAAM,SAAS,OAAO,QAAQ;EACjC,IAAI,MAAM,OAAO,WAAW;EAC5B,KAAK,MAAM,SAAS,MAAM,SAAS,KAAK,MAAM,QAAQ,MAAM,IAAI,cAAc,KAAK,CAAC;CACtF;CACA,MAAM,YAAY,aAAa;CAC/B,KAAK,MAAM,WAAW,CAAC,GAAG,OAAO,UAAU,GAAG,MAAM,QAAQ,GAAG;EAC7D,IAAI,QAAQ,aAAa,UAAU;EACnC,IAAI,QAAQ,OAAO,aAAa,QAAQ,OAAO,WAAW;EAC1D,KAAK,MAAM,QAAQ,QAAQ,OAAO,KAAK,KAAK,IAAI,QAAQ,KAAK,IAAI,IAAI,CAAC,CAAC;CACzE;CACA,MAAM,wBAAQ,IAAI,IAAY;CAC9B,KAAK,MAAM,eAAe,MAAM;EAC9B,MAAM,MAAM,UAAU,YAAY,QAAQ,YAAY,EAAE;EACxD,IAAI,CAAC,MAAM,IAAI,GAAG,GAAG;EACrB,MAAM,IAAI,GAAG;EACb,KAAK,YAAY,QAAQ,YAAY,IAAI,YAAY,MAAM;CAC7D;CACA,MAAM,OAAkC,CAAC;CACzC,KAAK,MAAM,CAAC,KAAK,QAAQ,OAAO;EAC9B,MAAM,QAAQ,QAAQ;EAGtB,IAAI,UAAU,KAAA,IAAY,CAAC,MAAM,IAAI,GAAG,IAAI,MAAM,WAAW;EAC7D,MAAM,SAAS,CAAC,GAAG,IAAI,MAAM,CAAC,CAAC,QAC7B,UAAS,UAAU,KAAA,KAAa,EAAE,MAAM,QAAQ,IAAI,KAAK,KAAK,MAAM,YAAY,IAAI,KAAK,EAC3F;EACA,IAAI,OAAO,SAAS,GAClB,KAAK,KACH,mBACE,eAAe,IAAI;GAAE;GAAW;GAAU,QAAQ,IAAI;GAAQ,IAAI,IAAI;GAAI;EAAO,CAAC,CACpF,CACF;CACJ;CACA,OAAO;AACT"}

package/dist/client-B055kQuP.d.ts

@@ -0,0 +1,110 @@
+import { i as RemoteError } from "./remoteData-mK1suYi1.js";
+import { E as MutationDescriptor, t as ConnectionChange } from "./optimistic-CECsfNGY.js";
+import { a as Requirement, n as RelationRequirement } from "./requirement-D57S2LpH.js";
+import { A as RemoteMutationError, C as ReadBatch, D as RemoteForbidden, F as RemoteUnauthenticated, I as RemoteUnreachable, M as RemoteQueryError, N as RemoteReadError, O as RemoteLiveError, f as MutationRequest, i as LiveChange, j as RemoteProtocolError, k as RemoteLiveRefused, n as ConnectionChangeSchema, o as LiveRequirement, p as MutationResult, v as QueryRequest, w as ReadBatchResult, y as QueryResult } from "./wire-DthPcTM6.js";
+import { n as CoalesceOptions } from "./coalesce-CLAr92Nk.js";
+import { a as LiveEvent, i as LiveCursor } from "./live-BpTzlCnY.js";
+import { Context, Effect, Layer, Schema, Stream } from "effect";
+declare const RemoteClient_base: Context.ServiceClass<RemoteClient, "foldkit-remote/RemoteClient", {
+  readonly read: (batch: Schema.Schema.Type<typeof ReadBatch>) => Effect.Effect<Schema.Schema.Type<typeof ReadBatchResult>, RemoteReadError | RemoteProtocolError | RemoteUnauthenticated>;
+  readonly query: (request: Schema.Schema.Type<typeof QueryRequest>) => Effect.Effect<Schema.Schema.Type<typeof QueryResult>, RemoteQueryError | RemoteUnauthenticated>;
+  readonly mutate: (request: Schema.Schema.Type<typeof MutationRequest>) => Effect.Effect<Schema.Schema.Type<typeof MutationResult>, RemoteMutationError | RemoteForbidden | RemoteUnauthenticated | RemoteUnreachable>;
+  readonly live: (request: {
+    readonly requirements: ReadonlyArray<Requirement>;
+    /** The lists read live, each as its read sends it. */
+    readonly queries: ReadonlyArray<Schema.Schema.Type<typeof QueryRequest>>;
+    readonly after: LiveCursor;
+  }) => Stream.Stream<LiveEvent, RemoteLiveError | RemoteLiveRefused | RemoteProtocolError | RemoteUnauthenticated>;
+}>;
+/**
+ * The transport boundary. `foldkit-remote` never talks to a transport directly;
+ * it depends on this Effect service, which a later phase wires to Effect RPC.
+ */
+declare class RemoteClient extends RemoteClient_base {}
+/**
+ * The methods an Effect RPC client for `RemoteRpc` exposes. `R` is the
+ * environment a handler needs; it defaults to `never`, which is what a real
+ * transport client satisfies. `RemoteServer.handlers` returns this type with its
+ * own `R`, so the two sides cannot drift apart.
+ *
+ * `TransportError` is what the transport itself may fail with on top of the
+ * declared errors: `RpcClientError` for the client `RpcClient.make` builds,
+ * `never` for in-process handlers.
+ */
+interface RemoteRpcClient<R = never, TransportError = never> {
+  readonly FoldkitRemoteRead: (payload: Schema.Schema.Type<typeof ReadBatch>) => Effect.Effect<Schema.Schema.Type<typeof ReadBatchResult>, RemoteReadError | RemoteProtocolError | RemoteUnauthenticated | TransportError, R>;
+  readonly FoldkitRemoteQuery: (payload: Schema.Schema.Type<typeof QueryRequest>) => Effect.Effect<Schema.Schema.Type<typeof QueryResult>, RemoteQueryError | RemoteUnauthenticated | TransportError, R>;
+  readonly FoldkitRemoteMutate: (payload: Schema.Schema.Type<typeof MutationRequest>) => Effect.Effect<Schema.Schema.Type<typeof MutationResult>, RemoteMutationError | RemoteForbidden | RemoteUnauthenticated | TransportError, R>;
+  readonly FoldkitRemoteLive: (payload: Schema.Schema.Type<typeof LiveRequirement>) => Stream.Stream<Schema.Schema.Type<typeof LiveChange>, RemoteLiveError | RemoteLiveRefused | RemoteProtocolError | RemoteUnauthenticated | TransportError, R>;
+}
+/**
+ * A client over a JSON transport (`Remote.json`, `Remote.http`): a mutation
+ * nothing answered fails `RemoteUnreachable`, its only error of its own.
+ */
+type RemoteJsonClient = RemoteRpcClient<never, RemoteUnreachable>;
+/** Reconstructs the client's `ConnectionChange` from the wire's flattened edge. */
+declare const connectionChangeOf: (change: Schema.Schema.Type<typeof ConnectionChangeSchema>) => ConnectionChange;
+/** Reconstructs the client's `LiveEvent` from the wire's flattened `LiveChange`. */
+declare const liveEventOf: (change: Schema.Schema.Type<typeof LiveChange>) => LiveEvent;
+declare const remoteError: (error: {
+  readonly _tag: string;
+  readonly message: string;
+  readonly refusal?: unknown;
+  readonly reason?: string | undefined;
+}) => RemoteError;
+declare const coalescedLayer: <E, R>(layer: Layer.Layer<RemoteClient, E, R>, options?: CoalesceOptions) => Layer.Layer<RemoteClient, E, R>;
+/**
+ * A new operation's identity: random, so unique across clients and reloads.
+ * `randomUUID` exists only in a secure context, so a page served over plain
+ * HTTP draws 128 random bits from `getRandomValues`, which exists in all.
+ */
+declare const mintOperation: () => string;
+/**
+ * `Remote.mutate` as a standalone effect, so `Remote.mutateInto` can reuse it
+ * without the object literal referencing itself.
+ */
+declare const mutateRemote: <Name extends string, Input, Output>(mutation: MutationDescriptor<Name, Input, Output, unknown>, input: Input, requestId: string, options?: {
+  readonly keys?: ReadonlyArray<string> | undefined;
+  /**
+   * The operation's identity across clients, the same on each retry of it:
+   * minted here when not given, so a retry must pass the one first sent.
+   */
+  readonly operation?: string | undefined;
+  /** What the client shows of each entity's rows, for the answer to carry (`Data.mutate` sends it). */
+  readonly shown?: ReadonlyArray<RelationRequirement> | undefined;
+  /** When the reader acted, as `Data.mutate` predicted it: sent for the server to take. */
+  readonly now?: number | undefined;
+} | undefined) => Effect.Effect<{
+  output: Output;
+  entities: readonly {
+    readonly entity: string;
+    readonly id: string;
+    readonly values: {
+      readonly [x: string]: unknown;
+    };
+  }[];
+  connections: ConnectionChange[];
+  deleted: readonly {
+    readonly entity: string;
+    readonly id: string;
+  }[];
+  read: {
+    readonly requests: readonly Requirement[];
+    readonly result: {
+      readonly entities: readonly {
+        readonly entity: string;
+        readonly id: string;
+        readonly values: {
+          readonly [x: string]: unknown;
+        };
+      }[];
+      readonly settled: readonly {
+        readonly entity: string;
+        readonly id: string;
+        readonly fields: readonly string[];
+      }[];
+    };
+  } | undefined;
+}, RemoteForbidden | RemoteMutationError | RemoteUnauthenticated | RemoteUnreachable, RemoteClient>;
+export { connectionChangeOf as a, mutateRemote as c, coalescedLayer as i, remoteError as l, RemoteJsonClient as n, liveEventOf as o, RemoteRpcClient as r, mintOperation as s, RemoteClient as t };
+//# sourceMappingURL=client-B055kQuP.d.ts.map

package/dist/client-B055kQuP.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-B055kQuP.d.ts","names":[],"sources":["../src/client.ts"],"mappings":";;;;;;;;WAuCmB,OACb,OAAO,OAAO,OAAO,YAAY,eAC9B,OAAO,OACV,OAAO,OAAO,YAAY,kBAC1B,kBAAkB,sBAAsB;WAE1B,QACd,SAAS,OAAO,OAAO,YAAY,kBAChC,OAAO,OACV,OAAO,OAAO,YAAY,cAC1B,mBAAmB;WAEJ,SACf,SAAS,OAAO,OAAO,YAAY,qBAChC,OAAO,OACV,OAAO,OAAO,YAAY,iBAC1B,sBAAsB,kBAAkB,wBAAwB;WAEnD,OAAC;aACL,cAAc,cAAc;;aAE5B,SAAS,cAAc,OAAO,OAAO,YAAY;aACjD,OAAO;QACZ,OAAO,OACX,WACA,kBAAkB,oBAAoB,sBAAsB;;;;;;cA5BrD,qBAAqB;;;;;;;;;;;UA2CjB,gBAAgB,WAAW;WACjC,oBACP,SAAS,OAAO,OAAO,YAAY,eAChC,OAAO,OACV,OAAO,OAAO,YAAY,kBAC1B,kBAAkB,sBAAsB,wBAAwB,gBAChE;WAEO,qBACP,SAAS,OAAO,OAAO,YAAY,kBAChC,OAAO,OACV,OAAO,OAAO,YAAY,cAC1B,mBAAmB,wBAAwB,gBAC3C;WAEO,sBACP,SAAS,OAAO,OAAO,YAAY,qBAChC,OAAO,OACV,OAAO,OAAO,YAAY,iBAC1B,sBAAsB,kBAAkB,wBAAwB,gBAChE;WAEO,oBACP,SAAS,OAAO,OAAO,YAAY,qBAChC,OAAO,OACV,OAAO,OAAO,YAAY,aACxB,kBACA,oBACA,sBACA,wBACA,gBACF;;;;;;KAQQ,mBAAmB,uBAAuB;;cAGzC,qBAAkB,QACrB,OAAO,OAAO,YAAY,4BACjC;;cAQU,cAAW,QAAY,OAAO,OAAO,YAAY,gBAAc;cAoC/D,cAAW;WACb;WACA;WACA;WACA;MACP;cAOS,iBAAkB,GAAG,GAAC,OAC1B,MAAM,MAAM,cAAc,GAAG,IAAE,UAC7B,oBACR,MAAM,MAAM,cAAc,GAAG;;;;;;cAgBnB;;;;;cAWA,eACX,qBACA,OACA,QAAM,UAAA,mBAAA,MAAA,OAAA,kBAAA,OAAA,OAAA,mBAAA;WAMY,OAAA;;;;;WAKK;;WAEJ,QAAA,cAAc;;WAEhB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCjB,kBAAA,sBAAA,wBAAA,mBAAA"}

package/dist/client.d.ts

@@ -0,0 +1,2 @@
+import { a as connectionChangeOf, c as mutateRemote, i as coalescedLayer, l as remoteError, n as RemoteJsonClient, o as liveEventOf, r as RemoteRpcClient, s as mintOperation, t as RemoteClient } from "./client-B055kQuP.js";
+export { RemoteClient, RemoteJsonClient, RemoteRpcClient, coalescedLayer, connectionChangeOf, liveEventOf, mintOperation, mutateRemote, remoteError };

package/dist/client.js

@@ -0,0 +1,142 @@
+import { RemoteMutationError } from "./wire.js";
+import { coalesceQueries, coalesceReads } from "./coalesce.js";
+import { Context, Effect, Layer, Schema } from "effect";
+// src/client.ts
+/**
+* The transport seam: the `RemoteClient` Effect service, the RPC client it is
+* built from, the wire-to-client reconstructions, and the mutation call.
+*/
+/**
+* The transport boundary. `foldkit-remote` never talks to a transport directly;
+* it depends on this Effect service, which a later phase wires to Effect RPC.
+*/
+var RemoteClient = class extends Context.Service()("foldkit-remote/RemoteClient") {};
+/** Reconstructs the client's `ConnectionChange` from the wire's flattened edge. */
+const connectionChangeOf = (change) => {
+	const edge = {
+		key: change.edge.key,
+		ref: {
+			entity: change.edge.entity,
+			id: change.edge.id
+		}
+	};
+	return change._tag === "Insert" ? {
+		_tag: "Insert",
+		connection: change.connection,
+		position: change.position,
+		edge
+	} : {
+		_tag: "Remove",
+		connection: change.connection,
+		edge
+	};
+};
+/** Reconstructs the client's `LiveEvent` from the wire's flattened `LiveChange`. */
+const liveEventOf = (change) => {
+	switch (change._tag) {
+		case "EntityPatched": return {
+			_tag: "EntityPatched",
+			ref: {
+				entity: change.entity,
+				id: change.id
+			},
+			values: change.values,
+			changed: change.changed,
+			cursor: change.cursor
+		};
+		case "EntityDeleted": return {
+			_tag: "EntityDeleted",
+			ref: {
+				entity: change.entity,
+				id: change.id
+			},
+			cursor: change.cursor
+		};
+		case "ConnectionInsert": return {
+			_tag: "ConnectionInsert",
+			connection: change.connection,
+			position: change.position,
+			edge: {
+				key: change.edge.key,
+				ref: {
+					entity: change.edge.entity,
+					id: change.edge.id
+				}
+			},
+			cursor: change.cursor
+		};
+		case "ConnectionRemove": return {
+			_tag: "ConnectionRemove",
+			connection: change.connection,
+			edge: {
+				key: change.edge.key,
+				ref: {
+					entity: change.edge.entity,
+					id: change.edge.id
+				}
+			},
+			cursor: change.cursor
+		};
+		case "ConnectionInvalidate": return {
+			_tag: "ConnectionInvalidate",
+			connection: change.connection,
+			cursor: change.cursor
+		};
+	}
+};
+const remoteError = (error) => ({
+	_tag: error._tag,
+	message: error.message,
+	...error.refusal === void 0 ? {} : { refusal: error.refusal },
+	...error.reason === void 0 ? {} : { reason: error.reason }
+});
+const coalescedLayer = (layer, options = {}) => Layer.effect(RemoteClient, Effect.gen(function* () {
+	const client = yield* RemoteClient;
+	const read = yield* coalesceReads(client.read, options);
+	const query = yield* coalesceQueries(client.query, options);
+	return {
+		...client,
+		read,
+		query
+	};
+})).pipe(Layer.provide(layer));
+/**
+* A new operation's identity: random, so unique across clients and reloads.
+* `randomUUID` exists only in a secure context, so a page served over plain
+* HTTP draws 128 random bits from `getRandomValues`, which exists in all.
+*/
+const mintOperation = () => typeof globalThis.crypto.randomUUID === "function" ? globalThis.crypto.randomUUID() : Array.from(globalThis.crypto.getRandomValues(/* @__PURE__ */ new Uint8Array(16)), (byte) => byte.toString(16).padStart(2, "0")).join("");
+/**
+* `Remote.mutate` as a standalone effect, so `Remote.mutateInto` can reuse it
+* without the object literal referencing itself.
+*/
+const mutateRemote = Effect.fn("Remote.mutate")(function* (mutation, input, requestId, options = {}) {
+	const { keys, shown, now } = options;
+	const operation = options.operation ?? (yield* Effect.sync(mintOperation));
+	yield* Effect.annotateCurrentSpan({
+		mutation: mutation.name,
+		requestId,
+		operation
+	});
+	const client = yield* RemoteClient;
+	const encoded = yield* Schema.encodeUnknownEffect(mutation.Input)(input).pipe(Effect.catchTag("SchemaError", (error) => Effect.fail(new RemoteMutationError({ message: error.message }))));
+	const result = yield* client.mutate({
+		requestId,
+		operation,
+		mutation: mutation.name,
+		input: encoded,
+		...keys === void 0 ? {} : { keys },
+		...now === void 0 ? {} : { now },
+		...shown === void 0 || shown.length === 0 ? {} : { shown }
+	});
+	return {
+		output: yield* Schema.decodeUnknownEffect(mutation.Output)(result.output).pipe(Effect.catchTag("SchemaError", (error) => Effect.fail(new RemoteMutationError({ message: error.message })))),
+		entities: result.entities,
+		connections: (result.connections ?? []).map(connectionChangeOf),
+		deleted: result.deleted ?? [],
+		read: result.read
+	};
+});
+export { RemoteClient, coalescedLayer, connectionChangeOf, liveEventOf, mintOperation, mutateRemote, remoteError };
+
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","names":[],"sources":["../src/client.ts"],"sourcesContent":["/**\n * The transport seam: the `RemoteClient` Effect service, the RPC client it is\n * built from, the wire-to-client reconstructions, and the mutation call.\n */\nimport { Context, Effect, Layer, Schema, Stream } from 'effect'\nimport type { RelationRequirement, Requirement } from './requirement.js'\nimport { coalesceQueries, coalesceReads, type CoalesceOptions } from './coalesce.js'\nimport type { LiveCursor, LiveEvent } from './live.js'\nimport type { MutationDescriptor } from './mutation.js'\nimport type { ConnectionChange } from './optimistic.js'\nimport type { RemoteError } from './remoteData.js'\nimport {\n  MutationRequest,\n  MutationResult,\n  QueryRequest,\n  QueryResult,\n  ReadBatch,\n  ReadBatchResult,\n  type ConnectionChangeSchema,\n  RemoteLiveError,\n  RemoteLiveRefused,\n  RemoteForbidden,\n  RemoteUnauthenticated,\n  RemoteMutationError,\n  RemoteProtocolError,\n  RemoteQueryError,\n  RemoteReadError,\n  RemoteUnreachable,\n  type LiveChange,\n  type LiveRequirement,\n} from './wire.js'\n\n/**\n * The transport boundary. `foldkit-remote` never talks to a transport directly;\n * it depends on this Effect service, which a later phase wires to Effect RPC.\n */\nexport class RemoteClient extends Context.Service<\n  RemoteClient,\n  {\n    readonly read: (\n      batch: Schema.Schema.Type<typeof ReadBatch>,\n    ) => Effect.Effect<\n      Schema.Schema.Type<typeof ReadBatchResult>,\n      RemoteReadError | RemoteProtocolError | RemoteUnauthenticated\n    >\n    readonly query: (\n      request: Schema.Schema.Type<typeof QueryRequest>,\n    ) => Effect.Effect<\n      Schema.Schema.Type<typeof QueryResult>,\n      RemoteQueryError | RemoteUnauthenticated\n    >\n    readonly mutate: (\n      request: Schema.Schema.Type<typeof MutationRequest>,\n    ) => Effect.Effect<\n      Schema.Schema.Type<typeof MutationResult>,\n      RemoteMutationError | RemoteForbidden | RemoteUnauthenticated | RemoteUnreachable\n    >\n    readonly live: (request: {\n      readonly requirements: ReadonlyArray<Requirement>\n      /** The lists read live, each as its read sends it. */\n      readonly queries: ReadonlyArray<Schema.Schema.Type<typeof QueryRequest>>\n      readonly after: LiveCursor\n    }) => Stream.Stream<\n      LiveEvent,\n      RemoteLiveError | RemoteLiveRefused | RemoteProtocolError | RemoteUnauthenticated\n    >\n  }\n>()('foldkit-remote/RemoteClient') {}\n\n/**\n * The methods an Effect RPC client for `RemoteRpc` exposes. `R` is the\n * environment a handler needs; it defaults to `never`, which is what a real\n * transport client satisfies. `RemoteServer.handlers` returns this type with its\n * own `R`, so the two sides cannot drift apart.\n *\n * `TransportError` is what the transport itself may fail with on top of the\n * declared errors: `RpcClientError` for the client `RpcClient.make` builds,\n * `never` for in-process handlers.\n */\nexport interface RemoteRpcClient<R = never, TransportError = never> {\n  readonly FoldkitRemoteRead: (\n    payload: Schema.Schema.Type<typeof ReadBatch>,\n  ) => Effect.Effect<\n    Schema.Schema.Type<typeof ReadBatchResult>,\n    RemoteReadError | RemoteProtocolError | RemoteUnauthenticated | TransportError,\n    R\n  >\n  readonly FoldkitRemoteQuery: (\n    payload: Schema.Schema.Type<typeof QueryRequest>,\n  ) => Effect.Effect<\n    Schema.Schema.Type<typeof QueryResult>,\n    RemoteQueryError | RemoteUnauthenticated | TransportError,\n    R\n  >\n  readonly FoldkitRemoteMutate: (\n    payload: Schema.Schema.Type<typeof MutationRequest>,\n  ) => Effect.Effect<\n    Schema.Schema.Type<typeof MutationResult>,\n    RemoteMutationError | RemoteForbidden | RemoteUnauthenticated | TransportError,\n    R\n  >\n  readonly FoldkitRemoteLive: (\n    payload: Schema.Schema.Type<typeof LiveRequirement>,\n  ) => Stream.Stream<\n    Schema.Schema.Type<typeof LiveChange>,\n    | RemoteLiveError\n    | RemoteLiveRefused\n    | RemoteProtocolError\n    | RemoteUnauthenticated\n    | TransportError,\n    R\n  >\n}\n\n/**\n * A client over a JSON transport (`Remote.json`, `Remote.http`): a mutation\n * nothing answered fails `RemoteUnreachable`, its only error of its own.\n */\nexport type RemoteJsonClient = RemoteRpcClient<never, RemoteUnreachable>\n\n/** Reconstructs the client's `ConnectionChange` from the wire's flattened edge. */\nexport const connectionChangeOf = (\n  change: Schema.Schema.Type<typeof ConnectionChangeSchema>,\n): ConnectionChange => {\n  const edge = { key: change.edge.key, ref: { entity: change.edge.entity, id: change.edge.id } }\n  return change._tag === 'Insert'\n    ? { _tag: 'Insert', connection: change.connection, position: change.position, edge }\n    : { _tag: 'Remove', connection: change.connection, edge }\n}\n\n/** Reconstructs the client's `LiveEvent` from the wire's flattened `LiveChange`. */\nexport const liveEventOf = (change: Schema.Schema.Type<typeof LiveChange>): LiveEvent => {\n  switch (change._tag) {\n    case 'EntityPatched':\n      return {\n        _tag: 'EntityPatched',\n        ref: { entity: change.entity, id: change.id },\n        values: change.values,\n        changed: change.changed,\n        cursor: change.cursor,\n      }\n    case 'EntityDeleted':\n      return {\n        _tag: 'EntityDeleted',\n        ref: { entity: change.entity, id: change.id },\n        cursor: change.cursor,\n      }\n    case 'ConnectionInsert':\n      return {\n        _tag: 'ConnectionInsert',\n        connection: change.connection,\n        position: change.position,\n        edge: { key: change.edge.key, ref: { entity: change.edge.entity, id: change.edge.id } },\n        cursor: change.cursor,\n      }\n    case 'ConnectionRemove':\n      return {\n        _tag: 'ConnectionRemove',\n        connection: change.connection,\n        edge: { key: change.edge.key, ref: { entity: change.edge.entity, id: change.edge.id } },\n        cursor: change.cursor,\n      }\n    case 'ConnectionInvalidate':\n      return { _tag: 'ConnectionInvalidate', connection: change.connection, cursor: change.cursor }\n  }\n}\n\nexport const remoteError = (error: {\n  readonly _tag: string\n  readonly message: string\n  readonly refusal?: unknown\n  readonly reason?: string | undefined\n}): RemoteError => ({\n  _tag: error._tag,\n  message: error.message,\n  ...(error.refusal === undefined ? {} : { refusal: error.refusal }),\n  ...(error.reason === undefined ? {} : { reason: error.reason }),\n})\n\nexport const coalescedLayer = <E, R>(\n  layer: Layer.Layer<RemoteClient, E, R>,\n  options: CoalesceOptions = {},\n): Layer.Layer<RemoteClient, E, R> =>\n  Layer.effect(\n    RemoteClient,\n    Effect.gen(function* () {\n      const client = yield* RemoteClient\n      const read = yield* coalesceReads(client.read, options)\n      const query = yield* coalesceQueries(client.query, options)\n      return { ...client, read, query }\n    }),\n  ).pipe(Layer.provide(layer))\n\n/**\n * A new operation's identity: random, so unique across clients and reloads.\n * `randomUUID` exists only in a secure context, so a page served over plain\n * HTTP draws 128 random bits from `getRandomValues`, which exists in all.\n */\nexport const mintOperation = (): string =>\n  typeof globalThis.crypto.randomUUID === 'function'\n    ? globalThis.crypto.randomUUID()\n    : Array.from(globalThis.crypto.getRandomValues(new Uint8Array(16)), byte =>\n        byte.toString(16).padStart(2, '0'),\n      ).join('')\n\n/**\n * `Remote.mutate` as a standalone effect, so `Remote.mutateInto` can reuse it\n * without the object literal referencing itself.\n */\nexport const mutateRemote = Effect.fn('Remote.mutate')(function* <\n  Name extends string,\n  Input,\n  Output,\n>(\n  mutation: MutationDescriptor<Name, Input, Output>,\n  input: Input,\n  requestId: string,\n  options: {\n    readonly keys?: ReadonlyArray<string> | undefined\n    /**\n     * The operation's identity across clients, the same on each retry of it:\n     * minted here when not given, so a retry must pass the one first sent.\n     */\n    readonly operation?: string | undefined\n    /** What the client shows of each entity's rows, for the answer to carry (`Data.mutate` sends it). */\n    readonly shown?: ReadonlyArray<RelationRequirement> | undefined\n    /** When the reader acted, as `Data.mutate` predicted it: sent for the server to take. */\n    readonly now?: number | undefined\n  } = {},\n) {\n  const { keys, shown, now } = options\n  const operation = options.operation ?? (yield* Effect.sync(mintOperation))\n  yield* Effect.annotateCurrentSpan({ mutation: mutation.name, requestId, operation })\n  const client = yield* RemoteClient\n  const encoded = yield* Schema.encodeUnknownEffect(mutation.Input)(input).pipe(\n    Effect.catchTag('SchemaError', error =>\n      Effect.fail(new RemoteMutationError({ message: error.message })),\n    ),\n  )\n  const result = yield* client.mutate({\n    requestId,\n    operation,\n    mutation: mutation.name,\n    input: encoded,\n    ...(keys === undefined ? {} : { keys }),\n    ...(now === undefined ? {} : { now }),\n    ...(shown === undefined || shown.length === 0 ? {} : { shown }),\n  })\n  const output = yield* Schema.decodeUnknownEffect(mutation.Output)(result.output).pipe(\n    Effect.catchTag('SchemaError', error =>\n      Effect.fail(new RemoteMutationError({ message: error.message })),\n    ),\n  )\n  return {\n    output,\n    entities: result.entities,\n    connections: (result.connections ?? []).map(connectionChangeOf),\n    deleted: result.deleted ?? [],\n    read: result.read,\n  }\n})\n"],"mappings":"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"}

package/dist/coalesce-CLAr92Nk.d.ts

@@ -0,0 +1,34 @@
+import { a as Requirement } from "./requirement-D57S2LpH.js";
+import { C as ReadBatch, F as RemoteUnauthenticated, M as RemoteQueryError, N as RemoteReadError, j as RemoteProtocolError, v as QueryRequest, w as ReadBatchResult, y as QueryResult } from "./wire-DthPcTM6.js";
+import { Duration, Effect, Schema } from "effect";
+type Batch = Schema.Schema.Type<typeof ReadBatch>;
+type BatchResult = Schema.Schema.Type<typeof ReadBatchResult>;
+type ReadError = RemoteReadError | RemoteProtocolError | RemoteUnauthenticated;
+type QueryError = RemoteQueryError | RemoteUnauthenticated;
+type BatchRead = (batch: Batch) => Effect.Effect<BatchResult, ReadError>;
+type QueryRequestValue = Schema.Schema.Type<typeof QueryRequest>;
+type QueryResultValue = Schema.Schema.Type<typeof QueryResult>;
+type QueryRun = (request: QueryRequestValue) => Effect.Effect<QueryResultValue, QueryError>;
+interface CoalesceOptions {
+  /**
+   * How long a batch waits to collect more requirements before it runs.
+   * Requirements issued concurrently coalesce even at the default of no wait.
+   */
+  readonly window?: Duration.Input | undefined;
+}
+/** A stable key for a requirement, so an equal requirement in flight is joined. */
+declare const requirementKey: (requirement: Requirement) => string;
+/**
+ * Wraps a raw query so that an identical query in flight (same query, input,
+ * and window) is joined rather than run again; distinct queries run
+ * concurrently. A page answers exactly one window, so nothing is batched.
+ */
+declare const coalesceQueries: (query: QueryRun, options?: CoalesceOptions) => Effect.Effect<QueryRun>;
+/**
+ * Wraps a raw batch read so that requirements are batched and deduplicated.
+ * Every waiter receives the whole batch result; `Remote.writeRead` is
+ * idempotent, so writing it more than once is harmless.
+ */
+declare const coalesceReads: (read: BatchRead, options?: CoalesceOptions) => Effect.Effect<BatchRead>;
+export { coalesceReads as a, coalesceQueries as i, CoalesceOptions as n, requirementKey as o, QueryRun as r, BatchRead as t };
+//# sourceMappingURL=coalesce-CLAr92Nk.d.ts.map

package/dist/coalesce-CLAr92Nk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coalesce-CLAr92Nk.d.ts","names":[],"sources":["../src/coalesce.ts"],"mappings":";;;KAgCK,QAAQ,OAAO,OAAO,YAAY;KAClC,cAAc,OAAO,OAAO,YAAY;KACxC,YAAY,kBAAkB,sBAAsB;KACpD,aAAa,mBAAmB;KACzB,aAAa,OAAO,UAAU,OAAO,OAAO,aAAa;KAChE,oBAAoB,OAAO,OAAO,YAAY;KAC9C,mBAAmB,OAAO,OAAO,YAAY;KACtC,YAAY,SAAS,sBAAsB,OAAO,OAAO,kBAAkB;UAEtE;;;;;WAKN,SAAS,SAAS;;;cAIhB,iBAAc,aAAiB;;;;;;cAoD/B,kBAAe,OACnB,UAAQ,UACN,oBACR,OAAO,OAAO;;;;;;cA+CJ,gBAAa,MAClB,WAAS,UACN,oBACR,OAAO,OAAO"}

package/dist/coalesce.d.ts

@@ -0,0 +1,2 @@
+import { a as coalesceReads, i as coalesceQueries, n as CoalesceOptions, o as requirementKey, r as QueryRun, t as BatchRead } from "./coalesce-CLAr92Nk.js";
+export { BatchRead, CoalesceOptions, QueryRun, coalesceQueries, coalesceReads, requirementKey };

package/dist/coalesce.js

@@ -0,0 +1,131 @@
+import { Requirement } from "./requirement.js";
+import { stableStringify } from "./query.js";
+import "./wire.js";
+import { Deferred, Duration, Effect, Request, RequestResolver } from "effect";
+// src/coalesce.ts
+/**
+* Read coalescing: every requirement a client asks for goes through one
+* `RequestResolver`, so requirements issued together become one `ReadBatch`
+* (ids batched, fields unioned) and a requirement already in flight is joined
+* rather than re-requested. The planner stays pure; this is the transport
+* seam's concern, and the store is still the only cache.
+*/
+/** A stable key for a requirement, so an equal requirement in flight is joined. */
+const requirementKey = (requirement) => stableStringify([
+	requirement.entity,
+	requirement.id,
+	[...requirement.fields].sort(),
+	requirement.windows ?? null,
+	requirement.relations ?? null
+]);
+/** Whether a requirement pages a relation anywhere in its graph. */
+const hasWindows = (requirement) => requirement.windows !== void 0 || Object.values(requirement.relations ?? {}).some(hasWindows);
+/**
+* The reads a batch runs. Requirements that page nothing union into one read
+* per entity and id, and every waiter may write its whole result, since
+* plain values are the same whoever asked. A requirement that pages a
+* relation reads alone: a page answers exactly one window, and a waiter
+* cannot tell which of two pages for the same entity was its own.
+*/
+const readsOf = (owned) => {
+	const plain = [...owned].filter(([, requirement]) => !hasWindows(requirement));
+	const paged = [...owned].filter(([, requirement]) => hasWindows(requirement));
+	return [...plain.length === 0 ? [] : [{
+		keys: plain.map(([key]) => key),
+		requests: Requirement.merge(plain.map(([, requirement]) => requirement))
+	}], ...paged.map(([key, requirement]) => ({
+		keys: [key],
+		requests: [requirement]
+	}))];
+};
+var QueryRead = class extends Request.Class {};
+/**
+* Wraps a raw query so that an identical query in flight (same query, input,
+* and window) is joined rather than run again; distinct queries run
+* concurrently. A page answers exactly one window, so nothing is batched.
+*/
+const coalesceQueries = (query, options = {}) => Effect.gen(function* () {
+	const runAll = (entries) => Effect.gen(function* () {
+		const distinct = /* @__PURE__ */ new Map();
+		for (const entry of entries) distinct.set(entry.request.key, entry.request.request);
+		const results = /* @__PURE__ */ new Map();
+		yield* Effect.forEach(distinct, ([key, request]) => Effect.exit(query(request)).pipe(Effect.map((exit) => void results.set(key, exit))), {
+			concurrency: "unbounded",
+			discard: true
+		});
+		for (const entry of entries) yield* Request.completeEffect(entry, results.get(entry.request.key));
+	});
+	let resolver = RequestResolver.make(runAll);
+	if (options.window !== void 0) resolver = RequestResolver.setDelay(resolver, Duration.fromInputUnsafe(options.window));
+	return (request) => Effect.request(new QueryRead({
+		key: stableStringify([
+			request.query,
+			request.input,
+			request.window,
+			request.select ?? null
+		]),
+		request
+	}), resolver);
+});
+var ReadRequirement = class extends Request.Class {};
+/**
+* Wraps a raw batch read so that requirements are batched and deduplicated.
+* Every waiter receives the whole batch result; `Remote.writeRead` is
+* idempotent, so writing it more than once is harmless.
+*/
+const coalesceReads = (read, options = {}) => Effect.gen(function* () {
+	const inFlight = /* @__PURE__ */ new Map();
+	const runAll = (entries) => Effect.gen(function* () {
+		const joins = /* @__PURE__ */ new Map();
+		const own = /* @__PURE__ */ new Map();
+		for (const entry of entries) {
+			const key = entry.request.key;
+			if (joins.has(key)) continue;
+			const existing = inFlight.get(key);
+			if (existing !== void 0) {
+				joins.set(key, existing);
+				continue;
+			}
+			const deferred = yield* Deferred.make();
+			inFlight.set(key, deferred);
+			own.set(key, deferred);
+			joins.set(key, deferred);
+		}
+		if (own.size > 0) {
+			const owned = /* @__PURE__ */ new Map();
+			for (const entry of entries) if (own.has(entry.request.key)) owned.set(entry.request.key, entry.request.requirement);
+			yield* Effect.forEach(readsOf(owned), ({ keys, requests }) => Effect.gen(function* () {
+				const exit = yield* Effect.exit(read({
+					version: 5,
+					requests
+				}));
+				for (const key of keys) {
+					inFlight.delete(key);
+					yield* Deferred.done(own.get(key), exit);
+				}
+			}), {
+				concurrency: "unbounded",
+				discard: true
+			});
+		}
+		for (const entry of entries) yield* Request.completeEffect(entry, Deferred.await(joins.get(entry.request.key)));
+	});
+	let resolver = RequestResolver.make(runAll);
+	if (options.window !== void 0) resolver = RequestResolver.setDelay(resolver, Duration.fromInputUnsafe(options.window));
+	return (batch) => batch.requests.length === 0 ? Effect.succeed({
+		entities: [],
+		settled: []
+	}) : Effect.forEach(batch.requests, (requirement) => Effect.request(new ReadRequirement({
+		key: requirementKey(requirement),
+		requirement
+	}), resolver), { concurrency: "unbounded" }).pipe(Effect.map((results) => {
+		const distinct = [...new Set(results)];
+		return {
+			entities: distinct.flatMap((result) => result.entities),
+			settled: distinct.flatMap((result) => result.settled)
+		};
+	}));
+});
+export { coalesceQueries, coalesceReads, requirementKey };
+
+//# sourceMappingURL=coalesce.js.map

package/dist/coalesce.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"coalesce.js","names":[],"sources":["../src/coalesce.ts"],"sourcesContent":["/**\n * Read coalescing: every requirement a client asks for goes through one\n * `RequestResolver`, so requirements issued together become one `ReadBatch`\n * (ids batched, fields unioned) and a requirement already in flight is joined\n * rather than re-requested. The planner stays pure; this is the transport\n * seam's concern, and the store is still the only cache.\n */\nimport {\n  Deferred,\n  Duration,\n  Effect,\n  Request,\n  RequestResolver,\n  type Exit,\n  type Schema,\n} from 'effect'\nimport { Requirement, type RelationRequirement } from './requirement.js'\nimport { stableStringify } from './query.js'\nimport {\n  REMOTE_PROTOCOL_VERSION,\n  type QueryRequest,\n  type QueryResult,\n  type ReadBatch,\n  type ReadBatchResult,\n} from './wire.js'\nimport type {\n  RemoteProtocolError,\n  RemoteQueryError,\n  RemoteReadError,\n  RemoteUnauthenticated,\n} from './wire.js'\n\ntype Batch = Schema.Schema.Type<typeof ReadBatch>\ntype BatchResult = Schema.Schema.Type<typeof ReadBatchResult>\ntype ReadError = RemoteReadError | RemoteProtocolError | RemoteUnauthenticated\ntype QueryError = RemoteQueryError | RemoteUnauthenticated\nexport type BatchRead = (batch: Batch) => Effect.Effect<BatchResult, ReadError>\ntype QueryRequestValue = Schema.Schema.Type<typeof QueryRequest>\ntype QueryResultValue = Schema.Schema.Type<typeof QueryResult>\nexport type QueryRun = (request: QueryRequestValue) => Effect.Effect<QueryResultValue, QueryError>\n\nexport interface CoalesceOptions {\n  /**\n   * How long a batch waits to collect more requirements before it runs.\n   * Requirements issued concurrently coalesce even at the default of no wait.\n   */\n  readonly window?: Duration.Input | undefined\n}\n\n/** A stable key for a requirement, so an equal requirement in flight is joined. */\nexport const requirementKey = (requirement: Requirement): string =>\n  stableStringify([\n    requirement.entity,\n    requirement.id,\n    [...requirement.fields].sort(),\n    requirement.windows ?? null,\n    requirement.relations ?? null,\n  ])\n\n/** Whether a requirement pages a relation anywhere in its graph. */\nconst hasWindows = (requirement: RelationRequirement): boolean =>\n  requirement.windows !== undefined || Object.values(requirement.relations ?? {}).some(hasWindows)\n\n/**\n * The reads a batch runs. Requirements that page nothing union into one read\n * per entity and id, and every waiter may write its whole result, since\n * plain values are the same whoever asked. A requirement that pages a\n * relation reads alone: a page answers exactly one window, and a waiter\n * cannot tell which of two pages for the same entity was its own.\n */\nconst readsOf = (\n  owned: ReadonlyMap<string, Requirement>,\n): ReadonlyArray<{\n  readonly keys: ReadonlyArray<string>\n  readonly requests: ReadonlyArray<Requirement>\n}> => {\n  const plain = [...owned].filter(([, requirement]) => !hasWindows(requirement))\n  const paged = [...owned].filter(([, requirement]) => hasWindows(requirement))\n  return [\n    ...(plain.length === 0\n      ? []\n      : [\n          {\n            keys: plain.map(([key]) => key),\n            requests: Requirement.merge(plain.map(([, requirement]) => requirement)),\n          },\n        ]),\n    ...paged.map(([key, requirement]) => ({ keys: [key], requests: [requirement] })),\n  ]\n}\n\nclass QueryRead extends Request.Class<\n  { readonly key: string; readonly request: QueryRequestValue },\n  QueryResultValue,\n  QueryError\n> {}\n\n/**\n * Wraps a raw query so that an identical query in flight (same query, input,\n * and window) is joined rather than run again; distinct queries run\n * concurrently. A page answers exactly one window, so nothing is batched.\n */\nexport const coalesceQueries = (\n  query: QueryRun,\n  options: CoalesceOptions = {},\n): Effect.Effect<QueryRun> =>\n  Effect.gen(function* () {\n    const runAll = (entries: ReadonlyArray<Request.Entry<QueryRead>>) =>\n      Effect.gen(function* () {\n        const distinct = new Map<string, QueryRequestValue>()\n        for (const entry of entries) distinct.set(entry.request.key, entry.request.request)\n        const results = new Map<string, Exit.Exit<QueryResultValue, QueryError>>()\n        yield* Effect.forEach(\n          distinct,\n          ([key, request]) =>\n            Effect.exit(query(request)).pipe(Effect.map(exit => void results.set(key, exit))),\n          { concurrency: 'unbounded', discard: true },\n        )\n        for (const entry of entries) {\n          yield* Request.completeEffect(entry, results.get(entry.request.key)!)\n        }\n      })\n    let resolver = RequestResolver.make<QueryRead>(runAll)\n    if (options.window !== undefined) {\n      resolver = RequestResolver.setDelay(resolver, Duration.fromInputUnsafe(options.window))\n    }\n    return request =>\n      Effect.request(\n        new QueryRead({\n          key: stableStringify([\n            request.query,\n            request.input,\n            request.window,\n            request.select ?? null,\n          ]),\n          request,\n        }),\n        resolver,\n      )\n  })\n\nclass ReadRequirement extends Request.Class<\n  { readonly key: string; readonly requirement: Requirement },\n  BatchResult,\n  ReadError\n> {}\n\n/**\n * Wraps a raw batch read so that requirements are batched and deduplicated.\n * Every waiter receives the whole batch result; `Remote.writeRead` is\n * idempotent, so writing it more than once is harmless.\n */\nexport const coalesceReads = (\n  read: BatchRead,\n  options: CoalesceOptions = {},\n): Effect.Effect<BatchRead> =>\n  Effect.gen(function* () {\n    // Requirements a batch is currently reading; a later equal requirement\n    // joins the deferred instead of starting another read.\n    const inFlight = new Map<string, Deferred.Deferred<BatchResult, ReadError>>()\n\n    // A batch runs to completion even when every requester is interrupted, so\n    // an in-flight requirement is always settled and released by its read.\n    const runAll = (entries: ReadonlyArray<Request.Entry<ReadRequirement>>) =>\n      Effect.gen(function* () {\n        // Per requirement key: the deferred this batch's entries wait on. One\n        // already in flight from an earlier batch is joined; the rest are\n        // owned here and settled by this batch's read.\n        const joins = new Map<string, Deferred.Deferred<BatchResult, ReadError>>()\n        const own = new Map<string, Deferred.Deferred<BatchResult, ReadError>>()\n        for (const entry of entries) {\n          const key = entry.request.key\n          if (joins.has(key)) continue\n          const existing = inFlight.get(key)\n          if (existing !== undefined) {\n            joins.set(key, existing)\n            continue\n          }\n          const deferred = yield* Deferred.make<BatchResult, ReadError>()\n          inFlight.set(key, deferred)\n          own.set(key, deferred)\n          joins.set(key, deferred)\n        }\n        if (own.size > 0) {\n          const owned = new Map<string, Requirement>()\n          for (const entry of entries) {\n            if (own.has(entry.request.key)) owned.set(entry.request.key, entry.request.requirement)\n          }\n          yield* Effect.forEach(\n            readsOf(owned),\n            ({ keys, requests }) =>\n              Effect.gen(function* () {\n                const exit = yield* Effect.exit(\n                  read({ version: REMOTE_PROTOCOL_VERSION, requests }),\n                )\n                // Settle exactly the requirements this read answered.\n                for (const key of keys) {\n                  inFlight.delete(key)\n                  yield* Deferred.done(own.get(key)!, exit)\n                }\n              }),\n            { concurrency: 'unbounded', discard: true },\n          )\n        }\n        for (const entry of entries) {\n          yield* Request.completeEffect(entry, Deferred.await(joins.get(entry.request.key)!))\n        }\n      })\n\n    let resolver = RequestResolver.make<ReadRequirement>(runAll)\n    if (options.window !== undefined) {\n      resolver = RequestResolver.setDelay(resolver, Duration.fromInputUnsafe(options.window))\n    }\n\n    return batch =>\n      batch.requests.length === 0\n        ? Effect.succeed({ entities: [], settled: [] })\n        : Effect.forEach(\n            batch.requests,\n            requirement =>\n              Effect.request(\n                new ReadRequirement({ key: requirementKey(requirement), requirement }),\n                resolver,\n              ),\n            { concurrency: 'unbounded' },\n          ).pipe(\n            Effect.map(results => {\n              const distinct = [...new Set(results)]\n              return {\n                entities: distinct.flatMap(result => result.entities),\n                settled: distinct.flatMap(result => result.settled),\n              }\n            }),\n          )\n  })\n"],"mappings":"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"}

package/dist/connection-BRyaJy89.d.ts

@@ -0,0 +1,45 @@
+interface EdgeRef {
+  readonly entity: string;
+  readonly id: string;
+}
+/** `key` is the edge identity used for de-duplication. */
+interface Edge {
+  readonly key: string;
+  readonly ref: EdgeRef;
+}
+declare const edge: (ref: EdgeRef, key?: string) => Edge;
+type Cursor = string;
+type Boundary = {
+  readonly _tag: 'Terminal';
+} | {
+  readonly _tag: 'Cursor';
+  readonly cursor: Cursor;
+} | {
+  readonly _tag: 'Unknown';
+};
+declare const terminal: Boundary;
+declare const unknown: Boundary;
+declare const cursor: (value: Cursor) => Boundary;
+interface Segment {
+  readonly edges: readonly Edge[];
+  readonly start: Boundary;
+  readonly end: Boundary;
+}
+interface Connection {
+  readonly segments: readonly Segment[];
+  readonly stale: boolean;
+}
+declare const emptyConnection: Connection;
+declare const segment: (edges: readonly Edge[], start: Boundary, end: Boundary) => Segment;
+/** Adds a page to the connection, joining contiguous or overlapping segments. */
+declare const merge: (current: Connection, page: Segment) => Connection;
+/** Visible edges, segment by segment. */
+declare const items: (connection: Connection) => ReadonlyArray<Edge>;
+/** There is more before the known region. Derived from boundaries, never row count. */
+declare const hasPrevious: (connection: Connection) => boolean;
+/** There is more after the known region. Derived from boundaries, never row count. */
+declare const hasNext: (connection: Connection) => boolean;
+/** A connection with more than one segment has an explicit unknown gap. */
+declare const isGapped: (connection: Connection) => boolean;
+export { unknown as _, EdgeRef as a, edge as c, hasPrevious as d, isGapped as f, terminal as g, segment as h, Edge as i, emptyConnection as l, merge as m, Connection as n, Segment as o, items as p, Cursor as r, cursor as s, Boundary as t, hasNext as u };
+//# sourceMappingURL=connection-BRyaJy89.d.ts.map

package/dist/connection-BRyaJy89.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection-BRyaJy89.d.ts","names":[],"sources":["../src/connection.ts"],"mappings":"A,UAUiB;WACN;WACA;;;UAIM;WACN;WACA,KAAK;;cAGH,OAAI,KAAS,SAAO,iBAAgD;KAKrE;KAEA;WACG;;WACA;WAAyB,QAAQ;;WACjC;;cAEF,UAAU;cACV,SAAS;cACT,SAAM,OAAW,WAAS;UAEtB;WACN,gBAAgB;WAChB,OAAO;WACP,KAAK;;UAGC;WACN,mBAAmB;WACnB;;cAGE,iBAAiB;cAEjB,UAAO,gBAAoB,QAAM,OAAS,UAAQ,KAAO,aAAW;;cA+FpE,QAAK,SAAa,YAAU,MAAQ,YAAU;;cA4C9C,QAAK,YAAgB,eAAa,cAAc;;cAIhD,cAAW,YAAgB;;cAM3B,UAAO,YAAgB;;cAMvB,WAAQ,YAAgB"}

package/dist/connection.d.ts

@@ -0,0 +1,2 @@
+import { _ as unknown, a as EdgeRef, c as edge, d as hasPrevious, f as isGapped, g as terminal, h as segment, i as Edge, l as emptyConnection, m as merge, n as Connection, o as Segment, p as items, r as Cursor, s as cursor, t as Boundary, u as hasNext } from "./connection-BRyaJy89.js";
+export { Boundary, Connection, Cursor, Edge, EdgeRef, Segment, cursor, edge, emptyConnection, hasNext, hasPrevious, isGapped, items, merge, segment, terminal, unknown };