Improve type definitions and update to PHPStan level max

Author: clue

README.md

@@ -426,7 +426,7 @@ To run the test suite, go to the project root and run:
 vendor/bin/phpunit
 ```
 
-On top of this, we use PHPStan on level 3 to ensure type safety across the project:
+On top of this, we use PHPStan on max level to ensure type safety across the project:
 
 ```bash
 vendor/bin/phpstan

phpstan.neon.dist

@@ -1,5 +1,5 @@
 parameters:
-    level: 3
+    level: max
 
     paths:
         - src/

src/functions.php

@@ -56,6 +56,8 @@ function await(PromiseInterface $promise)
     $resolved = null;
     $exception = null;
     $rejected = false;
+
+    /** @var bool $loopStarted */
     $loopStarted = false;
 
     $promise->then(
@@ -294,7 +296,7 @@ function delay(float $seconds): void
  * });
  * ```
  *
- * @param callable(mixed ...$args):\Generator<mixed,PromiseInterface,mixed,mixed> $function
+ * @param callable(mixed ...$args):(\Generator<mixed,PromiseInterface,mixed,mixed>|mixed) $function
  * @param mixed ...$args Optional list of additional arguments that will be passed to the given `$function` as is
  * @return PromiseInterface<mixed>
  * @since 3.0.0
@@ -313,6 +315,7 @@ function coroutine(callable $function, ...$args): PromiseInterface
 
     $promise = null;
     $deferred = new Deferred(function () use (&$promise) {
+        /** @var ?PromiseInterface $promise */
         if ($promise instanceof PromiseInterface && \method_exists($promise, 'cancel')) {
             $promise->cancel();
         }
@@ -333,6 +336,7 @@ function coroutine(callable $function, ...$args): PromiseInterface
             return;
         }
 
+        /** @var mixed $promise */
         $promise = $generator->current();
         if (!$promise instanceof PromiseInterface) {
             $next = null;
@@ -342,6 +346,7 @@ function coroutine(callable $function, ...$args): PromiseInterface
             return;
         }
 
+        assert($next instanceof \Closure);
         $promise->then(function ($value) use ($generator, $next) {
             $generator->send($value);
             $next();
@@ -364,6 +369,7 @@ function coroutine(callable $function, ...$args): PromiseInterface
  */
 function parallel(iterable $tasks): PromiseInterface
 {
+    /** @var array<int,PromiseInterface> $pending */
     $pending = [];
     $deferred = new Deferred(function () use (&$pending) {
         foreach ($pending as $promise) {
@@ -425,6 +431,7 @@ function series(iterable $tasks): PromiseInterface
 {
     $pending = null;
     $deferred = new Deferred(function () use (&$pending) {
+        /** @var ?PromiseInterface $pending */
         if ($pending instanceof PromiseInterface && \method_exists($pending, 'cancel')) {
             $pending->cancel();
         }
@@ -439,7 +446,7 @@ function series(iterable $tasks): PromiseInterface
 
     $taskCallback = function ($result) use (&$results, &$next) {
         $results[] = $result;
-        assert($next instanceof \Closure);
+        /** @var \Closure $next */
         $next();
     };
 
@@ -453,9 +460,11 @@ function series(iterable $tasks): PromiseInterface
             $task = $tasks->current();
             $tasks->next();
         } else {
+            assert(\is_array($tasks));
             $task = \array_shift($tasks);
         }
 
+        assert(\is_callable($task));
         $promise = \call_user_func($task);
         assert($promise instanceof PromiseInterface);
         $pending = $promise;
@@ -469,13 +478,14 @@ function series(iterable $tasks): PromiseInterface
 }
 
 /**
- * @param iterable<callable(mixed=):PromiseInterface<mixed>> $tasks
+ * @param iterable<(callable():PromiseInterface<mixed>)|(callable(mixed):PromiseInterface<mixed>)> $tasks
  * @return PromiseInterface<mixed>
  */
 function waterfall(iterable $tasks): PromiseInterface
 {
     $pending = null;
     $deferred = new Deferred(function () use (&$pending) {
+        /** @var ?PromiseInterface $pending */
         if ($pending instanceof PromiseInterface && \method_exists($pending, 'cancel')) {
             $pending->cancel();
         }
@@ -498,9 +508,11 @@ function waterfall(iterable $tasks): PromiseInterface
             $task = $tasks->current();
             $tasks->next();
         } else {
+            assert(\is_array($tasks));
             $task = \array_shift($tasks);
         }
 
+        assert(\is_callable($task));
         $promise = \call_user_func_array($task, func_get_args());
         assert($promise instanceof PromiseInterface);
         $pending = $promise;

tests/AwaitTest.php

@@ -8,7 +8,7 @@
 
 class AwaitTest extends TestCase
 {
-    public function testAwaitThrowsExceptionWhenPromiseIsRejectedWithException()
+    public function testAwaitThrowsExceptionWhenPromiseIsRejectedWithException(): void
     {
         $promise = new Promise(function () {
             throw new \Exception('test');
@@ -19,7 +19,7 @@ public function testAwaitThrowsExceptionWhenPromiseIsRejectedWithException()
         React\Async\await($promise);
     }
 
-    public function testAwaitThrowsUnexpectedValueExceptionWhenPromiseIsRejectedWithFalse()
+    public function testAwaitThrowsUnexpectedValueExceptionWhenPromiseIsRejectedWithFalse(): void
     {
         if (!interface_exists('React\Promise\CancellablePromiseInterface')) {
             $this->markTestSkipped('Promises must be rejected with a \Throwable instance since Promise v3');
@@ -34,7 +34,7 @@ public function testAwaitThrowsUnexpectedValueExceptionWhenPromiseIsRejectedWith
         React\Async\await($promise);
     }
 
-    public function testAwaitThrowsUnexpectedValueExceptionWhenPromiseIsRejectedWithNull()
+    public function testAwaitThrowsUnexpectedValueExceptionWhenPromiseIsRejectedWithNull(): void
     {
         if (!interface_exists('React\Promise\CancellablePromiseInterface')) {
             $this->markTestSkipped('Promises must be rejected with a \Throwable instance since Promise v3');
@@ -49,7 +49,7 @@ public function testAwaitThrowsUnexpectedValueExceptionWhenPromiseIsRejectedWith
         React\Async\await($promise);
     }
 
-    public function testAwaitThrowsErrorWhenPromiseIsRejectedWithError()
+    public function testAwaitThrowsErrorWhenPromiseIsRejectedWithError(): void
     {
         $promise = new Promise(function ($_, $reject) {
             throw new \Error('Test', 42);
@@ -61,7 +61,7 @@ public function testAwaitThrowsErrorWhenPromiseIsRejectedWithError()
         React\Async\await($promise);
     }
 
-    public function testAwaitReturnsValueWhenPromiseIsFullfilled()
+    public function testAwaitReturnsValueWhenPromiseIsFullfilled(): void
     {
         $promise = new Promise(function ($resolve) {
             $resolve(42);
@@ -70,7 +70,7 @@ public function testAwaitReturnsValueWhenPromiseIsFullfilled()
         $this->assertEquals(42, React\Async\await($promise));
     }
 
-    public function testAwaitReturnsValueWhenPromiseIsFulfilledEvenWhenOtherTimerStopsLoop()
+    public function testAwaitReturnsValueWhenPromiseIsFulfilledEvenWhenOtherTimerStopsLoop(): void
     {
         $promise = new Promise(function ($resolve) {
             Loop::addTimer(0.02, function () use ($resolve) {
@@ -84,7 +84,7 @@ public function testAwaitReturnsValueWhenPromiseIsFulfilledEvenWhenOtherTimerSto
         $this->assertEquals(2, React\Async\await($promise));
     }
 
-    public function testAwaitWithAlreadyFulfilledPromiseWillReturnWithoutRunningLoop()
+    public function testAwaitWithAlreadyFulfilledPromiseWillReturnWithoutRunningLoop(): void
     {
         $now = true;
 
@@ -100,7 +100,7 @@ public function testAwaitWithAlreadyFulfilledPromiseWillReturnWithoutRunningLoop
         $this->assertTrue($now);
     }
 
-    public function testAwaitWithAlreadyFulfilledPromiseWillReturnWithoutStoppingLoop()
+    public function testAwaitWithAlreadyFulfilledPromiseWillReturnWithoutStoppingLoop(): void
     {
         $ticks = 0;
 
@@ -128,7 +128,7 @@ public function testAwaitWithAlreadyFulfilledPromiseWillReturnWithoutStoppingLoo
         $this->assertEquals(2, $ticks);
     }
 
-    public function testAwaitWithPendingPromiseThatWillResolveWillStopLoopBeforeLastTimerFinishes()
+    public function testAwaitWithPendingPromiseThatWillResolveWillStopLoopBeforeLastTimerFinishes(): void
     {
         $promise = new Promise(function ($resolve) {
             Loop::addTimer(0.02, function () use ($resolve) {
@@ -159,7 +159,7 @@ public function testAwaitWithPendingPromiseThatWillResolveWillStopLoopBeforeLast
         $this->assertEquals(1, $ticks);
     }
 
-    public function testAwaitWithAlreadyRejectedPromiseWillReturnWithoutStoppingLoop()
+    public function testAwaitWithAlreadyRejectedPromiseWillReturnWithoutStoppingLoop(): void
     {
         $ticks = 0;
 
@@ -191,7 +191,7 @@ public function testAwaitWithAlreadyRejectedPromiseWillReturnWithoutStoppingLoop
         $this->assertEquals(2, $ticks);
     }
 
-    public function testAwaitWithPendingPromiseThatWillRejectWillStopLoopBeforeLastTimerFinishes()
+    public function testAwaitWithPendingPromiseThatWillRejectWillStopLoopBeforeLastTimerFinishes(): void
     {
         $promise = new Promise(function ($_, $reject) {
             Loop::addTimer(0.02, function () use (&$reject) {
@@ -227,7 +227,7 @@ public function testAwaitWithPendingPromiseThatWillRejectWillStopLoopBeforeLastT
         $this->assertEquals(1, $ticks);
     }
 
-    public function testAwaitShouldNotCreateAnyGarbageReferencesForResolvedPromise()
+    public function testAwaitShouldNotCreateAnyGarbageReferencesForResolvedPromise(): void
     {
         if (class_exists('React\Promise\When')) {
             $this->markTestSkipped('Not supported on legacy Promise v1 API');
@@ -244,7 +244,7 @@ public function testAwaitShouldNotCreateAnyGarbageReferencesForResolvedPromise()
         $this->assertEquals(0, gc_collect_cycles());
     }
 
-    public function testAwaitShouldNotCreateAnyGarbageReferencesForRejectedPromise()
+    public function testAwaitShouldNotCreateAnyGarbageReferencesForRejectedPromise(): void
     {
         if (class_exists('React\Promise\When')) {
             $this->markTestSkipped('Not supported on legacy Promise v1 API');
@@ -265,7 +265,7 @@ public function testAwaitShouldNotCreateAnyGarbageReferencesForRejectedPromise()
         $this->assertEquals(0, gc_collect_cycles());
     }
 
-    public function testAwaitShouldNotCreateAnyGarbageReferencesForPromiseRejectedWithNullValue()
+    public function testAwaitShouldNotCreateAnyGarbageReferencesForPromiseRejectedWithNullValue(): void
     {
         if (!interface_exists('React\Promise\CancellablePromiseInterface')) {
             $this->markTestSkipped('Promises must be rejected with a \Throwable instance since Promise v3');