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.

[julianthurner]

@sakno If you approve of the current state, I will implement Unit Tests next.

[sakno]

AwaitableResult is a leaf type. It cannot be used to build a chain, as discussed above. Please review the rest of the methods where the type is used as an input parameter.