@lionweb/core 0.8.0-beta.5 → 0.8.0-beta.6

package/src/m3/serializer.ts

@@ -1,13 +1,36 @@
 import { LionWebJsonChunk } from "@lionweb/json"
 import { serializerWith } from "../serializer.js"
-import { lioncoreReader } from "./facade.js"
+import { lioncoreReaderFor } from "./reading-writing.js"
 import { Language } from "./types.js"
+import { LionWebVersion } from "./version.js"
+import { defaultLionWebVersion, LionWebVersions } from "./versions.js"
 
 
+/**
+ * Type def. for objects that contain all necessary data to deserialize one or more languages from a {@link LionWebJsonChunk serialization chunk}.
+ */
+export type LanguageSerializationData = {
+    /**
+     * The version of the LionWeb serialization format to serialize in.
+     * Default = {@link defaultLionWebVersion}.
+     */
+    lionWebVersion?: LionWebVersion
+    languages: Language[]
+}
+
+/**
+ * @return the {@link LionWebJsonChunk serialization chunk} serializing the given languages (M2s, as instances of the LionCore M3),
+ * according to the configured {@link LionWebVersion} (which itself defaults to {@link defaultLionWebVersion}).
+ */
+export const serializeLanguagesFor = (data: LanguageSerializationData) => {
+    const lionwebVersion = data.lionWebVersion ?? defaultLionWebVersion
+    return serializerWith({ reader: lioncoreReaderFor(lionwebVersion) })(data.languages)
+}
+
 /**
  * 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 =>
-    serializerWith({ reader: lioncoreReader })(languages)
+    serializerWith({ reader: lioncoreReaderFor(LionWebVersions.v2023_1) })(languages)
 

package/src/m3/types.ts

@@ -5,15 +5,9 @@
 
 import { LionWebId, LionWebJsonMetaPointer, LionWebKey } from "@lionweb/json"
 import { ResolveInfoDeducer } from "../reading.js"
-import { MultiRef, SingleRef, referenceToSet } from "../references.js"
+import { MultiRef, referenceToSet, SingleRef } 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"
+import { lioncoreBuiltinsKey } from "./builtins-common.js"
 
 
 // Types appear roughly in the order of top-to-down+left-to-right in the diagram at:
@@ -72,7 +66,7 @@ abstract class M3Node implements IKeyed, IMetaTyped {
         this.key = key
         return this
     }
-    annotations: Node[] = [] // (containment)
+    readonly annotations: Node[] = [] // (containment)
 }
 
 abstract class Feature extends M3Node {
@@ -136,7 +130,7 @@ abstract class LanguageEntity extends M3Node {
 }
 
 abstract class Classifier extends LanguageEntity {
-    features: Feature[] = [] // (containment)
+    readonly features: Feature[] = [] // (containment)
     havingFeatures(...features: Feature[]) {
         this.features.push(...features.filter((feature) => this.features.indexOf(feature) < 0))
         return this
@@ -158,7 +152,7 @@ class Concept extends Classifier {
     abstract: boolean
     partition: boolean
     extends?: SingleRef<Concept>    // (reference)
-    implements: MultiRef<Interface> = []  // (reference)
+    readonly 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
@@ -181,7 +175,7 @@ class Annotation extends Classifier {
         return "Annotation"
     }
     extends?: SingleRef<Annotation> // (reference)
-    implements: MultiRef<Interface> = [] // (reference)
+    readonly implements: MultiRef<Interface> = [] // (reference)
     annotates: SingleRef<Classifier> = referenceToSet()   // (reference)
     constructor(language: Language, name: string, key: LionWebKey, id: LionWebId, extends_?: SingleRef<Annotation>) {
         super(language, name, key, id)
@@ -202,7 +196,7 @@ class Interface extends Classifier {
     metaType(): string {
         return "Interface"
     }
-    extends: MultiRef<Interface> = []    // (reference)
+    readonly extends: MultiRef<Interface> = []    // (reference)
     extending(...interfaces: Interface[]): Interface {
         // TODO  check actual types of interfaces, or use type shapes/interfaces
         this.extends.push(...interfaces)
@@ -227,7 +221,7 @@ class Enumeration extends DataType {
     metaType(): string {
         return "Enumeration"
     }
-    literals: EnumerationLiteral[] = [] // (containment)
+    readonly literals: EnumerationLiteral[] = [] // (containment)
     havingLiterals(...literals: EnumerationLiteral[]) {
         this.literals.push(...literals.filter((literal) => this.literals.indexOf(literal) < 0))
         return this
@@ -251,8 +245,8 @@ class Language extends M3Node {
         return "Language"
     }
     version: string
-    entities: LanguageEntity[] = []   // (containment)
-    dependsOn: MultiRef<Language> = []  // special (!) reference
+    readonly entities: LanguageEntity[] = []   // (containment)
+    readonly 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)

package/src/m3/version.ts

@@ -0,0 +1,23 @@
+import { LionCoreFacade } from "./lioncore-common.js"
+import { LionCoreBuiltinsFacade } from "./builtins-common.js"
+
+/**
+ * Representation of a LionWeb version.
+ */
+export class LionWebVersion {
+    constructor(
+        /**
+         * The value of the root-level `serializationFormatVersion` field for {@link LionWebJsonChunk serialization chunks} *emitted* by this version.
+         */
+        public readonly serializationFormatVersion: string,
+        public readonly lioncoreFacade: LionCoreFacade,
+        public readonly builtinsFacade: LionCoreBuiltinsFacade
+    ) {
+    }
+}
+
+/*
+ * This class must be in a separate file to avoid circular initializations:
+ *  versions.ts[LionWebVersions] -> version-<version>.ts -> version.ts
+ */
+

package/src/m3/versions/v2023_1/builtins-legacy.ts

@@ -0,0 +1,126 @@
+import { asMinimalJsonString } from "@lionweb/ts-utils"
+import { shouldBeIdentical } from "../../builtins-common.js"
+import { DataType, Property } from "../../types.js"
+import { PropertyValueDeserializer } from "../../../deserializer.js"
+import { isUnresolvedReference } from "../../../references.js"
+import { PropertyValueSerializer } from "../../../serializer.js"
+import { v2023_1 } from "./version.js"
+
+
+abstract class DataTypeRegistry<T> {
+    private map = new Map<DataType, T>()
+
+    private _sealed = false
+
+    sealed() {
+        this._sealed = true
+        return this
+    }
+
+    public register(dataType: DataType, t: T) {
+        if (this._sealed) {
+            throw new Error(`can't register a data type with a register that has been sealed`)
+        }
+        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
+    }
+}
+
+
+const { booleanDataType, integerDataType, jsonDataType, stringDataType } = v2023_1.builtinsFacade.primitiveTypes
+
+
+/**
+ * An implementation of {@link PropertyValueDeserializer} that knows how to deserialize serialized values of all the built-in primitive types.
+ *
+ * @deprecated
+ */
+export class BuiltinPropertyValueDeserializer
+    extends DataTypeRegistry<(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 (isUnresolvedReference(type)) {
+            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.
+ *
+ * @deprecated
+ */
+export class DefaultPrimitiveTypeDeserializer extends BuiltinPropertyValueDeserializer {
+}
+
+/**
+ * An implementation of {@link PropertyValueSerializer} that knows how to serialize values of all the built-in primitive types.
+ *
+ * @deprecated
+ */
+export class BuiltinPropertyValueSerializer extends DataTypeRegistry<(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 (isUnresolvedReference(type)) {
+            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.
+ *
+ * @deprecated
+ */
+export class DefaultPrimitiveTypeSerializer extends BuiltinPropertyValueSerializer {
+}
+

package/src/m3/versions/v2023_1/builtins.ts

@@ -0,0 +1,102 @@
+import { asMinimalJsonString } from "@lionweb/ts-utils"
+import {
+    LionCoreBuiltinsFacade,
+    lioncoreBuiltinsIdAndKeyGenerator,
+    newPropertyValueDeserializerRegistry,
+    newPropertyValueSerializerRegistry,
+    propertyValueDeserializerFrom,
+    propertyValueSerializerFrom
+} from "../../builtins-common.js"
+import { isBuiltinNodeConcept } from "../../builtins-function.js"
+import { LanguageFactory } from "../../factory.js"
+
+
+const factory = new LanguageFactory(
+    "LionCore_builtins",
+    "2023.1",
+    lioncoreBuiltinsIdAndKeyGenerator,
+    lioncoreBuiltinsIdAndKeyGenerator
+)
+/*
+ * ID == key: `LionCore-builtins-${qualified name _without_ "LionCore-builtins", dash-separated}`
+ */
+
+
+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 inamed = factory.interface("INamed")
+
+const inamed_name = factory.property(inamed, "name").ofType(stringDataType)
+
+
+export const lioncoreBuiltinsFacade: LionCoreBuiltinsFacade = {
+    language: factory.language,
+    propertyValueDeserializer: propertyValueDeserializerFrom(
+        newPropertyValueDeserializerRegistry()
+            .set(stringDataType, (value) => value)
+            .set(booleanDataType, (value) => JSON.parse(value))
+            .set(integerDataType, (value) => Number(value))
+            .set(jsonDataType, (value) => JSON.parse(value as string))
+    ),
+    propertyValueSerializer: propertyValueSerializerFrom(
+        newPropertyValueSerializerRegistry()
+            .set(stringDataType, (value) => value as string)
+            .set(booleanDataType, (value) => `${value as boolean}`)
+            .set(integerDataType, (value) => `${value as number}`)
+            .set(jsonDataType, (value) => asMinimalJsonString(value))
+    ),
+    classifiers: { node, inamed },
+    features: { inamed_name },
+    primitiveTypes: {
+        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
+    }
+}
+
+
+/**
+ * Definition of a LionCore language that serves as a standard library of built-in primitive types.
+ *
+ * @deprecated Use `<LionWebVersion>.builtinsFacade.isBuiltinNodeConcept` instead.
+ */
+export const lioncoreBuiltins = factory.language
+/**
+ * @deprecated Use `<LionWebVersion>.builtinsFacade.primitiveTypes` instead.
+ */
+export const builtinPrimitives = lioncoreBuiltinsFacade.primitiveTypes
+/**
+ * @deprecated Use `<LionWebVersion>.builtinsFacade.classifiers` instead.
+ */
+export const builtinClassifiers = lioncoreBuiltinsFacade.classifiers
+/**
+ * @deprecated Use `<LionWebVersion>.builtinsFacade.features` instead.
+ */
+export const builtinFeatures = lioncoreBuiltinsFacade.features
+/**
+ * @deprecated Use {@link isBuiltinNodeConcept} instead.
+ */
+export const isBuiltinConcept = isBuiltinNodeConcept
+

package/src/m3/{lioncore.ts → versions/v2023_1/lioncore.ts}

@@ -1,14 +1,13 @@
-import { currentReleaseVersion } from "../version.js"
-import { builtinClassifiers, builtinPrimitives } from "./builtins.js"
-import { LanguageFactory } from "./factory.js"
+import { lioncoreBuiltinsFacade } from "./builtins.js"
+import { LanguageFactory } from "../../factory.js"
+import { generatedLionCoreKeyFrom, LionCoreFacade } from "../../lioncore-common.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("-")
+    "2023.1",
+    (...names) => "-id-" + generatedLionCoreKeyFrom(...names),
+    generatedLionCoreKeyFrom
 )
 /*
  * ID: `-id-${key}`
@@ -17,28 +16,25 @@ const factory = new LanguageFactory(
 
 /**
  * Definition of LionCore in terms of itself.
+ *
+ * @deprecated Use {@code lioncoreFacade.language} instead.
  */
 export const lioncore = factory.language.havingKey("LionCore-M3")
 
-const { inamed } = builtinClassifiers
-const { booleanDataType, stringDataType } = builtinPrimitives
+const { inamed } = lioncoreBuiltinsFacade.classifiers
+const { booleanDataType, stringDataType } = lioncoreBuiltinsFacade.primitiveTypes
 
 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)
+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)
-
+factory.property(link, "multiple").ofType(booleanDataType)
 const link_type = factory.reference(link, "type")
 
 const containment = factory.concept("Containment", false, link)
@@ -48,92 +44,73 @@ 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)
-
+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)
-
+factory.reference(annotation, "annotates").isOptional().ofType(classifier)
+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)
-
+factory.property(concept, "partition").ofType(booleanDataType)
+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_)
+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
+factory.containment(language, "entities").isOptional().isMultiple().ofType(languageEntity)
+factory.reference(language, "dependsOn").isOptional().isMultiple().ofType(language)
+
+
+export const lioncoreFacade: LionCoreFacade = {
+    language: factory.language,
+    metaConcepts: {
+        annotation,
+        classifier,
+        concept,
+        interface: interface_,
+        containment,
+        enumeration,
+        enumerationLiteral,
+        ikeyed,
+        language,
+        primitiveType,
+        property,
+        reference
+    },
+    metaFeatures: {
+        concept_abstract,
+        ikeyed_key,
+        language_version
+    }
 }
 
-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 }
+/**
+ * @deprecated Use {@code <LionWeb version>.lioncoreFacade.metaConcepts} instead.
+ */
+export const metaConcepts = lioncoreFacade.metaConcepts
+
+/**
+ * @deprecated Use {@code <LionWeb version>.lioncoreFacade.metaFeatures} instead.
+ */
+export const metaFeatures = lioncoreFacade.metaFeatures
+

package/src/m3/versions/v2023_1/version.ts

@@ -0,0 +1,9 @@
+import { lioncoreBuiltinsFacade } from "./builtins.js"
+import { lioncoreFacade } from "./lioncore.js"
+import { LionWebVersion } from "../../version.js"
+
+/**
+ * A representation of the 2023.1 LionWeb version.
+ */
+export const v2023_1 = new LionWebVersion("2023.1", lioncoreFacade, lioncoreBuiltinsFacade)
+

package/src/m3/versions.ts

@@ -0,0 +1,37 @@
+import { v2023_1 } from "./versions/v2023_1/version.js"
+import { LionWebVersion } from "./version.js"
+
+
+/**
+ * The *current* release(d) version.
+ *
+ * @deprecated Use {@code defaultLionWebVersion.serializationFormatVersion} instead.
+ */
+export const currentReleaseVersion = "2023.1"
+
+
+/**
+ * An enumeration (as const object) of all LionWeb versions currently supported by the WIP specification.
+ */
+export const LionWebVersions = {
+    // LionWeb standard version 2023.1 — defined at https://lionweb.io/specification/2023.1
+    v2023_1
+} as const
+
+/**
+ * All LionWeb versions.
+ */
+export const allLionWebVersions = Object.values(LionWebVersions)
+
+/**
+ * The current default LionWeb version.
+ */
+export const defaultLionWebVersion = LionWebVersions.v2023_1
+
+/**
+ * @return the {@link LionWebVersion} matching the given `serializationFormatVersion` string,
+ * or {@link undefined} if there’s none.
+ */
+export const lionWebVersionFrom = (serializationFormatVersion: string): LionWebVersion | undefined =>
+    allLionWebVersions.find((version) => version.serializationFormatVersion === serializationFormatVersion)
+

package/src/reading.ts

@@ -51,6 +51,8 @@ export interface Reader<NT extends Node> {
 
 /**
  * Alias for {@link Reader}, kept for backward compatibility, and to be deprecated and removed later.
+ *
+ * @deprecated Use {@link Reader} instead.
  */
 export interface ExtractionFacade<NT extends Node> extends Reader<NT> {}