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]

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]

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]

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

[julianthurner]

I understand, I changed the implementation to return AwaitableResult<T> instead.

[sakno]

No need to do that, because SuspendException provides the same semantics:

Task<Optional<int>> optional = ...;
Result<int> result = await optional.Flatten().SuspendException();

[sakno]

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

[julianthurner]

Changed the implementation to return AwaitableResult<T, TError> instead.

[sakno]

No need to do that, because there is an overload for SuspendException that returns the necessary result:

public static AwaitableResult<T, TError> SuspendException<T, TError>(this Task<T> task,
        Converter<Exception, TError> converter)

[sakno]

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

[julianthurner]

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

@sakno I'm not sure I understand. This method is intended to be used like this:

var optional = Optional.Some(42);
var convertedOptional = await optional.Convert(async (int x, CancellationToken y) => x.ToString());

What would be the correct way of implementing this with SuspendException instead?

[sakno]

The same can be achieved with existing extension method:

var optional = Optional.Some(42);
Optional<string> convertedOptional = Task.FromResult(optional).Convert(async (value, token) => x.ToString());

[sakno]

SuspendException as the last call in the chain always returns Result<T>, so any async chain can be converted to Result<T> or Optional<T> in the end.

[sakno]

It means that public static async Task<Optional<TOutput>> Convert<TInput, TOutput>(this Task<Optional<TInput>> task, Func<TInput, CancellationToken, Task<Optional<TOutput>>> converter, CancellationToken token = default) method is redundant as well