@lionweb/core 0.7.0-beta.2 → 0.7.0-beta.21

package/src/m3/lioncore.ts

@@ -0,0 +1,139 @@
+import { currentReleaseVersion } from "../version.js"
+import { builtinClassifiers, builtinPrimitives } from "./builtins.js"
+import { LanguageFactory } from "./factory.js"
+
+const lioncoreKey = "LionCore-M3"
+
+const factory = new LanguageFactory(
+    "LionCore_M3",
+    currentReleaseVersion,
+    (...names) => "-id-" + (names.length === 1 ? lioncoreKey : names.slice(1).join("-")),
+    (...names) => names.slice(1).join("-")
+)
+/*
+ * ID: `-id-${key}`
+ * key: qualified name _without_ "LionCore_M3", dash-separated
+ */
+
+/**
+ * Definition of LionCore in terms of itself.
+ */
+export const lioncore = factory.language.havingKey("LionCore-M3")
+
+const { inamed } = builtinClassifiers
+const { booleanDataType, stringDataType } = builtinPrimitives
+
+const ikeyed = factory.interface("IKeyed").extending(inamed)
+
+const ikeyed_key = factory.property(ikeyed, "key").ofType(stringDataType)
+
+const feature = factory.concept("Feature", true).implementing(ikeyed)
+
+const feature_optional = factory.property(feature, "optional").ofType(booleanDataType)
+
+const property = factory.concept("Property", false, feature)
+
+const property_type = factory.reference(property, "type")
+
+const link = factory.concept("Link", true, feature)
+
+const link_multiple = factory.property(link, "multiple").ofType(booleanDataType)
+
+const link_type = factory.reference(link, "type")
+
+const containment = factory.concept("Containment", false, link)
+
+const reference = factory.concept("Reference", false, link)
+
+const languageEntity = factory.concept("LanguageEntity", true).implementing(ikeyed)
+
+const classifier = factory.concept("Classifier", true, languageEntity)
+
+const classifier_features = factory.containment(classifier, "features").isOptional().isMultiple().ofType(feature)
+
+link_type.ofType(classifier)
+
+const annotation = factory.concept("Annotation", false, classifier)
+
+const annotation_annotates = factory.reference(annotation, "annotates").isOptional().ofType(classifier)
+
+const annotation_extends = factory.reference(annotation, "extends").isOptional().ofType(annotation)
+
+const annotation_implements = factory.reference(annotation, "implements").isMultiple().isOptional()
+
+const concept = factory.concept("Concept", false, classifier)
+
+const concept_abstract = factory.property(concept, "abstract").ofType(booleanDataType)
+
+const concept_partition = factory.property(concept, "partition").ofType(booleanDataType)
+
+const concept_extends = factory.reference(concept, "extends").isOptional().ofType(concept)
+
+const concept_implements = factory.reference(concept, "implements").isOptional().isMultiple()
+
+const interface_ = factory.concept("Interface", false, classifier)
+
+const interface_extends = factory.reference(interface_, "extends").isOptional().isMultiple().ofType(interface_)
+
+annotation_implements.ofType(interface_)
+concept_implements.ofType(interface_)
+
+const dataType = factory.concept("DataType", true, languageEntity)
+
+property_type.ofType(dataType)
+
+const primitiveType = factory.concept("PrimitiveType", false, dataType)
+
+const enumeration = factory.concept("Enumeration", false, dataType)
+
+const enumeration_literals = factory.containment(enumeration, "literals").isMultiple().isOptional()
+
+const enumerationLiteral = factory.concept("EnumerationLiteral", false).implementing(ikeyed)
+
+enumeration_literals.ofType(enumerationLiteral)
+
+const language = factory.concept("Language", false).implementing(ikeyed).isPartition()
+
+const language_version = factory.property(language, "version").ofType(stringDataType)
+
+const language_entities = factory.containment(language, "entities").isOptional().isMultiple().ofType(languageEntity)
+
+const language_dependsOn = factory.reference(language, "dependsOn").isOptional().isMultiple().ofType(language)
+
+export const metaConcepts = {
+    annotation,
+    classifier,
+    concept,
+    interface: interface_,
+    containment,
+    enumeration,
+    enumerationLiteral,
+    ikeyed,
+    language,
+    primitiveType,
+    property,
+    reference
+}
+
+export const metaFeatures = {
+    annotation_annotates,
+    annotation_extends,
+    annotation_implements,
+    classifier_features,
+    concept_abstract,
+    concept_partition,
+    concept_extends,
+    concept_implements,
+    interface_extends,
+    enumeration_literals,
+    feature_optional,
+    ikeyed_key,
+    language_dependsOn,
+    language_entities,
+    language_version,
+    link_multiple,
+    link_type,
+    property_type
+}
+
+export { lioncoreKey }

package/src/m3/reference-checker.ts

@@ -0,0 +1,38 @@
+import { SingleRef, unresolved } from "../references.js"
+import { flatMap, qualifiedNameOf } from "./functions.js"
+import { Concept, Containment, Language, Property, Reference } from "./types.js"
+
+
+/**
+ * Checks whether the metamodel of the given language contains unresolved references.
+ */
+export const checkReferences = (language: Language): string[] =>
+    flatMap(
+        language,
+        (thing) => {
+
+            const locations: string[] = []
+            const check = (ref: SingleRef<unknown>, location: string) => {
+                if (ref === unresolved) {
+                    locations.push(location)
+                }
+            }
+
+            if (thing instanceof Concept) {
+                check(thing.extends, `<Concept>${qualifiedNameOf(thing)}#extends`)
+            }
+            if (thing instanceof Containment) {
+                check(thing.type, `<Containment>${qualifiedNameOf(thing)}#type`)
+            }
+            if (thing instanceof Property) {
+                check(thing.type, `<Property>${qualifiedNameOf(thing)}#type`)
+            }
+            if (thing instanceof Reference) {
+                check(thing.type, `<Reference>${qualifiedNameOf(thing)}#type`)
+            }
+
+            return locations
+        }
+    )
+// TODO (#8)  make this generic, parametrized by a {@link Metamodel}
+

package/src/m3/serializer.ts

@@ -0,0 +1,13 @@
+import { LionWebJsonChunk } from "@lionweb/json"
+import { nodeSerializer } from "../serializer.js"
+import { lioncoreReader } from "./facade.js"
+import { Language } from "./types.js"
+
+
+/**
+ * Serializes languages (i.e., instances of the LionCore metametamodel, using {@link M3Concept these type definitions})
+ * into the LionWeb serialization JSON format.
+ */
+export const serializeLanguages = (...languages: Language[]): LionWebJsonChunk =>
+    nodeSerializer(lioncoreReader)(languages)
+

package/src/m3/symbol-table.ts

@@ -0,0 +1,125 @@
+import { LionWebJsonMetaPointer, LionWebKey } from "@lionweb/json"
+import { lazyMapGet } from "@lionweb/ts-utils"
+import { allFeaturesOf } from "./functions.js"
+import { Classifier, Feature, Language, LanguageEntity } from "./types.js"
+
+
+/**
+ * Interface for objects that can look up within languages, based on given {@link LionWebJsonMetaPointer meta pointers}.
+ * This is meant to be able to properly encapsulate performance optimizations, also outside of the context
+ * of deserialization.
+ */
+interface SymbolTable {
+
+    /**
+     * Looks up the {@link Language}, as pointed to by the given language key and version.
+     */
+    languageMatching(key: LionWebKey, version: string): Language | undefined
+
+    /**
+     * Looks up the {@link LanguageEntity}, as pointed to by the given {@link LionWebJsonMetaPointer},
+     * or {@code undefined} if it couldn't be found.
+     */
+    entityMatching(entityMetaPointer: LionWebJsonMetaPointer): LanguageEntity | undefined
+
+    /**
+     * Looks up the {@link Feature}, as pointed to by the {@link LionWebJsonMetaPointer} given second,
+     * as a feature of the {@link Classifier}, as pointed to by the {@link LionWebJsonMetaPointer} given first,
+     * or {@code undefined} it it couldn't be found.
+     * *Note* that the {@code language} and {@code version} values of both {@link LionWebJsonMetaPointer}-typed arguments should coincide,
+     * although this is typically not checked!
+     */
+    featureMatching(entityMetaPointer: LionWebJsonMetaPointer, featureMetaPointer: LionWebJsonMetaPointer): Feature | undefined
+
+}
+
+
+type EntityInfo = {
+    entity: LanguageEntity
+    allFeatures: Feature[]                                      // === [] if entity is not a Classifier
+    featureKey2feature: { [featureKey: LionWebKey]: Feature }   // populated through memoisation
+}
+
+
+/**
+ * A {@link SymbolTable} implementation that *memoises* the items it has looked up.
+ * This helps with performance, because otherwise lookup might be linear in the (max.) number of languages,
+ * entities in a language, features in classifiers — taking inheritance into account.
+ */
+class MemoisingSymbolTable implements SymbolTable {
+
+    private readonly languages: Language[]
+
+    constructor(languages: Language[]) {
+        this.languages = languages
+    }
+
+    private readonly languageKey2version2language: { [languageKey: LionWebKey]: { [version: string]: Language } } = {}
+
+    languageMatching = (languageKey: LionWebKey, version: string): Language | undefined =>
+        lazyMapGet(
+            lazyMapGet(this.languageKey2version2language, languageKey, () => ({})),
+            version,
+            () => this.languages.find((language) =>
+                   language.key === languageKey
+                && language.version === version
+            )
+        )
+
+
+    private readonly languageKey2version2entityKey2entityInfo: { [languageKey: LionWebKey]: { [version: string]: { [entityKey: LionWebKey]: (EntityInfo | undefined) } } } = {}
+
+    private entityInfoMatching = (entityMetaPointer: LionWebJsonMetaPointer): undefined | EntityInfo =>
+        lazyMapGet(
+            lazyMapGet(
+                lazyMapGet(this.languageKey2version2entityKey2entityInfo, entityMetaPointer.language, () => ({})),
+                entityMetaPointer.version,
+                () => ({})
+            ),
+            entityMetaPointer.key,
+            () => {
+                const entity = this.languageMatching(entityMetaPointer.language, entityMetaPointer.version)
+                    ?.entities
+                    .find((entity) => entity.key === entityMetaPointer.key)
+                return entity === undefined
+                    ? undefined
+                    : {
+                        entity,
+                        allFeatures: entity instanceof Classifier ? allFeaturesOf(entity) : [], featureKey2feature: {}
+                }
+            }
+        )
+
+    entityMatching = (entityMetaPointer: LionWebJsonMetaPointer): LanguageEntity | undefined =>
+        this.entityInfoMatching(entityMetaPointer)?.entity
+
+    /**
+     * Looks up the {@link LanguageEntity}, as pointed to by the given {@link LionWebJsonMetaPointer},
+     * and @returns all its {@link Feature features} or an empty array if it couldn't be found.
+     */
+    allFeaturesOfEntityMatching = (entityMetaPointer: LionWebJsonMetaPointer): Feature[] =>
+        this.entityInfoMatching(entityMetaPointer)?.allFeatures ?? []
+
+    featureMatching = (classifierMetaPointer: LionWebJsonMetaPointer, featureMetaPointer: LionWebJsonMetaPointer): Feature | undefined => {
+        const entityInfo = this.entityInfoMatching(classifierMetaPointer)
+        if (entityInfo === undefined || !(entityInfo.entity instanceof Classifier)) {
+            return undefined
+        }
+        return lazyMapGet(
+            entityInfo.featureKey2feature,
+            featureMetaPointer.key,
+            () => entityInfo.allFeatures.find((feature) => feature.key === featureMetaPointer.key)
+        )
+    }
+
+}
+
+
+export type {
+    SymbolTable
+}
+
+export {
+    MemoisingSymbolTable
+}
+

package/src/m3/types.ts

@@ -0,0 +1,325 @@
+/**
+ * TypeScript type definitions for the `LionCore` M3 (=meta-meta) model.
+ * A LionWeb language (at the M2 meta level) can be represented as an instance of the {@link Language} type.
+ */
+
+import { LionWebId, LionWebJsonMetaPointer, LionWebKey } from "@lionweb/json"
+import { ResolveInfoDeducer } from "../reading.js"
+import { MultiRef, SingleRef, unresolved } from "../references.js"
+import { Node } from "../types.js"
+
+
+/**
+ * The key of the LionCore language containing the built-ins.
+ * (It's defined here because of instantiation order.)
+ */
+const lioncoreBuiltinsKey = "LionCore-builtins"
+
+
+// Types appear roughly in the order of top-to-down+left-to-right in the diagram at:
+//      https://lionweb-io.github.io/specification/metametamodel/metametamodel.html#_overview
+
+
+interface INamed {
+    name: string
+}
+
+const isINamed = (node: object): node is INamed =>
+    "name" in node && typeof node.name === "string"
+
+const simpleNameDeducer: ResolveInfoDeducer<Node> =
+    (node: Node) => isINamed(node) ? node.name : undefined
+
+
+interface IKeyed extends INamed {
+    key: LionWebId
+}
+
+
+/**
+ * An interface with one method to return a meta type,
+ * independent of the class's name obtained through `<node>.constructor.name`,
+ * which may be brittle when using bundlers.
+ */
+interface IMetaTyped {
+    metaType(): string
+}
+
+/**
+ * Abstract base class for nodes in an LionCore instance,
+ * providing an ID, a key, and the containment hierarchy.
+ */
+abstract class M3Node implements IKeyed, IMetaTyped {
+    metaType(): string {
+        throw new Error("#metaType() not implemented")
+    }
+    parent?: M3Node
+        /*
+         * Note: every parent in an M2 (i.e., a Language, Concept, Interface, Enumeration) implements IKeyed.
+         * Because that's just an interface and is implemented by {@link M3Node},
+         * we can type parent as M3Node?.
+         */
+    readonly id: LionWebId
+    name: string
+    key: LionWebId
+    protected constructor(id: LionWebId, name: string, key: LionWebId, parent?: M3Node) {
+        this.id = id
+        this.name = name
+        this.key = key
+        this.parent = parent
+    }
+    havingKey(key: LionWebId) {
+        this.key = key
+        return this
+    }
+    annotations: Node[] = [] // (containment)
+}
+
+abstract class Feature extends M3Node {
+    optional /*: boolean */ = false
+    // TODO  look at order of constructors' arguments!
+    constructor(classifier: Classifier, name: string, key: LionWebKey, id: LionWebId) {
+        super(id, name, key, classifier)
+    }
+    isOptional() {
+        this.optional = true
+        return this
+    }
+    get classifier(): Classifier {
+        return this.parent! as Classifier
+    }
+}
+
+class Property extends Feature {
+    metaType(): string {
+        return "Property"
+    }
+    type: SingleRef<DataType> = unresolved   // (reference)
+    ofType(type: DataType): Property {
+        this.type = type
+        return this
+    }
+}
+
+abstract class Link extends Feature {
+    multiple /*: boolean */ = false
+    type: SingleRef<Classifier> = unresolved   // (reference)
+    isMultiple() {
+        this.multiple = true
+        return this
+    }
+    ofType(type: Classifier) {
+        this.type = type
+        return this
+    }
+}
+
+class Containment extends Link {
+    metaType(): string {
+        return "Containment"
+    }
+}
+
+class Reference extends Link {
+    metaType(): string {
+        return "Reference"
+    }
+}
+
+abstract class LanguageEntity extends M3Node {
+    constructor(language: Language, name: string, key: LionWebId, id: LionWebId) {
+        super(id, name, key, language)
+    }
+    get language(): Language {
+        return this.parent! as Language
+    }
+}
+
+abstract class Classifier extends LanguageEntity {
+    features: Feature[] = [] // (containment)
+    havingFeatures(...features: Feature[]) {
+        this.features.push(...features.filter((feature) => this.features.indexOf(feature) < 0))
+        return this
+    }
+    metaPointer(): LionWebJsonMetaPointer {
+        const {language} = this
+        return {
+            language: language.key,
+            version: language.version,
+            key: this.key
+        }
+    }
+}
+
+class Concept extends Classifier {
+    metaType(): string {
+        return "Concept"
+    }
+    abstract: boolean
+    partition: boolean
+    extends?: SingleRef<Concept>    // (reference)
+    implements: MultiRef<Interface> = []  // (reference)
+    constructor(language: Language, name: string, key: LionWebKey, id: LionWebId, abstract: boolean, extends_?: SingleRef<Concept>) {
+        super(language, name, key, id)
+        this.abstract = abstract
+        this.extends = extends_
+        this.partition = false
+    }
+    implementing(...interfaces: Interface[]): Concept {
+        // TODO  check actual types of interfaces, or use type shapes/interfaces
+        this.implements.push(...interfaces)
+        return this
+    }
+    isPartition(): Concept {
+        this.partition = true
+        return this
+    }
+}
+
+class Annotation extends Classifier {
+    metaType(): string {
+        return "Annotation"
+    }
+    extends?: SingleRef<Annotation> // (reference)
+    implements: MultiRef<Interface> = [] // (reference)
+    annotates: SingleRef<Classifier> = unresolved   // (reference)
+    constructor(language: Language, name: string, key: LionWebKey, id: LionWebId, extends_?: SingleRef<Annotation>) {
+        super(language, name, key, id)
+        this.extends = extends_
+    }
+    implementing(...interfaces: Interface[]): Annotation {
+        // TODO  check actual types of interfaces, or use type shapes/interfaces
+        this.implements.push(...interfaces)
+        return this
+    }
+    annotating(classifier: Classifier): Annotation {
+        this.annotates = classifier
+        return this
+    }
+}
+
+class Interface extends Classifier {
+    metaType(): string {
+        return "Interface"
+    }
+    extends: MultiRef<Interface> = []    // (reference)
+    extending(...interfaces: Interface[]): Interface {
+        // TODO  check actual types of interfaces, or use type shapes/interfaces
+        this.extends.push(...interfaces)
+        return this
+    }
+}
+
+abstract class DataType extends LanguageEntity {}
+
+/**
+ * Misspelled alias of {@link DataType}, kept for backward compatibility, and to be deprecated and removed later.
+ */
+abstract class Datatype extends DataType {}
+
+class PrimitiveType extends DataType {
+    metaType(): string {
+        return "PrimitiveType"
+    }
+}
+
+class Enumeration extends DataType {
+    metaType(): string {
+        return "Enumeration"
+    }
+    literals: EnumerationLiteral[] = [] // (containment)
+    havingLiterals(...literals: EnumerationLiteral[]) {
+        this.literals.push(...literals.filter((literal) => this.literals.indexOf(literal) < 0))
+        return this
+    }
+}
+
+class EnumerationLiteral extends M3Node {
+    metaType(): string {
+        return "EnumerationLiteral"
+    }
+    constructor(enumeration: Enumeration, name: string, key: LionWebKey, id: LionWebId) {
+        super(id, name, key, enumeration)
+    }
+    get enumeration(): Enumeration {
+        return this.parent! as Enumeration
+    }
+}
+
+class Language extends M3Node {
+    metaType(): string {
+        return "Language"
+    }
+    version: string
+    entities: LanguageEntity[] = []   // (containment)
+    dependsOn: MultiRef<Language> = []  // special (!) reference
+        // (!) special because deserializer needs to be aware of where to get the instance from
+    constructor(name: string, version: string, id: LionWebId, key: LionWebKey) {
+        super(id, name, key)
+        this.version = version
+    }
+    havingEntities(...entities: LanguageEntity[]): Language {
+        this.entities.push(...entities.filter((entity) => this.entities.indexOf(entity) < 0))
+        return this
+    }
+    dependingOn(...languages: Language[]): Language {
+        this.dependsOn.push(
+            ...languages
+                .filter((language) => language.key !== lioncoreBuiltinsKey)
+        )
+        return this
+    }
+    equals(that: Language): boolean {
+        return this.key === that.key && this.version === that.version
+    }
+}
+
+
+/**
+ * Sum type of all LionCore type definitions whose meta-type is a concrete (thus: instantiable) Concept.
+ * All the classes in this sum type extend (from) {@link M3Node},
+ * so they also implement {@link INamed} and {@link IKeyed}.
+ */
+type M3Concept =
+    | Annotation
+    | Concept
+    | Containment
+    | Enumeration
+    | EnumerationLiteral
+    | Interface
+    | Language
+    | PrimitiveType
+    | Property
+    | Reference
+
+
+export {
+    Annotation,
+    Classifier,
+    Concept,
+    Containment,
+    DataType,
+    Datatype,
+    Enumeration,
+    EnumerationLiteral,
+    Feature,
+    Interface,
+    Language,
+    LanguageEntity,
+    Link,
+    PrimitiveType,
+    Property,
+    Reference,
+    isINamed,
+    lioncoreBuiltinsKey,
+    simpleNameDeducer
+}
+
+export type {
+    IKeyed,
+    IMetaTyped,
+    INamed,
+    M3Concept,
+    M3Node
+}
+

package/src/reading.ts

@@ -0,0 +1,55 @@
+import { Classifier, Enumeration, EnumerationLiteral, Feature } from "./m3/index.js"
+import { Node } from "./types.js"
+
+
+/**
+ * Type def. for functions that deduce the {@link Classifier classifier} of a given {@link Node node}.
+ */
+export type ClassifierDeducer<NT extends Node> = (node: NT) => Classifier
+
+/**
+ * Type def. for functions that deduce the string value of the `resolveInfo` field of a
+ * {@link LionWebJsonReferenceTarget serialized reference target}, or  {@code undefined}
+ * to indicate that no `resolveInfo` could be derived.
+ */
+export type ResolveInfoDeducer<NT extends Node> = (node: NT) => string | undefined
+
+/**
+ * An interface that's used to parametrize generic serialization of
+ * (in-memory) nodes of the given type (parameter).
+ * Implementations of these interfaces {w|c}ould be:
+ *  - specific to LionCore (so to match m3/types.ts)
+ *  - generic to serialize {@link DynamicNode dynamic nodes}
+ */
+export interface Reader<NT extends Node> {
+
+    /**
+     * @return The {@link Concept concept} of the given node
+     */
+    classifierOf: ClassifierDeducer<NT>
+
+    /**
+     * @return The value of the given {@link Feature feature} on the given node.
+     */
+    getFeatureValue: (node: NT, feature: Feature) => unknown
+// TODO  split to getPropertyValue, &c.?
+
+    /**
+     * @return The {@link EnumerationLiteral} corresponding to
+     * the given {@link Enumeration} and the runtime encoding of a literal of it,
+     */
+    enumerationLiteralFrom: (encoding: unknown, enumeration: Enumeration) => EnumerationLiteral | null
+
+    /**
+     * @return The string value of the `resolveInfo` field of a {@link LionWebJsonReferenceTarget serialized reference target},
+     * or {@code undefined} to indicate that no `resolveInfo` could be derived.
+     */
+    resolveInfoFor?: ResolveInfoDeducer<NT>
+
+}
+
+/**
+ * Alias for {@link Reader}, kept for backward compatibility, and to be deprecated and removed later.
+ */
+export interface ExtractionFacade<NT extends Node> extends Reader<NT> {}
+