@mark1russell7/coeval 0.2.2 → 0.3.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package",
   "name": "@mark1russell7/coeval",
-  "version": "0.2.2",
+  "version": "0.3.1",
   "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/evaluate.ts

@@ -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;
   }
 
@@ -821,6 +874,7 @@ 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}`;
 
@@ -877,6 +931,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 +959,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,
     });
   };
 }

package/src/formula.ts

@@ -24,7 +24,8 @@ export type ExtFn = (data: Json) => Result;
  * - `ext`: the extensions of the namespace `ext`, by their name. The kit has `ext.undefined` and `ext.number`.
  * - `truthy`: the truth of a value for `if`, `and` and `or`. `undefined` is an error `#VALUE!`. The default
  *   accepts only `true` and `false`.
- * - `otherwise`: the value of an `if` without `else`. The default is `null`.
+ * - `otherwise`: the value of an `if` without `else`. The default is `null`. A profile with this key gives its value,
+ *   also `undefined`.
  * - `logic`: what `and` and `or` give: a truth value (the default), or the value that decided.
  * - `omit`: the errors that leave a field out of a `record`, as an absent value.
  * - `missing`: the values that a reference cannot give. Such a value gives `#N/A`.
@@ -150,7 +151,7 @@ export function formulaKinds(): Readonly<Record<string, WorldEntry>> {
  */
 export function formulaEvaluators(profile: FormulaProfile = {}): Readonly<Record<string, Evaluator>> {
   const truthy = profile.truthy ?? strictTruthy;
-  const otherwise = ok(profile.otherwise ?? null);
+  const otherwise = ok(Object.hasOwn(profile, "otherwise") ? profile.otherwise : null);
   const logicValue = profile.logic === "value";
   const omit = profile.omit;
   const missing = profile.missing;

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/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) {