Merge pull request #76 from Mochitto/feat/node-transformations

Added `Node.transformChildren`, `Node.replaceWith`

Author: alessiostalla

CHANGELOG.md

@@ -2,6 +2,12 @@
 All notable changes to this project from version 1.2.0 upwards are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
+## [Unreleased]
+
+### Added
+- `Node.transformChildren` to run a function on all the children of a Node
+- `Node.replaceWith` to replace a Node with another
+
 ## [1.6.29] – 2024-07-09
 
 ### Fixed

src/model/model.ts

@@ -340,6 +340,57 @@ export abstract class Node extends Origin implements Destination {
         return this;
     }
 
+    /**
+     * Replace the current Node with another Node
+     *
+     * @throws Error - if this.parent === undefined
+     */
+    replaceWith(other: Node): void {
+        if (!this.parent) {
+            throw new Error("Cannot replace a Node that has no parent")
+        }
+
+        this.parent.transformChildren(node => node === this ? other : node);
+    }
+
+    /**
+     * Apply the given `operation` function to
+     * all of the Node's children.
+     *
+     * It's possible to use both pure functions,
+     * to replace the nodes, and functions that mutate
+     * the nodes in-place.
+     */
+    transformChildren(operation: (node: Node) => Node): void {
+        const nodesNames = this.getChildNames();
+
+        nodesNames.forEach(nodeName => {
+            const propertyValue = this[nodeName];
+            if (propertyValue instanceof Node) {
+                const newNode = operation(propertyValue);
+                /*
+                 * Identity check;
+                 * If the variable is pointing to the same object,
+                 * the operation changed the Node in-place.
+                 */
+                if (newNode !== propertyValue) {
+                    this.setChild(nodeName, newNode);
+                }
+
+            } else if (Array.isArray(propertyValue)) {
+                propertyValue.forEach((element, index) => {
+                    if (element instanceof Node) {
+                        const newNode = operation(element);
+                        // Another identity check
+                        if (newNode !== element) {
+                            (propertyValue as Node[])[index] = newNode;
+                        }
+                    }
+                });
+            }
+        });
+    }
+
     withOrigin(origin?: Origin): this {
         this.origin = origin;
         return this;

tests/nodes/nodes.test.ts

@@ -0,0 +1,64 @@
+import { expect } from "chai";
+import { Box, SomeNode, SomeNodeInPackage } from "../nodes";
+
+describe('Node.transformChildren', () => {
+    let childNode1: SomeNode;
+    let childNode2: SomeNode;
+    let boxNode: Box;
+
+    beforeEach(() => {
+        childNode1 = new SomeNode("Child1");
+        childNode2 = new SomeNode("Child2");
+
+        boxNode = new Box("BoxNode", [childNode1, childNode2]);
+    })
+
+    it('should apply in-place transformation to each child node', () => {
+        const inPlaceTransformation = (node: SomeNode): SomeNode => {
+            node.a = node.a?.toUpperCase();
+            return node;
+        };
+
+        boxNode.transformChildren(inPlaceTransformation);
+
+        expect(boxNode.contents[0]["a"]).to.eq("CHILD1");
+        expect(boxNode.contents[0]).to.eq(childNode1);
+        expect(boxNode.contents[1]["a"]).to.eq("CHILD2");
+        expect(boxNode.contents[1]).to.eq(childNode2);
+    });
+
+    it('should replace children nodes when used with pure-functions', () => {
+        const replaceTransformation = (node: SomeNode): SomeNode => {
+            return new SomeNode(node.a?.toUpperCase())
+        };
+
+        boxNode.transformChildren(replaceTransformation);
+
+        expect(boxNode.contents[0]["a"]).to.eq("CHILD1");
+        expect(boxNode.contents[0]).to.not.eq(childNode1);
+        expect(boxNode.contents[1]["a"]).to.eq("CHILD2");
+        expect(boxNode.contents[1]).to.not.eq(childNode2);
+    });
+});
+
+describe('Node.replaceWith', () => {
+    it('should replace a child node with another node', () => {
+        const childNode1 = new SomeNode("Child1");
+        const childNode2 = new SomeNode("Child2");
+
+        const parentNode = new SomeNodeInPackage("ParentNode");
+
+        parentNode.setChild('someNode', childNode1);
+        expect(parentNode.getChildren('someNode')).to.eql([childNode1]);
+        childNode1.replaceWith(childNode2);
+        expect(parentNode.getChildren('someNode')).to.eql([childNode2]);
+    });
+
+    it('should throw error if parent is not set', () => {
+        const childNode1 = new SomeNode("Child1");
+
+        const nodeWithoutParent = new SomeNode("NodeWithoutParent");
+        expect(() => nodeWithoutParent.replaceWith(childNode1)).to.throw('Cannot replace a Node that has no parent');
+    });
+});
+