use generic for node value

.php-cs-fixer.php

@@ -29,6 +29,7 @@
     ->withRules(PhpCsFixer\Config\Rules::fromArray([
         'declare_strict_types' => false,
         'final_class' => false,
+        'phpdoc_to_property_type' => false, // when turned on it breaks generics phpdoc types
         'void_return' => false,
     ]));
 

CHANGELOG.md

@@ -8,6 +8,10 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 
 For a full diff see [`0.10.0...master`][0.10.0...master].
 
+### Added
+
+- Added template/generic annotations for node values ([#333]), by [@smoench]
+
 ## [`0.10.0`][0.10.0]
 
 For a full diff see [0.9.0...0.10.0`][0.9.0...0.10.0].
@@ -303,3 +307,4 @@ For a full diff see [`fcfd14e...v0.1.1`][fcfd14e...0.1.1].
 [@mdwheele]: https://github.com/mdwheele
 [@nicmart]: https://github.com/nicmart
 [@pascalbaljet]: https://github.com/pascalbaljet
+[@smoench]: https://github.com/smoench

psalm-baseline.xml

@@ -1,70 +1,72 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<files psalm-version="5.12.0@f90118cdeacd0088e7215e64c0c99ceca819e176">
+<files psalm-version="5.26.1@d747f6500b38ac4f7dfc5edbcae6e4b637d7add0">
   <file src="src/Builder/NodeBuilder.php">
     <MixedAssignment>
-      <code>$value</code>
+      <code><![CDATA[$value]]></code>
     </MixedAssignment>
   </file>
   <file src="src/Builder/NodeBuilderInterface.php">
     <PossiblyUnusedReturnValue>
-      <code>static</code>
-      <code>static</code>
+      <code><![CDATA[static]]></code>
+      <code><![CDATA[static]]></code>
     </PossiblyUnusedReturnValue>
   </file>
+  <file src="src/Node/Node.php">
+    <PropertyNotSetInConstructor>
+      <code><![CDATA[Node]]></code>
+    </PropertyNotSetInConstructor>
+  </file>
   <file src="src/Node/NodeInterface.php">
     <PossiblyUnusedReturnValue>
-      <code>mixed</code>
-      <code>static</code>
-      <code>static</code>
-      <code>static</code>
+      <code><![CDATA[static]]></code>
+      <code><![CDATA[static]]></code>
+      <code><![CDATA[static]]></code>
+      <code><![CDATA[static]]></code>
     </PossiblyUnusedReturnValue>
   </file>
   <file src="src/Node/NodeTrait.php">
     <ArgumentTypeCoercion>
-      <code>$heights</code>
+      <code><![CDATA[$heights]]></code>
     </ArgumentTypeCoercion>
     <LessSpecificImplementedReturnType>
-      <code>array</code>
-      <code>array</code>
-      <code>array</code>
+      <code><![CDATA[array]]></code>
+      <code><![CDATA[array]]></code>
+      <code><![CDATA[array]]></code>
     </LessSpecificImplementedReturnType>
     <MixedArgument>
-      <code>$child</code>
+      <code><![CDATA[$child]]></code>
     </MixedArgument>
     <MixedAssignment>
-      <code>$child</code>
-      <code>$child</code>
-      <code>$child</code>
-      <code>$child</code>
-      <code>$heights[]</code>
-      <code>$size</code>
+      <code><![CDATA[$child]]></code>
+      <code><![CDATA[$child]]></code>
+      <code><![CDATA[$child]]></code>
+      <code><![CDATA[$child]]></code>
+      <code><![CDATA[$heights[]]]></code>
+      <code><![CDATA[$size]]></code>
     </MixedAssignment>
     <MixedInferredReturnType>
-      <code>int</code>
-      <code>int</code>
+      <code><![CDATA[int]]></code>
+      <code><![CDATA[int]]></code>
     </MixedInferredReturnType>
     <MixedMethodCall>
-      <code>getHeight</code>
-      <code>getSize</code>
-      <code>setParent</code>
+      <code><![CDATA[getHeight]]></code>
+      <code><![CDATA[getSize]]></code>
+      <code><![CDATA[setParent]]></code>
     </MixedMethodCall>
     <MixedOperand>
       <code><![CDATA[$child->getSize()]]></code>
-      <code>\max($heights)</code>
+      <code><![CDATA[\max($heights)]]></code>
     </MixedOperand>
-    <MoreSpecificReturnType>
-      <code>?static</code>
-    </MoreSpecificReturnType>
     <PossiblyNullReference>
-      <code>getDepth</code>
+      <code><![CDATA[getDepth]]></code>
     </PossiblyNullReference>
   </file>
   <file src="src/Visitor/PostOrderVisitor.php">
     <MixedArgument>
       <code><![CDATA[$child->accept($this)]]></code>
     </MixedArgument>
     <MixedReturnTypeCoercion>
-      <code>$nodes</code>
+      <code><![CDATA[$nodes]]></code>
       <code><![CDATA[array<int, NodeInterface>]]></code>
     </MixedReturnTypeCoercion>
   </file>
@@ -73,7 +75,7 @@
       <code><![CDATA[$child->accept($this)]]></code>
     </MixedArgument>
     <MixedReturnTypeCoercion>
-      <code>$nodes</code>
+      <code><![CDATA[$nodes]]></code>
       <code><![CDATA[array<int, NodeInterface>]]></code>
     </MixedReturnTypeCoercion>
   </file>
@@ -82,7 +84,7 @@
       <code><![CDATA[$child->accept($this)]]></code>
     </MixedArgument>
     <MixedReturnTypeCoercion>
-      <code>$yield</code>
+      <code><![CDATA[$yield]]></code>
       <code><![CDATA[array<int, NodeInterface>]]></code>
     </MixedReturnTypeCoercion>
   </file>
@@ -91,18 +93,10 @@
       <code><![CDATA['Tree\Node\Node']]></code>
     </ArgumentTypeCoercion>
     <InvalidDocblock>
-      <code>array[Node]</code>
+      <code><![CDATA[array[Node]]]></code>
     </InvalidDocblock>
-    <MissingClosureReturnType>
-      <code>static function (Node $node) {</code>
-    </MissingClosureReturnType>
     <PossiblyNullReference>
-      <code>leaf</code>
+      <code><![CDATA[leaf]]></code>
     </PossiblyNullReference>
   </file>
-  <file src="test/Unit/Node/NodeTest.php">
-    <TypeDoesNotContainType>
-      <code>assertSame</code>
-    </TypeDoesNotContainType>
-  </file>
 </files>

src/Node/Node.php

@@ -11,15 +11,22 @@
 
 namespace Tree\Node;
 
+/**
+ * @template TValue
+ *
+ * @template-implements NodeInterface<TValue>
+ */
 class Node implements NodeInterface
 {
+    /** @use NodeTrait<null|TValue> */
     use NodeTrait;
 
     /**
+     * @param null|TValue               $value
      * @param array<int, NodeInterface> $children
      */
     public function __construct(
-        mixed $value = null,
+        $value = null,
         array $children = [],
     ) {
         $this->setValue($value);

src/Node/NodeInterface.php

@@ -17,23 +17,27 @@
  * Interface for tree nodes.
  *
  * @author Nicolò Martini <nicmartnic@gmail.com>
+ *
+ * @template TValue
  */
 interface NodeInterface
 {
     /**
      * Set the value of the current node.
+     *
+     * @param TValue $value
      */
-    public function setValue(mixed $value): static;
+    public function setValue($value): static;
 
     /**
      * Get the current node value.
+     *
+     * @return TValue
      */
-    public function getValue(): mixed;
+    public function getValue();
 
     /**
      * Add a child.
-     *
-     * @return mixed
      */
     public function addChild(self $child): static;
 
@@ -58,8 +62,6 @@ public function getChildren(): array;
      * Replace the children set with the given one.
      *
      * @param array<int, NodeInterface> $children
-     *
-     * @return mixed
      */
     public function setChildren(array $children): static;
 
@@ -71,7 +73,7 @@ public function setParent(?self $parent = null): void;
     /**
      * Return the parent node.
      */
-    public function getParent(): ?static;
+    public function getParent(): ?self;
 
     /**
      * Retrieves all ancestors of node excluding current node.
@@ -115,7 +117,7 @@ public function isLeaf(): bool;
     /**
      * Find the root of the node.
      */
-    public function root(): static;
+    public function root(): self;
 
     /**
      * Return the distance from the current node to the root.

src/Node/NodeTrait.php

@@ -13,24 +13,36 @@
 
 use Tree\Visitor\Visitor;
 
+/**
+ * @template TValue
+ */
 trait NodeTrait
 {
-    private mixed $value = null;
+    /**
+     * @var TValue
+     */
+    private $value;
     private ?NodeInterface $parent = null;
 
     /**
      * @var array<int, NodeInterface>
      */
     private array $children = [];
 
-    public function setValue(mixed $value): static
+    /**
+     * @param TValue $value
+     */
+    public function setValue($value): static
     {
         $this->value = $value;
 
         return $this;
     }
 
-    public function getValue(): mixed
+    /**
+     * @return TValue
+     */
+    public function getValue()
     {
         return $this->value;
     }
@@ -90,7 +102,7 @@ public function setParent(?NodeInterface $parent = null): void
         $this->parent = $parent;
     }
 
-    public function getParent(): ?static
+    public function getParent(): ?NodeInterface
     {
         return $this->parent;
     }
@@ -153,7 +165,7 @@ public function isLeaf(): bool
         return [] === $this->children;
     }
 
-    public function root(): static
+    public function root(): NodeInterface
     {
         $node = $this;
 

src/Visitor/PostOrderVisitor.php

@@ -18,7 +18,7 @@ class PostOrderVisitor implements Visitor
     /**
      * @return array<int, NodeInterface> $node
      */
-    public function visit(NodeInterface $node): mixed
+    public function visit(NodeInterface $node): array
     {
         $nodes = [];
 

src/Visitor/YieldVisitor.php

@@ -18,7 +18,7 @@ class YieldVisitor implements Visitor
     /**
      * @return array<int, NodeInterface>
      */
-    public function visit(NodeInterface $node): mixed
+    public function visit(NodeInterface $node): array
     {
         if ($node->isLeaf()) {
             return [$node];

test/Unit/Node/NodeTest.php

@@ -69,6 +69,7 @@ public function testConstructorSetsChildren(): void
 
     public function testSetValue(): void
     {
+        /** @var Node<\stdClass|string> $node */
         $node = new Node();
 
         $node->setValue('string value');