@lionweb/class-core 0.6.13-beta.0

package/src/duplicator.ts

@@ -0,0 +1,111 @@
+// Copyright 2025 TRUMPF Laser SE and other contributors
+//
+// Licensed under the Apache License, Version 2.0 (the "License")
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+// SPDX-FileCopyrightText: 2025 TRUMPF Laser SE and other contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import {asArray, Containment, Feature, Id, idOf, Link, Property, Reference, SingleRef, unresolved} from "@lionweb/core";
+
+import {INodeBase} from "./base-types.js";
+import {NodesToInstall} from "./linking.js";
+import {getFeatureValue} from "./serializer.js";
+import {allNodesFrom} from "./convenience.js";
+
+
+/**
+ * Type definition for functions that duplicate a node.
+ */
+export type NodeDuplicator = (originalNode: INodeBase) => [duplicatedNode: INodeBase, featuresToDuplicate: Feature[]];
+
+/**
+ * Type definition for functions that duplicate the (variadically) given nodes.
+ */
+export type Duplicator = (...nodes: INodeBase[]) => INodeBase[];
+
+/**
+ * @return a function that deep-duplicates a given forest of {@link INodeBase nodes}.
+ * The result is an array of the deep-duplicated versions of the given nodes *in the same order*.
+ *
+ *  @param duplicateNode a function that returns a – possibly transformed – duplicate of the passed `originalNode`.
+ * ***Note***: it's assumed that the classifiers of the original and duplicated nodes coincide exactly!
+ */
+export const deepDuplicateWith = (duplicateNode: NodeDuplicator): Duplicator =>
+    (...nodes) => {
+
+        const nodesToInstall: NodesToInstall[] = [];
+
+        const visit = (node: INodeBase): [id: Id, duplicatedNode: INodeBase] => {
+            const [duplicatedNode, featuresToDuplicate] = duplicateNode(node);
+            const duplicateFeatureValue = (feature: Feature) => {
+                const value = getFeatureValue(node, feature);
+                if (feature instanceof Property) {
+                    duplicatedNode.getPropertyValueManager(feature).setDirectly(value);
+                } else if (feature instanceof Link) {
+                    const values = asArray(value as (SingleRef<INodeBase> | SingleRef<INodeBase>[]));
+                    const resolvedValues = values.filter((value) => value !== unresolved) as INodeBase[];
+                    if (resolvedValues.length > 0) {
+                        nodesToInstall.push([
+                            duplicatedNode,
+                            feature,
+                            resolvedValues.map(idOf),
+                            feature instanceof Reference
+                                ? resolvedValues
+                                : undefined
+                        ]);
+                    }
+                }
+            };
+            featuresToDuplicate.forEach(duplicateFeatureValue);
+            if (node.annotations.length > 0) {
+                nodesToInstall.push([duplicatedNode, null, node.annotations.map(idOf)]);
+            }
+            return [node.id, duplicatedNode];
+        }
+
+        const duplicatedNodesByOriginalId = Object.fromEntries(
+            nodes.flatMap(allNodesFrom).map(visit)
+        );
+
+        nodesToInstall.forEach(([copiedNode, feature, ids, originalReferenceTargets]) => {
+            if (feature instanceof Containment) {
+                const valueManager = copiedNode.getContainmentValueManager(feature);
+                ids.forEach((id) => {
+                    const nodeToInstall = duplicatedNodesByOriginalId[id];
+                    valueManager.addDirectly(nodeToInstall);
+                    nodeToInstall.attachTo(copiedNode, feature);
+                });
+                return;
+            }
+            if (feature instanceof Reference) {
+                const valueManager = copiedNode.getReferenceValueManager(feature);
+                ids.forEach((id, index) => {
+                    const nodeToInstall = duplicatedNodesByOriginalId[id] ?? originalReferenceTargets![index];
+                    valueManager.addDirectly(nodeToInstall);
+                });
+                return;
+            }
+            if (feature === null) {
+                const valueManager = copiedNode.annotationsValueManager;
+                ids.forEach((id) => {
+                    const nodeToInstall = duplicatedNodesByOriginalId[id];
+                    valueManager.addDirectly(nodeToInstall);
+                })
+                return;
+            }
+        });
+
+        return nodes.map(({id}) => duplicatedNodesByOriginalId[id]);
+
+    };
+

package/src/id-mapping.ts

@@ -0,0 +1,58 @@
+// Copyright 2025 TRUMPF Laser SE and other contributors
+//
+// Licensed under the Apache License, Version 2.0 (the "License")
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+// SPDX-FileCopyrightText: 2025 TRUMPF Laser SE and other contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import {Id, IdOrUnresolved, SingleRef, unresolved} from "@lionweb/core";
+
+import {INodeBase} from "./index.js";
+
+
+type NodesById = { [id: Id]: INodeBase};
+
+
+/**
+ * Maintains a mapping ID → node,
+ * which is primarily used for efficiently applying {@link IDelta deltas}.
+ * Instances are produced by the {@link nodeBaseDeserializerWithIdMapping} function.
+ */
+export class IdMapping {
+
+    nodesById: NodesById;
+    constructor(nodesById: NodesById) {
+        this.nodesById = {...nodesById};
+    }
+
+    fromId(id: Id): INodeBase {
+        if (!(id in this.nodesById)) {
+            throw new Error(`node with id=${id} not in ID mapping`);
+        }
+        return this.nodesById[id];
+    }
+
+    fromRefId(idOrUnresolved: IdOrUnresolved): SingleRef<INodeBase> {
+        return idOrUnresolved === null
+            ? null
+            : (this.nodesById[idOrUnresolved] ?? unresolved);
+    }
+
+    updateWith(node: INodeBase) {
+        this.nodesById[node.id] = node;
+        node.children   // recurse into all children
+            .forEach((child) => this.updateWith(child));
+    }
+
+}
+

package/src/index.ts

@@ -0,0 +1,29 @@
+// Copyright 2025 TRUMPF Laser SE and other contributors
+//
+// Licensed under the Apache License, Version 2.0 (the "License")
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+// SPDX-FileCopyrightText: 2025 TRUMPF Laser SE and other contributors
+// SPDX-License-Identifier: Apache-2.0
+
+export * from "./base-types.js";
+export * from "./convenience.js";
+export * from "./deltas/index.js";
+export * from "./deserializer.js";
+export {deepDuplicateWith} from "./duplicator.js";
+export * from "./id-mapping.js";
+// skip linking.js: see comment there
+export * from "./lionCore_builtins.g.js";
+export {serializeNodeBases} from "./serializer.js";
+export * from "./value-managers/index.js";
+export {asTreeTextWith} from "./textualizer.js";
+

package/src/linking.ts

@@ -0,0 +1,39 @@
+// Copyright 2025 TRUMPF Laser SE and other contributors
+//
+// Licensed under the Apache License, Version 2.0 (the "License")
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+// SPDX-FileCopyrightText: 2025 TRUMPF Laser SE and other contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import {Id, Link} from "@lionweb/core";
+import {INodeBase} from "./index.js";
+
+
+/**
+ * A tuple type for (data concerning) link and annotation values that are involved with deserialization and deep-duplication
+ *  — more specifically: nodes that have to be installed on other (deserialized/deep-duplicated) nodes in specific features (or as annotations).
+ *
+ * The elements are:
+ *
+ * 1. `parent` — the {@link INodeBase} instance to install on.
+ * 2. `feature` — the {@link Link link} feature to install on, or `null` to indicate that it's an annotation.
+ * 3. `nodesIds` — are the IDs of the nodes to install.
+ * 4. *optional* `originalReferenceTargets` — are the original reference targets of a {@link Reference reference} feature.
+ *  This element is only present when the feature is a {@link Reference reference} feature.
+ *  The `nodesIds` and `originalReferenceTargets` match up per index.
+ *
+ * Note: **DON'T** export this types from the package,
+ * as these are only used to align the deserializer and deep-cloner.
+ */
+export type NodesToInstall = [ container: INodeBase, feature: Link | null, nodesIds: Id[], originalReferenceTargets?: INodeBase[] ];
+

package/src/lionCore_builtins.g.ts

@@ -0,0 +1,141 @@
+// Copyright 2025 TRUMPF Laser SE and other contributors
+//
+// Licensed under the Apache License, Version 2.0 (the "License")
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+// SPDX-FileCopyrightText: 2025 TRUMPF Laser SE and other contributors
+// SPDX-License-Identifier: Apache-2.0
+
+// Warning: this file is generated!
+// Modifying it by hand is useless at best, and sabotage at worst.
+
+/*
+ * language's metadata:
+ *     name:    LionCore_builtins
+ *     version: 2023.1
+ *     key:     LionCore-builtins
+ *     id:      LionCore-builtins
+ */
+
+
+import {
+    Classifier,
+    Concept,
+    EnumerationLiteral,
+    Id,
+    Interface,
+    Language,
+    PrimitiveType,
+    Property
+} from "@lionweb/core";
+
+import {
+    DeltaHandler,
+    ILanguageBase,
+    INodeBase,
+    NodeBase,
+    NodeBaseFactory
+} from "./index.js";
+
+
+export class LionCore_builtinsBase implements ILanguageBase {
+
+    private readonly _language: Language = new Language("LionCore_builtins", "2023.1", "LionCore-builtins", "LionCore-builtins");
+    get language(): Language {
+        this.ensureWiredUp();
+        return this._language;
+    }
+
+    public readonly _String = new PrimitiveType(this._language, "String", "LionCore-builtins-String", "LionCore-builtins-String");
+    get String(): PrimitiveType {
+        this.ensureWiredUp();
+        return this._String;
+    }
+
+    public readonly _Boolean = new PrimitiveType(this._language, "Boolean", "LionCore-builtins-Boolean", "LionCore-builtins-Boolean");
+    get Boolean(): PrimitiveType {
+        this.ensureWiredUp();
+        return this._Boolean;
+    }
+
+    public readonly _Integer = new PrimitiveType(this._language, "Integer", "LionCore-builtins-Integer", "LionCore-builtins-Integer");
+    get Integer(): PrimitiveType {
+        this.ensureWiredUp();
+        return this._Integer;
+    }
+
+    public readonly _JSON = new PrimitiveType(this._language, "JSON", "LionCore-builtins-JSON", "LionCore-builtins-JSON");
+    get JSON(): PrimitiveType {
+        this.ensureWiredUp();
+        return this._JSON;
+    }
+
+    public readonly _Node = new Concept(this._language, "Node", "LionCore-builtins-Node", "LionCore-builtins-Node", true);
+    get Node(): Concept {
+        this.ensureWiredUp();
+        return this._Node;
+    }
+
+    public readonly _INamed = new Interface(this._language, "INamed", "LionCore-builtins-INamed", "LionCore-builtins-INamed");
+    get INamed(): Interface {
+        this.ensureWiredUp();
+        return this._INamed;
+    }
+    private readonly _INamed_name = new Property(this._INamed, "name", "LionCore-builtins-INamed-name", "LionCore-builtins-INamed-name");
+    get INamed_name(): Property {
+        this.ensureWiredUp();
+        return this._INamed_name;
+    }
+
+    private _wiredUp: boolean = false;
+    private ensureWiredUp() {
+        if (this._wiredUp) {
+            return;
+        }
+        this._language.havingEntities(this._String, this._Boolean, this._Integer, this._JSON, this._Node, this._INamed);
+        this._INamed.havingFeatures(this._INamed_name);
+        this._INamed_name.ofType(this._String);
+        this._wiredUp = true;
+    }
+
+    factory(_handleDelta?: DeltaHandler): NodeBaseFactory {
+        return (classifier: Classifier, _id: Id) => {
+            const {language} = classifier;
+            throw new Error(`can't instantiate ${classifier.name} (key=${classifier.key}): classifier is not known in language ${language.name} (key=${language.key}, version=${language.version})`);
+        }
+    }
+
+    enumLiteralFrom<EnumType>(enumerationLiteral: EnumerationLiteral): EnumType {
+        const {enumeration} = enumerationLiteral;
+        const {language} = enumeration;
+        throw new Error(`enumeration with key ${enumeration.key} is not known in language ${language.name} (key=${language.key}, version=${language.version})`);
+    }
+
+    public static readonly INSTANCE = new LionCore_builtinsBase();
+}
+
+
+export type String = string;
+
+export type Boolean = boolean;
+
+export type Integer = number;
+
+export type JSON = unknown;
+
+export abstract class Node extends NodeBase {
+}
+
+export interface INamed extends INodeBase {
+    name: string;
+}
+

package/src/serializer.ts

@@ -0,0 +1,86 @@
+// Copyright 2025 TRUMPF Laser SE and other contributors
+//
+// Licensed under the Apache License, Version 2.0 (the "License")
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+// SPDX-FileCopyrightText: 2025 TRUMPF Laser SE and other contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import {
+    allSuperTypesOf,
+    builtinClassifiers,
+    builtinFeatures,
+    Containment,
+    ExtractionFacade,
+    Feature,
+    Property,
+    Reference,
+    serializeNodes
+} from "@lionweb/core";
+
+import {INodeBase, LionCore_builtinsBase} from "./index.js";
+
+
+/**
+ * @return the value of the given {@link Feature feature} (2nd argument) on the given node (of type {@link INodeBase}; 1st argument).
+ * **Note** that this function is for internal use only!
+ */
+export const getFeatureValue = (node: INodeBase, feature: Feature) => {
+    if (feature instanceof Property) {
+        return node.getPropertyValueManager(feature).getDirectly();
+    }
+    if (feature instanceof Containment) {
+        return node.getContainmentValueManager(feature).getDirectly();
+    }
+    if (feature instanceof Reference) {
+        return node.getReferenceValueManager(feature).getDirectly();
+    }
+    throw new Error(`unhandled Feature sub type ${feature.constructor.name}`)
+};
+
+/**
+ * An {@link ExtractionFacade} that works on/for {@link INodeBase}s specifically.
+ * **Note** that this function is for internal use only!
+ */
+export const nodeBaseReader: ExtractionFacade<INodeBase> = {
+    classifierOf: (node) => node.classifier,
+    getFeatureValue,
+    enumerationLiteralFrom: (encoding, enumeration) => {
+        return enumeration.literals.find((literal) => literal.key === encoding)!;
+    },
+    resolveInfoFor: (node: INodeBase) => {
+        if ("name" in node) {
+            // evaluating `node.name` might cause an error through FeatureValueManager.throwOnReadOfUnset:
+            try {
+                const value = node.name;
+                return typeof value === "string" ? value : undefined;
+            } catch (_) {
+                return undefined;
+            }
+        }
+        const allSupertypes = allSuperTypesOf(node.classifier);
+        if (allSupertypes.indexOf(builtinClassifiers.inamed) > -1) {
+            return node.getPropertyValueManager(builtinFeatures.inamed_name).getDirectly() as (string | undefined);
+        }
+        if (allSupertypes.indexOf(LionCore_builtinsBase.INSTANCE.INamed) > -1) {
+            return node.getPropertyValueManager(LionCore_builtinsBase.INSTANCE.INamed_name).getDirectly() as (string | undefined);
+        }
+        return undefined;
+    }
+};
+
+/**
+ * @return a serialization of the given nodes (of type {@link INodeBase}) as a {@link SerializationChunk}.
+ */
+export const serializeNodeBases = (nodes: INodeBase[]) =>
+    serializeNodes(nodes, nodeBaseReader, { serializeEmptyFeatures: false });
+

package/src/textualizer.ts

@@ -0,0 +1,104 @@
+// Copyright 2025 TRUMPF Laser SE and other contributors
+//
+// Licensed under the Apache License, Version 2.0 (the "License")
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+// SPDX-FileCopyrightText: 2025 TRUMPF Laser SE and other contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import {asString, indentWith, Template} from "littoral-templates"
+import {allFeaturesOf, Containment, Feature, Property, Reference, unresolved} from "@lionweb/core"
+
+import {INodeBase} from "./base-types.js";
+import {LionCore_builtinsBase} from "./lionCore_builtins.g.js";
+
+
+const indent = indentWith("    ")(1)
+
+const prependWith = (template: Template, prefix: string): Template =>
+    prefix + asString(template)
+
+
+type INodeBaseOrNotThere = INodeBase | typeof unresolved | undefined
+
+const asINodeBases = (value: INodeBaseOrNotThere | INodeBaseOrNotThere[]): INodeBase[] => {
+    const isINodeBase = (value: INodeBaseOrNotThere): value is INodeBase =>
+        !(value === unresolved || value === undefined)
+
+    if (Array.isArray(value)) {
+        return value
+            .filter((subValue) => isINodeBase(subValue))
+            .map((subValue) => subValue as INodeBase)
+    }
+    return isINodeBase(value) ? [value] : []
+}
+
+
+/**
+ * @return a function that renders the roots of a given forest of {@link INodeBase nodes} in a textual tree-representation.
+ * @param identificationFor a function that renders an identification for the given {@link INodeBase node} — typically its name or its ID.
+ */
+export const asTreeTextWith = (identificationFor: (node: INodeBase) => string): ((nodes: INodeBase[]) => string) => {
+
+    const asText = (node: INodeBase): Template => {
+        const featureValueAsText = (feature: Feature) => {
+            if (feature instanceof Property) {
+                const valueManager = node.getPropertyValueManager(feature)
+                const displayValue = (() => {
+                    if (!valueManager.isSet()) {
+                        return `$<not set>`
+                    }
+                    const value = valueManager.getDirectly()
+                    if (feature.type === LionCore_builtinsBase.INSTANCE.String) {
+                        return `"${value}"`
+                    }
+                    return value
+                })()
+                return `${feature.name} = ${displayValue}`
+            }
+            if (feature instanceof Containment) {
+                const valueManager = node.getContainmentValueManager(feature)
+                const children = asINodeBases(valueManager.getDirectly())
+                return [
+                    `${feature.name}:${children.length === 0 ? " <nothing>" : ""}`,
+                    indent(children.map(asText))
+                ]
+            }
+            if (feature instanceof Reference) {
+                const valueManager= node.getReferenceValueManager(feature)
+                const references = asINodeBases(valueManager.getDirectly())
+                return [
+                    `${feature.name} -> ${references.length === 0 ? "<none>" : references.map(identificationFor).join(", ")}`
+                ]
+            }
+            return `!!! can't handle feature ${feature.name} (of meta type ${feature.metaType()})`
+        }
+
+        const annotationAsText = (annotation: INodeBase) =>
+            prependWith(asText(annotation), "@ ")
+
+        return [
+            `${node.classifier.name} (id: ${node.id})`,
+            indent([
+                allFeaturesOf(node.classifier).map(featureValueAsText),
+                node.annotations.map(annotationAsText)
+            ])
+        ]
+    }
+
+    return (nodes: INodeBase[]) => asString(
+        nodes
+            .filter((node) => node.parent === undefined) // root nodes
+            .map(asText)
+    )
+}
+