@mark1russell7/coeval 0.0.0-stage → 0.1.0

package/src/deref.ts

@@ -0,0 +1,290 @@
+import { type Envelope, type Json, type Key, field, fromJson, isKey, isRecord, typePath } from "./doc.ts";
+import { type World, entriesAsJson, lookupKind } from "./world.ts";
+
+/** The brand of a host thing: an object of the host that answers the steps of a path itself. */
+export const THING: unique symbol = Symbol("coeval.thing");
+
+/**
+ * A host thing: an object that answers the steps of a path itself, for example a node of a live tree. It is the
+ * own entry of the ladder for the verb `deref`.
+ */
+export interface HostThing {
+  readonly [THING]: true;
+  /** A short text for a reader, for example `node card`. */
+  readonly label: string;
+  /**
+   * This function answers one step.
+   *
+   * @param key - The key of the step.
+   * @returns What the step reaches, or `undefined`.
+   */
+  deref(key: Key): Thing | undefined;
+  /**
+   * This function gives the thing as a value, when a reference ends on it.
+   *
+   * @returns The value.
+   */
+  toJson(): Json;
+}
+
+/** Something that a path can reach: a JSON value, or a host thing. */
+export type Thing = Json | HostThing;
+
+/**
+ * This function tells if a thing is a host thing.
+ *
+ * @param thing - The thing.
+ * @returns `true` for a host thing.
+ */
+export function isHostThing(thing: Thing | undefined): thing is HostThing {
+  return typeof thing === "object" && thing !== null && !Array.isArray(thing) && (thing as Partial<HostThing>)[THING] === true;
+}
+
+/** The roots of a context. Each path starts with one of them. */
+export const ROOTS = ["self", "names", "world", "event", "caps"] as const;
+
+/** One root of a context. */
+export type Root = (typeof ROOTS)[number];
+
+/**
+ * The context of a term: a record with five roots. A reference reaches outside its term only through them.
+ *
+ * - `self`: the node that the term is part of.
+ * - `names`: the values that the evaluators around the term bound.
+ * - `world`: the registry of kinds.
+ * - `event`: the event that started a run.
+ * - `caps`: the effects that the term can cause.
+ */
+export interface Context {
+  readonly self: Thing;
+  readonly names: Readonly<Record<string, Json>>;
+  readonly world: Thing;
+  readonly event: Thing;
+  readonly caps: readonly string[];
+}
+
+/** The code of a `deref` evaluator: it answers one step of a path on a document of its kind. */
+export type DerefCode = (doc: Envelope, key: Key) => Thing | undefined;
+
+/** The result of a step document: what it reached, or the reason of a failure. */
+export type WalkResult = { readonly ok: true; readonly thing: Thing } | { readonly ok: false; readonly reason: string };
+
+/** The input of a walker: the code of a step document, for example `nearest`. */
+export interface WalkInput {
+  /** The value of the step document. */
+  readonly data: Json;
+  /** The thing that the path reached before this step. */
+  readonly here: Thing;
+  readonly context: Context;
+  /**
+   * This function answers one step on a thing, through the ladder.
+   *
+   * @param thing - The thing.
+   * @param key - The key.
+   * @returns What the step reaches, or `undefined`.
+   */
+  deref(thing: Thing, key: Key): Thing | undefined;
+}
+
+/** A walker: the code of the verb `step` of a kind of step documents. */
+export type Walker = (input: WalkInput) => WalkResult;
+
+/** What a resolution needs: the world, and the code of the `deref` evaluators and of the walkers. */
+export interface Navigator {
+  readonly world: World;
+  readonly derefs?: Readonly<Record<string, DerefCode>>;
+  readonly walkers?: Readonly<Record<string, Walker>>;
+}
+
+/** The way that one hop of a path was answered. */
+export type HopBy = "root" | "own" | "kind" | "default" | "step" | "collapse";
+
+/** One hop of a path: the step, what it reached, and who answered it. */
+export interface Hop {
+  readonly step: Json;
+  readonly thing: Thing;
+  readonly by: HopBy;
+}
+
+/** The result of a resolution: what the path reached, with each hop, or an error with the hops before it. */
+export type Resolution =
+  | { readonly ok: true; readonly thing: Thing; readonly hops: readonly Hop[] }
+  | { readonly ok: false; readonly code: "#REF!" | "#CYCLE!" | "#STEP?"; readonly reason: string; readonly hops: readonly Hop[] };
+
+function entryOf(verbs: Readonly<Record<string, string>> | undefined, verb: string): string | undefined {
+  return verbs !== undefined && Object.hasOwn(verbs, verb) ? verbs[verb] : undefined;
+}
+
+function plainStep(thing: Json, key: Key): Json | undefined {
+  if (Array.isArray(thing)) {
+    const index = typeof key === "number" ? key : /^\d+$/.test(key) ? Number(key) : -1;
+    return index >= 0 ? (thing as readonly Json[])[index] : undefined;
+  }
+  if (isRecord(thing) && typeof key === "string") return field(thing, key);
+  return undefined;
+}
+
+/**
+ * This function answers one step of a path on a thing, through the ladder of the verb `deref`. A host thing
+ * answers for itself (own). A document asks its own entry, then its kind. The default goes into the value: a field
+ * of a record, or an item of a list.
+ *
+ * @param nav - The world and the code of the evaluators.
+ * @param thing - The thing that the path reached.
+ * @param key - The key of the step.
+ * @returns What the step reaches and the rung that answered, or `undefined`.
+ */
+export function derefStep(nav: Navigator, thing: Thing, key: Key): { readonly thing: Thing; readonly by: HopBy } | undefined {
+  if (isHostThing(thing)) {
+    const reached = thing.deref(key);
+    return reached === undefined ? undefined : { thing: reached, by: "own" };
+  }
+  const envelope = fromJson(thing);
+  if (envelope !== undefined) {
+    const own = entryOf(envelope.own, "deref");
+    const ownCode = own === undefined ? undefined : nav.derefs?.[own];
+    if (ownCode !== undefined) {
+      const reached = ownCode(envelope, key);
+      return reached === undefined ? undefined : { thing: reached, by: "own" };
+    }
+    const found = lookupKind(nav.world, envelope.type);
+    const name = found.ok ? entryOf(found.kind.verbs, "deref") : undefined;
+    const code = name === undefined ? undefined : nav.derefs?.[name];
+    if (code !== undefined) {
+      const reached = code(envelope, key);
+      return reached === undefined ? undefined : { thing: reached, by: "kind" };
+    }
+    const reached = plainStep(envelope.value, key);
+    return reached === undefined ? undefined : { thing: reached, by: "default" };
+  }
+  const reached = plainStep(thing, key);
+  return reached === undefined ? undefined : { thing: reached, by: "default" };
+}
+
+/**
+ * This function tells if a thing is a reference document: an envelope of the type `ref`.
+ *
+ * @param thing - The thing.
+ * @returns `true` for a reference document.
+ */
+export function isRef(thing: Thing | undefined): thing is Envelope & { readonly value: readonly Json[] } {
+  if (thing === undefined || isHostThing(thing)) return false;
+  const envelope = fromJson(thing);
+  if (envelope === undefined || !Array.isArray(envelope.value)) return false;
+  const path = typePath(envelope.type);
+  return path !== undefined && path.length === 1 && path[0] === "ref";
+}
+
+/**
+ * This function makes the thing of the root `world`: the entries of the world as JSON. An alias is a reference
+ * document in it, thus a walk through the world follows each alias (collapse).
+ *
+ * @param world - The world.
+ * @returns The thing.
+ */
+export function worldThing(world: World): Json {
+  return entriesAsJson(world.kinds);
+}
+
+/**
+ * This function makes a context. The world comes from the navigator when the call gives none.
+ *
+ * @param parts - The roots to set.
+ * @returns The context.
+ */
+export function context(parts: Partial<Context> = {}): Context {
+  return {
+    self: parts.self ?? null,
+    names: parts.names ?? {},
+    world: parts.world ?? null,
+    event: parts.event ?? null,
+    caps: parts.caps ?? [],
+  };
+}
+
+const MAX_COLLAPSE = 64;
+
+/**
+ * This function resolves a path from a context, and records each hop.
+ *
+ * The first step is a root of the context. Each later step is a key or a step document. A key goes up the ladder
+ * of the verb `deref` on the thing that the path reached. A step document is evaluated by the walker of its kind,
+ * with the thing that the path reached. After each hop, a reference document is followed until the path reaches
+ * something else (collapse).
+ *
+ * @param nav - The world and the code of the evaluators.
+ * @param ctx - The context.
+ * @param path - The steps.
+ * @returns What the path reached and each hop, or an error.
+ */
+export function resolve(nav: Navigator, ctx: Context, path: readonly Json[]): Resolution {
+  const hops: Hop[] = [];
+  let collapses = 0;
+
+  const collapse = (thing: Thing): Resolution => {
+    let here = thing;
+    while (isRef(here)) {
+      collapses += 1;
+      if (collapses > MAX_COLLAPSE) return { ok: false, code: "#CYCLE!", reason: "The references form a cycle.", hops };
+      const inner = walk(here.value);
+      if (!inner.ok) return inner;
+      here = inner.thing;
+      hops.push({ step: here === null ? null : "collapse", thing: here, by: "collapse" });
+    }
+    return { ok: true, thing: here, hops };
+  };
+
+  const walk = (steps: readonly Json[]): Resolution => {
+    const [root, ...rest] = steps;
+    if (typeof root !== "string" || !(ROOTS as readonly string[]).includes(root)) {
+      return { ok: false, code: "#REF!", reason: `A path starts with a root: ${ROOTS.join(", ")}.`, hops };
+    }
+    let here: Thing = ctx[root as Root] as Thing;
+    hops.push({ step: root, thing: here, by: "root" });
+    const first = collapse(here);
+    if (!first.ok) return first;
+    here = first.thing;
+    for (const step of rest) {
+      if (isKey(step)) {
+        const reached = derefStep(nav, here, step);
+        if (reached === undefined) return { ok: false, code: "#REF!", reason: `The step ${String(step)} reaches nothing.`, hops };
+        hops.push({ step, thing: reached.thing, by: reached.by });
+        here = reached.thing;
+      } else {
+        const envelope = fromJson(step);
+        const found = envelope === undefined ? undefined : lookupKind(nav.world, envelope.type);
+        const name = found?.ok === true ? entryOf(found.kind.verbs, "step") : undefined;
+        const walker = name === undefined ? undefined : nav.walkers?.[name];
+        if (envelope === undefined || walker === undefined) {
+          return { ok: false, code: "#STEP?", reason: "A step is a key, or a document of a kind with the verb step.", hops };
+        }
+        const result = walker({
+          data: envelope.value,
+          here,
+          context: ctx,
+          deref: (thing, key) => derefStep(nav, thing, key)?.thing,
+        });
+        if (!result.ok) return { ok: false, code: "#REF!", reason: result.reason, hops };
+        hops.push({ step, thing: result.thing, by: "step" });
+        here = result.thing;
+      }
+      const next = collapse(here);
+      if (!next.ok) return next;
+      here = next.thing;
+    }
+    return { ok: true, thing: here, hops };
+  };
+
+  if (path.length === 0) return { ok: false, code: "#REF!", reason: "A path has at least one step: its root.", hops };
+  return walk(path);
+}
+
+/**
+ * This function gives the value of a thing: the thing itself for JSON, or the value that a host thing gives.
+ *
+ * @param thing - The thing.
+ * @returns The value.
+ */
+export function valueOfThing(thing: Thing): Json {
+  return isHostThing(thing) ? thing.toJson() : thing;
+}

package/src/doc.ts

@@ -0,0 +1,182 @@
+/** A JSON value. */
+export type Json = null | boolean | number | string | readonly Json[] | { readonly [key: string]: Json };
+
+/** A JSON record. */
+export type JsonRecord = { readonly [key: string]: Json };
+
+/** One step of a path that is a plain key: a name, or an index of a list. */
+export type Key = string | number;
+
+/**
+ * The type of a document is a reference into the world (the registry of kinds).
+ *
+ * - A text is a base reference with one key: `"add"`.
+ * - A list of keys is a base reference with a path: `["git", "push"]`.
+ * - A document of type `ref` is the same reference, expanded. Its path starts at the root `world`.
+ *
+ * The kernel resolves a base reference itself. The expanded form is necessary only to attach more to the
+ * reference. Thus the chain of types stops at a base reference.
+ */
+export type TypeRef = string | readonly Key[] | { readonly type: "ref"; readonly value: readonly Json[] };
+
+/**
+ * A typed document: an envelope with a header and a value. The header names the type of the value. The value is
+ * not changed by the envelope at any time. Thus any JSON value can have a type: a number, a list, a text or a record.
+ */
+export type Envelope = {
+  /** The type: a reference to a kind of the world. */
+  readonly type: TypeRef;
+  /** The value. */
+  readonly value: Json;
+  /** The name of a binding. A sequence gives the result of this document to the later steps under this name. */
+  readonly name?: string;
+  /** The own entries: one evaluator name for each verb. An own entry changes only this document. */
+  readonly own?: Readonly<Record<string, string>>;
+};
+
+/** The keys that an envelope can have. */
+export const ENVELOPE_KEYS = ["type", "value", "name", "own"] as const;
+
+/**
+ * This function tells if a value is a JSON record (not an array and not null).
+ *
+ * @param value - The value to examine.
+ * @returns `true` for a record.
+ */
+export function isRecord(value: Json | undefined): value is JsonRecord {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * This function reads a field of a record. It reads only the own fields, thus `constructor` is not a field.
+ *
+ * @param record - The record.
+ * @param key - The name of the field.
+ * @returns The value of the field, or `undefined` when the record has no such field.
+ */
+export function field(record: JsonRecord, key: string): Json | undefined {
+  return Object.hasOwn(record, key) ? record[key] : undefined;
+}
+
+/**
+ * This function tells if a value is a key of a path: a text, or a whole number from 0.
+ *
+ * @param value - The value to examine.
+ * @returns `true` for a key.
+ */
+export function isKey(value: Json | undefined): value is Key {
+  return typeof value === "string" || (typeof value === "number" && Number.isInteger(value) && value >= 0);
+}
+
+/**
+ * This function tells if a value is a reference to a type. The reference is a text, a list of keys, or a document
+ * of type `ref` whose path starts at the root `world`.
+ *
+ * @param value - The value to examine.
+ * @returns `true` for a reference to a type.
+ */
+export function isTypeRef(value: Json | undefined): boolean {
+  if (typeof value === "string") return value !== "";
+  if (Array.isArray(value)) return value.length > 0 && (value as readonly Json[]).every(isKey);
+  if (!isRecord(value)) return false;
+  const path = field(value, "value");
+  return field(value, "type") === "ref" && Array.isArray(path) && (path as readonly Json[])[0] === "world";
+}
+
+/**
+ * This function gives the path of a reference to a type, from the root of the world.
+ *
+ * @param type - The reference.
+ * @returns The keys from the root of the world, or `undefined` for a computed step that has no fixed key.
+ */
+export function typePath(type: TypeRef): readonly Key[] | undefined {
+  if (typeof type === "string") return [type];
+  if (Array.isArray(type)) return type as readonly Key[];
+  const steps = (type as { readonly value: readonly Json[] }).value.slice(1);
+  return steps.every(isKey) ? (steps as readonly Key[]) : undefined;
+}
+
+/**
+ * This function gives the text of a type for a reader: its keys, joined with a dot.
+ *
+ * @param type - The reference to the type.
+ * @returns The text, for example `git.push`.
+ */
+export function typeName(type: TypeRef): string {
+  return typePath(type)?.join(".") ?? "(computed)";
+}
+
+/**
+ * This function tells if a value has the form of an envelope. That form is a record with a reference to a type
+ * and a `value`. It has no other keys than the keys of an envelope. A contract decides where an envelope is
+ * expected. This function only checks the form.
+ *
+ * @param value - The value to examine.
+ * @returns `true` when the value has the form of an envelope.
+ */
+export function isEnvelope(value: Json | undefined): value is JsonRecord & Envelope {
+  if (!isRecord(value)) return false;
+  if (!isTypeRef(field(value, "type")) || !Object.hasOwn(value, "value")) return false;
+  const name = field(value, "name");
+  if (name !== undefined && typeof name !== "string") return false;
+  const own = field(value, "own");
+  if (own !== undefined && !isRecord(own)) return false;
+  return Object.keys(value).every((key) => (ENVELOPE_KEYS as readonly string[]).includes(key));
+}
+
+/**
+ * This function makes an envelope.
+ *
+ * @param type - The reference to the kind.
+ * @param value - The value.
+ * @param header - The optional name and own entries.
+ * @returns The envelope.
+ */
+export function typed(type: TypeRef, value: Json, header: { readonly name?: string; readonly own?: Record<string, string> } = {}): Envelope {
+  return { type, value, ...(header.name === undefined ? {} : { name: header.name }), ...(header.own === undefined ? {} : { own: header.own }) };
+}
+
+/**
+ * This function makes a reference document: a path from a root of the context.
+ *
+ * @param path - The steps. The first step is a root: `self`, `names`, `world`, `event` or `caps`.
+ * @returns The document of type `ref`.
+ */
+export function ref(...path: readonly Json[]): Envelope {
+  return typed("ref", path);
+}
+
+/**
+ * This function gives an envelope as a JSON record, for a store or for a view.
+ *
+ * @param doc - The envelope.
+ * @returns The same envelope as JSON.
+ */
+export function toJson(doc: Envelope): JsonRecord {
+  return {
+    type: doc.type as Json,
+    value: doc.value,
+    ...(doc.name === undefined ? {} : { name: doc.name }),
+    ...(doc.own === undefined ? {} : { own: doc.own }),
+  };
+}
+
+/**
+ * This function reads an envelope from JSON. A value without the form of an envelope gives `undefined`.
+ *
+ * @param value - The JSON value.
+ * @returns The envelope, or `undefined`.
+ */
+export function fromJson(value: Json | undefined): Envelope | undefined {
+  if (!isEnvelope(value)) return undefined;
+  const own = field(value, "own");
+  const ownEntries: Record<string, string> = {};
+  if (isRecord(own)) {
+    for (const [verb, name] of Object.entries(own)) if (typeof name === "string") ownEntries[verb] = name;
+  }
+  const name = field(value, "name");
+  return typed(field(value, "type") as TypeRef, field(value, "value") ?? null, {
+    ...(typeof name === "string" ? { name } : {}),
+    ...(isRecord(own) ? { own: ownEntries } : {}),
+  });
+}