Added convenience methods for easier Monad creation and Monad chaining

[julianthurner]

I added some convenience methods to the library. The Option class receives a few extension methods that allow for chaining async conversions:

var optional = await Optional.FromValue(42)
    .Convert(async x => x > 10 ? Optional.FromValue(x * 2.0 - 20) : Optional<double>.None)
    .Convert(async x => x > 0 ? Optional.FromValue("Success") : Optional<string>.None);

Console.WriteLine(optional.HasValue ? optional.Value : "Optional has no value");

This is really useful if you work with databases where data is fetched / transformed multiple times asynchronously before being filled into a DTO.
The same thing for Result:

var result = await Result.FromValue(42)
    .Convert(async x => x > 10 ? Result.FromValue(x * 2.0 - 20) : Result.FromException<double>(new Exception("x too small")))
    .Convert(async x => x > 0 ? Result.FromValue("Success") : Result.FromException<string>(new Exception("x less than zero")));

Console.WriteLine(result.IsSuccessful ? result : $"Failed with exception: {result.Error}");

This also forwards the exception up the chain just like with regular monads.

There's also overloads for converting Option ↔ Result in both directions if there's need for conversion within a chain.

var optionalFromResult = await Task.FromResult(Result.FromValue<int, TestError>(42))
    .TryGet()
    .Convert(async x => x > 10 ? Optional.FromValue(x) : Optional<int>.None);
Console.WriteLine(optionalFromResult.HasValue ? optionalFromResult.Value : "Optional has no value");

var resultFromOptional = await Task.FromResult(Optional.FromValue(42))
    .ToResult()
    .Convert(async x => x > 10 ? Result.FromValue("Success") : Result.FromException<string>(new Exception("x too small")));
Console.WriteLine(resultFromOptional.IsSuccessful ? resultFromOptional.Value : $"Failed with exception: {resultFromOptional.Error}");

Also, I added some additional convenience methods for creating Options and Results statically:

var optionalWithValue = Optional.FromValue(42);
var errorCodeResultWithValue = Result.FromValue<int, TestError>(42);
var errorCodeResultWithError = Result.FromError<int, TestError>(TestError.Error1);

[julianthurner]

@dotnet-policy-service agree

@dotnet-policy-service agree

[sakno]

@julianthurner , thanks for your contribution! According to the Contribution Guideline, could you change the target branch from master to develop?

[sakno]

Task<Result<T>> is a subject for debates, because Task is already a monad that contains a result or an exception. Both types have the similar semantics. Thus, Task<Result<T>> is the same as Result<Result<T>>.

[julianthurner]

I understand that point, however: If i have an async method which contains one ore more await statements, then the result of the method has to be Task<T>. And as far as I am concerned, there is no implicit conversion from Task<T> to Result<T>. Or did I overlook that?

[sakno]

There are some methods to convert task types located in Conversion class. Also, there is a method

static AwaitableResult<T> SuspendException<T>(this Task<T> task)

not yet released. With help of these methods, you can create async pipeline as follows:

Result<double> result = await SomeAsyncMethod().Convert<int, double>(i => i).SuspendException();

It's called SuspendException because the returned awaitable object never throws. Instead, the exception is returned as the part of Result<T>.

[julianthurner]

AwaitableResult seems like a neat feature!

Will this also be chainable like so?

var result = await Task.FromResult(42).SuspendException()
    .Convert(async x => x > 10 ? x * 2.0 : throw new Exception("x too small")).SuspendException()
    .Convert(async x => x > 42 ? x.ToString() : throw new Exception("x less than 42").SuspendException();

If not, I can wait until the method is implemented and then add the respective extension methods that are needed to do this.

[sakno]

SuspendException is the last call in the chain since the Task is already acts as a monad:

Result<int> result = await Task.FromResult(42)
    .Convert(async x => x > 10 ? x * 2.0 : throw new Exception("x too small"))
    .Convert(async x => x > 42 ? x.ToString() : throw new Exception("x less than 42")
    .SuspendException();

[julianthurner]

Neat! Then I'll remove the commented method?

[sakno]

I think so. SuspendException is available in develop branch (added in 0cb6a6a)

[julianthurner]

@sakno could you take a look at the updated branch? I changed all methods to work with AwaitableResult

[sakno]

SuspendException is a tail call, no need apply any transformation to it. As shown above, all transformations can be done before SuspendException.

[julianthurner]

SuspendException is a tail call, no need apply any transformation to it.

What part of the code are you referring to / what do you suggest I should change?

[sakno]

Changing the target branch is not enough. master cannot be used as a base branch for your branch, because master branch contains only squashed commits from develop branch. You need to create a branch from develop and cherrypick your commits, then force push.

Also, after the discussion of the API, units tests need to be added as well.

[sakno]

This method is also redundant, because Convert is already defined for generic Task<T> in DotNext.Threading.Tasks.Conversion static class.

[julianthurner]

Sorry it took me a while to find time again, I think this method is not completely redundant because omitting it means having to handle the Optional yourself every time instead of being able to rely on the monad chain handling it which defeats the whole purpose of the chain (see examples below). It also means that if I use static conversion methods which I might re-use elsewhere in the code instead of lambdas, I have to force Optional<TInput> as input type instead of being able to simply accept TInput.

Without extension method:

var optional = await Task.FromResult(Optional.FromValue(42))
    .Convert(async x => x > 10 ? x * 2.0 - 20 : Optional<double>.None)
    .Convert(async x => x > 0 ? "Success" : Optional<string>.None);

With extension method:

var optional = await Task.FromResult(Optional.From(42))
    .Convert(async x => x.HasValue && x.Value > 10 ? x.Value * 2.0 - 20 : Optional<double>.None)
    .Convert(async x => x.HasValue && x.Value > 0 ? "Success" : Optional<string>.None);

[sakno]

The proposed method has no cancellation token support. Since 5.19.0 that is just released, there is Convert with it:

Task<Optional<TOutput>> Convert<TInput, TOutput>(this Task<Optional<TInput>> task,
        Func<TInput, CancellationToken, Task<TOutput>> converter, CancellationToken token = default)

[sakno]

I would suggest to review the proposed API again from your side, since 5.19.0 has been released:

1. Some factory method ✔️
2. SuspendException to return Result<T> or Result<T, TError> ✔️
3. Async Convert with cancellation support ✔️
4. Flatten to convert Task<Optional<T>> to Task<T> ✔️

[julianthurner]

I would suggest to review the proposed API again from your side, since 5.19.0 has been released:

1. Some factory method ✔️
2. SuspendException to return Result<T> or Result<T, TError> ✔️
3. Async Convert with cancellation support ✔️

Looks nice👍I will review the changes and adjust them accordingly, sometime this week probably.

[julianthurner]

Well, life got in the way ...
I started solving the merge conflicts today. But I'm in the middle of exams right now, so it's probably gonna take a little more time till I can continue.

[julianthurner]

@sakno Sorry it took me this long. My exams were eating up any brain capacity I had, but luckily they are over now. Please take a look at the updated version. I will add Unit Tests once the API is finished.

[sakno]

Why do you need this method? AwaitableResult<T> is a leaf type in async chain. All you need to just to change the order of your conversion methods.

Instead

Task<int> task = Task.FromResult(20);
Result<double> result = await task.SuspendException().Convert(i => (double)i);

you can do

Task<int> task = Task.FromResult(20);
Result<double> result = await task.Convert(i => (double)i).SuspendException();

Task<Result<T>> as well as Result<Task<T>> is a redundancy, because Task<T> and Result<T> has similar semantics due to encapsulating error/result in the same place.

[sakno]

This method is redundant because AwaitableResult<T> is a leaf type in async chain.

Instead

Task<string> task = Task.FromResult("Hello, world!");
Result<object> result = await task.SuspendException().Convert<string, object>();

you can do

Task<string> task = Task.FromResult("Hello, world!");
Result<object> result = await task.Convert<string, object>().SuspendException();

[sakno]

Task<Result<T>> is redundant type, this conversion makes no sense. There is Flatten method that converts Task<Optional<T>> to Task<T>.

[sakno]

Task<Result<T, TError>> is a redundant type.

[sakno]

AwaitableResult<T> is a leaf type.

[sakno]

This method provides a little value, because it's already covered by Conversion.Convert. Also, Flatten method can be used to convert Task<Optional<T>> to Task<T> in the beginning of the async chain.

Instead

Task<Optional<int>> task = Task.FromResult(Optional.Some(42));
Optional<int> result = await task.Convert(i => i);

Task<Optional<int>> task = Task.FromResult(Optional.Some(42));
int result = await task.Flatten().Convert(i => i);

Also, the similar behavior can be achieved by using SuspendException which returns Result<T>. Result<T> has implicit conversion to Optional<T>, so the chain above can be rewritten easily with existing API:

Task<Optional<int>> task = Task.FromResult(Optional.Some(42));
Optional<int> result = await task.Flatten().Convert(i => i).SuspendException(); // implicit conversion from Result<T> to Optional<T>

[sakno]

There is explicit conversion operator in Result<T> type, so you can use casting syntax:

Optional<int> value = 42;
var result = (Result<int>)value;

[sakno]

The method is redundant, since SuspendException returns Result<T> that has implicit conversion to Optional<T>.

[sakno]

This method doesn't help with type inference, it's literally the same as calling ctor on Result<T, E> type.

[sakno]

AwaitableResult<T> is a leaf type, it cannot be chained.