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

package/src/language/Range.mjs

@@ -0,0 +1,51 @@
+/**
+ * Range — a half-open interval of a list's positions: its start and its end, each a number counted from the start, an index counted from the end, or null where the range leaves it out
+ */
+
+import { Index } from './Index.mjs';
+
+export class Range {
+    /** @type {number | Index | null} */
+    #start;
+
+    /** @type {number | Index | null} */
+    #end;
+
+    /**
+     * @param {number | Index | null} start Its start, a nonnegative safe integer or an index, null where it is left out, the list's start.
+     * @param {number | Index | null} end Its end, a nonnegative safe integer or an index, null where it is left out, the list's end.
+     */
+    constructor(start, end) {
+        this.#start = start;
+        this.#end = end;
+        Object.freeze(this);
+    }
+
+    /** Its start, null where it is left out. */
+    get start() {
+        return this.#start;
+    }
+
+    /** Its end, null where it is left out. */
+    get end() {
+        return this.#end;
+    }
+
+    /** The offsets from the start its boundaries stand at within a list of the length, applied to that one length: a start left out 0, an end left out the length, an index the length less its offset. */
+    resolveIn(length) {
+        return { start: Range.#offsetOf(this.#start, 0, length), end: Range.#offsetOf(this.#end, length, length) };
+    }
+
+    /** The range as a script writes it. */
+    toString() {
+        return `${this.#start ?? ''}..${this.#end ?? ''}`;
+    }
+
+    static #offsetOf(boundary, absent, length) {
+        if (boundary === null) {
+            return absent;
+        }
+
+        return boundary instanceof Index ? boundary.resolveIn(length) : boundary;
+    }
+}

package/src/language/RecentlyUsed.mjs

@@ -0,0 +1,50 @@
+/**
+ * RecentlyUsed — the entries kept for the keys used most recently, as many as its capacity, which a key enters while there is room and otherwise at its second miss among the misses it remembers, so a stream of keys
+ * met once never displaces the keys met again, and the entry used least recently leaves to make room
+ */
+
+export class RecentlyUsed {
+    #capacity;
+
+    /** The entries, the most recently used last. @type {Map<string, unknown>} */
+    #entries = new Map();
+
+    /** The keys that missed while the entries were full, the most recent last, as many as twice the capacity, each entering at its next miss. @type {Set<string>} */
+    #missed = new Set();
+
+    /** @param {number} capacity The most entries it keeps. */
+    constructor(capacity) {
+        this.#capacity = capacity;
+    }
+
+    /** The entry of the key, which becomes the most recently used, or undefined where none is kept. */
+    get(key) {
+        const value = this.#entries.get(key);
+
+        if (value !== undefined) {
+            this.#entries.delete(key);
+            this.#entries.set(key, value);
+        }
+
+        return value;
+    }
+
+    /** Offers the entry of a key that missed: it is kept while there is room or at the key's second miss, letting the entry used least recently go, and only remembered otherwise. */
+    offer(key, value) {
+        if (this.#entries.size < this.#capacity || this.#missed.delete(key)) {
+            this.#entries.set(key, value);
+
+            if (this.#entries.size > this.#capacity) {
+                this.#entries.delete(this.#entries.keys().next().value);
+            }
+
+            return;
+        }
+
+        this.#missed.add(key);
+
+        if (this.#missed.size > this.#capacity * 2) {
+            this.#missed.delete(this.#missed.values().next().value);
+        }
+    }
+}

package/src/language/ResolvedDefinition.mjs

@@ -0,0 +1,219 @@
+/**
+ * ResolvedDefinition — a definition resolved against the vocabulary: the host call it ends in, the type of its result, and what each of its nodes resolved to
+ */
+
+/** The character that begins each segment of a JSON Pointer. */
+const SLASH = '/'.charCodeAt(0);
+
+export class ResolvedDefinition {
+    #definition;
+    #type;
+    #hostCall;
+    #resolutions;
+    #usedDeclarations;
+    #deferredAccesses;
+
+    /** The JSON Pointer each node of the definition's expression stands at, by the node, a call's copy of a function's body among them, as resolution recorded it reaching the node. @type {WeakMap<object, string>} */
+    #pointers;
+
+    /**
+     * @param {object} definition The request's definition, whose every node is an object of its own.
+     * @param {import('./Type.mjs').Type | null} type The type of its result, null for a host call that supplies nothing.
+     * @param {{ node: object, pointer: string, name: string, declaration: object | null, candidates: readonly object[] } | null} hostCall The host call the script ends in, null for one that gives a value.
+     * @param {Map<string, object>} resolutions What each member node, by its JSON Pointer, resolved to.
+     * @param {WeakMap<object, string>} pointers The JSON Pointer each node resolution reached stands at, by the node.
+     * @param {object[]} usedDeclarations The declarations the request uses, each with the pointer that used it, a call's copy of a function's body among them, and its qualified name, the name a message gives it, qualified
+     * by the type its declaration is for.
+     * @param {{ name: string | null, pointer: string, candidates: object[] }[]} deferredAccesses The accesses whose member is selected during evaluation, each with the name it accesses, null for an unnamed indexer,
+     * and the declarations its selection could choose, each a use at its pointer.
+     * @param {{ node: object, pointer: string, bodyPointer: string }[]} functionBodyCopies The copy of a function's body each call resolved, with the pointer it was resolved under and the pointer of the body it copies.
+     * @param {boolean} mayRecognize Whether evaluating it may ask a module's `typeOf` of a value, in any branch, reached or not; true where left out, so a resolution that doesn't say is made stale by every module
+     * declaring a `typeOf`, never kept current past one.
+     */
+    constructor(definition, type, hostCall, resolutions, pointers, usedDeclarations, deferredAccesses, functionBodyCopies = [], mayRecognize = true) {
+        this.#mayRecognize = mayRecognize;
+        this.#definition = definition;
+        this.#type = type;
+        this.#hostCall = hostCall;
+        this.#resolutions = resolutions;
+        this.#pointers = pointers;
+        this.#functionBodyCopies = functionBodyCopies;
+        this.#usedDeclarations = Object.freeze(this.#definitionUsesOf(usedDeclarations));
+        this.#deferredAccesses = Object.freeze(this.#definitionAccessesOf(deferredAccesses));
+    }
+
+    /** @type {{ node: object, pointer: string, bodyPointer: string }[]} */
+    #functionBodyCopies;
+
+    /**
+     * The uses, each named by the pointer into the definition it stands at, as a hook's request names its call, a body copy's pointer taken back to the body it copies; a declaration is kept once at each pointer, since
+     * every call of one function resolves its body's uses again.
+     */
+    #definitionUsesOf(usedDeclarations) {
+        const kept = [];
+        // The declarations kept at each pointer, so a use is looked for among those at its own pointer alone.
+        const keptAt = new Map();
+
+        for (const use of usedDeclarations) {
+            const pointer = this.resolveDefinitionPointer(use.pointer);
+            let declarations = keptAt.get(pointer);
+
+            if (declarations === undefined) {
+                declarations = new Set();
+                keptAt.set(pointer, declarations);
+            }
+
+            if (!declarations.has(use.declaration)) {
+                declarations.add(use.declaration);
+                kept.push({ ...use, pointer });
+            }
+        }
+
+        return kept;
+    }
+
+    /** The deferred accesses, each named by the pointer into the definition it stands at, as a use is, and kept once at each pointer, since every call of one function resolves its body's accesses again. */
+    #definitionAccessesOf(deferredAccesses) {
+        const kept = new Map();
+
+        for (const access of deferredAccesses) {
+            const pointer = this.resolveDefinitionPointer(access.pointer);
+
+            if (!kept.has(pointer)) {
+                kept.set(pointer, { ...access, pointer, candidates: access.candidates.map(candidate => ({ ...candidate, pointer })) });
+            }
+        }
+
+        return [...kept.values()];
+    }
+
+    /**
+     * The pointer into the definition each pointer resolved to, by the pointer: valid for good, since the body copies never change, and released with this resolved definition. An evaluation with hooks resolves the pointer
+     * of every invocation it reports, which would scan the body copies each time.
+     * @type {Map<string, string>}
+     */
+    #definitionPointers = new Map();
+
+    /** Resolves the pointer into the definition a pointer names, a pointer into a call's copy of a function's body naming the part of the body it copies, and any other pointer itself. */
+    resolveDefinitionPointer(pointer) {
+        let definitionPointer = this.#definitionPointers.get(pointer);
+
+        if (definitionPointer === undefined) {
+            definitionPointer = ResolvedDefinition.resolveDefinitionPointer(pointer, this.#functionBodyCopies);
+            this.#definitionPointers.set(pointer, definitionPointer);
+        }
+
+        return definitionPointer;
+    }
+
+    /** The pointer into the definition a pointer names among the function body copies, each call's copy of a function's body taken back to the body it copies, a copy within a copy as many times as it is one. */
+    static resolveDefinitionPointer(pointer, functionBodyCopies) {
+        let definitionPointer = pointer;
+
+        for (let bodyCopy = ResolvedDefinition.#bodyCopyOf(definitionPointer, functionBodyCopies); bodyCopy !== undefined; bodyCopy = ResolvedDefinition.#bodyCopyOf(definitionPointer, functionBodyCopies)) {
+            definitionPointer = `${bodyCopy.bodyPointer}${definitionPointer.slice(bodyCopy.pointer.length)}`;
+        }
+
+        return definitionPointer;
+    }
+
+    /** The body copy whose pointer the pointer is or lies beneath, the innermost one, which is resolved after the one it lies in. */
+    static #bodyCopyOf(pointer, functionBodyCopies) {
+        for (let index = functionBodyCopies.length - 1; index >= 0; index--) {
+            const bodyCopy = functionBodyCopies[index];
+            const { length } = bodyCopy.pointer;
+
+            // The pointer is the copy's, or one beneath it, whose next segment begins with a slash.
+            if (pointer.startsWith(bodyCopy.pointer) && (pointer.length === length || pointer.charCodeAt(length) === SLASH)) {
+                return bodyCopy;
+            }
+        }
+
+        return undefined;
+    }
+
+    #mayRecognize;
+
+    /**
+     * Whether evaluating it may recognize a value, asking each module's `typeOf`, in any branch, reached or not: where a declaration it uses gives the script a value of `Any`, a deferred access among them, or it ends
+     * in a host call whose supplied type holds a nullable reference type. A registration changes a resolution through recognition alone, so one that may not stays current whatever is registered after it.
+     */
+    get mayRecognize() {
+        return this.#mayRecognize;
+    }
+
+    /** The request's definition. */
+    get definition() {
+        return this.#definition;
+    }
+
+    /** The type of the request's result, null for a host call that supplies nothing. */
+    get type() {
+        return this.#type;
+    }
+
+    /**
+     * The host call the script ends in: its node, where it stands, its name, its declaration, null on a receiver of unknown type, and its candidates, the declaration alone or, on a receiver of unknown type, every one
+     * that takes the call as it is written; null for a script that gives a value.
+     */
+    get hostCall() {
+        return this.#hostCall;
+    }
+
+    /** The declarations the request uses, with where each is used in the definition and the name a message gives it. */
+    get usedDeclarations() {
+        return this.#usedDeclarations;
+    }
+
+    /** The accesses whose member is selected during evaluation, by its value's actual type, each with where it stands in the definition, the name it accesses and the declarations its selection could choose. */
+    get deferredAccesses() {
+        return this.#deferredAccesses;
+    }
+
+    /**
+     * Every declaration evaluation could select: the used declarations, each deferred access's candidates at its pointer, every accessible declaration of its name and form, and each conversion of a value of Any's,
+     * every conversion to its type the imports make available, which its value's actual type selects one of or none of, so they are an overestimate wherever either remains.
+     */
+    get candidateDeclarations() {
+        return this.#definitionUsesOf([...this.#usedDeclarations, ...this.#deferredAccesses.flatMap(access => access.candidates), ...this.#deferredConversionUses()]);
+    }
+
+    /** Whether evaluation selects a declaration of its own, at a deferred access or a conversion of a value of Any, so the candidate declarations overestimate what it uses. */
+    get selectsAsEvaluated() {
+        return this.#deferredAccesses.length > 0 || this.#deferredConversionUses().length > 0;
+    }
+
+    /** The candidates of each conversion of a value of Any, at its pointer. */
+    #deferredConversionUses() {
+        return [...this.#resolutions.values()].flatMap(resolution => (resolution.kind === 'conversion' && resolution.candidateUses !== undefined ? resolution.candidateUses : []));
+    }
+
+    /**
+     * The copy of a function's body each call resolved, with the pointer it was resolved under and the pointer of the body it copies.
+     * @internal
+     */
+    get functionBodyCopies() {
+        return this.#functionBodyCopies;
+    }
+
+    /** What the member node at the pointer resolved to. */
+    getResolution(pointer) {
+        return this.#resolutions.get(pointer);
+    }
+
+    /**
+     * What the node of the definition resolved to.
+     * @internal
+     */
+    resolutionOf(node) {
+        return this.#resolutions.get(this.#pointers.get(node));
+    }
+
+    /**
+     * The JSON Pointer of the node of the definition.
+     * @internal
+     */
+    pointerOf(node) {
+        return this.#pointers.get(node);
+    }
+}

package/src/language/ResultPath.mjs

@@ -0,0 +1,101 @@
+/**
+ * ResultPath — a path into an expression's result, of field names and list indices: its shape, the type it reaches and the value it reads
+ */
+
+import { NexoErrors } from './NexoError.mjs';
+import { Names } from './Names.mjs';
+import { Type } from './Type.mjs';
+
+export class ResultPath {
+    /** Validates a path's shape before anything reads it: a list, each of its items a name or a list index, a whole number that is not negative, and any other is refused. */
+    static validateShape(path) {
+        if (!Array.isArray(path)) {
+            throw NexoErrors.structure('NEXO2646', `A path is a list of the names of fields and of list indices, and ${JSON.stringify(path) ?? String(path)} is none`, {});
+        }
+
+        for (const item of path) {
+            const isIndex = Number.isInteger(item) && item >= 0;
+
+            // A field a result holds is named by any word, a reserved word among them.
+            if (!isIndex && !Names.isIdentifier(item)) {
+                throw NexoErrors.structure('NEXO2646', `A path holds the names of fields and list indices that are whole numbers and not negative, and ${JSON.stringify(item) ?? String(item)} is neither`, {});
+            }
+        }
+    }
+
+    /**
+     * The type the path reaches in the result's type, nullable where a step it passes is; a type that says nothing of its value takes any path, which is checked once its type is known. The path's shape is its
+     * caller's to validate first.
+     * @param {Type} resultType The result's type.
+     * @param {(string | number)[]} path
+     * @param {import('./vocabulary/NexoRegistry.mjs').NexoRegistry} registry Where a structured type's fields are declared.
+     * @param {() => object} locationOf Where a path that does not fit the result is refused, found only when one is.
+     */
+    static typeAt(resultType, path, registry, locationOf) {
+        let type = resultType;
+        let isNullable = false;
+
+        for (const item of path) {
+            if (type.kind === 'null' || type.kind === 'never') {
+                return Type.null;
+            }
+
+            isNullable ||= type.isNullable;
+
+            if (typeof item === 'number') {
+                if (!type.isList) {
+                    throw NexoErrors.validation('NEXO3601', `The path indexes ${type.toNonNullable()}, which is no list`, locationOf());
+                }
+
+                // An index out of range gives null.
+                type = type.itemType;
+                isNullable = true;
+                continue;
+            }
+
+            // A dictionary exports its entries, and a pair its key and its value, so a path steps through them as through the result's exported form.
+            if (type.isDictionary && item === 'entries') {
+                const [keyType, valueType] = type.typeArguments;
+
+                type = Type.createListType(Type.createObjectType(new Map([['key', keyType], ['value', valueType]])));
+                continue;
+            }
+
+            if (type.isPair && (item === 'key' || item === 'value')) {
+                type = type.typeArguments[item === 'key' ? 0 : 1];
+                continue;
+            }
+
+            // An object type's object field, or a property of a structured type's data, each type's lookup its own.
+            const nextType = type.kind === 'object' ? type.getObjectFieldType(item) : (registry.getDataShape(type)?.get(item) ?? null);
+
+            if (nextType === null) {
+                throw NexoErrors.validation('NEXO3602', `The path names '${item}', which ${type.toNonNullable()} does not hold`, locationOf());
+            }
+
+            type = nextType;
+        }
+
+        return isNullable ? type.toNullable() : type;
+    }
+
+    /**
+     * The value the path reaches in the result: a name steps to an object field the value holds, and an index to a list's item; null where a step it passes is null or holds nothing at the step, an object field it
+     * lacks, an index out of range, and a name of a list or an index of an object among them. The path's shape is its caller's to validate first.
+     */
+    static valueAt(value, path) {
+        let current = value;
+
+        for (const item of path) {
+            const holds = typeof item === 'number' ? Array.isArray(current) && item < current.length : current !== null && typeof current === 'object' && !Array.isArray(current) && Object.hasOwn(current, item);
+
+            if (!holds) {
+                return null;
+            }
+
+            current = current[item] ?? null;
+        }
+
+        return current;
+    }
+}

package/src/language/ScopeLocals.mjs

@@ -0,0 +1,102 @@
+/**
+ * ScopeLocals — the names in scope where resolution reaches a node, each with what it holds: a local, an object field, a conditional binding, a function parameter or an option
+ */
+
+/** How many names a scope adds over the map beneath it before it is flattened into one. */
+const MOST_LAYERS = 16;
+
+export class ScopeLocals {
+    /** The names this scope adds to, the one beneath it; null for a scope flattened into its map. @type {ScopeLocals | null} */
+    #enclosing;
+
+    /** The name this scope adds. @type {string | null} */
+    #name;
+
+    /** What the name it adds holds. */
+    #entry;
+
+    /** Every name in scope, for a scope flattened into one map; null for one that adds a name. @type {Map<string, unknown> | null} */
+    #names;
+
+    /** How many names this scope and those beneath it add over the map beneath them. */
+    #layers;
+
+    /**
+     * A scope is made empty, or by adding a name to another; neither is made directly.
+     * @param {ScopeLocals | null} enclosing The scope the name is added to, null for one flattened into its map.
+     * @param {string | null} name The name it adds.
+     * @param {unknown} entry What the name holds.
+     * @param {Map<string, unknown> | null} names Every name in scope, for a scope flattened into one map.
+     * @param {number} layers How many names it and those beneath it add over the map beneath them.
+     */
+    constructor(enclosing, name, entry, names, layers) {
+        this.#enclosing = enclosing;
+        this.#name = name;
+        this.#entry = entry;
+        this.#names = names;
+        this.#layers = layers;
+    }
+
+    /** The scope with no name in it. */
+    static empty = new ScopeLocals(null, null, undefined, new Map(), 0);
+
+    /**
+     * The scope with the name added, holding the entry, and hiding any name of its spelling this one has; this scope is left as it is, so each scope keeps the names in scope where it was made. A scope adds its name over
+     * this one rather than copying every name, so adding the fields of an object one by one takes as long as the fields do, not as their square; every sixteenth added flattens them into one map, so a lookup reads
+     * sixteen names at most.
+     */
+    with(name, entry) {
+        if (this.#layers < MOST_LAYERS) {
+            return new ScopeLocals(this, name, entry, null, this.#layers + 1);
+        }
+
+        const names = new Map();
+
+        this.#copyInto(names);
+        names.set(name, entry);
+
+        return new ScopeLocals(null, null, undefined, names, 0);
+    }
+
+    /** What the name holds in this scope, the one added last of its spelling; undefined where none is in scope. */
+    get(name) {
+        let scope = this;
+
+        while (scope.#names === null) {
+            if (scope.#name === name) {
+                return scope.#entry;
+            }
+
+            scope = scope.#enclosing;
+        }
+
+        return scope.#names.get(name);
+    }
+
+    /** Whether a name of the spelling is in scope. */
+    has(name) {
+        let scope = this;
+
+        while (scope.#names === null) {
+            if (scope.#name === name) {
+                return true;
+            }
+
+            scope = scope.#enclosing;
+        }
+
+        return scope.#names.has(name);
+    }
+
+    /** Copies every name in scope into the map, each added later replacing one of its spelling added before it. */
+    #copyInto(names) {
+        if (this.#names !== null) {
+            this.#names.forEach((entry, name) => names.set(name, entry));
+
+            return;
+        }
+
+        this.#enclosing.#copyInto(names);
+        names.set(this.#name, this.#entry);
+    }
+}

package/src/language/StructureTypes.mjs

@@ -0,0 +1,48 @@
+/**
+ * StructureTypes — the structured type each structured value Nexo made is of, held by the value itself: a member's answer it copied, an object expression it constructed, and a value a host supplies or binds that it
+ * captured, so a value of Any keeps the identity its declaration gave it
+ */
+
+/** A base whose constructor answers the value it is given, so a private field its subclass declares is added to that value. */
+class Stamp {
+    constructor(value) {
+        return value;
+    }
+}
+
+export class StructureTypes extends Stamp {
+    /**
+     * The registry whose declaration typed the structured value, held by the value as a private field, which no reflection reads and no copy carries, beside its type. A record lives as long as its value, is replaced
+     * where another declaration gives that value as another type, and is read only against the registry that wrote it, so a value never carries a type into a registry that doesn't declare it. A weak map of every
+     * value, which each record was written to before, grew with every binding until a collection, and writing it measured half of binding.
+     * @type {object}
+     */
+    #registry;
+
+    /** The structured type the registry gave the value. @type {import('./Type.mjs').Type} */
+    #type;
+
+    constructor(value, registry, type) {
+        super(value);
+        this.#registry = registry;
+        this.#type = type;
+    }
+
+    /**
+     * Records the structured value as of the type, a non-null structured type the registry declares; a value recorded already as the same type by the same registry keeps its record. The value is one Nexo made,
+     * recorded before it is frozen, never a host's own.
+     */
+    static recordType(value, registry, type) {
+        if (!(#registry in value)) {
+            new StructureTypes(value, registry, type);
+        } else {
+            value.#registry = registry;
+            value.#type = type;
+        }
+    }
+
+    /** The structured type the value was recorded as, where the registry given recorded it, and undefined otherwise. */
+    static getType(value, registry) {
+        return #registry in value && value.#registry === registry ? value.#type : undefined;
+    }
+}