feat!: refactor tree node API

The class `\CuyZ\Valinor\Mapper\Tree\Node` has been refactored to remove access to unwanted methods that were not supposed to be part of the public API. Below are a list of all changes: - New methods `$node->sourceFilled()` and `$node->sourceValue()` allow accessing the source value. - The method `$node->value()` has been renamed to `$node->mappedValue()` and will throw an exception if the node is not value. - The method `$node->type()` now returns a string. - The methods `$message->name()`, `$message->path()`, `$message->type()` and `$message->value()` have been deprecated in favor of the new method `$message->node()`. - The message parameter `{original_value}` has been deprecated in favor of `{source_value}`.
CuyZ · Jul 10, 2022 · d3b1dcb · d3b1dcb
1 parent 316d919
commit d3b1dcb
Show file tree

Hide file tree

Showing 39 changed files with 761 additions and 454 deletions.
diff --git a/docs/pages/message-customization.md b/docs/pages/message-customization.md
@@ -12,7 +12,7 @@ on the original message.
 | `{node_name}`        | name of the node to which the message is bound       |
 | `{node_path}`        | path of the node to which the message is bound       |
 | `{node_type}`        | type of the node to which the message is bound       |
-| `{original_value}`   | the source value that was given to the node          |
+| `{source_value}`     | the source value that was given to the node          |
 | `{original_message}` | the original message before being customized         |
 
 Usage:
@@ -46,9 +46,9 @@ try {
 } catch (\CuyZ\Valinor\Mapper\MappingError $error) {
     $message = $error->node()->messages()[0];
 
-    if (is_numeric($message->value())) {
+    if (is_numeric($message->node()->mappedValue())) {
         $message = $message->withBody(
-            'Invalid amount {original_value, number, currency}'
+            'Invalid amount {source_value, number, currency}'
         );    
     } 
 
@@ -133,7 +133,7 @@ In any case, the content can contain placeholders as described
     'Some message content' => 'New content / previous: {original_message}',
 
     // Will match if the given message is an instance of `SomeError`
-    SomeError::class => 'New content / value: {original_value}',
+    SomeError::class => 'New content / value: {source_value}',
 
     // A callback can be used to get access to the message instance
     OtherError::class => function (NodeMessage $message): string {

diff --git a/src/Mapper/Tree/Builder/ArrayNodeBuilder.php b/src/Mapper/Tree/Builder/ArrayNodeBuilder.php
@@ -6,12 +6,9 @@
 
 use CuyZ\Valinor\Mapper\Tree\Exception\InvalidTraversableKey;
 use CuyZ\Valinor\Mapper\Tree\Exception\SourceMustBeIterable;
-use CuyZ\Valinor\Mapper\Tree\Node;
 use CuyZ\Valinor\Mapper\Tree\Shell;
 use CuyZ\Valinor\Type\CompositeTraversableType;
-
 use CuyZ\Valinor\Type\Types\ArrayType;
-
 use CuyZ\Valinor\Type\Types\IterableType;
 use CuyZ\Valinor\Type\Types\NonEmptyArrayType;
 
@@ -28,15 +25,15 @@ public function __construct(bool $flexible)
         $this->flexible = $flexible;
     }
 
-    public function build(Shell $shell, RootNodeBuilder $rootBuilder): Node
+    public function build(Shell $shell, RootNodeBuilder $rootBuilder): TreeNode
     {
         $type = $shell->type();
         $value = $shell->hasValue() ? $shell->value() : null;
 
         assert($type instanceof ArrayType || $type instanceof NonEmptyArrayType || $type instanceof IterableType);
 
         if (null === $value && $this->flexible) {
-            return Node::branch($shell, [], []);
+            return TreeNode::branch($shell, [], []);
         }
 
         if (! is_array($value)) {
@@ -46,11 +43,11 @@ public function build(Shell $shell, RootNodeBuilder $rootBuilder): Node
         $children = $this->children($type, $shell, $rootBuilder);
         $array = $this->buildArray($children);
 
-        return Node::branch($shell, $array, $children);
+        return TreeNode::branch($shell, $array, $children);
     }
 
     /**
-     * @return array<Node>
+     * @return array<TreeNode>
      */
     private function children(CompositeTraversableType $type, Shell $shell, RootNodeBuilder $rootBuilder): array
     {
@@ -74,7 +71,7 @@ private function children(CompositeTraversableType $type, Shell $shell, RootNode
     }
 
     /**
-     * @param array<Node> $children
+     * @param array<TreeNode> $children
      * @return mixed[]|null
      */
     private function buildArray(array $children): ?array

diff --git a/src/Mapper/Tree/Builder/CasterNodeBuilder.php b/src/Mapper/Tree/Builder/CasterNodeBuilder.php
@@ -5,7 +5,6 @@
 namespace CuyZ\Valinor\Mapper\Tree\Builder;
 
 use CuyZ\Valinor\Mapper\Tree\Exception\NoCasterForType;
-use CuyZ\Valinor\Mapper\Tree\Node;
 use CuyZ\Valinor\Mapper\Tree\Shell;
 
 /** @internal */
@@ -22,7 +21,7 @@ public function __construct(array $builders)
         $this->builders = $builders;
     }
 
-    public function build(Shell $shell, RootNodeBuilder $rootBuilder): Node
+    public function build(Shell $shell, RootNodeBuilder $rootBuilder): TreeNode
     {
         $type = $shell->type();
 

diff --git a/src/Mapper/Tree/Builder/CasterProxyNodeBuilder.php b/src/Mapper/Tree/Builder/CasterProxyNodeBuilder.php
@@ -4,7 +4,6 @@
 
 namespace CuyZ\Valinor\Mapper\Tree\Builder;
 
-use CuyZ\Valinor\Mapper\Tree\Node;
 use CuyZ\Valinor\Mapper\Tree\Shell;
 
 /** @internal */
@@ -17,13 +16,13 @@ public function __construct(NodeBuilder $delegate)
         $this->delegate = $delegate;
     }
 
-    public function build(Shell $shell, RootNodeBuilder $rootBuilder): Node
+    public function build(Shell $shell, RootNodeBuilder $rootBuilder): TreeNode
     {
         if ($shell->hasValue()) {
             $value = $shell->value();
 
             if ($shell->type()->accepts($value)) {
-                return Node::leaf($shell, $value);
+                return TreeNode::leaf($shell, $value);
             }
         }
 

diff --git a/src/Mapper/Tree/Builder/ClassNodeBuilder.php b/src/Mapper/Tree/Builder/ClassNodeBuilder.php
@@ -10,7 +10,6 @@
 use CuyZ\Valinor\Mapper\Object\FilteredObjectBuilder;
 use CuyZ\Valinor\Mapper\Object\ObjectBuilder;
 use CuyZ\Valinor\Mapper\Tree\Exception\UnexpectedArrayKeysForClass;
-use CuyZ\Valinor\Mapper\Tree\Node;
 use CuyZ\Valinor\Mapper\Tree\Shell;
 use CuyZ\Valinor\Type\Type;
 use CuyZ\Valinor\Type\Types\ClassType;
@@ -41,7 +40,7 @@ public function __construct(
         $this->flexible = $flexible;
     }
 
-    public function build(Shell $shell, RootNodeBuilder $rootBuilder): Node
+    public function build(Shell $shell, RootNodeBuilder $rootBuilder): TreeNode
     {
         $classTypes = $this->classTypes($shell->type());
 
@@ -70,7 +69,7 @@ public function build(Shell $shell, RootNodeBuilder $rootBuilder): Node
 
         $object = $this->buildObject($builder, $children);
 
-        $node = Node::branch($shell, $object, $children);
+        $node = TreeNode::branch($shell, $object, $children);
 
         if (! $this->flexible) {
             $node = $this->checkForUnexpectedKeys($arguments, $node);
@@ -109,7 +108,7 @@ private function builder(Shell $shell, ClassType ...$classTypes): ObjectBuilder
     }
 
     /**
-     * @param Node[] $children
+     * @param TreeNode[] $children
      */
     private function buildObject(ObjectBuilder $builder, array $children): ?object
     {
@@ -126,7 +125,7 @@ private function buildObject(ObjectBuilder $builder, array $children): ?object
         return $builder->build($arguments);
     }
 
-    private function checkForUnexpectedKeys(FilledArguments $arguments, Node $node): Node
+    private function checkForUnexpectedKeys(FilledArguments $arguments, TreeNode $node): TreeNode
     {
         $superfluousKeys = $arguments->superfluousKeys();
 

diff --git a/src/Mapper/Tree/Builder/EnumNodeBuilder.php b/src/Mapper/Tree/Builder/EnumNodeBuilder.php
@@ -6,7 +6,6 @@
 
 use BackedEnum;
 use CuyZ\Valinor\Mapper\Tree\Exception\InvalidEnumValue;
-use CuyZ\Valinor\Mapper\Tree\Node;
 use CuyZ\Valinor\Mapper\Tree\Shell;
 use CuyZ\Valinor\Type\Types\EnumType;
 use Stringable;
@@ -28,7 +27,7 @@ public function __construct(bool $flexible)
         $this->flexible = $flexible;
     }
 
-    public function build(Shell $shell, RootNodeBuilder $rootBuilder): Node
+    public function build(Shell $shell, RootNodeBuilder $rootBuilder): TreeNode
     {
         $type = $shell->type();
         $value = $shell->value();
@@ -37,7 +36,7 @@ public function build(Shell $shell, RootNodeBuilder $rootBuilder): Node
 
         foreach ($type->className()::cases() as $case) {
             if ($this->valueMatchesEnumCase($value, $case)) {
-                return Node::leaf($shell, $case);
+                return TreeNode::leaf($shell, $case);
             }
         }
 

diff --git a/src/Mapper/Tree/Builder/ErrorCatcherNodeBuilder.php b/src/Mapper/Tree/Builder/ErrorCatcherNodeBuilder.php
@@ -7,7 +7,6 @@
 use CuyZ\Valinor\Mapper\Tree\Message\ErrorMessage;
 use CuyZ\Valinor\Mapper\Tree\Message\Message;
 use CuyZ\Valinor\Mapper\Tree\Message\UserlandError;
-use CuyZ\Valinor\Mapper\Tree\Node;
 use CuyZ\Valinor\Mapper\Tree\Shell;
 use Throwable;
 
@@ -28,7 +27,7 @@ public function __construct(NodeBuilder $delegate, callable $exceptionFilter)
         $this->exceptionFilter = $exceptionFilter;
     }
 
-    public function build(Shell $shell, RootNodeBuilder $rootBuilder): Node
+    public function build(Shell $shell, RootNodeBuilder $rootBuilder): TreeNode
     {
         try {
             return $this->delegate->build($shell, $rootBuilder);
@@ -37,7 +36,7 @@ public function build(Shell $shell, RootNodeBuilder $rootBuilder): Node
                 $exception = ($this->exceptionFilter)($exception->previous());
             }
 
-            return Node::error($shell, $exception);
+            return TreeNode::error($shell, $exception);
         }
     }
 }
diff --git a/src/Mapper/Tree/Builder/InterfaceNodeBuilder.php b/src/Mapper/Tree/Builder/InterfaceNodeBuilder.php
@@ -10,7 +10,6 @@
 use CuyZ\Valinor\Mapper\Object\FilledArguments;
 use CuyZ\Valinor\Mapper\Tree\Exception\ObjectImplementationCallbackError;
 use CuyZ\Valinor\Mapper\Tree\Message\UserlandError;
-use CuyZ\Valinor\Mapper\Tree\Node;
 use CuyZ\Valinor\Mapper\Tree\Shell;
 use CuyZ\Valinor\Type\Types\ClassType;
 use CuyZ\Valinor\Type\Types\InterfaceType;
@@ -44,7 +43,7 @@ public function __construct(
         $this->flexible = $flexible;
     }
 
-    public function build(Shell $shell, RootNodeBuilder $rootBuilder): Node
+    public function build(Shell $shell, RootNodeBuilder $rootBuilder): TreeNode
     {
         $type = $shell->type();
 
@@ -63,7 +62,7 @@ public function build(Shell $shell, RootNodeBuilder $rootBuilder): Node
 
         foreach ($children as $child) {
             if (! $child->isValid()) {
-                return Node::branch($shell, null, $children);
+                return TreeNode::branch($shell, null, $children);
             }
 
             $values[] = $child->value();
@@ -82,7 +81,7 @@ public function build(Shell $shell, RootNodeBuilder $rootBuilder): Node
     }
 
     /**
-     * @return Node[]
+     * @return TreeNode[]
      */
     private function children(Shell $shell, FilledArguments $arguments, RootNodeBuilder $rootBuilder): array
     {

diff --git a/src/Mapper/Tree/Builder/IterableNodeBuilder.php b/src/Mapper/Tree/Builder/IterableNodeBuilder.php
@@ -4,7 +4,6 @@
 
 namespace CuyZ\Valinor\Mapper\Tree\Builder;
 
-use CuyZ\Valinor\Mapper\Tree\Node;
 use CuyZ\Valinor\Mapper\Tree\Shell;
 
 use function is_array;
@@ -21,7 +20,7 @@ public function __construct(NodeBuilder $delegate)
         $this->delegate = $delegate;
     }
 
-    public function build(Shell $shell, RootNodeBuilder $rootBuilder): Node
+    public function build(Shell $shell, RootNodeBuilder $rootBuilder): TreeNode
     {
         if ($shell->hasValue()) {
             $value = $shell->value();

diff --git a/src/Mapper/Tree/Builder/ListNodeBuilder.php b/src/Mapper/Tree/Builder/ListNodeBuilder.php
@@ -6,7 +6,6 @@
 
 use CuyZ\Valinor\Mapper\Tree\Exception\InvalidListKey;
 use CuyZ\Valinor\Mapper\Tree\Exception\SourceMustBeIterable;
-use CuyZ\Valinor\Mapper\Tree\Node;
 use CuyZ\Valinor\Mapper\Tree\Shell;
 use CuyZ\Valinor\Type\CompositeTraversableType;
 use CuyZ\Valinor\Type\Types\ListType;
@@ -25,15 +24,15 @@ public function __construct(bool $flexible)
         $this->flexible = $flexible;
     }
 
-    public function build(Shell $shell, RootNodeBuilder $rootBuilder): Node
+    public function build(Shell $shell, RootNodeBuilder $rootBuilder): TreeNode
     {
         $type = $shell->type();
         $value = $shell->hasValue() ? $shell->value() : null;
 
         assert($type instanceof ListType || $type instanceof NonEmptyListType);
 
         if (null === $value && $this->flexible) {
-            return Node::branch($shell, [], []);
+            return TreeNode::branch($shell, [], []);
         }
 
         if (! is_array($value)) {
@@ -43,11 +42,11 @@ public function build(Shell $shell, RootNodeBuilder $rootBuilder): Node
         $children = $this->children($type, $shell, $rootBuilder);
         $array = $this->buildArray($children);
 
-        return Node::branch($shell, $array, $children);
+        return TreeNode::branch($shell, $array, $children);
     }
 
     /**
-     * @return array<Node>
+     * @return array<TreeNode>
      */
     private function children(CompositeTraversableType $type, Shell $shell, RootNodeBuilder $rootBuilder): array
     {
@@ -64,7 +63,7 @@ private function children(CompositeTraversableType $type, Shell $shell, RootNode
                 $children[$expected] = $rootBuilder->build($child->withValue($value));
             } else {
                 $child = $shell->child((string)$key, $subType);
-                $children[$key] = Node::error($child, new InvalidListKey($key, $expected));
+                $children[$key] = TreeNode::error($child, new InvalidListKey($key, $expected));
             }
 
             $expected++;
@@ -74,7 +73,7 @@ private function children(CompositeTraversableType $type, Shell $shell, RootNode
     }
 
     /**
-     * @param array<Node> $children
+     * @param array<TreeNode> $children
      * @return mixed[]|null
      */
     private function buildArray(array $children): ?array

diff --git a/src/Mapper/Tree/Builder/NodeBuilder.php b/src/Mapper/Tree/Builder/NodeBuilder.php
@@ -2,11 +2,10 @@
 
 namespace CuyZ\Valinor\Mapper\Tree\Builder;
 
-use CuyZ\Valinor\Mapper\Tree\Node;
 use CuyZ\Valinor\Mapper\Tree\Shell;
 
 /** @internal */
 interface NodeBuilder
 {
-    public function build(Shell $shell, RootNodeBuilder $rootBuilder): Node;
+    public function build(Shell $shell, RootNodeBuilder $rootBuilder): TreeNode;
 }
diff --git a/src/Mapper/Tree/Builder/RootNodeBuilder.php b/src/Mapper/Tree/Builder/RootNodeBuilder.php
@@ -4,7 +4,6 @@
 
 namespace CuyZ\Valinor\Mapper\Tree\Builder;
 
-use CuyZ\Valinor\Mapper\Tree\Node;
 use CuyZ\Valinor\Mapper\Tree\Shell;
 
 /** @internal */
@@ -17,7 +16,7 @@ public function __construct(NodeBuilder $root)
         $this->root = $root;
     }
 
-    public function build(Shell $shell): Node
+    public function build(Shell $shell): TreeNode
     {
         return $this->root->build($shell, $this);
     }

diff --git a/src/Mapper/Tree/Builder/ScalarNodeBuilder.php b/src/Mapper/Tree/Builder/ScalarNodeBuilder.php
@@ -6,7 +6,6 @@
 
 use CuyZ\Valinor\Mapper\Tree\Exception\CannotCastToScalarValue;
 use CuyZ\Valinor\Mapper\Tree\Exception\ValueNotAcceptedByScalarType;
-use CuyZ\Valinor\Mapper\Tree\Node;
 use CuyZ\Valinor\Mapper\Tree\Shell;
 use CuyZ\Valinor\Type\ScalarType;
 
@@ -22,7 +21,7 @@ public function __construct(bool $flexible)
         $this->flexible = $flexible;
     }
 
-    public function build(Shell $shell, RootNodeBuilder $rootBuilder): Node
+    public function build(Shell $shell, RootNodeBuilder $rootBuilder): TreeNode
     {
         $type = $shell->type();
         $value = $shell->hasValue() ? $shell->value() : null;
@@ -37,6 +36,6 @@ public function build(Shell $shell, RootNodeBuilder $rootBuilder): Node
             throw new CannotCastToScalarValue($value, $type);
         }
 
-        return Node::leaf($shell, $type->cast($value));
+        return TreeNode::leaf($shell, $type->cast($value));
     }
 }