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

package/src/m3/factory.ts

@@ -0,0 +1,98 @@
+import { StringsMapper } from "@lionweb/ts-utils"
+import { SingleRef } from "../references.js"
+import {
+    Annotation,
+    Classifier,
+    Concept,
+    Containment,
+    Enumeration,
+    EnumerationLiteral,
+    Interface,
+    Language,
+    PrimitiveType,
+    Property,
+    Reference
+} from "./types.js"
+
+
+/**
+ * A factory that produces a {@link Language} instance,
+ * as well as {@link LanguageEntity entities} contained by that instance
+ * and {@link Feature features} of {@link Classifier classifiers}
+ * and {@link EnumerationLiteral enumeration literals} of {@link Enumeration enumerations}.
+ *
+ * The factory methods take care of proper containment.
+ * *Note:* also calling `havingEntities`, `havingFeatures`, and `havingLiterals` doesn't produce duplicates.
+ * (This is to stay backward compatible.)
+ */
+export class LanguageFactory {
+
+    readonly id: StringsMapper
+    readonly key: StringsMapper
+    readonly language: Language
+
+    constructor(name: string, version: string, id: StringsMapper, key: StringsMapper) {
+        this.id = id
+        this.key = key
+        this.language = new Language(name, version, this.id(name), this.key(name))
+    }
+
+
+    annotation(name: string, extends_?: SingleRef<Annotation>): Annotation {
+        const annotation = new Annotation(this.language, name, this.key(this.language.name, name), this.id(this.language.name, name), extends_)
+        this.language.havingEntities(annotation)
+        return annotation
+    }
+
+    concept(name: string, abstract: boolean, extends_?: SingleRef<Concept>): Concept {
+        const concept = new Concept(this.language, name, this.key(this.language.name, name), this.id(this.language.name, name), abstract, extends_)
+        this.language.havingEntities(concept)
+        return concept
+    }
+
+    interface(name: string): Interface {
+        const intface = new Interface(this.language, name, this.key(this.language.name, name), this.id(this.language.name, name))
+        this.language.havingEntities(intface)
+        return intface
+    }
+
+    enumeration(name: string): Enumeration {
+        const enumeration = new Enumeration(this.language, name, this.key(this.language.name, name), this.id(this.language.name, name))
+        this.language.havingEntities(enumeration)
+        return enumeration
+    }
+
+    primitiveType(name: string): PrimitiveType {
+        const primitiveType = new PrimitiveType(this.language, name, this.key(this.language.name, name), this.id(this.language.name, name))
+        this.language.havingEntities(primitiveType)
+        return primitiveType
+    }
+
+
+    containment(classifier: Classifier, name: string): Containment {
+        const containment = new Containment(classifier, name, this.key(this.language.name, classifier.name, name), this.id(this.language.name, classifier.name, name))
+        classifier.havingFeatures(containment)
+        return containment
+    }
+
+    property(classifier: Classifier, name: string): Property {
+        const property = new Property(classifier, name, this.key(this.language.name, classifier.name, name), this.id(this.language.name, classifier.name, name))
+        classifier.havingFeatures(property)
+        return property
+    }
+
+    reference(classifier: Classifier, name: string): Reference {
+        const reference = new Reference(classifier, name, this.key(this.language.name, classifier.name, name), this.id(this.language.name, classifier.name, name))
+        classifier.havingFeatures(reference)
+        return reference
+    }
+
+
+    enumerationLiteral(enumeration: Enumeration, name: string): EnumerationLiteral {
+        const enumerationLiteral = new EnumerationLiteral(enumeration, name, this.key(this.language.name, enumeration.name, name), this.id(this.language.name, enumeration.name, name))
+        enumeration.havingLiterals(enumerationLiteral)
+        return enumerationLiteral
+    }
+
+}
+

package/src/m3/feature-resolvers.ts

@@ -0,0 +1,55 @@
+import { LionWebJsonMetaPointer } from "@lionweb/json"
+
+import { Classifier, Containment, Feature, Language, Property, Reference } from "./types.js"
+import { MemoisingSymbolTable } from "./symbol-table.js"
+
+
+/**
+ * Type def. for functions that resolve a {@link Feature feature} of the indicated sub-type
+ * from a feature's and a classifier's meta-pointers,
+ * throwing an {@link Error error} when the feature couldn't be resolved,
+ * or it isn't of the expected sub-type.
+ */
+export type FeatureResolver<FT extends Feature> = (metaPointer: LionWebJsonMetaPointer, classifier: Classifier) => FT
+
+/**
+ * Type def. for an object containing {@link FeatureResolver resolvers} for
+ * {@link Property properties}, {@link Containmnent containments}, and {@link Reference references}.
+ */
+export type FeatureResolvers = {
+    resolvedPropertyFrom: FeatureResolver<Property>
+    resolvedContainmentFrom: FeatureResolver<Containment>
+    resolvedReferenceFrom: FeatureResolver<Reference>
+}
+
+/**
+ * @return an {@link FeatureResolvers object} for the given {@link Language languages}.
+ */
+export const featureResolversFor = (languages: Language[]): FeatureResolvers => {
+    const symbolTable = new MemoisingSymbolTable(languages)
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const featureResolverFor = <FT extends Feature>(featureClassConstructor: new (...args: any[]) => FT): FeatureResolver<FT> =>
+        (featureMetaPointer, classifier: Classifier) => {
+            const classifierMetaPointer = classifier.metaPointer()
+            const featureLocationMessage = () => `feature with meta-pointer ${JSON.stringify(featureMetaPointer)} on classifier with meta-pointer ${JSON.stringify(classifierMetaPointer)}`
+            const feature = symbolTable.featureMatching(classifierMetaPointer, featureMetaPointer)
+            if (feature === undefined) {
+                throw new Error(`couldn't resolve ${featureLocationMessage()}`)    // fail early <== unrecoverable
+            }
+            if (feature.constructor !== featureClassConstructor) {  // feature's type must match desired type *exactly* — cheaper to evaluate than "feature instanceof featureClassConstructor"
+                throw new Error(`${featureLocationMessage()} is not a ${featureClassConstructor.name} but a ${feature.constructor.name}`)    // fail early <== unrecoverable
+            }
+            /*
+             * We could make this function memoising as well, to avoid having to perform these checks every resolution.
+             * That memoisation would involve a 6-deep lookup, in the feature's meta-pointer + container's classifier meta-pointer.
+             * The checks seem cheap enough to not be problematic performance-wise, though.
+             */
+            return feature as FT    // valid <== feature.constructor === featureClassConstructor
+        }
+    return {
+        resolvedPropertyFrom: featureResolverFor(Property),
+        resolvedContainmentFrom: featureResolverFor(Containment),
+        resolvedReferenceFrom: featureResolverFor(Reference)
+    }
+}
+

package/src/m3/functions.ts

@@ -0,0 +1,379 @@
+/**
+ * Various functions on M3 models.
+ */
+
+
+import { LionWebId, LionWebKey } from "@lionweb/json"
+import { cycleWith, flatMapNonCyclingFollowing, sortByStringKey } from "@lionweb/ts-utils"
+import { containmentChain } from "../functions.js"
+import { ClassifierDeducer } from "../reading.js"
+import { isRef, unresolved } from "../references.js"
+import { Node } from "../types.js"
+import {
+    Annotation,
+    Classifier,
+    Concept,
+    Containment,
+    DataType,
+    Enumeration,
+    Feature,
+    IKeyed,
+    IMetaTyped,
+    INamed,
+    Interface,
+    isINamed,
+    Language,
+    LanguageEntity,
+    Link,
+    M3Concept,
+    Property,
+    Reference
+} from "./types.js"
+
+
+/**
+ * @return The type of the given {@link Feature}
+ */
+const type = (feature: Feature): Classifier | DataType | typeof unresolved =>
+    (feature as (Link | Property)).type
+
+
+const isProperty = (feature: Feature): feature is Property =>
+    feature instanceof Property
+
+const isContainment = (feature: Feature): feature is Containment =>
+    feature instanceof Containment
+
+const isReference = (feature: Feature): feature is Reference =>
+    feature instanceof Reference
+
+const isMultiple = (feature: Feature): feature is Link =>
+    feature instanceof Link && feature.multiple
+
+
+/**
+ * The (names of the) metatypes of a feature.
+ */
+type FeatureMetaType =
+    | "Containment"
+    | "Property"
+    | "Reference"
+
+/**
+ * @return the (name of the) metatype of the given {@link Feature feature}.
+ */
+const featureMetaType = (feature: Feature): FeatureMetaType => {
+    if (feature instanceof Containment) {
+        return "Containment"
+    }
+    if (feature instanceof Property) {
+        return "Property"
+    }
+    if (feature instanceof Reference) {
+        return "Reference"
+    }
+    throw new Error(`unhandled Feature sub type ${feature.constructor.name}`)
+}
+
+
+/**
+ * Determines whether a {@link Feature feature} is "relational",
+ * i.e. it's a {@link Link containment or reference}.
+ */
+const isRelational = (feature: Feature): feature is Link =>
+    feature instanceof Link
+
+/**
+ * @return the relations among the given {@link Feature features}.
+ */
+const relations = (features: Feature[]): Link[] =>
+    features.filter(isRelational)
+
+/**
+ * @return the non-relations among the given {@link Feature features}.
+ */
+const nonRelationalFeatures = (features: Feature[]): Feature[] =>
+    features.filter((feature) => !isRelational(feature))
+
+
+/**
+ * @return the relations of the given {@link LanguageEntity language element}.
+ */
+const relationsOf = (element: LanguageEntity): Link[] =>
+    element instanceof Classifier
+        ? relations(element.features)
+        : []
+
+
+/**
+ * @return The "things", i.e. {@link M3Concept}s, directly contained by the given "thing".
+ *  These can be:
+ *  {@link LanguageEntity language entities}, {@link Feature features}, and {@link EnumerationLiteral enumeration literals}
+ *  (and all their sub types).
+ */
+const directlyContaineds = (thing: M3Concept): M3Concept[] => {
+    if (thing instanceof Language) {
+        return thing.entities
+    }
+    if (thing instanceof Classifier) {
+        return thing.features as M3Concept[]    // (cast is necessary because of presence of Feature#classifier getter...?)
+    }
+    if (thing instanceof Enumeration) {
+        return thing.literals
+    }
+    return []
+}
+
+
+/**
+ * @return All {@link M3Concept nodes} contained in this {@link Language language},
+ * including the language itself.
+ */
+const allContaineds = (language: Language): M3Concept[] =>
+    [
+        language,
+        ...directlyContaineds(language),
+        ...directlyContaineds(language).flatMap(directlyContaineds)
+    ]
+
+
+/**
+ * Performs a depth-first tree traversal of a language, "flatMapping" the `map` function on every node.
+ * It avoids visiting nodes twice (to avoid potential infinite loops), but doesn't report cycles.
+ */
+const flatMap = <T>(language: Language, map: (t: M3Concept) => T[]): T[] =>
+    flatMapNonCyclingFollowing(map, directlyContaineds)(language)
+
+
+/**
+ * @return string the name of the given {@link INamed named thing}.
+ */
+const nameOf = <T extends INamed>({name}: T): string =>
+    name
+
+
+/**
+ * @return the given named things sorted by name
+ */
+export const nameSorted = <T extends INamed>(ts: T[]): T[] =>
+    sortByStringKey(ts, nameOf)
+
+
+/**
+ * @return the concatenation of the names of the given nodes using the given separator.
+ */
+const concatenateNamesOf = (separator: string, nodes: M3Concept[]): string =>
+    nodes
+        .filter(isINamed)
+        .map(nameOf)
+        .join(separator)
+    // !! slight overkill: every node in an M2 is an M3Concept, so IKeyed and INamed
+
+/**
+ * @return the qualified name of the given {@link INamed named thing}.
+ */
+const qualifiedNameOf = <T extends INamed & Node>(node: T, separator = "."): string =>
+    concatenateNamesOf(separator, containmentChain(node).reverse() as M3Concept[])
+
+
+/**
+ * @return the {@link INamed named things} in this {@link Language language}
+ *  (excluding the language itself)
+ */
+const namedsOf = (language: Language): M3Concept[] =>
+    allContaineds(language).filter(isINamed)
+
+
+/**
+ * @return the key of the given {@link INamed named thing}.
+ */
+const keyOf = <T extends IKeyed>({key}: T): LionWebKey =>
+    key
+
+
+type ConcreteClassifier = Concept | Annotation
+
+
+/**
+ * Determines whether the given {@link LanguageEntity metamodel element} is
+ * *concrete*, i.e. is instantiable.
+ */
+const isConcrete = (thing: LanguageEntity): thing is ConcreteClassifier =>
+    (thing instanceof Concept && !thing.abstract) || (thing instanceof Annotation)
+
+/**
+ * Determines whether the given {@link LanguageEntity metamodel element} is a {@link Concept concept}
+ * which is a partition.
+ */
+const isPartition = (thing: LanguageEntity): thing is Concept =>
+    thing instanceof Concept && thing.partition
+
+/**
+ * @return an array of {@link Classifier classifiers} that it **directly** inherits from.
+ */
+const inheritsDirectlyFrom = (classifier: Classifier): Classifier[] => {
+    if (classifier instanceof Concept || classifier instanceof Annotation) {
+        return [
+            ...(
+                isRef(classifier.extends)
+                    ? [classifier.extends as Classifier]
+                    : []
+            ),
+            ...classifier.implements
+        ]
+    }
+    if (classifier instanceof Interface) {
+        return classifier.extends
+    }
+    throw new Error(`classifier type ${typeof classifier} not handled`)
+}
+
+/**
+ * Alias for {@link inheritsDirectlyFrom}, kept for backward compatibility, and to be deprecated and removed later.
+ */
+const inheritsFrom = inheritsDirectlyFrom;
+
+/**
+ * @return an array that's either an inheritance cycle, or empty (meaning: no inheritance cycle).
+ */
+const inheritanceCycleWith = (classifier: Classifier) =>
+    cycleWith(classifier, inheritsDirectlyFrom)
+
+/**
+ * Alias for {@link inheritanceCycleWith}, kept for backward compatibility, and to be deprecated and removed later.
+ */
+const inheritedCycleWith = inheritanceCycleWith;
+
+/**
+ * @return *all* super types (through `extends` or `implements`) of the given {@link Classifier classifier}.
+ */
+const allSuperTypesOf = (classifier: Classifier): Classifier[] =>
+    flatMapNonCyclingFollowing(inheritsDirectlyFrom, inheritsDirectlyFrom)(classifier)
+
+
+/**
+ * @return *all* {@link Feature features} of the given {@link Classifier classifier},
+ * including the inherited ones.
+ */
+const allFeaturesOf = (classifier: Classifier): Feature[] =>
+    flatMapNonCyclingFollowing((ci) => ci.features, inheritsDirectlyFrom)(classifier)
+
+
+/**
+ * Determines whether the given {@link LanguageEntity language element} is an {@link Enumeration enumeration}.
+ */
+const isEnumeration = (element: LanguageEntity): element is Enumeration =>
+    element instanceof Enumeration
+
+
+/**
+ * @return a function that looks up a classifier from the given {@link Language language} by its ID.
+ */
+const idBasedClassifierDeducerFor = (language: Language) =>
+    (id: LionWebId) =>
+        language.entities.find((element) => element instanceof Classifier && element.id === id) as Classifier
+
+/**
+ * @return a function that looks up a classifier from the given {@link Language language} by its name.
+ */
+const nameBasedClassifierDeducerFor = (language: Language) =>
+    (name: string) =>
+        language.entities.find((element) => element instanceof Classifier && element.name === name) as Classifier
+
+
+/**
+ * @return a {@link ClassifierDeducer classifier deducer} that deduces the classifier of nodes by looking up
+ * the classifier in the given {@link Language language} by matching the node object's class name to classifiers' names.
+ * **Note** that this is not reliable when using bundlers who might minimize class names, and such.
+ */
+const classBasedClassifierDeducerFor = <NT extends Node>(language: Language): ClassifierDeducer<NT> =>
+    (node: NT) => nameBasedClassifierDeducerFor(language)(node.constructor.name)
+
+
+/**
+ * @return a {@link ClassifierDeducer classifier deducer} that deduces the classifier of nodes that implement {@link IMetaTyped}
+ * by looking up the classifier in the given {@link Language language} by matching the result of {@link IMetaTyped#metaType}
+ * to classifiers' names.
+ */
+const metaTypedBasedClassifierDeducerFor = <NT extends Node & IMetaTyped>(language: Language): ClassifierDeducer<NT> =>
+    (node: NT) => nameBasedClassifierDeducerFor(language)(node.metaType())
+
+
+/**
+ * @return all {@link Concept concepts} defined in the given {@link Language language}.
+ */
+const conceptsOf = (language: Language): Concept[] =>
+    language.entities.filter((entity) => entity instanceof Concept) as Concept[]
+
+
+const isInstantiableClassifier = (entity: LanguageEntity): boolean =>
+       entity instanceof Annotation
+    || (entity instanceof Concept && !entity.abstract)
+    // leaves out Interface and Concept { abstract: true }
+
+/**
+ * @return an array of all instantiable {@link Classifier classifiers} of the given {@link Language language}.
+ */
+const instantiableClassifiersOf = (language: Language): Classifier[] =>
+    language.entities.filter(isInstantiableClassifier) as Classifier[]
+
+
+/**
+ * @return whether the two given {@link Classifiers classifiers} are the same (/identical by meta-pointer).
+ */
+const areSameClassifiers = (left: Classifier, right: Classifier) =>
+    (left === right) || (
+        areSameLanguages(left.language, right.language) && left.key === right.key
+    )
+
+/**
+ * @return whether the two given {@link Language languages} are the same (/identical by meta-pointer).
+ */
+const areSameLanguages = (left: Language, right: Language) =>
+    (left === right) || (
+        left.key === right.key && left.version === right.version
+    )
+
+
+export {
+    allContaineds,
+    allFeaturesOf,
+    allSuperTypesOf,
+    areSameClassifiers,
+    areSameLanguages,
+    classBasedClassifierDeducerFor,
+    concatenateNamesOf,
+    conceptsOf,
+    containmentChain,
+    directlyContaineds,
+    featureMetaType,
+    flatMap,
+    idBasedClassifierDeducerFor,
+    inheritanceCycleWith,
+    inheritedCycleWith,
+    inheritsFrom,
+    inheritsDirectlyFrom,
+    instantiableClassifiersOf,
+    isConcrete,
+    isContainment,
+    isEnumeration,
+    isMultiple,
+    isPartition,
+    isProperty,
+    isReference,
+    keyOf,
+    metaTypedBasedClassifierDeducerFor,
+    nameBasedClassifierDeducerFor,
+    nameOf,
+    namedsOf,
+    nonRelationalFeatures,
+    relations,
+    relationsOf,
+    type,
+    qualifiedNameOf
+}
+
+export type {
+    FeatureMetaType
+}
+

package/src/m3/index.ts

@@ -0,0 +1,12 @@
+export * from "./builtins.js"
+export * from "./constraints.js"
+export * from "./deserializer.js"
+export * from "./facade.js"
+export * from "./factory.js"
+export * from "./feature-resolvers.js"
+export * from "./functions.js"
+export * from "./lioncore.js"
+export * from "./reference-checker.js"
+export * from "./serializer.js"
+export * from "./symbol-table.js"
+export * from "./types.js"

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 }