Add template annotations

These annotations will aid static analyses like PHPStan and Psalm to enhance type-safety for this project and projects depending on it

These changes make the following example understandable by PHPStan:

```yaml
final readonly class User
{
    public function __construct(
        public string $name,
    )
}

/**
 * \React\Promise\PromiseInterface<User>
 */
function getCurrentUserFromDatabase(): \React\Promise\PromiseInterface
{
    // The following line would do the database query and fetch the result from it
    // but keeping it simple for the sake of the example.
    return \React\Promise\resolve(new User('WyriHaximus'));
}

// For the sake of this example we're going to assume the following code runs
// in \React\Async\async call
echo await(getCurrentUserFromDatabase())->name; // This echos: WyriHaximus
```

Author: WyriHaximus

README.md

@@ -226,7 +226,7 @@ await($promise);
 
 ### await()
 
-The `await(PromiseInterface $promise): mixed` function can be used to
+The `await(PromiseInterface<T> $promise): mixed` function can be used to
 block waiting for the given `$promise` to be fulfilled.
 
 ```php
@@ -278,7 +278,7 @@ try {
 
 ### coroutine()
 
-The `coroutine(callable $function, mixed ...$args): PromiseInterface<mixed>` function can be used to
+The `coroutine(callable $function, mixed ...$args): PromiseInterface<T>` function can be used to
 execute a Generator-based coroutine to "await" promises.
 
 ```php
@@ -498,7 +498,7 @@ Loop::addTimer(2.0, function () use ($promise): void {
 
 ### parallel()
 
-The `parallel(iterable<callable():PromiseInterface<mixed>> $tasks): PromiseInterface<array<mixed>>` function can be used
+The `parallel(iterable<callable():PromiseInterface<T>> $tasks): PromiseInterface<array<T>>` function can be used
 like this:
 
 ```php
@@ -540,7 +540,7 @@ React\Async\parallel([
 
 ### series()
 
-The `series(iterable<callable():PromiseInterface<mixed>> $tasks): PromiseInterface<array<mixed>>` function can be used
+The `series(iterable<callable():PromiseInterface<T>> $tasks): PromiseInterface<array<T>>` function can be used
 like this:
 
 ```php
@@ -582,7 +582,7 @@ React\Async\series([
 
 ### waterfall()
 
-The `waterfall(iterable<callable(mixed=):PromiseInterface<mixed>> $tasks): PromiseInterface<mixed>` function can be used
+The `waterfall(iterable<callable(mixed=):PromiseInterface<T>> $tasks): PromiseInterface<T>` function can be used
 like this:
 
 ```php

src/FiberMap.php

@@ -6,13 +6,15 @@
 
 /**
  * @internal
+ *
+ * @template T
  */
 final class FiberMap
 {
     /** @var array<int,bool> */
     private static array $status = [];
 
-    /** @var array<int,PromiseInterface> */
+    /** @var array<int,PromiseInterface<T>> */
     private static array $map = [];
 
     /** @param \Fiber<mixed,mixed,mixed,mixed> $fiber */
@@ -27,19 +29,28 @@ public static function cancel(\Fiber $fiber): void
         self::$status[\spl_object_id($fiber)] = true;
     }
 
-    /** @param \Fiber<mixed,mixed,mixed,mixed> $fiber */
+    /**
+     * @param \Fiber<mixed,mixed,mixed,mixed> $fiber
+     * @param PromiseInterface<T> $promise
+     */
     public static function setPromise(\Fiber $fiber, PromiseInterface $promise): void
     {
         self::$map[\spl_object_id($fiber)] = $promise;
     }
 
-    /** @param \Fiber<mixed,mixed,mixed,mixed> $fiber */
+    /**
+     * @param \Fiber<mixed,mixed,mixed,mixed> $fiber
+     * @param PromiseInterface<T> $promise
+     */
     public static function unsetPromise(\Fiber $fiber, PromiseInterface $promise): void
     {
         unset(self::$map[\spl_object_id($fiber)]);
     }
 
-    /** @param \Fiber<mixed,mixed,mixed,mixed> $fiber */
+    /**
+     * @param \Fiber<mixed,mixed,mixed,mixed> $fiber
+     * @return ?PromiseInterface<T>
+     */
     public static function getPromise(\Fiber $fiber): ?PromiseInterface
     {
         return self::$map[\spl_object_id($fiber)] ?? null;

src/functions.php

@@ -176,8 +176,11 @@
  * await($promise);
  * ```
  *
- * @param callable $function
- * @return callable(mixed ...): PromiseInterface<mixed>
+ * @template T
+ * @template TFulfilled as PromiseInterface<T>|T
+ * @template A
+ * @param (callable(): TFulfilled)|(callable(A): TFulfilled) $function
+ * @return callable(mixed ...$args): PromiseInterface<T>
  * @since 4.0.0
  * @see coroutine()
  */
@@ -268,8 +271,9 @@ function async(callable $function): callable
  * }
  * ```
  *
- * @param PromiseInterface $promise
- * @return mixed returns whatever the promise resolves to
+ * @template T
+ * @param PromiseInterface<T> $promise
+ * @return T
  * @throws \Exception when the promise is rejected with an `Exception`
  * @throws \Throwable when the promise is rejected with a `Throwable`
  * @throws \UnexpectedValueException when the promise is rejected with an unexpected value (Promise API v1 or v2 only)
@@ -279,6 +283,10 @@ function await(PromiseInterface $promise): mixed
     $fiber = null;
     $resolved = false;
     $rejected = false;
+
+    /**
+     * @var T $resolvedValue
+     */
     $resolvedValue = null;
     $rejectedThrowable = null;
     $lowLevelFiber = \Fiber::getCurrent();
@@ -292,6 +300,9 @@ function (mixed $value) use (&$resolved, &$resolvedValue, &$fiber, $lowLevelFibe
             /** @var ?\Fiber<mixed,mixed,mixed,mixed> $fiber */
             if ($fiber === null) {
                 $resolved = true;
+                /**
+                 * @var T $resolvedValue
+                 */
                 $resolvedValue = $value;
                 return;
             }
@@ -305,7 +316,7 @@ function (mixed $throwable) use (&$rejected, &$rejectedThrowable, &$fiber, $lowL
 
             if (!$throwable instanceof \Throwable) {
                 $throwable = new \UnexpectedValueException(
-                    'Promise rejected with unexpected value of type ' . (is_object($throwable) ? get_class($throwable) : gettype($throwable))
+                    'Promise rejected with unexpected value of type ' . (is_object($throwable) ? get_class($throwable) : gettype($throwable)) /** @phpstan-ignore-line */
                 );
 
                 // avoid garbage references by replacing all closures in call stack.
@@ -354,7 +365,11 @@ function (mixed $throwable) use (&$rejected, &$rejectedThrowable, &$fiber, $lowL
 
     $fiber = FiberFactory::create();
 
-    return $fiber->suspend();
+    /**
+     * @var T $result
+     */
+    $result = $fiber->suspend();
+    return $result;
 }
 
 /**
@@ -592,9 +607,10 @@ function delay(float $seconds): void
  * });
  * ```
  *
- * @param callable(mixed ...$args):(\Generator<mixed,PromiseInterface,mixed,mixed>|mixed) $function
+ * @template T
+ * @param callable(mixed ...$args):(\Generator<mixed,PromiseInterface<T>,mixed,mixed>|T) $function
  * @param mixed ...$args Optional list of additional arguments that will be passed to the given `$function` as is
- * @return PromiseInterface<mixed>
+ * @return PromiseInterface<T>
  * @since 3.0.0
  */
 function coroutine(callable $function, mixed ...$args): PromiseInterface
@@ -609,9 +625,9 @@ function coroutine(callable $function, mixed ...$args): PromiseInterface
         return resolve($generator);
     }
 
+    /** @var ?PromiseInterface<T> $promise */
     $promise = null;
     $deferred = new Deferred(function () use (&$promise) {
-        /** @var ?PromiseInterface $promise */
         if ($promise instanceof PromiseInterface && \method_exists($promise, 'cancel')) {
             $promise->cancel();
         }
@@ -632,7 +648,7 @@ function coroutine(callable $function, mixed ...$args): PromiseInterface
             return;
         }
 
-        /** @var mixed $promise */
+        /** @var mixed|PromiseInterface<T> $promise */
         $promise = $generator->current();
         if (!$promise instanceof PromiseInterface) {
             $next = null;
@@ -660,12 +676,13 @@ function coroutine(callable $function, mixed ...$args): PromiseInterface
 }
 
 /**
- * @param iterable<callable():PromiseInterface<mixed>> $tasks
- * @return PromiseInterface<array<mixed>>
+ * @template T
+ * @param iterable<callable():PromiseInterface<T>> $tasks
+ * @return PromiseInterface<array<T>>
  */
 function parallel(iterable $tasks): PromiseInterface
 {
-    /** @var array<int,PromiseInterface> $pending */
+    /** @var array<int,PromiseInterface<T>> $pending */
     $pending = [];
     $deferred = new Deferred(function () use (&$pending) {
         foreach ($pending as $promise) {
@@ -720,14 +737,15 @@ function parallel(iterable $tasks): PromiseInterface
 }
 
 /**
- * @param iterable<callable():PromiseInterface<mixed>> $tasks
- * @return PromiseInterface<array<mixed>>
+ * @template T
+ * @param iterable<callable():PromiseInterface<T>> $tasks
+ * @return PromiseInterface<array<T>>
  */
 function series(iterable $tasks): PromiseInterface
 {
     $pending = null;
     $deferred = new Deferred(function () use (&$pending) {
-        /** @var ?PromiseInterface $pending */
+        /** @var ?PromiseInterface<T> $pending */
         if ($pending instanceof PromiseInterface && \method_exists($pending, 'cancel')) {
             $pending->cancel();
         }
@@ -774,14 +792,15 @@ function series(iterable $tasks): PromiseInterface
 }
 
 /**
- * @param iterable<(callable():PromiseInterface<mixed>)|(callable(mixed):PromiseInterface<mixed>)> $tasks
- * @return PromiseInterface<mixed>
+ * @template T
+ * @param iterable<(callable():PromiseInterface<T>)|(callable(mixed):PromiseInterface<T>)> $tasks
+ * @return PromiseInterface<T>
  */
 function waterfall(iterable $tasks): PromiseInterface
 {
     $pending = null;
     $deferred = new Deferred(function () use (&$pending) {
-        /** @var ?PromiseInterface $pending */
+        /** @var ?PromiseInterface<T> $pending */
         if ($pending instanceof PromiseInterface && \method_exists($pending, 'cancel')) {
             $pending->cancel();
         }

tests/AwaitTest.php

@@ -413,7 +413,7 @@ public function testRejectedPromisesShouldBeDetached(callable $await): void
         })());
     }
 
-    /** @return iterable<string,list<callable(PromiseInterface): mixed>> */
+    /** @return iterable<string,list<callable(PromiseInterface<mixed>): mixed>> */
     public function provideAwaiters(): iterable
     {
         yield 'await' => [static fn (React\Promise\PromiseInterface $promise): mixed => React\Async\await($promise)];

tests/ParallelTest.php

@@ -12,6 +12,9 @@ class ParallelTest extends TestCase
 {
     public function testParallelWithoutTasks(): void
     {
+        /**
+         * @var array<callable(): React\Promise\PromiseInterface<mixed>> $tasks
+         */
         $tasks = array();
 
         $promise = React\Async\parallel($tasks);

tests/SeriesTest.php

@@ -12,6 +12,9 @@ class SeriesTest extends TestCase
 {
     public function testSeriesWithoutTasks(): void
     {
+        /**
+         * @var array<callable(): React\Promise\PromiseInterface<mixed>> $tasks
+         */
         $tasks = array();
 
         $promise = React\Async\series($tasks);
@@ -151,6 +154,9 @@ public function testSeriesWithErrorFromInfiniteIteratorAggregateReturnsPromiseRe
         $tasks = new class() implements \IteratorAggregate {
             public int $called = 0;
 
+            /**
+             * @return \Iterator<callable(): React\Promise\PromiseInterface<mixed>>
+             */
             public function getIterator(): \Iterator
             {
                 while (true) { // @phpstan-ignore-line

tests/WaterfallTest.php

@@ -12,6 +12,9 @@ class WaterfallTest extends TestCase
 {
     public function testWaterfallWithoutTasks(): void
     {
+        /**
+         * @var array<callable(): React\Promise\PromiseInterface<mixed>> $tasks
+         */
         $tasks = array();
 
         $promise = React\Async\waterfall($tasks);
@@ -165,6 +168,9 @@ public function testWaterfallWithErrorFromInfiniteIteratorAggregateReturnsPromis
         $tasks = new class() implements \IteratorAggregate {
             public int $called = 0;
 
+            /**
+             * @return \Iterator<callable(): React\Promise\PromiseInterface<mixed>>
+             */
             public function getIterator(): \Iterator
             {
                 while (true) { // @phpstan-ignore-line

tests/types/async.php

@@ -0,0 +1,10 @@
+<?php
+
+use React\Promise\PromiseInterface;
+use function PHPStan\Testing\assertType;
+use function React\Async\async;
+use function React\Async\await;
+use function React\Promise\resolve;
+
+assertType('React\Promise\PromiseInterface<bool>', async(static fn (): PromiseInterface => resolve(true))());
+assertType('React\Promise\PromiseInterface<bool>', async(static fn (): bool => await(resolve(true)))());

tests/types/await.php

@@ -0,0 +1,50 @@
+<?php
+
+use React\Promise\PromiseInterface;
+use function PHPStan\Testing\assertType;
+use function React\Async\async;
+use function React\Async\await;
+use function React\Async\coroutine;
+use function React\Async\parallel;
+use function React\Async\series;
+use function React\Async\waterfall;
+use function React\Promise\resolve;
+
+assertType('bool', await(resolve(true)));
+assertType('bool', await(async(static fn (): bool => true)()));
+assertType('bool', await(async(static fn (): PromiseInterface => resolve(true))()));
+assertType('bool', await(async(static fn (): bool => await(resolve(true)))()));
+assertType('bool', await(coroutine(static function () {
+    return (yield resolve(true));
+})));
+assertType('array<bool|float|int>', await(parallel([
+    static fn (): PromiseInterface => resolve(true),
+    static fn (): PromiseInterface => resolve(time()),
+    static fn (): PromiseInterface => resolve(microtime(true)),
+])));
+assertType('array<bool|float|int>', await(series([
+    static fn (): PromiseInterface => resolve(true),
+    static fn (): PromiseInterface => resolve(time()),
+    static fn (): PromiseInterface => resolve(microtime(true)),
+])));
+assertType('float', await(waterfall([
+    static fn (): PromiseInterface => resolve(microtime(true)),
+])));
+
+// Desired, but currently unsupported with the current set of templates
+//assertType('float', await(waterfall([
+//    static fn (): PromiseInterface => resolve(true),
+//    static fn (bool $bool): PromiseInterface => resolve(time()),
+//    static fn (int $int): PromiseInterface => resolve(microtime(true)),
+//])));
+
+final class AwaitExampleUser
+{
+    public string $name;
+
+    public function __construct(string $name) {
+        $this->name = $name;
+    }
+}
+
+assertType('string', await(resolve(new AwaitExampleUser('WyriHaximus')))->name);