@mark1russell7/coeval 0.0.0-bootstrap.0 → 0.1.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,43 @@
+import { type Json, type JsonRecord, field, isRecord } from "./doc.ts";
+import type { PartsSpec } from "./ladder.ts";
+
+/** One part of a value: its key, the JSON of the part, and the type that its position declares. */
+export interface PartSlot {
+  readonly key: string;
+  readonly item: Json;
+  readonly of?: string;
+}
+
+/** The value of a document, split into its data and its parts. */
+export type Split =
+  | { readonly ok: true; readonly data: Json; readonly parts: readonly PartSlot[] }
+  | { readonly ok: false; readonly reason: string };
+
+/**
+ * This function splits a value into its data and its parts, by the contract of its kind. The evaluator and the
+ * view use the same split, thus a picture shows the parts that the evaluation gets.
+ *
+ * @param spec - The contract of the parts.
+ * @param value - The value of the document.
+ * @returns The data and the parts, or the reason why the value does not obey the contract.
+ */
+export function splitParts(spec: PartsSpec | undefined, value: Json): Split {
+  const of = (slot: { key: string; item: Json }, declared: string | undefined): PartSlot =>
+    declared === undefined ? slot : { ...slot, of: declared };
+  if (spec === undefined || spec.shape === "none") return { ok: true, data: value, parts: [] };
+  if (spec.shape === "list") {
+    if (!Array.isArray(value)) return { ok: false, reason: "The value must be a list." };
+    const items: readonly Json[] = value;
+    return { ok: true, data: null, parts: items.map((item, index) => of({ key: String(index), item }, spec.of)) };
+  }
+  if (!isRecord(value)) return { ok: false, reason: "The value must be a record." };
+  const record: JsonRecord = value;
+  const rest: Record<string, Json> = {};
+  for (const [key, item] of Object.entries(record)) if (!spec.fields.includes(key)) rest[key] = item;
+  const parts: PartSlot[] = [];
+  for (const key of spec.fields) {
+    const item = field(record, key);
+    if (item !== undefined) parts.push(of({ key, item }, spec.of));
+  }
+  return { ok: true, data: rest, parts };
+}

package/src/stdlib.ts

@@ -0,0 +1,283 @@
+import { type Json, type Key, field, isRecord } from "./doc.ts";
+import { type Context, type Evaluator, type Machine, type Part, type Result, type RunPart, type Runner, fail, ok } from "./evaluate.ts";
+import { type HostThing, type Thing, type Walker, THING, isHostThing, valueOfThing } from "./deref.ts";
+import type { World } from "./ladder.ts";
+
+/**
+ * The world of the examples: small kinds for numbers, lists, conditions, names, sequences and effects.
+ * Each kind names an evaluator for `eval` and a view for `view`. The site draws each document with its view.
+ */
+export const STD_WORLD: World = {
+  kinds: {
+    number: { verbs: { eval: "data.number", view: "view.value" }, summary: "A number. Its value is the result." },
+    text: { verbs: { eval: "data.text", view: "view.value" }, summary: "A text. Its value is the result." },
+    bool: { verbs: { eval: "data.bool", view: "view.value" }, summary: "A truth value. Its value is the result." },
+    add: {
+      verbs: { eval: "math.add", view: "view.op" },
+      parts: { shape: "list", of: "number" },
+      summary: "The sum of its parts. A bare number in its list gets the type number.",
+    },
+    multiply: {
+      verbs: { eval: "math.multiply", view: "view.op" },
+      parts: { shape: "list", of: "number" },
+      summary: "The product of its parts.",
+    },
+    greater: {
+      verbs: { eval: "math.greater", view: "view.op" },
+      parts: { shape: "list", of: "number" },
+      summary: "True when the first part is greater than the second part.",
+    },
+    list: { verbs: { eval: "list.all", view: "view.op" }, parts: { shape: "list" }, summary: "The results of its parts, as a list." },
+    if: {
+      verbs: { eval: "control.if", view: "view.op" },
+      parts: { shape: "record", fields: ["test", "then", "else"] },
+      summary: "It evaluates the test, then only the branch that the test selects.",
+    },
+    ref: {
+      verbs: { eval: "ref.resolve", view: "view.ref" },
+      summary: "A path from a root of the context. Each step goes up the ladder of the verb deref.",
+    },
+    nearest: {
+      verbs: { step: "walk.nearest", view: "view.card" },
+      summary: "A step of a path: it follows a key again and again, until it reaches a node of a type.",
+    },
+    panel: {
+      verbs: { eval: "tree.node", view: "view.op" },
+      parts: { shape: "record", fields: ["width", "height", "children"], of: "number" },
+      summary: "A node of a tree. Its parts see it as self, and each node links to its parent.",
+    },
+    box: {
+      verbs: { eval: "tree.node", view: "view.op" },
+      parts: { shape: "record", fields: ["width", "height", "children"], of: "number" },
+      summary: "A node of a tree, as panel. A formula in a box can read the parent of the box.",
+    },
+    math: {
+      kinds: {
+        sum: { type: "ref", value: ["world", "add"] },
+        product: { type: "ref", value: ["world", "multiply"] },
+      },
+    },
+    seq: {
+      verbs: { eval: "control.seq", view: "view.seq" },
+      parts: { shape: "list" },
+      summary: "Its steps, in order. The result of a named step is a name for the later steps.",
+    },
+    pure: {
+      verbs: { eval: "control.pure", view: "view.op" },
+      parts: { shape: "list" },
+      summary: "It evaluates its part without capabilities, thus an effect in it fails.",
+    },
+    log: {
+      verbs: { eval: "effect.log", view: "view.op" },
+      parts: { shape: "list", of: "text" },
+      side: "run",
+      summary: "It writes the result of its part to the log. This is an effect.",
+    },
+    write: {
+      verbs: { eval: "effect.write", view: "view.op" },
+      parts: { shape: "record", fields: ["value"] },
+      side: "run",
+      summary: "It writes the result of its part to the store, at its key. This is an effect.",
+    },
+  },
+  defaults: { view: "view.card" },
+};
+
+function isNumber(value: Json): value is number {
+  return typeof value === "number" && Number.isFinite(value);
+}
+
+/** This function evaluates each part, collects the errors, and gives the values when no part failed. */
+function allValues(results: readonly Result[]): { readonly values: readonly Json[] } | { readonly error: Result } {
+  const errors = results.filter((result) => !result.ok);
+  const first = errors[0];
+  if (first !== undefined && errors.length === 1) return { error: first };
+  if (errors.length > 1) return { error: fail("#ARGS", `${errors.length} parts failed.`) };
+  return { values: results.map((result) => (result.ok ? result.value : null)) };
+}
+
+function numbers(values: readonly Json[], kind: string): readonly number[] | Result {
+  const bad = values.findIndex((value) => !isNumber(value));
+  if (bad !== -1) return fail("#VALUE!", `Part ${bad} of ${kind} is not a number.`);
+  return values.filter(isNumber);
+}
+
+function dataOf(type: "number" | "string" | "boolean"): Evaluator {
+  return ({ data }) =>
+    typeof data === type && (type !== "number" || isNumber(data))
+      ? ok(data)
+      : fail("#VALUE!", `The value must be a ${type === "string" ? "text" : type}.`);
+}
+
+/** The code of the evaluators of the standard world, by name. */
+export const STD_EVALUATORS: Readonly<Record<string, Evaluator>> = {
+  "data.number": dataOf("number"),
+  "data.text": dataOf("string"),
+  "data.bool": dataOf("boolean"),
+  "math.add": ({ parts }) => {
+    const all = allValues(parts.map((part) => part.evaluate()));
+    if ("error" in all) return all.error;
+    const values = numbers(all.values, "add");
+    return Array.isArray(values) ? ok(values.reduce((sum, value) => sum + value, 0)) : (values as Result);
+  },
+  "math.multiply": ({ parts }) => {
+    const all = allValues(parts.map((part) => part.evaluate()));
+    if ("error" in all) return all.error;
+    const values = numbers(all.values, "multiply");
+    return Array.isArray(values) ? ok(values.reduce((product, value) => product * value, 1)) : (values as Result);
+  },
+  "math.greater": ({ parts }) => {
+    if (parts.length !== 2) return fail("#VALUE!", "greater needs exactly two parts.");
+    const all = allValues(parts.map((part) => part.evaluate()));
+    if ("error" in all) return all.error;
+    const values = numbers(all.values, "greater");
+    if (!Array.isArray(values)) return values as Result;
+    const [a, b] = values as readonly number[];
+    return ok((a ?? 0) > (b ?? 0));
+  },
+  "ref.resolve": ({ data, resolve }) => {
+    if (!Array.isArray(data) || data.length === 0) {
+      return fail("#VALUE!", "The value of ref is a path: a list that starts with a root, for example [\"names\", \"a\"].");
+    }
+    const path: readonly Json[] = data;
+    const found = resolve(path);
+    if (found.ok) return ok(valueOfThing(found.thing));
+    if (path[0] === "names" && found.hops.length === 1) return fail("#NAME?", `The context has no name ${String(path[1])}.`);
+    return fail(found.code, found.reason);
+  },
+  "tree.node": (input) => treeNode(input.parts, input.context, input.kind),
+};
+
+/**
+ * This function evaluates a node of a tree. The node is a host thing. A step `parent` reaches the node that holds
+ * it. A step with the name of a part evaluates that part on demand, one time. Each part sees the node as self.
+ */
+function treeNode(parts: readonly Part[], context: Context, type: string): Result {
+  const memo = new Map<string, Result>();
+  const read = (key: string): Result | undefined => {
+    const known = memo.get(key);
+    if (known !== undefined) return known;
+    const part = parts.find((item) => item.key === key);
+    if (part === undefined) return undefined;
+    const result = part.evaluate({ ...context, self: me });
+    memo.set(key, result);
+    return result;
+  };
+  const me: HostThing & { readonly type: string } = {
+    [THING]: true,
+    type,
+    label: `node ${type}`,
+    deref(key: Key): Thing | undefined {
+      if (key === "parent") return context.self;
+      if (key === "type") return type;
+      const result = read(String(key));
+      return result?.ok === true ? result.value : undefined;
+    },
+    toJson(): Json {
+      const out: Record<string, Json> = {};
+      for (const part of parts) {
+        const result = read(part.key);
+        out[part.key] = result?.ok === true ? result.value : null;
+      }
+      return out;
+    },
+  };
+  const out: Record<string, Json> = {};
+  for (const part of parts) {
+    const result = read(part.key);
+    if (result === undefined) continue;
+    if (!result.ok) return result;
+    out[part.key] = result.value;
+  }
+  return ok(out);
+}
+
+/**
+ * The walker of `nearest`: it follows a key (the default is `parent`) until the node that it reaches has the
+ * wanted type. With `self: true`, the node where the walk starts is the first candidate. A node without that key
+ * ends the walk with an error.
+ */
+const nearest: Walker = ({ data, here, deref }) => {
+  const follow = isRecord(data) && typeof field(data, "follow") === "string" ? String(field(data, "follow")) : "parent";
+  const wanted = isRecord(data) ? field(data, "type") : undefined;
+  const fromSelf = isRecord(data) && field(data, "self") === true;
+  let at: Thing | undefined = here;
+  for (let hops = 0; hops < 256; hops += 1) {
+    if (hops > 0 || !fromSelf) at = at === undefined || at === null ? undefined : deref(at, follow);
+    if (at === undefined || at === null) return { ok: false, reason: `No node of the type ${String(wanted)} is on the way.` };
+    const type = isHostThing(at) ? (at as { readonly type?: unknown }).type : undefined;
+    if (type === wanted) return { ok: true, thing: at };
+  }
+  return { ok: false, reason: "The walk is too long." };
+};
+
+/** The walkers of the standard world, by name. */
+export const STD_WALKERS: Readonly<Record<string, Walker>> = { "walk.nearest": nearest };
+
+/** This function evaluates parts one after the other, and stops at the first error. */
+function* inOrder(parts: readonly RunPart[]): Generator<Promise<Result>, { readonly values: readonly Json[] } | { readonly error: Result }, Result> {
+  const values: Json[] = [];
+  for (const part of parts) {
+    const result = yield* part.evaluate();
+    if (!result.ok) return { error: result };
+    values.push(result.value);
+  }
+  return { values };
+}
+
+/**
+ * The runners of the standard world, by name: the kinds that can hold effects. Each one evaluates its parts in
+ * order. In a run, an effect ends before the next step starts.
+ */
+export const STD_RUNNERS: Readonly<Record<string, Runner>> = {
+  "control.seq": function* ({ parts, context }) {
+    let names: Record<string, Json> = { ...context.names };
+    let last: Json = null;
+    for (const part of parts) {
+      const result = yield* part.evaluate({ ...context, names });
+      if (!result.ok) return result;
+      names = { ...names, last: result.value };
+      if (part.name !== undefined) names = { ...names, [part.name]: result.value };
+      last = result.value;
+    }
+    return ok(last);
+  },
+  "control.pure": function* ({ parts, context }) {
+    const only = parts[0];
+    if (only === undefined) return fail("#VALUE!", "pure needs one part.");
+    return yield* only.evaluate({ ...context, caps: [] });
+  },
+  "control.if": function* ({ parts }) {
+    const test = parts.find((part) => part.key === "test");
+    if (test === undefined) return fail("#VALUE!", "if needs a test.");
+    const chosen = yield* test.evaluate();
+    if (!chosen.ok) return chosen;
+    if (typeof chosen.value !== "boolean") return fail("#VALUE!", "The test of if must give a truth value.");
+    const branch = parts.find((part) => part.key === (chosen.value === true ? "then" : "else"));
+    return branch === undefined ? ok(null) : yield* branch.evaluate();
+  },
+  "list.all": function* ({ parts }) {
+    const all = yield* inOrder(parts);
+    return "error" in all ? all.error : ok(all.values);
+  },
+  "effect.log": function* ({ parts, effect }) {
+    const all = yield* inOrder(parts);
+    if ("error" in all) return all.error;
+    return yield* effect("log", all.values.length === 1 ? (all.values[0] ?? null) : all.values);
+  },
+  "effect.write": function* ({ parts, data, effect }) {
+    const key = isRecord(data) ? field(data, "key") : undefined;
+    if (typeof key !== "string") return fail("#VALUE!", "write needs a text key.");
+    const value = parts.find((part) => part.key === "value");
+    if (value === undefined) return fail("#VALUE!", "write needs a value.");
+    const result = yield* value.evaluate();
+    if (!result.ok) return result;
+    return yield* effect("write", { key, value: result.value });
+  },
+};
+
+/** The machine of the examples: the standard world, its evaluators, its runners and its walkers. */
+export const STD_MACHINE: Machine = { world: STD_WORLD, evaluators: STD_EVALUATORS, runners: STD_RUNNERS, walkers: STD_WALKERS };
+
+/** The capabilities of the examples at the root: the two effects of the standard world. */
+export const STD_CAPS: readonly string[] = ["log", "write"];