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

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

package/src/references.ts

@@ -0,0 +1,31 @@
+import { LionWebId } from "@lionweb/json"
+
+
+/**
+ * The `unresolved` symbol indicates a reference value which hasn't been resolved yet.
+ * It differs from an unset (`undefined`) value.
+ */
+export const unresolved = null
+
+/**
+ * A type definition for a reference value that can be unresolved.
+ */
+export type SingleRef<T> = typeof unresolved | T
+
+/**
+ * Checks whether a given (at most) single-valued reference actually refers to something.
+ */
+export const isRef = <T>(ref?: SingleRef<T>): ref is T =>
+    ref !== undefined && ref !== unresolved
+
+/**
+ * A type alias for a multi-valued reference, to make it look consistent with {@link SingleRef}.
+ */
+export type MultiRef<T> = T[]
+
+
+/**
+ * A type that expresses a value is either an {@link LionWebId} or a value to indicate that resolution to a node previously failed.
+ */
+export type IdOrUnresolved = LionWebId | typeof unresolved;
+

package/src/serializer.ts

@@ -0,0 +1,244 @@
+import {
+    currentSerializationFormatVersion,
+    LionWebId,
+    LionWebJsonChunk,
+    LionWebJsonMetaPointer,
+    LionWebJsonNode
+} from "@lionweb/json"
+import { asArray, keepDefineds, lazyMapGet, Nested3Map, uniquesAmong } from "@lionweb/ts-utils"
+import { asIds } from "./functions.js"
+import { Reader } from "./reading.js"
+import { Node } from "./types.js"
+import { BuiltinPropertyValueSerializer } from "./m3/builtins.js"
+import { inheritsDirectlyFrom } from "./m3/functions.js"
+import {
+    Classifier,
+    Containment,
+    Enumeration,
+    Feature,
+    Language,
+    PrimitiveType,
+    Property,
+    Reference,
+    simpleNameDeducer
+} from "./m3/types.js"
+
+
+/**
+ * Interface for objects that expose a method to serialize a property's value.
+ */
+export interface PropertyValueSerializer {
+    serializeValue(value: unknown, property: Property): string | null
+}
+
+/**
+ * Misspelled alias of {@link PropertyValueSerializer}, kept for backward compatibility, and to be deprecated and removed later.
+ */
+export interface PrimitiveTypeSerializer extends PropertyValueSerializer {}
+
+
+const isPropertyValueSerializer = (value: unknown): value is PropertyValueSerializer =>
+    typeof value === "object" && value !== null && "serializeValue" in value && typeof value.serializeValue === "function"
+        // (we can't check the rest of the signature – i.e. arguments and their types – at runtime, because that's JavaScript)
+
+
+/**
+ * Type to provide (non-required) options to the serializer.
+ */
+export type SerializationOptions = Partial<{
+
+    /**
+     * Determines whether empty feature values are explicitly serialized or skipped during serialization.
+     * (The specification states that empty feature values SHOULD be serialized, but not that they MUST be.)
+     * Default = true, meaning that empty feature values are *not* skipped.
+     */
+    serializeEmptyFeatures: boolean
+
+    /**
+     * A {@link PropertyValueSerializer} implementation.
+     * Default = DefaultPropertyValueSerializer.
+     */
+    propertyValueSerializer: PropertyValueSerializer
+
+    /**
+     * Misspelled alias of {@link #propertyValueSerializer}, kept for backward compatibility, and to be deprecated and removed later.
+     */
+    primitiveTypeSerializer: PropertyValueSerializer
+
+}>
+
+/**
+ * @return the {@link LionWebJsonMetaPointer} for the given {@link Feature}.
+ */
+export const metaPointerFor = (feature: Feature): LionWebJsonMetaPointer => {
+    const { language } = feature.classifier
+    return {
+        language: language.key,
+        version: language.version,
+        key: feature.key
+    }
+}
+
+
+/**
+ * @return a function that serializes the {@link Node nodes} passed to it.
+ */
+export const nodeSerializer = <NT extends Node>(reader: Reader<NT>, serializationOptions?: SerializationOptions) => {
+    const propertyValueSerializer =
+        serializationOptions?.propertyValueSerializer ?? serializationOptions?.primitiveTypeSerializer ?? new BuiltinPropertyValueSerializer()
+    const serializeEmptyFeatures = serializationOptions?.serializeEmptyFeatures ?? true
+
+    const languageKey2version2classifierKey2allFeatures: Nested3Map<Feature[]> = {}
+    const memoisedAllFeaturesOf = (classifier: Classifier): Feature[] =>
+        lazyMapGet(
+            lazyMapGet(
+                lazyMapGet(
+                    languageKey2version2classifierKey2allFeatures,
+                    classifier.language.key,
+                    () => ({})
+                ),
+                classifier.language.version,
+                () => ({})
+            ),
+            classifier.key,
+            () => uniquesAmong( // make unique in case a feature was inherited from multiple super-classifiers
+                [ ...classifier.features, ...(inheritsDirectlyFrom(classifier).flatMap(memoisedAllFeaturesOf)) ]
+                /*
+                 * [NOTE]
+                 * The allFeaturesOf function uses flatMapNonCyclingFollowing which avoids that features of a super-classifier are added multiple times.
+                 * Unfortunately, to make use of the memoising, we can't use flatMapNonCyclingFollowing in the same way here.
+                 * So, we have to remove duplicates ourselves.
+                 */
+            )
+        )
+
+    return (nodes: NT[]): LionWebJsonChunk => {
+        const serializedNodes: LionWebJsonNode[] = [] // keep nodes as much as possible "in order"
+        const ids: { [id: LionWebId]: boolean } = {} // maintain a map to keep track of IDs of nodes that have been serialized
+        const languagesUsed: Language[] = []
+        const usedLanguageKey2Version2Boolean: { [key: string]: { [version: string]: boolean } } = {}
+        const registerLanguageUsed = (language: Language) => {
+            const version2Boolean = lazyMapGet<{ [version: string]: boolean }>(usedLanguageKey2Version2Boolean, language.key, () => ({}))
+            if (!version2Boolean[language.version]) {
+                version2Boolean[language.version] = true
+                languagesUsed.push(language)
+            }
+        }
+
+        const visit = (node: NT, parent?: NT) => {
+            if (node.id in ids) {
+                return
+            }
+
+            const classifier = reader.classifierOf(node)
+            const language = classifier.language
+            registerLanguageUsed(language)
+            const serializedNode: LionWebJsonNode = {
+                id: node.id,
+                classifier: classifier.metaPointer(),
+                properties: [],
+                containments: [],
+                references: [],
+                annotations: [],
+                parent: null
+            }
+            serializedNodes.push(serializedNode)
+            ids[node.id] = true
+            memoisedAllFeaturesOf(classifier).forEach((feature) => {
+                const value = reader.getFeatureValue(node, feature)
+                const featureLanguage = feature.classifier.language
+                registerLanguageUsed(featureLanguage)
+                const featureMetaPointer = metaPointerFor(feature)
+                if (feature instanceof Property) {
+                    if (value === undefined && !serializeEmptyFeatures) {
+                        // for immediate backward compatibility: skip empty property values regardless of options?.skipEmptyValues
+                        return
+                    }
+                    const encodedValue = (() => {
+                        // (could also just inspect type of value:)
+                        if (feature.type instanceof PrimitiveType) {
+                            return propertyValueSerializer.serializeValue(value, feature)
+                        }
+                        if (feature.type instanceof Enumeration) {
+                            return reader.enumerationLiteralFrom(value, feature.type)?.key
+                        }
+                        return undefined
+                    })()
+                    serializedNode.properties.push({
+                        property: featureMetaPointer,
+                        value: (encodedValue as string) ?? null // (undefined -> null)
+                    })
+                    return
+                }
+                if (feature instanceof Containment) {
+                    const children = asArray(value) as (NT | null)[]
+                    if (children.length === 0 && !serializeEmptyFeatures) {
+                        return
+                    }
+                    serializedNode.containments.push({
+                        containment: featureMetaPointer,
+                        children: keepDefineds(asIds(children))
+                            .map(childId => childId as string)
+                    })
+                    children.forEach(childOrNull => {
+                        if (childOrNull !== null) {
+                            visit(childOrNull, node)
+                        }
+                    })
+                    return
+                }
+                if (feature instanceof Reference) {
+                    // Note: value can be null === typeof unresolved, e.g. on an unset (or previously unresolved) single-valued reference
+                    const targets = asArray(value) as (NT | null)[]
+                    if (targets.length === 0 && !serializeEmptyFeatures) {
+                        return
+                    }
+                    serializedNode.references.push({
+                        reference: featureMetaPointer,
+                        targets: keepDefineds(targets) // (skip "non-connected" targets)
+                            .map(t => t as NT)
+                            .map(t => ({
+                                resolveInfo:
+                                    (reader.resolveInfoFor ? reader.resolveInfoFor(t) : simpleNameDeducer(t)) ?? null,
+                                reference: t.id
+                            }))
+                    })
+                    return
+                }
+            })
+
+            const annotations = asArray(node.annotations) as NT[] // assumes that annotations also all are of type NT (which is not unreasonable)
+            serializedNode.annotations = annotations.map(annotation => annotation.id)
+            annotations.forEach(annotation => visit(annotation, node))
+
+            serializedNode.parent = parent?.id ?? null // (undefined -> null)
+        }
+
+        nodes.forEach(node => visit(node, undefined))
+
+        return {
+            serializationFormatVersion: currentSerializationFormatVersion,
+            languages: languagesUsed.map(({ key, version }) => ({ key, version })),
+            nodes: serializedNodes
+        }
+    }
+}
+
+/**
+ * @return a {@link LionWebJsonChunk} of the given model (i.e., an array of {@link Node nodes} - the first argument) to the LionWeb serialization JSON format.
+ *  <em>Note:</em> this function will be deprecated and removed later — use {@link nodeSerializer} instead.
+ */
+export const serializeNodes = <NT extends Node>(
+    nodes: NT[],
+    reader: Reader<NT>,
+    propertyValueSerializerOrOptions?: PropertyValueSerializer | SerializationOptions
+): LionWebJsonChunk =>
+    nodeSerializer<NT>(
+        reader,
+        isPropertyValueSerializer(propertyValueSerializerOrOptions)
+            ? {
+                propertyValueSerializer: propertyValueSerializerOrOptions
+            }
+            : propertyValueSerializerOrOptions
+    )(nodes)
+

package/src/types.ts

@@ -0,0 +1,11 @@
+import { LionWebId } from "@lionweb/json"
+
+/**
+ * Type definition for a LionWeb-compliant AST node.
+ */
+export type Node = {
+    id: LionWebId
+    parent?: Node
+    annotations: Node[]
+}
+

package/src/version.ts

@@ -0,0 +1,5 @@
+/**
+ * The <em>current</em> release(d) version.
+ */
+export const currentReleaseVersion = "2023.1"
+