Simple path reporter: a simpler way to provide errors (#45)

Author: ilario-pierbattista

CHANGELOG.md

@@ -5,6 +5,10 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
+### Added
+- `SimplePathReporter` error reporter.
+### Changed
+- `Facile\PhpCodec\PathReporter` moved to `Facile\PhpCodec\Reporters\PathReporter`.
 
 ## [0.0.2] - 2021-08-13
 ### Added

README.md

@@ -11,14 +11,14 @@ Install it now. It only requires PHP > 7.2.
 
     composer require facile-it/php-codec
 
-## Disclaimer
+# Disclaimer
 
 This project is under active development: it's unstable and still poorly documented.
 The API is likely to change several times, and it won't be ready for production soon.
 
 The project follows [semantic versioning](https://semver.org/).
 
-## Introduction
+# Introduction
 
 This project is a partial porting of the fantastic [io-ts](https://github.com/gcanti/io-ts) library for Typescript.
 Everything rounds about the concept of decoder, encoder and codec.
@@ -66,18 +66,18 @@ I recommend reading the [The Idea](https://github.com/gcanti/io-ts/blob/master/i
 documentation of io-ts. It starts with a beautiful description of what codecs are.
 > A value of type `Type<A, O, I>` (called "codec") is the run time representation of the static type `A`.
 
-## Getting started
+# Getting started
 
     composer require facile-it/php-codec
 
-### Decoders
+## Decoders
 
 Decoders are objects with decoding capabilities.
 A decoder of type `Decoder<I, A>` takes an input of type `I` and builds a result of type `Validation<A>`.
 
 The class `Facile\PhpCodec\Decoders` provides factory methods for built-in decoders and combinators.
 
-#### How to use decoders
+### How to use decoders
 
 ```php
 use Facile\PhpCodec\Decoders;
@@ -109,7 +109,7 @@ if($v2 instanceof ValidationFailures) {
 }
 ```
 
-#### Dealing with the validation result
+### Dealing with the validation result
 
 We can use `Validation::fold` to destruct the validation result while providing 
 a valid result in any case. 
@@ -142,7 +142,7 @@ use Facile\PhpCodec\Decoders;
 
 $decoder = Decoders::intFromString();
 $v = $decoder->decode('hello');
-$msgs = \Facile\PhpCodec\PathReporter::create()->report($v);
+$msgs = \Facile\PhpCodec\Reporters::path()->report($v);
 
 var_dump($msgs);
 /* This will print 
@@ -153,6 +153,44 @@ array(1) {
 */
 ```
 
-### Examples
+## Examples
 
 Take a look to the [examples](https://github.com/facile-it/php-codec/tree/master/tests/examples) folder.
+
+
+# Reporters
+
+Reporters do create reports from `Validation` objects.
+Generally speaking, reporters are objects that implement the `Reporter<T>` interface, given `T` the type of the report that the generate.
+
+One interesting group of reporters is the validation error reporters group.
+They implements `Reporter<list<string>>`.
+Thus, given a `Validation` object, they generate a list of error messages for each validation error.
+
+PHP-Codec comes with two error reporters:
+
+- PathReporter, which is a pretty straightforward porting of io-ts' [PathReporter](https://github.com/gcanti/io-ts/blob/master/index.md#error-reporters).
+- SimplePathReporter, which is a simplified (read: shorter messages) version of the PathReporter.
+
+```php
+$d = Decoders::arrayProps([
+  'a' => Decoders::arrayProps([
+    'a1' => Decoders::int(),
+    'a2' => Decoders::string(),
+  ]),
+  'b' => Decoders::arrayProps(['b1' => Decoders::bool()])
+]);
+$v = $d->decode(['a'=> ['a1' => 'str', 'a2' => 1], 'b' => 2]);
+
+$x = \Facile\PhpCodec\Reporters::path()->report($v);
+// $x will be
+// ['Invalid value "str" supplied to : {a: {a1: int, a2: string}, b: {b1: bool}}/a: {a1: int, a2: string}/a1: int',
+//  'Invalid value 1 supplied to : {a: {a1: int, a2: string}, b: {b1: bool}}/a: {a1: int, a2: string}/a2: string',
+//  'Invalid value undefined supplied to : {a: {a1: int, a2: string}, b: {b1: bool}}/b: {b1: bool}/b1: bool']
+
+$y = \Facile\PhpCodec\Reporters::simplePath()->report($v);
+// $y will be
+// ['/a/a1: Invalid value "str" supplied to decoder "int"',
+//  '/a/a2: Invalid value 1 supplied to decoder "string"',
+//  '/b/b1: Invalid value undefined supplied to decoder "bool"']
+```

src/Decoders.php

@@ -122,12 +122,27 @@ public static function union(Decoder $a, Decoder $b, ?Decoder $c = null, ?Decode
     {
         // Order is important, this is not commutative
 
-        return new UnionDecoder(
-            $a,
-            $c instanceof Decoder
-                ? self::union($b, $c, $d, $e)
-                : $b
+        $args = array_values(
+            array_filter(
+                func_get_args(),
+                static function ($x): bool {
+                    return $x instanceof Decoder;
+                }
+            )
         );
+        $argc = count($args);
+
+        $res = new UnionDecoder($args[$argc - 2], $args[$argc - 1], $argc - 2);
+
+        for ($i = $argc - 3; $i >= 0; --$i) {
+            $res = new UnionDecoder(
+                $args[$i],
+                $res,
+                $i
+            );
+        }
+
+        return $res;
     }
 
     /**
@@ -224,21 +239,21 @@ public static function arrayProps(array $props): Decoder
      * @psalm-template CF of callable(...mixed):T
      * @psalm-param Decoder<mixed, PD> $propsDecoder
      * @psalm-param CF $factory
-     * @psalm-param class-string<T> $fqcn
+     * @psalm-param string $decoderName
      * @psalm-return Decoder<mixed, T>
      */
     public static function classFromArrayPropsDecoder(
         Decoder $propsDecoder,
         callable $factory,
-        string $fqcn
+        string $decoderName
     ): Decoder {
         return self::pipe(
             $propsDecoder,
             new MapDecoder(
                 function (array $props) use ($factory) {
                     return destructureIn($factory)(\array_values($props));
                 },
-                \sprintf('%s(%s)', $fqcn, $propsDecoder->getName())
+                \sprintf('%s(%s)', $decoderName, $propsDecoder->getName())
             )
         );
     }

src/Internal/Arrays/ListOfDecoder.php

@@ -50,8 +50,17 @@ public function validate($i, Context $context): Validation
         $validation = [];
 
         /** @var IT $item */
-        foreach ($i as $item) {
-            $validation[] = $this->elementDecoder->validate($item, $context);
+        foreach ($i as $index => $item) {
+            $validation[] = $this->elementDecoder->validate(
+                $item,
+                $context->appendEntries(
+                    new ContextEntry(
+                        (string) $index,
+                        $this->elementDecoder,
+                        $item
+                    )
+                )
+            );
         }
 
         return ListOfValidation::sequence($validation);

src/Internal/Combinators/IntersectionDecoder.php

@@ -5,9 +5,14 @@
 namespace Facile\PhpCodec\Internal\Combinators;
 
 use Facile\PhpCodec\Decoder;
+use function Facile\PhpCodec\destructureIn;
 use function Facile\PhpCodec\Internal\standardDecode;
 use Facile\PhpCodec\Validation\Context;
+use Facile\PhpCodec\Validation\ContextEntry;
+use Facile\PhpCodec\Validation\ListOfValidation;
 use Facile\PhpCodec\Validation\Validation;
+use Facile\PhpCodec\Validation\ValidationFailures;
+use Facile\PhpCodec\Validation\ValidationSuccess;
 
 /**
  * @psalm-template I
@@ -35,23 +40,45 @@ public function __construct(Decoder $a, Decoder $b)
 
     public function validate($i, Context $context): Validation
     {
-        return Validation::bind(
-            /**
-             * @psalm-param A $a
-             * @psalm-return Validation<A & B>
-             *
-             * @param mixed $a
-             */
-            function ($a) use ($i): Validation {
-                /** @psalm-var Closure(B):A&B $f */
-                $f = $this->curryIntersect($a);
+        /** @var Validation<A> $va */
+        $va = $this->a->validate($i, $context->appendEntries(new ContextEntry('0', $this->a, $i)));
+        /** @var Validation<B> $vb */
+        $vb = $this->b->validate($i, $context->appendEntries(new ContextEntry('1', $this->b, $i)));
 
-                return Validation::map(
-                    $f,
-                    $this->b->decode($i)
-                );
-            },
-            $this->a->decode($i)
+        if ($va instanceof ValidationFailures && $vb instanceof ValidationFailures) {
+            return ValidationFailures::failures(
+                array_merge(
+                    $va->getErrors(),
+                    $vb->getErrors()
+                )
+            );
+        }
+
+        if ($va instanceof ValidationFailures && $vb instanceof ValidationSuccess) {
+            /** @psalm-var Validation<A&B> $va */
+            return $va;
+        }
+
+        if ($va instanceof ValidationSuccess && $vb instanceof ValidationFailures) {
+            /** @psalm-var Validation<A&B> $vb */
+            return $vb;
+        }
+
+        return Validation::map(
+            destructureIn(
+                /**
+                 * @psalm-param A $a
+                 * @psalm-param B $b
+                 * @psalm-return A&B
+                 *
+                 * @param mixed $a
+                 * @param mixed $b
+                 */
+                function ($a, $b) {
+                    return self::intersectResults($a, $b);
+                }
+            ),
+            ListOfValidation::sequence([$va, $vb])
         );
     }
 
@@ -67,37 +94,32 @@ public function getName(): string
     }
 
     /**
-     * @psalm-param A $a
-     * @psalm-return Closure(B):A&B
+     * @template T1
+     * @template T2
+     * @psalm-param T1 $a
+     * @psalm-param T2 $b
+     * @psalm-return T1&T2
      *
      * @param mixed $a
+     * @param mixed $b
+     *
+     * @return array|object
      */
-    private function curryIntersect($a): \Closure
+    private static function intersectResults($a, $b)
     {
-        $f =
-            /**
-             * @psalm-param B $b
-             * @psalm-return A&B
-             *
-             * @param mixed $b
-             */
-            static function ($b) use ($a) {
-                if (\is_array($a) && \is_array($b)) {
-                    /** @var A&B */
-                    return \array_merge($a, $b);
-                }
-
-                if ($a instanceof \stdClass && $b instanceof \stdClass) {
-                    /** @var A&B */
-                    return (object) \array_merge((array) $a, (array) $b);
-                }
+        if (\is_array($a) && \is_array($b)) {
+            /** @var T1&T2 */
+            return \array_merge($a, $b);
+        }
 
-                /**
-                 * @psalm-var A&B $b
-                 */
-                return $b;
-            };
+        if ($a instanceof \stdClass && $b instanceof \stdClass) {
+            /** @var T1&T2 */
+            return (object) \array_merge((array) $a, (array) $b);
+        }
 
-        return $f;
+        /**
+         * @psalm-var T1&T2 $b
+         */
+        return $b;
     }
 }

src/Internal/Combinators/UnionDecoder.php

@@ -7,6 +7,7 @@
 use Facile\PhpCodec\Decoder;
 use function Facile\PhpCodec\Internal\standardDecode;
 use Facile\PhpCodec\Validation\Context;
+use Facile\PhpCodec\Validation\ContextEntry;
 use Facile\PhpCodec\Validation\Validation;
 use Facile\PhpCodec\Validation\ValidationFailures;
 
@@ -24,25 +25,60 @@ final class UnionDecoder implements Decoder
     private $a;
     /** @var Decoder<IB, B> */
     private $b;
+    /** @var int */
+    private $indexBegin;
 
     /**
      * @psalm-param Decoder<IA, A> $a
      * @psalm-param Decoder<IB, B> $b
      */
     public function __construct(
         Decoder $a,
-        Decoder $b
+        Decoder $b,
+        int $indexBegin = 0
     ) {
         $this->a = $a;
         $this->b = $b;
+        $this->indexBegin = $indexBegin;
     }
 
     public function validate($i, Context $context): Validation
     {
-        $va = $this->a->validate($i, $context);
+        $va = $this->a->validate(
+            $i,
+            $context->appendEntries(
+                new ContextEntry(
+                    (string) $this->indexBegin,
+                    $this->a,
+                    $i
+                )
+            )
+        );
 
         if ($va instanceof ValidationFailures) {
-            return $this->b->validate($i, $context);
+            $vb = $this->b->validate(
+                $i,
+                $this->b instanceof self
+                    ? $context
+                    : $context->appendEntries(
+                        new ContextEntry(
+                            (string) ($this->indexBegin + 1),
+                            $this->b,
+                            $i
+                        )
+                    )
+            );
+
+            if ($vb instanceof ValidationFailures) {
+                return Validation::failures(
+                    array_merge(
+                        $va->getErrors(),
+                        $vb->getErrors()
+                    )
+                );
+            }
+
+            return $vb;
         }
 
         return $va;