Invariant generic T in Type

vudaltsov · vudaltsov · commit 93c705b686d3 · 2026-02-11T03:10:33.000+03:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -5,6 +5,12 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.8.0] 2026-02-11
+
+### Changed
+
+- **BC Break:** Make generic `T` in `Typhoon\Type` invariant.
+
 ## [0.7.0] 2025-11-20
 
 In this release, we refocus the library: `typhoon/type` now contains only the types necessary for building
diff --git a/generator/Spec/Template.php b/generator/Spec/Template.php
@@ -20,7 +20,7 @@ public function __construct(
     public function declaration(): string
     {
         return \sprintf(
-            '@template-covariant %s%s%s',
+            '@template %s%s%s',
             $this->name,
             $this->of === null ? '' : ' of ' . $this->of,
             $this->default === null ? '' : ' = ' . $this->default,
diff --git a/generator/Spec/Type.php b/generator/Spec/Type.php
@@ -185,9 +185,15 @@ static function (array $matches) use ($typesByName, &$firstType): string {
             return "return \$this->{$firstType->name}({$code});";
         }
 
+        $unionFix = '';
+
+        if (str_contains($code, 'UnionT([')) {
+            $unionFix = ' // @phpstan-ignore argument.type';
+        }
+
         return <<<PHP
             /** @var \\{$firstType->className()} */
-            static \$reduced = {$code};
+            static \$reduced = {$code};{$unionFix}
             
             return \$this->{$firstType->name}(\$reduced);
             PHP;
diff --git a/src/Type.php b/src/Type.php
@@ -8,7 +8,7 @@
 
 /**
  * @api
- * @template-covariant T = mixed
+ * @template T = mixed
  */
 interface Type
 {
diff --git a/src/Type/ArrayT.php b/src/Type/ArrayT.php
@@ -12,8 +12,8 @@
 
 /**
  * @api
- * @template-covariant K of array-key = array-key
- * @template-covariant V = mixed
+ * @template K of array-key = array-key
+ * @template V = mixed
  * @implements Type<array<K, V>>
  * @codeCoverageIgnore
  */
diff --git a/src/Type/BitmaskT.php b/src/Type/BitmaskT.php
@@ -12,7 +12,7 @@
 
 /**
  * @api
- * @template-covariant T of int = int
+ * @template T of int = int
  * @implements Type<T>
  * @codeCoverageIgnore
  */
diff --git a/src/Type/CallableT.php b/src/Type/CallableT.php
@@ -12,7 +12,7 @@
 
 /**
  * @api
- * @template-covariant T of callable = callable
+ * @template T of callable = callable
  * @implements Type<T>
  * @codeCoverageIgnore
  */
diff --git a/src/Type/ClassConstantMaskT.php b/src/Type/ClassConstantMaskT.php
@@ -12,7 +12,7 @@
 
 /**
  * @api
- * @template-covariant T = mixed
+ * @template T = mixed
  * @implements Type<T>
  * @codeCoverageIgnore
  */
diff --git a/src/Type/ClassConstantT.php b/src/Type/ClassConstantT.php
@@ -12,7 +12,7 @@
 
 /**
  * @api
- * @template-covariant T = mixed
+ * @template T = mixed
  * @implements Type<T>
  * @codeCoverageIgnore
  */
diff --git a/src/Type/ClassT.php b/src/Type/ClassT.php
@@ -12,7 +12,7 @@
 
 /**
  * @api
- * @template-covariant T of object = object
+ * @template T of object = object
  * @implements Type<class-string<T>>
  * @codeCoverageIgnore
  */
diff --git a/src/Type/ClosureT.php b/src/Type/ClosureT.php
@@ -12,7 +12,7 @@
 
 /**
  * @api
- * @template-covariant T of \Closure = \Closure
+ * @template T of \Closure = \Closure
  * @implements Type<T>
  * @codeCoverageIgnore
  */
diff --git a/src/Type/ConstantMaskT.php b/src/Type/ConstantMaskT.php
@@ -12,7 +12,7 @@
 
 /**
  * @api
- * @template-covariant T = mixed
+ * @template T = mixed
  * @implements Type<T>
  * @codeCoverageIgnore
  */
diff --git a/src/Type/ConstantT.php b/src/Type/ConstantT.php
@@ -12,7 +12,7 @@
 
 /**
  * @api
- * @template-covariant T = mixed
+ * @template T = mixed
  * @implements Type<T>
  * @codeCoverageIgnore
  */
diff --git a/src/Type/FloatRangeT.php b/src/Type/FloatRangeT.php
@@ -12,7 +12,7 @@
 
 /**
  * @api
- * @template-covariant T of float = float
+ * @template T of float = float
  * @implements Type<T>
  * @codeCoverageIgnore
  */
diff --git a/src/Type/FloatValueT.php b/src/Type/FloatValueT.php
@@ -12,7 +12,7 @@
 
 /**
  * @api
- * @template-covariant T of float = float
+ * @template T of float = float
  * @implements Type<T>
  * @codeCoverageIgnore
  */
diff --git a/src/Type/IntRangeT.php b/src/Type/IntRangeT.php
@@ -12,7 +12,7 @@
 
 /**
  * @api
- * @template-covariant T of int = int
+ * @template T of int = int
  * @implements Type<T>
  * @codeCoverageIgnore
  */
diff --git a/src/Type/IntValueT.php b/src/Type/IntValueT.php
@@ -12,7 +12,7 @@
 
 /**
  * @api
- * @template-covariant T of int = int
+ * @template T of int = int
  * @implements Type<T>
  * @codeCoverageIgnore
  */
diff --git a/src/Type/IntersectionT.php b/src/Type/IntersectionT.php
@@ -12,7 +12,7 @@
 
 /**
  * @api
- * @template-covariant T = mixed
+ * @template T = mixed
  * @implements Type<T>
  * @codeCoverageIgnore
  */
diff --git a/src/Type/IterableT.php b/src/Type/IterableT.php
@@ -12,8 +12,8 @@
 
 /**
  * @api
- * @template-covariant K = mixed
- * @template-covariant V = mixed
+ * @template K = mixed
+ * @template V = mixed
  * @implements Type<iterable<K, V>>
  * @codeCoverageIgnore
  */
diff --git a/src/Type/ListT.php b/src/Type/ListT.php
@@ -12,7 +12,7 @@
 
 /**
  * @api
- * @template-covariant V = mixed
+ * @template V = mixed
  * @implements Type<list<V>>
  * @codeCoverageIgnore
  */
diff --git a/src/Type/NamedObjectT.php b/src/Type/NamedObjectT.php
@@ -12,7 +12,7 @@
 
 /**
  * @api
- * @template-covariant T of object = object
+ * @template T of object = object
  * @implements Type<T>
  * @codeCoverageIgnore
  */
diff --git a/src/Type/ObjectShapeT.php b/src/Type/ObjectShapeT.php
@@ -12,7 +12,7 @@
 
 /**
  * @api
- * @template-covariant T of object = object
+ * @template T of object = object
  * @implements Type<T>
  * @codeCoverageIgnore
  */
diff --git a/src/Type/StringValueT.php b/src/Type/StringValueT.php
@@ -12,7 +12,7 @@
 
 /**
  * @api
- * @template-covariant T of string = string
+ * @template T of string = string
  * @implements Type<T>
  * @codeCoverageIgnore
  */
diff --git a/src/Type/UnionT.php b/src/Type/UnionT.php
@@ -12,7 +12,7 @@
 
 /**
  * @api
- * @template-covariant T = mixed
+ * @template T = mixed
  * @implements Type<T>
  * @codeCoverageIgnore
  */
diff --git a/src/Type/Visitor/Reduced.php b/src/Type/Visitor/Reduced.php
@@ -52,7 +52,7 @@ trait Reduced
     public function boolT(BoolT $type): mixed
     {
         /** @var UnionT */
-        static $reduced = new UnionT([FalseT::T, TrueT::T]);
+        static $reduced = new UnionT([FalseT::T, TrueT::T]); // @phpstan-ignore argument.type
 
         return $this->unionT($reduced);
     }
@@ -94,7 +94,7 @@ public function nonPositiveIntT(NonPositiveIntT $type): mixed
     public function nonZeroIntT(NonZeroIntT $type): mixed
     {
         /** @var UnionT */
-        static $reduced = new UnionT([NegativeIntT::T, PositiveIntT::T]);
+        static $reduced = new UnionT([NegativeIntT::T, PositiveIntT::T]); // @phpstan-ignore argument.type
 
         return $this->unionT($reduced);
     }
@@ -172,7 +172,7 @@ public function closureT(ClosureT $type): mixed
     public function arrayKeyT(ArrayKeyT $type): mixed
     {
         /** @var UnionT */
-        static $reduced = new UnionT([IntT::T, StringT::T]);
+        static $reduced = new UnionT([IntT::T, StringT::T]); // @phpstan-ignore argument.type
 
         return $this->unionT($reduced);
     }
@@ -181,7 +181,7 @@ public function arrayKeyT(ArrayKeyT $type): mixed
     public function numericT(NumericT $type): mixed
     {
         /** @var UnionT */
-        static $reduced = new UnionT([IntT::T, FloatT::T, NumericStringT::T]);
+        static $reduced = new UnionT([IntT::T, FloatT::T, NumericStringT::T]); // @phpstan-ignore argument.type
 
         return $this->unionT($reduced);
     }
@@ -190,7 +190,7 @@ public function numericT(NumericT $type): mixed
     public function scalarT(ScalarT $type): mixed
     {
         /** @var UnionT */
-        static $reduced = new UnionT([BoolT::T, IntT::T, FloatT::T, StringT::T]);
+        static $reduced = new UnionT([BoolT::T, IntT::T, FloatT::T, StringT::T]); // @phpstan-ignore argument.type
 
         return $this->unionT($reduced);
     }
@@ -199,7 +199,7 @@ public function scalarT(ScalarT $type): mixed
     public function mixedT(MixedT $type): mixed
     {
         /** @var UnionT */
-        static $reduced = new UnionT([NullT::T, FalseT::T, TrueT::T, IntT::T, FloatT::T, StringT::T, ArrayBareT::T, ObjectT::T, ResourceT::T]);
+        static $reduced = new UnionT([NullT::T, FalseT::T, TrueT::T, IntT::T, FloatT::T, StringT::T, ArrayBareT::T, ObjectT::T, ResourceT::T]); // @phpstan-ignore argument.type
 
         return $this->unionT($reduced);
     }
diff --git a/src/Type/constructors.php b/src/Type/constructors.php
@@ -226,8 +226,7 @@ function arrayT(Type $key = arrayKeyT, Type $value = mixedT): ArrayT
  */
 function nonEmptyArrayT(Type $key = arrayKeyT, Type $value = mixedT): ArrayT
 {
-    /** @var ArrayT<K, V>&Type<non-empty-array<K, V>> */
-    return new ArrayT($key, $value, isNonEmpty: true);
+    return new ArrayT($key, $value, isNonEmpty: true); // @phpstan-ignore return.type
 }
 
 /**
@@ -403,24 +402,35 @@ function classConstantMaskT(string $class, string|Mask $mask): ClassConstantMask
 /**
  * @api
  * @no-named-arguments
- * @param Type|non-empty-list<Type> $types
+ * @template T1
+ * @template T2
+ * @param Type<T1>|non-empty-list<Type<T1>> $type
+ * @param Type<T2> ...$types
+ * @return IntersectionT<T1&T2>
  */
-function intersectionT(Type|array $types, Type ...$moreTypes): IntersectionT
+function intersectionT(Type|array $type, Type ...$types): IntersectionT
 {
-    return new IntersectionT([...(\is_array($types) ? $types : [$types]), ...$moreTypes]);
+    return new IntersectionT([ // @phpstan-ignore return.type
+        ...(\is_array($type) ? $type : [$type]),
+        ...$types,
+    ]);
 }
 
 /**
  * @api
  * @no-named-arguments
- * @template T
- * @param Type<T>|non-empty-list<Type<T>> $types
- * @param Type<T> ...$moreTypes
- * @return UnionT<T>
+ * @template T1
+ * @template T2
+ * @param Type<T1>|non-empty-list<Type<T1>> $type
+ * @param Type<T2> ...$types
+ * @return UnionT<T1|T2>
  */
-function unionT(Type|array $types, Type ...$moreTypes): UnionT
+function unionT(Type|array $type, Type ...$types): UnionT
 {
-    return new UnionT([...(\is_array($types) ? $types : [$types]), ...$moreTypes]);
+    return new UnionT([ // @phpstan-ignore argument.type
+        ...(\is_array($type) ? $type : [$type]),
+        ...$types,
+    ]);
 }
 
 /**
@@ -431,7 +441,7 @@ function unionT(Type|array $types, Type ...$moreTypes): UnionT
  */
 function nullOrT(Type $type): UnionT
 {
-    return new UnionT([nullT, $type]);
+    return unionT(nullT, $type);
 }
 
 const mixedT = MixedT::T;
diff --git a/tests/Type/StringifyTest.php b/tests/Type/StringifyTest.php
@@ -50,7 +50,7 @@ public static function provideCases(): iterable
         yield [intRangeT(max: 23), 'int<min, 23>'];
         yield [intRangeT(min: -100, max: 234), 'int<-100, 234>'];
         yield [intMaskT(intT(1), intT(2), intT(4)), 'int-mask-of<1|2|4>'];
-        yield [intMaskT(unionT(intT(1), intT(2), intT(4))), 'int-mask-of<1|2|4>'];
+        yield [intMaskT(unionT(intT(1), intT(2), intT(4))), 'int-mask-of<1|2|4>']; // @phpstan-ignore argument.type, argument.type
         yield [intMaskT(constantMaskT('JSON_*')), 'int-mask-of<const<JSON_*>>'];
         yield [floatT, 'float'];
         yield [floatT(0), '0.0'];
@@ -142,10 +142,10 @@ public static function provideCases(): iterable
         yield [objectT(\ArrayObject::class, [arrayKeyT, stringT]), 'ArrayObject<array-key, string>'];
         yield [unionT(intT, stringT), 'int|string'];
         yield [unionT(intT, unionT(stringT, floatT)), 'int|(string|float)'];
-        yield [unionT(intT, intersectionT(stringT, floatT)), 'int|(string&float)'];
+        yield [unionT(intT, intersectionT(stringT, scalarT)), 'int|(string&scalar)'];
         yield [nullOrT(stringT), 'null|string'];
-        yield [intersectionT(intT, stringT), 'int&string'];
-        yield [intersectionT(intT, unionT(stringT, floatT)), 'int&(string|float)'];
+        yield [intersectionT(intT, scalarT), 'int&scalar'];
+        yield [intersectionT(scalarT, unionT(stringT, floatT)), 'scalar&(string|float)'];
         yield [iterableT, 'iterable'];
         yield [iterableT(), 'iterable<mixed>'];
         yield [iterableT(value: stringT), 'iterable<string>'];

Original file line number	Diff line number	Diff line change
`@@ -20,7 +20,7 @@ public function __construct(`
`20`	`20`	`public function declaration(): string`
`21`	`21`	`{`
`22`	`22`	`return \sprintf(`
`23`		`- '@template-covariant %s%s%s',`
	`23`	`+ '@template %s%s%s',`
`24`	`24`	`$this->name,`
`25`	`25`	`$this->of === null ? '' : ' of ' . $this->of,`
`26`	`26`	`$this->default === null ? '' : ' = ' . $this->default,`
Original file line number	Diff line number	Diff line change
`@@ -8,7 +8,7 @@`
`8`	`8`
`9`	`9`	`/**`
`10`	`10`	`* @api`
`11`		`- * @template-covariant T = mixed`
	`11`	`+ * @template T = mixed`
`12`	`12`	`*/`
`13`	`13`	`interface Type`
`14`	`14`	`{`