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.

[julianthurner]

@sakno Are you content with the current state of the API?

[julianthurner]

@sakno While implementing Unit Tests, I noticed that trying to access the unsafe versions of both the existing ConvertOptional() and newly added ConvertResult() methods results in an error due to ambiguity (see attached screenshots). If this is not surpassable by some means, I think that the unsafe versions of both methods should be removed.

[julianthurner]

@sakno Also, the Linux Tests seem to fail due to timeout. What can I do about that?

[sakno]

results in an error due to ambiguity

Try to specify generic argument explicitly to help the compiler.

the Linux Tests seem to fail due to timeout

Yeah, it's a flaky issue caused by synchronization context used by xUnit infrastructure. You can just restart the test from Azure DevOps. From time to time I'm improving the stability of the tests, but it's not completely fixed.

[julianthurner]

@sakno Thanks, I got the unsafe versions to work and after a few restarts, the Linux Tests managed to finish without timeout.