@mark1russell7/coeval 0.1.0 → 0.2.0

package/src/stdlib.ts

@@ -1,5 +1,5 @@
 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 Context, type Evaluator, type Machine, type Part, type Result, type RunPart, type Runner, type Steps, fail, ok } from "./evaluate.ts";
 import { type HostThing, type Thing, type Walker, THING, isHostThing, valueOfThing } from "./deref.ts";
 import type { World } from "./ladder.ts";
 
@@ -60,6 +60,10 @@ export const STD_WORLD: World = {
     seq: {
       verbs: { eval: "control.seq", view: "view.seq" },
       parts: { shape: "list" },
+      scope: [
+        { names: { headers: true }, in: [["*"]], sequential: true },
+        { names: { fixed: ["last"] }, in: [["*"]], sequential: true },
+      ],
       summary: "Its steps, in order. The result of a named step is a name for the later steps.",
     },
     pure: {
@@ -83,12 +87,12 @@ export const STD_WORLD: World = {
   defaults: { view: "view.card" },
 };
 
-function isNumber(value: Json): value is number {
+function isNumber(value: unknown): 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 } {
+function allValues(results: readonly Result[]): { readonly values: readonly unknown[] } | { readonly error: Result } {
   const errors = results.filter((result) => !result.ok);
   const first = errors[0];
   if (first !== undefined && errors.length === 1) return { error: first };
@@ -96,7 +100,7 @@ function allValues(results: readonly Result[]): { readonly values: readonly Json
   return { values: results.map((result) => (result.ok ? result.value : null)) };
 }
 
-function numbers(values: readonly Json[], kind: string): readonly number[] | Result {
+function numbers(values: readonly unknown[], 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);
@@ -139,11 +143,8 @@ export const STD_EVALUATORS: Readonly<Record<string, Evaluator>> = {
     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);
+    const found = resolve(data as readonly Json[]);
+    return found.ok ? ok(valueOfThing(found.thing)) : fail(found.code, found.reason);
   },
   "tree.node": (input) => treeNode(input.parts, input.context, input.kind),
 };
@@ -173,8 +174,8 @@ function treeNode(parts: readonly Part[], context: Context, type: string): Resul
       const result = read(String(key));
       return result?.ok === true ? result.value : undefined;
     },
-    toJson(): Json {
-      const out: Record<string, Json> = {};
+    toJson(): unknown {
+      const out: Record<string, unknown> = {};
       for (const part of parts) {
         const result = read(part.key);
         out[part.key] = result?.ok === true ? result.value : null;
@@ -182,7 +183,7 @@ function treeNode(parts: readonly Part[], context: Context, type: string): Resul
       return out;
     },
   };
-  const out: Record<string, Json> = {};
+  const out: Record<string, unknown> = {};
   for (const part of parts) {
     const result = read(part.key);
     if (result === undefined) continue;
@@ -192,31 +193,57 @@ function treeNode(parts: readonly Part[], context: Context, type: string): Resul
   return ok(out);
 }
 
+/** The options of a walker `nearest`. */
+export interface NearestOptions {
+  /**
+   * This function tells if a node has the wanted type. The default compares the field `type` of a host thing.
+   *
+   * @param node - The node that the walk reached.
+   * @param wanted - The type that the step document asks for.
+   * @returns `true` when the node has the type.
+   */
+  readonly matches?: (node: Thing, wanted: Json | undefined) => boolean;
+  /** The most hops of one walk. The default is 256. */
+  readonly maxHops?: number;
+}
+
+function hostType(node: Thing, wanted: Json | undefined): boolean {
+  return isHostThing(node) && (node as { readonly type?: unknown }).type === wanted;
+}
+
 /**
- * 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.
+ * This function makes a walker `nearest`. The walker 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.
+ *
+ * @param options - The test of a type and the most hops.
+ * @returns The walker.
  */
-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." };
-};
+export function nearestWalker(options: NearestOptions = {}): Walker {
+  const matches = options.matches ?? hostType;
+  const maxHops = options.maxHops ?? 256;
+  return ({ 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 < maxHops; 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.` };
+      if (matches(at, wanted)) return { ok: true, thing: at };
+    }
+    return { ok: false, reason: "The walk is too long." };
+  };
+}
+
+const nearest: Walker = nearestWalker();
 
 /** 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[] = [];
+function* inOrder(parts: readonly RunPart[]): Generator<Promise<unknown>, { readonly values: readonly unknown[] } | { readonly error: Result }, unknown> {
+  const values: unknown[] = [];
   for (const part of parts) {
     const result = yield* part.evaluate();
     if (!result.ok) return { error: result };
@@ -230,9 +257,9 @@ function* inOrder(parts: readonly RunPart[]): Generator<Promise<Result>, { reado
  * 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;
+  "control.seq": function* ({ parts, context }): Steps {
+    let names: Record<string, unknown> = { ...context.names };
+    let last: unknown = null;
     for (const part of parts) {
       const result = yield* part.evaluate({ ...context, names });
       if (!result.ok) return result;

package/src/world.ts

@@ -4,33 +4,84 @@ import { type Envelope, type Json, type Key, type TypeRef, field, isRecord, type
 export type Side = "derive" | "run";
 
 /**
- * Where the parts of a value are. A part is a typed document that the evaluator gets sealed.
+ * Where the parts of a value are: the shape of the value. A part is a typed document that the evaluator gets
+ * sealed. `of` is the type of a bare part: a part without an envelope gets this type from its position.
  *
  * - `none`: the value is data. It has no parts.
- * - `list`: the value is a list, and each item is a part.
- * - `record`: the value is a record. The named fields are parts, and the other fields are data.
- *
- * `of` is the type of a bare item. An item without an envelope gets this type from its container.
+ * - `term`: the value itself is one part.
+ * - `list`: the value is a list. Each item has the shape `item` (the default is a part).
+ * - `map`: the value is a record. Each field has the shape `item` (the default is a part).
+ * - `record`: the value is a record. Each named field has its shape. A list of names makes each named field a
+ *   part. The other fields have the shape `rest` (the default is data). `required` names the fields that must be.
+ * - `deep`: each envelope at any depth of the value is a part, and the rest is data.
  */
-export type PartsSpec =
+export type Shape =
   | { readonly shape: "none" }
-  | { readonly shape: "list"; readonly of?: string }
-  | { readonly shape: "record"; readonly fields: readonly string[]; readonly of?: string };
+  | { readonly shape: "term"; readonly of?: string }
+  | { readonly shape: "list"; readonly of?: string; readonly item?: Shape }
+  | { readonly shape: "map"; readonly of?: string; readonly item?: Shape }
+  | {
+      readonly shape: "record";
+      readonly fields: readonly string[] | Readonly<Record<string, Shape>>;
+      readonly of?: string;
+      readonly required?: readonly string[];
+      readonly rest?: Shape;
+    }
+  | { readonly shape: "deep"; readonly of?: string };
+
+/** The former name of `Shape`. */
+export type PartsSpec = Shape;
+
+/**
+ * Where the names of a scope rule come from.
+ *
+ * - `fixed`: the names in the list.
+ * - `keysAt`: the keys of the record at this path of the value, for example the bindings of a `let`.
+ * - `listAt`: the texts of the list at this path of the value, for example the parameters of a `fn`.
+ * - `textAt`: the text at this path of the value, or `otherwise` when the value has no text there.
+ * - `headers`: the binding name (`name`) of each part that the rule covers.
+ */
+export type NamesSource =
+  | { readonly fixed: readonly string[] }
+  | { readonly keysAt: readonly Key[] }
+  | { readonly listAt: readonly Key[] }
+  | { readonly textAt: readonly Key[]; readonly otherwise?: string }
+  | { readonly headers: true };
+
+/**
+ * A scope rule of a kind: names that the kind binds, and the parts that see them. The static kit reads the rules,
+ * and the evaluator of the kind binds the same names when it evaluates the parts.
+ */
+export interface ScopeRule {
+  readonly names: NamesSource;
+  /** The parts that see the names, as patterns of their paths in the value. The key `"*"` matches each key. */
+  readonly in: readonly (readonly Key[])[];
+  /** `true`: a part sees only the names of the parts before it, as in a sequence. */
+  readonly sequential?: boolean;
+}
 
 /** A kind gives the name of an evaluator for each verb, and the contract of its value. */
 export interface Kind {
   readonly verbs: Readonly<Record<string, string>>;
   /** Where the parts of the value are. The default is `none`. */
-  readonly parts?: PartsSpec;
+  readonly parts?: Shape;
+  /** The names that the kind binds for its parts. */
+  readonly scope?: readonly ScopeRule[];
   /** The side of the kind. A kind of the run side causes effects. The default is `derive`. */
   readonly side?: Side;
+  /**
+   * The effects that a document of this kind can cause. It is a list of the kinds of the effects. The text
+   * `"type"` means that the kind of the effect is the type of the document itself, as for a call.
+   */
+  readonly effects?: "type" | readonly string[];
   /** One sentence that tells what the kind is. */
   readonly summary?: string;
 }
 
-/** A namespace: a group of entries under one key of the world. */
+/** A namespace: a group of entries under one key of the world. `fallback` is the kind of each other key in it. */
 export interface Namespace {
   readonly kinds: Readonly<Record<string, WorldEntry>>;
+  readonly fallback?: Kind;
 }
 
 /** An alias: a reference to another entry of the world. The lookup follows it (collapse). */
@@ -70,6 +121,16 @@ export function isAlias(entry: WorldEntry | undefined): entry is Alias {
   return entry !== undefined && (entry as { type?: unknown }).type === "ref" && Array.isArray((entry as { value?: unknown }).value);
 }
 
+/**
+ * This function tells if an entry of the world is a namespace.
+ *
+ * @param entry - The entry.
+ * @returns `true` for a namespace.
+ */
+export function isNamespace(entry: WorldEntry | undefined): entry is Namespace {
+  return entry !== undefined && !isKind(entry) && !isAlias(entry) && Object.hasOwn(entry, "kinds");
+}
+
 function entryAt(entries: Readonly<Record<string, WorldEntry>>, key: Key): WorldEntry | undefined {
   const name = String(key);
   return Object.hasOwn(entries, name) ? entries[name] : undefined;
@@ -77,7 +138,8 @@ function entryAt(entries: Readonly<Record<string, WorldEntry>>, key: Key): World
 
 /**
  * This function finds the kind that a type names. It walks the path from the root of the world, one key at a
- * time. An alias on the way is followed until a kind answers (collapse). A cycle of aliases stops the lookup.
+ * time. An alias on the way is followed until a kind answers (collapse). A cycle of aliases stops the lookup. In a
+ * namespace with a fallback, a key that the namespace does not have gets the fallback kind.
  *
  * @param world - The world.
  * @param type - The reference to the type.
@@ -90,12 +152,16 @@ export function lookupKind(world: World, type: TypeRef): Lookup {
   let aliases = 0;
   for (;;) {
     let entries = world.kinds;
+    let fallback: Kind | undefined;
     let entry: WorldEntry | undefined;
     let followed = false;
     for (let index = 0; index < path.length; index += 1) {
       const key = path[index] as Key;
       entry = entryAt(entries, key);
-      if (entry === undefined) return { ok: false, reason: "unknown", path };
+      if (entry === undefined) {
+        if (fallback !== undefined) return { ok: true, kind: fallback, path, aliases };
+        return { ok: false, reason: "unknown", path };
+      }
       if (isAlias(entry)) {
         aliases += 1;
         if (aliases > 32) return { ok: false, reason: "cycle", path };
@@ -108,8 +174,9 @@ export function lookupKind(world: World, type: TypeRef): Lookup {
         break;
       }
       if (index < path.length - 1) {
-        if (isKind(entry)) return { ok: false, reason: "not-a-kind", path };
-        entries = (entry as Namespace).kinds;
+        if (!isNamespace(entry)) return { ok: false, reason: "not-a-kind", path };
+        entries = entry.kinds;
+        fallback = entry.fallback;
       }
     }
     if (followed) continue;
@@ -135,6 +202,16 @@ export function entriesAsJson(entries: Readonly<Record<string, WorldEntry>>): Js
   return out;
 }
 
+function describeShape(shape: Shape | undefined): Json {
+  if (shape === undefined || shape.shape === "none") return "none";
+  if (shape.shape === "term") return `a part${shape.of === undefined ? "" : ` of ${shape.of}`}`;
+  if (shape.shape === "deep") return "each document in the value";
+  if (shape.shape === "list") return `a list${shape.of === undefined ? "" : ` of ${shape.of}`}`;
+  if (shape.shape === "map") return `a record of parts${shape.of === undefined ? "" : ` of ${shape.of}`}`;
+  const names = Array.isArray(shape.fields) ? shape.fields : Object.keys(shape.fields);
+  return `the fields ${names.join(", ")}`;
+}
+
 /**
  * This function makes the document of a kind, so that a view can draw it as each other document.
  *
@@ -143,13 +220,10 @@ export function entriesAsJson(entries: Readonly<Record<string, WorldEntry>>): Js
  * @returns The document of type `kind`.
  */
 export function kindDocument(name: string, kind: Kind): Envelope {
-  const parts: Json =
-    kind.parts === undefined || kind.parts.shape === "none"
-      ? "none"
-      : kind.parts.shape === "list"
-        ? `a list${kind.parts.of === undefined ? "" : ` of ${kind.parts.of}`}`
-        : `the fields ${kind.parts.fields.join(", ")}`;
-  return { type: "kind", value: { name, verbs: { ...kind.verbs }, parts, side: kind.side ?? "derive", summary: kind.summary ?? "" } };
+  return {
+    type: "kind",
+    value: { name, verbs: { ...kind.verbs }, parts: describeShape(kind.parts), side: kind.side ?? "derive", summary: kind.summary ?? "" },
+  };
 }
 
 /**
@@ -158,6 +232,6 @@ export function kindDocument(name: string, kind: Kind): Envelope {
  * @param value - The value.
  * @returns `true` when the value has verbs.
  */
-export function looksLikeKind(value: Json | undefined): boolean {
+export function looksLikeKind(value: unknown): boolean {
   return isRecord(value) && isRecord(field(value, "verbs"));
 }