@lionweb/core 0.7.0-beta.18 → 0.7.0-beta.19

package/src/m3/builtins.ts

@@ -0,0 +1,170 @@
+import { asMinimalJsonString, StringsMapper } from "@lionweb/ts-utils"
+import { PropertyValueDeserializer } from "../deserializer.js"
+import { PropertyValueSerializer } from "../serializer.js"
+import { currentReleaseVersion } from "../version.js"
+import { LanguageFactory } from "./factory.js"
+import { Classifier, Concept, DataType, lioncoreBuiltinsKey, Property } from "./types.js"
+
+const lioncoreBuiltinsIdAndKeyGenerator: StringsMapper = (...names) => [lioncoreBuiltinsKey, ...names.slice(1)].join("-")
+
+const factory = new LanguageFactory(
+    "LionCore_builtins",
+    currentReleaseVersion,
+    lioncoreBuiltinsIdAndKeyGenerator,
+    lioncoreBuiltinsIdAndKeyGenerator
+)
+/*
+ * ID == key: `LionCore-builtins-${qualified name _without_ "LionCore-builtins", dash-separated}`
+ */
+
+/**
+ * Definition of a LionCore language that serves as a standard library of built-in primitive types.
+ */
+const lioncoreBuiltins = factory.language
+
+const stringDataType = factory.primitiveType("String")
+const booleanDataType = factory.primitiveType("Boolean")
+const integerDataType = factory.primitiveType("Integer")
+const jsonDataType = factory.primitiveType("JSON")
+
+const node = factory.concept("Node", true)
+
+const isBuiltinNodeConcept = (classifier: Classifier) =>
+    classifier instanceof Concept &&
+    classifier.language.key === lioncoreBuiltinsKey &&
+    classifier.language.version === currentReleaseVersion &&
+    classifier.key === builtinClassifiers.node.key &&
+    (classifier as Concept).abstract
+
+const inamed = factory.interface("INamed")
+
+const inamed_name = factory.property(inamed, "name").ofType(stringDataType)
+
+const builtinPrimitives = {
+    stringDataType,
+    booleanDataType,
+    integerDataType,
+    jsonDataType,
+    /**
+     * Misspelled alias of {@link stringDataType}, kept for backward compatibility, and to be deprecated and removed later.
+     */
+    stringDatatype: stringDataType,
+    /**
+     * Misspelled alias of {@link booleanDataType}, kept for backward compatibility, and to be deprecated and removed later.
+     */
+    booleanDatatype: booleanDataType,
+    /**
+     * Misspelled alias of {@link integerDataType}, kept for backward compatibility, and to be deprecated and removed later.
+     */
+    integerDatatype: integerDataType,
+    /**
+     * Misspelled alias of {@link jsonDataType}, kept for backward compatibility, and to be deprecated and removed later.
+     */
+    jsonDatatype: jsonDataType
+}
+
+const builtinClassifiers = {
+    node,
+    inamed
+}
+
+const builtinFeatures = {
+    inamed_name
+}
+
+/**
+ * Determines whether two data types should be structurally equal based on equality of: meta type, key, and language's key.
+ */
+const shouldBeIdentical = (left: DataType, right: DataType): boolean =>
+    left.key === right.key && left.language.key === right.language.key && left.metaType() === right.metaType()
+
+abstract class DataTypeRegister<T> {
+    private map = new Map<DataType, T>()
+
+    public register(dataType: DataType, t: T) {
+        this.map.set(dataType, t)
+    }
+
+    protected byType(targetDataType: DataType): T | undefined {
+        for (const [dataType, t] of this.map.entries()) {
+            if (shouldBeIdentical(targetDataType, dataType)) {
+                return t
+            }
+        }
+        return undefined
+    }
+}
+
+export class BuiltinPropertyValueDeserializer
+    extends DataTypeRegister<(value: string) => unknown>
+    implements PropertyValueDeserializer
+{
+    constructor() {
+        super()
+        this.register(stringDataType, value => value)
+        this.register(booleanDataType, value => JSON.parse(value))
+        this.register(integerDataType, value => Number(value))
+        this.register(jsonDataType, value => JSON.parse(value as string))
+    }
+
+    deserializeValue(value: string | undefined, property: Property): unknown | undefined {
+        if (value === undefined) {
+            if (property.optional) {
+                return undefined
+            }
+            throw new Error(`can't deserialize undefined as the value of required property "${property.name}" (on classifier "${property.classifier.name}" in language "${property.classifier.language.name}")`)
+        }
+        const { type } = property
+        if (type == null) {
+            throw new Error(`can't deserialize property "${property.name}" (on classifier "${property.classifier.name}" in language "${property.classifier.language.name}") with unspecified type`)
+        }
+        const specificDeserializer = this.byType(type)
+        if (specificDeserializer != undefined) {
+            return specificDeserializer(value)
+        } else {
+            throw new Error(`can't deserialize value of property "${property.name}" (on classifier "${property.classifier.name}" in language "${property.classifier.language.name}") of type "${type!.name}": ${value}`)
+        }
+    }
+}
+
+/**
+ * Misspelled alias of {@link BuiltinPropertyValueDeserializer}, kept for backward compatibility, and to be deprecated and removed later.
+ */
+export class DefaultPrimitiveTypeDeserializer extends BuiltinPropertyValueDeserializer {}
+
+
+export class BuiltinPropertyValueSerializer extends DataTypeRegister<(value: unknown) => string> implements PropertyValueSerializer {
+    constructor() {
+        super()
+        this.register(stringDataType, value => value as string)
+        this.register(booleanDataType, value => `${value as boolean}`)
+        this.register(integerDataType, value => `${value as number}`)
+        this.register(jsonDataType, value => asMinimalJsonString(value))
+    }
+
+    serializeValue(value: unknown | undefined, property: Property): string | null {
+        if (value === undefined) {
+            if (property.optional) {
+                return null
+            }
+            throw new Error(`can't serialize undefined as the value of required property "${property.name}" (on classifier "${property.classifier.name}" in language "${property.classifier.language.name}")`)
+        }
+        const { type } = property
+        if (type == null) {
+            throw new Error(`can't serialize property "${property.name}" (on classifier "${property.classifier.name}" in language "${property.classifier.language.name}") with unspecified type`)
+        }
+        const specificSerializer = this.byType(type)
+        if (specificSerializer != undefined) {
+            return specificSerializer(value)
+        } else {
+            throw new Error(`can't serialize value of property "${property.name}" (on classifier "${property.classifier.name}" in language "${property.classifier.language.name}") of type "${type!.name}": ${value}`)
+        }
+    }
+}
+
+/**
+ * Misspelled alias of {@link BuiltinPropertyValueSerializer}, kept for backward compatibility, and to be deprecated and removed later.
+ */
+export class DefaultPrimitiveTypeSerializer extends BuiltinPropertyValueSerializer {}
+
+export { builtinPrimitives, builtinClassifiers, builtinFeatures, isBuiltinNodeConcept, lioncoreBuiltins, shouldBeIdentical }

package/src/m3/constraints.ts

@@ -0,0 +1,109 @@
+import { duplicatesAmong } from "@lionweb/ts-utils"
+import { idOf } from "../functions.js"
+import { allContaineds, flatMap, inheritanceCycleWith, keyOf, namedsOf, qualifiedNameOf } from "./functions.js"
+import { Classifier, isINamed, Language, M3Concept } from "./types.js"
+
+
+/**
+ * Type definition for an issue corresponding
+ * to a violation of a constraint on a {@link M3Concept language object}.
+ */
+export type Issue = {
+    location: M3Concept
+    message: string
+    secondaries: M3Concept[]
+}
+// TODO  back this type with an M2
+
+
+const base64urlRegex = /^[A-Za-z0-9_-]+$/
+
+/**
+ * @return whether the given string is a valid identifier according to the LionWeb specification – see [here](https://github.com/LionWeb-io/specification/blob/main/2023.1/metametamodel/metametamodel.adoc#identifiers) for the relevant part.
+ * This is essentially whether the given string is a valid, non-empty [Base64url](https://en.wikipedia.org/wiki/Base64#Variants_summary_table) string.
+ */
+const isValidIdentifier = (str: string): boolean =>
+    base64urlRegex.test(str)
+
+
+/**
+ * Computes the {@link Issue issues} (i.e., constraint violations) for the given language.
+ * (This computation is resilient against e.g. inheritance cycles.)
+ */
+export const issuesLanguage = (language: Language): Issue[] =>
+    [
+        ...flatMap(
+            language,
+            (t) => {
+
+                const issues: Issue[] = []
+                const issue = (message: string, secondaries?: M3Concept[]): void => {
+                    issues.push({
+                        location: t,
+                        message,
+                        secondaries: secondaries ?? []
+                    })
+                }
+
+                // The id consists only of latin characters (upper/lowercase), numbers, underscores, and hyphens
+                const id = t.id.trim()
+                !isValidIdentifier(id) && issue(`An ID must consist only of latin characters (upper/lowercase), numbers, underscores, and hyphens`)
+
+                // The key consists only of latin characters (upper/lowercase), numbers, underscores, and hyphens
+                const key = t.key.trim()
+                !isValidIdentifier(key) && issue(`A KEY must consist only of latin characters (upper/lowercase), numbers, underscores, and hyphens`)
+
+                if(isINamed(t)) {
+                    const trimmedName = t.name.trim()
+                    // The name should be a non-empty string
+                    trimmedName.length === 0 && issue(`A ${t.constructor.name}'s name must not be empty`)
+
+                    // The name should not contain whitespace characters
+                    trimmedName.includes(" ") && issue(`A ${t.constructor.name}'s name cannot contain whitespace characters`)
+                }
+
+                if (t instanceof Language) {
+                    // The name should not start with a number
+                    const name = t.name.trim()
+                    !isNaN(parseInt(name[0])) && issue(`A Language's name cannot start with a number`)
+
+                   // The version is a non-empty string
+                    const version = t.version.trim();
+                    version.length === 0 && issue(`A Language's version must be a non-empty string`)
+                }
+
+                // The classifier should not inherit from itself (directly or indirectly)
+                if (t instanceof Classifier) {
+                    const cycle = inheritanceCycleWith(t);
+                    (cycle.length > 0) && issue(`A ${t.constructor.name} can't inherit (directly or indirectly) from itself, but ${qualifiedNameOf(t)} does so through the following cycle: ${cycle.map((t) => qualifiedNameOf(t)).join(" -> ")}`)
+                            // TODO  check whether it needs to be "a" or "an", or just say "An instance of ..."
+                }
+
+                return issues
+            }
+        ),
+        ...Object.entries(duplicatesAmong(allContaineds(language), idOf))
+            .flatMap(
+                ([id, ts]) => ts.map(
+                    (t) => ({ location: t, message: `Multiple (nested) language elements with the same ID "${id}" exist in this language`, secondaries: ts.filter((otherT) => t !== otherT) })
+                )
+            ),
+        ...Object.entries(duplicatesAmong(namedsOf(language), keyOf))   // all M3Concept-s that are INamed are also IKeyed
+            .flatMap(
+                ([key, ts]) => ts.map(
+                    (t) => ({ location: t, message: `Multiple (nested) language elements with the same key "${key}" exist in this language`, secondaries: ts.filter((otherT) => t !== otherT) })
+                )
+            ),
+        ...Object.entries(duplicatesAmong(namedsOf(language), qualifiedNameOf))
+            .flatMap(
+                ([key, ts]) => ts.map(
+                    (t) => ({ location: t, message: `Multiple (nested) language elements with the same key "${key}" exist in this language`, secondaries: ts.filter((otherT) => t !== otherT) })
+                )
+            )
+    ]
+
+
+// not here: unresolved references are a problem on a lower level
+// TODO (#8)  check whether references are resolved
+// Same goes for duplicate IDs, but for completeness' and symmetry's sake, we're also checking it here.
+

package/src/m3/deserializer.ts

@@ -0,0 +1,38 @@
+import { LionWebJsonChunk } from "@lionweb/json"
+import { deserializeSerializationChunk } from "../deserializer.js"
+import { nodesExtractorUsing } from "../extraction.js"
+import { defaultSimplisticHandler, SimplisticHandler } from "../handler.js"
+import { BuiltinPropertyValueDeserializer, lioncoreBuiltins } from "./builtins.js"
+import { lioncoreReader, lioncoreWriter } from "./facade.js"
+import { lioncore } from "./lioncore.js"
+import { Language } from "./types.js"
+
+
+/**
+ * Deserializes languages that have been serialized into the LionWeb serialization JSON format
+ * as an instance of the LionCore metametamodel, using {@link _M3Concept these type definitions}.
+ */
+export const deserializeLanguages = (serializationChunk: LionWebJsonChunk, ...dependentLanguages: Language[]): Language[] =>
+    deserializeLanguagesWithHandler(serializationChunk, defaultSimplisticHandler, ...dependentLanguages)
+
+/**
+ * Deserializes languages that have been serialized into the LionWeb serialization JSON format
+ * as an instance of the LionCore metametamodel, using {@link _M3Concept these type definitions}.
+ * This function takes a handler to be able to see what problems occurred.
+ */
+export const deserializeLanguagesWithHandler = (
+    serializationChunk: LionWebJsonChunk,
+    handler: SimplisticHandler,
+    ...dependentLanguages: Language[]
+): Language[] =>
+    deserializeSerializationChunk(
+        serializationChunk,
+        lioncoreWriter,
+        [lioncore, ...dependentLanguages],
+        [lioncoreBuiltins, ...dependentLanguages].flatMap(nodesExtractorUsing(lioncoreReader)),
+        new BuiltinPropertyValueDeserializer(),
+        handler
+    )
+        .filter((rootNode) => rootNode instanceof Language)
+        .map((language) => (language as Language).dependingOn(...dependentLanguages))
+

package/src/m3/facade.ts

@@ -0,0 +1,130 @@
+import { builtinFeatures } from "./builtins.js"
+import { metaTypedBasedClassifierDeducerFor, qualifiedNameOf } from "./functions.js"
+import { lioncore, metaConcepts, metaFeatures } from "./lioncore.js"
+import { Reader } from "../reading.js"
+import {
+    Annotation,
+    Classifier,
+    Concept,
+    Containment,
+    Enumeration,
+    EnumerationLiteral,
+    Interface,
+    Language,
+    M3Concept,
+    PrimitiveType,
+    Property,
+    Reference
+} from "./types.js"
+import { updateSettingsNameBased, Writer } from "../writing.js"
+
+const { inamed_name } = builtinFeatures
+const { ikeyed_key } = metaFeatures
+
+export const lioncoreReader: Reader<M3Concept> = {
+    classifierOf: metaTypedBasedClassifierDeducerFor(lioncore),
+    getFeatureValue: (node, feature) =>
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        (node as any)[feature.name], // (mirrors name-based update of settings)
+    enumerationLiteralFrom: (value, _) => value as EnumerationLiteral | null
+}
+
+/**
+ * Alias for {@link lioncoreReader}, kept for backward compatibility, and to be deprecated and removed later.
+ */
+export const lioncoreExtractionFacade = lioncoreReader
+
+/**
+ * @return An implementation of {@link Writer} for instances of the LionCore M3 (so M2s).
+ */
+export const lioncoreWriter: Writer<M3Concept> = {
+    nodeFor: (parent, classifier, id, propertySettings) => {
+        switch (classifier.key) {
+            case metaConcepts.annotation.key:
+                return new Annotation(
+                    parent as Language,
+                    propertySettings[inamed_name.key] as string,
+                    propertySettings[ikeyed_key.key] as string,
+                    id
+                )
+            case metaConcepts.concept.key:
+                return new Concept(
+                    parent as Language,
+                    propertySettings[inamed_name.key] as string,
+                    propertySettings[ikeyed_key.key] as string,
+                    id,
+                    propertySettings[metaFeatures.concept_abstract.key] as boolean
+                )
+            case metaConcepts.interface.key:
+                return new Interface(
+                    parent as Language,
+                    propertySettings[inamed_name.key] as string,
+                    propertySettings[ikeyed_key.key] as string,
+                    id
+                )
+            case metaConcepts.containment.key:
+                return new Containment(
+                    parent as Classifier,
+                    propertySettings[inamed_name.key] as string,
+                    propertySettings[ikeyed_key.key] as string,
+                    id
+                )
+            case metaConcepts.enumeration.key:
+                return new Enumeration(
+                    parent as Language,
+                    propertySettings[inamed_name.key] as string,
+                    propertySettings[ikeyed_key.key] as string,
+                    id
+                )
+            case metaConcepts.enumerationLiteral.key:
+                return new EnumerationLiteral(
+                    parent as Enumeration,
+                    propertySettings[inamed_name.key] as string,
+                    propertySettings[ikeyed_key.key] as string,
+                    id
+                )
+            case metaConcepts.language.key:
+                return new Language(
+                    propertySettings[inamed_name.key] as string,
+                    propertySettings[metaFeatures.language_version.key] as string,
+                    id,
+                    propertySettings[metaFeatures.ikeyed_key.key] as string
+                )
+            case metaConcepts.primitiveType.key:
+                return new PrimitiveType(
+                    parent as Language,
+                    propertySettings[inamed_name.key] as string,
+                    propertySettings[ikeyed_key.key] as string,
+                    id
+                )
+            case metaConcepts.property.key:
+                return new Property(
+                    parent as Classifier,
+                    propertySettings[inamed_name.key] as string,
+                    propertySettings[ikeyed_key.key] as string,
+                    id
+                )
+            case metaConcepts.reference.key:
+                return new Reference(
+                    parent as Classifier,
+                    propertySettings[inamed_name.key] as string,
+                    propertySettings[ikeyed_key.key] as string,
+                    id
+                )
+            default:
+                throw new Error(
+                    `don't know a node of concept ${qualifiedNameOf(classifier)} with key ${classifier.key} that's not in LionCore M3`
+                )
+        }
+    },
+    setFeatureValue: (node, feature, value) => {
+        updateSettingsNameBased(node as unknown as Record<string, unknown>, feature, value)
+    },
+    encodingOf: literal => literal
+}
+
+/**
+ * Alias for {@link lioncoreWriter}, kept for backward compatibility, and to be deprecated and removed later.
+ */
+export const lioncoreInstantationFacade = lioncoreWriter
+

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)
+    }
+}
+