Introduce numeric-string type (#406)

docs/component/type.md

@@ -43,6 +43,7 @@
 - [null](./../../src/Psl/Type/null.php#L10)
 - [nullable](./../../src/Psl/Type/nullable.php#L14)
 - [num](./../../src/Psl/Type/num.php#L10)
+- [numeric_string](./../../src/Psl/Type/numeric_string.php#L10)
 - [object](./../../src/Psl/Type/object.php#L10)
 - [optional](./../../src/Psl/Type/optional.php#L14)
 - [positive_int](./../../src/Psl/Type/positive_int.php#L12)

src/Psl/Internal/Loader.php

@@ -331,6 +331,7 @@ final class Loader
         'Psl\\Type\\string' => 'Psl/Type/string.php',
         'Psl\\Type\\non_empty_dict' => 'Psl/Type/non_empty_dict.php',
         'Psl\\Type\\non_empty_string' => 'Psl/Type/non_empty_string.php',
+        'Psl\\Type\\numeric_string' => 'Psl/Type/numeric_string.php',
         'Psl\\Type\\non_empty_vec' => 'Psl/Type/non_empty_vec.php',
         'Psl\\Type\\scalar' => 'Psl/Type/scalar.php',
         'Psl\\Type\\shape' => 'Psl/Type/shape.php',
@@ -653,6 +654,7 @@ final class Loader
         'Psl\\Type\\Internal\\ShapeType' => 'Psl/Type/Internal/ShapeType.php',
         'Psl\\Type\\Internal\\NonEmptyDictType' => 'Psl/Type/Internal/NonEmptyDictType.php',
         'Psl\\Type\\Internal\\NonEmptyStringType' => 'Psl/Type/Internal/NonEmptyStringType.php',
+        'Psl\\Type\\Internal\\NumericStringType' => 'Psl/Type/Internal/NumericStringType.php',
         'Psl\\Type\\Internal\\NonEmptyVecType' => 'Psl/Type/Internal/NonEmptyVecType.php',
         'Psl\\Type\\Internal\\UIntType' => 'Psl/Type/Internal/UIntType.php',
         'Psl\\Type\\Internal\\I8Type' => 'Psl/Type/Internal/I8Type.php',

src/Psl/Type/Internal/NumericStringType.php

@@ -0,0 +1,77 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\Type\Internal;
+
+use Psl\Type;
+use Psl\Type\Exception\AssertException;
+use Psl\Type\Exception\CoercionException;
+use Stringable;
+
+use function is_numeric;
+use function is_string;
+
+/**
+ * @extends Type\Type<numeric-string>
+ *
+ * @internal
+ */
+final class NumericStringType extends Type\Type
+{
+    /**
+     * @psalm-assert-if-true numeric-string $value
+     */
+    public function matches(mixed $value): bool
+    {
+        return is_string($value) && is_numeric($value);
+    }
+
+    /**
+     * @throws CoercionException
+     *
+     * @return numeric-string
+     */
+    public function coerce(mixed $value): string
+    {
+        if (is_string($value) && is_numeric($value)) {
+            /** @var numeric-string $value */
+            return $value;
+        }
+
+        if (is_numeric($value)) {
+            return (string) $value;
+        }
+
+        if ($value instanceof Stringable) {
+            $str = (string) $value;
+            if (is_numeric($str)) {
+                return $str;
+            }
+        }
+
+        throw CoercionException::withValue($value, $this->toString(), $this->getTrace());
+    }
+
+    /**
+     * @throws AssertException
+     *
+     * @return numeric-string
+     *
+     * @psalm-assert numeric-string $value
+     */
+    public function assert(mixed $value): string
+    {
+        if (is_string($value) && is_numeric($value)) {
+            /** @var numeric-string $value */
+            return $value;
+        }
+
+        throw AssertException::withValue($value, $this->toString(), $this->getTrace());
+    }
+
+    public function toString(): string
+    {
+        return 'numeric-string';
+    }
+}

src/Psl/Type/numeric_string.php

@@ -0,0 +1,13 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\Type;
+
+/**
+ * @return TypeInterface<numeric-string>
+ */
+function numeric_string(): TypeInterface
+{
+    return new Internal\NumericStringType();
+}

tests/unit/Type/NumericStringTypeTest.php

@@ -0,0 +1,52 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\Tests\Unit\Type;
+
+use Psl\Type;
+
+/**
+ * @extends TypeTest<numeric-string>
+ */
+final class NumericStringTypeTest extends TypeTest
+{
+    /**
+     * @return Type\Type<numeric-string>
+     */
+    public function getType(): Type\TypeInterface
+    {
+        return Type\numeric_string();
+    }
+
+    public function getValidCoercions(): iterable
+    {
+        yield [123, '123'];
+        yield [0, '0'];
+        yield [1.0, '1'];
+        yield [1.23, '1.23'];
+        yield ['0', '0'];
+        yield ['123', '123'];
+        yield ['1e23', '1e23'];
+        yield [$this->stringable('123'), '123'];
+    }
+
+    public function getInvalidCoercions(): iterable
+    {
+        yield [''];
+        yield ['hello', 'hello'];
+        yield [$this->stringable('hello'), 'hello'];
+        yield [[]];
+        yield [[1]];
+        yield [Type\bool()];
+        yield [null];
+        yield [false];
+        yield [true];
+        yield [STDIN];
+    }
+
+    public function getToStringExamples(): iterable
+    {
+        yield [$this->getType(), 'numeric-string'];
+    }
+}