feat(type): Introduce type constructor purity (#461)

azjezz · Apr 5, 2024 · 5ab5416 · 5ab5416
1 parent 12ab1d9
commit 5ab5416
Show file tree

Hide file tree

Showing 73 changed files with 263 additions and 47 deletions.
diff --git a/docs/component/type.md b/docs/component/type.md
@@ -12,54 +12,54 @@
 
 #### `Functions`
 
-- [array_key](./../../src/Psl/Type/array_key.php#L10)
-- [backed_enum](./../../src/Psl/Type/backed_enum.php#L16)
-- [bool](./../../src/Psl/Type/bool.php#L10)
-- [class_string](./../../src/Psl/Type/class_string.php#L14)
-- [converted](./../../src/Psl/Type/converted.php#L21)
-- [dict](./../../src/Psl/Type/dict.php#L16)
-- [f32](./../../src/Psl/Type/f32.php#L12)
-- [f64](./../../src/Psl/Type/f64.php#L12)
-- [float](./../../src/Psl/Type/float.php#L10)
-- [i16](./../../src/Psl/Type/i16.php#L12)
-- [i32](./../../src/Psl/Type/i32.php#L12)
-- [i64](./../../src/Psl/Type/i64.php#L12)
-- [i8](./../../src/Psl/Type/i8.php#L12)
-- [instance_of](./../../src/Psl/Type/instance_of.php#L14)
-- [int](./../../src/Psl/Type/int.php#L10)
-- [intersection](./../../src/Psl/Type/intersection.php#L18)
+- [array_key](./../../src/Psl/Type/array_key.php#L14)
+- [backed_enum](./../../src/Psl/Type/backed_enum.php#L18)
+- [bool](./../../src/Psl/Type/bool.php#L14)
+- [class_string](./../../src/Psl/Type/class_string.php#L16)
+- [converted](./../../src/Psl/Type/converted.php#L23)
+- [dict](./../../src/Psl/Type/dict.php#L18)
+- [f32](./../../src/Psl/Type/f32.php#L16)
+- [f64](./../../src/Psl/Type/f64.php#L16)
+- [float](./../../src/Psl/Type/float.php#L14)
+- [i16](./../../src/Psl/Type/i16.php#L16)
+- [i32](./../../src/Psl/Type/i32.php#L16)
+- [i64](./../../src/Psl/Type/i64.php#L16)
+- [i8](./../../src/Psl/Type/i8.php#L16)
+- [instance_of](./../../src/Psl/Type/instance_of.php#L16)
+- [int](./../../src/Psl/Type/int.php#L14)
+- [intersection](./../../src/Psl/Type/intersection.php#L20)
 - [is_nan](./../../src/Psl/Type/is_nan.php#L14)
-- [iterable](./../../src/Psl/Type/iterable.php#L16)
-- [literal_scalar](./../../src/Psl/Type/literal_scalar.php#L14)
-- [map](./../../src/Psl/Type/map.php#L18)
-- [mixed](./../../src/Psl/Type/mixed.php#L10)
-- [mixed_dict](./../../src/Psl/Type/mixed_dict.php#L10)
-- [mixed_vec](./../../src/Psl/Type/mixed_vec.php#L10)
-- [mutable_map](./../../src/Psl/Type/mutable_map.php#L18)
-- [mutable_vector](./../../src/Psl/Type/mutable_vector.php#L16)
-- [non_empty_dict](./../../src/Psl/Type/non_empty_dict.php#L16)
-- [non_empty_string](./../../src/Psl/Type/non_empty_string.php#L10)
-- [non_empty_vec](./../../src/Psl/Type/non_empty_vec.php#L14)
-- [nonnull](./../../src/Psl/Type/nonnull.php#L12)
-- [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)
-- [resource](./../../src/Psl/Type/resource.php#L12)
-- [scalar](./../../src/Psl/Type/scalar.php#L10)
-- [shape](./../../src/Psl/Type/shape.php#L15)
-- [string](./../../src/Psl/Type/string.php#L10)
-- [u16](./../../src/Psl/Type/u16.php#L12)
-- [u32](./../../src/Psl/Type/u32.php#L12)
-- [u8](./../../src/Psl/Type/u8.php#L12)
-- [uint](./../../src/Psl/Type/uint.php#L12)
-- [union](./../../src/Psl/Type/union.php#L16)
-- [unit_enum](./../../src/Psl/Type/unit_enum.php#L16)
-- [vec](./../../src/Psl/Type/vec.php#L14)
-- [vector](./../../src/Psl/Type/vector.php#L16)
+- [iterable](./../../src/Psl/Type/iterable.php#L18)
+- [literal_scalar](./../../src/Psl/Type/literal_scalar.php#L16)
+- [map](./../../src/Psl/Type/map.php#L20)
+- [mixed](./../../src/Psl/Type/mixed.php#L14)
+- [mixed_dict](./../../src/Psl/Type/mixed_dict.php#L12)
+- [mixed_vec](./../../src/Psl/Type/mixed_vec.php#L12)
+- [mutable_map](./../../src/Psl/Type/mutable_map.php#L20)
+- [mutable_vector](./../../src/Psl/Type/mutable_vector.php#L18)
+- [non_empty_dict](./../../src/Psl/Type/non_empty_dict.php#L18)
+- [non_empty_string](./../../src/Psl/Type/non_empty_string.php#L14)
+- [non_empty_vec](./../../src/Psl/Type/non_empty_vec.php#L16)
+- [nonnull](./../../src/Psl/Type/nonnull.php#L16)
+- [null](./../../src/Psl/Type/null.php#L14)
+- [nullable](./../../src/Psl/Type/nullable.php#L16)
+- [num](./../../src/Psl/Type/num.php#L14)
+- [numeric_string](./../../src/Psl/Type/numeric_string.php#L14)
+- [object](./../../src/Psl/Type/object.php#L14)
+- [optional](./../../src/Psl/Type/optional.php#L16)
+- [positive_int](./../../src/Psl/Type/positive_int.php#L16)
+- [resource](./../../src/Psl/Type/resource.php#L14)
+- [scalar](./../../src/Psl/Type/scalar.php#L14)
+- [shape](./../../src/Psl/Type/shape.php#L17)
+- [string](./../../src/Psl/Type/string.php#L14)
+- [u16](./../../src/Psl/Type/u16.php#L16)
+- [u32](./../../src/Psl/Type/u32.php#L16)
+- [u8](./../../src/Psl/Type/u8.php#L16)
+- [uint](./../../src/Psl/Type/uint.php#L16)
+- [union](./../../src/Psl/Type/union.php#L18)
+- [unit_enum](./../../src/Psl/Type/unit_enum.php#L18)
+- [vec](./../../src/Psl/Type/vec.php#L16)
+- [vector](./../../src/Psl/Type/vector.php#L18)
 
 #### `Interfaces`
 

diff --git a/src/Psl/Type/Internal/ArrayKeyType.php b/src/Psl/Type/Internal/ArrayKeyType.php
@@ -14,6 +14,9 @@
  */
 final class ArrayKeyType extends UnionType
 {
+    /**
+     * @psalm-mutation-free
+     */
     public function __construct()
     {
         /** @psalm-suppress MissingThrowsDocblock */

diff --git a/src/Psl/Type/Internal/BackedEnumType.php b/src/Psl/Type/Internal/BackedEnumType.php
@@ -18,6 +18,8 @@
 final class BackedEnumType extends Type\Type
 {
     /**
+     * @psalm-mutation-free
+     *
      * @param class-string<T> $enum
      */
     public function __construct(

diff --git a/src/Psl/Type/Internal/ClassStringType.php b/src/Psl/Type/Internal/ClassStringType.php
@@ -23,6 +23,8 @@ final class ClassStringType extends Type
     private string $classname;
 
     /**
+     * @psalm-mutation-free
+     *
      * @param class-string<T> $classname
      */
     public function __construct(

diff --git a/src/Psl/Type/Internal/ConvertedType.php b/src/Psl/Type/Internal/ConvertedType.php
@@ -24,6 +24,8 @@
 final class ConvertedType extends Type\Type
 {
     /**
+     * @psalm-mutation-free
+     *
      * @param TypeInterface<I> $from
      * @param TypeInterface<O> $into
      * @param (Closure(I): O) $converter

diff --git a/src/Psl/Type/Internal/DictType.php b/src/Psl/Type/Internal/DictType.php
@@ -23,6 +23,8 @@
 final class DictType extends Type\Type
 {
     /**
+     * @psalm-mutation-free
+     *
      * @param Type\TypeInterface<Tk> $key_type
      * @param Type\TypeInterface<Tv> $value_type
      */

diff --git a/src/Psl/Type/Internal/InstanceOfType.php b/src/Psl/Type/Internal/InstanceOfType.php
@@ -23,6 +23,8 @@ final class InstanceOfType extends Type
     private string $classname;
 
     /**
+     * @psalm-mutation-free
+     *
      * @param class-string<T> $classname
      */
     public function __construct(

diff --git a/src/Psl/Type/Internal/IntersectionType.php b/src/Psl/Type/Internal/IntersectionType.php
@@ -22,6 +22,8 @@
 final class IntersectionType extends Type
 {
     /**
+     * @psalm-mutation-free
+     *
      * @param TypeInterface<Tl> $left_type
      * @param TypeInterface<Tr> $right_type
      */

diff --git a/src/Psl/Type/Internal/IterableType.php b/src/Psl/Type/Internal/IterableType.php
@@ -24,6 +24,8 @@
 final class IterableType extends Type\Type
 {
     /**
+     * @psalm-mutation-free
+     *
      * @param Type\TypeInterface<Tk> $key_type
      * @param Type\TypeInterface<Tv> $value_type
      */

diff --git a/src/Psl/Type/Internal/LiteralScalarType.php b/src/Psl/Type/Internal/LiteralScalarType.php
@@ -19,6 +19,8 @@
 final class LiteralScalarType extends Type\Type
 {
     /**
+     * @psalm-mutation-free
+     *
      * @param T $value
      */
     public function __construct(

diff --git a/src/Psl/Type/Internal/MapType.php b/src/Psl/Type/Internal/MapType.php
@@ -26,6 +26,8 @@
 final class MapType extends Type\Type
 {
     /**
+     * @psalm-mutation-free
+     *
      * @param Type\TypeInterface<Tk> $key_type
      * @param Type\TypeInterface<Tv> $value_type
      */

diff --git a/src/Psl/Type/Internal/MutableMapType.php b/src/Psl/Type/Internal/MutableMapType.php
@@ -26,6 +26,8 @@
 final class MutableMapType extends Type\Type
 {
     /**
+     * @psalm-mutation-free
+     *
      * @param Type\TypeInterface<Tk> $key_type
      * @param Type\TypeInterface<Tv> $value_type
      */

diff --git a/src/Psl/Type/Internal/MutableVectorType.php b/src/Psl/Type/Internal/MutableVectorType.php
@@ -24,6 +24,8 @@
 final class MutableVectorType extends Type\Type
 {
     /**
+     * @psalm-mutation-free
+     *
      * @param Type\TypeInterface<T> $value_type
      */
     public function __construct(

diff --git a/src/Psl/Type/Internal/NonEmptyDictType.php b/src/Psl/Type/Internal/NonEmptyDictType.php
@@ -24,6 +24,8 @@
 final class NonEmptyDictType extends Type\Type
 {
     /**
+     * @psalm-mutation-free
+     *
      * @param Type\TypeInterface<Tk> $key_type
      * @param Type\TypeInterface<Tv> $value_type
      */

diff --git a/src/Psl/Type/Internal/NonEmptyVecType.php b/src/Psl/Type/Internal/NonEmptyVecType.php
@@ -23,6 +23,8 @@
 final class NonEmptyVecType extends Type\Type
 {
     /**
+     * @psalm-mutation-free
+     *
      * @param Type\TypeInterface<Tv> $value_type
      */
     public function __construct(

diff --git a/src/Psl/Type/Internal/NullableType.php b/src/Psl/Type/Internal/NullableType.php
@@ -18,6 +18,8 @@
 final class NullableType extends Type\Type
 {
     /**
+     * @psalm-mutation-free
+     *
      * @param Type\TypeInterface<T> $inner
      */
     public function __construct(

diff --git a/src/Psl/Type/Internal/NumType.php b/src/Psl/Type/Internal/NumType.php
@@ -11,6 +11,9 @@
  */
 final class NumType extends UnionType
 {
+    /**
+     * @psalm-mutation-free
+     */
     public function __construct()
     {
         /** @psalm-suppress MissingThrowsDocblock */

diff --git a/src/Psl/Type/Internal/OptionalType.php b/src/Psl/Type/Internal/OptionalType.php
@@ -18,6 +18,8 @@
 final class OptionalType extends Type\Type
 {
     /**
+     * @psalm-mutation-free
+     *
      * @param Type\TypeInterface<T> $inner
      */
     public function __construct(

diff --git a/src/Psl/Type/Internal/ResourceType.php b/src/Psl/Type/Internal/ResourceType.php
@@ -18,6 +18,9 @@
  */
 final class ResourceType extends Type\Type
 {
+    /**
+     * @psalm-mutation-free
+     */
     public function __construct(
         private ?string $kind = null
     ) {

diff --git a/src/Psl/Type/Internal/ScalarType.php b/src/Psl/Type/Internal/ScalarType.php
@@ -11,6 +11,9 @@
  */
 final class ScalarType extends UnionType
 {
+    /**
+     * @psalm-mutation-free
+     */
     public function __construct()
     {
         /** @psalm-suppress MissingThrowsDocblock */

diff --git a/src/Psl/Type/Internal/ShapeType.php b/src/Psl/Type/Internal/ShapeType.php
@@ -34,12 +34,15 @@ final class ShapeType extends Type\Type
     private array $requiredElements;
 
     /**
+     * @psalm-mutation-free
+     *
      * @param array<Tk, Type\TypeInterface<Tv>> $elements_types
      */
     public function __construct(
         private array $elements_types,
         private bool $allow_unknown_fields = false,
     ) {
+        /** @psalm-suppress ImpureFunctionCall - This implementation is pure. */
         $this->requiredElements = array_filter(
             $elements_types,
             static fn (Type\TypeInterface $element): bool => ! $element->isOptional()

diff --git a/src/Psl/Type/Internal/UnionType.php b/src/Psl/Type/Internal/UnionType.php
@@ -20,6 +20,8 @@
 class UnionType extends Type\Type
 {
     /**
+     * @psalm-mutation-free
+     *
      * @param Type\TypeInterface<Tl> $left_type
      * @param Type\TypeInterface<Tr> $right_type
      */

diff --git a/src/Psl/Type/Internal/UnitEnumType.php b/src/Psl/Type/Internal/UnitEnumType.php
@@ -18,6 +18,8 @@
 final class UnitEnumType extends Type\Type
 {
     /**
+     * @psalm-mutation-free
+     *
      * @param class-string<T> $enum
      */
     public function __construct(

diff --git a/src/Psl/Type/Internal/VecType.php b/src/Psl/Type/Internal/VecType.php
@@ -23,6 +23,8 @@
 final class VecType extends Type\Type
 {
     /**
+     * @psalm-mutation-free
+     *
      * @param Type\TypeInterface<Tv> $value_type
      */
     public function __construct(

diff --git a/src/Psl/Type/Internal/VectorType.php b/src/Psl/Type/Internal/VectorType.php
@@ -24,6 +24,8 @@
 final class VectorType extends Type\Type
 {
     /**
+     * @psalm-mutation-free
+     *
      * @param Type\TypeInterface<T> $value_type
      */
     public function __construct(

diff --git a/src/Psl/Type/array_key.php b/src/Psl/Type/array_key.php
@@ -5,6 +5,10 @@
 namespace Psl\Type;
 
 /**
+ * @psalm-pure
+ *
+ * @psalm-suppress ImpureStaticVariable - The $instance is always the same and is considered pure.
+ *
  * @return TypeInterface<array-key>
  */
 function array_key(): TypeInterface

diff --git a/src/Psl/Type/backed_enum.php b/src/Psl/Type/backed_enum.php
@@ -7,6 +7,8 @@
 use BackedEnum;
 
 /**
+ * @psalm-pure
+ *
  * @template T of BackedEnum
  *
  * @param class-string<T> $enum

diff --git a/src/Psl/Type/bool.php b/src/Psl/Type/bool.php
@@ -5,6 +5,10 @@
 namespace Psl\Type;
 
 /**
+ * @psalm-pure
+ *
+ * @psalm-suppress ImpureStaticVariable - The $instance is always the same and is considered pure.
+ *
  * @return TypeInterface<bool>
  */
 function bool(): TypeInterface

diff --git a/src/Psl/Type/class_string.php b/src/Psl/Type/class_string.php
@@ -5,6 +5,8 @@
 namespace Psl\Type;
 
 /**
+ * @psalm-pure
+ *
  * @template T
  *
  * @param class-string<T> $classname

diff --git a/src/Psl/Type/converted.php b/src/Psl/Type/converted.php
@@ -7,6 +7,8 @@
 use Closure;
 
 /**
+ * @psalm-pure
+ *
  * @template I
  * @template O
  *

diff --git a/src/Psl/Type/dict.php b/src/Psl/Type/dict.php
@@ -5,6 +5,8 @@
 namespace Psl\Type;
 
 /**
+ * @psalm-pure
+ *
  * @template Tk of array-key
  * @template Tv
  *

diff --git a/src/Psl/Type/f32.php b/src/Psl/Type/f32.php
@@ -5,6 +5,10 @@
 namespace Psl\Type;
 
 /**
+ * @psalm-pure
+ *
+ * @psalm-suppress ImpureStaticVariable - The $instance is always the same and is considered pure.
+ *
  * @ara-return TypeInterface<f32>
  *
  * @return TypeInterface<float>