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

package/src/language/ImportedVocabulary.mjs

@@ -0,0 +1,137 @@
+/**
+ * ImportedVocabulary — what a script's imports make available: the namespaces their local names begin, the types a script names, and the declarations it may select, Nexo's own always among them
+ */
+
+import { Imports } from './Imports.mjs';
+import { Type } from './Type.mjs';
+import { TypeNameScope } from './vocabulary/TypeNameScope.mjs';
+import { Vocabulary } from './vocabulary/Vocabulary.mjs';
+
+export class ImportedVocabulary {
+    /** The registry the imports name modules, types and extensions of. */
+    #registry;
+
+    /** The module each local name a module import gives names, by that local name. @type {Map<string, string>} */
+    #namespaceModules = new Map();
+
+    /** The names of the modules the script imports whole, under whichever local names. @type {Set<string>} */
+    #importedModules = new Set();
+
+    /** The scope the script's type names are read in, which its imports give. @type {TypeNameScope} */
+    #typeNameScope;
+
+    /** The types and the extensions the script imports by name, each a declaration whose members the import makes available. @type {Set<object>} */
+    #importedDeclarations = new Set();
+
+    /** The ordinary types the script imports by name and every supertype above each, whose members an imported type has as its own or inherits. @type {Set<object>} */
+    #typeLineages = new Set();
+
+    /** The extension each local name a type import of an extension gives names, by that local name, which an extension access names it by first. @type {Map<string, object>} */
+    #importedExtensions = new Map();
+
+    /** The first local name a type import gives each type or extension it imports, by the declaration. @type {Map<object, string>} */
+    #declarationLocalNames = new Map();
+
+    /**
+     * @param {import('./vocabulary/NexoRegistry.mjs').NexoRegistry} registry The registry the imports name declarations of.
+     * @param {readonly object[]} imports The script's imports, in a definition's shape, each naming a module the registry holds and, for a type import, a public type or extension it declares.
+     */
+    constructor(registry, imports) {
+        this.#registry = registry;
+        this.#typeNameScope = TypeNameScope.createScriptScope(imports);
+
+        for (const entry of imports) {
+            const localName = Imports.localNameOf(entry);
+
+            if (Imports.isModuleImport(entry)) {
+                this.#namespaceModules.set(localName, entry.module);
+                this.#importedModules.add(entry.module);
+
+                continue;
+            }
+
+            const declaration = registry.getModuleType(entry.module, entry.type);
+
+            this.#importedDeclarations.add(declaration);
+
+            if (!this.#declarationLocalNames.has(declaration)) {
+                this.#declarationLocalNames.set(declaration, localName);
+            }
+
+            if (declaration.kind === 'extension') {
+                this.#importedExtensions.set(localName, declaration);
+            }
+
+            if (declaration.kind !== 'extension') {
+                for (let reached = Type.createNamedType(entry.type, false, entry.module); reached !== null; reached = registry.getSupertype(reached)) {
+                    this.#typeLineages.add(registry.getTypeDeclaration(reached));
+                }
+            }
+        }
+    }
+
+    /** The local names the module imports give, each beginning its module's namespace where it stands in place of a value. */
+    get namespaceNames() {
+        return new Set(this.#namespaceModules.keys());
+    }
+
+    /** The name of the module the local name a module import gives names, or undefined where no module import gives it. */
+    getNamespaceModule(localName) {
+        return this.#namespaceModules.get(localName);
+    }
+
+    /** The local name the module imports give the module first, which a name the script writes qualified by it begins with, or undefined where the script imports it under none. */
+    getNamespaceName(moduleName) {
+        return [...this.#namespaceModules].find(([, module]) => module === moduleName)?.[0];
+    }
+
+    /** The names of the modules the script imports whole, whose public extensions an extension access names unqualified beside Nexo's own. */
+    get importedModuleNames() {
+        return [...this.#importedModules];
+    }
+
+    /** The extension the local name a type import gives names, which an extension access names it by before any module's of its name; undefined where no import of an extension gives it. */
+    getImportedExtension(localName) {
+        return this.#importedExtensions.get(localName);
+    }
+
+    /** The local name a type import gives the type or the extension, the first where several do, or undefined where none imports it by name. */
+    getLocalNameOf(declaration) {
+        return this.#declarationLocalNames.get(declaration);
+    }
+
+    /** Whether the script imports the module whole, which makes its public vocabulary available. */
+    importsModule(moduleName) {
+        return this.#importedModules.has(moduleName);
+    }
+
+    /** The scope the script's type names are read in: its type imports' names first, then Nexo's own types, then its imported modules', qualified by the local names its module imports give. */
+    get typeNameScope() {
+        return this.#typeNameScope;
+    }
+
+    /**
+     * Whether the script's imports make the declaration available to select: one of Nexo's own, which every script has; one its declaring module's import makes available; one an imported extension declares; or one an
+     * imported type declares within it, or a supertype above it does, which the imported type inherits. A module member is reached through its module's import alone.
+     */
+    makesAvailable(declaration) {
+        const moduleName = this.#registry.getDeclaringModuleName(declaration);
+
+        if (moduleName === Vocabulary.moduleName || this.#importedModules.has(moduleName)) {
+            return true;
+        }
+
+        const containing = this.#registry.getContainingType(declaration);
+
+        if (containing === undefined) {
+            return false;
+        }
+
+        return containing.kind === 'extension' ? this.#importedDeclarations.has(containing) : this.#typeLineages.has(containing);
+    }
+
+    /** The declarations the script's imports make available, in the order given. */
+    getAvailable(declarations) {
+        return declarations.filter(declaration => this.makesAvailable(declaration));
+    }
+}

package/src/language/Imports.mjs

@@ -0,0 +1,141 @@
+/**
+ * Imports — a script's imports in a definition's shape: the local name each gives, the imports a host supplies, checked as a definition's are, and the imports a definition records, each once, in order of the local name it gives
+ */
+
+import { NexoErrors } from './NexoError.mjs';
+import { Names } from './Names.mjs';
+
+/** The keys an import holds: its module, its type where it imports one, and its alias where it gives a local name other than its own. */
+const IMPORT_KEYS = Object.freeze(['module', 'type', 'alias']);
+
+export class Imports {
+    /** The local name the import gives in its script: its alias, or else its type's name, or else its module's. */
+    static localNameOf(entry) {
+        return entry.alias ?? entry.type ?? entry.module;
+    }
+
+    /** Whether the import imports a module, whose local name begins its namespace, rather than one of its types. */
+    static isModuleImport(entry) {
+        return entry.type === undefined;
+    }
+
+    /** The local names the imports give modules, each beginning its module's namespace where it stands in place of a value. */
+    static namespaceNamesOf(imports) {
+        return new Set(imports.filter(entry => Imports.isModuleImport(entry)).map(entry => Imports.localNameOf(entry)));
+    }
+
+    /** Whether two imports import one declaration under one local name, which counts once. */
+    static isSameImport(one, other) {
+        return one.module === other.module && one.type === other.type && Imports.localNameOf(one) === Imports.localNameOf(other);
+    }
+
+    /** The import as text writes it: `import`, its alias and `=` where it has one, its module and, where it imports a type, a dot and the type's name, as `import Measures = Measurements`. */
+    static quote(entry) {
+        const source = entry.type === undefined ? entry.module : `${entry.module}.${entry.type}`;
+
+        return entry.alias === undefined ? `import ${source}` : `import ${entry.alias} = ${source}`;
+    }
+
+    /** The imports, each once, in order of the local name it gives, the order a definition records them in, so the order they were written or supplied in decides nothing. */
+    static mergeImports(...lists) {
+        const merged = [];
+
+        for (const entry of lists.flat()) {
+            if (!merged.some(other => Imports.isSameImport(entry, other))) {
+                merged.push(entry);
+            }
+        }
+
+        return merged.sort((one, other) => Imports.#compareLocalNames(Imports.localNameOf(one), Imports.localNameOf(other)));
+    }
+
+    /** The two imports that give one local name to different declarations, the first such pair in order, or null where none do. */
+    static findConflict(imports) {
+        for (let index = 0; index < imports.length; index++) {
+            const other = imports.slice(0, index).find(earlier => Imports.localNameOf(earlier) === Imports.localNameOf(imports[index]) && !Imports.isSameImport(earlier, imports[index]));
+
+            if (other !== undefined) {
+                return [other, imports[index]];
+            }
+        }
+
+        return null;
+    }
+
+    /**
+     * The imports a host supplies, each a module's name or an import in a definition's shape, as definition-shaped imports, each once, in order of the local name it gives. Each is checked as a definition's import is,
+     * and two giving one local name to different declarations are refused, each with NEXO2008.
+     * @param {unknown} supplied
+     */
+    static createSuppliedImports(supplied) {
+        if (supplied === undefined) {
+            return [];
+        }
+
+        if (!Array.isArray(supplied)) {
+            throw NexoErrors.structure('NEXO2008', "A host's imports are a list, each a module's name or an import, as { module: 'Home' }", {});
+        }
+
+        const imports = supplied.map(item => {
+            const entry = typeof item === 'string' ? { module: item } : item;
+
+            Imports.validateImport(entry, message => {
+                throw NexoErrors.structure('NEXO2008', `${message}, and the host supplies ${Imports.#describe(item)}`, {});
+            });
+
+            return Object.freeze(Object.fromEntries(IMPORT_KEYS.filter(key => entry[key] !== undefined).map(key => [key, entry[key]])));
+        });
+        const conflict = Imports.findConflict(imports);
+
+        if (conflict !== null) {
+            throw NexoErrors.structure('NEXO2008', Imports.describeConflict(conflict), {});
+        }
+
+        return Imports.mergeImports(imports);
+    }
+
+    /**
+     * Checks one import's shape, calling `fail` with why it breaks it: an object holding a module, an identifier other than Nexo's, a type where it imports one and an alias only where it differs from the local name the
+     * import gives without one, each an identifier.
+     */
+    static validateImport(entry, fail) {
+        if (entry === null || typeof entry !== 'object' || Array.isArray(entry) || Object.keys(entry).some(key => !IMPORT_KEYS.includes(key))) {
+            fail("An import holds its module, its type where it imports one, and its alias where it gives a local name other than its own");
+        }
+
+        if (!Names.isIdentifier(entry.module)) {
+            fail("An import's module is a registered module's name, a letter followed by letters and digits");
+        }
+
+        if (entry.module === Names.nexoModuleName) {
+            fail("Nexo's own vocabulary is always available, so no script imports it or one of its types");
+        }
+
+        if (entry.type !== undefined && !Names.isIdentifier(entry.type)) {
+            fail("An import's type is the local name of a type its module declares, a letter followed by letters and digits");
+        }
+
+        if (entry.alias !== undefined && !Names.isIdentifier(entry.alias)) {
+            fail("An import's alias is a local name, a letter followed by letters and digits");
+        }
+
+        if (entry.alias !== undefined && entry.alias === (entry.type ?? entry.module)) {
+            fail(`'${entry.alias}' is the local name the import gives without an alias, so it holds none`);
+        }
+    }
+
+    /** Why two imports conflict: the local name they share, and each as text writes it. */
+    static describeConflict([one, other]) {
+        return `'${Imports.localNameOf(one)}' is the local name both '${Imports.quote(one)}' and '${Imports.quote(other)}' give, to different declarations; give one of them an alias of its own`;
+    }
+
+    /** An item a host supplied, as a message quotes it. */
+    static #describe(item) {
+        return typeof item === 'string' ? `'${item}'` : JSON.stringify(item) ?? String(item);
+    }
+
+    /** The order of two local names, by their characters' code units, so every reader orders a definition's imports alike. */
+    static #compareLocalNames(one, other) {
+        return one < other ? -1 : one > other ? 1 : 0;
+    }
+}

package/src/language/Index.mjs

@@ -0,0 +1,29 @@
+/**
+ * Index — a position counted from a list's end, `^n`: its offset, a nonnegative safe integer, `^1` the last item and `^0` the end past it
+ */
+
+export class Index {
+    /** How far from the end the position stands. */
+    #offset;
+
+    /** @param {number} offset A nonnegative safe integer, which its expression's evaluation checked. */
+    constructor(offset) {
+        this.#offset = offset;
+        Object.freeze(this);
+    }
+
+    /** How far from the end the position stands. */
+    get offset() {
+        return this.#offset;
+    }
+
+    /** The offset from the start the index stands at within a list of the length: the length less its offset, which is negative for an index before the start. */
+    resolveIn(length) {
+        return length - this.#offset;
+    }
+
+    /** The index as a script writes it. */
+    toString() {
+        return `^${this.#offset}`;
+    }
+}