feat(type): add always_assert type (#522)

Signed-off-by: azjezz <[email protected]>

Author: azjezz

src/Psl/Internal/Loader.php

@@ -353,6 +353,7 @@ final class Loader
         'Psl\\Type\\int' => 'Psl/Type/int.php',
         'Psl\\Type\\intersection' => 'Psl/Type/intersection.php',
         'Psl\\Type\\iterable' => 'Psl/Type/iterable.php',
+        'Psl\\Type\\always_assert' => 'Psl/Type/always_assert.php',
         'Psl\\Type\\container' => 'Psl/Type/container.php',
         'Psl\\Type\\mixed' => 'Psl/Type/mixed.php',
         'Psl\\Type\\mixed_dict' => 'Psl/Type/mixed_dict.php',
@@ -671,6 +672,7 @@ final class Loader
         'Psl\\Result\\Stats' => 'Psl/Result/Stats.php',
         'Psl\\Result\\Success' => 'Psl/Result/Success.php',
         'Psl\\Type\\Internal\\ArrayKeyType' => 'Psl/Type/Internal/ArrayKeyType.php',
+        'Psl\\Type\\Internal\\AlwaysAssertType' => 'Psl/Type/Internal/AlwaysAssertType.php',
         'Psl\\Type\\Internal\\ContainerType' => 'Psl/Type/Internal/ContainerType.php',
         'Psl\\Type\\Internal\\MapType' => 'Psl/Type/Internal/MapType.php',
         'Psl\\Type\\Internal\\MutableMapType' => 'Psl/Type/Internal/MutableMapType.php',

src/Psl/Type/Internal/AlwaysAssertType.php

@@ -0,0 +1,65 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\Type\Internal;
+
+use Psl\Type;
+use Psl\Type\Exception\AssertException;
+use Psl\Type\Exception\CoercionException;
+
+/**
+ * @template T
+ *
+ * @ara-extends Type\Type<T>
+ *
+ * @extends Type\Type<T>
+ *
+ * @internal
+ */
+final readonly class AlwaysAssertType extends Type\Type
+{
+    /**
+     * @psalm-mutation-free
+     *
+     * @param Type\TypeInterface<T> $inner
+     */
+    public function __construct(
+        private Type\TypeInterface $inner,
+    ) {
+    }
+
+    /**
+     * @throws CoercionException
+     *
+     * @return T
+     */
+    #[\Override]
+    public function coerce(mixed $value): mixed
+    {
+        if ($this->inner->matches($value)) {
+            return $value;
+        }
+
+        throw CoercionException::withValue($value, $this->toString());
+    }
+
+    /**
+     * @psalm-assert T $value
+     *
+     * @throws AssertException
+     *
+     * @return T
+     */
+    #[\Override]
+    public function assert(mixed $value): mixed
+    {
+        return $this->inner->assert($value);
+    }
+
+    #[\Override]
+    public function toString(): string
+    {
+        return $this->inner->toString();
+    }
+}

src/Psl/Type/README.md

@@ -1381,3 +1381,26 @@ When the iterable value does not match the specified type, you will get detailed
 > Could not coerce "stdClass" to type "Psl\Collection\VectorInterface<array{'user': string, 'comment': string}>" **at path "foo.user".**
 
 ---
+
+#### [always_assert](always_assert.php)
+
+```hack
+@pure
+@template T
+Type\always_assert(TypeInterface<T> $type): TypeInterface<T>
+```
+
+Provides a type that will always assert that the input value matches the input, even when coercing.
+
+```php
+use Psl\Type;
+
+$integer = Type\int();
+$always_assert_integer = Type\always_assert(Type\int());
+
+$integer->assert(1); // Ok.
+$always_assert_integer->assert(1); // Ok.
+
+$integer->coerce('1'); // Ok.
+$always_assert_integer->coerce('1'); // Error: Could not coerce "string" to type "int".
+```

src/Psl/Type/always_assert.php

@@ -0,0 +1,22 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\Type;
+
+/**
+ * Create a new type that always asserts that the value matches the provided type,
+ * even when coercing.
+ *
+ * @psalm-pure
+ *
+ * @template T
+ *
+ * @param TypeInterface<T> $type
+ *
+ * @return TypeInterface<T>
+ */
+function always_assert(TypeInterface $type): TypeInterface
+{
+    return new Internal\AlwaysAssertType($type);
+}

tests/unit/Type/AlwaysAssertTypeTest.php

@@ -0,0 +1,69 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\Tests\Unit\Type;
+
+use Psl\Math;
+use Psl\Type;
+
+final class AlwaysAssertTypeTest extends TypeTest
+{
+    #[\Override]
+    public function getType(): Type\TypeInterface
+    {
+        return Type\always_assert(Type\int());
+    }
+
+    #[\Override]
+    public function getValidCoercions(): iterable
+    {
+        yield [123, 123];
+        yield [0, 0];
+        yield [Math\INT64_MAX, Math\INT64_MAX];
+        yield [-321, -321];
+    }
+
+    #[\Override]
+    public function getInvalidCoercions(): iterable
+    {
+        yield [1.23];
+        yield ['1.23'];
+        yield ['1e123'];
+        yield [''];
+        yield [[]];
+        yield [[123]];
+        yield [null];
+        yield [false];
+        yield [$this->stringable('1.23')];
+        yield [$this->stringable('-007')];
+        yield ['-007'];
+        yield ['9223372036854775808'];
+        yield [$this->stringable('9223372036854775808')];
+        yield ['-9223372036854775809'];
+        yield [$this->stringable('-9223372036854775809')];
+        yield ['0xFF'];
+        yield [''];
+        yield ['123'];
+        yield ['0'];
+        yield [$this->stringable('123')];
+        yield [$this->stringable((string) Math\INT16_MAX)];
+        yield [$this->stringable((string) Math\INT64_MAX)];
+        yield [(string) Math\INT64_MAX];
+        yield [$this->stringable('-321')];
+        yield ['-321'];
+        yield ['7'];
+        yield ['07'];
+        yield ['007'];
+        yield ['000'];
+        yield [1.0];
+    }
+
+    #[\Override]
+    public function getToStringExamples(): iterable
+    {
+        yield [Type\always_assert(Type\int()), 'int'];
+        yield [Type\always_assert(Type\string()), 'string'];
+        yield [Type\always_assert(Type\bool()), 'bool'];
+    }
+}