@lionweb/class-core 0.7.0-beta.9 → 0.7.0

package/src/deltas/compositor.ts

@@ -0,0 +1,107 @@
+// 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 { CompositeDelta, DeltaReceiver, IDelta } from "../index.js"
+
+
+/**
+ * A *delta compositor* is used to *aggregate* deltas as {@link CompositeDelta composite deltas}.
+ *
+ * Usage:
+ * ```typescript
+ * const compositor = new Compositor(downstreamReceiveDelta);
+ * compositor.openComposite();
+ * // ...
+ * compositor.upstreamReceiveDelta(<delta>);
+ * // ...
+ * compositor.closeComposite();
+ * ```
+ */
+export class DeltaCompositor {
+
+    /**
+     * The {@link DeltaReceiver} implementation that either forwards to the given downstream delta handle
+     * or gathers deltas into composite deltas to forward to the downstream delta receiver later.
+     */
+    readonly upstreamReceiveDelta: DeltaReceiver;
+
+    /**
+     * An array of arrays of {@link IDelta deltas}, comprising a “stack”.
+     *
+     * Invariants:
+     *  - (I1) composite has been opened &hArr; `this.deltasInComposite !== undefined` / `Array.isArray(this.deltasInComposite)`
+     *  - (I2) this.deltasStack is either undefined or an array containing at least one array
+     */
+    private deltasStack: IDelta[][] | undefined = undefined;
+
+    /**
+     * @param downstreamReceiveDelta the {@link DeltaReceiver} that deltas get passed to.
+     * @param maximumNestingDepth the maximum depth that composites can be nested.
+     *  A maximum depth of e.g. 1 means that at most 1 composite can be open at any time.
+     */
+    constructor(private readonly downstreamReceiveDelta: DeltaReceiver, private readonly maximumNestingDepth: number = Infinity) {
+        if (maximumNestingDepth !== Infinity && (!Number.isInteger(maximumNestingDepth) || maximumNestingDepth < 0)) {
+            throw new Error(`maximum nesting depth must be a non-negative integer`);
+        }
+        this.upstreamReceiveDelta = (delta) => {
+            if (this.deltasStack === undefined) {
+                // pass on immediately:
+                this.downstreamReceiveDelta(delta);
+            } else {
+                // store for later:
+                this.deltasStack[this.deltasStack.length - 1].push(delta);  // (I2)
+            }
+        };
+    }
+
+    /**
+     * Opens a composite, meaning that all deltas passed to the {@link upstreamReceiveDelta} are gathered into a composite delta
+     * that gets forwarded to the downstream delta receiver as soon as the composite is closed.
+     *
+     * Composites can be nested, to the maximum depth configured through this class’ constructor,
+     * beyond which an error gets thrown.
+     */
+    openComposite = (): void => {
+        if (this.deltasStack === undefined) {
+            this.deltasStack = [];  // ==> (I1) + 1st half of (I2)
+        }
+        if (this.deltasStack.length >= this.maximumNestingDepth) {
+            throw new Error(`attempt occurred to start a nested composition exceeding the maximum nesting depth`)
+        }
+        this.deltasStack.push([]);  // ==> 2nd half of (I2)
+    }
+
+    /**
+     * Closes the current composite, producing the deltas gathered for this composite into a composite delta.
+     * Composites can be nested, and deltas only get forwarded to the downstream delta receiver after the top-level composite has been closed.
+     */
+    closeComposite = (): void => {
+        if (this.deltasStack === undefined) {
+            throw new Error(`attempt occurred to finish a composite without one being started`);
+        }
+
+        const parts = this.deltasStack.pop()!;  // is an array because of (I2)
+        if (this.deltasStack.length === 0) {    // last array popped from stack
+            this.deltasStack = undefined;   // maintain (I2)
+        }
+        if (parts.length > 0) {
+            this.upstreamReceiveDelta(new CompositeDelta(parts));
+        }
+    }
+
+}
+

package/src/deltas/index.ts

@@ -17,7 +17,9 @@
 
 export * from "./appliers.js";
 export * from "./base.js";
-export * from "./handlers.js";
+export * from "./compositor.js";
 export * from "./inverters.js";
+export * from "./receivers.js";
 export * from "./types.g.js";
 export * from "./serialization/index.js";
+

package/src/deltas/inverters.ts

@@ -18,23 +18,36 @@
 import {
     AnnotationAddedDelta,
     AnnotationDeletedDelta,
+    AnnotationMovedAndReplacedFromOtherParentDelta,
+    AnnotationMovedAndReplacedInSameParentDelta,
     AnnotationMovedFromOtherParentDelta,
     AnnotationMovedInSameParentDelta,
     AnnotationReplacedDelta,
     ChildAddedDelta,
     ChildDeletedDelta,
-    ChildMovedDelta,
+    ChildMovedAndReplacedFromOtherContainmentDelta,
+    ChildMovedAndReplacedFromOtherContainmentInSameParentDelta,
+    ChildMovedAndReplacedInSameContainmentDelta,
+    ChildMovedFromOtherContainmentDelta,
+    ChildMovedFromOtherContainmentInSameParentDelta,
     ChildMovedInSameContainmentDelta,
     ChildReplacedDelta,
+    CompositeDelta,
+    EntryMovedAndReplacedFromOtherReferenceDelta,
+    EntryMovedAndReplacedFromOtherReferenceInSameParentDelta,
+    EntryMovedAndReplacedInSameReferenceDelta,
+    EntryMovedFromOtherReferenceDelta,
+    EntryMovedFromOtherReferenceInSameParentDelta,
+    EntryMovedInSameReferenceDelta,
     NoOpDelta,
+    PartitionAddedDelta,
+    PartitionDeletedDelta,
     PropertyAddedDelta,
     PropertyChangedDelta,
     PropertyDeletedDelta,
     ReferenceAddedDelta,
-    ReferenceDeletedDelta,
-    ReferenceMovedDelta,
-    ReferenceMovedInSameReferenceDelta,
-    ReferenceReplacedDelta
+    ReferenceChangedDelta,
+    ReferenceDeletedDelta
 } from "./types.g.js"
 import { IDelta } from "./base.js"
 
@@ -44,52 +57,57 @@ import { IDelta } from "./base.js"
  * in the sense that it undoes that delta after it has been applied.
  */
 export const invertDelta = (delta: IDelta): IDelta => {
-    if (delta instanceof NoOpDelta) {
-        return delta;
+    if (delta instanceof PartitionAddedDelta) {
+        return new PartitionDeletedDelta(delta.newPartition);
     }
-
-    if (delta instanceof PropertyAddedDelta) {
-        return new PropertyDeletedDelta(delta.container, delta.property, delta.value);
+    if (delta instanceof PartitionDeletedDelta) {
+        return new PartitionAddedDelta(delta.deletedPartition);
     }
-    if (delta instanceof PropertyChangedDelta) {
-        return new PropertyChangedDelta(delta.container, delta.property, delta.newValue, delta.oldValue);
+    if (delta instanceof PropertyAddedDelta) {
+        return new PropertyDeletedDelta(delta.node, delta.property, delta.value);
     }
     if (delta instanceof PropertyDeletedDelta) {
-        return new PropertyAddedDelta(delta.container, delta.property, delta.oldValue);
+        return new PropertyAddedDelta(delta.node, delta.property, delta.oldValue);
+    }
+    if (delta instanceof PropertyChangedDelta) {
+        return new PropertyChangedDelta(delta.node, delta.property, delta.newValue, delta.oldValue);
     }
-
     if (delta instanceof ChildAddedDelta) {
         return new ChildDeletedDelta(delta.parent, delta.containment, delta.index, delta.newChild);
     }
-    if (delta instanceof ChildReplacedDelta) {
-        return new ChildReplacedDelta(delta.parent, delta.containment, delta.index, delta.newChild, delta.replacedChild);
-    }
-    if (delta instanceof ChildMovedDelta) {
-        return new ChildMovedDelta(delta.newParent, delta.newContainment, delta.newIndex, delta.oldParent, delta.oldContainment, delta.oldIndex, delta.child);
-    }
-    if (delta instanceof ChildMovedInSameContainmentDelta) {
-        return new ChildMovedInSameContainmentDelta(delta.parent, delta.containment, delta.newIndex, delta.oldIndex, delta.child);
-    }
     if (delta instanceof ChildDeletedDelta) {
         return new ChildAddedDelta(delta.parent, delta.containment, delta.index, delta.deletedChild);
     }
-
-    if (delta instanceof ReferenceAddedDelta) {
-        return new ReferenceDeletedDelta(delta.container, delta.reference, delta.index, delta.newTarget);
-    }
-    if (delta instanceof ReferenceReplacedDelta) {
-        return new ReferenceReplacedDelta(delta.container, delta.reference, delta.index, delta.newTarget, delta.replacedTarget);
+    if (delta instanceof ChildReplacedDelta) {
+        return new ChildReplacedDelta(delta.parent, delta.containment, delta.index, delta.newChild, delta.replacedChild);
     }
-    if (delta instanceof ReferenceMovedDelta) {
-        return new ReferenceMovedDelta(delta.newContainer, delta.newReference, delta.newIndex, delta.oldContainer, delta.oldReference, delta.oldIndex, delta.target);
+    if (delta instanceof ChildMovedFromOtherContainmentDelta) {
+        return new ChildMovedFromOtherContainmentDelta(delta.newParent, delta.newContainment, delta.newIndex, delta.oldParent, delta.oldContainment, delta.oldIndex, delta.movedChild);
     }
-    if (delta instanceof ReferenceMovedInSameReferenceDelta) {
-        return new ReferenceMovedInSameReferenceDelta(delta.container, delta.reference, delta.newIndex, delta.oldIndex, delta.target);
+    if (delta instanceof ChildMovedFromOtherContainmentInSameParentDelta) {
+        return new ChildMovedFromOtherContainmentInSameParentDelta(delta.parent, delta.newContainment, delta.newIndex, delta.movedChild, delta.oldContainment, delta.oldIndex);
     }
-    if (delta instanceof ReferenceDeletedDelta) {
-        return new ReferenceAddedDelta(delta.container, delta.reference, delta.index, delta.deletedTarget);
+    if (delta instanceof ChildMovedInSameContainmentDelta) {
+        return new ChildMovedInSameContainmentDelta(delta.parent, delta.containment, delta.newIndex, delta.oldIndex, delta.movedChild);
+    }
+    if (delta instanceof ChildMovedAndReplacedFromOtherContainmentDelta) {
+        return new CompositeDelta([
+            new ChildMovedFromOtherContainmentDelta(delta.newParent, delta.newContainment, delta.newIndex, delta.oldParent, delta.oldContainment, delta.oldIndex, delta.movedChild),
+            new ChildAddedDelta(delta.newParent, delta.newContainment, delta.newIndex, delta.replacedChild)
+        ]);
+    }
+    if (delta instanceof ChildMovedAndReplacedFromOtherContainmentInSameParentDelta) {
+        return new CompositeDelta([
+            new ChildMovedFromOtherContainmentInSameParentDelta(delta.parent, delta.newContainment, delta.newIndex, delta.movedChild, delta.oldContainment, delta.oldIndex),
+            new ChildAddedDelta(delta.parent, delta.newContainment, delta.newIndex, delta.replacedChild)
+        ]);
+    }
+    if (delta instanceof ChildMovedAndReplacedInSameContainmentDelta) {
+        return new CompositeDelta([
+            new ChildMovedInSameContainmentDelta(delta.parent, delta.containment, delta.newIndex, delta.oldIndex, delta.movedChild),
+            new ChildAddedDelta(delta.parent, delta.containment, delta.newIndex, delta.replacedChild)
+        ]);
     }
-
     if (delta instanceof AnnotationAddedDelta) {
         return new AnnotationDeletedDelta(delta.parent, delta.index, delta.newAnnotation);
     }
@@ -105,6 +123,60 @@ export const invertDelta = (delta: IDelta): IDelta => {
     if (delta instanceof AnnotationMovedInSameParentDelta) {
         return new AnnotationMovedInSameParentDelta(delta.parent, delta.newIndex, delta.oldIndex, delta.movedAnnotation);
     }
+    if (delta instanceof AnnotationMovedAndReplacedFromOtherParentDelta) {
+        return new CompositeDelta([
+            new AnnotationMovedFromOtherParentDelta(delta.newParent, delta.newIndex, delta.oldParent, delta.oldIndex, delta.movedAnnotation),
+            new AnnotationAddedDelta(delta.newParent, delta.newIndex, delta.replacedAnnotation)
+        ]);
+    }
+    if (delta instanceof AnnotationMovedAndReplacedInSameParentDelta) {
+        return new CompositeDelta([
+            new AnnotationMovedInSameParentDelta(delta.parent, delta.newIndex, delta.oldIndex, delta.movedAnnotation),
+            new AnnotationAddedDelta(delta.parent, delta.newIndex, delta.replacedAnnotation)
+        ]);
+    }
+    if (delta instanceof ReferenceAddedDelta) {
+        return new ReferenceDeletedDelta(delta.parent, delta.reference, delta.index, delta.newTarget);
+    }
+    if (delta instanceof ReferenceDeletedDelta) {
+        return new ReferenceAddedDelta(delta.parent, delta.reference, delta.index, delta.deletedTarget);
+    }
+    if (delta instanceof ReferenceChangedDelta) {
+        return new ReferenceChangedDelta(delta.parent, delta.reference, delta.index, delta.oldTarget, delta.newTarget);
+    }
+    if (delta instanceof EntryMovedFromOtherReferenceDelta) {
+        return new EntryMovedFromOtherReferenceDelta(delta.newParent, delta.newReference, delta.newIndex, delta.oldParent, delta.oldReference, delta.oldIndex, delta.movedTarget);
+    }
+    if (delta instanceof EntryMovedFromOtherReferenceInSameParentDelta) {
+        return new EntryMovedFromOtherReferenceInSameParentDelta(delta.parent, delta.newReference, delta.newIndex, delta.oldReference, delta.oldIndex, delta.movedTarget);
+    }
+    if (delta instanceof EntryMovedInSameReferenceDelta) {
+        return new EntryMovedInSameReferenceDelta(delta.parent, delta.reference, delta.newIndex, delta.oldIndex, delta.movedTarget);
+    }
+    if (delta instanceof EntryMovedAndReplacedFromOtherReferenceDelta) {
+        return new CompositeDelta([
+            new EntryMovedFromOtherReferenceDelta(delta.newParent, delta.newReference, delta.newIndex, delta.oldParent, delta.oldReference, delta.oldIndex, delta.movedTarget),
+            new ReferenceAddedDelta(delta.newParent, delta.newReference, delta.newIndex, delta.replacedTarget)
+        ]);
+    }
+    if (delta instanceof EntryMovedAndReplacedFromOtherReferenceInSameParentDelta) {
+        return new CompositeDelta([
+            new EntryMovedFromOtherReferenceInSameParentDelta(delta.parent, delta.newReference, delta.newIndex, delta.oldReference, delta.oldIndex, delta.movedTarget),
+            new ReferenceAddedDelta(delta.parent, delta.newReference, delta.newIndex, delta.replacedTarget)
+        ]);
+    }
+    if (delta instanceof EntryMovedAndReplacedInSameReferenceDelta) {
+        return new CompositeDelta([
+            new EntryMovedInSameReferenceDelta(delta.parent, delta.reference, delta.newIndex, delta.oldIndex, delta.movedTarget),
+            new ReferenceAddedDelta(delta.parent, delta.reference, delta.newIndex, delta.replacedTarget)
+        ]);
+    }
+    if (delta instanceof CompositeDelta) {
+        return new CompositeDelta(delta.parts.map(invertDelta));
+    }
+    if (delta instanceof NoOpDelta) {
+        return delta;
+    }
 
     throw new Error(`inversion of delta of class ${delta.constructor.name} not implemented`);
 }

package/src/deltas/receivers.ts

@@ -0,0 +1,92 @@
+// 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 { asPrettyJsonString } from "@lionweb/ts-utils"
+import { IDelta } from "./base.js"
+import { serializeDelta } from "./serialization/index.js"
+
+/**
+ * A type for functions that receive deltas.
+ */
+export type DeltaReceiver = (delta: IDelta) => void;
+
+/**
+ * Legacy alias for {@link DeltaReceiver}.
+ */
+export type DeltaHandler = (delta: IDelta) => void;
+
+/**
+ * @return a tuple consisting of a {@link DeltaReceiver} implementation (as 1st member) that pushes any received delta unto the tuple's 2nd member: an array of {@link IDelta deltas}.
+ * @param printSerializations determines whether the deltas are serialized as JSON and printed to the JavaScript console.
+ */
+export const collectingDeltaReceiver = (printSerializations = false): [DeltaReceiver, IDelta[]] => {
+    const deltas: IDelta[] = [];
+    const receiveDelta: DeltaReceiver = (delta) => {
+        deltas.push(delta);
+        if (printSerializations) {
+            console.log(asPrettyJsonString(serializeDelta(delta)));
+        }
+    };
+    return [receiveDelta, deltas];
+};
+
+/**
+ * Legacy alias for {@link collectingDeltaReceiver}.
+ */
+export const collectingDeltaHandler = collectingDeltaReceiver;
+
+/**
+ * An interface for {@link DeltaReceiver delta receivers} that can be switched on and off — “latchingDeltaReceiverFrom”.
+ */
+export interface LatchingDeltaReceiver extends DeltaReceiver {
+    latch(emitDeltas: boolean): void;
+}
+
+/**
+ * Legacy alias for {@link LatchingDeltaReceiver}.
+ */
+export interface LatchingDeltaHandler extends LatchingDeltaReceiver {};
+
+/**
+ * @return a latching version of the given {@link DeltaReceiver delta receiver}.
+ */
+export const latchingDeltaReceiverFrom = (receiveDelta: DeltaReceiver): LatchingDeltaReceiver => {
+    let emitDeltas = false;
+    return Object.assign(
+        (delta: IDelta) => {
+            if (emitDeltas) {
+                receiveDelta(delta);
+            }
+        },
+        {
+            latch(emitDeltas_: boolean) {
+                emitDeltas = emitDeltas_;
+            },
+        },
+    );
+};
+
+
+/**
+ * @return a {@link DeltaReceiver delta receiver} implementation that forwards received deltas to the given {@link DeltaReceiver delta receivers}.
+ * This is necessary e.g. for combining using the delta protocol with an undo mechanism.
+ */
+export const deltaReceiverForwardingTo = (...deltaReceivers: DeltaReceiver[]): DeltaReceiver =>
+    (delta) => {
+        deltaReceivers.forEach((receiveDelta) => receiveDelta(delta));
+    };
+