Merge pull request #627: Add PromiseInterface stub for IDE

Author: roxblnfk

psalm-baseline.xml

@@ -1592,6 +1592,7 @@
       <code><![CDATA[PromiseInterface<bool>]]></code>
       <code><![CDATA[PromiseInterface<int>]]></code>
       <code><![CDATA[PromiseInterface<mixed>]]></code>
+      <code><![CDATA[PromiseInterface<mixed>]]></code>
       <code><![CDATA[PromiseInterface<null>]]></code>
     </TooManyTemplateParams>
   </file>

resources/.phpstorm.meta.php …es/.phpstorm.meta.php/.phpstorm.meta.phpresources/.phpstorm.meta.php renamed to resources/.phpstorm.meta.php/.phpstorm.meta.php resources/.phpstorm.meta.php renamed to resources/.phpstorm.meta.php/.phpstorm.meta.php

@@ -0,0 +1,50 @@
+<?php
+
+declare(strict_types=1);
+
+namespace React\Promise;
+
+/**
+ * @note This is a stub interface for better IDE support.
+ *
+ * @yield T
+ * @template-covariant T
+ */
+interface PromiseInterface
+{
+    /**
+     * Transforms a promise's value by applying a function to the promise's fulfillment
+     * or rejection value. Returns a new promise for the transformed result.
+     *
+     * The `then()` method registers new fulfilled and rejection handlers with a promise
+     * (all parameters are optional):
+     *
+     *  * `$onFulfilled` will be invoked once the promise is fulfilled and passed
+     *     the result as the first argument.
+     *  * `$onRejected` will be invoked once the promise is rejected and passed the
+     *     reason as the first argument.
+     *  * `$onProgress` (deprecated) will be invoked whenever the producer of the promise
+     *     triggers progress notifications and passed a single argument (whatever it
+     *     wants) to indicate progress.
+     *
+     * It returns a new promise that will fulfill with the return value of either
+     * `$onFulfilled` or `$onRejected`, whichever is called, or will reject with
+     * the thrown exception if either throws.
+     *
+     * A promise makes the following guarantees about handlers registered in
+     * the same call to `then()`:
+     *
+     *  1. Only one of `$onFulfilled` or `$onRejected` will be called,
+     *      never both.
+     *  2. `$onFulfilled` and `$onRejected` will never be called more
+     *      than once.
+     *  3. `$onProgress` (deprecated) may be called multiple times.
+     *
+     * @template TFulfilled
+     * @template TRejected
+     * @param ?(callable((T is void ? null : T)): (PromiseInterface<TFulfilled>|TFulfilled)) $onFulfilled
+     * @param ?(callable(\Throwable): (PromiseInterface<TRejected>|TRejected)) $onRejected
+     * @return PromiseInterface<($onRejected is null ? ($onFulfilled is null ? T : TFulfilled) : ($onFulfilled is null ? T|TRejected : TFulfilled|TRejected))>
+     */
+    public function then(?callable $onFulfilled = null, ?callable $onRejected = null, ?callable $onProgress = null);
+}

resources/.phpstorm.meta.php/PromiseInterface.php

@@ -183,13 +183,9 @@ public function getLastCompletionResultValues(): ?ValuesInterface
         return $this->lastCompletionResult;
     }
 
-    public function getLastCompletionResult($type = null)
+    public function getLastCompletionResult(mixed $type = null): mixed
     {
-        if ($this->lastCompletionResult === null) {
-            return null;
-        }
-
-        return $this->lastCompletionResult->getValue(0, $type);
+        return $this->lastCompletionResult?->getValue(0, $type);
     }
 
     public function getClient(): ClientInterface

src/Internal/Workflow/WorkflowContext.php

@@ -183,6 +183,10 @@ public static function getInput(): ValuesInterface
      * You can see more information about the capabilities of the child
      * asynchronous task in {@see CancellationScopeInterface} interface.
      *
+     * @template TReturn
+     * @param callable(): (TReturn|\Generator<mixed, mixed, mixed, TReturn>) $task
+     * @return CancellationScopeInterface<TReturn>
+     *
      * @throws OutOfContextException in the absence of the workflow execution context.
      */
     public static function async(callable $task): CancellationScopeInterface
@@ -231,6 +235,10 @@ public static function async(callable $task): CancellationScopeInterface
      *
      * Use asyncDetached to handle cleanup and compensation logic.
      *
+     * @template TReturn
+     * @param callable(): (TReturn|\Generator<mixed, mixed, mixed, TReturn>) $task
+     * @return CancellationScopeInterface<TReturn>
+     *
      * @throws OutOfContextException in the absence of the workflow execution context.
      */
     public static function asyncDetached(callable $task): CancellationScopeInterface
@@ -315,10 +323,9 @@ public static function awaitWithTimeout($interval, callable|Mutex|PromiseInterfa
      * Returns value of last completion result, if any.
      *
      * @param Type|TypeEnum|mixed $type
-     * @return mixed
      * @throws OutOfContextException in the absence of the workflow execution context.
      */
-    public static function getLastCompletionResult($type = null)
+    public static function getLastCompletionResult($type = null): mixed
     {
         return self::getCurrentContext()->getLastCompletionResult($type);
     }
@@ -685,7 +692,10 @@ public static function newContinueAsNewStub(string $class, ?ContinueAsNewOptions
      *  }
      * ```
      *
+     * @param non-empty-string $type
+     * @param list<mixed> $args
      * @param Type|string|\ReflectionType|\ReflectionClass|null $returnType
+     * @return PromiseInterface<mixed>
      *
      * @throws OutOfContextException in the absence of the workflow execution context.
      */
@@ -879,6 +889,7 @@ public static function newUntypedExternalWorkflowStub(WorkflowExecution $executi
      *  }
      * ```
      *
+     * @param non-empty-string $type
      * @param ActivityOptions|null $options
      * @return PromiseInterface<mixed>
      * @throws OutOfContextException in the absence of the workflow execution context.

src/Workflow.php

@@ -14,7 +14,7 @@
 use React\Promise\PromiseInterface;
 
 /**
- * @template T
+ * @template-covariant T
  * @yield T
  * @extends PromiseInterface<T>
  */

src/Workflow/CancellationScopeInterface.php

@@ -21,6 +21,10 @@ interface ScopedContextInterface extends WorkflowContextInterface
     /**
      * The method calls an asynchronous task and returns a promise.
      *
+     * @template TReturn
+     * @param callable(): (TReturn|\Generator<mixed, mixed, mixed, TReturn>) $handler
+     * @return CancellationScopeInterface<TReturn>
+     *
      * @see Workflow::async()
      */
     public function async(callable $handler): CancellationScopeInterface;
@@ -29,6 +33,10 @@ public function async(callable $handler): CancellationScopeInterface;
      * Cancellation scope which does not react to parent cancel and completes
      * in background.
      *
+     * @template TReturn
+     * @param callable(): (TReturn|\Generator<mixed, mixed, mixed, TReturn>) $handler
+     * @return CancellationScopeInterface<TReturn>
+     *
      * @see Workflow::asyncDetached()
      */
     public function asyncDetached(callable $handler): CancellationScopeInterface;

src/Workflow/ScopedContextInterface.php

@@ -49,9 +49,8 @@ public function getInput(): ValuesInterface;
      * @see Workflow::getLastCompletionResult()
      *
      * @param Type|string|null $type
-     * @return mixed
      */
-    public function getLastCompletionResult($type = null);
+    public function getLastCompletionResult(mixed $type = null): mixed;
 
     /**
      * A method that allows you to dynamically register additional query

src/Workflow/WorkflowContextInterface.php

@@ -44,7 +44,7 @@ public function handle()
         $version = yield Workflow::getVersion('test', Workflow::DEFAULT_VERSION, 2);
 
         if ($version === 1) {
-            yield Workflow::sideEffect(static fn() => 'test');
+            yield Workflow::sideEffect(static fn(): string => 'test');
             return 'v1';
         }
 

tests/Acceptance/Extra/Versioning/VersioningTest.php

@@ -12,7 +12,6 @@
 namespace Temporal\Tests\Workflow;
 
 use Temporal\Activity\ActivityOptions;
-use Temporal\Common\Uuid;
 use Temporal\Workflow;
 use Temporal\Workflow\WorkflowMethod;
 use Temporal\Tests\Activity\SimpleActivity;
@@ -25,13 +24,13 @@ public function handler(string $input): iterable
     {
         $simple = Workflow::newActivityStub(
             SimpleActivity::class,
-            ActivityOptions::new()->withStartToCloseTimeout(5)
+            ActivityOptions::new()->withStartToCloseTimeout(5),
         );
 
         $result = yield Workflow::sideEffect(
-            function () use ($input) {
+            static function () use ($input): string {
                 return $input . '-42';
-            }
+            },
         );
 
         return yield $simple->lower($result);