@lionweb/class-core 0.7.0-beta.12 → 0.7.0-beta.14

package/src/id-mapping.ts

@@ -30,35 +30,56 @@ type NodesById = { [id: LionWebId]: INodeBase }
  */
 export class IdMapping {
 
-    nodesById: NodesById;
+    private nodesById: NodesById;
     constructor(nodesById: NodesById) {
         this.nodesById = {...nodesById};
     }
     // TODO  consider using an instance of Map<Id, INodeBase> instead
 
-    fromId(id: LionWebId): INodeBase {
+    /**
+     * @return the {@link INodeBase node} with the given {@link LionWebId `id`}, or
+     * @throws an Error if no node with the given ID was registered.
+     */
+    fromId = (id: LionWebId): INodeBase => {
         if (!(id in this.nodesById)) {
             throw new Error(`node with id=${id} not in ID mapping`);
         }
         return this.nodesById[id];
     }
 
+    /**
+     * @return the {@link INodeBase node} with the given {@link LionWebId `id`},
+     * or `undefined` if no node with the given ID was registered.
+     */
     tryFromId = (id: LionWebId): (INodeBase | undefined) =>
         this.nodesById[id];
 
+    /**
+     * @return the {@link INodeBase node} referenced from the given {@link LionWebId ID},
+     * or `unresolved` if `unresolved` was passed in or no node with the given ID was registered.
+     */
     fromRefId = (idOrUnresolved: IdOrUnresolved): SingleRef<INodeBase> =>
-        idOrUnresolved === null
-            ? null
+        idOrUnresolved === unresolved
+            ? unresolved
             : (this.nodesById[idOrUnresolved] ?? unresolved);
 
     /**
      * Updates this {@link IdMapping} with the given `node` *and all its descendants* (recursively).
      */
-    updateWith(node: INodeBase) {
+    updateWith= (node: INodeBase) => {
         this.nodesById[node.id] = node;
         node.children   // recurse into all children
             .forEach((child) => this.updateWith(child));
     }
 
+    /**
+     * Re-initializes this {@link IdMapping ID mapping} with the given nodes-by-ID.
+     * This completely removes all registrations of nodes,
+     * and should only be used by components which are in complete control of the nodes being passed to this method.
+     */
+    reinitializeWith = (nodesById: NodesById) => {
+        this.nodesById = nodesById
+    }
+
 }
 

package/src/textualizer.ts

@@ -54,7 +54,7 @@ export const asTreeTextWith = (identificationFor: (node: INodeBase) => string):
                 const valueManager = node.getPropertyValueManager(feature)
                 const displayValue = (() => {
                     if (!valueManager.isSet()) {
-                        return `$<not set>`
+                        return `<not set>`
                     }
                     const value = valueManager.getDirectly()
                     if (feature.type === LionCore_builtinsBase.INSTANCE.String) {

package/src/value-managers/annotations.ts

@@ -17,7 +17,7 @@
 
 import { action, observable } from "mobx"
 
-import { INodeBase, removeFromParent } from "../base-types.js"
+import { INodeBase } from "../base-types.js"
 import { checkIndex, ValueManager } from "./base.js"
 import {
     AnnotationAddedDelta,
@@ -67,7 +67,7 @@ export class AnnotationsValueManager extends ValueManager {
             newAnnotation.attachTo(this.container, null);
             return false;
         } else {
-            const oldIndex = removeFromParent(oldParent, newAnnotation);
+            const oldIndex = oldParent.annotationsValueManager.removeDirectly(newAnnotation);
             newAnnotation.attachTo(this.container, null);
             return [oldParent, oldIndex];
         }

package/src/value-managers/base.ts

@@ -29,12 +29,12 @@ export abstract class ValueManager {
     }
 
     /**
-     * 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.
+     * Emits a delta if a {@link DeltaReceiver} is registered with the container.
+     * @param deltaThunk a thunk that generates the delta, and is only called when a delta receiver is registered with the container.
      */
     emitDelta(deltaThunk: () => IDelta) {
-        if (this.container.handleDelta) {
-            this.container.handleDelta(deltaThunk());
+        if (this.container.receiveDelta) {
+            this.container.receiveDelta(deltaThunk());
         }
     }
 

package/src/value-managers/containments.ts

@@ -18,12 +18,15 @@
 import { Containment } from "@lionweb/core"
 import { action, observable } from "mobx"
 
-import { INodeBase, removeFromParent } from "../base-types.js"
+import { INodeBase } from "../base-types.js"
 import {
     ChildAddedDelta,
     ChildDeletedDelta,
-    ChildMovedAndReplacedFromOtherContainmentInSameParentDelta, ChildMovedAndReplacedInSameContainmentDelta,
+    ChildMovedAndReplacedFromOtherContainmentDelta,
+    ChildMovedAndReplacedFromOtherContainmentInSameParentDelta,
+    ChildMovedAndReplacedInSameContainmentDelta,
     ChildMovedFromOtherContainmentDelta,
+    ChildMovedFromOtherContainmentInSameParentDelta,
     ChildMovedInSameContainmentDelta,
     ChildReplacedDelta
 } from "../deltas/index.js"
@@ -80,24 +83,38 @@ export abstract class SingleContainmentValueManager<T extends INodeBase> extends
         this.child.set(newChild);
     }
 
-    @action replaceWith(newChild: T) {
-        const oldChild = this.getDirectly();
-        if (oldChild === undefined) {
+    @action replaceWith(movedChild: T) {
+        const replacedChild = this.getDirectly();
+        if (replacedChild === undefined) {
             // not a proper replace, but an add-set => delegate to regular setter (— unfortunately, through necessarily “unfolding the hierarchy”):
             if (this instanceof OptionalSingleContainmentValueManager) {
-                this.set(newChild);
+                this.set(movedChild);
             }
             if (this instanceof RequiredSingleContainmentValueManager) {
-                this.set(newChild);
+                this.set(movedChild);
             }
         } else {
-            if (oldChild === newChild) {
+            if (replacedChild === movedChild) {
                 // do nothing: nothing's changed
             } else {
-                oldChild.detach();
-                this.setDirectly(newChild);
-                newChild.attachTo(this.container, this.feature);
-                this.emitDelta(() => new ChildReplacedDelta(this.container, this.feature, 0, oldChild, newChild));
+                if (movedChild.parent === undefined) {
+                    this.emitDelta(() => new ChildReplacedDelta(this.container, this.feature, 0, replacedChild, movedChild));
+                } else {
+                    if (movedChild.parent === this.container) {
+                        if (movedChild.containment === this.containment) {
+                            this.emitDelta(() => new ChildMovedAndReplacedInSameContainmentDelta(this.container, this.containment, 0, 0, movedChild, replacedChild));
+                        } else {
+                            const oldIndex = removeFromContainment(replacedChild);
+                            this.emitDelta(() => new ChildMovedAndReplacedFromOtherContainmentInSameParentDelta(this.container, movedChild.containment!, oldIndex, this.containment, 0, movedChild, replacedChild));
+                        }
+                    } else {
+                        const oldIndex = removeFromContainment(replacedChild);
+                        this.emitDelta(() => new ChildMovedAndReplacedFromOtherContainmentDelta(this.container, this.containment, 0, movedChild, movedChild.parent!, movedChild.containment!, oldIndex, replacedChild));
+                    }
+                }
+                this.setDirectly(movedChild);
+                movedChild.attachTo(this.container, this.containment);
+                replacedChild.detach();
             }
         }
     }
@@ -124,7 +141,7 @@ export class OptionalSingleContainmentValueManager<T extends INodeBase> extends
             } else {
                 if (newChild.parent && newChild.containment) {
                     const oldParent = newChild.parent;
-                    removeFromParent(oldParent, newChild);
+                    removeFromContainment(newChild);
                     this.emitDelta(() => new ChildMovedFromOtherContainmentDelta(oldParent, newChild.containment!, 0, this.container, this.feature, 0, newChild));
                 } else {
                     this.emitDelta(() => new ChildAddedDelta(this.container, this.feature, 0, newChild));
@@ -141,13 +158,14 @@ export class OptionalSingleContainmentValueManager<T extends INodeBase> extends
                 if (oldChild === newChild) {
                     // do nothing: nothing's changed
                 } else {
+                    // FIXME  this could emit 2 deltas where it should be a single ChildReplaced-delta
                     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);
+                        removeFromContainment(newChild);
                     }
                     this.setDirectly(newChild);
                     newChild.attachTo(this.container, this.feature);
@@ -183,7 +201,7 @@ export class RequiredSingleContainmentValueManager<T extends INodeBase> extends
             } else {
                 if (newChild.parent && newChild.containment) {
                     const oldParent = newChild.parent;
-                    removeFromParent(oldParent, newChild);
+                    removeFromContainment(newChild);
                     this.emitDelta(() => new ChildMovedFromOtherContainmentDelta(oldParent, newChild.containment!, 0, this.container, this.feature, 0, newChild));
                 } else {
                     this.emitDelta(() => new ChildAddedDelta(this.container, this.feature, 0, newChild));
@@ -204,7 +222,7 @@ export class RequiredSingleContainmentValueManager<T extends INodeBase> extends
                     }
                     oldChild.detach();
                     if (newChild.parent && newChild.containment) {
-                        removeFromParent(newChild.parent, newChild);
+                        removeFromContainment(newChild);
                     }
                     this.setDirectly(newChild);
                     newChild.attachTo(this.container, this.feature);
@@ -251,16 +269,31 @@ export abstract class MultiContainmentValueManager<T extends INodeBase> extends
         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));
+    @action insertAtIndex(newChild: T, newIndex: number) {
+        if (newChild.parent === undefined) {
+            this.insertAtIndexDirectly(newChild, newIndex);
+            newChild.attachTo(this.container, this.containment);
+            this.emitDelta(() => new ChildAddedDelta(this.container, this.containment, newIndex, newChild));
         } else {
-            const oldIndex = removeFromParent(newChild.parent, newChild);
-            this.emitDelta(() => new ChildMovedFromOtherContainmentDelta(newChild.parent!, newChild.containment!, oldIndex, this.container, this.containment, index, newChild));
-            newChild.detach();
+            if (newChild.parent === this.container) {
+                if (newChild.containment === this.containment) {
+                    const oldIndex = this.children.indexOf(newChild);
+                    this.moveDirectly(oldIndex, newIndex);
+                    this.emitDelta(() => new ChildMovedInSameContainmentDelta(this.container, this.containment, oldIndex, newIndex, newChild));
+                } else {
+                    const oldIndex = removeFromContainment(newChild);
+                    checkIndex(newIndex, this.children.length, true);
+                    this.insertAtIndexDirectly(newChild, newIndex);
+                    this.emitDelta(() => new ChildMovedFromOtherContainmentInSameParentDelta(this.container, newChild.containment!, oldIndex, newChild, this.containment, newIndex));
+                    newChild.attachTo(this.container, this.containment);
+                }
+            } else {
+                const oldIndex = removeFromContainment(newChild);
+                this.insertAtIndexDirectly(newChild, newIndex);
+                this.emitDelta(() => new ChildMovedFromOtherContainmentDelta(newChild.parent!, newChild.containment!, oldIndex, this.container, this.containment, newIndex, newChild));
+                newChild.attachTo(this.container, this.containment);
+            }
         }
-        newChild.attachTo(this.container, this.containment);
     }
 
     @action removeDirectly(childToRemove: T): number {
@@ -298,18 +331,20 @@ export abstract class MultiContainmentValueManager<T extends INodeBase> extends
 
     @action replaceAtIndex(movedChild: T, newIndex: number) {
         checkIndex(newIndex, this.children.length, false);
+        if (movedChild.parent === undefined) {
+            throw new Error(`a child-to-move (id=${movedChild.id}) must already be contained`);
+        }
         const replacedChild = this.children[newIndex];
         if (replacedChild === movedChild) {
             // do nothing: nothing's changed
         } else {
             this.children.splice(newIndex, 1, movedChild);
-            if (replacedChild.parent) {
+            if (replacedChild.parent !== undefined) {
                 const oldValueManager = replacedChild.parent.getContainmentValueManager(replacedChild.containment!);
                 const oldIndex = oldValueManager instanceof SingleContainmentValueManager
                     ? 0
                     // eslint-disable-next-line @typescript-eslint/no-explicit-any
                     : (oldValueManager as MultiContainmentValueManager<any>).children.indexOf(replacedChild);
-                replacedChild.detach();
                 if (replacedChild.parent === movedChild.parent) {
                     if (replacedChild.containment === movedChild.containment) {
                         this.emitDelta(() => new ChildMovedAndReplacedInSameContainmentDelta(this.container, this.containment, oldIndex, newIndex, movedChild, replacedChild));
@@ -317,8 +352,9 @@ export abstract class MultiContainmentValueManager<T extends INodeBase> extends
                         this.emitDelta(() => new ChildMovedAndReplacedFromOtherContainmentInSameParentDelta(this.container, replacedChild.containment!, oldIndex, this.containment, newIndex, movedChild, replacedChild));
                     }
                 } else {
-                    this.emitDelta(() => new ChildMovedFromOtherContainmentDelta(replacedChild.parent!, replacedChild.containment!, oldIndex, this.container, this.containment, newIndex, movedChild));
+                    this.emitDelta(() => new ChildMovedAndReplacedFromOtherContainmentDelta(this.container, this.containment, newIndex, movedChild, movedChild.parent!, movedChild.containment!, oldIndex, replacedChild));
                 }
+                replacedChild.detach();
             } else {
                 // not a move+replace, but a regular replace instead:
                 this.emitDelta(() => new ChildReplacedDelta(this.container, this.containment, newIndex, replacedChild, movedChild));
@@ -380,3 +416,27 @@ export class RequiredMultiContainmentValueManager<T extends INodeBase> extends M
 
 }
 
+/**
+ * Removes the given child node from its containment, and returns the containment index it had before removal.
+ */
+const removeFromContainment = (child: INodeBase): number => {
+    if (child.parent === undefined) {
+        throw new Error(`can't remove an orphan from its parent`)
+    }
+    if (child.containment === undefined) {
+        throw new Error(`can't remove an orphan from its containing feature`)
+    }
+    if (child.containment === null) {
+        throw new Error(`can't remove an annotation`)
+    }
+    const valueManager = child.parent.getContainmentValueManager(child.containment)
+    if (valueManager instanceof SingleContainmentValueManager) {
+        valueManager.setDirectly(undefined)
+        return 0
+    } else if (valueManager instanceof MultiContainmentValueManager) {
+        return valueManager.removeDirectly(child)
+    } else {
+        throw new Error(`don't know how to remove a child that's contained through a value manager of type ${valueManager.constructor.name}`)
+    }
+}
+

package/src/value-managers/references.ts

@@ -106,7 +106,7 @@ export class OptionalSingleReferenceValueManager<T extends INodeBase> extends Si
             if (oldTarget === undefined) {
                 this.emitDelta(() => new ReferenceAddedDelta(this.container, this.reference, 0, newTarget));
             } else {
-                this.emitDelta(() => new ReferenceChangedDelta(this.container, this.reference, 0, oldTarget, newTarget));
+                this.emitDelta(() => new ReferenceChangedDelta(this.container, this.reference, 0, newTarget, oldTarget));
             }
         }
     }
@@ -142,7 +142,7 @@ export class RequiredSingleReferenceValueManager<T extends INodeBase> extends Si
             if (oldTarget === undefined) {
                 this.emitDelta(() => new ReferenceAddedDelta(this.container, this.reference, 0, newTarget));
             } else {
-                this.emitDelta(() => new ReferenceChangedDelta(this.container, this.reference, 0, oldTarget, newTarget));
+                this.emitDelta(() => new ReferenceChangedDelta(this.container, this.reference, 0, newTarget, oldTarget));
             }
         }
     }

package/dist/deltas/handlers.d.ts

@@ -1,17 +0,0 @@
-import { IDelta } from "./base.js";
-/**
- * A type for functions that handle deltas.
- */
-export type DeltaHandler = (delta: IDelta) => void;
-export declare const collectingDeltaHandler: (printSerializations?: boolean) => [DeltaHandler, IDelta[]];
-/**
- * An interface for {@link DeltaHandler delta handlers} that can be switched on and off — “latching”.
- */
-export interface LatchingDeltaHandler extends DeltaHandler {
-    latch(emitDeltas: boolean): void;
-}
-/**
- * @return a latching version of the given {@link DeltaHandler delta handler}.
- */
-export declare const latching: (handleDelta: DeltaHandler) => LatchingDeltaHandler;
-//# sourceMappingURL=handlers.d.ts.map

package/dist/deltas/handlers.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"handlers.d.ts","sourceRoot":"","sources":["../../src/deltas/handlers.ts"],"names":[],"mappings":"AAiBA,OAAO,EAAE,MAAM,EAAE,MAAM,WAAW,CAAA;AAIlC;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;AAEnD,eAAO,MAAM,sBAAsB,GAAI,6BAA2B,KAAG,CAAC,YAAY,EAAE,MAAM,EAAE,CAS3F,CAAC;AAGF;;GAEG;AACH,MAAM,WAAW,oBAAqB,SAAQ,YAAY;IACtD,KAAK,CAAC,UAAU,EAAE,OAAO,GAAG,IAAI,CAAC;CACpC;AAED;;GAEG;AACH,eAAO,MAAM,QAAQ,GAAI,aAAa,YAAY,KAAG,oBAcpD,CAAC"}

package/dist/deltas/handlers.js

@@ -1,43 +0,0 @@
-// 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 { serializeDelta } from "./serialization/index.js";
-export const collectingDeltaHandler = (printSerializations = false) => {
-    const deltas = [];
-    const handleDelta = (delta) => {
-        deltas.push(delta);
-        if (printSerializations) {
-            console.log(JSON.stringify(serializeDelta(delta), null, 4));
-        }
-    };
-    return [handleDelta, deltas];
-};
-/**
- * @return a latching version of the given {@link DeltaHandler delta handler}.
- */
-export const latching = (handleDelta) => {
-    let emitDeltas = false;
-    return Object.assign((delta) => {
-        if (emitDeltas) {
-            handleDelta(delta);
-        }
-    }, {
-        latch(emitDeltas_) {
-            emitDeltas = emitDeltas_;
-        },
-    });
-};
-//# sourceMappingURL=handlers.js.map

package/dist/deltas/handlers.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"handlers.js","sourceRoot":"","sources":["../../src/deltas/handlers.ts"],"names":[],"mappings":"AAAA,wDAAwD;AACxD,EAAE;AACF,iEAAiE;AACjE,mEAAmE;AACnE,0CAA0C;AAC1C,EAAE;AACF,iDAAiD;AACjD,EAAE;AACF,sEAAsE;AACtE,oEAAoE;AACpE,2EAA2E;AAC3E,sEAAsE;AACtE,iCAAiC;AACjC,EAAE;AACF,sEAAsE;AACtE,sCAAsC;AAGtC,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAA;AAQzD,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,mBAAmB,GAAG,KAAK,EAA4B,EAAE;IAC5F,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,MAAM,WAAW,GAAiB,CAAC,KAAK,EAAE,EAAE;QACxC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACnB,IAAI,mBAAmB,EAAE,CAAC;YACtB,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,cAAc,CAAC,KAAK,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;QAChE,CAAC;IACL,CAAC,CAAC;IACF,OAAO,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC;AACjC,CAAC,CAAC;AAUF;;GAEG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,WAAyB,EAAwB,EAAE;IACxE,IAAI,UAAU,GAAG,KAAK,CAAC;IACvB,OAAO,MAAM,CAAC,MAAM,CAChB,CAAC,KAAa,EAAE,EAAE;QACd,IAAI,UAAU,EAAE,CAAC;YACb,WAAW,CAAC,KAAK,CAAC,CAAC;QACvB,CAAC;IACL,CAAC,EACD;QACI,KAAK,CAAC,WAAoB;YACtB,UAAU,GAAG,WAAW,CAAC;QAC7B,CAAC;KACJ,CACJ,CAAC;AACN,CAAC,CAAC"}

package/src/deltas/handlers.ts

@@ -1,64 +0,0 @@
-// 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 { IDelta } from "./base.js"
-import { serializeDelta } from "./serialization/index.js"
-
-
-/**
- * A type for functions that handle deltas.
- */
-export type DeltaHandler = (delta: IDelta) => void;
-
-export const collectingDeltaHandler = (printSerializations = false): [DeltaHandler, IDelta[]] => {
-    const deltas: IDelta[] = [];
-    const handleDelta: DeltaHandler = (delta) => {
-        deltas.push(delta);
-        if (printSerializations) {
-            console.log(JSON.stringify(serializeDelta(delta), null, 4));
-        }
-    };
-    return [handleDelta, deltas];
-};
-
-
-/**
- * An interface for {@link DeltaHandler delta handlers} that can be switched on and off — “latching”.
- */
-export interface LatchingDeltaHandler extends DeltaHandler {
-    latch(emitDeltas: boolean): void;
-}
-
-/**
- * @return a latching version of the given {@link DeltaHandler delta handler}.
- */
-export const latching = (handleDelta: DeltaHandler): LatchingDeltaHandler => {
-    let emitDeltas = false;
-    return Object.assign(
-        (delta: IDelta) => {
-            if (emitDeltas) {
-                handleDelta(delta);
-            }
-        },
-        {
-            latch(emitDeltas_: boolean) {
-                emitDeltas = emitDeltas_;
-            },
-        },
-    );
-};
-