foldkit-surface 0.13.0 → 0.15.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.js CHANGED
@@ -1,5 +1,9 @@
1
- import { Optic, Option, Predicate, Result, Schema } from "effect";
2
- import { Metadata, Metadata as Metadata$1, MetadataTypeId } from "foldkit-metadata";
1
+ import { Equal, Optic, Option, Predicate, Result, Schema } from "effect";
2
+ import { hasTagIn, messageTag, messageTags } from "./messageTags.js";
3
+ import { Evidence, Metadata, Metadata as Metadata$1, MetadataTypeId } from "foldkit-metadata";
4
+ import { labelOf, pathText, tableCell } from "./text.js";
5
+ import { Closure, ClosureViolation } from "./closure.js";
6
+ import { Graph, GraphEdge, GraphNode } from "./graph.js";
3
7
  import { Diagnostics } from "./diagnostics.js";
4
8
  import { CacheStore, CachedRead, PageReads, cachePolicy, maxAgeSeconds, shorterPolicy } from "./edgeCache.js";
5
9
  // src/index.ts
@@ -51,15 +55,6 @@ function propertyReader(root, key) {
51
55
  function optionalReader(value) {
52
56
  return value === void 0 ? Option.none() : Option.some(value);
53
57
  }
54
- /** Reads the tag off a Foldkit Message constructor without constructing one. */
55
- const messageTag = (constructor) => {
56
- const literal = constructor.fields?._tag?.ast?.literal;
57
- return typeof literal === "string" ? literal : void 0;
58
- };
59
- /** Whether a Message, of an application this cannot name, has one of `tags`. */
60
- const hasTagIn = (tags, message) => Predicate.hasProperty(message, "_tag") && typeof message._tag === "string" && tags.has(message._tag);
61
- /** The tags of the Messages a Surface lists in `messages`. */
62
- const messageTags = (surface) => surface.messages.map(messageTag).filter((tag) => tag !== void 0);
63
58
  function makeTree(schema, path, optic, get, optional = false, set, owner) {
64
59
  const erasedOptic = optic;
65
60
  const setFocus = set ?? ((root, value) => optic.replace(value, root));
@@ -193,9 +188,10 @@ const Projection = {
193
188
  dependencies.push(focus.dependency);
194
189
  readers.push([key, focus.get]);
195
190
  } else {
191
+ if (entry.Model === void 0) throw new Error(`Projection.struct: "${key}" is a Derived with no Model. Pass the Schema of its value: Projection.derive(on, derive, { Model }).`);
196
192
  picked[key] = entry.Model;
197
193
  dependencies.push(...entry.dependencies);
198
- metadata.push(entry.metadata);
194
+ if ("metadata" in entry) metadata.push(entry.metadata);
199
195
  nesteds.push(entry);
200
196
  readers.push([key, entry.read]);
201
197
  }
@@ -249,6 +245,17 @@ const Projection = {
249
245
  * keyed on it holds. It keeps one result: the one for the last Model it was
250
246
  * given.
251
247
  *
248
+ * `verify` checks that promise: where the memo would give its last value,
249
+ * `derive` runs again, and a result unequal to it throws, naming the paths
250
+ * `on` reads, since `derive` read something they do not name. Pass
251
+ * `import.meta.env?.DEV === true`, as `Remote.make`'s `verifyPredictions` takes it;
252
+ * it doubles the work, so leave it off in production.
253
+ *
254
+ * `Model`, the Schema of the value, makes the result a `ModeledDerived`, which
255
+ * a `Projection.struct` takes as an entry: the struct reads the memoized
256
+ * value, and the Surface checks it against `Model`. A Derived plans no
257
+ * requirements, whatever `on` holds.
258
+ *
252
259
  * @example
253
260
  * ```ts
254
261
  * const shown = Projection.derive([App.model.todos, App.model.filter], (model: Model) =>
@@ -257,18 +264,21 @@ const Projection = {
257
264
  * // In the view: shown.read(model)
258
265
  * ```
259
266
  */
260
- derive: (on, derive) => {
267
+ derive: ((on, derive, options = {}) => {
261
268
  if (on.length === 0) throw new Error("Projection.derive: it names nothing it reads, so nothing could tell it to work the value out again. Name field references, or Projections built from them.");
262
269
  const parts = on.map((entry) => RefTypeId in entry ? { dependencies: [entry[RefTypeId].dependency] } : entry);
263
270
  const dependencies = mergeDependencies(parts.flatMap((part) => part.dependencies));
264
271
  const always = parts.some(unnamed);
265
272
  let last;
266
273
  const derived = {
274
+ ...options.Model === void 0 ? {} : { Model: options.Model },
267
275
  dependencies,
268
276
  read: (root) => {
269
277
  const values = dependencies.map((path) => valueAt(root, path));
270
278
  const before = last;
271
- const value = before === void 0 ? derive(root) : !always && values.every((value, index) => Object.is(value, before.values[index])) ? before.value : keepAlike(before.value, derive(root));
279
+ const hit = before !== void 0 && !always && values.every((value, index) => Object.is(value, before.values[index]));
280
+ if (hit && options.verify === true && !Equal.equals(derive(root), before.value)) throw new Error(`Projection.derive: nothing it names changed (${dependencies.map((path) => path.join(".")).join(", ")}), yet working the value out again gives another. It reads something its \`on\` does not name: add it there.`);
281
+ const value = before === void 0 ? derive(root) : hit ? before.value : keepAlike(before.value, derive(root));
272
282
  last = {
273
283
  values,
274
284
  value
@@ -278,7 +288,7 @@ const Projection = {
278
288
  };
279
289
  if (always) readsUnnamed.add(derived);
280
290
  return derived;
281
- },
291
+ }),
282
292
  /**
283
293
  * Derives a writable projection from generated Model field references:
284
294
  * `Projection.pick(App.model.todos, App.model.selectedTodoId)` infers
@@ -377,7 +387,8 @@ function application(config) {
377
387
  const shape = surfaceConfig.model(context);
378
388
  return isProjection(shape) ? shape : Projection.struct(shape);
379
389
  },
380
- messages: surfaceConfig.messages
390
+ messages: surfaceConfig.messages,
391
+ closed: surfaceConfig.closed
381
392
  });
382
393
  const made = {
383
394
  ...scope,
@@ -610,6 +621,7 @@ const Surface = {
610
621
  Params: config.Params,
611
622
  Message: Schema.Never,
612
623
  messages: config.messages ?? [],
624
+ closed: config.closed ?? false,
613
625
  projection
614
626
  };
615
627
  },
@@ -648,7 +660,8 @@ const Surface = {
648
660
  owns: [],
649
661
  observes: projection.dependencies,
650
662
  messages: messageTags(surface),
651
- metadata: Metadata$1.summarize(projection.metadata)
663
+ metadata: Metadata$1.summarize(projection.metadata),
664
+ ...surface.closed ? { closed: true } : {}
652
665
  };
653
666
  },
654
667
  /**
@@ -665,10 +678,8 @@ const Surface = {
665
678
  };
666
679
  }
667
680
  };
668
- const label = (contract) => `${contract.kind}:${contract.name}`;
669
- /** Metadata summaries are application data (a query's input), so they cannot break the table. */
670
- const tableCell = (text) => text.replace(/\\/g, "\\\\").replace(/\|/g, "\\|").replace(/\r\n?|\n/g, " ");
671
- const pathKey = (path) => path.join(".");
681
+ const label = labelOf;
682
+ const pathKey = pathText;
672
683
  const isPrefix = (prefix, path) => prefix.length <= path.length && prefix.every((segment, index) => segment === path[index]);
673
684
  const toContract = (item) => "contract" in item ? item.contract : "projection" in item ? Surface.contract(item, void 0) : item;
674
685
  const applicationTags = (app) => Object.entries(app.Message).filter(([key, value]) => messageTag(value) === key).map(([key]) => key);
@@ -698,7 +709,8 @@ const Module = {
698
709
  * Cross-contract invariants the types cannot express: a contract from another
699
710
  * application, a duplicate `kind:name`, two owners of overlapping Model paths,
700
711
  * a Message recorded by two replication contracts, and a path or Message the
701
- * application does not declare.
712
+ * application does not declare. The rules over the contracts' laws are
713
+ * `Graph.validate`'s.
702
714
  */
703
715
  validate: (module) => {
704
716
  const findings = [];
@@ -785,11 +797,14 @@ const Module = {
785
797
  fields: Object.keys(module.app.Model.fields),
786
798
  messages: applicationTags(module.app),
787
799
  ownership,
788
- contracts: module.contracts.map(({ owner: _owner, ...rest }) => rest),
800
+ contracts: module.contracts.map(({ owner: _owner, laws: _laws, ...rest }) => rest),
789
801
  findings: Module.validate(module)
790
802
  };
791
803
  },
792
- /** The manifest as Markdown: the ownership tree, a table of contracts, and findings. */
804
+ /**
805
+ * The manifest as Markdown: the ownership tree, a table of contracts, and
806
+ * findings. `Graph.toMarkdown` writes the laws.
807
+ */
793
808
  toMarkdown: (module) => {
794
809
  const manifest = Module.manifest(module);
795
810
  const lines = ["```text", "Model"];
@@ -810,6 +825,7 @@ const Module = {
810
825
  /**
811
826
  * The manifest as a Mermaid flowchart: Model fields in a subgraph, one node
812
827
  * per contract, a solid edge for ownership and a dotted edge for observation.
828
+ * `Graph.toMermaid` draws the laws.
813
829
  */
814
830
  toMermaid: (module) => {
815
831
  const manifest = Module.manifest(module);
@@ -834,6 +850,6 @@ const Module = {
834
850
  return lines.join("\n");
835
851
  }
836
852
  };
837
- export { Action, CacheStore, CachedRead, Diagnostics, MessageSet, Metadata, MetadataTypeId, ModelRef, Module, PageReads, Projection, RefTypeId, Surface, cachePolicy, maxAgeSeconds, shorterPolicy };
853
+ export { Action, CacheStore, CachedRead, Closure, ClosureViolation, Diagnostics, Evidence, Graph, GraphEdge, GraphNode, MessageSet, Metadata, MetadataTypeId, ModelRef, Module, PageReads, Projection, RefTypeId, Surface, cachePolicy, maxAgeSeconds, shorterPolicy };
838
854
 
839
855
  //# sourceMappingURL=index.js.map