Looking for help with type safety for react/promise and react/async

[WyriHaximus]

For react/promise and react/async (specifically the await function in that package) we, the ReactPHP team (@jsor, @cboden, @clue, @SimonFrings, and I) are looking for help making sure our promises are type safe in both Psalm's and PHPStan's eyes.

Additionally, I'm looking for the same kind of help with wyrihaximus/react-awaitable-observable that builds on reactivex/rxphp (maintained @davidwdan and @mbonneau). (P.S. I haven't discussed this yet with @davidwdan and @mbonneau for rxphp, but I wanted to know what to propose to that package.) That is very simmular, aside from the fact that it is an itertable instead of a single value (or exception). But lets start with promises.

On react/promise this PR reactphp/promise#188 by @simPod was created to add templates for it's type safety. Now we're very happy with that, as this recently came up again while discussing react/promise v3 and fibers through react/async's await function. Giving our personal experience with type safety via PHPStan and Psalm we're looking for your help making sure we get the best possible set up for it.

To give a few examples, this is what we're aiming to achieve. Let's assume we have this, very basic function that returns a promise that resolves to a string:

use function React\Promise\resolve;

/**
 * @return PromiseInterface<string>
 */
function a(): PromiseInterface {
    return resolve('string');
}

Now if we call that function, we're aiming for PHPStorm, Psalm, and PHPStan to understand that this is what we expect:

a()->then(function (string $a) {});

And this is not what we expect:

a()->then(function (bool $a) {});

Now on top of that, we aim for the await function to achieve this:

use function React\Async\await;

$a = await(a()); // Both PHPStan and Psalm should understand that $a will be a string

Then there is the async function we should also cover as that takes an sync running bit of code, and runs it in a fiber, and as such will return a promise with the result:

use function React\Async\async;
use function React\Async\await;

async(function (): string {
    $a = await(a()); // Both PHPStan and Psalm should understand that $a will be a string

    return strrev($a);
})->then(function (string $a) {});

This is it with regards to what we're looking for ReactPHP. Personally I'm also looking to achieve the same with observables, with TL;DR are instead of a single value coming from a promise, are stream of values, that just like a promise might take an arbritairy amount of time before the next item in the stream comes in. If observables doesn't ring a bell, reactive or rxjs instead might.

So for Observables I'm looking to achieve exactly the same thing:

/**
 * @return Observable<int>
 */
function b(): Observable {
    return Observable::fromArray(range(0, 1337), new ImmediateScheduler());
}

async(function () {
    foreach (awaitObservable(b()) as $integer) {
        echo $integer; // Psalm, PHPStorm, and PHPStan should understand $integer is an int
    }
});

How do we achieve this?

[orklah]

I drafted a little something just to show you the basic idea: https://psalm.dev/r/bae938642c

I did not get to Observable yet.

Can you take a look at it and make me some feedback? I never used Promise so I may have made obvious mistakes here!

EDIT: the same but with user code with it to show inference and error detection: https://psalm.dev/r/eb38080b8d

[weirdan]

ERROR: InvalidArgument - 44:14 - Argument 1 of PromiseInterface::then expects callable(T:fn-await as mixed):PromiseInterface, impure-Closure(mixed):void provided

This is legit - the closure must return PromiseInterface according to your docblocks. And it's the same for other ->then() calls.

Use by reference will be a pain, as there are no guarantees that the used variable won't change its type after closure is created.

[ondrejmirtes]

Whatever example you come up with, please make sure it also works in PHPStan, and report any problems, thanks. You can use \PHPStan\Testing\assertType or \PHPStan\dumpType functions that the types are correctly inferred.

[WyriHaximus]

Whatever example you come up with, please make sure it also works in PHPStan, and report any problems, thanks. You can use \PHPStan\Testing\assertType or \PHPStan\dumpType functions that the types are correctly inferred.

@ondrejmirtes I will 👍 ! Just spend nearly 3 weeks converting one of my projects to user fibers and testing these templates out in a real project with all kinds of edge cases. And so far they have been working great. Still need to test and reassure a few things. But so far it's a lot easier than I was expecting.

ERROR: InvalidArgument - 44:14 - Argument 1 of PromiseInterface::then expects callable(T:fn-await as mixed):PromiseInterface, impure-Closure(mixed):void provided

This is legit - the closure must return PromiseInterface according to your docblocks. And it's the same for other ->then() calls.

Use by reference will be a pain, as there are no guarantees that the used variable won't change its type after closure is created.

@weirdan Yeah about to dive into that. The current WIP we're been linking around in this topic is based on a FulfilledPromise and not the more widely used Promise class. Will try to add that later today because that one communicates through callables the results and might complicate things further.

[WyriHaximus]

Came to this result for now by adding a FullfilledPromise and a more realistic Promise implementation but I honestly doubt that will matter for the template annotations even though there are still a bunch of errors: https://psalm.dev/r/22a9692a97

Tried to get the full promise implementation into a psalm.dev link, but it turns out that exceeds the allowed size: https://gist.github.com/WyriHaximus/0a286e42a7c6e3494d4ffe7922586e05

[orklah]

https://psalm.dev/r/7a5580ae09
You can pretty much ignore other errors. They shouldn't impact users of the library and they're not an issue for your own usage I thing