Deprecate codecs in favour of decoders and other things (#33)

Author: ilario-pierbattista

CHANGELOG.md

@@ -7,10 +7,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 ### Added
 - `trasformValidationSuccess` function for decoders. Structurally equivalent to a map. (#24)
+- Decoders to replace codecs (#33).
+### Changed
+- `Validation::sequence` moved to `ListOfValidation::sequence` (#33)
+### Deprecated
+- The usage of codecs is deprecated in favour of decoders. (#24)
 ### Fixed
 - Used Psalm specific annotations to avoid confusing IDEs without Psalm support. (#26)
-### Deprecated
-- Usage of codecs is deprecated in favour of decoders. (#24)
+- Evety class in the namespace `Facile\PhpCodec\Internal` is marked as internal, and it should not be used outside. (#33)
 
 ## [0.0.1] - 2021-04-30 
 ### Added

Makefile

@@ -10,9 +10,14 @@ sh:
 	docker-compose up -d
 	docker-compose exec php bash
 
-psalm:
+psalm-src:
 	./vendor/bin/psalm src --no-cache
 
+psalm-tests:
+	./vendor/bin/psalm tests --no-cache
+
+psalm: psalm-src psalm-tests
+
 type-assertions:
 	./vendor/bin/psalm tests/type-assertions --no-cache
 
@@ -29,4 +34,6 @@ cs-fix:
 cs-check:
 	./vendor/bin/php-cs-fixer fix --ansi --verbose --dry-run
 
-ci: test cs-check psalm type-assertions architecture
+ci: test cs-fix psalm type-assertions architecture
+
+ci-check: test cs-check psalm type-assertions architecture

README.md

@@ -30,57 +30,13 @@ Its documentation starts with:
 I strongly recomend the reading of [The Idea](https://github.com/gcanti/io-ts/blob/master/index.md#the-idea) section
 from the io-ts documentation.
 
-## Types and combinators
-
-All the implemented codecs and combinators are exposed through methods of the class `Facile\PhpCodec\Codecs`.
-
-| Typescript Type | Psalm Type | Codec | 
-| --- | --- | --- |
-| `unknown` | `mixed` | `Codecs::mixed()` |
-| `null` | `null` | `Codecs::null()` |
-| `bool` | `bool` | `Codecs::bool()` |
-| `number` | `int` | `Codecs::int()` |
-| `number` | `float` | `Codecs::float()` |
-| `string` | `string` | `Codecs::string()` |
-| `'s'` | `'s'` | `Codecs::literal('s')` |
-| `Array<T>` | `list<T>` | `Codecs::listt(Type $item)` |
-| - | `A::class` | `Codecs::classFromArray(Type[] $props, callable $factory, A::class)` |
+## Decoders
 
-## Examples
+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 a list of built-in decoders.
 
-For further examples take a look to the [examples](https://github.com/facile-it/php-codec/tree/master/tests/examples):
-
-```php
-use Facile\PhpCodec\Codecs;
-
-$codec = Codecs::classFromArray(
-    [
-        'a' => Codecs::string(),
-        'b' => Codecs::int(),
-        'c' => Codecs::bool(),
-        'd' => Codecs::float()
-    ],
-    function (string $a, int $b, bool $c, float $d): Foo {
-        return new Foo($a, $b, $c, $d);
-    },
-    Foo::class
-);
-
-// Gives an instance of ValidationSuccess<Foo>
-$validation = $codec->decode(['a' => 'hey', 'b' => 123, 'c' => false, 'd' => 1.23]);
-
-// Gives an instance of ValidationFailures
-$failures = $codec->decode(['a' => 'hey', 'b' => 123, 'c' => 'a random string', 'd' => 1.23]);
-
-class Foo { 
-    public function __construct(
-        string $a,
-        int $b,
-        bool $c,
-        float $d
-    ) {
-    // [...]
-    }
-}
-```
+## Examples
 
+Take a look to the [examples](https://github.com/facile-it/php-codec/tree/master/tests/examples) folder.

composer.json

@@ -3,12 +3,12 @@
     "description": "A partial porting of io-ts in PHP",
     "type": "library",
     "require-dev": {
-        "vimeo/psalm": "^4.4.0",
         "phpunit/phpunit": "^8.5",
         "giorgiosironi/eris": "^0.12.0",
         "phpunit/php-code-coverage": "^7.0",
         "phpat/phpat": "^0.7.5",
-        "facile-it/facile-coding-standard": "^0.4.1"
+        "facile-it/facile-coding-standard": "^0.4.1",
+        "icomefromthenet/reverse-regex": "^0.1.0"
     },
     "license": "MIT",
     "authors": [
@@ -35,7 +35,8 @@
         }
     },
     "require": {
-        "php": "^7.2 | ^8.0"
+        "php": "^7.2 | ^8.0",
+        "vimeo/psalm": "^4.8"
     },
     "prefer-stable": true,
     "archive": {

psalm.xml

@@ -10,10 +10,10 @@
     xsi:schemaLocation="https://getpsalm.org/schema/config vendor/vimeo/psalm/config.xsd"
 >
     <projectFiles>
-        <directory name="src" />
-        <directory name="tests/type-assertions" />
+        <directory name="src"/>
+        <directory name="tests"/>
         <ignoreFiles>
-            <directory name="vendor" />
+            <directory name="vendor"/>
         </ignoreFiles>
     </projectFiles>
 </psalm>

src/Codecs.php

@@ -4,70 +4,66 @@
 
 namespace Facile\PhpCodec;
 
-use Facile\PhpCodec\Internal\Arrays\ListCodec;
-use Facile\PhpCodec\Internal\Arrays\MapType;
-use Facile\PhpCodec\Internal\Combinators\ClassFromArray;
-use Facile\PhpCodec\Internal\Combinators\ComposeCodec;
-use Facile\PhpCodec\Internal\Combinators\LiteralType;
-use Facile\PhpCodec\Internal\Combinators\UnionCodec;
+use Facile\PhpCodec\Internal\Combinators\PipeCodec;
 use Facile\PhpCodec\Internal\IdentityEncoder;
-use Facile\PhpCodec\Internal\Primitives\BoolType;
-use Facile\PhpCodec\Internal\Primitives\CallableDecoder;
-use Facile\PhpCodec\Internal\Primitives\FloatType;
-use Facile\PhpCodec\Internal\Primitives\IntDecoder;
-use Facile\PhpCodec\Internal\Primitives\MixedDecoder;
-use Facile\PhpCodec\Internal\Primitives\NullType;
-use Facile\PhpCodec\Internal\Primitives\StringType;
 use Facile\PhpCodec\Internal\Primitives\UndefinedDecoder;
-use Facile\PhpCodec\Internal\Useful\DateTimeFromIsoStringType;
-use Facile\PhpCodec\Internal\Useful\IntFromStringDecoder;
-use Facile\PhpCodec\Internal\Useful\RegexType;
 use Facile\PhpCodec\Utils\ConcreteCodec;
 
 final class Codecs
 {
     /**
      * @psalm-return Codec<null, mixed, null>
+     *
+     * @deprecated use decoder instead
+     * @see Decoders::null()
      */
     public static function null(): Codec
     {
-        return new NullType();
+        return self::fromDecoder(Decoders::null());
     }
 
     /**
      * @psalm-return Codec<string, mixed, string>
+     *
+     * @deprecated use decoder instead
+     * @see Decoders::string()
      */
     public static function string(): Codec
     {
-        return new StringType();
+        return self::fromDecoder(Decoders::string());
     }
 
     /**
-     * @template I of mixed
-     * @psalm-return Codec<int, I, int>
+     * @psalm-return Codec<int, mixed, int>
      *
      * @deprecated use decoder instead
      * @see Decoders::int()
      */
     public static function int(): Codec
     {
-        return self::fromDecoder(new IntDecoder());
+        return self::fromDecoder(Decoders::int());
     }
 
     /**
      * @psalm-return Codec<float, mixed, float>
+     *
+     * @deprecated use decoder instead
+     * @see Decoders::float()
      */
     public static function float(): Codec
     {
-        return new FloatType();
+        return self::fromDecoder(Decoders::float());
     }
 
     /**
      * @psalm-return Codec<bool, mixed, bool>
+     *
+     * @deprecated use decoder instead
+     * @see Decoders::bool()
      */
     public static function bool(): Codec
     {
-        return new BoolType();
+        return self::fromDecoder(Decoders::bool());
     }
 
     /**
@@ -76,10 +72,13 @@ public static function bool(): Codec
      * @psalm-return Codec<T, mixed, T>
      *
      * @param mixed $x
+     *
+     * @deprecated use decoder instead
+     * @see Decoders::literal()
      */
     public static function literal($x): Codec
     {
-        return new LiteralType($x);
+        return self::fromDecoder(Decoders::literal($x));
     }
 
     /**
@@ -90,42 +89,60 @@ public static function literal($x): Codec
      */
     public static function intFromString(): Codec
     {
-        return self::fromDecoder(new IntFromStringDecoder());
+        return self::fromDecoder(Decoders::intFromString());
     }
 
     /**
-     * @psalm-return Codec<\DateTime, string, \DateTime>
+     * @psalm-return Codec<\DateTimeInterface, string, \DateTimeInterface>
+     *
+     * @deprecated use decoder instead
+     * @see Decoders::dateTimeFromString()
      */
     public static function dateTimeFromIsoString(): Codec
     {
-        return new DateTimeFromIsoStringType();
+        return self::fromDecoder(Decoders::dateTimeFromString());
     }
 
     /**
      * @psalm-template T
      * @psalm-param Codec<T, mixed, T> $itemCodec
      * @psalm-return Codec<list<T>, mixed, list<T>>
+     *
+     * @deprecated use decoder instead
+     * @see Decoders::listOf()
      */
     public static function listt(Codec $itemCodec): Codec
     {
-        return new ListCodec($itemCodec);
+        return self::fromDecoder(Decoders::listOf($itemCodec));
     }
 
     /**
-     * @psalm-template T
-     * @psalm-param non-empty-array<string, Codec> $props
+     * @psalm-template T of object
+     * @psalm-template K of array-key
+     * @psalm-template Vs
+     * @psalm-template PD of non-empty-array<K, Decoder<mixed, Vs>>
+     * @psalm-param PD $props
      * @psalm-param callable(...mixed):T           $factory
      * @psalm-param class-string<T>                $fqcn
      * @psalm-return Codec<T, mixed, T>
+     *
+     * @deprecated use decoder instead
+     * @see Decoders::classFromArrayPropsDecoder()
      */
     public static function classFromArray(
         array $props,
         callable $factory,
         string $fqcn
     ): Codec {
-        return self::pipe(
-            new MapType(),
-            new ClassFromArray($props, $factory, $fqcn)
+        /** @var Decoder<mixed, non-empty-array<array-key, Vs>> $propsDecoder */
+        $propsDecoder = Decoders::arrayProps($props);
+
+        return self::fromDecoder(
+            Decoders::classFromArrayPropsDecoder(
+                $propsDecoder,
+                $factory,
+                $fqcn
+            )
         );
     }
 
@@ -150,7 +167,7 @@ public static function classFromArray(
      * @psalm-return (func_num_args() is 2 ? Codec<B, IA, OB>
      *                          : (func_num_args() is 3 ? Codec<C, IA, OC>
      *                          : (func_num_args() is 4 ? Codec<D, IA, OD>
-     *                          : (func_num_args() is 5 ? Codec<E, IA, OC> : Codec)
+     *                          : (func_num_args() is 5 ? Codec<E, IA, OE> : Codec)
      *                          )))
      */
     public static function pipe(
@@ -161,32 +178,45 @@ public static function pipe(
         ?Codec $e = null
     ): Codec {
         // Order is important: composition is not commutative
-        return new ComposeCodec(
+        return new PipeCodec(
             $a,
             $c instanceof Codec
                 ? self::pipe($b, $c, $d, $e)
                 : $b
         );
     }
 
+    /**
+     * @param Codec $a
+     * @param Codec $b
+     * @param Codec ...$others
+     *
+     * @return Codec
+     *
+     * @deprecated use decoder instead
+     * @see Decoders::union()
+     */
     public static function union(Codec $a, Codec $b, Codec ...$others): Codec
     {
         // Order is important, this is not commutative
         return \array_reduce(
             $others,
             static function (Codec $carry, Codec $current): Codec {
-                return new UnionCodec($current, $carry);
+                return self::fromDecoder(Decoders::union($current, $carry));
             },
-            new UnionCodec($a, $b)
+            self::fromDecoder(Decoders::union($a, $b))
         );
     }
 
     /**
      * @psalm-return Codec<string[], string, string[]>
+     *
+     * @deprecated use decoder instead
+     * @see Decoders::regex()
      */
     public static function regex(string $regex): Codec
     {
-        return new RegexType($regex);
+        return self::fromDecoder(Decoders::regex($regex));
     }
 
     /**
@@ -226,7 +256,7 @@ public static function undefined($default = null): Codec
      */
     public static function mixed(): Codec
     {
-        return self::fromDecoder(new MixedDecoder());
+        return self::fromDecoder(Decoders::mixed());
     }
 
     /**
@@ -237,6 +267,6 @@ public static function mixed(): Codec
      */
     public static function callable(): Codec
     {
-        return self::fromDecoder(new CallableDecoder());
+        return self::fromDecoder(Decoders::callable());
     }
 }