foldkit-remote 0.20.0 → 0.22.0

package/dist/remoteData-mK1suYi1.d.ts

@@ -0,0 +1,148 @@
+import { Option, Schema } from "effect";
+interface RemoteError {
+  readonly _tag: string;
+  readonly message: string;
+  /**
+   * A refused mutation's refusal, encoded as the server sent it. Read it
+   * decoded, by its mutation, with `Data.refusal`.
+   */
+  readonly refusal?: unknown;
+  /**
+   * Why the server refused who is asking (`_tag: 'Unauthenticated'` or
+   * `'Forbidden'`), when it said. Read it with `RemoteData.denied`.
+   */
+  readonly reason?: string | undefined;
+}
+/**
+ * The server would not answer who is asking: their session ended or was
+ * never there (`Unauthenticated`, a 401), or they may not (`Forbidden`, a
+ * 403). `reason` is the server's sentence, when it gave one. Not a mutation's
+ * declared `refusal`, which the server answered and `Data.refusal` reads.
+ */
+declare const Denied: import("foldkit/schema").TaggedUnion<{
+  readonly Unauthenticated: {
+    reason: Schema.Option<Schema.String>;
+  };
+  readonly Forbidden: {
+    reason: Schema.Option<Schema.String>;
+  };
+}>;
+type Denied = typeof Denied.Type;
+type RemoteData<A> = {
+  readonly _tag: 'Initial';
+} | {
+  readonly _tag: 'Loading';
+} | {
+  readonly _tag: 'Ready';
+  readonly value: A;
+} | {
+  readonly _tag: 'Refreshing';
+  readonly value: A;
+} | {
+  readonly _tag: 'Failed';
+  readonly error: RemoteError;
+  readonly previous?: A;
+} | {
+  readonly _tag: 'NotFound';
+};
+declare const remoteErrorSchema: Schema.Struct<{
+  readonly _tag: Schema.String;
+  readonly message: Schema.String;
+  readonly refusal: Schema.optional<Schema.Unknown>;
+  readonly reason: Schema.optional<Schema.String>;
+}>;
+/**
+ * What `RemoteData.render` tells the `data` branch about the value it is
+ * given: whether a newer answer is on its way, and whether this one is what
+ * was last known good before a read failed. It is one tag rather than two
+ * booleans because a value cannot be both at once, and a type that can say so
+ * invites a view to handle a state that never arrives. Fold it with
+ * `Freshness.match`.
+ */
+declare const Freshness: import("foldkit/schema").TaggedUnion<{
+  readonly Fresh: {};
+  readonly Refreshing: {};
+  readonly Stale: {
+    error: Schema.Struct<{
+      readonly _tag: Schema.String;
+      readonly message: Schema.String;
+      readonly refusal: Schema.optional<Schema.Unknown>;
+      readonly reason: Schema.optional<Schema.String>;
+    }>;
+  };
+}>;
+type Freshness = typeof Freshness.Type;
+declare const remoteDataSchema: <A>(value: Schema.Schema<A>) => Schema.Codec<RemoteData<A>, unknown>;
+declare const RemoteData: {
+  /**
+   * The `RemoteData` schema for a value schema. Exposed so a `RemoteData` can
+   * be embedded in a hand-written Model schema, not only through `Remote.select`.
+   */
+  schema: <A>(value: Schema.Schema<A>) => Schema.Schema<RemoteData<A>>;
+  /**
+   * Whether the read has an answer: `Ready`, `Refreshing`, `Failed` or
+   * `NotFound`. `Initial` and `Loading` are still waiting for one.
+   */
+  answered: <A>(data: RemoteData<A>) => boolean;
+  /** Exhaustive: omitting a state is a compile error. */
+  match: <A, R>(data: RemoteData<A>, cases: {
+    readonly Initial: () => R;
+    readonly Loading: () => R;
+    readonly Ready: (value: A) => R;
+    readonly Refreshing: (value: A) => R;
+    readonly Failed: (error: RemoteError, previous: Option.Option<A>) => R;
+    readonly NotFound: () => R;
+  }) => R;
+  /**
+   * The view-oriented fold: the six states as the three things a view actually
+   * draws, under the policy that useful data stays on screen. A value that is
+   * being refetched, or that a later read failed to replace, still reaches
+   * `data` — with `freshness` saying which — instead of being replaced by a
+   * spinner or an error the reader cannot act on.
+   *
+   * ```ts
+   * RemoteData.render(model.user, {
+   *   loading: () => UserSkeleton(),
+   *   notFound: () => NoSuchUser(),
+   *   failed: error => ErrorView(error),
+   *   data: (user, freshness) => UserView({ user, dimmed: freshness._tag !== 'Fresh' }),
+   * })
+   * ```
+   *
+   * `notFound` is its own branch and not optional: a row the server answered
+   * for and does not have is neither loading nor a failure, and drawing it as
+   * either is a spinner that never ends or an error nobody can fix.
+   *
+   * This does not replace `match`, which is the exhaustive fold over the states
+   * themselves. Reach for `match` when the six states really do draw
+   * differently, and for this when they draw the usual three ways.
+   */
+  render: <A, R>(data: RemoteData<A>, cases: {
+    readonly loading: () => R;
+    readonly notFound: () => R;
+    readonly failed: (error: RemoteError) => R;
+    readonly data: (value: A, freshness: Freshness) => R;
+  }) => R;
+  /**
+   * The denial a failure was, typed, or none for any other failure (a
+   * network error, a protocol mismatch): what to read before telling a reader
+   * to sign in again.
+   *
+   * ```ts
+   * Option.match(RemoteData.denied(error), {
+   *   onNone: () => 'Could not load',
+   *   onSome: Denied.match({ Unauthenticated: () => 'Sign in again', Forbidden: () => 'Not yours' }),
+   * })
+   * ```
+   */
+  denied: (error: RemoteError) => Option.Option<Denied>;
+  /**
+   * Whether nothing answered (`RemoteUnreachable`): the request was not sent,
+   * or what came back was no Remote answer, so a write may or may not have
+   * run. A failure the server answered (a refusal, a denial) is not one.
+   */
+  isUnreachable: (error: RemoteError) => boolean;
+  map: <A, B>(data: RemoteData<A>, f: (value: A) => B) => RemoteData<B>;
+};
+export { remoteDataSchema as a, RemoteError as i, Freshness as n, remoteErrorSchema as o, RemoteData as r, Denied as t };
+//# sourceMappingURL=remoteData-mK1suYi1.d.ts.map

package/dist/remoteData-mK1suYi1.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"remoteData-mK1suYi1.d.ts","names":[],"sources":["../src/remoteData.ts"],"mappings":";UAKiB;WACN;WACA;;;;;WAKA;;;;;WAKA;;;;;;;;cASE,iCAAM;;IACE,QAAM,OAAA,OAAA,OAAA;;;IACZ,QAAM,OAAA,OAAA,OAAA;;;KAET,gBAAgB,OAAO;KAUvB,WAAW;WACR;;WACA;;WACA;WAAwB,OAAO;;WAC/B;WAA6B,OAAO;;WACpC;WAAyB,OAAO;WAAsB,WAAW;;WACjE;;cAEF,mBAAiB,OAAA;;;;;;;;;;;;;;cAejB,oCAAS;;;;IAGX,OAAK,OAAA;;;;;;;;KAEJ,mBAAmB,UAAU;cAW5B,mBAAoB,GAAC,OACzB,OAAO,OAAO,OACpB,OAAO,MAAM,WAAW;cAmBd;;;;;EAKX,SAAS,GAAC,OAAS,OAAO,OAAO,OAAK,OAAO,OAAO,WAAW;;;;;EAM/D,WAAW,GAAC,MAAQ,WAAW;;EAW/B,QAAQ,GAAG,GAAC,MACJ,WAAW,IAAE;aAER,eAAe;aACf,eAAe;aACf,QAAQ,OAAO,MAAM;aACrB,aAAa,OAAO,MAAM;aAC1B,SAAS,OAAO,aAAa,UAAU,OAAO,OAAO,OAAO;aAC5D,gBAAgB;QAE1B;;;;;;;;;;;;;;;;;;;;;;;;;EA4CH,SAAS,GAAG,GAAC,MACL,WAAW,IAAE;aAER,eAAe;aACf,gBAAgB;aAChB,SAAS,OAAO,gBAAgB;aAChC,OAAO,OAAO,GAAG,WAAW,cAAc;QAEpD;;;;;;;;;;;;;EA8BH,SAAM,OAAU,gBAAc,OAAO,OAAO;;;;;;EAW5C,gBAAa,OAAU;EAIvB,MAAM,GAAG,GAAC,MAAQ,WAAW,IAAE,IAAM,OAAO,MAAM,MAAI,WAAW"}

package/dist/remoteData.d.ts

@@ -0,0 +1,2 @@
+import { a as remoteDataSchema, i as RemoteError, n as Freshness, o as remoteErrorSchema, r as RemoteData, t as Denied } from "./remoteData-mK1suYi1.js";
+export { Denied, Freshness, RemoteData, RemoteError, remoteDataSchema, remoteErrorSchema };

package/dist/remoteData.js

@@ -0,0 +1,179 @@
+import { Option, Schema } from "effect";
+import { defineTaggedUnion } from "foldkit/schema";
+// src/remoteData.ts
+/** `RemoteData`: the state of a value the store may not hold yet. */
+/**
+* The server would not answer who is asking: their session ended or was
+* never there (`Unauthenticated`, a 401), or they may not (`Forbidden`, a
+* 403). `reason` is the server's sentence, when it gave one. Not a mutation's
+* declared `refusal`, which the server answered and `Data.refusal` reads.
+*/
+const Denied = defineTaggedUnion({
+	Unauthenticated: { reason: Schema.Option(Schema.String) },
+	Forbidden: { reason: Schema.Option(Schema.String) }
+});
+/** The tags `denied` reads: a `RemoteError`'s `_tag` is open, for any failure a transport reports. */
+const denials = /* @__PURE__ */ new Set(["Unauthenticated", "Forbidden"]);
+const isDenial = (tag) => denials.has(tag);
+const deny = {
+	Unauthenticated: Denied.Unauthenticated,
+	Forbidden: Denied.Forbidden
+};
+/** Typed by the error class, so renaming its tag is a type error here. */
+const unreachable = "Unreachable";
+const remoteErrorSchema = Schema.Struct({
+	_tag: Schema.String,
+	message: Schema.String,
+	refusal: Schema.optional(Schema.Unknown),
+	reason: Schema.optional(Schema.String)
+});
+/**
+* What `RemoteData.render` tells the `data` branch about the value it is
+* given: whether a newer answer is on its way, and whether this one is what
+* was last known good before a read failed. It is one tag rather than two
+* booleans because a value cannot be both at once, and a type that can say so
+* invites a view to handle a state that never arrives. Fold it with
+* `Freshness.match`.
+*/
+const Freshness = defineTaggedUnion({
+	Fresh: {},
+	Refreshing: {},
+	Stale: { error: remoteErrorSchema }
+});
+const fresh = Freshness.Fresh();
+const refreshing = Freshness.Refreshing();
+/** A `RemoteData` schema, so a projection that reads remote state is typed. */
+const remoteDataSchemas = /* @__PURE__ */ new WeakMap();
+const remoteDataSchema = (value) => {
+	const cached = remoteDataSchemas.get(value);
+	if (cached !== void 0) return cached;
+	const built = Schema.Union([
+		Schema.Struct({ _tag: Schema.Literal("Initial") }),
+		Schema.Struct({ _tag: Schema.Literal("Loading") }),
+		Schema.Struct({
+			_tag: Schema.Literal("Ready"),
+			value
+		}),
+		Schema.Struct({
+			_tag: Schema.Literal("Refreshing"),
+			value
+		}),
+		Schema.Struct({
+			_tag: Schema.Literal("Failed"),
+			error: remoteErrorSchema,
+			previous: Schema.optional(value)
+		}),
+		Schema.Struct({ _tag: Schema.Literal("NotFound") })
+	]);
+	remoteDataSchemas.set(value, built);
+	return built;
+};
+const RemoteData = {
+	/**
+	* The `RemoteData` schema for a value schema. Exposed so a `RemoteData` can
+	* be embedded in a hand-written Model schema, not only through `Remote.select`.
+	*/
+	schema: (value) => remoteDataSchema(value),
+	/**
+	* Whether the read has an answer: `Ready`, `Refreshing`, `Failed` or
+	* `NotFound`. `Initial` and `Loading` are still waiting for one.
+	*/
+	answered: (data) => RemoteData.match(data, {
+		Initial: () => false,
+		Loading: () => false,
+		Ready: () => true,
+		Refreshing: () => true,
+		Failed: () => true,
+		NotFound: () => true
+	}),
+	/** Exhaustive: omitting a state is a compile error. */
+	match: (data, cases) => {
+		switch (data._tag) {
+			case "Initial": return cases.Initial();
+			case "Loading": return cases.Loading();
+			case "Ready": return cases.Ready(data.value);
+			case "Refreshing": return cases.Refreshing(data.value);
+			case "Failed": return cases.Failed(data.error, data.previous === void 0 ? Option.none() : Option.some(data.previous));
+			case "NotFound": return cases.NotFound();
+		}
+	},
+	/**
+	* The view-oriented fold: the six states as the three things a view actually
+	* draws, under the policy that useful data stays on screen. A value that is
+	* being refetched, or that a later read failed to replace, still reaches
+	* `data` — with `freshness` saying which — instead of being replaced by a
+	* spinner or an error the reader cannot act on.
+	*
+	* ```ts
+	* RemoteData.render(model.user, {
+	*   loading: () => UserSkeleton(),
+	*   notFound: () => NoSuchUser(),
+	*   failed: error => ErrorView(error),
+	*   data: (user, freshness) => UserView({ user, dimmed: freshness._tag !== 'Fresh' }),
+	* })
+	* ```
+	*
+	* `notFound` is its own branch and not optional: a row the server answered
+	* for and does not have is neither loading nor a failure, and drawing it as
+	* either is a spinner that never ends or an error nobody can fix.
+	*
+	* This does not replace `match`, which is the exhaustive fold over the states
+	* themselves. Reach for `match` when the six states really do draw
+	* differently, and for this when they draw the usual three ways.
+	*/
+	render: (data, cases) => {
+		switch (data._tag) {
+			case "Initial":
+			case "Loading": return cases.loading();
+			case "NotFound": return cases.notFound();
+			case "Ready": return cases.data(data.value, fresh);
+			case "Refreshing": return cases.data(data.value, refreshing);
+			case "Failed": return data.previous === void 0 ? cases.failed(data.error) : cases.data(data.previous, Freshness.Stale({ error: data.error }));
+		}
+	},
+	/**
+	* The denial a failure was, typed, or none for any other failure (a
+	* network error, a protocol mismatch): what to read before telling a reader
+	* to sign in again.
+	*
+	* ```ts
+	* Option.match(RemoteData.denied(error), {
+	*   onNone: () => 'Could not load',
+	*   onSome: Denied.match({ Unauthenticated: () => 'Sign in again', Forbidden: () => 'Not yours' }),
+	* })
+	* ```
+	*/
+	denied: (error) => isDenial(error._tag) ? Option.some(deny[error._tag]({ reason: Option.fromUndefinedOr(error.reason) })) : Option.none(),
+	/**
+	* Whether nothing answered (`RemoteUnreachable`): the request was not sent,
+	* or what came back was no Remote answer, so a write may or may not have
+	* run. A failure the server answered (a refusal, a denial) is not one.
+	*/
+	isUnreachable: (error) => error._tag === unreachable,
+	map: (data, f) => {
+		switch (data._tag) {
+			case "Ready": return {
+				_tag: "Ready",
+				value: f(data.value)
+			};
+			case "Refreshing": return {
+				_tag: "Refreshing",
+				value: f(data.value)
+			};
+			case "Failed": return data.previous === void 0 ? {
+				_tag: "Failed",
+				error: data.error
+			} : {
+				_tag: "Failed",
+				error: data.error,
+				previous: f(data.previous)
+			};
+			case "Initial":
+			case "Loading":
+			case "NotFound": return data;
+		}
+	}
+};
+export { Denied, Freshness, RemoteData, remoteDataSchema, remoteErrorSchema };
+
+//# sourceMappingURL=remoteData.js.map

package/dist/remoteData.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"remoteData.js","names":[],"sources":["../src/remoteData.ts"],"sourcesContent":["/** `RemoteData`: the state of a value the store may not hold yet. */\nimport { Option, Schema } from 'effect'\nimport { defineTaggedUnion } from 'foldkit/schema'\nimport type { RemoteUnreachable } from './wire.js'\n\nexport interface RemoteError {\n  readonly _tag: string\n  readonly message: string\n  /**\n   * A refused mutation's refusal, encoded as the server sent it. Read it\n   * decoded, by its mutation, with `Data.refusal`.\n   */\n  readonly refusal?: unknown\n  /**\n   * Why the server refused who is asking (`_tag: 'Unauthenticated'` or\n   * `'Forbidden'`), when it said. Read it with `RemoteData.denied`.\n   */\n  readonly reason?: string | undefined\n}\n\n/**\n * The server would not answer who is asking: their session ended or was\n * never there (`Unauthenticated`, a 401), or they may not (`Forbidden`, a\n * 403). `reason` is the server's sentence, when it gave one. Not a mutation's\n * declared `refusal`, which the server answered and `Data.refusal` reads.\n */\nexport const Denied = defineTaggedUnion({\n  Unauthenticated: { reason: Schema.Option(Schema.String) },\n  Forbidden: { reason: Schema.Option(Schema.String) },\n})\nexport type Denied = typeof Denied.Type\n\n/** The tags `denied` reads: a `RemoteError`'s `_tag` is open, for any failure a transport reports. */\nconst denials: ReadonlySet<string> = new Set<Denied['_tag']>(['Unauthenticated', 'Forbidden'])\nconst isDenial = (tag: string): tag is Denied['_tag'] => denials.has(tag)\nconst deny = { Unauthenticated: Denied.Unauthenticated, Forbidden: Denied.Forbidden }\n\n/** Typed by the error class, so renaming its tag is a type error here. */\nconst unreachable: RemoteUnreachable['_tag'] = 'Unreachable'\n\nexport type RemoteData<A> =\n  | { readonly _tag: 'Initial' }\n  | { readonly _tag: 'Loading' }\n  | { readonly _tag: 'Ready'; readonly value: A }\n  | { readonly _tag: 'Refreshing'; readonly value: A }\n  | { readonly _tag: 'Failed'; readonly error: RemoteError; readonly previous?: A }\n  | { readonly _tag: 'NotFound' }\n\nexport const remoteErrorSchema = Schema.Struct({\n  _tag: Schema.String,\n  message: Schema.String,\n  refusal: Schema.optional(Schema.Unknown),\n  reason: Schema.optional(Schema.String),\n})\n\n/**\n * What `RemoteData.render` tells the `data` branch about the value it is\n * given: whether a newer answer is on its way, and whether this one is what\n * was last known good before a read failed. It is one tag rather than two\n * booleans because a value cannot be both at once, and a type that can say so\n * invites a view to handle a state that never arrives. Fold it with\n * `Freshness.match`.\n */\nexport const Freshness = defineTaggedUnion({\n  Fresh: {},\n  Refreshing: {},\n  Stale: { error: remoteErrorSchema },\n})\nexport type Freshness = typeof Freshness.Type\n\nconst fresh = Freshness.Fresh()\nconst refreshing = Freshness.Refreshing()\n\n/** A `RemoteData` schema, so a projection that reads remote state is typed. */\n// A projection is rebuilt on every Model change (a Surface's `model` callback\n// runs per dependency computation), so the schema for a value schema is built\n// once and shared: the value schema is a module-level constant in practice.\nconst remoteDataSchemas = new WeakMap<object, Schema.Schema<unknown>>()\n\nexport const remoteDataSchema = <A>(\n  value: Schema.Schema<A>,\n): Schema.Codec<RemoteData<A>, unknown> => {\n  const cached = remoteDataSchemas.get(value)\n  if (cached !== undefined) return cached as Schema.Codec<RemoteData<A>, unknown>\n  const built = Schema.Union([\n    Schema.Struct({ _tag: Schema.Literal('Initial') }),\n    Schema.Struct({ _tag: Schema.Literal('Loading') }),\n    Schema.Struct({ _tag: Schema.Literal('Ready'), value }),\n    Schema.Struct({ _tag: Schema.Literal('Refreshing'), value }),\n    Schema.Struct({\n      _tag: Schema.Literal('Failed'),\n      error: remoteErrorSchema,\n      previous: Schema.optional(value),\n    }),\n    Schema.Struct({ _tag: Schema.Literal('NotFound') }),\n  ]) as unknown as Schema.Codec<RemoteData<A>, unknown>\n  remoteDataSchemas.set(value, built as Schema.Schema<unknown>)\n  return built\n}\n\nexport const RemoteData = {\n  /**\n   * The `RemoteData` schema for a value schema. Exposed so a `RemoteData` can\n   * be embedded in a hand-written Model schema, not only through `Remote.select`.\n   */\n  schema: <A>(value: Schema.Schema<A>): Schema.Schema<RemoteData<A>> => remoteDataSchema(value),\n\n  /**\n   * Whether the read has an answer: `Ready`, `Refreshing`, `Failed` or\n   * `NotFound`. `Initial` and `Loading` are still waiting for one.\n   */\n  answered: <A>(data: RemoteData<A>): boolean =>\n    RemoteData.match(data, {\n      Initial: () => false,\n      Loading: () => false,\n      Ready: () => true,\n      Refreshing: () => true,\n      Failed: () => true,\n      NotFound: () => true,\n    }),\n\n  /** Exhaustive: omitting a state is a compile error. */\n  match: <A, R>(\n    data: RemoteData<A>,\n    cases: {\n      readonly Initial: () => R\n      readonly Loading: () => R\n      readonly Ready: (value: A) => R\n      readonly Refreshing: (value: A) => R\n      readonly Failed: (error: RemoteError, previous: Option.Option<A>) => R\n      readonly NotFound: () => R\n    },\n  ): R => {\n    switch (data._tag) {\n      case 'Initial':\n        return cases.Initial()\n      case 'Loading':\n        return cases.Loading()\n      case 'Ready':\n        return cases.Ready(data.value)\n      case 'Refreshing':\n        return cases.Refreshing(data.value)\n      case 'Failed':\n        return cases.Failed(\n          data.error,\n          data.previous === undefined ? Option.none() : Option.some(data.previous),\n        )\n      case 'NotFound':\n        return cases.NotFound()\n    }\n  },\n\n  /**\n   * The view-oriented fold: the six states as the three things a view actually\n   * draws, under the policy that useful data stays on screen. A value that is\n   * being refetched, or that a later read failed to replace, still reaches\n   * `data` — with `freshness` saying which — instead of being replaced by a\n   * spinner or an error the reader cannot act on.\n   *\n   * ```ts\n   * RemoteData.render(model.user, {\n   *   loading: () => UserSkeleton(),\n   *   notFound: () => NoSuchUser(),\n   *   failed: error => ErrorView(error),\n   *   data: (user, freshness) => UserView({ user, dimmed: freshness._tag !== 'Fresh' }),\n   * })\n   * ```\n   *\n   * `notFound` is its own branch and not optional: a row the server answered\n   * for and does not have is neither loading nor a failure, and drawing it as\n   * either is a spinner that never ends or an error nobody can fix.\n   *\n   * This does not replace `match`, which is the exhaustive fold over the states\n   * themselves. Reach for `match` when the six states really do draw\n   * differently, and for this when they draw the usual three ways.\n   */\n  render: <A, R>(\n    data: RemoteData<A>,\n    cases: {\n      readonly loading: () => R\n      readonly notFound: () => R\n      readonly failed: (error: RemoteError) => R\n      readonly data: (value: A, freshness: Freshness) => R\n    },\n  ): R => {\n    switch (data._tag) {\n      case 'Initial':\n      case 'Loading':\n        return cases.loading()\n      case 'NotFound':\n        return cases.notFound()\n      case 'Ready':\n        return cases.data(data.value, fresh)\n      case 'Refreshing':\n        return cases.data(data.value, refreshing)\n      case 'Failed':\n        return data.previous === undefined\n          ? cases.failed(data.error)\n          : cases.data(data.previous, Freshness.Stale({ error: data.error }))\n    }\n  },\n\n  /**\n   * The denial a failure was, typed, or none for any other failure (a\n   * network error, a protocol mismatch): what to read before telling a reader\n   * to sign in again.\n   *\n   * ```ts\n   * Option.match(RemoteData.denied(error), {\n   *   onNone: () => 'Could not load',\n   *   onSome: Denied.match({ Unauthenticated: () => 'Sign in again', Forbidden: () => 'Not yours' }),\n   * })\n   * ```\n   */\n  denied: (error: RemoteError): Option.Option<Denied> =>\n    // tag-check: open — a RemoteError carries any transport failure's tag.\n    isDenial(error._tag)\n      ? Option.some(deny[error._tag]({ reason: Option.fromUndefinedOr(error.reason) }))\n      : Option.none(),\n\n  /**\n   * Whether nothing answered (`RemoteUnreachable`): the request was not sent,\n   * or what came back was no Remote answer, so a write may or may not have\n   * run. A failure the server answered (a refusal, a denial) is not one.\n   */\n  isUnreachable: (error: RemoteError): boolean =>\n    // tag-check: open — a RemoteError carries any transport failure's tag.\n    error._tag === unreachable,\n\n  map: <A, B>(data: RemoteData<A>, f: (value: A) => B): RemoteData<B> => {\n    switch (data._tag) {\n      case 'Ready':\n        return { _tag: 'Ready', value: f(data.value) }\n      case 'Refreshing':\n        return { _tag: 'Refreshing', value: f(data.value) }\n      case 'Failed':\n        return data.previous === undefined\n          ? { _tag: 'Failed', error: data.error }\n          : { _tag: 'Failed', error: data.error, previous: f(data.previous) }\n      case 'Initial':\n      case 'Loading':\n      case 'NotFound':\n        return data\n    }\n  },\n}\n"],"mappings":"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"}

package/dist/reporting.d.ts

@@ -0,0 +1,12 @@
+import { i as RemoteMessage, s as RemoteModel } from "./model-B6zk1NMB.js";
+import { Focus } from "foldkit-surface";
+import * as Update from "foldkit/update";
+/**
+ * `reduce`, and the Command reporting each diagnostic it recorded. `heard`
+ * says whether the application's own `update` receives `MutationFailed`;
+ * when it does not, a pending write's failure is recorded as `WriteUnheard`.
+ */
+export declare const reduceReporting: <AppModel, Store extends RemoteModel, Message extends {
+  readonly _tag: string;
+}>(store: Focus<AppModel, Store>, reduce: (model: AppModel, message: Message) => AppModel, model: AppModel, message: Message, heard: boolean) => Update.Return<AppModel, RemoteMessage>;
+//# sourceMappingURL=reporting.d.ts.map

package/dist/reporting.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reporting.d.ts","names":[],"sources":["../src/reporting.ts"],"mappings":";;;;;;;;qBAyCa,kBACX,UACA,cAAc,aACd;WAA2B;GAAc,OAElC,MAAM,UAAU,QAAM,SACpB,OAAO,UAAU,SAAS,YAAY,UAAQ,OAChD,UAAQ,SACN,SAAO,mBAEf,OAAO,OAAO,UAAU"}

package/dist/reporting.js

@@ -0,0 +1,45 @@
+import { withDiagnostics, writeUnheard } from "./diagnostics.js";
+import { Effect, Option } from "effect";
+import { Diagnostics } from "foldkit-surface";
+// src/reporting.ts
+/**
+* Reporting what a reduction recorded. The reducer stays pure and only
+* records in `RemoteModel.diagnostics`; the wiring's route and `Remote.fold`,
+* which return Commands, report what it added through `Diagnostics.report`.
+*/
+const completed = { _tag: "CompletedReportDiagnostics" };
+const reportDiagnostics = (diagnostics) => ({
+	name: "ReportDiagnostics",
+	effect: Effect.as(Effect.forEach(diagnostics, Diagnostics.report, { discard: true }), completed)
+});
+/** The failed write `message` settles, when it was pending: one the application did not hear. */
+const unheardOf = (before, message) => message._tag === "MutationFailed" && before.mutations.pending.has(message.requestId) ? [writeUnheard({
+	requestId: message.requestId,
+	mutation: Option.map(Option.fromUndefinedOr(before.mutations.writes.get(message.requestId)), (write) => write.mutation),
+	error: message.error
+})] : [];
+/**
+* `reduce`, and the Command reporting each diagnostic it recorded. `heard`
+* says whether the application's own `update` receives `MutationFailed`;
+* when it does not, a pending write's failure is recorded as `WriteUnheard`.
+*/
+const reduceReporting = (store, reduce, model, message, heard) => {
+	const before = store.get(model);
+	const reduced = reduce(model, message);
+	const unheard = heard ? [] : unheardOf(before, message);
+	const next = unheard.length === 0 ? reduced : store.modify(reduced, (remote) => ({
+		...remote,
+		diagnostics: withDiagnostics(remote.diagnostics, unheard)
+	}));
+	const recorded = store.get(next).diagnostics;
+	if (recorded === before.diagnostics) return { model: next };
+	const known = new Set(before.diagnostics);
+	const news = recorded.filter((diagnostic) => !known.has(diagnostic));
+	return news.length === 0 ? { model: next } : {
+		model: next,
+		commands: [reportDiagnostics(news)]
+	};
+};
+export { reduceReporting };
+
+//# sourceMappingURL=reporting.js.map

package/dist/reporting.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reporting.js","names":[],"sources":["../src/reporting.ts"],"sourcesContent":["/**\n * Reporting what a reduction recorded. The reducer stays pure and only\n * records in `RemoteModel.diagnostics`; the wiring's route and `Remote.fold`,\n * which return Commands, report what it added through `Diagnostics.report`.\n */\nimport { Effect, Option } from 'effect'\nimport type { Command } from 'foldkit/command'\nimport type * as Update from 'foldkit/update'\nimport { Diagnostics, type Focus } from 'foldkit-surface'\nimport { withDiagnostics, writeUnheard, type RemoteDiagnostic } from './diagnostics.js'\nimport type { RemoteMessage, RemoteModel } from './model.js'\n\nconst completed: RemoteMessage = { _tag: 'CompletedReportDiagnostics' }\n\nconst reportDiagnostics = (\n  diagnostics: ReadonlyArray<RemoteDiagnostic>,\n): Command<RemoteMessage> => ({\n  name: 'ReportDiagnostics',\n  effect: Effect.as(Effect.forEach(diagnostics, Diagnostics.report, { discard: true }), completed),\n})\n\n/** The failed write `message` settles, when it was pending: one the application did not hear. */\nconst unheardOf = (before: RemoteModel, message: RemoteMessage): ReadonlyArray<RemoteDiagnostic> =>\n  message._tag === 'MutationFailed' && before.mutations.pending.has(message.requestId)\n    ? [\n        writeUnheard({\n          requestId: message.requestId,\n          mutation: Option.map(\n            Option.fromUndefinedOr(before.mutations.writes.get(message.requestId)),\n            write => write.mutation,\n          ),\n          error: message.error,\n        }),\n      ]\n    : []\n\n/**\n * `reduce`, and the Command reporting each diagnostic it recorded. `heard`\n * says whether the application's own `update` receives `MutationFailed`;\n * when it does not, a pending write's failure is recorded as `WriteUnheard`.\n */\nexport const reduceReporting = <\n  AppModel,\n  Store extends RemoteModel,\n  Message extends { readonly _tag: string },\n>(\n  store: Focus<AppModel, Store>,\n  reduce: (model: AppModel, message: Message) => AppModel,\n  model: AppModel,\n  message: Message,\n  heard: boolean,\n): Update.Return<AppModel, RemoteMessage> => {\n  const before = store.get(model)\n  const reduced = reduce(model, message)\n  // An application-union case has the runtime shape of the `RemoteMessage` it names.\n  const unheard = heard ? [] : unheardOf(before, message as unknown as RemoteMessage)\n  // Still the reduction of this Message into Remote's own slice, which `reduce`\n  // writes through the same `store`: not an application transition.\n  const next =\n    unheard.length === 0\n      ? reduced\n      : store.modify(reduced, remote => ({\n          ...remote,\n          diagnostics: withDiagnostics(remote.diagnostics, unheard),\n        }))\n  const recorded = store.get(next).diagnostics\n  if (recorded === before.diagnostics) return { model: next }\n  // Recorded ones are appended, but `forget` clears them all: compare by identity.\n  const known = new Set(before.diagnostics)\n  const news = recorded.filter(diagnostic => !known.has(diagnostic))\n  return news.length === 0 ? { model: next } : { model: next, commands: [reportDiagnostics(news)] }\n}\n"],"mappings":";;;;;;;;;AAYA,MAAM,YAA2B,EAAE,MAAM,6BAA6B;AAEtE,MAAM,qBACJ,iBAC4B;CAC5B,MAAM;CACN,QAAQ,OAAO,GAAG,OAAO,QAAQ,aAAa,YAAY,QAAQ,EAAE,SAAS,KAAK,CAAC,GAAG,SAAS;AACjG;;AAGA,MAAM,aAAa,QAAqB,YACtC,QAAQ,SAAS,oBAAoB,OAAO,UAAU,QAAQ,IAAI,QAAQ,SAAS,IAC/E,CACE,aAAa;CACX,WAAW,QAAQ;CACnB,UAAU,OAAO,IACf,OAAO,gBAAgB,OAAO,UAAU,OAAO,IAAI,QAAQ,SAAS,CAAC,IACrE,UAAS,MAAM,QACjB;CACA,OAAO,QAAQ;AACjB,CAAC,CACH,IACA,CAAC;;;;;;AAOP,MAAa,mBAKX,OACA,QACA,OACA,SACA,UAC2C;CAC3C,MAAM,SAAS,MAAM,IAAI,KAAK;CAC9B,MAAM,UAAU,OAAO,OAAO,OAAO;CAErC,MAAM,UAAU,QAAQ,CAAC,IAAI,UAAU,QAAQ,OAAmC;CAGlF,MAAM,OACJ,QAAQ,WAAW,IACf,UACA,MAAM,OAAO,UAAS,YAAW;EAC/B,GAAG;EACH,aAAa,gBAAgB,OAAO,aAAa,OAAO;CAC1D,EAAE;CACR,MAAM,WAAW,MAAM,IAAI,IAAI,CAAC,CAAC;CACjC,IAAI,aAAa,OAAO,aAAa,OAAO,EAAE,OAAO,KAAK;CAE1D,MAAM,QAAQ,IAAI,IAAI,OAAO,WAAW;CACxC,MAAM,OAAO,SAAS,QAAO,eAAc,CAAC,MAAM,IAAI,UAAU,CAAC;CACjE,OAAO,KAAK,WAAW,IAAI,EAAE,OAAO,KAAK,IAAI;EAAE,OAAO;EAAM,UAAU,CAAC,kBAAkB,IAAI,CAAC;CAAE;AAClG"}

package/dist/requirement-D57S2LpH.d.ts

@@ -0,0 +1,64 @@
+import { l as QueryWindow } from "./query-BuIU93xA.js";
+import { Metadata } from "foldkit-surface";
+/**
+ * The slice required of an entity. `windows` carries a pagination window per
+ * relation field, and `relations` the slice required of each relation's
+ * target, so one requirement describes a whole selection graph.
+ */
+interface RelationRequirement {
+  readonly entity: string;
+  readonly fields: readonly string[];
+  readonly windows?: Readonly<Record<string, QueryWindow>> | undefined;
+  readonly relations?: Readonly<Record<string, RelationRequirement>> | undefined;
+}
+interface Requirement extends RelationRequirement {
+  readonly id: string;
+  /** The projection also subscribes to changes of this entity (`Data.live`). */
+  readonly live?: boolean | undefined;
+}
+/**
+ * A query connection a projection reads: the page it first asks for and the
+ * slice it selects of each item. `identity` is the connection's (query plus
+ * canonical input, excluding the window).
+ */
+interface ConnectionRequirement {
+  readonly identity: string;
+  readonly window: QueryWindow;
+  readonly select: RelationRequirement;
+  /** The projection also watches the list live (`Data.query(…, { live: true })`). */
+  readonly live?: boolean | undefined;
+}
+/**
+ * Merges connection requirements for the same connection and window into one,
+ * unioning what they select of each item, live when either is; the first keeps
+ * its other properties.
+ */
+declare function mergeConnections(connections: readonly ConnectionRequirement[]): readonly ConnectionRequirement[];
+/** Unions two relation slices for the same target: fields, windows, and nested relations. */
+declare function mergeRelation(current: RelationRequirement, next: RelationRequirement): RelationRequirement;
+/** Unions requirements for the same entity + id, dropping duplicate fields. */
+declare function mergeRequirements(requirements: readonly Requirement[]): readonly Requirement[];
+/**
+ * Requirement helpers, for the packages that plan and serve requirements.
+ * `merge` unions same-entity+id requirements; `mergeRelation` unions two
+ * slices of one target (fields, windows, nested relations).
+ */
+declare const Requirement: {
+  merge: typeof mergeRequirements;
+  mergeRelation: typeof mergeRelation;
+  mergeConnections: typeof mergeConnections;
+};
+/** Remote's entity requirements on a Projection, unioned per entity and id as nodes compose. */
+declare const RemoteRequirements: import("foldkit-metadata").MetadataKey<Requirement>;
+/** Remote's query connections on a Projection, unioned per connection and window. */
+declare const RemoteConnections: import("foldkit-metadata").MetadataKey<ConnectionRequirement>;
+/** The entity requirements a Projection carries. */
+declare const requirementsOf: (projection: {
+  readonly metadata: Metadata;
+}) => ReadonlyArray<Requirement>;
+/** The query connections a Projection carries. */
+declare const connectionsOf: (projection: {
+  readonly metadata: Metadata;
+}) => ReadonlyArray<ConnectionRequirement>;
+export { Requirement as a, RemoteRequirements as i, RelationRequirement as n, connectionsOf as o, RemoteConnections as r, requirementsOf as s, ConnectionRequirement as t };
+//# sourceMappingURL=requirement-D57S2LpH.d.ts.map

package/dist/requirement-D57S2LpH.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"requirement-D57S2LpH.d.ts","names":[],"sources":["../src/requirement.ts"],"mappings":";;;;;;;UAciB;WACN;WACA;WACA,UAAU,SAAS,eAAe;WAClC,YAAY,SAAS,eAAe;;UAG9B,oBAAoB;WAC1B;;WAEA;;;;;;;UAQM;WACN;WACA,QAAQ;WACR,QAAQ;;WAER;;;;;;;iBAgBF,iBACP,sBAAsB,mCACZ;;iBAoBH,cACP,SAAS,qBACT,MAAM,sBACL;;iBAkCM,kBAAkB,uBAAuB,yBAAyB;;;;;;cAqB9D;;;;;;cAOA,+CAAkB,YAAA;;cAMlB,8CAAiB,YAAA;;cAMjB,iBAAc;WAChB,UAAU;MACjB,cAAc;;cAGL,gBAAa;WACf,UAAU;MACjB,cAAc"}

package/dist/requirement.d.ts

@@ -0,0 +1,2 @@
+import { a as Requirement, i as RemoteRequirements, n as RelationRequirement, o as connectionsOf, r as RemoteConnections, s as requirementsOf, t as ConnectionRequirement } from "./requirement-D57S2LpH.js";
+export { ConnectionRequirement, RelationRequirement, RemoteConnections, RemoteRequirements, Requirement, connectionsOf, requirementsOf };

package/dist/requirement.js

@@ -0,0 +1,114 @@
+import { own, put } from "./record.js";
+import { Metadata } from "foldkit-surface";
+// src/requirement.ts
+/**
+* What a Remote Projection needs from the server: entity slices and query
+* connections. They ride on `Projection.metadata` under Remote's own keys, so
+* Surface composes them without knowing their shape.
+*/
+const windowKey = (window) => JSON.stringify([
+	window.first ?? null,
+	window.last ?? null,
+	window.after ?? null,
+	window.before ?? null
+]);
+/**
+* Merges connection requirements for the same connection and window into one,
+* unioning what they select of each item, live when either is; the first keeps
+* its other properties.
+*/
+function mergeConnections(connections) {
+	const merged = /* @__PURE__ */ new Map();
+	for (const connection of connections) {
+		const key = `${connection.identity}\u0000${windowKey(connection.window)}`;
+		const current = merged.get(key);
+		if (current === void 0) {
+			merged.set(key, connection);
+			continue;
+		}
+		const live = current.live === true || connection.live === true;
+		merged.set(key, {
+			...current,
+			select: mergeRelation(current.select, connection.select),
+			...live ? { live } : {}
+		});
+	}
+	return [...merged.values()];
+}
+/** Unions two relation slices for the same target: fields, windows, and nested relations. */
+function mergeRelation(current, next) {
+	const fields = [...current.fields];
+	const seen = new Set(fields);
+	for (const field of next.fields) {
+		if (seen.has(field)) continue;
+		seen.add(field);
+		fields.push(field);
+	}
+	const windows = {
+		...current.windows,
+		...next.windows
+	};
+	const relations = mergeRelations(current.relations, next.relations);
+	return {
+		entity: current.entity,
+		fields,
+		...Object.keys(windows).length === 0 ? {} : { windows },
+		...relations === void 0 ? {} : { relations }
+	};
+}
+/** Unions two relation maps field by field; a field in both merges recursively. */
+function mergeRelations(current, next) {
+	if (current === void 0) return next;
+	if (next === void 0) return current;
+	const merged = { ...current };
+	for (const [field, relation] of Object.entries(next)) {
+		const existing = own(merged, field);
+		put(merged, field, existing === void 0 ? relation : mergeRelation(existing, relation));
+	}
+	return merged;
+}
+/** Unions requirements for the same entity + id, dropping duplicate fields. */
+function mergeRequirements(requirements) {
+	const grouped = /* @__PURE__ */ new Map();
+	for (const requirement of requirements) {
+		const key = `${requirement.entity}\u0000${requirement.id}`;
+		const group = grouped.get(key);
+		const live = group?.live === true || requirement.live === true;
+		grouped.set(key, {
+			...mergeRelation(group ?? {
+				entity: requirement.entity,
+				fields: []
+			}, requirement),
+			id: requirement.id,
+			...live ? { live } : {}
+		});
+	}
+	return [...grouped.values()];
+}
+/**
+* Requirement helpers, for the packages that plan and serve requirements.
+* `merge` unions same-entity+id requirements; `mergeRelation` unions two
+* slices of one target (fields, windows, nested relations).
+*/
+const Requirement = {
+	merge: mergeRequirements,
+	mergeRelation,
+	mergeConnections
+};
+/** Remote's entity requirements on a Projection, unioned per entity and id as nodes compose. */
+const RemoteRequirements = Metadata.key("remote", {
+	merge: mergeRequirements,
+	summarize: (requirement) => `${requirement.entity}:${requirement.id}`
+});
+/** Remote's query connections on a Projection, unioned per connection and window. */
+const RemoteConnections = Metadata.key("remote.connection", {
+	merge: mergeConnections,
+	summarize: (connection) => connection.identity.split("\0").join(" ")
+});
+/** The entity requirements a Projection carries. */
+const requirementsOf = (projection) => RemoteRequirements.get(projection.metadata);
+/** The query connections a Projection carries. */
+const connectionsOf = (projection) => RemoteConnections.get(projection.metadata);
+export { RemoteConnections, RemoteRequirements, Requirement, connectionsOf, requirementsOf };
+
+//# sourceMappingURL=requirement.js.map

package/dist/requirement.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"requirement.js","names":[],"sources":["../src/requirement.ts"],"sourcesContent":["/**\n * What a Remote Projection needs from the server: entity slices and query\n * connections. They ride on `Projection.metadata` under Remote's own keys, so\n * Surface composes them without knowing their shape.\n */\nimport { Metadata } from 'foldkit-surface'\nimport type { QueryWindow } from './query.js'\nimport { own, put } from './record.js'\n\n/**\n * The slice required of an entity. `windows` carries a pagination window per\n * relation field, and `relations` the slice required of each relation's\n * target, so one requirement describes a whole selection graph.\n */\nexport interface RelationRequirement {\n  readonly entity: string\n  readonly fields: readonly string[]\n  readonly windows?: Readonly<Record<string, QueryWindow>> | undefined\n  readonly relations?: Readonly<Record<string, RelationRequirement>> | undefined\n}\n\nexport interface Requirement extends RelationRequirement {\n  readonly id: string\n  /** The projection also subscribes to changes of this entity (`Data.live`). */\n  readonly live?: boolean | undefined\n}\n\n/**\n * A query connection a projection reads: the page it first asks for and the\n * slice it selects of each item. `identity` is the connection's (query plus\n * canonical input, excluding the window).\n */\nexport interface ConnectionRequirement {\n  readonly identity: string\n  readonly window: QueryWindow\n  readonly select: RelationRequirement\n  /** The projection also watches the list live (`Data.query(…, { live: true })`). */\n  readonly live?: boolean | undefined\n}\n\nconst windowKey = (window: QueryWindow): string =>\n  JSON.stringify([\n    window.first ?? null,\n    window.last ?? null,\n    window.after ?? null,\n    window.before ?? null,\n  ])\n\n/**\n * Merges connection requirements for the same connection and window into one,\n * unioning what they select of each item, live when either is; the first keeps\n * its other properties.\n */\nfunction mergeConnections(\n  connections: readonly ConnectionRequirement[],\n): readonly ConnectionRequirement[] {\n  const merged = new Map<string, ConnectionRequirement>()\n  for (const connection of connections) {\n    const key = `${connection.identity}\\u0000${windowKey(connection.window)}`\n    const current = merged.get(key)\n    if (current === undefined) {\n      merged.set(key, connection)\n      continue\n    }\n    const live = current.live === true || connection.live === true\n    merged.set(key, {\n      ...current,\n      select: mergeRelation(current.select, connection.select),\n      ...(live ? { live } : {}),\n    })\n  }\n  return [...merged.values()]\n}\n\n/** Unions two relation slices for the same target: fields, windows, and nested relations. */\nfunction mergeRelation(\n  current: RelationRequirement,\n  next: RelationRequirement,\n): RelationRequirement {\n  const fields = [...current.fields]\n  const seen = new Set(fields)\n  for (const field of next.fields) {\n    if (seen.has(field)) continue\n    seen.add(field)\n    fields.push(field)\n  }\n  const windows = { ...current.windows, ...next.windows }\n  const relations = mergeRelations(current.relations, next.relations)\n  return {\n    entity: current.entity,\n    fields,\n    ...(Object.keys(windows).length === 0 ? {} : { windows }),\n    ...(relations === undefined ? {} : { relations }),\n  }\n}\n\n/** Unions two relation maps field by field; a field in both merges recursively. */\nfunction mergeRelations(\n  current: Readonly<Record<string, RelationRequirement>> | undefined,\n  next: Readonly<Record<string, RelationRequirement>> | undefined,\n): Readonly<Record<string, RelationRequirement>> | undefined {\n  if (current === undefined) return next\n  if (next === undefined) return current\n  const merged: Record<string, RelationRequirement> = { ...current }\n  for (const [field, relation] of Object.entries(next)) {\n    const existing = own(merged, field)\n    put(merged, field, existing === undefined ? relation : mergeRelation(existing, relation))\n  }\n  return merged\n}\n\n/** Unions requirements for the same entity + id, dropping duplicate fields. */\nfunction mergeRequirements(requirements: readonly Requirement[]): readonly Requirement[] {\n  const grouped = new Map<string, Requirement>()\n  for (const requirement of requirements) {\n    const key = `${requirement.entity}\\u0000${requirement.id}`\n    // Later windows win; a duplicate is a caller bug, not a merge policy.\n    const group = grouped.get(key)\n    const live = group?.live === true || requirement.live === true\n    grouped.set(key, {\n      ...mergeRelation(group ?? { entity: requirement.entity, fields: [] }, requirement),\n      id: requirement.id,\n      ...(live ? { live } : {}),\n    })\n  }\n  return [...grouped.values()]\n}\n\n/**\n * Requirement helpers, for the packages that plan and serve requirements.\n * `merge` unions same-entity+id requirements; `mergeRelation` unions two\n * slices of one target (fields, windows, nested relations).\n */\nexport const Requirement = {\n  merge: mergeRequirements,\n  mergeRelation,\n  mergeConnections,\n}\n\n/** Remote's entity requirements on a Projection, unioned per entity and id as nodes compose. */\nexport const RemoteRequirements = Metadata.key<Requirement>('remote', {\n  merge: mergeRequirements,\n  summarize: requirement => `${requirement.entity}:${requirement.id}`,\n})\n\n/** Remote's query connections on a Projection, unioned per connection and window. */\nexport const RemoteConnections = Metadata.key<ConnectionRequirement>('remote.connection', {\n  merge: mergeConnections,\n  summarize: connection => connection.identity.split('\\u0000').join(' '),\n})\n\n/** The entity requirements a Projection carries. */\nexport const requirementsOf = (projection: {\n  readonly metadata: Metadata\n}): ReadonlyArray<Requirement> => RemoteRequirements.get(projection.metadata)\n\n/** The query connections a Projection carries. */\nexport const connectionsOf = (projection: {\n  readonly metadata: Metadata\n}): ReadonlyArray<ConnectionRequirement> => RemoteConnections.get(projection.metadata)\n"],"mappings":"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"}