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

.gitattributes

@@ -1,5 +1,7 @@
 /.gitattributes export-ignore
 /.github/ export-ignore
 /.gitignore export-ignore
+/phpstan.neon.dist export-ignore
 /phpunit.xml.dist export-ignore
 /tests/ export-ignore
+/types/ export-ignore

.github/workflows/ci.yml

@@ -20,3 +20,17 @@ jobs:
           coverage: xdebug
       - run: composer install
       - run: vendor/bin/phpunit --coverage-text
+
+  PHPStan:
+    name: PHPStan
+    runs-on: ubuntu-20.04
+    strategy:
+      matrix:
+        php:
+          - 8.1
+    steps:
+      - uses: actions/checkout@v3
+      - uses: shivammathur/setup-php@v2
+        with:
+          php-version: ${{ matrix.php }}
+      - run: vendor/bin/phpstan

composer.json

@@ -31,7 +31,8 @@
         "react/promise": "^3.0 || ^2.8 || ^1.2.1"
     },
     "require-dev": {
-        "phpunit/phpunit": "^9.3"
+        "phpunit/phpunit": "^9.3",
+        "phpstan/phpstan": "^1.8"
     },
     "autoload": {
         "psr-4": {

phpstan.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(mixed ...$args): 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,7 @@
+<?php
+
+use function PHPStan\Testing\assertType;
+use function React\Async\await;
+use function React\Promise\resolve;
+
+assertType('bool', await(resolve(true)));