Add template annotations to async and await

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

Author: WyriHaximus

.github/workflows/ci.yml

@@ -20,3 +20,16 @@ jobs:
           coverage: xdebug
       - run: composer install
       - run: vendor/bin/phpunit --coverage-text
+
+  static-analysis:
+    name: PHPStan
+    runs-on: ubuntu-20.04
+    continue-on-error: true
+    steps:
+      - uses: actions/checkout@v3
+      - uses: shivammathur/setup-php@v2
+        with:
+          php-version: 8.1
+      - run: composer require phpstan/phpstan
+      - name: Execute type checking
+        run: vendor/bin/phpstan --configuration="phpstan.types.neon.dist"

phpstan.types.neon.dist

@@ -0,0 +1,4 @@
+parameters:
+  paths:
+    - types
+  level: max

src/functions.php

@@ -174,9 +174,9 @@
  * $promise->cancel();
  * await($promise);
  * ```
- *
- * @param callable(mixed ...$args):mixed $function
- * @return callable(): PromiseInterface<mixed>
+ * @template T
+ * @param callable(): T $function
+ * @return callable(): PromiseInterface<T>
  * @since 4.0.0
  * @see coroutine()
  */
@@ -266,8 +266,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)

types/await.php

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