Tweaking the public API and internal names for consistence

src/MaterializedPath/Path.php

@@ -4,6 +4,7 @@
 
 namespace Dakujem\Oliva\MaterializedPath;
 
+use Dakujem\Oliva\TreeNodeContract;
 use LogicException;
 
 /**
@@ -25,7 +26,10 @@ public static function delimited(string $delimiter, callable $accessor): callabl
         if (strlen($delimiter) !== 1) {
             throw new LogicException('The delimiter must be a single character.');
         }
-        return function (mixed $data) use ($delimiter, $accessor): array {
+        return function (mixed $data, mixed $inputIndex = null, ?TreeNodeContract $node = null) use (
+            $delimiter,
+            $accessor,
+        ): array {
             $path = $accessor($data);
             if (null === $path) {
                 return [];
@@ -53,7 +57,10 @@ public static function delimited(string $delimiter, callable $accessor): callabl
      */
     public static function fixed(int $levelWidth, callable $accessor): callable
     {
-        return function (mixed $data) use ($levelWidth, $accessor): array {
+        return function (mixed $data, mixed $inputIndex = null, ?TreeNodeContract $node = null) use (
+            $levelWidth,
+            $accessor,
+        ): array {
             $path = $accessor($data);
             if (null === $path || $path === '') {
                 return [];

src/MaterializedPath/TreeBuilder.php

@@ -50,7 +50,7 @@ final class TreeBuilder
      * signature `fn(mixed $data): MovableNodeContract`.
      * @var callable
      */
-    private $node;
+    private $factory;
 
     /**
      * Extractor of the node vector,
@@ -63,7 +63,7 @@ public function __construct(
         callable $node,
         callable $vector,
     ) {
-        $this->node = $node;
+        $this->factory = $node;
         $this->vector = $vector;
     }
 
@@ -80,7 +80,7 @@ public function processInput(iterable $input): AlmostThere
     {
         $shadowRoot = $this->buildShadowTree(
             $input,
-            $this->node,
+            $this->factory,
             $this->vector,
         );
 

src/Node.php

@@ -42,7 +42,7 @@ public function children(): array
     }
 
     /**
-     * Discover whether the given node is one or the given key points to one of this node's children.
+     * Discover whether the given node is one of this node's children (or the given key points to one of them).
      */
     public function hasChild(TreeNodeContract|string|int $child): bool
     {
@@ -58,7 +58,7 @@ public function hasChild(TreeNodeContract|string|int $child): bool
 
     /**
      * Get a specific child, if possible.
-     * Returns `null` when there is no such a child.
+     * Returns `null` when there is no such child.
      */
     public function child(int|string $key): ?TreeNodeContract
     {

src/Recursive/TreeBuilder.php

@@ -33,21 +33,21 @@ final class TreeBuilder
      * signature `fn(mixed $data): MovableNodeContract`.
      * @var callable
      */
-    private $node;
+    private $factory;
 
     /**
      * Extractor of the self reference,
      * signature `fn(mixed $data, mixed $inputIndex, TreeNodeContract $node): string|int`.
      * @var callable
      */
-    private $self;
+    private $selfRef;
 
     /**
      * Extractor of the parent reference,
      * signature `fn(mixed $data, mixed $inputIndex, TreeNodeContract $node): string|int|null`.
      * @var callable
      */
-    private $parent;
+    private $parentRef;
 
     /**
      * Callable that detects the root node.
@@ -58,18 +58,24 @@ final class TreeBuilder
 
     public function __construct(
         callable $node,
-        callable $self,
-        callable $parent,
+        callable $selfRef,
+        callable $parentRef,
         string|int|callable|null $root = null,
     ) {
-        $this->node = $node;
-        $this->self = $self;
-        $this->parent = $parent;
+        $this->factory = $node;
+        $this->selfRef = $selfRef;
+        $this->parentRef = $parentRef;
         if (null === $root || is_string($root) || is_int($root)) {
             // By default, the root node is detected by having the parent ref equal to `null`.
             // By passing in a string or an integer, the root node will be detected by comparing that value to the node's parent value.
             // For custom "is root" detector, use a callable.
-            $this->root = fn($data, $inputIndex, $node, $parentRef, $selfRef): bool => $parentRef === $root;
+            $this->root = fn(
+                mixed $data,
+                mixed $inputIndex,
+                TreeNodeContract $node,
+                int|string|null $parentReference,
+                int|string|null $selfReference,
+            ): bool => $parentReference === $root;
         } elseif (is_callable($root)) {
             $this->root = $root;
         } else {
@@ -81,9 +87,9 @@ public function build(iterable $input): TreeNodeContract
     {
         [$root] = $this->processData(
             input: $input,
-            nodeFactory: $this->node,
-            selfRefExtractor: $this->self,
-            parentRefExtractor: $this->parent,
+            nodeFactory: $this->factory,
+            selfRefExtractor: $this->selfRef,
+            parentRefExtractor: $this->parentRef,
             isRoot: $this->root,
         );
         return $root;
@@ -121,26 +127,35 @@ private function processData(
                 throw new LogicException('The node factory must return a movable node instance.');
             }
 
-            $self = $selfRefExtractor($data, $inputIndex, $node);
-            $parent = $parentRefExtractor($data, $inputIndex, $node);
+            $selfRef = $selfRefExtractor($data, $inputIndex, $node);
+            $parentRef = $parentRefExtractor($data, $inputIndex, $node);
 
-            if (isset($nodeRegister[$self])) {
+            if (!is_string($selfRef) && !is_int($selfRef)) {
                 // TODO improve exceptions
-                throw new LogicException('Duplicate node reference: ' . $self);
+                throw new LogicException('Invalid "self reference" returned by the extractor. Requires a int|string unique to the given node.');
             }
-            $nodeRegister[$self] = $node;
+            if (null !== $parentRef && !is_string($parentRef) && !is_int($parentRef)) {
+                // TODO improve exceptions
+                throw new LogicException('Invalid "parent reference" returned by the extractor. Requires a int|string uniquely pointing to "self reference" of another node, or `null`.');
+            }
+
+            if (isset($nodeRegister[$selfRef])) {
+                // TODO improve exceptions
+                throw new LogicException('Duplicate node reference: ' . $selfRef);
+            }
+            $nodeRegister[$selfRef] = $node;
 
             // When this node is the root, it has no parent.
-            if (!$rootFound && $isRoot($data, $inputIndex, $node, $parent, $self)) {
-                $rootRef = $self;
+            if (!$rootFound && $isRoot($data, $inputIndex, $node, $parentRef, $selfRef)) {
+                $rootRef = $selfRef;
                 $rootFound = true;
                 continue;
             }
 
-            if (!isset($childRegister[$parent])) {
-                $childRegister[$parent] = [];
+            if (!isset($childRegister[$parentRef])) {
+                $childRegister[$parentRef] = [];
             }
-            $childRegister[$parent][] = $self;
+            $childRegister[$parentRef][] = $selfRef;
         }
 
         if (!$rootFound) {

src/Simple/NodeBuilder.php

@@ -28,8 +28,10 @@ public function __construct(
         $this->factory = $node;
     }
 
-    public function node(mixed $data, iterable $children = []): TreeNodeContract
-    {
+    public function node(
+        mixed $data,
+        iterable $children = [],
+    ): TreeNodeContract {
         // Build the node.
         $node = ($this->factory)($data);
 

src/Simple/TreeWrapper.php

@@ -38,8 +38,9 @@ public function __construct(
         $this->childrenExtractor = $children;
     }
 
-    public function wrap(mixed $data): TreeNodeContract
-    {
+    public function wrap(
+        mixed $data,
+    ): TreeNodeContract {
         return $this->wrapNode(
             data: $data,
             nodeFactory: $this->factory,

src/TreeNodeContract.php

@@ -19,18 +19,20 @@ public function parent(): ?TreeNodeContract;
     /**
      * Get the node's children.
      *
+     * The implementations MUST ensure the keys are valid PHP array keys (only int or string).
+     *
      * @return iterable<int|string,TreeNodeContract>
      */
     public function children(): iterable;
 
     /**
-     * Discover whether the given node is one or the given key points to one of this node's children.
+     * Discover whether the given node is one of this node's children (or the given key points to one of them).
      */
     public function hasChild(TreeNodeContract|string|int $child): bool;
 
     /**
      * Get a specific child, if possible.
-     * Returns `null` when there is no such a child.
+     * Returns `null` when there is no such child.
      */
     public function child(string|int $key): ?TreeNodeContract;
 

tests/recursive.phpt

@@ -44,8 +44,8 @@ class Item
 
     $builder = new TreeBuilder(
         node: fn(?Item $item) => new Node($item),
-        self: fn(?Item $item) => $item?->id,
-        parent: fn(?Item $item) => $item?->parent,
+        selfRef: fn(?Item $item) => $item?->id,
+        parentRef: fn(?Item $item) => $item?->parent,
     );
 
     $tree = $builder->build(
@@ -70,8 +70,8 @@ class Item
 
     $builder = new TreeBuilder(
         node: fn(?Item $item) => new Node($item),
-        self: fn(?Item $item) => $item?->id,
-        parent: fn(?Item $item) => $item?->parent,
+        selfRef: fn(?Item $item) => $item?->id,
+        parentRef: fn(?Item $item) => $item?->parent,
     );
 
     $tree = $builder->build(