@mark1russell7/coeval 0.0.0-stage → 0.2.0

package/src/ladder.ts

@@ -0,0 +1,141 @@
+import { type TypeRef, typeName } from "./doc.ts";
+import { type Kind, type World, lookupKind } from "./world.ts";
+
+export type { Kind, Namespace, PartsSpec, Side, World, WorldEntry } from "./world.ts";
+
+/** The rungs of the ladder, in the order that a question visits them. */
+export const RUNGS = ["own", "kind", "default"] as const;
+
+/** One rung of the ladder. */
+export type Rung = (typeof RUNGS)[number];
+
+/** The place where the ladder found the type. */
+export type KindSource = "document" | "container";
+
+/**
+ * The outcome of one rung.
+ *
+ * - `answers`: the rung gives an evaluator.
+ * - `no-entry`: the rung has nothing for this verb, thus the question goes to the next rung.
+ * - `skipped`: the rung does not apply, because no type is known.
+ * - `unknown-kind`: the type is not a kind of the world. The question stops.
+ */
+export type Outcome = "answers" | "no-entry" | "skipped" | "unknown-kind";
+
+/** The record of one rung that a question visited. */
+export interface Step {
+  readonly rung: Rung;
+  readonly outcome: Outcome;
+  /** The evaluator, when the outcome is `answers`. */
+  readonly evaluator?: string;
+  /** The text of the type, at the kind rung. */
+  readonly kind?: string;
+  /** The place of the type, at the kind rung. */
+  readonly source?: KindSource;
+}
+
+/** The answer to a question. It keeps the record of each rung that the question visited. */
+export interface Answer {
+  readonly verb: string;
+  /** The evaluator that answers. A question that stops with an error has no evaluator. */
+  readonly evaluator?: string;
+  /** The rung that answered. */
+  readonly rung?: Rung;
+  /** The reason when no rung answers. */
+  readonly error?: "unknown-kind" | "no-answer";
+  readonly steps: readonly Step[];
+}
+
+/**
+ * The header that the ladder reads: the type and the own entries. An envelope is a header. A bare value has an
+ * empty header, and its position can declare its type.
+ */
+export interface Header {
+  readonly type?: TypeRef;
+  readonly own?: Readonly<Record<string, string>>;
+}
+
+/** The options of a question. */
+export interface AskOptions {
+  /** The type that the position of a bare value declares. The type of an envelope wins. */
+  readonly declaredType?: string;
+}
+
+function entryOf(verbs: Readonly<Record<string, string>> | undefined, verb: string): string | undefined {
+  return verbs !== undefined && Object.hasOwn(verbs, verb) ? verbs[verb] : undefined;
+}
+
+/**
+ * This function finds the kind that a type names, and follows each alias. It gives `undefined` for an unknown
+ * type.
+ *
+ * @param world - The world.
+ * @param type - The reference to the type.
+ * @returns The kind, or `undefined`.
+ */
+export function kindOf(world: World, type: TypeRef): Kind | undefined {
+  const found = lookupKind(world, type);
+  return found.ok ? found.kind : undefined;
+}
+
+/**
+ * This function finds a kind by a text type. It is the same as `kindOf` for a one-key reference.
+ *
+ * @param world - The world.
+ * @param name - The text of the type.
+ * @returns The kind, or `undefined`.
+ */
+export function kindNamed(world: World, name: TypeRef): Kind | undefined {
+  return kindOf(world, name);
+}
+
+/**
+ * This function asks a document a question, and gives the evaluator that answers it.
+ *
+ * The question visits the rungs in order: the own entry of the envelope, then its kind, then the default of the
+ * world. The type comes from the envelope, or else from the type that the position declares. The type is a
+ * reference into the world. The ladder does not guess a type from the shape of a value.
+ *
+ * @param world - The kinds and the defaults.
+ * @param doc - The header of the document: an envelope, or `{}` for a bare value.
+ * @param verb - The verb of the question, for example `eval` or `view`.
+ * @param options - The type that the position declares.
+ * @returns The answer, with the record of each rung that the question visited.
+ */
+export function ask(world: World, doc: Header, verb: string, options: AskOptions = {}): Answer {
+  const steps: Step[] = [];
+
+  const own = entryOf(doc.own, verb);
+  if (own !== undefined) {
+    steps.push({ rung: "own", outcome: "answers", evaluator: own });
+    return { verb, evaluator: own, rung: "own", steps };
+  }
+  steps.push({ rung: "own", outcome: "no-entry" });
+
+  const type: TypeRef | undefined = doc.type ?? options.declaredType;
+  if (type === undefined) {
+    steps.push({ rung: "kind", outcome: "skipped" });
+  } else {
+    const source: KindSource = doc.type === undefined ? "container" : "document";
+    const name = typeName(type);
+    const kind = kindOf(world, type);
+    if (kind === undefined) {
+      steps.push({ rung: "kind", outcome: "unknown-kind", kind: name, source });
+      return { verb, error: "unknown-kind", steps };
+    }
+    const entry = entryOf(kind.verbs, verb);
+    if (entry !== undefined) {
+      steps.push({ rung: "kind", outcome: "answers", evaluator: entry, kind: name, source });
+      return { verb, evaluator: entry, rung: "kind", steps };
+    }
+    steps.push({ rung: "kind", outcome: "no-entry", kind: name, source });
+  }
+
+  const fallback = entryOf(world.defaults, verb);
+  if (fallback !== undefined) {
+    steps.push({ rung: "default", outcome: "answers", evaluator: fallback });
+    return { verb, evaluator: fallback, rung: "default", steps };
+  }
+  steps.push({ rung: "default", outcome: "no-entry" });
+  return { verb, error: "no-answer", steps };
+}

package/src/order.ts

@@ -0,0 +1,111 @@
+/** One step of a sequence: its name, the names of the earlier steps that it reads, and if it has an effect. */
+export interface StepSpec {
+  readonly id: string;
+  readonly reads: readonly string[];
+  readonly effect: boolean;
+}
+
+/** An edge from a step that must come first to a step that must come after it. */
+export type Edge = readonly [before: string, after: string];
+
+/** A reference that a sequence cannot resolve. */
+export interface OrderProblem {
+  readonly step: string;
+  readonly reads: string;
+  /** `unknown-name`: no step has this name. `read-before-defined`: the step with this name comes later. */
+  readonly problem: "unknown-name" | "read-before-defined";
+}
+
+/**
+ * This function finds the references that a sequence cannot resolve. A step can read only the steps before it.
+ *
+ * @param steps - The steps, in the written order.
+ * @returns One problem for each bad reference, in the written order.
+ */
+export function checkSteps(steps: readonly StepSpec[]): readonly OrderProblem[] {
+  const problems: OrderProblem[] = [];
+  steps.forEach((step, index) => {
+    for (const name of step.reads) {
+      const at = steps.findIndex((other) => other.id === name);
+      if (at === -1) problems.push({ step: step.id, reads: name, problem: "unknown-name" });
+      else if (at >= index) problems.push({ step: step.id, reads: name, problem: "read-before-defined" });
+    }
+  });
+  return problems;
+}
+
+/**
+ * This function gives the data edges: a step comes after each earlier step that it reads.
+ *
+ * @param steps - The steps, in the written order.
+ * @returns The edges. A bad reference gives no edge.
+ */
+export function dataEdges(steps: readonly StepSpec[]): readonly Edge[] {
+  const edges: Edge[] = [];
+  steps.forEach((step, index) => {
+    for (const name of step.reads) {
+      const at = steps.findIndex((other) => other.id === name);
+      if (at !== -1 && at < index) edges.push([name, step.id]);
+    }
+  });
+  return edges;
+}
+
+/**
+ * This function gives the effect edges: each step with an effect comes after the previous step with an effect.
+ * Effects keep their written order. Steps without an effect get no effect edge.
+ *
+ * @param steps - The steps, in the written order.
+ * @returns The edges, one for each pair of consecutive effect steps.
+ */
+export function effectEdges(steps: readonly StepSpec[]): readonly Edge[] {
+  const edges: Edge[] = [];
+  let previous: string | undefined;
+  for (const step of steps) {
+    if (!step.effect) continue;
+    if (previous !== undefined) edges.push([previous, step.id]);
+    previous = step.id;
+  }
+  return edges;
+}
+
+/**
+ * This function tells if an order of the steps gives the same meaning as the written order.
+ * The order must contain each step one time, and it must obey the data edges and the effect edges.
+ *
+ * @param steps - The steps, in the written order.
+ * @param order - The names of the steps in the order to examine.
+ * @returns `true` when the order is permitted.
+ */
+export function isAllowedOrder(steps: readonly StepSpec[], order: readonly string[]): boolean {
+  if (order.length !== steps.length) return false;
+  if (new Set(order).size !== order.length) return false;
+  if (!steps.every((step) => order.includes(step.id))) return false;
+  const position = new Map(order.map((id, index) => [id, index] as const));
+  return [...dataEdges(steps), ...effectEdges(steps)].every(
+    ([before, after]) => (position.get(before) ?? 0) < (position.get(after) ?? 0),
+  );
+}
+
+/**
+ * This function puts the steps in layers. Each step goes one layer after the last step that it must follow.
+ * The steps of one layer do not depend on each other, thus they can run at the same time.
+ *
+ * @param steps - The steps, in the written order.
+ * @returns The layers, first to last. Each layer keeps the written order.
+ */
+export function layers(steps: readonly StepSpec[]): readonly (readonly string[])[] {
+  const edges = [...dataEdges(steps), ...effectEdges(steps)];
+  const depth = new Map<string, number>();
+  for (const step of steps) {
+    const before = edges.filter(([, after]) => after === step.id).map(([first]) => depth.get(first) ?? 0);
+    depth.set(step.id, before.length === 0 ? 0 : Math.max(...before) + 1);
+  }
+  const result: string[][] = [];
+  for (const step of steps) {
+    const at = depth.get(step.id) ?? 0;
+    while (result.length <= at) result.push([]);
+    result[at]?.push(step.id);
+  }
+  return result;
+}

package/src/parts.ts

@@ -0,0 +1,156 @@
+import { type Json, type Key, isEnvelope, isRecord } from "./doc.ts";
+import type { Shape } from "./world.ts";
+
+/** One part of a value: its place in the value, the JSON of the part, and the type that its position declares. */
+export interface PartSlot {
+  /** The keys from the value of the document to the part. */
+  readonly path: readonly Key[];
+  /** The path as one text, with a dot between the keys, for example `bind.x`. A part of a list has its index. */
+  readonly key: string;
+  readonly item: Json;
+  readonly of?: string;
+}
+
+type Template =
+  | { readonly t: "data"; readonly value: unknown }
+  | { readonly t: "slot"; readonly index: number }
+  | { readonly t: "list"; readonly items: readonly Template[] }
+  | { readonly t: "record"; readonly fields: readonly (readonly [string, Template])[] };
+
+/** The value of a document, split into its parts, by the shape that its kind declares. */
+export type Split =
+  | {
+      readonly ok: true;
+      /** The parts, in the order of the value. */
+      readonly parts: readonly PartSlot[];
+      /** The value without the parts: a field that holds a part is not in it, and a list of parts gives `null`. */
+      readonly data: Json;
+      /**
+       * This function gives the value with a handle in the place of each part.
+       *
+       * @param handles - One handle for each part, in the order of `parts`.
+       * @returns The value with the handles.
+       */
+      fill<P>(handles: readonly P[]): unknown;
+    }
+  | { readonly ok: false; readonly reason: string; readonly at: readonly Key[] };
+
+class Bad {
+  constructor(
+    readonly reason: string,
+    readonly at: readonly Key[],
+  ) {}
+}
+
+function setOwn(target: Record<string, unknown>, key: string, value: unknown): void {
+  Object.defineProperty(target, key, { value, enumerable: true, writable: true, configurable: true });
+}
+
+function hasSlots(template: Template): boolean {
+  return template.t !== "data";
+}
+
+/**
+ * This function splits a value into its parts, by the shape that its kind declares. The evaluator, the view and
+ * the static kit use the same split, thus each one sees the same parts.
+ *
+ * @param shape - The shape of the value. The default is data.
+ * @param value - The value of the document.
+ * @returns The parts and a way to fill their places, or the reason why the value does not have the shape.
+ */
+export function splitParts(shape: Shape | undefined, value: Json): Split {
+  const parts: PartSlot[] = [];
+  const slot = (item: Json, path: readonly Key[], of: string | undefined): Template => {
+    parts.push({ path, key: path.join("."), item, ...(of === undefined ? {} : { of }) });
+    return { t: "slot", index: parts.length - 1 };
+  };
+
+  const deep = (item: Json, path: readonly Key[], of: string | undefined): Template => {
+    if (isEnvelope(item)) return slot(item, path, of);
+    if (Array.isArray(item)) {
+      const items = (item as readonly Json[]).map((child, index) => deep(child, [...path, index], of));
+      return items.some(hasSlots) ? { t: "list", items } : { t: "data", value: item };
+    }
+    if (isRecord(item)) {
+      const fields = Object.keys(item).map((key) => [key, deep(item[key] as Json, [...path, key], of)] as const);
+      return fields.some(([, child]) => hasSlots(child)) ? { t: "record", fields } : { t: "data", value: item };
+    }
+    return { t: "data", value: item };
+  };
+
+  const walk = (spec: Shape | undefined, item: Json, path: readonly Key[]): Template => {
+    if (spec === undefined || spec.shape === "none") return { t: "data", value: item };
+    if (spec.shape === "term") return slot(item, path, spec.of);
+    if (spec.shape === "deep") return deep(item, path, spec.of);
+    if (spec.shape === "list") {
+      if (!Array.isArray(item)) throw new Bad("The value must be a list.", path);
+      const each: Shape = spec.item ?? { shape: "term", ...(spec.of === undefined ? {} : { of: spec.of }) };
+      return { t: "list", items: (item as readonly Json[]).map((child, index) => walk(each, child, [...path, index])) };
+    }
+    if (!isRecord(item)) throw new Bad("The value must be a record.", path);
+    if (spec.shape === "map") {
+      const each: Shape = spec.item ?? { shape: "term", ...(spec.of === undefined ? {} : { of: spec.of }) };
+      return { t: "record", fields: Object.keys(item).map((key) => [key, walk(each, item[key] as Json, [...path, key])] as const) };
+    }
+    for (const name of spec.required ?? []) {
+      if (!Object.hasOwn(item, name)) throw new Bad(`The field ${name} is missing.`, path);
+    }
+    const named: Readonly<Record<string, Shape>> = Array.isArray(spec.fields)
+      ? Object.fromEntries((spec.fields as readonly string[]).map((name) => [name, { shape: "term", ...(spec.of === undefined ? {} : { of: spec.of }) } as Shape]))
+      : (spec.fields as Readonly<Record<string, Shape>>);
+    const fields: (readonly [string, Template])[] = [];
+    for (const key of Object.keys(item)) {
+      const fieldShape = Object.hasOwn(named, key) ? named[key] : spec.rest;
+      fields.push([key, walk(fieldShape, item[key] as Json, [...path, key])]);
+    }
+    return { t: "record", fields };
+  };
+
+  let template: Template;
+  try {
+    template = walk(shape, value, []);
+  } catch (error) {
+    if (error instanceof Bad) return { ok: false, reason: error.reason, at: error.at };
+    throw error;
+  }
+
+  const strip = (node: Template): Json | undefined => {
+    if (node.t === "data") return node.value as Json;
+    if (node.t === "slot") return undefined;
+    if (node.t === "list") return node.items.every((child) => child.t === "slot") ? null : (node.items.map((child) => strip(child) ?? null) as Json);
+    const out: Record<string, Json> = {};
+    for (const [key, child] of node.fields) {
+      const kept = strip(child);
+      if (kept !== undefined) setOwn(out, key, kept);
+    }
+    return out;
+  };
+
+  const fillWith = <P>(node: Template, handles: readonly P[]): unknown => {
+    if (node.t === "data") return node.value;
+    if (node.t === "slot") return handles[node.index];
+    if (node.t === "list") return node.items.map((child) => fillWith(child, handles));
+    const out: Record<string, unknown> = {};
+    for (const [key, child] of node.fields) setOwn(out, key, fillWith(child, handles));
+    return out;
+  };
+
+  return { ok: true, parts, data: strip(template) ?? null, fill: (handles) => fillWith(template, handles) };
+}
+
+/**
+ * This function tells if the path of a part matches a pattern of a scope rule. The key `"*"` of a pattern matches
+ * each key.
+ *
+ * @param path - The path of the part.
+ * @param pattern - The pattern.
+ * @returns `true` when the path matches.
+ */
+export function pathMatches(path: readonly Key[], pattern: readonly Key[]): boolean {
+  if (path.length !== pattern.length) return false;
+  for (let index = 0; index < path.length; index += 1) {
+    const want = pattern[index];
+    if (want !== "*" && String(want) !== String(path[index])) return false;
+  }
+  return true;
+}