[3.x] Add template annotations

WyriHaximus-secret-labs · Jun 25, 2023 · 7390a8c · 7390a8c
1 parent d66fa66
commit 7390a8c
Show file tree

Hide file tree

Showing 9 changed files with 165 additions and 27 deletions.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -35,6 +35,7 @@ jobs:
     name: PHPStan (PHP ${{ matrix.php }})
     runs-on: ubuntu-22.04
     strategy:
+      fail-fast: false
       matrix:
         php:
           - 8.2

diff --git a/phpstan.neon.dist b/phpstan.neon.dist
@@ -1,6 +1,7 @@
 parameters:
     level: max
+    checkGenericClassInNonGenericObjectType: false
 
     paths:
         - src/
-        - tests/
+        - types/
diff --git a/src/Deferred.php b/src/Deferred.php
@@ -2,9 +2,12 @@
 
 namespace React\Promise;
 
+/**
+ * @template-covariant T
+ */
 final class Deferred
 {
-    /** @var Promise */
+    /** @var PromiseInterface<T> */
     private $promise;
 
     /** @var callable */
@@ -21,6 +24,9 @@ public function __construct(callable $canceller = null)
         }, $canceller);
     }
 
+    /**
+     * @return PromiseInterface<T>
+     */
     public function promise(): PromiseInterface
     {
         return $this->promise;

diff --git a/src/Internal/FulfilledPromise.php b/src/Internal/FulfilledPromise.php
@@ -7,14 +7,17 @@
 
 /**
  * @internal
+ *
+ * @template-implements PromiseInterface<T>
+ * @template-covariant T
  */
 final class FulfilledPromise implements PromiseInterface
 {
-    /** @var mixed */
+    /** @var T */
     private $value;
 
     /**
-     * @param mixed $value
+     * @param T $value
      * @throws \InvalidArgumentException
      */
     public function __construct($value = null)
@@ -26,6 +29,9 @@ public function __construct($value = null)
         $this->value = $value;
     }
 
+    /**
+     * @inheritdoc
+     */
     public function then(callable $onFulfilled = null, callable $onRejected = null): PromiseInterface
     {
         if (null === $onFulfilled) {
@@ -39,11 +45,17 @@ public function then(callable $onFulfilled = null, callable $onRejected = null):
         }
     }
 
+    /**
+     * @inheritdoc
+     */
     public function catch(callable $onRejected): PromiseInterface
     {
         return $this;
     }
 
+    /**
+     * @inheritdoc
+     */
     public function finally(callable $onFulfilledOrRejected): PromiseInterface
     {
         return $this->then(function ($value) use ($onFulfilledOrRejected): PromiseInterface {
@@ -60,6 +72,7 @@ public function cancel(): void
     /**
      * @deprecated 3.0.0 Use `catch()` instead
      * @see self::catch()
+     * @inheritdoc
      */
     public function otherwise(callable $onRejected): PromiseInterface
     {
@@ -69,6 +82,7 @@ public function otherwise(callable $onRejected): PromiseInterface
     /**
      * @deprecated 3.0.0 Use `finally()` instead
      * @see self::finally()
+     * @inheritdoc
      */
     public function always(callable $onFulfilledOrRejected): PromiseInterface
     {

diff --git a/src/Internal/RejectedPromise.php b/src/Internal/RejectedPromise.php
@@ -8,6 +8,9 @@
 
 /**
  * @internal
+ *
+ * @template-implements PromiseInterface<T>
+ * @template-covariant T
  */
 final class RejectedPromise implements PromiseInterface
 {
@@ -22,6 +25,9 @@ public function __construct(\Throwable $reason)
         $this->reason = $reason;
     }
 
+    /**
+     * @inheritdoc
+     */
     public function then(callable $onFulfilled = null, callable $onRejected = null): PromiseInterface
     {
         if (null === $onRejected) {
@@ -35,6 +41,9 @@ public function then(callable $onFulfilled = null, callable $onRejected = null):
         }
     }
 
+    /**
+     * @inheritdoc
+     */
     public function catch(callable $onRejected): PromiseInterface
     {
         if (!_checkTypehint($onRejected, $this->reason)) {
@@ -44,6 +53,9 @@ public function catch(callable $onRejected): PromiseInterface
         return $this->then(null, $onRejected);
     }
 
+    /**
+     * @inheritdoc
+     */
     public function finally(callable $onFulfilledOrRejected): PromiseInterface
     {
         return $this->then(null, function (\Throwable $reason) use ($onFulfilledOrRejected): PromiseInterface {
@@ -60,6 +72,7 @@ public function cancel(): void
     /**
      * @deprecated 3.0.0 Use `catch()` instead
      * @see self::catch()
+     * @inheritdoc
      */
     public function otherwise(callable $onRejected): PromiseInterface
     {
@@ -69,6 +82,7 @@ public function otherwise(callable $onRejected): PromiseInterface
     /**
      * @deprecated 3.0.0 Use `always()` instead
      * @see self::always()
+     * @inheritdoc
      */
     public function always(callable $onFulfilledOrRejected): PromiseInterface
     {

diff --git a/src/Promise.php b/src/Promise.php
@@ -4,12 +4,16 @@
 
 use React\Promise\Internal\RejectedPromise;
 
+/**
+ * @template-implements PromiseInterface<T>
+ * @template-covariant T
+ */
 final class Promise implements PromiseInterface
 {
     /** @var ?callable */
     private $canceller;
 
-    /** @var ?PromiseInterface */
+    /** @var PromiseInterface<T> */
     private $result;
 
     /** @var callable[] */
@@ -30,6 +34,9 @@ public function __construct(callable $resolver, callable $canceller = null)
         $this->call($cb);
     }
 
+    /**
+     * @inheritdoc
+     */
     public function then(callable $onFulfilled = null, callable $onRejected = null): PromiseInterface
     {
         if (null !== $this->result) {
@@ -63,6 +70,9 @@ static function () use (&$parent) {
         );
     }
 
+    /**
+     * @inheritdoc
+     */
     public function catch(callable $onRejected): PromiseInterface
     {
         return $this->then(null, static function ($reason) use ($onRejected) {
@@ -74,14 +84,17 @@ public function catch(callable $onRejected): PromiseInterface
         });
     }
 
+    /**
+     * @inheritdoc
+     */
     public function finally(callable $onFulfilledOrRejected): PromiseInterface
     {
         return $this->then(static function ($value) use ($onFulfilledOrRejected) {
-            return resolve($onFulfilledOrRejected())->then(function () use ($value) {
+            return resolve($onFulfilledOrRejected())->then(function ($_) use ($value) {
                 return $value;
             });
         }, static function ($reason) use ($onFulfilledOrRejected) {
-            return resolve($onFulfilledOrRejected())->then(function () use ($reason) {
+            return resolve($onFulfilledOrRejected())->then(function ($_) use ($reason) {
                 return new RejectedPromise($reason);
             });
         });
@@ -125,6 +138,7 @@ public function cancel(): void
     /**
      * @deprecated 3.0.0 Use `catch()` instead
      * @see self::catch()
+     * @inheritdoc
      */
     public function otherwise(callable $onRejected): PromiseInterface
     {
@@ -134,6 +148,7 @@ public function otherwise(callable $onRejected): PromiseInterface
     /**
      * @deprecated 3.0.0 Use `finally()` instead
      * @see self::finally()
+     * @inheritdoc
      */
     public function always(callable $onFulfilledOrRejected): PromiseInterface
     {

diff --git a/src/PromiseInterface.php b/src/PromiseInterface.php
@@ -2,6 +2,9 @@
 
 namespace React\Promise;
 
+/**
+ * @template-covariant T
+ */
 interface PromiseInterface
 {
     /**
@@ -28,9 +31,9 @@ interface PromiseInterface
      *  2. `$onFulfilled` and `$onRejected` will never be called more
      *      than once.
      *
-     * @param callable|null $onFulfilled
-     * @param callable|null $onRejected
-     * @return PromiseInterface
+     * @template TFulfilled as PromiseInterface<T>|T
+     * @param (callable(T): TFulfilled)|null $onFulfilled
+     * @return PromiseInterface<T>
      */
     public function then(?callable $onFulfilled = null, ?callable $onRejected = null): PromiseInterface;
 
@@ -44,8 +47,7 @@ public function then(?callable $onFulfilled = null, ?callable $onRejected = null
      * Additionally, you can type hint the `$reason` argument of `$onRejected` to catch
      * only specific errors.
      *
-     * @param callable $onRejected
-     * @return PromiseInterface
+     * @return PromiseInterface<T>
      */
     public function catch(callable $onRejected): PromiseInterface;
 
@@ -91,8 +93,9 @@ public function catch(callable $onRejected): PromiseInterface;
      *     ->finally('cleanup');
      * ```
      *
-     * @param callable $onFulfilledOrRejected
-     * @return PromiseInterface
+     * @template TReturn of PromiseInterface<T>|T
+     * @param callable(T=): TReturn $onFulfilledOrRejected
+     * @return PromiseInterface<T>
      */
     public function finally(callable $onFulfilledOrRejected): PromiseInterface;
 
@@ -118,7 +121,7 @@ public function cancel(): void;
      * ```
      *
      * @param callable $onRejected
-     * @return PromiseInterface
+     * @return PromiseInterface<T>
      * @deprecated 3.0.0 Use catch() instead
      * @see self::catch()
      */
@@ -135,7 +138,7 @@ public function otherwise(callable $onRejected): PromiseInterface;
      * ```
      *
      * @param callable $onFulfilledOrRejected
-     * @return PromiseInterface
+     * @return PromiseInterface<T>
      * @deprecated 3.0.0 Use finally() instead
      * @see self::finally()
      */

diff --git a/src/functions.php b/src/functions.php
@@ -17,8 +17,9 @@
  *
  * If `$promiseOrValue` is a promise, it will be returned as is.
  *
- * @param mixed $promiseOrValue
- * @return PromiseInterface
+ * @template T
+ * @param PromiseInterface<T>|T $promiseOrValue
+ * @return PromiseInterface<T>
  */
 function resolve($promiseOrValue): PromiseInterface
 {
@@ -30,7 +31,9 @@ function resolve($promiseOrValue): PromiseInterface
         $canceller = null;
 
         if (\method_exists($promiseOrValue, 'cancel')) {
-            $canceller = [$promiseOrValue, 'cancel'];
+            $canceller = static function () use ($promiseOrValue) {
+                $promiseOrValue->cancel();
+            };
         }
 
         return new Promise(function ($resolve, $reject) use ($promiseOrValue): void {
@@ -54,8 +57,7 @@ function resolve($promiseOrValue): PromiseInterface
  * throwing an exception. For example, it allows you to propagate a rejection with
  * the value of another promise.
  *
- * @param \Throwable $reason
- * @return PromiseInterface
+ * @return PromiseInterface<null>
  */
 function reject(\Throwable $reason): PromiseInterface
 {
@@ -68,8 +70,9 @@ function reject(\Throwable $reason): PromiseInterface
  * will be an array containing the resolution values of each of the items in
  * `$promisesOrValues`.
  *
- * @param iterable<mixed> $promisesOrValues
- * @return PromiseInterface
+ * @template T
+ * @param array<PromiseInterface<T>|T> $promisesOrValues
+ * @return PromiseInterface<array<T>>
  */
 function all(iterable $promisesOrValues): PromiseInterface
 {
@@ -119,8 +122,9 @@ function (\Throwable $reason) use (&$continue, $reject): void {
  * The returned promise will become **infinitely pending** if  `$promisesOrValues`
  * contains 0 items.
  *
- * @param iterable<mixed> $promisesOrValues
- * @return PromiseInterface
+ * @template T
+ * @param array<PromiseInterface<T>|T> $promisesOrValues
+ * @return PromiseInterface<T>
  */
 function race(iterable $promisesOrValues): PromiseInterface
 {
@@ -154,8 +158,9 @@ function race(iterable $promisesOrValues): PromiseInterface
  * The returned promise will also reject with a `React\Promise\Exception\LengthException`
  * if `$promisesOrValues` contains 0 items.
  *
- * @param iterable<mixed> $promisesOrValues
- * @return PromiseInterface
+ * @template T
+ * @param array<PromiseInterface<T>|T> $promisesOrValues
+ * @return PromiseInterface<T>
  */
 function any(iterable $promisesOrValues): PromiseInterface
 {