[RFC] Change `ResultInterface<T>` to `ResultInterface<T, E>`

[devnix]

I've been chatting with @veewee on Discord about adding a template to ResultInterface to return what kind of error it could contain.

I'm not sure if this could be considered a breaking change, as it only affects static analysis and can be easily ignored, baselined, or fixed in a moment by going to each error and changing every @return ResultInterface<Foo> to @return ResultInterface<Foo, Throwable> if you don't feel like studying the specific throwables you want to return from there.

Another option apart from waiting for a new major version or just letting static analysis break is to wait for some default generic type syntax, see:

• (RFC) Implement template default syntax phpstan/phpdoc-parser#148
• Add support for template default types phpstan/phpstan#4801
• Implement template default types phpstan/phpstan-src#1835

This could allow us to have a syntax that would behave the same way but without having any new errors:

/**
 * @template T
 * @template E of Throwable = Throwable
 */
interface ResultInterface {}

If we are OK with baselining errors (regardless of whether the change is in a minor or major version), the following syntax would infer the template with Throwable as the default value:

/**
 * @template T
 * @template E of Throwable
 */
interface ResultInterface {}

Psalm would only throw a MissingTemplateParalm. At the same time, PHPStan would report two errors. Still, the return would be implicitly inferred from ResultInterface<int> to ResultInterface<Throwable> in the not_documented() case on both major static analysis tools.

---

Apart from this, there is another feature that would be nice to have in the static analysis, and that is to be able to infer the type of @throws with a generic, so we could type this:

/**
 * @template T
 * @template E of Throwable = Throwable
 */
interface ResultInterface {
    /**
     * @return T
     * 
     * @throws E
     */
    public function getResult();
}

• Psalm:
  • UndefinedDocblockClass
  • Template usage on throws annotation vimeo/psalm#6098
• PHPStan
  • No errors, but when using checked exceptions it will not evaluate E at @throws
  • PHPStan doesn't infer exceptions that are thrown with generics. phpstan/phpstan#6043

[psalm-github-bot]

I found these snippets:

https://psalm.dev/r/891520eca6

<?php

/**
 * @template T
 * @template E of Throwable
 */
interface ResultInterface 
{
    /**
     * @return E
     */
    public function getThrowable();
}

/** 
 * @template E of Throwable
 * @implements ResultInterface<never, E>
 */
class Failure implements ResultInterface
{
    /**
     * @param E $throwable
     */
    public function __construct(
        private readonly Throwable $throwable
    ) {
    }
    
    public function getThrowable()
    {
        return $this->throwable;
    }
}

/**
 * @return ResultInterface<int, RuntimeException>
 */
function documented()
{
    return new Failure(new RuntimeException());
}

/**
 * @return ResultInterface<int>
 */
function not_documented()
{
    return new Failure(new RuntimeException());
}

function test_documented(): RuntimeException
{
    return documented()->getThrowable();
}

function test_not_documented(): Throwable
{
    return not_documented()->getThrowable();
}

Psalm output (using commit 3c90054):

ERROR: MissingTemplateParam - 44:12 - ResultInterface has missing template params, expecting 2

https://psalm.dev/r/e3257c26e9

<?php

/**
 * @template T
 * @template E of Throwable = Throwable
 */
interface ResultInterface {
    /**
     * @return T
     * 
     * @throws E
     */
    public function getResult();
}

Psalm output (using commit 3c90054):

ERROR: UndefinedDocblockClass - 11:16 - Docblock-defined class, interface or enum named E does not exist

[azjezz]

@veewee do you think this can make it to 3.0?

[veewee]

I've had an offline discussion about this and there were some good arguments in favour and against this. Will add the main discussion points to this ticket later so that we can conclude here

[veewee]

These were the main reasons that were holding back on implementing it:

There is no way in psalm (nor phpstan) to throw a generic exception:
https://psalm.dev/r/b3988674a5

/**
 * @template T of \Throwable
 * @param T $e
 * @throws T
 */
function throwIt(\Throwable $e): never {
    throw $e;
}

There is no way in psalm to set a default generic value

In a lot of situations, you are using something like Result\wrap() or similar in which you don't know what type of exception will be thrown. This will therefor be defaulted to \Throwable, making people have to add the type \Throwable everywhere where they use Result. It doesn't add any value for the user to add this type - just more work for no extra gain. This could be solved if we had generics with default types.

But there is no such thing like:

/**
 * @template E of \Throwable = \Throwable
 */

That allows you to overwrite defaults.

Either

Most of the problems that the additional <E> would solve, could be better dealt with when introducing an Eiter<L, R> type as described in #355.
There the types would be required and there won't be a throw. So you could use one of them as the specific exception.

Conclusion
It is possible to add an additional <E> param. But it wouldn't add a lot of value, if any at current moment.

@devnix Feel free to add to the list here - I might have forgotten a few details.

[psalm-github-bot]

I found these snippets:

https://psalm.dev/r/b3988674a5

<?php

/**
 * @template T of \Throwable
 * @param T $e
 * @throws T
 */
function throwIt(\Throwable $e): never {
    throw $e;
}

Psalm output (using commit ef3b018):

ERROR: UndefinedDocblockClass - 6:12 - Docblock-defined class, interface or enum named T does not exist

[devnix]

Update: https://x.com/OndrejMirtes/status/1843920480342057154?t=DEWZtzAdwWL9HIJFt1muVA&s=19

[devnix]

I've been reading lately and I've finally clicked on this:

In a lot of situations, you are using something like Result\wrap() or similar in which you don't know what type of exception will be thrown. This will therefore be defaulted to \Throwable, making people have to add the type \Throwable everywhere where they use Result. It doesn't add any value for the user to add this type - just more work for no extra gain. This could be solved if we had generics with default types.

Also, when handling a success or a failure of a Result instance, if another error/exception is thrown, it will return a Result<TResult, Throwable>, and the previous type of the E template will be lost.

I think there's a nomenclature problem: this is not a Result monad, but a Try monad, and I was expecting this Result implementation as a specialized subtype of Either.

You may not like the idea of deprecating and renaming the implementation. Would a Rector rule help considering that suggestion? If not, would you suggest looking into another library specializing in monads?

[veewee]

I'm not in favour of renaming the implementation at this point.

Introducing an Either monad would solve the issue IMO.

[azjezz]

+1 for introducing Either<A, B>