@formaui-net/nexo 0.0.0 → 1.0.0-preview.1

package/src/language/ValueCapture.mjs

@@ -0,0 +1,315 @@
+/**
+ * ValueCapture — a value from outside a script captured as the type declared for it, as a value a host supplies is: a value its type admits taken, a list from an array or a set, a structure as its data shape alone,
+ * and a reference of another type null where a nullable reference type is declared, each list, object, structure, dictionary and pair it makes frozen as it is made
+ */
+
+import { ArrayUtils } from '../common/ArrayUtils.mjs';
+import { ObjectUtils } from '../common/ObjectUtils.mjs';
+import { Dictionary } from './Dictionary.mjs';
+import { Limits } from './Limits.mjs';
+import { Pair } from './Pair.mjs';
+import { StructureTypes } from './StructureTypes.mjs';
+import { NexoModule } from './vocabulary/NexoModule.mjs';
+
+export class ValueCapture {
+    #registry;
+
+    /** What capturing each named type takes, as `#namedCaptures` holds it for the registry. */
+    #captures;
+
+    /** @param {import('./vocabulary/NexoRegistry.mjs').NexoRegistry} registry The registry whose types the value is captured as, whose modules recognize a reference of another type. */
+    constructor(registry) {
+        this.#registry = registry;
+        this.#captures = ValueCapture.#namedCaptures.get(registry);
+
+        if (this.#captures === undefined) {
+            this.#captures = new Map();
+            ValueCapture.#namedCaptures.set(registry, this.#captures);
+        }
+    }
+
+    /**
+     * What capturing a named type takes, settled once for each type a registry declares, by the registry and then the type's identity: a scalar's check, a reference type, a structure's data shape, as a list of each
+     * property's name beside its type, with its type without null, which records each structure captured, or none, which fails every value. A registry's declarations never change once registered, so an entry is valid
+     * for the registry's life and released with it; recognizing a reference asks the registry anew each time, since a registration can change it. Settling it for each value measured a tenth of binding.
+     * @type {WeakMap<object, Map<string, { kind: 'scalar', check: (value: unknown) => boolean } | { kind: 'reference' } | { kind: 'structured', shape: [string, import('./Type.mjs').Type][], type: import('./Type.mjs').Type } | { kind: 'none' }>>}
+     */
+    static #namedCaptures = new WeakMap();
+
+    /** What capturing the named type takes, settled at its first capture. */
+    #getNamedCapture(type) {
+        let named = this.#captures.get(type.identity);
+
+        if (named === undefined) {
+            const declaration = this.#registry.getTypeDeclaration(type);
+
+            if (type.moduleName === null && NexoModule.scalarTypeNames.includes(type.name)) {
+                named = { kind: 'scalar', check: ValueCapture.#scalarChecks.get(type.name) };
+            } else if (declaration?.kind === 'reference') {
+                named = { kind: 'reference' };
+            } else if (declaration?.kind === 'structured') {
+                named = { kind: 'structured', shape: [...this.#registry.getDataShape(type)], type: type.toNonNullable() };
+            } else {
+                named = { kind: 'none' };
+            }
+
+            this.#captures.set(type.identity, named);
+        }
+
+        return named;
+    }
+
+    /**
+     * The value captured as its type at every level of it: a value its type admits taken, a structure as its declared fields alone and a list item by item, from an array or a set, its items in their traversal
+     * order and no uniqueness kept; nothing, or null, null where its type is nullable; and a
+     * reference of another type null where a nullable reference type is declared, so the value keeps only the reference its type names. Anything else is given to `fail`, which throws, with the part of the value
+     * by its path within it, the value itself by none, the part and the type it is declared; and data that reaches itself, a list or an object holding one of the lists or objects it lies within, is given to `fail`
+     * as well, with the reason `'cycle'`, since data never does, data nesting deeper than `Limits.dataNesting` with the reason `'depth'`, and a dictionary holding a key twice, once captured, with the reason
+     * `'duplicate'` at the later key, since a dictionary holds each key once.
+     * @param {unknown} value
+     * @param {import('./Type.mjs').Type} type
+     * @param {(path: string, part: unknown, type: import('./Type.mjs').Type, reason?: 'cycle' | 'depth' | 'duplicate') => never} fail
+     * @param {string} [asked] What asks for the capture, as a recognition's fault names it.
+     */
+    capture(value, type, fail, asked = 'capturing a supplied value') {
+        this.#asked = asked;
+        this.#enclosing = new Set();
+        this.#steps = [];
+
+        return this.#capture(value, type, fail);
+    }
+
+    /** The lists and objects the part being captured lies within, which it never holds, since data doesn't reach itself. */
+    #enclosing = new Set();
+
+    /**
+     * The steps from the value to the part being captured: a field's name, a list item's index, or a dictionary entry's key or value. The path they make is written only where a part fails, so a capture that succeeds
+     * writes none.
+     * @type {(string | number | { entry: number, part: 'key' | 'value' })[]}
+     */
+    #steps = [];
+
+    /** What the capture under way was asked by, which a module's recognition, faulting, names. */
+    #asked = 'capturing a supplied value';
+
+    /** The path of the part being captured within the value, as `fail` is given it: `rooms[2].name`, and a dictionary entry's part as `.entries[0].key`. */
+    #path() {
+        let path = '';
+
+        for (const step of this.#steps) {
+            path = typeof step === 'number' ? `${path}[${step}]` : typeof step === 'string' ? ValueCapture.#pathOf(path, step) : `${path}.entries[${step.entry}].${step.part}`;
+        }
+
+        return path;
+    }
+
+    /** A part of the value captured as its type, one step further along the path. */
+    #captureStep(value, type, step, fail) {
+        this.#steps.push(step);
+
+        const captured = this.#capture(value, type, fail);
+
+        this.#steps.pop();
+
+        return captured;
+    }
+
+    /** Enters a list or an object of data, whose parts are captured next, refusing one of those it lies within; `#leave` releases it once they are. */
+    #enter(value, type, fail) {
+        if (this.#enclosing.has(value)) {
+            fail(this.#path(), value, type, 'cycle');
+        }
+
+        if (this.#enclosing.size >= Limits.dataNesting) {
+            fail(this.#path(), value, type, 'depth');
+        }
+
+        this.#enclosing.add(value);
+    }
+
+    #leave(value) {
+        this.#enclosing.delete(value);
+    }
+
+    /** The fields of an object or a structure, each captured as its type and defined as an ordinary field, in the order of their types. */
+    #captureFields(value, fieldTypes, fail) {
+        const captured = {};
+
+        for (const [name, fieldType] of fieldTypes) {
+            ObjectUtils.defineDataProperty(captured, name, this.#captureStep(value[name], fieldType, name, fail));
+        }
+
+        return captured;
+    }
+
+    #capture(value, type, fail) {
+        if (value === undefined || value === null) {
+            if (!type.isNullable) {
+                fail(this.#path(), value, type);
+            }
+
+            return null;
+        }
+
+        // A list is supplied as an array or a set, a set's items in their traversal order, the list it gives holding no uniqueness.
+        if (type.isList) {
+            const items = value instanceof Set ? [...value] : value;
+
+            if (!Array.isArray(items) || ArrayUtils.findMissingIndex(items) !== -1) {
+                fail(this.#path(), value, type);
+            }
+
+            this.#enter(value, type, fail);
+
+            try {
+                const captured = new Array(items.length);
+
+                for (let index = 0; index < items.length; index++) {
+                    captured[index] = this.#captureStep(items[index], type.itemType, index, fail);
+                }
+
+                return Object.freeze(captured);
+            } finally {
+                this.#leave(value);
+            }
+        }
+
+        // A dictionary is supplied as a map or the language's, each key and value captured as its type declares, and a pair as the language's or an object of a key and a value alone.
+        if (type.isDictionary) {
+            const entries = value instanceof Map ? [...value] : value instanceof Dictionary ? value.entries.map(entry => [entry.key, entry.value]) : fail(this.#path(), value, type);
+            const [keyType, valueType] = type.typeArguments;
+
+            this.#enter(value, type, fail);
+
+            try {
+                const captured = entries.map(([key, entry], index) => [this.#captureStep(key, keyType, { entry: index, part: 'key' }, fail), this.#captureStep(entry, valueType, { entry: index, part: 'value' }, fail)]);
+                // Keys equal by key equality, which a set's keeps, -0 equal to 0 and a reference by its identity, are one key, and two of them are refused, as constructing a dictionary refuses them, never one kept.
+                const keys = new Set();
+
+                captured.forEach(([key], index) => {
+                    if (keys.has(key)) {
+                        this.#steps.push({ entry: index, part: 'key' });
+                        fail(this.#path(), key, keyType, 'duplicate');
+                    }
+
+                    keys.add(key);
+                });
+
+                return Object.freeze(new Dictionary(captured));
+            } finally {
+                this.#leave(value);
+            }
+        }
+
+        if (type.isPair) {
+            const isPair = value instanceof Pair || (ObjectUtils.isPlainObject(value) && Object.keys(value).length === 2 && Object.hasOwn(value, 'key') && Object.hasOwn(value, 'value'));
+
+            if (!isPair) {
+                fail(this.#path(), value, type);
+            }
+
+            const [keyType, valueType] = type.typeArguments;
+
+            this.#enter(value, type, fail);
+
+            try {
+                return Object.freeze(new Pair(this.#captureStep(value.key, keyType, 'key', fail), this.#captureStep(value.value, valueType, 'value', fail)));
+            } finally {
+                this.#leave(value);
+            }
+        }
+
+        switch (type.kind) {
+            // A value of Any is of any type, which the evaluation that reads it checks where a type is declared for it, as a member's answer of Any is.
+            case 'any':
+            case 'typeParameter':
+                return value;
+            case 'object':
+                if (!ObjectUtils.isNonArrayObject(value)) {
+                    fail(this.#path(), value, type);
+                }
+
+                this.#enter(value, type, fail);
+
+                try {
+                    return Object.freeze(this.#captureFields(value, type.fieldTypes, fail));
+                } finally {
+                    this.#leave(value);
+                }
+            default:
+                return this.#captureNamed(value, type, fail);
+        }
+    }
+
+    /**
+     * A value captured as a named type: a built-in type's value and a reference of the type as they are, a reference of another type null where a nullable reference type is declared, and a structure as its declared
+     * fields, each captured in turn. A value from outside has no type until it is captured, so where it doesn't belong to a reference type, the registry's recognition tells a reference of another type from mistyped
+     * data, which fails whatever its nullability.
+     */
+    #captureNamed(value, type, fail) {
+        const named = this.#getNamedCapture(type);
+
+        if (named.kind === 'scalar') {
+            if (!named.check(value)) {
+                fail(this.#path(), value, type);
+            }
+
+            return value;
+        }
+
+        if (named.kind === 'reference') {
+            const asked = this.#asked;
+
+            if (this.#registry.belongsTo(value, type, asked)) {
+                return value;
+            }
+
+            if (type.isNullable && this.#registry.recognize(value, asked).length > 0) {
+                return null;
+            }
+
+            fail(this.#path(), value, type);
+        }
+
+        if (named.kind !== 'structured' || !ObjectUtils.isNonArrayObject(value)) {
+            fail(this.#path(), value, type);
+        }
+
+        this.#enter(value, type, fail);
+
+        let structure;
+
+        try {
+            structure = this.#captureFields(value, named.shape, fail);
+        } finally {
+            this.#leave(value);
+        }
+
+        // A captured structure keeps its type through a value of Any, as one a member answers does, recorded before it is frozen.
+        StructureTypes.recordType(structure, this.#registry, named.type);
+
+        return Object.freeze(structure);
+    }
+
+    /** The path of a field within the path of the value that holds it. */
+    static #pathOf(path, name) {
+        return path === '' ? name : `${path}.${name}`;
+    }
+
+    /** Each scalar type's check of a value, by its name: a finite number, a string and a Boolean. */
+    static #scalarChecks = new Map([
+        ['Number', value => Number.isFinite(value)],
+        ['String', value => typeof value === 'string'],
+        ['Boolean', value => typeof value === 'boolean'],
+    ]);
+
+    /** The check of the scalar type the name names, one of `NexoModule.scalarTypeNames`, which a check compiled once for the type calls with no name to tell; undefined for any other name. */
+    static getScalarCheck(typeName) {
+        return ValueCapture.#scalarChecks.get(typeName);
+    }
+
+    /** Whether the value belongs to the scalar type the name names, one of `NexoModule.scalarTypeNames`: a finite number, a string or a Boolean. */
+    static belongsToScalar(value, typeName) {
+        return ValueCapture.#scalarChecks.get(typeName)?.(value) ?? false;
+    }
+}

package/src/language/Versions.mjs

@@ -0,0 +1,14 @@
+/**
+ * Versions — the versions the implementation reports: its release, the language specification it follows, and the definition format it supports
+ */
+
+export class Versions {
+    /** The implementation's release version, which the packages and the bundle carry. */
+    static implementation = '1.0.0-preview.1';
+
+    /** The language specification version the implementation follows. */
+    static language = '1.0.0-preview.1';
+
+    /** The definition format version the implementation supports. */
+    static definition = 38;
+}

package/src/language/vocabulary/Declarations.mjs

@@ -0,0 +1,64 @@
+/**
+ * Declarations — the helpers that write a vocabulary's declarations: its parameters and members, each in the declaration shape with the defaults its contract gives it, constructing a record and registering nothing.
+ * Each writes every option it is given over its defaults, leaving none out, so a module refuses an option its declaration doesn't take, where a helper that dropped it would hide the mistake.
+ */
+
+export class Declarations {
+    /** A value parameter, required unless it is given a default. */
+    static createValueParameterDeclaration(name, type, options = {}) {
+        return { name, kind: 'value', type, required: options.default === undefined, fixed: false, nulls: 'propagate', ...options };
+    }
+
+    /**
+     * An expression parameter, evaluated against each item of the collection it follows, a list's item or a dictionary's value, and producing the type. Its null policy says how a body reads a null item: `propagate`, the
+     * default, reads each item as a value that is not null, a null item answering null without the body being evaluated, and `accept` evaluates the body against every item, null included, its `it` of the item's type.
+     */
+    static createExpressionParameterDeclaration(type, options = {}) {
+        return { name: 'expression', kind: 'expression', type, context: 'item', required: true, fixed: false, nulls: 'propagate', ...options };
+    }
+
+    /**
+     * A required predicate parameter, an expression evaluated against each item whose truthiness its implementation receives. Its null policy says how a body reads a null item, as an expression parameter's does:
+     * `propagate`, the default, answers null for it, which is falsy, without the body being evaluated, and `accept` evaluates the body against it.
+     */
+    static createPredicateParameterDeclaration(options = {}) {
+        return { name: 'expression', kind: 'predicate', type: 'Boolean', context: 'item', required: true, fixed: false, nulls: 'propagate', ...options };
+    }
+
+    /** A function parameter, always required: its callback contract, the types of the arguments the member calls the function with, in order, and the type of the result it takes from it. */
+    static createFunctionParameterDeclaration(name, type, parameterTypes) {
+        return { name, kind: 'function', type, parameterTypes, required: true };
+    }
+
+    /**
+     * A property, a member read without arguments: one with updates, which the evaluator invokes, or, without them, a property of a structured type's data where it stands directly in that type, as the contract of
+     * where it stands decides.
+     */
+    static createPropertyDeclaration(name, result, options) {
+        return Declarations.#createMemberDeclaration('property', name, result, options);
+    }
+
+    /** A function, a member called with its arguments, positional unless it says they are options, or, with `invokedBy: 'host'`, one its host invokes, its result left out where its host supplies nothing. */
+    static createFunctionDeclaration(name, result, options) {
+        return Declarations.#createMemberDeclaration('function', name, result, options);
+    }
+
+    /** An indexer, given its one key in brackets: a named one, `x.name[key]`, or, where its name is null, the unnamed one of its receivers, `x[key]`. */
+    static createIndexerDeclaration(name, result, options) {
+        return Declarations.#createMemberDeclaration('indexer', name, result, options);
+    }
+
+    /**
+     * A member of the kind, named unless its name is null, with no receiver of its own: where it stands gives it one, the type or the extension it is declared within, and a module member, among a module's `members`,
+     * takes none. A function and an indexer take no parameters unless they are given some, and a function's arguments are positional where it has parameters and is given no argument form.
+     */
+    static #createMemberDeclaration(kind, name, result, options = {}) {
+        const declaration = { ...(name === null ? {} : { name }), kind, result, ...(kind === 'property' ? {} : { parameters: [] }), ...options };
+
+        if (kind === 'function' && declaration.arguments === undefined && Array.isArray(declaration.parameters) && declaration.parameters.length > 0) {
+            declaration.arguments = 'positional';
+        }
+
+        return declaration;
+    }
+}

package/src/language/vocabulary/ItemPositions.mjs

@@ -0,0 +1,48 @@
+/**
+ * ItemPositions — where in its receiver each item stood of a list one of Nexo's own members answered of its receiver's items, handed with that list to the invocation that answers it, so the item's lineage follows its
+ * occurrence rather than its value
+ */
+
+export class ItemPositions {
+    /**
+     * The list `createAnswer` created last, and the receiver's position of each of its items, which `takePositions` hands over once. A member creates its answer after everything it evaluates, its functions' calls among
+     * them, and its invocation takes the positions as the member returns, so no other answer is created between the two. The slot is valid until another answer is created, and releases the list and its positions
+     * once taken; a global map of every answer's positions, written for each, measured a twentieth of an evaluation.
+     */
+    static #answer = null;
+
+    /** @type {readonly number[] | null} */
+    static #positions = null;
+
+    /**
+     * The receiver's items at the positions, in the positions' order, a position given twice giving its item twice, as a frozen list whose positions `takePositions` hands over. Each position is one the receiver has an
+     * item at, which its member has checked, and the member never changes the positions it gives.
+     */
+    static createAnswer(receiver, positions) {
+        const answer = Object.freeze(positions.map(position => receiver[position]));
+
+        ItemPositions.#answer = answer;
+        ItemPositions.#positions = positions;
+
+        return answer;
+    }
+
+    /** The position in its receiver of each item of the list, in the list's order, where `createAnswer` created it last and none has taken them, handed over once; undefined for any other list. */
+    static takePositions(list) {
+        if (list !== ItemPositions.#answer) {
+            return undefined;
+        }
+
+        const positions = ItemPositions.#positions;
+
+        ItemPositions.#answer = null;
+        ItemPositions.#positions = null;
+
+        return positions;
+    }
+
+    /** The positions from the start to before the end, in order, none where the end is not after the start. */
+    static createSpan(start, end) {
+        return Array.from({ length: Math.max(end - start, 0) }, (_, offset) => start + offset);
+    }
+}

package/src/language/vocabulary/ListOrdering.mjs

@@ -0,0 +1,145 @@
+/**
+ * ListOrdering — the order `orderBy` and `thenBy` give a list: each item's keys, one for each criterion, kept with the list they ordered, so a later `thenBy` refines its ties without evaluating them again
+ */
+
+import { ItemPositions } from './ItemPositions.mjs';
+import { MemberFailure } from './MemberFailure.mjs';
+
+/** The domains an ordering key is of, each compared within itself alone: numbers numerically, strings by code unit, without a locale, and Booleans, false before true. */
+const KEY_DOMAINS = Object.freeze(['number', 'string', 'boolean']);
+
+export class ListOrdering {
+    /**
+     * The ordering of each list `orderBy` or `thenBy` answered, or a copy of it carried that ordering, by the list. A list never changes, so an entry is valid for good, and it is released with its list, which the map holds
+     * weakly; no evaluation reads another's lists, so none shares an entry.
+     * @type {WeakMap<object, ListOrdering>}
+     */
+    static #orderings = new WeakMap();
+
+    /** Each item's keys, in the list's order, one for each criterion in the order they were applied. @type {readonly (readonly unknown[])[]} */
+    #keys;
+
+    /** @param {readonly (readonly unknown[])[]} keys Each item's keys, in the list's order. */
+    constructor(keys) {
+        this.#keys = keys;
+    }
+
+    /**
+     * The items ordered by the key each gives, its expression evaluated once for each item, ascending or descending, a null key last either way, items of equal keys keeping their order; the answer keeps its
+     * keys, so `thenBy` refines it. A key of no domain, or keys of two, are refused (NEXO5036).
+     */
+    static orderBy(list, keyOf, isDescending, memberName) {
+        const keys = ListOrdering.#evaluateKeys(list, keyOf, memberName);
+        const order = list.map((_, index) => index).sort((one, other) => ListOrdering.compareKeys(keys[one], keys[other], isDescending));
+
+        return ListOrdering.#createOrdered(list, order, order.map(index => Object.freeze([keys[index]])));
+    }
+
+    /**
+     * The items `orderBy` and any `thenBy` after it ordered, each run of items whose keys so far are equal ordered within itself by the key each gives, evaluated once for each item, ascending or descending, a null key
+     * last either way; items keep their place where their keys are equal, so the list is refined, never sorted again. A list no `orderBy` ordered is refused (NEXO5037), and a key of no domain, or keys of two
+     * (NEXO5036).
+     */
+    static thenBy(list, keyOf, isDescending, memberName) {
+        const ordering = ListOrdering.#orderings.get(list);
+
+        if (ordering === undefined) {
+            throw new MemberFailure('NEXO5037', `'${memberName}' refines the order 'orderBy' gave a list, and this list was ordered by no 'orderBy': order it with 'orderBy' first, which a local or 'thenBy' keeps, and no other member does`);
+        }
+
+        const keys = ListOrdering.#evaluateKeys(list, keyOf, memberName);
+        const order = [];
+
+        for (let start = 0; start < list.length;) {
+            let end = start + 1;
+
+            while (end < list.length && ListOrdering.#haveEqualKeys(ordering.#keys[start], ordering.#keys[end])) {
+                end++;
+            }
+
+            const run = Array.from({ length: end - start }, (_, offset) => start + offset);
+
+            order.push(...run.sort((one, other) => ListOrdering.compareKeys(keys[one], keys[other], isDescending)));
+            start = end;
+        }
+
+        return ListOrdering.#createOrdered(list, order, order.map(index => Object.freeze([...ordering.#keys[index], keys[index]])));
+    }
+
+    /** The first item whose key is the least, or the greatest, items whose key is null skipped, and null where none gives one; a key of no domain, or keys of two, are refused (NEXO5036). */
+    static findExtreme(list, keyOf, isGreatest, memberName) {
+        const keys = ListOrdering.#evaluateKeys(list, keyOf, memberName);
+        let best = -1;
+
+        keys.forEach((key, index) => {
+            if (key !== null && (best === -1 || ListOrdering.compareKeys(key, keys[best], isGreatest) < 0)) {
+                best = index;
+            }
+        });
+
+        return best === -1 ? null : list[best];
+    }
+
+    /** Carries the ordering of the list a member answered to the copy of it the evaluation keeps, its items in the same places, so a `thenBy` given the copy refines it. */
+    static carry(list, copy) {
+        const ordering = ListOrdering.#orderings.get(list);
+
+        if (ordering !== undefined) {
+            ListOrdering.#orderings.set(copy, ordering);
+        }
+    }
+
+    /** How two keys of one domain order, ascending or descending, a null key after any other whichever the direction. */
+    static compareKeys(one, other, isDescending) {
+        if (one === null || other === null) {
+            return one === other ? 0 : one === null ? 1 : -1;
+        }
+
+        const ascending = one < other ? -1 : one > other ? 1 : 0;
+
+        return isDescending ? -ascending : ascending;
+    }
+
+    /** Each item's key, its expression evaluated once for each item, checked to be null or of one domain, which every key of the criterion shares. */
+    static #evaluateKeys(list, keyOf, memberName) {
+        const keys = list.map(item => keyOf(item));
+        let domain = null;
+
+        for (const key of keys) {
+            if (key === null) {
+                continue;
+            }
+
+            if (!KEY_DOMAINS.includes(typeof key)) {
+                throw new MemberFailure('NEXO5036', `'${memberName}' orders by numbers, strings or Booleans, and a key is ${ListOrdering.#describe(key)}`);
+            }
+
+            domain ??= typeof key;
+
+            if (typeof key !== domain) {
+                throw new MemberFailure('NEXO5036', `'${memberName}' orders by keys of one domain, and its keys are ${domain}s and ${typeof key}s`);
+            }
+        }
+
+        return keys;
+    }
+
+    /** Whether two items' keys so far are equal, criterion by criterion, null equal to null and `-0` to `0`. */
+    static #haveEqualKeys(one, other) {
+        return one.every((key, index) => key === other[index]);
+    }
+
+    /** The list's items in the order of their positions, frozen, holding each item's keys as their ordering and, through `ItemPositions`, the position each stood at in the list. */
+    static #createOrdered(list, order, keys) {
+        const ordered = ItemPositions.createAnswer(list, order);
+
+        ListOrdering.#orderings.set(ordered, new ListOrdering(Object.freeze(keys)));
+
+        return ordered;
+    }
+
+    /** A key outside the ordering domains, as a message names it. */
+    static #describe(key) {
+        return Array.isArray(key) ? 'a list' : typeof key === 'object' ? 'an object or a reference' : `a ${typeof key}`;
+    }
+}

package/src/language/vocabulary/MemberFailure.mjs

@@ -0,0 +1,21 @@
+/**
+ * MemberFailure — a failure one of Nexo's own members reports of the values it is given, which the evaluator raises at the call with the code it carries
+ */
+
+export class MemberFailure extends Error {
+    #code;
+
+    /**
+     * @param {string} code The code of the condition the values break.
+     * @param {string} message What the call is refused for.
+     */
+    constructor(code, message) {
+        super(message);
+        this.#code = code;
+    }
+
+    /** The code of the condition the values break. */
+    get code() {
+        return this.#code;
+    }
+}