@mark1russell7/coeval 0.3.0 → 0.3.2

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package",
   "name": "@mark1russell7/coeval",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "coeval: the kernel of declarative languages. Documents in envelopes, a ladder that finds the evaluator, kind contracts, compiled plans, a static kit, a formula kit and a run side with capabilities.",
   "type": "module",
   "main": "./build/index.js",

package/src/doc.ts

@@ -106,6 +106,7 @@ export function typePath(type: TypeRef): readonly Key[] | undefined {
  * @returns The text, for example `git.push`.
  */
 export function typeName(type: TypeRef): string {
+  if (typeof type === "string") return type;
   return typePath(type)?.join(".") ?? "(computed)";
 }
 
@@ -126,9 +127,12 @@ function headerFits(value: JsonRecord): boolean {
  * @returns `true` when the value has the form of an envelope.
  */
 export function isEnvelope(value: unknown): value is JsonRecord & Envelope {
-  if (!isRecord(value) || !headerFits(value)) return false;
-  for (const key in value) if (Object.hasOwn(value, key) && !(ENVELOPE_KEYS as readonly string[]).includes(key)) return false;
-  return true;
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+  // The keys come first: most values that are not envelopes have another key, thus the check stops early.
+  for (const key in value) {
+    if (key !== "type" && key !== "value" && key !== "name" && key !== "own" && Object.hasOwn(value, key)) return false;
+  }
+  return isRecord(value) && headerFits(value);
 }
 
 /** A stored document: an envelope, and the keys of its store beside it, for example `_id`. */

package/src/evaluate.ts

@@ -1,7 +1,7 @@
-import { type Envelope, type Json, type Key, type TypeRef, isEnvelope, isRecord, typeName } from "./doc.ts";
+import { type Envelope, type Json, type Key, type TypeRef, isEnvelope, typeName } from "./doc.ts";
 import { splitParts } from "./parts.ts";
 import { ask, type Answer } from "./ladder.ts";
-import { type Side, lookupKind } from "./world.ts";
+import { type Lookup, type Side, type World, lookupKind } from "./world.ts";
 import { type ErrorCode, type EvalError, type Result, fail, ok, placed, thrown, describe } from "./errors.ts";
 import {
   type Cap,
@@ -145,10 +145,22 @@ export interface Runtime {
    * This function drives several steps at the same time. When one waits, the others go on.
    *
    * @param list - One function for each item. Each function starts the steps of its item.
-   * @param options - The most items that run at the same time. The default is each item.
+   * @param options - The most items that run at the same time, and the stop at the first failure.
    * @returns The steps that give each result, in the order of the list.
    */
-  all(list: readonly (() => Steps)[], options?: { readonly concurrency?: number }): Generator<Promise<unknown>, readonly Result[], unknown>;
+  all(list: readonly (() => Steps)[], options?: AllOptions): Generator<Promise<unknown>, readonly Result[], unknown>;
+}
+
+/**
+ * The options of a drive of parts at the same time.
+ *
+ * - `concurrency`: the most parts that run at the same time. The default is each part.
+ * - `failFast`: `true` stops at the first part that fails. The parts that did not start do not start, the parts that
+ *   run stop at their wait, and the results come at once. Each part without a result gives `#ABORT`.
+ */
+export interface AllOptions {
+  readonly concurrency?: number;
+  readonly failFast?: boolean;
 }
 
 /** Compiled code: the evaluation of a document in a context. */
@@ -187,6 +199,14 @@ export interface CompileInput {
   /** The keys from the root document to this document. */
   readonly place: readonly Key[];
   readonly machine: Machine;
+  /**
+   * This function gives the value of the document with an item in the place of each part. The containers on the way
+   * to a part are new. The data around the parts stays the same objects.
+   *
+   * @param items - One item for each part, in the order of `parts`, for example the results of the parts.
+   * @returns The value with the items.
+   */
+  fill(items: readonly unknown[]): unknown;
 }
 
 /**
@@ -243,6 +263,14 @@ export interface EvalInput {
    * @returns The payload, or the error `#CAP!`.
    */
   effect(kind: Cap, payload: unknown): Result;
+  /**
+   * This function gives the value of the document with an item in the place of each part, for example the result of
+   * each part. The containers on the way to a part are new. The data around the parts stays the same objects.
+   *
+   * @param items - One item for each part, in the order of `parts`.
+   * @returns The value with the items.
+   */
+  fill(items: readonly unknown[]): unknown;
 }
 
 /** A part for a runner. Its evaluation can wait for the effects in it. */
@@ -284,13 +312,22 @@ export interface RunInput {
    */
   effect(kind: Cap, payload: unknown): Steps;
   /**
-   * This function evaluates parts at the same time. Take the results with `yield*`.
+   * This function evaluates parts at the same time. Take the results with `yield*`. A runner can give its own parts,
+   * for example a part with a different context: each part needs only the function `evaluate`.
    *
    * @param parts - The parts.
-   * @param options - The most parts that run at the same time.
+   * @param options - The most parts that run at the same time, and the stop at the first failure.
    * @returns The steps that give each result, in the order of the parts.
    */
-  all(parts: readonly RunPart[], options?: { readonly concurrency?: number }): Generator<Promise<unknown>, readonly Result[], unknown>;
+  all(parts: readonly RunPart[], options?: AllOptions): Generator<Promise<unknown>, readonly Result[], unknown>;
+  /**
+   * This function gives the value of the document with an item in the place of each part, for example the result of
+   * each part. The containers on the way to a part are new. The data around the parts stays the same objects.
+   *
+   * @param items - One item for each part, in the order of `parts`.
+   * @returns The value with the items.
+   */
+  fill(items: readonly unknown[]): unknown;
 }
 
 /** An evaluator that is a function of its input. The kernel calls it for each evaluation. */
@@ -520,9 +557,11 @@ class Session implements Runtime {
     return (yield done.then((value: unknown) => ok(value), failed)) as Result;
   }
 
-  *all(list: readonly (() => Steps)[], options: { readonly concurrency?: number } = {}): Generator<Promise<unknown>, readonly Result[], unknown> {
+  *all(list: readonly (() => Steps)[], options: AllOptions = {}): Generator<Promise<unknown>, readonly Result[], unknown> {
     const results: Result[] = new Array<Result>(list.length);
     const limit = Math.max(1, options.concurrency ?? list.length);
+    const failFast = options.failFast === true;
+    let failed = false;
     interface Active {
       readonly index: number;
       readonly steps: Steps;
@@ -530,16 +569,20 @@ class Session implements Runtime {
     }
     const active: Active[] = [];
     let next = 0;
+    const settle = (index: number, result: Result): void => {
+      results[index] = result;
+      if (failFast && !result.ok) failed = true;
+    };
     const advance = (index: number, steps: Steps, input: { readonly value?: unknown; readonly error?: unknown; readonly threw: boolean }): void => {
       let step: IteratorResult<Promise<unknown>, Result>;
       try {
         step = input.threw ? steps.throw(input.error) : steps.next(input.value);
       } catch (error) {
-        results[index] = thrown(error, "a part");
+        settle(index, thrown(error, "a part"));
         return;
       }
       if (step.done === true) {
-        results[index] = step.value;
+        settle(index, step.value);
         return;
       }
       const item: Active = { index, steps, pending: Promise.resolve() };
@@ -550,7 +593,7 @@ class Session implements Runtime {
       active.push(item);
     };
     const start = (): void => {
-      while (active.length < limit && next < list.length) {
+      while (!failed && active.length < limit && next < list.length) {
         const index = next;
         next += 1;
         const begin = list[index] as () => Steps;
@@ -558,14 +601,14 @@ class Session implements Runtime {
         try {
           steps = begin();
         } catch (error) {
-          results[index] = thrown(error, "a part");
+          settle(index, thrown(error, "a part"));
           continue;
         }
         advance(index, steps, { threw: false });
       }
     };
     start();
-    while (active.length > 0) {
+    while (active.length > 0 && !failed) {
       const settled = (yield Promise.race(active.map((item) => item.pending))) as {
         readonly item: Active;
         readonly value?: unknown;
@@ -576,6 +619,16 @@ class Session implements Runtime {
       advance(settled.item.index, settled.item.steps, settled);
       start();
     }
+    if (!failed) return results;
+    const stopped = fail("#ABORT", "The part stopped: a part before it failed, and the parts run with failFast.");
+    for (const item of active) {
+      try {
+        item.steps.return(stopped);
+      } catch {
+        // The finally code of a part threw. The part stops with the abort.
+      }
+    }
+    for (let index = 0; index < list.length; index += 1) if (results[index] === undefined) results[index] = stopped;
     return results;
   }
 
@@ -777,23 +830,50 @@ function finish(c: Compiler, meta: Meta, code: Code, run: RunCode): { readonly c
   return { code: tracedCode, run: tracedRun };
 }
 
+/**
+ * This function finds the evaluator of the verb `eval` without the record of the rungs, for a compilation without a
+ * trace. It gives the same evaluator as `ask`: the own entry, then the kind, then the default of the world.
+ */
+function evaluatorOf(world: World, envelope: Envelope | undefined, found: Lookup): { readonly name?: string; readonly unknown: boolean } {
+  const own = envelope?.own;
+  const ownName = own !== undefined && Object.hasOwn(own, "eval") ? own["eval"] : undefined;
+  if (ownName !== undefined) return { name: ownName, unknown: false };
+  if (!found.ok) return { unknown: true };
+  const verbs = found.kind.verbs;
+  const name = Object.hasOwn(verbs, "eval") ? verbs["eval"] : Object.hasOwn(world.defaults, "eval") ? world.defaults["eval"] : undefined;
+  return name === undefined ? { unknown: false } : { name, unknown: false };
+}
+
+/** The meta of a node of a compilation without a trace. Only a trace reads the meta of a node. */
+const NO_META: Meta = Object.freeze({ path: [], doc: { type: "?", value: null }, declared: false, answer: NO_ANSWER, side: "derive" });
+
 function compileNode(c: Compiler, value: unknown, place: readonly Key[], declared: string | undefined, depth: number): { readonly code: Code; readonly run: RunCode } {
   const envelope = isEnvelope(value) ? (value as Envelope) : undefined;
   const doc: Envelope = envelope ?? { type: declared ?? "?", value: value as Json };
-  const path = place.map(String);
-  const meta0: Meta = { path, doc, declared: envelope === undefined, answer: NO_ANSWER, side: "derive" };
+  const meta0: Meta = c.traced ? { path: place.map(String), doc, declared: envelope === undefined, answer: NO_ANSWER, side: "derive" } : NO_META;
   if (envelope === undefined && declared === undefined) {
     return failing(c, meta0, place, "#PART?", "The value has no envelope, and its position declares no type.");
   }
   if (depth > c.maxDepth) return failing(c, meta0, place, "#DEPTH!", `The nesting is deeper than ${c.maxDepth} documents.`);
 
-  const answer = ask(c.machine.world, envelope ?? {}, "eval", declared === undefined ? {} : { declaredType: declared });
-  const found = lookupKind(c.machine.world, doc.type);
+  const world = c.machine.world;
+  const found = lookupKind(world, doc.type);
   const kind = found.ok ? found.kind : undefined;
-  const meta: Meta = { ...meta0, answer, side: kind?.side ?? "derive" };
+  let meta = meta0;
+  let name: string | undefined;
+  let unknown: boolean;
+  if (c.traced) {
+    const answer = ask(world, envelope ?? {}, "eval", declared === undefined ? {} : { declaredType: declared });
+    meta = { ...meta0, answer, side: kind?.side ?? "derive" };
+    name = answer.evaluator;
+    unknown = answer.error === "unknown-kind";
+  } else {
+    const quick = evaluatorOf(world, envelope, found);
+    name = quick.name;
+    unknown = quick.unknown;
+  }
   const kindText = typeName(doc.type);
-  if (answer.error === "unknown-kind") return failing(c, meta, place, "#KIND?", `The world has no kind ${kindText}.`);
-  const name = answer.evaluator;
+  if (unknown) return failing(c, meta, place, "#KIND?", `The world has no kind ${kindText}.`);
   const runners = c.machine.runners ?? {};
   const runner = name !== undefined && Object.hasOwn(runners, name) ? runners[name] : undefined;
   const evaluator = name !== undefined && Object.hasOwn(c.machine.evaluators, name) ? c.machine.evaluators[name] : undefined;
@@ -807,9 +887,13 @@ function compileNode(c: Compiler, value: unknown, place: readonly Key[], declare
     return failing(c, meta, place, "#VALUE!", `${split.reason}${at} The kind is ${kindText}.`);
   }
   const parts: CompiledPart[] = split.parts.map((slot) => {
-    const compiled = compileNode(c, slot.item, [...place, ...slot.path], slot.of, depth + 1);
-    const header = isEnvelope(slot.item) && isRecord(slot.item) && typeof slot.item["name"] === "string" ? slot.item["name"] : undefined;
-    return { key: slot.key, path: slot.path, ...(header === undefined ? {} : { name: header }), code: compiled.code, run: compiled.run };
+    const item = slot.item;
+    const compiled = compileNode(c, item, place.concat(slot.path), slot.of, depth + 1);
+    // The binding name is in the header of an envelope. Most parts have no name, thus the cheap test comes first.
+    const header = typeof (item as { readonly name?: unknown } | null)?.name === "string" && isEnvelope(item) ? (item as { readonly name: string }).name : undefined;
+    return header === undefined
+      ? { key: slot.key, path: slot.path, code: compiled.code, run: compiled.run }
+      : { key: slot.key, path: slot.path, name: header, code: compiled.code, run: compiled.run };
   });
   const typePath = found.ok ? found.path : [];
   const input: CompileInput = {
@@ -821,9 +905,8 @@ function compileNode(c: Compiler, value: unknown, place: readonly Key[], declare
     parts,
     place,
     machine: c.machine,
+    fill: (items) => (split.parts.length === 0 ? doc.value : split.fill(items)),
   };
-  const who = `the evaluator ${name}`;
-
   if (runner !== undefined) {
     const inner: RunCode = isCompiledRunner(runner) ? runner.compileRun(input) : interpretRun(runner, input, split.fill);
     const run: RunCode = function* (ctx, rt) {
@@ -847,7 +930,7 @@ function compileNode(c: Compiler, value: unknown, place: readonly Key[], declare
     try {
       return placed(inner(ctx, rt), place);
     } catch (error) {
-      return placed(thrown(error, who), place);
+      return placed(thrown(error, `the evaluator ${name}`), place);
     }
   };
   return finish(c, meta, code, function* (ctx, rt) {
@@ -877,6 +960,7 @@ function interpret(fn: EvalFn, input: CompileInput, fill: <P>(handles: readonly
       place,
       resolve: (path, options) => rt.resolve(ctx, path, options),
       effect: (effectKind, payload) => rt.effect(ctx, effectKind, payload, place),
+      fill: input.fill,
     });
   };
 }
@@ -904,6 +988,7 @@ function interpretRun(fn: RunFn, input: CompileInput, fill: <P>(handles: readonl
       resolve: (path, options) => rt.resolve(ctx, path, options),
       effect: (effectKind, payload) => rt.runEffect(ctx, effectKind, payload, place),
       all: (list, options) => rt.all(list.map((part) => () => part.evaluate()), options),
+      fill: input.fill,
     });
   };
 }
@@ -940,8 +1025,8 @@ export function prepare(machine: Machine, doc: unknown, options: PrepareOptions
     machine,
     traced: c.traced,
     root: compiled,
-    evaluate(context: Context = makeContext(), evalOptions: EvalOptions = {}): Result {
-      const s = new Session(machine, false, c.traced, undefined, undefined, evalOptions.effects);
+    evaluate(context: Context = makeContext(), evalOptions?: EvalOptions): Result {
+      const s = new Session(machine, false, c.traced, undefined, undefined, evalOptions?.effects);
       return root.code(rootContext(machine, context), s);
     },
     run(context: Context = makeContext(), runOptions: RunOptions = {}): Promise<Result> {

package/src/formula.ts

@@ -84,8 +84,13 @@ function strictTruthy(value: unknown): boolean | undefined {
   return typeof value === "boolean" ? value : undefined;
 }
 
+/**
+ * This function sets an own data property. Only the key `__proto__` needs `defineProperty`: an assignment to it
+ * changes the prototype. An assignment is faster for each other key of a new plain object.
+ */
 function setOwn(target: Record<string, unknown>, key: string, value: unknown): void {
-  Object.defineProperty(target, key, { value, enumerable: true, writable: true, configurable: true });
+  if (key === "__proto__") Object.defineProperty(target, key, { value, enumerable: true, writable: true, configurable: true });
+  else target[key] = value;
 }
 
 function compiled(compile: (input: CompileInput) => Code): CompiledEvaluator {
@@ -193,16 +198,18 @@ export function formulaEvaluators(profile: FormulaProfile = {}): Readonly<Record
     }),
 
     "formula.record": compiled(({ value }) => {
-      const fields = Object.entries(partsOf(value));
+      const fields = partsOf(value);
+      const keys = Object.keys(fields);
+      const codes = keys.map((key) => (fields[key] as CompiledPart).code);
       return (ctx, rt) => {
         const out: Record<string, unknown> = {};
-        for (const [key, part] of fields) {
-          const result = part.code(ctx, rt);
+        for (let index = 0; index < keys.length; index += 1) {
+          const result = (codes[index] as Code)(ctx, rt);
           if (!result.ok) {
             if (omit !== undefined && omit(result.error)) continue;
             return result;
           }
-          setOwn(out, key, result.value);
+          setOwn(out, keys[index] as string, result.value);
         }
         return ok(out);
       };

package/src/index.ts

@@ -96,6 +96,7 @@ export {
 export { type Classification, type Shape, classify, tag } from "./classify.ts";
 export { type PartSlot, type Split, pathMatches, splitParts } from "./parts.ts";
 export {
+  type AllOptions,
   type Code,
   type CompileInput,
   type CompiledEvaluator,

package/src/parts.ts

@@ -42,10 +42,14 @@ class Bad {
   ) {}
 }
 
+/** This function sets an own data property. Only the key `__proto__` needs `defineProperty`. */
 function setOwn(target: Record<string, unknown>, key: string, value: unknown): void {
-  Object.defineProperty(target, key, { value, enumerable: true, writable: true, configurable: true });
+  if (key === "__proto__") Object.defineProperty(target, key, { value, enumerable: true, writable: true, configurable: true });
+  else target[key] = value;
 }
 
+const NO_SLOTS: readonly PartSlot[] = Object.freeze([]);
+
 function hasSlots(template: Template): boolean {
   return template.t !== "data";
 }
@@ -59,6 +63,8 @@ function hasSlots(template: Template): boolean {
  * @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 {
+  // A value without parts is data: the split needs no template.
+  if (shape === undefined || shape.shape === "none") return { ok: true, parts: NO_SLOTS, data: value, fill: () => value };
   const parts: PartSlot[] = [];
   const slot = (item: Json, path: readonly Key[], of: string | undefined): Template => {
     parts.push({ path, key: path.join("."), item, ...(of === undefined ? {} : { of }) });

package/src/static.ts

@@ -111,6 +111,15 @@ function scopesOf(rules: readonly ScopeRule[] | undefined, value: unknown, slots
   return { sees, later };
 }
 
+/** The names of a walk without names. A walk does not change a set at any time: it makes a new set to add names. */
+const NO_NAMES: ReadonlySet<string> = new Set();
+
+/** This function gives the options of a walk without the names of the host. */
+function withoutNames(options: WalkOptions): WalkOptions {
+  const { names: _host, ...rest } = options;
+  return rest;
+}
+
 /**
  * This function visits each document of a document: the root and each part at each depth, by the contracts of the
  * kinds. A part of a kind that the world does not have is not visited. The walk uses no stack of the host for the
@@ -131,9 +140,8 @@ export function walk(world: World, doc: unknown, visit: (visit: DocVisit) => voi
     readonly names: ReadonlySet<string>;
     readonly later: ReadonlySet<string>;
   }
-  const stack: Item[] = [
-    { value: doc, place: [], at: [], declared: options.declaredType, depth: 0, names: new Set(options.names ?? []), later: new Set() },
-  ];
+  const names: ReadonlySet<string> = options.names === undefined || options.names.length === 0 ? NO_NAMES : new Set(options.names);
+  const stack: Item[] = [{ value: doc, place: [], at: [], declared: options.declaredType, depth: 0, names, later: NO_NAMES }];
   while (stack.length > 0) {
     const item = stack.pop() as Item;
     const envelope = isEnvelope(item.value) ? (item.value as Envelope) : undefined;
@@ -144,16 +152,21 @@ export function walk(world: World, doc: unknown, visit: (visit: DocVisit) => voi
     const doc: Envelope = envelope ?? { type: item.declared ?? "?", value: item.value as Json };
     const found = lookupKind(world, doc.type);
     const kind = found.ok ? found.kind : undefined;
-    const answer = visit({
-      place: item.place,
-      at: item.at,
-      doc,
-      declared: envelope === undefined,
-      ...(kind === undefined ? {} : { kind, typePath: found.ok ? found.path : [] }),
-      depth: item.depth,
-      names: item.names,
-      later: item.later,
-    });
+    const seen: DocVisit =
+      kind === undefined
+        ? { place: item.place, at: item.at, doc, declared: envelope === undefined, depth: item.depth, names: item.names, later: item.later }
+        : {
+            place: item.place,
+            at: item.at,
+            doc,
+            declared: envelope === undefined,
+            kind,
+            typePath: found.ok ? found.path : [],
+            depth: item.depth,
+            names: item.names,
+            later: item.later,
+          };
+    const answer = visit(seen);
     if (answer === "skip" || kind === undefined) continue;
     const split = splitParts(kind.parts, doc.value);
     if (!split.ok) {
@@ -206,7 +219,7 @@ export interface RefUse {
 export function refsOf(world: World, doc: unknown, options: WalkOptions = {}): readonly RefUse[] {
   const out: RefUse[] = [];
   // The walk gets no names of the host: a name that the host binds is a dependency, thus its reference is free.
-  const { names: _host, ...rest } = options;
+  const rest: WalkOptions = options.names === undefined ? options : withoutNames(options);
   walk(
     world,
     doc,

package/src/world.ts

@@ -90,10 +90,14 @@ export type Alias = { readonly type: "ref"; readonly value: readonly Json[] };
 /** One entry of the world: a kind, a namespace, or an alias. */
 export type WorldEntry = Kind | Namespace | Alias;
 
-/** A world holds the kinds and the defaults that answer the questions. */
+/**
+ * A world holds the kinds and the defaults that answer the questions. `fallback` is the kind of each first key that
+ * the world does not have. A world with a fallback is open: each path that starts with an unknown key names a kind.
+ */
 export interface World {
   readonly kinds: Readonly<Record<string, WorldEntry>>;
   readonly defaults: Readonly<Record<string, string>>;
+  readonly fallback?: Kind;
 }
 
 /** The result of a lookup of a type in the world. */
@@ -139,7 +143,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. In a
- * namespace with a fallback, a key that the namespace does not have gets the fallback kind.
+ * namespace with a fallback, a key that the namespace does not have gets the fallback kind. In an open world, a first
+ * key that the world does not have gets the fallback kind of the world.
  *
  * @param world - The world.
  * @param type - The reference to the type.
@@ -152,7 +157,7 @@ export function lookupKind(world: World, type: TypeRef): Lookup {
   let aliases = 0;
   for (;;) {
     let entries = world.kinds;
-    let fallback: Kind | undefined;
+    let fallback: Kind | undefined = world.fallback;
     let entry: WorldEntry | undefined;
     let followed = false;
     for (let index = 0; index < path.length; index += 1) {