@mark1russell7/coeval 0.2.0 → 0.2.2

package/package.json

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

@@ -112,6 +112,8 @@ export type Walker = (input: WalkInput) => WalkResult;
  * - `plain`: `true` when the values are data. Then a step does not ask the kind of an envelope, and a reference
  *   that a step reaches stays a value (no collapse).
  * - `roots`: the roots that a path can start at. The default is each root.
+ * - `adopt`: the thing of each value that a path reaches. A host gives its own values a host thing with this
+ *   function, for example a value whose fields read through signals. A host thing is not followed as a reference.
  */
 export interface Navigator {
   readonly world: World;
@@ -119,6 +121,7 @@ export interface Navigator {
   readonly walkers?: Readonly<Record<string, Walker>>;
   readonly plain?: boolean;
   readonly roots?: readonly Root[];
+  readonly adopt?: (value: unknown) => Thing;
 }
 
 /** The way that one hop of a path was answered. */
@@ -256,21 +259,37 @@ function mayBeRef(thing: unknown): boolean {
   return typeof thing === "object" && thing !== null && (thing as { readonly type?: unknown }).type === "ref";
 }
 
+/** This function tells if each step of a path from an index is a key. */
+function keysFrom(path: readonly unknown[], start: number): boolean {
+  for (let index = start; index < path.length; index += 1) if (!isKey(path[index])) return false;
+  return true;
+}
+
 /**
- * This function resolves the common path without a record of hops: a root, then keys, through plain values. It
- * gives `undefined` when the path needs the full algorithm. Examples are a host thing, an envelope, a reference to
- * follow, a step document and a failure (for its exact reason).
+ * This function resolves the common path without a record of hops: a root, then keys. Plain values answer the
+ * keys, or a host thing answers all of them in one call. It gives `undefined` when the path needs the full
+ * algorithm. Examples are a host thing without `resolve`, an envelope, a reference to follow, a step document and a
+ * failure of a step (for its exact reason).
  */
 function resolveQuick(nav: Navigator, ctx: Context, path: readonly unknown[]): Resolution | undefined {
   const root = path[0];
-  if (root !== "names" && root !== "self" && root !== "event") return undefined;
+  if (root !== "names" && root !== "self" && root !== "event" && root !== "world") return undefined;
   if (nav.roots !== undefined && !(nav.roots as readonly string[]).includes(root)) return undefined;
+  if (nav.adopt !== undefined) return undefined;
   let here: unknown = ctx[root];
   const plain = nav.plain === true;
   for (let index = 1; index < path.length; index += 1) {
     if (typeof here !== "object" || here === null) return undefined;
     if (!plain && mayBeRef(here)) return undefined;
-    if ((here as Partial<HostThing>)[THING] === true) return undefined;
+    if ((here as Partial<HostThing>)[THING] === true) {
+      const thing = here as HostThing;
+      if (thing.resolve === undefined || !keysFrom(path, index)) return undefined;
+      const keys = path.slice(index) as readonly Key[];
+      const reached = thing.resolve(keys);
+      if (reached === undefined) return { ok: false, code: "#N/A", reason: `The path ${keys.join(".")} reaches nothing.`, hops: NO_HOPS };
+      if (!plain && mayBeRef(reached.thing)) return undefined;
+      return { ok: true, thing: reached.thing, hops: NO_HOPS };
+    }
     const step = path[index];
     if (Array.isArray(here)) {
       if (typeof step !== "number" || !Number.isInteger(step) || step < 0 || step >= here.length) return undefined;
@@ -316,6 +335,7 @@ export function resolve(nav: Navigator, ctx: Context, path: readonly unknown[],
   const done = hops ?? NO_HOPS;
   const failed = (code: ResolveCode, reason: string): Resolution => ({ ok: false, code, reason, hops: done });
   let collapses = 0;
+  const adopt = nav.adopt ?? ((value: unknown): Thing => value);
 
   const collapse = (thing: Thing): Resolution => {
     let here = thing;
@@ -325,7 +345,7 @@ export function resolve(nav: Navigator, ctx: Context, path: readonly unknown[],
       if (collapses > MAX_COLLAPSE) return failed("#CYCLE!", "The references form a cycle.");
       const inner = walk(here.value);
       if (!inner.ok) return inner;
-      here = inner.thing;
+      here = adopt(inner.thing);
       hops?.push({ step: "collapse", thing: here, by: "collapse" });
     }
     return { ok: true, thing: here, hops: done };
@@ -339,7 +359,7 @@ export function resolve(nav: Navigator, ctx: Context, path: readonly unknown[],
     if (nav.roots !== undefined && !(nav.roots as readonly string[]).includes(root)) {
       return failed("#REF!", `The root ${root} is not open here. The open roots are ${nav.roots.join(", ")}.`);
     }
-    let here: Thing = ctx[root as Root];
+    let here: Thing = adopt(ctx[root as Root]);
     hops?.push({ step: root, thing: here, by: "root" });
     const first = collapse(here);
     if (!first.ok) return first;
@@ -350,8 +370,9 @@ export function resolve(nav: Navigator, ctx: Context, path: readonly unknown[],
         const keys = steps.slice(index) as readonly Key[];
         const reached = here.resolve(keys);
         if (reached === undefined) return failed("#N/A", `The path ${keys.join(".")} reaches nothing.`);
-        hops?.push({ step: keys as readonly Json[], thing: reached.thing, by: "own" });
-        return collapse(reached.thing);
+        const thing = adopt(reached.thing);
+        hops?.push({ step: keys as readonly Json[], thing, by: "own" });
+        return collapse(thing);
       }
       if (isKey(step)) {
         const reached = derefStep(nav, here, step);
@@ -359,8 +380,8 @@ export function resolve(nav: Navigator, ctx: Context, path: readonly unknown[],
           if (root === "names" && index === 1) return failed("#NAME?", `The context has no name ${String(step)}.`);
           return failed("#N/A", `The step ${String(step)} reaches nothing.`);
         }
-        hops?.push({ step, thing: reached.thing, by: reached.by });
-        here = reached.thing;
+        here = adopt(reached.thing);
+        hops?.push({ step, thing: here, by: reached.by });
       } else {
         const envelope = isEnvelope(step) ? step : undefined;
         const found = envelope === undefined ? undefined : lookupKind(nav.world, envelope.type);
@@ -373,11 +394,14 @@ export function resolve(nav: Navigator, ctx: Context, path: readonly unknown[],
           data: envelope.value,
           here,
           context: ctx,
-          deref: (thing, key) => derefStep(nav, thing, key)?.thing,
+          deref: (thing, key) => {
+            const reached = derefStep(nav, thing, key);
+            return reached === undefined ? undefined : adopt(reached.thing);
+          },
         });
         if (!result.ok) return failed("#N/A", result.reason);
-        hops?.push({ step: envelope as Json, thing: result.thing, by: "step" });
-        here = result.thing;
+        here = adopt(result.thing);
+        hops?.push({ step: envelope as Json, thing: here, by: "step" });
       }
       const next = collapse(here);
       if (!next.ok) return next;

package/src/evaluate.ts

@@ -445,9 +445,14 @@ export interface EvalOptions {
   readonly effects?: Effect[];
 }
 
+/** The options of a resolution without a record of hops, and with one. One object of each serves each call. */
+const WITHOUT_HOPS: ResolveOptions = Object.freeze({ hops: false });
+const WITH_HOPS: ResolveOptions = Object.freeze({ hops: true });
+
 /** This class holds the state of one evaluation or run: the machine, the effects, the clock and the trace. */
 class Session implements Runtime {
-  readonly effects: Effect[];
+  /** The list of the effects. It is made at the first effect, thus an evaluation without effects makes no list. */
+  private list: Effect[] | undefined;
   tick = 0;
   nextId = 0;
   current: Building | undefined;
@@ -461,13 +466,19 @@ class Session implements Runtime {
     readonly signal: StopSignal | undefined,
     effects: Effect[] | undefined,
   ) {
-    this.effects = effects ?? [];
+    this.list = effects;
     this.holder = traced ? holderNode() : undefined;
     this.current = this.holder;
   }
 
+  /** The effects of the evaluation, in their order. */
+  get effects(): Effect[] {
+    return (this.list ??= []);
+  }
+
   resolve(ctx: Context, path: readonly unknown[], options?: ResolveOptions): Resolution {
-    return resolve(this.machine, ctx, path, { hops: options?.hops ?? this.traced });
+    const hops = options?.hops ?? this.traced;
+    return resolve(this.machine, ctx, path, hops ? WITH_HOPS : WITHOUT_HOPS);
   }
 
   private permitted(ctx: Context, keys: readonly Key[]): boolean {
@@ -479,8 +490,9 @@ class Session implements Runtime {
     const text = keys.join(".");
     if (!this.permitted(ctx, keys)) return fail("#CAP!", `The context has no capability for the effect ${text}.`, { place });
     const node = this.current;
-    const effect: Effect = { index: this.effects.length, kind: text, path: keys, payload, node: node?.id ?? -1, at: this.tick, place, context: ctx };
-    this.effects.push(effect);
+    const list = this.effects;
+    const effect: Effect = { index: list.length, kind: text, path: keys, payload, node: node?.id ?? -1, at: this.tick, place, context: ctx };
+    list.push(effect);
     if (node !== undefined) node.effects.push(effect.index);
     return effect;
   }