test the new option

Author: dakujem

src/Tree.php

@@ -32,7 +32,7 @@ public static function link(
         MovableNodeContract $node,
         MovableNodeContract $parent,
         string|int|null $key = null,
-        bool $preventDuplicateLinking = true,
+        bool $handleDuplicateLinking = true,
     ): ?MovableNodeContract {
         $currentParent = $node->parent();
 
@@ -48,7 +48,7 @@ public static function link(
         }
 
         // Create the parent-to-child link.
-        self::adoptChild($parent, $node, $key, $preventDuplicateLinking);
+        self::adoptChild($parent, $node, $key, $handleDuplicateLinking);
 
         // If a parent was unlinked during the process, return it.
         return $originalParent ?? null;
@@ -165,12 +165,12 @@ private static function adoptChild(
         MovableNodeContract $parent,
         MovableNodeContract $child,
         string|int|null $key,
-        bool $preventDuplicateLinking,
+        bool $handleDuplicateLinking,
     ): void {
         // Note:
         // The duplicate adding prevention is very slow for nodes with many siblings due to the child node lookup
         // (done by the `childKey` method), if not optimized internally.
-        $existing = $preventDuplicateLinking ? $parent->childKey($child) : null;
+        $existing = $handleDuplicateLinking ? $parent->childKey($child) : null;
         if (
             null !== $existing &&
             $parent->child($existing) === $child &&

tests/tree.phpt

@@ -4,6 +4,7 @@ declare(strict_types=1);
 
 namespace Dakujem\Test;
 
+use Dakujem\Oliva\Exceptions\ChildKeyCollision;
 use Dakujem\Oliva\Exceptions\NodeNotMovable;
 use Dakujem\Oliva\Node;
 use Dakujem\Oliva\Simple\NodeBuilder;
@@ -187,3 +188,42 @@ require_once __DIR__ . '/setup.php';
     Assert::same(['two' => $node2, 'three' => $node1], $parent->children());
 })();
 
+
+(function () {
+    //
+    // Duplicate linking of the same node without duplicate handling does not prevent adding the same node multiple times.
+    //
+
+    $node = new Node(null);
+    $parent = new Node(null);
+    Tree::link($node, $parent); // default index `0`
+
+    // this will add the same node duplicate under `1`,
+    // behaves like an array push
+    Tree::link($node, $parent, handleDuplicateLinking: false);
+    Assert::same([0 => $node, 1 => $node], $parent->children());
+    // this will add the same node yet again under `foo`
+    Tree::link($node, $parent, 'foo', handleDuplicateLinking: false);
+    Assert::same([0 => $node, 1 => $node, 'foo' => $node], $parent->children());
+
+    $node1 = new Node(null);
+    $node2 = new Node(null);
+    $children = ['one' => $node1, 'two' => $node2];
+    $parent = new Node(null, children: $children);
+    Assert::same($children, $parent->children()); // sanity check
+
+    // Attempting to add the same node under an existing (albeit same) key without duplicate node handling mechanism
+    // results in a ChildKeyCollision exception.
+    Assert::throws(function () use ($parent, $node1) {
+        Tree::link($node1, $parent, 'one', handleDuplicateLinking: false);
+    }, ChildKeyCollision::class);
+    Assert::throws(function () use ($parent, $node1) {
+        Tree::link($node1, $parent, 'two', handleDuplicateLinking: false);
+    }, ChildKeyCollision::class);
+
+    // Without the duplicate node handling mechanism, this call will allow adding the node as a duplicate child,
+    // possibly causing issues in the tree structure.
+    Tree::link($node1, $parent, 'three', handleDuplicateLinking: false);
+    Assert::same(['one' => $node1, 'two' => $node2, 'three' => $node1], $parent->children());
+})();
+