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

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"

composer.json

@@ -28,8 +28,14 @@
     "require": {
         "php": ">=8.1",
         "react/event-loop": "^1.2",
-        "react/promise": "^3.0 || ^2.8 || ^1.2.1"
+        "react/promise": "dev-2.x-add-basic-template-annotations as 2.13.0"
     },
+    "repositories": [
+        {
+            "type": "vcs",
+            "url": "https://github.com/WyriHaximus-secret-labs/promise"
+        }
+    ],
     "require-dev": {
         "phpunit/phpunit": "^9.3"
     },

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)));