@mark1russell7/coeval 0.7.0 → 0.7.1

package/package.json

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

@@ -0,0 +1,185 @@
+import { type Json, isEnvelope, isRecord } from "./doc.ts";
+import { type Result, describe, fail, ok } from "./errors.ts";
+import { type Machine, makeContext, prepare } from "./evaluate.ts";
+import { type Domain, type DomainCodec, domainOf, member } from "./types.ts";
+
+/*
+ * The codec of the values that JSON cannot write (K140, D40). A document holds such a value as a standard extension:
+ * `ext.number` for `NaN`, an infinity and `-0`, `ext.undefined` for `undefined`, and `ext.domain` for a member of a
+ * domain with a codec. Thus the same value has the same document in each language (D12).
+ */
+
+/** The domains of a machine, by their names. */
+type Domains = Readonly<Record<string, Domain>> | undefined;
+
+/** This function gives the codec of a domain, or `undefined` when the domain has no codec. */
+function codecOf(domain: Domain): DomainCodec | undefined {
+  const codec: unknown = domain.codec;
+  if (typeof codec !== "object" || codec === null) return undefined;
+  const { encode, decode } = codec as Partial<DomainCodec>;
+  return typeof encode === "function" && typeof decode === "function" ? (codec as DomainCodec) : undefined;
+}
+
+/**
+ * This function reads the value of an extension `ext.domain` (EXT.DOMAIN). The value is a record with only the text
+ * `domain` and the JSON `data`. The codec of the named domain reads the data, and the result must be a member of the
+ * domain.
+ *
+ * @param data - The value of the extension document.
+ * @param domains - The domains of the machine.
+ * @returns The member, `#NAME?` for a domain without a codec, or `#VALUE!` for data that the codec cannot read.
+ */
+export function decodeDomain(data: Json, domains: Domains): Result {
+  if (!isRecord(data) || typeof data["domain"] !== "string" || !Object.hasOwn(data, "data") || Object.keys(data).length !== 2) {
+    return fail("#VALUE!", "The value of ext.domain is a record with only the text domain and the data.");
+  }
+  const name = data["domain"];
+  const domain = domainOf(name, domains);
+  if (domain === undefined) return fail("#NAME?", `The machine has no domain ${name}.`);
+  const codec = codecOf(domain);
+  if (codec === undefined) return fail("#NAME?", `The domain ${name} has no codec.`);
+  let value: unknown;
+  try {
+    value = codec.decode(data["data"] as Json);
+  } catch (error) {
+    return fail("#VALUE!", `The codec of the domain ${name} cannot read the data: ${describe(error)}`, { cause: error });
+  }
+  if (!member(value, name, domains)) return fail("#VALUE!", `The codec of the domain ${name} gives a value that is not a member of the domain.`);
+  return ok(value);
+}
+
+/**
+ * This function gives the static type of an extension `ext.domain`: the name of its domain when that domain has a
+ * codec. A run then gives a member of the domain or an error, because `decodeDomain` tests the membership.
+ *
+ * @param data - The value of the extension document.
+ * @param domains - The domains of the machine.
+ * @returns The name of the domain, or `unknown`.
+ */
+export function domainTypeOf(data: unknown, domains: Domains): string {
+  if (!isRecord(data) || typeof data["domain"] !== "string") return "unknown";
+  const domain = domainOf(data["domain"], domains);
+  return domain !== undefined && codecOf(domain) !== undefined ? data["domain"] : "unknown";
+}
+
+/** This function sets an own data property. Only the key `__proto__` needs `defineProperty`. */
+function setOwn(target: Record<string, Json>, key: string, value: Json): void {
+  if (key === "__proto__") Object.defineProperty(target, key, { value, enumerable: true, writable: true, configurable: true });
+  else target[key] = value;
+}
+
+/** The state of one call of `encodeValue`. */
+interface Encoder {
+  readonly domains: Domains;
+  /** The domains with a codec, in the order of their names. */
+  readonly codecs: readonly (readonly [string, DomainCodec])[];
+  /** The answer of `isJson` for each container that it examined. */
+  readonly json: WeakMap<object, boolean>;
+  /** The containers on the way from the root to the value. A container on the way again is a cycle. */
+  readonly open: Set<object>;
+}
+
+/**
+ * This function tells if JSON writes a value exactly. Such a value is a finite number other than `-0`, a text, a truth
+ * value, `null`, or a container of such values.
+ */
+function isJson(value: unknown, encoder: Encoder): boolean {
+  if (value === null || typeof value === "string" || typeof value === "boolean") return true;
+  if (typeof value === "number") return Number.isFinite(value) && !Object.is(value, -0);
+  const list = Array.isArray(value);
+  if (!list && !isRecord(value)) return false;
+  const container = value as object;
+  const known = encoder.json.get(container);
+  if (known !== undefined) return known;
+  // A cycle is not JSON. The mark stays false until each item is JSON.
+  encoder.json.set(container, false);
+  let all = true;
+  if (list) {
+    const items = value as readonly unknown[];
+    for (let index = 0; index < items.length && all; index += 1) all = isJson(items[index], encoder);
+  } else {
+    const record = value as Readonly<Record<string, unknown>>;
+    for (const key of Object.keys(record)) {
+      if (!isJson(record[key], encoder)) {
+        all = false;
+        break;
+      }
+    }
+  }
+  encoder.json.set(container, all);
+  return all;
+}
+
+/** This function gives the text of a number that JSON cannot write, for `ext.number`. */
+function numberText(value: number): string {
+  if (Number.isNaN(value)) return "NaN";
+  if (value === Number.POSITIVE_INFINITY) return "Infinity";
+  if (value === Number.NEGATIVE_INFINITY) return "-Infinity";
+  return "-0";
+}
+
+/** This function gives the term document of a value in one call of `encodeValue`. */
+function encodeTerm(value: unknown, encoder: Encoder): Json {
+  if (isJson(value, encoder)) return isEnvelope(value) ? { type: "lit", value: value as Json } : (value as Json);
+  if (value === undefined) return { type: ["ext", "undefined"], value: null };
+  if (typeof value === "number") return { type: ["ext", "number"], value: numberText(value) };
+  for (const [name, codec] of encoder.codecs) {
+    if (member(value, name, encoder.domains)) return { type: ["ext", "domain"], value: { domain: name, data: codec.encode(value) } };
+  }
+  if (!Array.isArray(value) && !isRecord(value)) {
+    throw new TypeError(`encodeValue cannot write the value ${describe(value)}: no domain of the machine with a codec holds it.`);
+  }
+  if (encoder.open.has(value)) throw new TypeError("encodeValue cannot write a value with a cycle.");
+  encoder.open.add(value);
+  let out: Json;
+  if (Array.isArray(value)) {
+    // `Array.from` visits each hole of a sparse list as `undefined`.
+    out = { type: "list", value: Array.from(value as readonly unknown[], (item) => encodeTerm(item, encoder)) };
+  } else {
+    const fields: Record<string, Json> = {};
+    const record = value as Readonly<Record<string, unknown>>;
+    for (const key of Object.keys(record)) setOwn(fields, key, encodeTerm(record[key], encoder));
+    out = { type: "record", value: fields };
+  }
+  encoder.open.delete(value);
+  return out;
+}
+
+/**
+ * This function writes a host value as a term document of the formula kit (EXT.ENCODE, D40). Thus the same value has
+ * the same document in each language (D12).
+ *
+ * - A value that JSON writes exactly stays as it is. A literal with the shape of an envelope goes into `lit`.
+ * - `NaN`, an infinity and `-0` become `ext.number`, and `undefined` becomes `ext.undefined`.
+ * - A member of a domain with a codec becomes `ext.domain`. The domains go in the order of their names.
+ * - A list or a plain record with such a value becomes the construct `list` or `record`.
+ *
+ * @param machine - The machine, or only its domains.
+ * @param value - The host value.
+ * @returns The document. `decodeValue` gives the value again (EXT.ROUNDTRIP).
+ * @throws {TypeError} The value has a cycle, or it is not JSON and no domain with a codec holds it.
+ */
+export function encodeValue(machine: Pick<Machine, "domains">, value: unknown): Json {
+  const domains = machine.domains;
+  const codecs: (readonly [string, DomainCodec])[] = [];
+  if (domains !== undefined) {
+    for (const name of Object.keys(domains).sort()) {
+      const domain = domainOf(name, domains);
+      const codec = domain === undefined ? undefined : codecOf(domain);
+      if (codec !== undefined) codecs.push([name, codec]);
+    }
+  }
+  return encodeTerm(value, { domains, codecs, json: new WeakMap(), open: new Set() });
+}
+
+/**
+ * This function reads a document of `encodeValue` again: it evaluates the document as a term, in an empty context.
+ * A bare root value is a literal.
+ *
+ * @param machine - A machine of the formula kit, with the domains of the document.
+ * @param doc - The document.
+ * @returns The value, or the error of the evaluation.
+ */
+export function decodeValue(machine: Machine, doc: unknown): Result {
+  return prepare(machine, doc, { declaredType: "lit" }).evaluate(makeContext());
+}

package/src/conform.ts

@@ -692,7 +692,7 @@ function finish(shot: Shot, start: () => Result, who: string): Result {
  */
 function instanceOf(env: Env, under: Under, doc: Envelope, split: SplitOk, sample: Sample): Instance {
   const fill = (items: readonly unknown[]): unknown => (split.parts.length === 0 ? doc.value : split.fill(items));
-  const base = { kind: sample.type, typePath: sample.typePath, doc, data: split.data, place: PLACE, fill };
+  const base = { kind: sample.type, typePath: sample.typePath, doc, data: split.data, place: PLACE, machine: env.machine, fill };
   const who = `the ${env.runner ? "runner" : "evaluator"} ${env.name}`;
   if (under.form === "eval" || under.form === "run") {
     if (under.form === "eval") {

package/src/evaluate.ts

@@ -523,6 +523,8 @@ export interface EvalInput {
   readonly context: Context;
   /** The keys from the root document to this document. */
   readonly place: readonly Key[];
+  /** The machine of the evaluation, for example for its domains (D40). The kernel sets it. */
+  readonly machine?: Machine;
   /** `true` when the position of the document declares an address. */
   readonly address?: boolean;
   /**
@@ -580,6 +582,8 @@ export interface RunInput {
   readonly parts: readonly RunPart[];
   readonly context: Context;
   readonly place: readonly Key[];
+  /** The machine of the evaluation, for example for its domains (D40). The kernel sets it. */
+  readonly machine?: Machine;
   resolve(path: readonly unknown[], options?: ResolveOptions): Resolution;
   /**
    * This function causes an effect. In a run, the host does the effect, and the steps wait when the host waits. In
@@ -1534,7 +1538,7 @@ function fillOf(split: Extract<Split, { readonly ok: true }>, doc: Envelope): <P
 
 
 function interpret(fn: EvalFn, input: CompileInput, fill: <P>(handles: readonly P[]) => unknown): Code {
-  const { kind, typePath, doc, data, place } = input;
+  const { kind, typePath, doc, data, place, machine } = input;
   const address = input.address === true ? { address: true } : {};
   // The code keeps the fill and not the whole input, thus it does not keep the compiled value of the document (PLAN.LEAN).
   const refill = input.fill;
@@ -1556,6 +1560,7 @@ function interpret(fn: EvalFn, input: CompileInput, fill: <P>(handles: readonly
       parts,
       context: ctx,
       place,
+      machine,
       ...address,
       resolve: (path, options) => rt.resolve(ctx, path, options),
       effect: (effectKind, payload) => rt.effect(ctx, effectKind, payload, place),
@@ -1565,7 +1570,7 @@ function interpret(fn: EvalFn, input: CompileInput, fill: <P>(handles: readonly
 }
 
 function interpretRun(fn: RunFn, input: CompileInput, fill: <P>(handles: readonly P[]) => unknown): RunCode {
-  const { kind, typePath, doc, data, place } = input;
+  const { kind, typePath, doc, data, place, machine } = input;
   const refill = input.fill;
   const compiled = input.parts;
   const hasParts = compiled.length > 0;
@@ -1585,6 +1590,7 @@ function interpretRun(fn: RunFn, input: CompileInput, fill: <P>(handles: readonl
       parts,
       context: ctx,
       place,
+      machine,
       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),

package/src/formula.ts

@@ -4,8 +4,9 @@ import { type CompiledPath, type Context, type Resolution, compilePath, valueOfT
 import { type EvalError, type Failed, type Result, Failure, fail, ok, thrown } from "./errors.ts";
 import { type Code, type CompileInput, type CompiledEvaluator, type CompiledPart, type Evaluator, type Machine, type Runtime, resolveCompiled } from "./evaluate.ts";
 import { type MachinePart, mergeMachines } from "./merge.ts";
-import { type ValueType, HEADER_KEYS, STD_DOMAINS, callable, fieldOf, fits, fnOf, holdsEnvelope, isPrecise, isUnknown, itemOf, join, stepType, typeText } from "./types.ts";
+import { type Domain, type ValueType, HEADER_KEYS, STD_DOMAINS, callable, fieldOf, fits, fnOf, holdsEnvelope, isPrecise, isUnknown, itemOf, join, stepType, typeText } from "./types.ts";
 import type { TypeInput, TypeRule } from "./typing.ts";
+import { decodeDomain, domainTypeOf } from "./codec.ts";
 
 /** An operation of a formula language: a function of the values of its arguments. */
 export type OpFn = (...args: never[]) => unknown;
@@ -16,15 +17,19 @@ export type OpFn = (...args: never[]) => unknown;
  */
 export type LazyOp = (args: readonly (() => Result)[]) => Result;
 
-/** The code of an extension: it gives the value of the data of an extension document, in the context of the document. */
-export type ExtFn = (data: Json, context: Context) => Result;
+/**
+ * The code of an extension: it gives the value of the data of an extension document, in the context of the document.
+ * It also gets the domains of the machine, for the codecs of `ext.domain` (D40).
+ */
+export type ExtFn = (data: Json, context: Context, domains?: Readonly<Record<string, Domain>>) => Result;
 
 /**
  * The rules of one formula language: its operations, and the rules that differ between languages.
  *
  * - `ops`: the operations of the namespace `ops`, by their name (the keys after `ops`, with dots between them).
  * - `lazy`: the operations that evaluate their arguments themselves.
- * - `ext`: the extensions of the namespace `ext`, by their name. The kit has `ext.undefined` and `ext.number`.
+ * - `ext`: the extensions of the namespace `ext`, by their name. The kit has `ext.undefined`, `ext.number` and
+ *   `ext.domain`.
  * - `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`. A profile with this key gives its value,
@@ -97,7 +102,10 @@ export function isClosure(value: unknown): value is Closure {
   return typeof value === "function" && (value as Partial<Closure>)[CLOSURE] !== undefined;
 }
 
-/** The standard extensions: the values that JSON cannot write. */
+/**
+ * The standard extensions: the values that JSON cannot write. `ext.domain` reads a member of a domain through the
+ * codec of the domain (EXT.DOMAIN, D40).
+ */
 export const STD_EXT: Readonly<Record<string, ExtFn>> = {
   undefined: () => ok(undefined),
   number: (data) => {
@@ -107,6 +115,7 @@ export const STD_EXT: Readonly<Record<string, ExtFn>> = {
     if (data === "-0") return ok(-0);
     return fail("#VALUE!", "The value of ext.number is NaN, Infinity, -Infinity or -0.");
   },
+  domain: (data, _context, domains) => decodeDomain(data, domains),
 };
 
 /** The truth of a value in the rules of JavaScript: `0`, `""`, `null`, `undefined` and `NaN` are false. */
@@ -477,7 +486,9 @@ function formulaTypes(profile: FormulaProfile): Readonly<Record<string, TypeRule
       synth: (input) => {
         const name = nameOf(input);
         const own = profile.ext !== undefined && Object.hasOwn(profile.ext, name);
-        return name === "number" && !own ? "number" : "unknown";
+        if (own) return "unknown";
+        if (name === "number") return "number";
+        return name === "domain" ? domainTypeOf(input.doc.value, input.machine.domains) : "unknown";
       },
     },
   };
@@ -811,7 +822,7 @@ function formulaCode(profile: FormulaProfile): Readonly<Record<string, CompiledE
       };
     }),
 
-    "formula.ext": compiled(({ typePath, doc }) => {
+    "formula.ext": compiled(({ typePath, doc, machine }) => {
       const name = typePath.slice(1).join(".");
       const own = profile.ext !== undefined && Object.hasOwn(profile.ext, name) ? profile.ext[name] : undefined;
       const handler = own ?? (Object.hasOwn(STD_EXT, name) ? STD_EXT[name] : undefined);
@@ -821,7 +832,7 @@ function formulaCode(profile: FormulaProfile): Readonly<Record<string, CompiledE
       }
       return (ctx) => {
         try {
-          return handler(doc.value, ctx);
+          return handler(doc.value, ctx, machine.domains);
         } catch (error) {
           return thrown(error, `the extension ${name}`);
         }

package/src/index.ts

@@ -211,6 +211,24 @@ export {
   isClosure,
   jsTruthy,
 } from "./formula.ts";
+export { decodeDomain, decodeValue, encodeValue } from "./codec.ts";
+export {
+  type ParseResult,
+  type SyntaxAssoc,
+  type SyntaxCalls,
+  type SyntaxFixity,
+  type SyntaxForm,
+  type SyntaxIssue,
+  type SyntaxLiterals,
+  type SyntaxOperator,
+  type SyntaxProfile,
+  type SyntaxRefPattern,
+  type SyntaxRefs,
+  STD_SYNTAX,
+  parse,
+  print,
+  syntaxFormat,
+} from "./syntax.ts";
 export { type Definitions, type ReferenceOptions, STD_DEFINITIONS, formulaDefinitions, reference } from "./reference.ts";
 export { type AgreeOptions, type Agreement, type Tier, type TierInput, type TierResult, agree, sameValue } from "./agree.ts";
 export { type ConformOptions, type ConformProbe, type Finding, type Obligation, conforms } from "./conform.ts";
@@ -230,6 +248,6 @@ export {
 export { type GraphCycle, type GraphEdge, type GraphNode, type GraphOptions, type NodeGraph, components, cycles, heights, necessary, nodeLayers } from "./graph.ts";
 export { type Recorder, type ReplayEntry, type ReplayLog, type ReplayOptions, type ReplaySettle, recorder, replayer } from "./replay.ts";
 export { type GenerateOptions, type Random, generate, random, typesOf } from "./generate.ts";
-export { type Domain, type TypeIssue, type ValueType, STD_DOMAINS, fits, join, member, typeIssues, typeText } from "./types.ts";
+export { type Domain, type DomainCodec, type TypeIssue, type ValueType, STD_DOMAINS, fits, join, member, typeIssues, typeText } from "./types.ts";
 export { type PartType, type RootTypes, type TypeInput, type TypeProblem, type TypeRule, type Typed, CAPS_TYPE } from "./typing.ts";
 export { type SampleOptions, type TypeReading, typeFromSamples, typeFromSchema } from "./providers.ts";

package/src/reference.ts

@@ -307,6 +307,7 @@ function evalInput(env: Env, seen: Seen, at: At): EvalInput {
     parts,
     context: at.ctx,
     place: at.place,
+    machine: env.machine,
     ...(at.address ? { address: true } : {}),
     resolve: (path, options) => resolveFully(env.machine, at.ctx, path, options),
     effect: (kind, payload) => cause(env, at.ctx, kind, payload, at.place),
@@ -335,6 +336,7 @@ function runInput(env: Env, seen: Seen, at: At): RunInput {
     parts,
     context: at.ctx,
     place: at.place,
+    machine: env.machine,
     resolve: (path, options) => resolveFully(env.machine, at.ctx, path, options),
     effect: function* (kind, payload) {
       return cause(env, at.ctx, kind, payload, at.place);
@@ -748,12 +750,12 @@ export function formulaDefinitions(profile: FormulaProfile = {}): Definitions {
     }
   };
 
-  const ext: EvalFn = ({ typePath, doc, context }) => {
+  const ext: EvalFn = ({ typePath, doc, context, machine }) => {
     const name = typePath.slice(1).join(".");
     const handler = own(profile.ext, name) ?? own(STD_EXT, name);
     if (handler === undefined) return fail("#NAME?", `The language has no extension ${name}.`);
     try {
-      return handler(doc.value, context);
+      return handler(doc.value, context, machine?.domains);
     } catch (error) {
       return thrown(error, `the extension ${name}`);
     }