foldkit-remote 0.20.0 → 0.22.0

package/dist/inspect-DtRQGCRP.d.ts

@@ -0,0 +1,134 @@
+import { r as RemoteData } from "./remoteData-mK1suYi1.js";
+import { o as RemoteDiagnostic } from "./diagnostics-DHhVYflV.js";
+import { l as QueryWindow } from "./query-BuIU93xA.js";
+import { n as RelationRequirement } from "./requirement-D57S2LpH.js";
+import { s as RemoteModel, t as Failures } from "./model-B6zk1NMB.js";
+import { Dependencies } from "foldkit-entity";
+/** A query body's `Dependencies` as plain data: each field by its Entity's name and key. */
+interface ExplainedDependencies {
+  readonly fields: ReadonlyArray<{
+    readonly entity: string;
+    readonly key: string;
+  }>;
+  readonly inputs: Dependencies['inputs'];
+  readonly operations: Dependencies['operations'];
+  /** Each operator it calls, by its id and version. */
+  readonly operators: ReadonlyArray<{
+    readonly id: string;
+    readonly version: number;
+  }>;
+}
+/** A serializable summary of a RemoteModel for DevTools and diagnostics. */
+interface RemoteInspection {
+  readonly entities: ReadonlyArray<{
+    readonly key: string;
+    readonly present: ReadonlyArray<string>;
+    readonly stale: ReadonlyArray<string>;
+    readonly unavailable: ReadonlyArray<string>;
+    readonly tombstone: boolean;
+    readonly updatedAt: number;
+    readonly windows: Readonly<Record<string, string>>;
+  }>;
+  readonly connections: ReadonlyArray<string>;
+  readonly live: ReadonlyArray<string>;
+  readonly gaps: ReadonlyArray<string>;
+  /** What the client met and kept going past, oldest first (`RemoteModel.diagnostics`). */
+  readonly diagnostics: ReadonlyArray<RemoteDiagnostic>;
+  /**
+   * The `entity\0id\0field` marks of reads in flight, and a
+   * `\0connection\0identity` mark for each query in flight. This is what "Remote is
+   * working" means here, and it is read from the Model rather than from the
+   * fibers doing the work: a tool that shows it shows something the Model can
+   * be replayed to, and nothing that needs the runtime to be asked.
+   */
+  readonly loading: ReadonlyArray<string>;
+  /**
+   * The reads that failed and are not yet settled: queries by connection
+   * identity, entity fields by `entity\0id\0field` mark, each with its error.
+   */
+  readonly failures: Failures;
+  readonly mutations: {
+    readonly pending: ReadonlyArray<string>;
+    readonly failed: ReadonlyArray<string>;
+    readonly applied: number;
+  };
+}
+/** A pure, serializable view of the whole cache. */
+declare const inspectRemote: (model: RemoteModel) => RemoteInspection;
+/** A pure, serializable view of one entity, or `undefined` if unknown. */
+declare const inspectEntity: (model: RemoteModel, key: string) => RemoteInspection['entities'][number] | undefined;
+/**
+ * What one query read is, and what it currently is — data-query-DESIGN §29.1.
+ *
+ * Every member is gathered from something that already existed: the read was
+ * always this many pieces, and nothing had ever been asked to put them in one
+ * place. It is plain serializable data, so a DevTools panel, a log line and a
+ * test assert on the same value.
+ *
+ * Two members of §29.1's sketch are **not** here, and their absence is the
+ * finding rather than an omission:
+ *
+ * - **Surface.** A Projection does not know which Surface reads it, and often
+ *   several do — so it is not a property of the read, and `explain` cannot
+ *   recover it alone. Given the active Surfaces (the same record
+ *   `subscriptions` takes), it reports **every** Surface reading the connection
+ *   rather than guessing one, and omits the member entirely when it was not
+ *   given them.
+ * - **Executor.** The thing that answers a query is a `RemoteClient` Layer in
+ *   the runtime, not a value in the Model, and a pure read of the Model cannot
+ *   see it. That is the same boundary that makes this function pure and
+ *   replayable, so it is worth more than the line of text.
+ *
+ * And one that the design proposed and this does not want: *expectation*
+ * (required versus optional). §11 left it unbuilt for want of a consumer, and
+ * the explanation was the likeliest consumer. It turns out not to need it — a
+ * query's result is a connection, so the shape is a `Page`, decided by the
+ * definition rather than by the read. Nothing here has an opinion about whether
+ * an empty one is an error, because nothing here has to have one.
+ */
+interface QueryExplanation {
+  /** The bound Remote domain that answers it. */
+  readonly domain: string;
+  /** The definition's name. */
+  readonly query: string;
+  /** The input as encoded, which is what the identity is built from. */
+  readonly input: unknown;
+  /** The connection identity: definition plus canonical input, excluding the window. */
+  readonly identity: string;
+  /** How much of the connection this read asks for. */
+  readonly window: QueryWindow;
+  /** What it reads of each item, as the slice asked of the server. */
+  readonly select: RelationRequirement;
+  /**
+   * What the query means, as readable text — `Query.show`, and so neither SQL
+   * nor whatever the backend compiled. Absent for a definition made with
+   * `Query.make`, whose meaning lives on the server that answers it.
+   */
+  readonly body?: string | undefined;
+  /**
+   * The fields, inputs and operations the body reads; absent with the body.
+   * Plain data, so it serializes: a field is its Entity's name and key, which
+   * is unambiguous because a query reads one Entity.
+   */
+  readonly dependencies?: ExplainedDependencies | undefined;
+  /** What the read answers from this Model right now. */
+  readonly state: RemoteData<unknown>['_tag'];
+  /**
+   * The active Surfaces reading this connection at this Model, if the active
+   * record was supplied. Plural because several may, which is why a Projection
+   * cannot carry the answer itself.
+   */
+  readonly surfaces?: ReadonlyArray<string> | undefined;
+  /**
+   * Why each of those Surfaces is active, where it was placed with
+   * `Surface.when` — the Model path and the tag, without running anything. A
+   * Surface placed with `Surface.at` has no entry: a callback cannot be read.
+   */
+  readonly activation?: ReadonlyArray<{
+    readonly surface: string;
+    readonly path: readonly string[];
+    readonly tag: string;
+  }> | undefined;
+}
+export { inspectRemote as a, inspectEntity as i, QueryExplanation as n, RemoteInspection as r, ExplainedDependencies as t };
+//# sourceMappingURL=inspect-DtRQGCRP.d.ts.map

package/dist/inspect-DtRQGCRP.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inspect-DtRQGCRP.d.ts","names":[],"sources":["../src/inspect.ts"],"mappings":";;;;;;;UAIiB;WACN,QAAQ;aAAyB;aAAyB;;WAC1D,QAAQ;WACR,YAAY;;WAEZ,WAAW;aAAyB;aAAqB;;;;UAUnD;WACN,UAAU;aACR;aACA,SAAS;aACT,OAAO;aACP,aAAa;aACb;aACA;aACA,SAAS,SAAS;;WAEpB,aAAa;WACb,MAAM;WACN,MAAM;;WAEN,aAAa,cAAc;;;;;;;;WAQ3B,SAAS;;;;;WAKT,UAAU;WACV;aACE,SAAS;aACT,QAAQ;aACR;;;;cAeA,gBAAa,OAAW,gBAAc;;cAgBtC,gBAAa,OACjB,aAAW,gBAEjB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;UAkCc;;WAEN;;WAEA;;WAEA;;WAEA;;WAEA,QAAQ;;WAER,QAAQ;;;;;;WAMR;;;;;;WAMA,eAAe;;WAEf,OAAO;;;;;;WAMP,WAAW;;;;;;WAMX,aACL;aACW;aACA;aACA"}

package/dist/inspect.d.ts

@@ -0,0 +1,2 @@
+import { a as inspectRemote, i as inspectEntity, n as QueryExplanation, r as RemoteInspection, t as ExplainedDependencies } from "./inspect-DtRQGCRP.js";
+export { ExplainedDependencies, QueryExplanation, RemoteInspection, inspectEntity, inspectRemote };

package/dist/inspect.js

@@ -0,0 +1,33 @@
+// src/inspect.ts
+const inspectEntry = (key, entry) => ({
+	key,
+	present: [...entry.present],
+	stale: [...entry.stale],
+	unavailable: [...entry.unavailable],
+	tombstone: entry.tombstone,
+	updatedAt: entry.updatedAt,
+	windows: { ...entry.windows }
+});
+/** A pure, serializable view of the whole cache. */
+const inspectRemote = (model) => ({
+	entities: Object.entries(model.entities).map(([key, entry]) => inspectEntry(key, entry)),
+	connections: Object.keys(model.connections),
+	live: Object.keys(model.live),
+	gaps: [...model.gaps],
+	diagnostics: model.diagnostics,
+	loading: [...model.loading],
+	failures: model.failures,
+	mutations: {
+		pending: [...model.mutations.pending],
+		failed: [...model.mutations.failed],
+		applied: model.mutations.applied.size
+	}
+});
+/** A pure, serializable view of one entity, or `undefined` if unknown. */
+const inspectEntity = (model, key) => {
+	const entry = model.entities[key];
+	return entry === void 0 ? void 0 : inspectEntry(key, entry);
+};
+export { inspectEntity, inspectRemote };
+
+//# sourceMappingURL=inspect.js.map

package/dist/inspect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inspect.js","names":[],"sources":["../src/inspect.ts"],"sourcesContent":["/** A serializable summary of a RemoteModel for DevTools and diagnostics. */\nimport type { Dependencies } from 'foldkit-entity'\n\n/** A query body's `Dependencies` as plain data: each field by its Entity's name and key. */\nexport interface ExplainedDependencies {\n  readonly fields: ReadonlyArray<{ readonly entity: string; readonly key: string }>\n  readonly inputs: Dependencies['inputs']\n  readonly operations: Dependencies['operations']\n  /** Each operator it calls, by its id and version. */\n  readonly operators: ReadonlyArray<{ readonly id: string; readonly version: number }>\n}\nimport type { RemoteDiagnostic } from './diagnostics.js'\nimport type { Failures, RemoteModel } from './model.js'\nimport type { QueryWindow } from './query.js'\nimport type { RemoteData } from './remoteData.js'\nimport type { RelationRequirement } from './requirement.js'\nimport type { EntityEntry } from './store.js'\n\n/** A serializable summary of a RemoteModel for DevTools and diagnostics. */\nexport interface RemoteInspection {\n  readonly entities: ReadonlyArray<{\n    readonly key: string\n    readonly present: ReadonlyArray<string>\n    readonly stale: ReadonlyArray<string>\n    readonly unavailable: ReadonlyArray<string>\n    readonly tombstone: boolean\n    readonly updatedAt: number\n    readonly windows: Readonly<Record<string, string>>\n  }>\n  readonly connections: ReadonlyArray<string>\n  readonly live: ReadonlyArray<string>\n  readonly gaps: ReadonlyArray<string>\n  /** What the client met and kept going past, oldest first (`RemoteModel.diagnostics`). */\n  readonly diagnostics: ReadonlyArray<RemoteDiagnostic>\n  /**\n   * The `entity\\0id\\0field` marks of reads in flight, and a\n   * `\\0connection\\0identity` mark for each query in flight. This is what \"Remote is\n   * working\" means here, and it is read from the Model rather than from the\n   * fibers doing the work: a tool that shows it shows something the Model can\n   * be replayed to, and nothing that needs the runtime to be asked.\n   */\n  readonly loading: ReadonlyArray<string>\n  /**\n   * The reads that failed and are not yet settled: queries by connection\n   * identity, entity fields by `entity\\0id\\0field` mark, each with its error.\n   */\n  readonly failures: Failures\n  readonly mutations: {\n    readonly pending: ReadonlyArray<string>\n    readonly failed: ReadonlyArray<string>\n    readonly applied: number\n  }\n}\n\nconst inspectEntry = (key: string, entry: EntityEntry): RemoteInspection['entities'][number] => ({\n  key,\n  present: [...entry.present],\n  stale: [...entry.stale],\n  unavailable: [...entry.unavailable],\n  tombstone: entry.tombstone,\n  updatedAt: entry.updatedAt,\n  windows: { ...entry.windows },\n})\n\n/** A pure, serializable view of the whole cache. */\nexport const inspectRemote = (model: RemoteModel): RemoteInspection => ({\n  entities: Object.entries(model.entities).map(([key, entry]) => inspectEntry(key, entry)),\n  connections: Object.keys(model.connections),\n  live: Object.keys(model.live),\n  gaps: [...model.gaps],\n  diagnostics: model.diagnostics,\n  loading: [...model.loading],\n  failures: model.failures,\n  mutations: {\n    pending: [...model.mutations.pending],\n    failed: [...model.mutations.failed],\n    applied: model.mutations.applied.size,\n  },\n})\n\n/** A pure, serializable view of one entity, or `undefined` if unknown. */\nexport const inspectEntity = (\n  model: RemoteModel,\n  key: string,\n): RemoteInspection['entities'][number] | undefined => {\n  const entry = model.entities[key]\n  return entry === undefined ? undefined : inspectEntry(key, entry)\n}\n\n/**\n * What one query read is, and what it currently is — data-query-DESIGN §29.1.\n *\n * Every member is gathered from something that already existed: the read was\n * always this many pieces, and nothing had ever been asked to put them in one\n * place. It is plain serializable data, so a DevTools panel, a log line and a\n * test assert on the same value.\n *\n * Two members of §29.1's sketch are **not** here, and their absence is the\n * finding rather than an omission:\n *\n * - **Surface.** A Projection does not know which Surface reads it, and often\n *   several do — so it is not a property of the read, and `explain` cannot\n *   recover it alone. Given the active Surfaces (the same record\n *   `subscriptions` takes), it reports **every** Surface reading the connection\n *   rather than guessing one, and omits the member entirely when it was not\n *   given them.\n * - **Executor.** The thing that answers a query is a `RemoteClient` Layer in\n *   the runtime, not a value in the Model, and a pure read of the Model cannot\n *   see it. That is the same boundary that makes this function pure and\n *   replayable, so it is worth more than the line of text.\n *\n * And one that the design proposed and this does not want: *expectation*\n * (required versus optional). §11 left it unbuilt for want of a consumer, and\n * the explanation was the likeliest consumer. It turns out not to need it — a\n * query's result is a connection, so the shape is a `Page`, decided by the\n * definition rather than by the read. Nothing here has an opinion about whether\n * an empty one is an error, because nothing here has to have one.\n */\nexport interface QueryExplanation {\n  /** The bound Remote domain that answers it. */\n  readonly domain: string\n  /** The definition's name. */\n  readonly query: string\n  /** The input as encoded, which is what the identity is built from. */\n  readonly input: unknown\n  /** The connection identity: definition plus canonical input, excluding the window. */\n  readonly identity: string\n  /** How much of the connection this read asks for. */\n  readonly window: QueryWindow\n  /** What it reads of each item, as the slice asked of the server. */\n  readonly select: RelationRequirement\n  /**\n   * What the query means, as readable text — `Query.show`, and so neither SQL\n   * nor whatever the backend compiled. Absent for a definition made with\n   * `Query.make`, whose meaning lives on the server that answers it.\n   */\n  readonly body?: string | undefined\n  /**\n   * The fields, inputs and operations the body reads; absent with the body.\n   * Plain data, so it serializes: a field is its Entity's name and key, which\n   * is unambiguous because a query reads one Entity.\n   */\n  readonly dependencies?: ExplainedDependencies | undefined\n  /** What the read answers from this Model right now. */\n  readonly state: RemoteData<unknown>['_tag']\n  /**\n   * The active Surfaces reading this connection at this Model, if the active\n   * record was supplied. Plural because several may, which is why a Projection\n   * cannot carry the answer itself.\n   */\n  readonly surfaces?: ReadonlyArray<string> | undefined\n  /**\n   * Why each of those Surfaces is active, where it was placed with\n   * `Surface.when` — the Model path and the tag, without running anything. A\n   * Surface placed with `Surface.at` has no entry: a callback cannot be read.\n   */\n  readonly activation?:\n    | ReadonlyArray<{\n        readonly surface: string\n        readonly path: readonly string[]\n        readonly tag: string\n      }>\n    | undefined\n}\n"],"mappings":";AAsDA,MAAM,gBAAgB,KAAa,WAA8D;CAC/F;CACA,SAAS,CAAC,GAAG,MAAM,OAAO;CAC1B,OAAO,CAAC,GAAG,MAAM,KAAK;CACtB,aAAa,CAAC,GAAG,MAAM,WAAW;CAClC,WAAW,MAAM;CACjB,WAAW,MAAM;CACjB,SAAS,EAAE,GAAG,MAAM,QAAQ;AAC9B;;AAGA,MAAa,iBAAiB,WAA0C;CACtE,UAAU,OAAO,QAAQ,MAAM,QAAQ,CAAC,CAAC,KAAK,CAAC,KAAK,WAAW,aAAa,KAAK,KAAK,CAAC;CACvF,aAAa,OAAO,KAAK,MAAM,WAAW;CAC1C,MAAM,OAAO,KAAK,MAAM,IAAI;CAC5B,MAAM,CAAC,GAAG,MAAM,IAAI;CACpB,aAAa,MAAM;CACnB,SAAS,CAAC,GAAG,MAAM,OAAO;CAC1B,UAAU,MAAM;CAChB,WAAW;EACT,SAAS,CAAC,GAAG,MAAM,UAAU,OAAO;EACpC,QAAQ,CAAC,GAAG,MAAM,UAAU,MAAM;EAClC,SAAS,MAAM,UAAU,QAAQ;CACnC;AACF;;AAGA,MAAa,iBACX,OACA,QACqD;CACrD,MAAM,QAAQ,MAAM,SAAS;CAC7B,OAAO,UAAU,KAAA,IAAY,KAAA,IAAY,aAAa,KAAK,KAAK;AAClE"}

package/dist/json-DowLl1eB.d.ts

@@ -0,0 +1,52 @@
+import { n as RemoteJsonClient } from "./client-B055kQuP.js";
+import { Schema } from "effect";
+/** A request: which of Remote's calls, and its payload as the RPC protocol encodes it. */
+declare const RemoteJsonRequest: Schema.Struct<{
+  readonly operation: Schema.Literals<readonly ["read", "query", "mutate"]>;
+  readonly payload: Schema.Unknown;
+}>;
+type RemoteJsonRequest = typeof RemoteJsonRequest.Type;
+/** An answer: the call's result, or why there is none. */
+declare const RemoteJsonAnswer: Schema.Union<readonly [Schema.Struct<{
+  readonly result: Schema.Unknown;
+}>, Schema.Struct<{
+  readonly error: Schema.String;
+  readonly refusal: Schema.optional<Schema.Unknown>;
+  /** Who is asking was refused, with the application's reason when it gave one. */
+  readonly forbidden: Schema.optional<Schema.Struct<{
+    readonly reason: Schema.optional<Schema.String>;
+  }>>;
+  /** Who is asking could not be told, with the reason when one was given; a 401. */
+  readonly unauthenticated: Schema.optional<Schema.Struct<{
+    readonly reason: Schema.optional<Schema.String>;
+  }>>;
+}>]>;
+type RemoteJsonAnswer = typeof RemoteJsonAnswer.Type;
+/**
+ * Sends one request's text and resolves with its answer as parsed JSON. It
+ * rejects when nothing came back, and the call fails with that message. A
+ * value that is not a `RemoteJsonAnswer` is no answer either: a mutation fails
+ * `RemoteUnreachable` for both, a read or a query its own error, which is
+ * retried like any failed read.
+ */
+type RemoteJsonSend = (request: string) => Promise<unknown>;
+/** Remote's client over `send`, for `Remote.clientLayer`. */
+declare const json: (send: RemoteJsonSend) => RemoteJsonClient;
+/**
+ * Remote's client over HTTP: each call a `POST` of the request to `url`, the
+ * answer its JSON body. A body that is not JSON, or one under 408, 429, 502,
+ * 503 or 504, is no answer: a mutation fails `RemoteUnreachable`, so a
+ * durable one is sent again. A 401 is answered as
+ * unauthenticated, for every call kind, and a 403 as forbidden, whatever the
+ * body says: the server's own says why, and middleware in front of Remote
+ * may say anything.
+ * `headers` is read per request, so a token that changes reaches the next
+ * call. `fetch` defaults to the global one; pass it to route calls through
+ * another implementation in tests.
+ */
+declare const http: (url: string, options?: {
+  readonly headers?: (() => Readonly<Record<string, string>>) | undefined;
+  readonly fetch?: typeof fetch | undefined;
+}) => RemoteJsonClient;
+export { json as a, http as i, RemoteJsonRequest as n, RemoteJsonSend as r, RemoteJsonAnswer as t };
+//# sourceMappingURL=json-DowLl1eB.d.ts.map

package/dist/json-DowLl1eB.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-DowLl1eB.d.ts","names":[],"sources":["../src/json.ts"],"mappings":";;;cAmBa,mBAAiB,OAAA;;;;KAIlB,2BAA2B,kBAAkB;;cAG5C,kBAAgB,OAAA,gBAAA,OAAA;;;;;;;;;;;;;;KAWjB,0BAA0B,iBAAiB;;;;;;;;KAa3C,kBAAkB,oBAAoB;;cAgDrC,OAAI,MAAU,mBAAiB;;;;;;;;;;;;;cAmF/B,OAAI,aACJ;WAEA,iBAAiB,SAAS;WAC1B,eAAe;MAEzB"}

package/dist/json.d.ts

@@ -0,0 +1,2 @@
+import { a as json, i as http, n as RemoteJsonRequest, r as RemoteJsonSend, t as RemoteJsonAnswer } from "./json-DowLl1eB.js";
+export { RemoteJsonAnswer, RemoteJsonRequest, RemoteJsonSend, http, json };

package/dist/json.js

@@ -0,0 +1,123 @@
+import { RemoteForbidden, RemoteMutationError, RemoteQueryError, RemoteReadError, RemoteUnauthenticated, RemoteUnreachable } from "./wire.js";
+import { Effect, Option, Schema, Stream } from "effect";
+// src/json.ts
+/**
+* Remote's three calls as JSON: one request, `{ operation, payload }`, and one
+* answer, `{ result }` or `{ error }`. `RemoteServer.answer` is the other end.
+* The client takes any way of sending the request text and receiving the
+* answer, so the same client speaks HTTP (`http`), a worker, or a server
+* running in the page. There is no live stream over it.
+*/
+/** A request: which of Remote's calls, and its payload as the RPC protocol encodes it. */
+const RemoteJsonRequest = Schema.Struct({
+	operation: Schema.Literals([
+		"read",
+		"query",
+		"mutate"
+	]),
+	payload: Schema.Unknown
+});
+/** An answer: the call's result, or why there is none. */
+const RemoteJsonAnswer = Schema.Union([Schema.Struct({ result: Schema.Unknown }), Schema.Struct({
+	error: Schema.String,
+	refusal: Schema.optional(Schema.Unknown),
+	/** Who is asking was refused, with the application's reason when it gave one. */
+	forbidden: Schema.optional(Schema.Struct({ reason: Schema.optional(Schema.String) })),
+	/** Who is asking could not be told, with the reason when one was given; a 401. */
+	unauthenticated: Schema.optional(Schema.Struct({ reason: Schema.optional(Schema.String) }))
+})]);
+const decodeAnswer = Schema.decodeUnknownEffect(RemoteJsonAnswer);
+const call = (send, operation, payload, fail, unreached) => Effect.tryPromise({
+	try: () => send(JSON.stringify({
+		operation,
+		payload
+	})),
+	catch: (error) => unreached(error instanceof Error ? error.message : String(error))
+}).pipe(Effect.flatMap((answer) => decodeAnswer(answer).pipe(Effect.mapError(() => unreached("The server answered with something that is not an answer")))), Effect.flatMap((answer) => "error" in answer ? Effect.fail(fail(answer)) : Effect.succeed(answer.result)));
+/**
+* An error answer as its call's failure: a refusal of who is asking, of
+* every call kind alike, or the call's own error.
+*/
+const failure = (own) => (answer) => answer.unauthenticated === void 0 ? own(answer) : new RemoteUnauthenticated({
+	message: answer.error,
+	...answer.unauthenticated.reason === void 0 ? {} : { reason: answer.unauthenticated.reason }
+});
+/** Remote's client over `send`, for `Remote.clientLayer`. */
+const json = (send) => ({
+	FoldkitRemoteRead: (payload) => call(send, "read", payload, failure(({ error }) => new RemoteReadError({ message: error })), (message) => new RemoteReadError({ message })),
+	FoldkitRemoteQuery: (payload) => call(send, "query", payload, failure(({ error }) => new RemoteQueryError({ message: error })), (message) => new RemoteQueryError({ message })),
+	FoldkitRemoteMutate: (payload) => call(send, "mutate", payload, failure(({ error, refusal, forbidden }) => forbidden === void 0 ? new RemoteMutationError({
+		message: error,
+		refusal
+	}) : new RemoteForbidden({
+		message: error,
+		...forbidden.reason === void 0 ? {} : { reason: forbidden.reason }
+	})), (message) => new RemoteUnreachable({ message })),
+	FoldkitRemoteLive: () => Stream.empty
+});
+/** A body that did not parse, told apart from every value one can parse to, `null` included. */
+const notJson = Symbol("not JSON");
+const Reason = Schema.Struct({ reason: Schema.optional(Schema.String) });
+/** A refusal in Remote's own words, by the key it is given under. */
+const ownRefusal = {
+	unauthenticated: Schema.decodeUnknownOption(Schema.Struct({
+		error: Schema.String,
+		unauthenticated: Reason
+	})),
+	forbidden: Schema.decodeUnknownOption(Schema.Struct({
+		error: Schema.String,
+		forbidden: Reason
+	}))
+};
+/**
+* A 401's or 403's answer, whatever its body: Remote's own refusal as it is,
+* and anything else (`{ error }` from middleware, HTML, a shape of its own)
+* as the status alone, so it never reaches a decoder that would call it a
+* broken answer.
+*/
+const refusalOf = (body, kind, status) => Option.getOrElse(ownRefusal[kind](body), () => ({
+	error: status,
+	[kind]: {}
+}));
+/**
+* Statuses Remote's server never answers with, which say the request was not
+* served (yet): a body under one is a gateway's or a limiter's, never an answer.
+*/
+const unanswered = /* @__PURE__ */ new Set([
+	408,
+	429,
+	502,
+	503,
+	504
+]);
+/**
+* Remote's client over HTTP: each call a `POST` of the request to `url`, the
+* answer its JSON body. A body that is not JSON, or one under 408, 429, 502,
+* 503 or 504, is no answer: a mutation fails `RemoteUnreachable`, so a
+* durable one is sent again. A 401 is answered as
+* unauthenticated, for every call kind, and a 403 as forbidden, whatever the
+* body says: the server's own says why, and middleware in front of Remote
+* may say anything.
+* `headers` is read per request, so a token that changes reaches the next
+* call. `fetch` defaults to the global one; pass it to route calls through
+* another implementation in tests.
+*/
+const http = (url, options = {}) => json(async (request) => {
+	const response = await (options.fetch ?? fetch)(url, {
+		method: "POST",
+		headers: {
+			"content-type": "application/json",
+			...options.headers?.()
+		},
+		body: request
+	});
+	const status = `${response.status} ${response.statusText}`;
+	const body = await response.json().catch(() => notJson);
+	if (response.status === 401) return refusalOf(body, "unauthenticated", status);
+	if (response.status === 403) return refusalOf(body, "forbidden", status);
+	if (body === notJson || unanswered.has(response.status)) throw new Error(status);
+	return body;
+});
+export { RemoteJsonAnswer, RemoteJsonRequest, http, json };
+
+//# sourceMappingURL=json.js.map

package/dist/json.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"json.js","names":[],"sources":["../src/json.ts"],"sourcesContent":["/**\n * Remote's three calls as JSON: one request, `{ operation, payload }`, and one\n * answer, `{ result }` or `{ error }`. `RemoteServer.answer` is the other end.\n * The client takes any way of sending the request text and receiving the\n * answer, so the same client speaks HTTP (`http`), a worker, or a server\n * running in the page. There is no live stream over it.\n */\nimport { Effect, Option, Schema, Stream } from 'effect'\nimport type { RemoteJsonClient } from './client.js'\nimport {\n  RemoteForbidden,\n  RemoteMutationError,\n  RemoteQueryError,\n  RemoteReadError,\n  RemoteUnauthenticated,\n  RemoteUnreachable,\n} from './wire.js'\n\n/** A request: which of Remote's calls, and its payload as the RPC protocol encodes it. */\nexport const RemoteJsonRequest = Schema.Struct({\n  operation: Schema.Literals(['read', 'query', 'mutate']),\n  payload: Schema.Unknown,\n})\nexport type RemoteJsonRequest = typeof RemoteJsonRequest.Type\n\n/** An answer: the call's result, or why there is none. */\nexport const RemoteJsonAnswer = Schema.Union([\n  Schema.Struct({ result: Schema.Unknown }),\n  Schema.Struct({\n    error: Schema.String,\n    refusal: Schema.optional(Schema.Unknown),\n    /** Who is asking was refused, with the application's reason when it gave one. */\n    forbidden: Schema.optional(Schema.Struct({ reason: Schema.optional(Schema.String) })),\n    /** Who is asking could not be told, with the reason when one was given; a 401. */\n    unauthenticated: Schema.optional(Schema.Struct({ reason: Schema.optional(Schema.String) })),\n  }),\n])\nexport type RemoteJsonAnswer = typeof RemoteJsonAnswer.Type\n\ntype ErrorAnswer = Extract<RemoteJsonAnswer, { readonly error: string }>\n\nconst decodeAnswer = Schema.decodeUnknownEffect(RemoteJsonAnswer)\n\n/**\n * Sends one request's text and resolves with its answer as parsed JSON. It\n * rejects when nothing came back, and the call fails with that message. A\n * value that is not a `RemoteJsonAnswer` is no answer either: a mutation fails\n * `RemoteUnreachable` for both, a read or a query its own error, which is\n * retried like any failed read.\n */\nexport type RemoteJsonSend = (request: string) => Promise<unknown>\n\nconst call = <A, E, U>(\n  send: RemoteJsonSend,\n  operation: RemoteJsonRequest['operation'],\n  payload: unknown,\n  fail: (answer: ErrorAnswer) => E,\n  /** What no answer coming back is: the request was not sent, or what came back was no answer. */\n  unreached: (message: string) => U,\n): Effect.Effect<A, E | U> =>\n  Effect.tryPromise({\n    try: () => send(JSON.stringify({ operation, payload })),\n    catch: error => unreached(error instanceof Error ? error.message : String(error)),\n  }).pipe(\n    Effect.flatMap(answer =>\n      decodeAnswer(answer).pipe(\n        // JSON that is not an answer came from something in front of Remote\n        // (a gateway's `{}`), so the request may have reached the server.\n        Effect.mapError(() =>\n          unreached('The server answered with something that is not an answer'),\n        ),\n      ),\n    ),\n    Effect.flatMap(answer =>\n      'error' in answer\n        ? Effect.fail(fail(answer))\n        : // The answer is to the request this call sent, so its result is this call's.\n          Effect.succeed(answer.result as A),\n    ),\n  )\n\n/**\n * An error answer as its call's failure: a refusal of who is asking, of\n * every call kind alike, or the call's own error.\n */\nconst failure =\n  <E>(own: (answer: ErrorAnswer) => E) =>\n  (answer: ErrorAnswer): E | RemoteUnauthenticated =>\n    answer.unauthenticated === undefined\n      ? own(answer)\n      : new RemoteUnauthenticated({\n          message: answer.error,\n          ...(answer.unauthenticated.reason === undefined\n            ? {}\n            : { reason: answer.unauthenticated.reason }),\n        })\n\n/** Remote's client over `send`, for `Remote.clientLayer`. */\nexport const json = (send: RemoteJsonSend): RemoteJsonClient => ({\n  FoldkitRemoteRead: payload =>\n    call(\n      send,\n      'read',\n      payload,\n      failure(({ error }) => new RemoteReadError({ message: error })),\n      message => new RemoteReadError({ message }),\n    ),\n  FoldkitRemoteQuery: payload =>\n    call(\n      send,\n      'query',\n      payload,\n      failure(({ error }) => new RemoteQueryError({ message: error })),\n      message => new RemoteQueryError({ message }),\n    ),\n  FoldkitRemoteMutate: payload =>\n    call(\n      send,\n      'mutate',\n      payload,\n      failure(({ error, refusal, forbidden }) =>\n        forbidden === undefined\n          ? new RemoteMutationError({ message: error, refusal })\n          : new RemoteForbidden({\n              message: error,\n              ...(forbidden.reason === undefined ? {} : { reason: forbidden.reason }),\n            }),\n      ),\n      // A mutation that may not have reached the server is told apart, so a\n      // durable one is sent again rather than settled.\n      message => new RemoteUnreachable({ message }),\n    ),\n  FoldkitRemoteLive: () => Stream.empty,\n})\n\n/** A body that did not parse, told apart from every value one can parse to, `null` included. */\nconst notJson = Symbol('not JSON')\n\nconst Reason = Schema.Struct({ reason: Schema.optional(Schema.String) })\n/** A refusal in Remote's own words, by the key it is given under. */\nconst ownRefusal: Record<\n  'unauthenticated' | 'forbidden',\n  (body: unknown) => Option.Option<Partial<RemoteJsonAnswer>>\n> = {\n  unauthenticated: Schema.decodeUnknownOption(\n    Schema.Struct({ error: Schema.String, unauthenticated: Reason }),\n  ),\n  forbidden: Schema.decodeUnknownOption(Schema.Struct({ error: Schema.String, forbidden: Reason })),\n}\n\n/**\n * A 401's or 403's answer, whatever its body: Remote's own refusal as it is,\n * and anything else (`{ error }` from middleware, HTML, a shape of its own)\n * as the status alone, so it never reaches a decoder that would call it a\n * broken answer.\n */\nconst refusalOf = (\n  body: unknown,\n  kind: 'unauthenticated' | 'forbidden',\n  status: string,\n): Partial<RemoteJsonAnswer> =>\n  Option.getOrElse(ownRefusal[kind](body), () => ({ error: status, [kind]: {} }))\n\n/**\n * Statuses Remote's server never answers with, which say the request was not\n * served (yet): a body under one is a gateway's or a limiter's, never an answer.\n */\nconst unanswered: ReadonlySet<number> = new Set([408, 429, 502, 503, 504])\n\n/**\n * Remote's client over HTTP: each call a `POST` of the request to `url`, the\n * answer its JSON body. A body that is not JSON, or one under 408, 429, 502,\n * 503 or 504, is no answer: a mutation fails `RemoteUnreachable`, so a\n * durable one is sent again. A 401 is answered as\n * unauthenticated, for every call kind, and a 403 as forbidden, whatever the\n * body says: the server's own says why, and middleware in front of Remote\n * may say anything.\n * `headers` is read per request, so a token that changes reaches the next\n * call. `fetch` defaults to the global one; pass it to route calls through\n * another implementation in tests.\n */\nexport const http = (\n  url: string,\n  options: {\n    readonly headers?: (() => Readonly<Record<string, string>>) | undefined\n    readonly fetch?: typeof fetch | undefined\n  } = {},\n): RemoteJsonClient =>\n  json(async request => {\n    const via = options.fetch ?? fetch\n    const response = await via(url, {\n      method: 'POST',\n      headers: { 'content-type': 'application/json', ...options.headers?.() },\n      body: request,\n    })\n    const status = `${response.status} ${response.statusText}`\n    const body: unknown = await response.json().catch(() => notJson)\n    if (response.status === 401) return refusalOf(body, 'unauthenticated', status)\n    if (response.status === 403) return refusalOf(body, 'forbidden', status)\n    if (body === notJson || unanswered.has(response.status)) throw new Error(status)\n    return body\n  })\n"],"mappings":";;;;;;;;;;;AAmBA,MAAa,oBAAoB,OAAO,OAAO;CAC7C,WAAW,OAAO,SAAS;EAAC;EAAQ;EAAS;CAAQ,CAAC;CACtD,SAAS,OAAO;AAClB,CAAC;;AAID,MAAa,mBAAmB,OAAO,MAAM,CAC3C,OAAO,OAAO,EAAE,QAAQ,OAAO,QAAQ,CAAC,GACxC,OAAO,OAAO;CACZ,OAAO,OAAO;CACd,SAAS,OAAO,SAAS,OAAO,OAAO;;CAEvC,WAAW,OAAO,SAAS,OAAO,OAAO,EAAE,QAAQ,OAAO,SAAS,OAAO,MAAM,EAAE,CAAC,CAAC;;CAEpF,iBAAiB,OAAO,SAAS,OAAO,OAAO,EAAE,QAAQ,OAAO,SAAS,OAAO,MAAM,EAAE,CAAC,CAAC;AAC5F,CAAC,CACH,CAAC;AAKD,MAAM,eAAe,OAAO,oBAAoB,gBAAgB;AAWhE,MAAM,QACJ,MACA,WACA,SACA,MAEA,cAEA,OAAO,WAAW;CAChB,WAAW,KAAK,KAAK,UAAU;EAAE;EAAW;CAAQ,CAAC,CAAC;CACtD,QAAO,UAAS,UAAU,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK,CAAC;AAClF,CAAC,CAAC,CAAC,KACD,OAAO,SAAQ,WACb,aAAa,MAAM,CAAC,CAAC,KAGnB,OAAO,eACL,UAAU,0DAA0D,CACtE,CACF,CACF,GACA,OAAO,SAAQ,WACb,WAAW,SACP,OAAO,KAAK,KAAK,MAAM,CAAC,IAExB,OAAO,QAAQ,OAAO,MAAW,CACvC,CACF;;;;;AAMF,MAAM,WACA,SACH,WACC,OAAO,oBAAoB,KAAA,IACvB,IAAI,MAAM,IACV,IAAI,sBAAsB;CACxB,SAAS,OAAO;CAChB,GAAI,OAAO,gBAAgB,WAAW,KAAA,IAClC,CAAC,IACD,EAAE,QAAQ,OAAO,gBAAgB,OAAO;AAC9C,CAAC;;AAGT,MAAa,QAAQ,UAA4C;CAC/D,oBAAmB,YACjB,KACE,MACA,QACA,SACA,SAAS,EAAE,YAAY,IAAI,gBAAgB,EAAE,SAAS,MAAM,CAAC,CAAC,IAC9D,YAAW,IAAI,gBAAgB,EAAE,QAAQ,CAAC,CAC5C;CACF,qBAAoB,YAClB,KACE,MACA,SACA,SACA,SAAS,EAAE,YAAY,IAAI,iBAAiB,EAAE,SAAS,MAAM,CAAC,CAAC,IAC/D,YAAW,IAAI,iBAAiB,EAAE,QAAQ,CAAC,CAC7C;CACF,sBAAqB,YACnB,KACE,MACA,UACA,SACA,SAAS,EAAE,OAAO,SAAS,gBACzB,cAAc,KAAA,IACV,IAAI,oBAAoB;EAAE,SAAS;EAAO;CAAQ,CAAC,IACnD,IAAI,gBAAgB;EAClB,SAAS;EACT,GAAI,UAAU,WAAW,KAAA,IAAY,CAAC,IAAI,EAAE,QAAQ,UAAU,OAAO;CACvE,CAAC,CACP,IAGA,YAAW,IAAI,kBAAkB,EAAE,QAAQ,CAAC,CAC9C;CACF,yBAAyB,OAAO;AAClC;;AAGA,MAAM,UAAU,OAAO,UAAU;AAEjC,MAAM,SAAS,OAAO,OAAO,EAAE,QAAQ,OAAO,SAAS,OAAO,MAAM,EAAE,CAAC;;AAEvE,MAAM,aAGF;CACF,iBAAiB,OAAO,oBACtB,OAAO,OAAO;EAAE,OAAO,OAAO;EAAQ,iBAAiB;CAAO,CAAC,CACjE;CACA,WAAW,OAAO,oBAAoB,OAAO,OAAO;EAAE,OAAO,OAAO;EAAQ,WAAW;CAAO,CAAC,CAAC;AAClG;;;;;;;AAQA,MAAM,aACJ,MACA,MACA,WAEA,OAAO,UAAU,WAAW,KAAK,CAAC,IAAI,UAAU;CAAE,OAAO;EAAS,OAAO,CAAC;AAAE,EAAE;;;;;AAMhF,MAAM,6BAAkC,IAAI,IAAI;CAAC;CAAK;CAAK;CAAK;CAAK;AAAG,CAAC;;;;;;;;;;;;;AAczE,MAAa,QACX,KACA,UAGI,CAAC,MAEL,KAAK,OAAM,YAAW;CAEpB,MAAM,WAAW,OADL,QAAQ,SAAS,MAAA,CACF,KAAK;EAC9B,QAAQ;EACR,SAAS;GAAE,gBAAgB;GAAoB,GAAG,QAAQ,UAAU;EAAE;EACtE,MAAM;CACR,CAAC;CACD,MAAM,SAAS,GAAG,SAAS,OAAO,GAAG,SAAS;CAC9C,MAAM,OAAgB,MAAM,SAAS,KAAK,CAAC,CAAC,YAAY,OAAO;CAC/D,IAAI,SAAS,WAAW,KAAK,OAAO,UAAU,MAAM,mBAAmB,MAAM;CAC7E,IAAI,SAAS,WAAW,KAAK,OAAO,UAAU,MAAM,aAAa,MAAM;CACvE,IAAI,SAAS,WAAW,WAAW,IAAI,SAAS,MAAM,GAAG,MAAM,IAAI,MAAM,MAAM;CAC/E,OAAO;AACT,CAAC"}

package/dist/law.d.ts

@@ -0,0 +1,56 @@
+import { E as MutationDescriptor } from "./optimistic-CECsfNGY.js";
+import { c as QueryRef } from "./query-BuIU93xA.js";
+import { t as RemoteClient } from "./client-B055kQuP.js";
+import { RemoteDomain } from "./index.js";
+import { Effect } from "effect";
+import { AnyEntity } from "foldkit-entity";
+/** One part both sides answered, and what each said. */
+export interface LawPart {
+  /** `Entity:id.field`, `Entity:id` for whether the row is there, or a list's identity. */
+  readonly part: string;
+  /** When the client said it: while the write was pending, or once its answer had landed. */
+  readonly when: 'pending' | 'answered';
+  readonly client: unknown;
+  readonly server: unknown;
+}
+/**
+ * What `Law.check` compared: the parts both sides agreed on, pending and
+ * answered, and those they did not.
+ */
+export interface LawReport {
+  readonly agreed: ReadonlyArray<string>;
+  readonly disagreed: ReadonlyArray<LawPart>;
+  /** Parts the client left to the server: a list it did not place, a field it did not foresee. */
+  readonly unknown: ReadonlyArray<string>;
+}
+export interface LawConfig<AppModel> {
+  /** The application's Model before the client holds anything; `Remote.make`'s viewer reads it. */
+  readonly model: AppModel;
+  /** The rows the client holds, each read whole as the server's principal sees it. */
+  readonly holds: ReadonlyArray<{
+    readonly entity: AnyEntity;
+    readonly ids: ReadonlyArray<string>;
+  }>;
+  /** Lists the client holds, wholly loaded, whose placements are compared. */
+  readonly lists?: ReadonlyArray<QueryRef<string, unknown>> | undefined;
+  readonly mutation: MutationDescriptor<string, any, any, any>;
+  readonly input: unknown;
+  /** When the reader acted: what the client predicts with and the request sends. */
+  readonly now: number;
+}
+/**
+ * Runs `config.mutation` as the client would, through `Data.mutate` over a
+ * Model holding what the server sends this principal, and through the server
+ * (`RemoteClient`: `Remote.clientLayer(RemoteServer.handlers(server, principal))`),
+ * then compares each predicted field, each predicted deletion and each list's
+ * order with what the server answers after the write.
+ *
+ * Fails when nothing was compared: two sides that both said nothing agree,
+ * and that agreement is no evidence.
+ */
+declare const check: <AppModel>(Data: RemoteDomain<AppModel, any, any, any, any>, config: LawConfig<AppModel>) => Effect.Effect<LawReport, unknown, RemoteClient>;
+export declare const Law: {
+  check: typeof check;
+};
+export {};
+//# sourceMappingURL=law.d.ts.map

package/dist/law.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"law.d.ts","names":[],"sources":["../src/law.ts"],"mappings":";;;;;;;iBAoBiB;;WAEN;;WAEA;WACA;WACA;;;;;;iBAOM;WACN,QAAQ;WACR,WAAW,cAAc;;WAEzB,SAAS;;iBAGH,UAAU;;WAEhB,OAAO;;WAEP,OAAO;aAAyB,QAAQ;aAAoB,KAAK;;;WAEjE,QAAQ,cAAc;WACtB,UAAU;WACV;;WAEA;;;;;;;;;;;;cAsCL,QAAS,UAAQ,MACf,aAAa,+BAA6B,QACxC,UAAU,cACjB,OAAO,OAAO,oBAAoB;qBAoLxB"}