@lionweb/class-core 0.6.13-beta.0

package/src/value-managers/annotations.ts

@@ -0,0 +1,139 @@
+// 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 {action, observable} from "mobx";
+
+import {INodeBase, removeFromParent} from "../base-types.js";
+import {checkIndex, ValueManager} from "./base.js";
+import {
+    AnnotationAddedDelta,
+    AnnotationDeletedDelta,
+    AnnotationMovedFromOtherParentDelta,
+    AnnotationMovedInSameParentDelta,
+    AnnotationReplacedDelta
+} from "../deltas/index.js";
+
+
+/**
+ * A value manager for annotations.
+ * Annotations (of any type) are simply contained by a parent (which is an {@link INodeBase}),
+ * not in the context of a(ny) {@link Feature feature}.
+ */
+export class AnnotationsValueManager extends ValueManager {
+
+    constructor(container: INodeBase) {
+        super(container);
+    }
+
+    private readonly annotations = observable.array<INodeBase>([], {deep: false});
+
+    get(): INodeBase[] {
+        return this.annotations.slice();
+    }
+
+    @action addDirectly(newAnnotation: INodeBase) {
+        this.annotations.push(newAnnotation);
+        newAnnotation.attachTo(this.container, null);
+    }
+
+    @action add(newAnnotation: INodeBase) {
+        this.insertAtIndex(newAnnotation, this.annotations.length);
+    }
+
+    /**
+     * @return `false` if the given `newAnnotation` wasn't contained before,
+     *  otherwise an array tuple with the old – i.e.: previous – parent of the inserted annotation, and the index it was contained at.
+     */
+    @action insertAtIndexDirectly(newAnnotation: INodeBase, index: number): false | [oldParent: INodeBase, oldIndex: number] {
+        checkIndex(index, this.annotations.length, true);
+        this.annotations.splice(index, 0, newAnnotation);
+        const oldParent = newAnnotation.parent;
+        if (oldParent === undefined) {
+            newAnnotation.attachTo(this.container, null);
+            return false;
+        } else {
+            const oldIndex = removeFromParent(oldParent, newAnnotation);
+            newAnnotation.attachTo(this.container, null);
+            return [oldParent, oldIndex];
+        }
+    }
+
+    @action insertAtIndex(newAnnotation: INodeBase, index: number) {
+        const oldParentage = this.insertAtIndexDirectly(newAnnotation, index);
+        if (oldParentage === false) {
+            this.emitDelta(() => new AnnotationAddedDelta(this.container, index, newAnnotation));
+        } else {
+            this.emitDelta(() => new AnnotationMovedFromOtherParentDelta(oldParentage[0], oldParentage[1], this.container, index, newAnnotation));
+        }
+    }
+
+    /**
+     * @return the moved annotation, or `undefined` if the indices coincide.
+     */
+    @action moveDirectly(oldIndex: number, newIndex: number): INodeBase | undefined {
+        checkIndex(oldIndex, this.annotations.length, false);
+        checkIndex(newIndex, this.annotations.length, false);
+        if (oldIndex !== newIndex) {
+            const [annotation] = this.annotations.splice(oldIndex, 1);
+            this.annotations.splice(newIndex, 0, annotation);
+            return annotation;
+        }
+        return undefined;
+    }
+
+    @action move(oldIndex: number, newIndex: number) {
+        const annotation = this.moveDirectly(oldIndex, newIndex);
+        if (annotation !== undefined) {
+            this.emitDelta(() => new AnnotationMovedInSameParentDelta(this.container, oldIndex, newIndex, annotation));
+        }
+    }
+
+    /**
+     * @return the replaced annotation.
+     */
+    @action replaceAtIndexDirectly(newAnnotation: INodeBase, index: number): INodeBase {
+        checkIndex(index, this.annotations.length, false);
+        const replacedAnnotation = this.annotations[index];
+        this.annotations.splice(index, 1, newAnnotation);
+        replacedAnnotation.detach();
+        newAnnotation.attachTo(this.container, null);
+        return replacedAnnotation;
+    }
+
+    @action replaceAtIndex(newAnnotation: INodeBase, index: number) {
+        const replacedAnnotation = this.replaceAtIndexDirectly(newAnnotation, index);
+        this.emitDelta(() => new AnnotationReplacedDelta(this.container, index, replacedAnnotation, newAnnotation));
+    }
+
+    @action removeDirectly(annotationToRemove: INodeBase): number {
+        const index = this.annotations.indexOf(annotationToRemove);
+        if (index > -1) {
+            this.annotations.splice(index, 1);
+        }
+        annotationToRemove.detach();
+        return index;
+    }
+
+    @action remove(annotationToRemove: INodeBase) {
+        const removeIndex = this.removeDirectly(annotationToRemove);
+        if (removeIndex > -1) {
+            this.emitDelta(() => new AnnotationDeletedDelta(this.container, removeIndex, annotationToRemove));
+        }
+    }
+
+}
+

package/src/value-managers/base.ts

@@ -0,0 +1,123 @@
+// 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 {Feature, featureMetaType, Link} from "@lionweb/core";
+import {INodeBase} from "../base-types.js";
+import {IDelta} from "../deltas/index.js";
+
+
+/**
+ * Abstract super/base type for managers of values on classifiers.
+ */
+export abstract class ValueManager {
+
+    protected constructor(protected readonly container: INodeBase) {
+    }
+
+    /**
+     * Emits a delta if a {@link DeltaHandler} is registered with the container.
+     * @param deltaThunk a thunk that generates the delta, and is only called when a delta handler is registered with the container.
+     */
+    emitDelta(deltaThunk: () => IDelta) {
+        if (this.container.handleDelta) {
+            this.container.handleDelta(deltaThunk());
+        }
+    }
+
+}
+
+
+/**
+ * Abstract super/base type for managers of values of features on classifiers.
+ * All subtypes have "<requiredness><multiplicity>ValueManager" as names,
+ * where <requiredness> = "" (for abstract “inter-types”) or "Optional" or "Required",
+ * and <multiplicity> = "Single" or "Multiple".
+ */
+export abstract class FeatureValueManager<FT extends Feature> extends ValueManager {
+
+    protected constructor(protected readonly feature: FT, container: INodeBase) {
+        super(container);
+    }
+
+
+    /**
+     * Checks whether the feature's requiredness matches the expected one.
+     */
+    checkRequired(expectRequired: boolean) {
+        if (this.feature.optional === expectRequired) { // (double negation)
+            throw new Error(`${featureMetaType(this.feature).toLowerCase()} "${this.feature.name}" (with key="${this.feature.key}") should be ${expectRequired ? "required" : "optional"}`);
+        }
+    }
+
+    /**
+     * Checks whether the feature's multiplicity matches the expected one.
+     */
+    checkMultiple(expectMultiple: boolean) {
+        if ((this.feature as unknown as Link).multiple !== expectMultiple) {
+            throw new Error(`${featureMetaType(this.feature).toLowerCase()} "${this.feature.name}" (with key="${this.feature.key}") should be ${expectMultiple ? "multi" : "single"}-valued`);
+        }
+    }
+
+
+    /**
+     * @return whether the feature's value is (has been) set.
+     */
+    abstract isSet(): boolean;
+
+    /**
+     * @throws when the feature's value is unset, but has been attempted to read.
+     */
+    throwOnReadOfUnset(): never {
+        throw new Error(`can't read required ${featureMetaType(this.feature).toLowerCase()} "${this.feature.name}" that's unset on instance of ${this.container.classifier.language.name}.${this.container.classifier.name} with id=${this.container.id}`);
+    }
+
+    /**
+     * @throws when the feature's value has been attempted to unset, but the feature is required.
+     */
+    throwOnUnset(): never {
+        throw new Error(`can't unset required ${featureMetaType(this.feature).toLowerCase()} "${this.feature.name}" on instance of ${this.container.classifier.language.name}.${this.container.classifier.name} with id=${this.container.id}`);
+    }
+
+}
+
+
+/**
+ * Checks whether the given index is valid within the given parameters of the context.
+ * @param index the supposed index of an element to retrieve/insert at/to
+ * @param nElements the number of elements in an array
+ * @param inserting whether the intention is to insert an element to the array
+ */
+export const checkIndex = (index: number, nElements: number, inserting: boolean) => {
+    if (!Number.isInteger(index)) {
+        throw new Error(`an array index must be an integer, but got: ${index}`);
+    }
+    if (index < 0) {
+        throw new Error(`an array index must be a non-negative integer, but got: ${index}`);
+    }
+    if (inserting) {
+        if (index > nElements) {
+            throw new Error(`the largest valid insert index for an array with ${nElements} element${nElements === 1 ? "": "s"} is ${nElements}, but got: ${index}`);
+        }
+    } else {
+        if (nElements === 0) {
+            throw new Error(`an empty array has no valid indices (got: ${index})`);
+        } else if (index + 1 > nElements) {
+            throw new Error(`the largest valid index for an array with ${nElements} element${nElements === 1 ? "": "s"} is ${nElements - 1}, but got: ${index}`);
+        }
+    }
+}
+

package/src/value-managers/containments.ts

@@ -0,0 +1,323 @@
+// 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 {Containment} from "@lionweb/core";
+import {action, observable} from "mobx";
+
+import {INodeBase, removeFromParent} from "../base-types.js";
+import {checkIndex, FeatureValueManager} from "./base.js";
+import {
+    ChildAddedDelta,
+    ChildDeletedDelta,
+    ChildMovedDelta,
+    ChildMovedInSameContainmentDelta,
+    ChildReplacedDelta
+} from "../deltas/index.js";
+
+
+/**
+ * An instance manages the value of a particular containment feature on a particular instance of a classifier.
+ */
+export abstract class ContainmentValueManager<T extends INodeBase> extends FeatureValueManager<Containment> {
+
+    get containment(): Containment {
+        return this.feature;
+    }
+
+    abstract getDirectly(): T | undefined | (T | undefined)[];
+
+    /**
+     * Adds the given child to the containment.
+     * For a single-valued containment, this assumes that it contained no child before,
+     * or else it throws.
+     */
+    abstract addDirectly(newChild: T): void;
+
+}
+
+
+export abstract class SingleContainmentValueManager<T extends INodeBase> extends ContainmentValueManager<T> {
+
+    protected constructor(containment: Containment, container: INodeBase) {
+        super(containment, container);
+        this.checkMultiple(false);
+    }
+
+    private readonly child = observable.box<T | undefined>(undefined, {deep: false});
+
+    getDirectly(): T | undefined {
+        return this.child.get();
+    }
+
+    isSet(): boolean {
+        return this.child.get() !== undefined;
+    }
+
+    @action setDirectly(newChild: T | undefined) {
+        this.child.set(newChild);
+    }
+
+    @action addDirectly(newChild: T) {
+        const oldChild = this.getDirectly();
+        if (oldChild !== undefined) {
+            throw new Error(`replacing a child using addDirectly on a value manager for a single-valued containment isn't allowed`);    // FIXME  unit test this
+        }
+        this.child.set(newChild);
+    }
+
+}
+
+
+export class OptionalSingleContainmentValueManager<T extends INodeBase> extends SingleContainmentValueManager<T> {
+
+    constructor(containment: Containment, container: INodeBase) {
+        super(containment, container);
+        this.checkRequired(false);
+    }
+
+    get(): T | undefined {
+        return this.getDirectly();
+    }
+
+    @action set(newChild: T | undefined) {
+        const oldChild = this.getDirectly();
+        if (oldChild === undefined) {
+            if (newChild === undefined) {
+                // do nothing: nothing's changed
+            } else {
+                if (newChild.parent && newChild.containment) {
+                    const oldParent = newChild.parent;
+                    removeFromParent(oldParent, newChild);
+                    this.emitDelta(() => new ChildMovedDelta(oldParent, newChild.containment!, 0, this.container, this.feature, 0, newChild));
+                } else {
+                    this.emitDelta(() => new ChildAddedDelta(this.container, this.feature, 0, newChild));
+                }
+                this.setDirectly(newChild);
+                newChild.attachTo(this.container, this.feature);
+            }
+        } else {
+            if (newChild === undefined) {
+                oldChild.detach();
+                this.setDirectly(undefined);
+                this.emitDelta(() => new ChildDeletedDelta(this.container, this.feature, 0, oldChild));
+            } else {
+                if (oldChild === newChild) {
+                    // do nothing: nothing's changed
+                } else {
+                    if (oldChild.parent && oldChild.containment && oldChild.parent === this.container && oldChild.containment === this.feature) {
+                        // FIXME  oldChild.parent COULD be this.container
+                        this.emitDelta(() => new ChildDeletedDelta(this.container, this.feature, 0, oldChild));
+                    }
+                    oldChild.detach();
+                    if (newChild.parent && newChild.containment) {
+                        removeFromParent(newChild.parent, newChild);
+                    }
+                    this.setDirectly(newChild);
+                    newChild.attachTo(this.container, this.feature);
+                    this.emitDelta(() => new ChildReplacedDelta(this.container, this.feature, 0, oldChild, newChild));
+                }
+            }
+        }
+    }
+
+}
+
+
+export class RequiredSingleContainmentValueManager<T extends INodeBase> extends SingleContainmentValueManager<T> {
+
+    constructor(containment: Containment, container: INodeBase) {
+        super(containment, container);
+        this.checkRequired(true);
+    }
+
+    get(): T {
+        const child = this.getDirectly();
+        if (child === undefined) {
+            this.throwOnReadOfUnset();
+        }
+        return child;
+    }
+
+    @action set(newChild: T | undefined) {
+        const oldChild = this.getDirectly();
+        if (oldChild === undefined) {
+            if (newChild === undefined) {
+                // do nothing: nothing's changed
+            } else {
+                if (newChild.parent && newChild.containment) {
+                    const oldParent = newChild.parent;
+                    removeFromParent(oldParent, newChild);
+                    this.emitDelta(() => new ChildMovedDelta(oldParent, newChild.containment!, 0, this.container, this.feature, 0, newChild));
+                } else {
+                    this.emitDelta(() => new ChildAddedDelta(this.container, this.feature, 0, newChild));
+                }
+                this.setDirectly(newChild);
+                newChild.attachTo(this.container, this.feature);
+            }
+        } else {
+            if (newChild === undefined) {
+                this.throwOnUnset();
+            } else {
+                if (oldChild === newChild) {
+                    // do nothing: nothing's changed
+                } else {
+                    if (oldChild.parent && oldChild.containment && oldChild.parent === this.container && oldChild.containment === this.feature) {
+                        // FIXME  oldChild.parent COULD be this.container
+                        this.emitDelta(() => new ChildDeletedDelta(this.container, this.feature, 0, oldChild));
+                    }
+                    oldChild.detach();
+                    if (newChild.parent && newChild.containment) {
+                        removeFromParent(newChild.parent, newChild);
+                    }
+                    this.setDirectly(newChild);
+                    newChild.attachTo(this.container, this.feature);
+                    this.emitDelta(() => new ChildReplacedDelta(this.container, this.feature, 0, oldChild, newChild));
+                }
+            }
+        }
+    }
+
+}
+
+
+export abstract class MultiContainmentValueManager<T extends INodeBase> extends ContainmentValueManager<T> {
+
+    protected constructor(containment: Containment, container: INodeBase) {
+        super(containment, container);
+        this.checkMultiple(true);
+    }
+
+    private readonly children = observable.array<T>([], {deep: false});
+
+    getDirectly(): T[] {
+        return this.children;
+    }
+
+    get(): T[] {
+        return this.getDirectly().slice();
+    }
+
+    isSet(): boolean {
+        return this.children.length > 0;
+    }
+
+    @action addDirectly(newChild: T) {
+        this.children.push(newChild);
+    }
+
+    @action add(newChild: T): void {
+        this.insertAtIndex(newChild, this.getDirectly().length);
+    }
+
+    @action insertAtIndexDirectly(newChild: T, index: number) {
+        checkIndex(index, this.children.length, true);
+        this.children.splice(index, 0, newChild);
+    }
+
+    @action insertAtIndex(newChild: T, index: number) {
+        this.insertAtIndexDirectly(newChild, index);
+        if (newChild.parent === undefined && newChild.containment === undefined) {
+            this.emitDelta(() => new ChildAddedDelta(this.container, this.containment, index, newChild));
+        } else {
+            const oldIndex = removeFromParent(newChild.parent, newChild);
+            this.emitDelta(() => new ChildMovedDelta(newChild.parent!, newChild.containment!, oldIndex, this.container, this.containment, index, newChild));
+            newChild.detach();
+        }
+        newChild.attachTo(this.container, this.containment);
+    }
+
+    @action removeDirectly(childToRemove: T): number {
+        const children = this.getDirectly();
+        const index = children.findIndex((child) => child === childToRemove);
+        if (index > -1) {
+            children.splice(index, 1);
+            return index;
+        }
+        return -1;
+    }
+
+    @action moveDirectly(oldIndex: number, newIndex: number): T | undefined {
+        checkIndex(oldIndex, this.children.length, false);
+        checkIndex(newIndex, this.children.length, false);
+        if (oldIndex !== newIndex) {
+            const [child] = this.children.splice(oldIndex, 1);
+            this.children.splice(newIndex, 0, child);
+            return child;
+        }
+        return undefined;
+    }
+
+    @action move(oldIndex: number, newIndex: number) {
+        const child = this.moveDirectly(oldIndex, newIndex);
+        if (child !== undefined) {
+            this.emitDelta(() => new ChildMovedInSameContainmentDelta(this.container, this.containment, oldIndex, newIndex, child));
+        }
+    }
+
+}
+
+
+export class OptionalMultiContainmentValueManager<T extends INodeBase> extends MultiContainmentValueManager<T> {
+
+    constructor(containment: Containment, container: INodeBase) {
+        super(containment, container);
+        this.checkRequired(false);
+    }
+
+    @action remove(childToRemove: T) {
+        const children = this.getDirectly();
+        const index = children.findIndex((child) => child === childToRemove);
+        if (index > -1) {
+            children.splice(index, 1);
+            childToRemove.detach();
+            this.emitDelta(() => new ChildDeletedDelta(this.container, this.containment, index, childToRemove));
+        }
+    }
+
+}
+
+
+export class RequiredMultiContainmentValueManager<T extends INodeBase> extends MultiContainmentValueManager<T> {
+
+    constructor(containment: Containment, container: INodeBase) {
+        super(containment, container);
+        this.checkRequired(true);
+    }
+
+    get(): T[] {
+        const children = this.getDirectly();
+        if (children.length === 0) {
+            this.throwOnReadOfUnset();
+        }
+        return children;
+    }
+
+    @action remove(childToRemove: T) {
+        const children = this.getDirectly();
+        const index = children.findIndex((child) => child === childToRemove);
+        if (index > -1) {
+            if (children.length === 1) {
+                this.throwOnUnset();
+            }
+            children.splice(index, 1);
+            childToRemove.detach();
+            this.emitDelta(() => new ChildDeletedDelta(this.container, this.containment, index, childToRemove));
+        }
+    }
+
+}
+

package/src/value-managers/index.ts

@@ -0,0 +1,22 @@
+// 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 "./annotations.js";
+export * from "./base.js";
+export * from "./properties.js";
+export * from "./containments.js";
+export * from "./references.js";