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

package/CHANGELOG.md

@@ -33,6 +33,7 @@
     * Fix a bug where some features’ values are serialized multiple times.
 * Expose feature resolution, through the `featureResolversFor` function (and associated types), which performs proper checking.
   This avoids undebuggable `undefined` dereferencing at runtime in `deltaDeserializer` and `eventToDeltaTranslator` functions.
+* Package `src/` again (— i.e., don't ignore for NPM packaging.)
 
 
 ## 0.6.12

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@lionweb/core",
-    "version": "0.7.0-beta.18",
+    "version": "0.7.0-beta.19",
     "description": "LionWeb core for {Java|Type}Script",
     "main": "dist/index.js",
     "types": "dist/index.d.ts",
@@ -27,7 +27,7 @@
         "release": "npm publish"
     },
     "dependencies": {
-        "@lionweb/json": "0.7.0-beta.18",
-        "@lionweb/ts-utils": "0.7.0-beta.18"
+        "@lionweb/json": "0.7.0-beta.19",
+        "@lionweb/ts-utils": "0.7.0-beta.19"
     }
 }

package/src/deserializer.ts

@@ -0,0 +1,224 @@
+import {
+    currentSerializationFormatVersion,
+    LionWebId,
+    LionWebJsonChunk,
+    LionWebJsonNode,
+    LionWebKey
+} from "@lionweb/json"
+import { byIdMap, groupBy, keepDefineds } from "@lionweb/ts-utils"
+import { Writer } from "./writing.js"
+import { defaultSimplisticHandler, SimplisticHandler } from "./handler.js"
+import { BuiltinPropertyValueDeserializer } from "./m3/builtins.js"
+import { MemoisingSymbolTable } from "./m3/symbol-table.js"
+import { Classifier, Containment, Enumeration, Language, PrimitiveType, Property, Reference } from "./m3/types.js"
+import { unresolved } from "./references.js"
+import { Node } from "./types.js"
+
+/**
+ * Interface for objects that expose a method to deserialize a property's value.
+ */
+export interface PropertyValueDeserializer {
+    deserializeValue(value: string | undefined, property: Property): unknown | undefined
+}
+
+/**
+ * Misspelled alias of {@link PropertyValueDeserializer}, kept for backward compatibility, and to be deprecated and removed later.
+ */
+export interface PrimitiveTypeDeserializer extends PropertyValueDeserializer {}
+
+/**
+ * @return a deserialization of a {@link LionWebJsonChunk}
+ *
+ * @param serializationChunk - a {@link SerializedModel model} from its LionWeb serialization JSON format
+ * @param writer - a {@link Writer} that is used to instantiate nodes and set values on them
+ * @param languages - a {@link Language language} that the serialized model is expected to conform to
+ * @param dependentNodes - a collection of nodes from dependent models against which all references in the serialized model are supposed to resolve against
+ * @param propertyValueDeserializer - a deserializer for values of properties (by default a {@link BuiltinPropertyValueDeserializer})
+ * @param problemHandler - a handler for reporting problems (by default a {@link defaultSimplisticHandler})
+ */
+export const deserializeSerializationChunk = <NT extends Node>(
+    serializationChunk: LionWebJsonChunk,
+    writer: Writer<NT>,
+    languages: Language[],
+    // TODO  facades <--> languages, so it's weird that it looks split up like this
+    dependentNodes: Node[],
+    // TODO (#13)  see if you can turn this into [nodes: Node[], writer: Writer<Node>][] after all
+    propertyValueDeserializer: BuiltinPropertyValueDeserializer = new BuiltinPropertyValueDeserializer(),
+    problemHandler: SimplisticHandler = defaultSimplisticHandler
+): NT[] => {
+    if (serializationChunk.serializationFormatVersion !== currentSerializationFormatVersion) {
+        problemHandler.reportProblem(
+            `can't deserialize from serialization format other than version "${currentSerializationFormatVersion}" - assuming that version`
+        )
+    }
+
+    const symbolTable = new MemoisingSymbolTable(languages)
+
+    const { nodes: serializedNodes } = serializationChunk
+
+    const serializedNodeById = byIdMap(serializedNodes)
+
+    const deserializedNodeById: { [id: LionWebId]: NT } = {}
+
+    /**
+     * Instantiates a {@link Node} from the given {@link LionWebJsonNode},
+     * and stores it under its ID so references to it can be resolved.
+     * For every serialized node, only one instance will ever be constructed (through memoisation).
+     */
+    const instantiateMemoised = (serNode: LionWebJsonNode, parent?: NT): NT | null => {
+        if (serNode.id in deserializedNodeById) {
+            return deserializedNodeById[serNode.id]
+        }
+        const node = instantiate(serNode, parent)
+        if (node !== null) {
+            deserializedNodeById[node.id] = node
+        }
+        return node
+    }
+
+    type ReferenceToInstall = [node: NT, feature: Reference, refId: LionWebId]
+    const referencesToInstall: ReferenceToInstall[] = []
+
+    const tryInstantiate = (
+        parent: NT | undefined,
+        classifier: Classifier,
+        id: LionWebId,
+        propertySettings: { [propertyKey: LionWebKey]: unknown }
+    ): NT | null => {
+        try {
+            return writer.nodeFor(parent, classifier, id, propertySettings)
+        } catch (e: unknown) {
+            problemHandler.reportProblem(
+                `error occurred during instantiation of a node for classifier ${classifier.name} with meta-pointer (${classifier.language.key}, ${classifier.language.version}, ${classifier.key}); reason:`
+            )
+            problemHandler.reportProblem((e as Error).toString())
+            return null
+        }
+    }
+
+    /**
+     * Instantiates a {@link Node} from its {@link LionWebJsonNode serialization}.
+     */
+    const instantiate = (
+        { id, classifier: classifierMetaPointer, properties, containments, references, annotations }: LionWebJsonNode,
+        parent?: NT
+    ): NT | null => {
+        const classifier = symbolTable.entityMatching(classifierMetaPointer)
+
+        if (classifier === undefined || !(classifier instanceof Classifier)) {
+            problemHandler.reportProblem(
+                `can't deserialize node with id=${id}: can't find the classifier with key ${classifierMetaPointer.key} in language (${classifierMetaPointer.language}, ${classifierMetaPointer.version})`
+            )
+            return null
+        }
+
+        const allFeatures = symbolTable.allFeaturesOfEntityMatching(classifierMetaPointer)
+
+        const propertySettings: { [propertyKey: LionWebKey]: unknown } = {}
+
+        const serializedPropertiesPerKey = properties === undefined ? {} : groupBy(properties, sp => sp.property.key) // (this assumes no duplicate keys among properties!)
+        if (properties !== undefined) {
+            allFeatures
+                .filter(feature => feature instanceof Property)
+                .map(feature => feature as Property)
+                .forEach(property => {
+                    if (property.key in serializedPropertiesPerKey) {
+                        const value = serializedPropertiesPerKey[property.key][0].value
+                        if (property.type instanceof PrimitiveType) {
+                            propertySettings[property.key] =
+                                value === null ? undefined : propertyValueDeserializer.deserializeValue(value, property as Property)
+                            return
+                        }
+                        if (property.type instanceof Enumeration) {
+                            const literal = property.type.literals.find(literal => literal.key === value)
+                            if (literal !== undefined) {
+                                propertySettings[property.key] = writer.encodingOf(literal)
+                            }
+                            return
+                        }
+                        // (property is not handled, because neither a primitive type nor of enumeration type)
+                    }
+                })
+        }
+
+        const node = tryInstantiate(parent, classifier, id, propertySettings)
+        if (node === null) {
+            return null
+        }
+
+        const serializedContainmentsPerKey = containments === undefined ? {} : groupBy(containments, sp => sp.containment.key) // (this assumes no duplicate keys among containments!)
+        const serializedReferencesPerKey = references === undefined ? {} : groupBy(references, sp => sp.reference.key) // (this assumes no duplicate keys among references!)
+
+        allFeatures.forEach(feature => {
+            if (feature instanceof Property && properties !== undefined && feature.key in serializedPropertiesPerKey) {
+                writer.setFeatureValue(node, feature, propertySettings[feature.key])
+            } else if (feature instanceof Containment && containments !== undefined && feature.key in serializedContainmentsPerKey) {
+                const childIds = serializedContainmentsPerKey[feature.key].flatMap(serChildren => serChildren.children) as LionWebId[]
+                if (feature.multiple) {
+                    childIds.forEach(childId => {
+                        if (childId in serializedNodeById) {
+                            writer.setFeatureValue(node, feature, instantiateMemoised(serializedNodeById[childId], node))
+                        }
+                    })
+                } else {
+                    if (childIds.length > 0) {
+                        // just set the 1st one:
+                        const firstChildId = childIds[0]
+                        if (firstChildId in serializedNodeById) {
+                            writer.setFeatureValue(node, feature, instantiateMemoised(serializedNodeById[firstChildId], node))
+                        }
+                    }
+                }
+            } else if (feature instanceof Reference && references !== undefined && feature.key in serializedReferencesPerKey) {
+                const serRefs = (serializedReferencesPerKey[feature.key] ?? []).flatMap(serReferences =>
+                    serReferences.targets.map(t => t.reference)
+                )
+                referencesToInstall.push(
+                    ...(serRefs.filter(serRef => typeof serRef === "string") as LionWebId[]).map(
+                        refId => [node, feature, refId] as ReferenceToInstall
+                    )
+                )
+            }
+        })
+
+        node.annotations = keepDefineds(
+            annotations
+                .filter(annotationId => annotationId in serializedNodeById)
+                .map(annotationId => instantiateMemoised(serializedNodeById[annotationId]))
+        )
+            .map(annotation => annotation!)
+
+        return node
+    }
+
+    const rootLikeNodes = keepDefineds(
+        serializedNodes
+            .filter(({ parent }) => parent === null || !(parent in serializedNodeById))
+            .map(serializedNode => instantiateMemoised(serializedNode))
+    )
+        .map(node => node!)
+
+    const dependentNodesById = byIdMap(dependentNodes)
+
+    referencesToInstall.forEach(([node, reference, refId]) => {
+        const target = deserializedNodeById[refId] ?? dependentNodesById[refId]
+        const value = (() => {
+            if (target === undefined) {
+                const metaTypeMessage = "concept" in node ? ` and (meta-)type ${node.concept}` : ""
+                problemHandler.reportProblem(
+                    `couldn't resolve the target with id=${refId} of a "${reference.name}" reference on the node with id=${node.id}${metaTypeMessage}`
+                )
+                return unresolved
+            }
+            return target
+        })()
+        writer.setFeatureValue(node, reference, value)
+    })
+
+    return rootLikeNodes
+}
+
+/**
+ * Alias for {@link deserializeSerializationChunk}.
+ */
+export const deserializeChunk = deserializeSerializationChunk

package/src/dynamic-facade.ts

@@ -0,0 +1,63 @@
+import { LionWebKey } from "@lionweb/json"
+import { builtinFeatures } from "./m3/builtins.js"
+import { Classifier } from "./m3/types.js"
+import { Reader, ResolveInfoDeducer } from "./reading.js"
+import { Node } from "./types.js"
+import { updateSettingsKeyBased, Writer } from "./writing.js"
+
+
+/**
+ * Type definition for "dynamic nodes" that are not backed by specific types (e.g. classes).
+ */
+export type DynamicNode = Node & {
+    classifier: Classifier
+    settings: Record<string, unknown>
+}
+// TODO  could also have properties, containments, references - mimicking the serialization
+
+
+const propertyGetterFor = (key: LionWebKey): ResolveInfoDeducer<DynamicNode> =>
+    (node) =>
+        (key in node.settings && typeof node.settings[key] === "string")
+            ? node.settings[key] as string  // FIXME  type cast shouldn't be necessary
+            : undefined
+
+/**
+ * An implementation of {@link Reader} for {@link DynamicNode dynamic nodes}.
+ */
+export const dynamicReader: Reader<DynamicNode> = ({
+    classifierOf: (node) => node.classifier,
+    getFeatureValue: (node, feature) =>
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+        (node.settings as any)[feature.key],
+    enumerationLiteralFrom: (value, enumeration) =>
+        enumeration.literals.find(({key}) => key === value)
+        ?? null,    // (undefined -> null)
+    resolveInfoFor: propertyGetterFor(builtinFeatures.inamed_name.key)
+})
+
+/**
+ * Alias for {@link Reader}, kept for backward compatibility, and to be deprecated and removed later.
+ */
+export const dynamicExtractionFacade = dynamicReader
+
+/**
+ * An implementation of {@link Writer} for {@link DynamicNode dynamic nodes}.
+ */
+export const dynamicWriter: Writer<DynamicNode> = ({
+    nodeFor: (_parent, classifier, id, _propertySettings) => ({
+        id,
+        classifier,
+        settings: {}
+    } as DynamicNode),
+    setFeatureValue: (node, feature, value) => {
+        updateSettingsKeyBased(node.settings, feature, value)
+    },
+    encodingOf: ({key}) => key
+})
+
+/**
+ * Alias for {@link Reader}, kept for backward compatibility, and to be deprecated and removed later.
+ */
+export const dynamicInstantiationFacade = dynamicReader
+

package/src/extraction.ts

@@ -0,0 +1,31 @@
+import { flatMapNonCyclingFollowing, trivialFlatMapper } from "@lionweb/ts-utils"
+
+import { allFeaturesOf, isContainment } from "./m3/index.js"
+import { Reader } from "./reading.js"
+import { Node } from "./types.js"
+
+
+/**
+ * Type def. for functions that extract {@link Node nodes} from a given one.
+ */
+export type NodesExtractor<NT extends Node> = (node: NT) => NT[]
+
+/**
+ * @return A function that extracts the children from a given node.
+ */
+export const childrenExtractorUsing = <NT extends Node>(reader: Reader<NT>): NodesExtractor<NT> =>
+    (node: NT): NT[] => [
+        ...(allFeaturesOf(reader.classifierOf(node))
+            .filter(isContainment)
+            .flatMap((containment) => reader.getFeatureValue(node, containment) ?? [])),
+// FIXME  there's NO guarantee about the result of reader.getFeatureValue(node, containment) !!!
+        ...node.annotations
+    ] as NT[]
+
+
+/**
+ * @return a function that extracts *all* nodes from a given start node - usually a root node.
+ */
+export const nodesExtractorUsing = <NT extends Node>(reader: Reader<NT>): NodesExtractor<NT> =>
+    flatMapNonCyclingFollowing(trivialFlatMapper, childrenExtractorUsing<NT>(reader))
+

package/src/functions.ts

@@ -0,0 +1,28 @@
+import { LionWebId } from "@lionweb/json"
+import { flatMapNonCyclingFollowing, trivialFlatMapper } from "@lionweb/ts-utils"
+import { Node } from "./types.js"
+
+
+/**
+ * @return a list of itself and the ancestors of the given {@link Node node}, in anti-chronological order.
+ */
+export const containmentChain = (node: Node): Node[] => {
+    const getParent = (t: Node): Node[] => t.parent === undefined ? [] : [t.parent]
+    return flatMapNonCyclingFollowing(trivialFlatMapper, getParent)(node)
+}
+
+
+/**
+ * Maps an array of {@link Node AST nodes} or `null`s to their IDs.
+ * These `null`s might be the result of unresolved children.
+ */
+export const asIds = (nodeOrNulls: (Node | null)[]): (LionWebId | null)[] =>
+    nodeOrNulls.map((nodeOrNull) => nodeOrNull === null ? null : nodeOrNull.id)
+
+
+/**
+ * @return the id of the given {@link Node node}.
+ */
+export const idOf = <T extends Node>({id}: T): LionWebId =>
+    id
+

package/src/handler.ts

@@ -0,0 +1,57 @@
+/**
+ * A simplistic handler to which problems that arise during deserialization,
+ * are reported as plain text by calling the `reportProblem` function.
+ */
+export interface SimplisticHandler {
+    reportProblem: (message: string) => void
+}
+
+/**
+ * A default simplistic handler that just outputs everything of the console.
+ */
+export const defaultSimplisticHandler: SimplisticHandler = {
+    reportProblem: (message) => {
+        console.log(message)
+    }
+}
+
+
+/**
+ * A simplistic handler that just accumulates problems (in terms of their messages).
+ */
+export class AccumulatingSimplisticHandler implements SimplisticHandler {
+    private _allProblems: string[] = []
+    reportProblem(message: string) {
+        this._allProblems.push(message)
+    }
+    get allProblems() {
+        return this._allProblems
+    }
+}
+
+
+/**
+ * A simplistic handler that aggregates problems by their message.
+ * This is convenient for problems that arise many times during deserialization
+ * but produce the exact same message every time.
+ */
+export class AggregatingSimplisticHandler implements SimplisticHandler {
+    private messageByCount: { [message: string]: number } = {}
+    reportProblem(message: string) {
+        this.messageByCount[message] = (this.messageByCount[message] ?? 0) + 1
+    }
+    reportAllProblemsOnConsole(asTable = false) {
+        if (asTable) {
+            console.table(this.messageByCount)
+        } else {
+            Object.entries(this.messageByCount)
+                .forEach(([message, count]) => {
+                    console.log(`${message} (${count})`)
+                })
+        }
+    }
+    allProblems() {
+        return { ...this.messageByCount }
+    }
+}
+

package/src/index.ts

@@ -0,0 +1,13 @@
+export * from "./deserializer.js"
+export * from "./dynamic-facade.js"
+export * from "./extraction.js"
+export * from "./handler.js"
+export * from "./functions.js"
+export * from "./reading.js"
+export * from "./references.js"
+export * from "./serializer.js"
+export * from "./types.js"
+export * from "./version.js"
+export * from "./writing.js"
+export * from "./m1/reference-utils.js"
+export * from "./m3/index.js"

package/src/m1/reference-utils.ts

@@ -0,0 +1,106 @@
+import { Reader } from "../reading.js"
+import { allFeaturesOf, Reference } from "../m3/index.js"
+import { Node } from "../types.js"
+
+
+/**
+ * Represents information about a source and target node related through a {@link Reference}.
+ * An index of `null` means that the reference is (at most) single-valued.
+ */
+export class ReferenceValue<NT extends Node> {
+    constructor(
+        public readonly sourceNode: NT,
+        public readonly targetNode: NT,
+        public readonly reference: Reference,
+        public readonly index: number | null
+    ) {}
+}
+
+
+/**
+ * Finds all references within the given scope, as {@link ReferenceValue reference values}.
+ * To search within all nodes under a collection of root nodes,
+ * use _child extraction_ to compute all nodes in the forest hanging off of those root nodes as scope.
+ * Note that any reference is found uniquely,
+ * i.e. the returned {@link ReferenceValue reference values} are pairwise distinct,
+ * even if the scope passed contains duplicate nodes.
+ *
+ * @param scope - the {@link Node nodes} that are searched for references
+ * @param reader - a {@link Reader} to reflect on nodes.
+ * _Note_ that it's assumed that its {@link getFeatureValue} function doesn't throw.
+ */
+export const referenceValues = <NT extends Node>(
+    scope: NT[],
+    reader: Reader<NT>
+): ReferenceValue<NT>[] => {
+    const visit = (sourceNode: NT, reference: Reference): ReferenceValue<NT>[] => {
+        if (reference.multiple) {
+            const targetNodes = (reader.getFeatureValue(sourceNode, reference) ?? []) as NT[]
+            return targetNodes
+                .map((targetNode, index) =>
+                    new ReferenceValue<NT>(sourceNode, targetNode, reference, index)
+                )
+        }
+
+        const targetNode = reader.getFeatureValue(sourceNode, reference) as (NT | undefined)
+        if (targetNode !== undefined) {
+            return [new ReferenceValue<NT>(sourceNode, targetNode, reference, null)]
+        }
+
+        return []
+    }
+
+    return [...new Set(scope)]  // ~ .distinct()
+        .flatMap((sourceNode) =>
+            allFeaturesOf(reader.classifierOf(sourceNode))
+                .filter((feature) => feature instanceof Reference)
+                .map((feature) => feature as Reference)
+                .flatMap((reference) => visit(sourceNode, reference))
+        )
+}
+
+
+/**
+ * Finds all references coming into the given target node or any of the given target nodes,
+ * within the given scope, as {@link ReferenceValue reference values}.
+ * To search within all nodes under a collection of root nodes,
+ * use _child extraction_ to compute all nodes in the forest hanging off of those root nodes as scope.
+ * Note that any reference is found uniquely,
+ * i.e. the returned {@link ReferenceValue reference values} are pairwise distinct,
+ * even if the given target nodes or scope contain duplicate nodes.
+ *
+ * @param targetNodeOrNodes - one or more target {@link Node nodes} for which the incoming references are searched
+ * @param scope - the {@link Node nodes} that are searched for references
+ * @param reader - a {@link Reader} to reflect on nodes.
+ * _Note_ that it's assumed that its {@link getFeatureValue} function doesn't throw.
+ */
+export const incomingReferences = <NT extends Node>(
+    targetNodeOrNodes: NT[] | NT,
+    scope: NT[],
+    reader: Reader<NT>
+): ReferenceValue<NT>[] => {
+    const targetNodes = Array.isArray(targetNodeOrNodes) ? targetNodeOrNodes : [targetNodeOrNodes]
+    return referenceValues(scope, reader)
+        .filter((referenceValue) => targetNodes.indexOf(referenceValue.targetNode) > -1)
+}
+
+
+/**
+ * Finds all references to nodes that are not in the given scope, as {@link ReferenceValue reference values}.
+ * To search within all nodes under a collection of root nodes,
+ * use _child extraction_ to compute all nodes in the forest hanging off of those root nodes as scope.
+ * Note that any reference is found uniquely,
+ * i.e. the returned {@link ReferenceValue reference values} are pairwise distinct,
+ * even if the given scope contains duplicate nodes.
+ *
+ * @param scope - the {@link Node nodes} that form the scope of “reachable” nodes
+ * @param reader - a {@link Reader} to reflect on nodes.
+ * _Note_ that it's assumed that its {@link getFeatureValue} function doesn't throw.
+ */
+export const referencesToOutOfScopeNodes = <NT extends Node>(
+    scope: NT[],
+    reader: Reader<NT>
+): ReferenceValue<NT>[] =>
+    referenceValues(scope, reader)
+        .filter((referenceValue) => scope.indexOf(referenceValue.targetNode) === -1)
+

package/src/m3/README.md

@@ -0,0 +1,16 @@
+# LionCore M3 metametamodel
+
+
+## Aspects
+
+* [TypeScript type definitions](./types.ts)
+* [Factory](./factory.ts) for conveniently creating M3 instances
+* [Classifiers built in (`LionCore-builtins`) to LionCore](./builtins.ts)
+* [Facades specific for M3 instances](./facade.ts)
+* Persistence: [serializer](./serializer.ts) and [deserializer](./deserializer.ts)
+* [Constraints checker](./constraints.ts)
+* Convenience/helper [functions](./functions.ts) defined on M3 concepts
+* ([Reference checker](./reference-checker.ts))
+
+An interesting place to start might be the [self-definition](./lioncore.ts) of LionCore (`LionCore-M3`) using its own [TypeScript type definitions](./types.ts).
+