Waystone.Monads 5.5.0

Waystone.Monads

A .NET implementation of the std::option and std::result modules from the Rust Standard Library.

Option

The Option type represents an optional value: every Option is either Some and contains a value, or None, and does not. It provides similar functionality to the built in nullable reference types offered in C#, but provides a more rigid structure for handling the "null" scenario.

Implemented Types

• An Option<T> abstract record describes the Option type.
• A Some<T> record describes the Some type.
• A None<T> record describes the None type.

Result

The Result type is a type used for returning and propagating errors. Every Result is either Ok, representing success and containing a value, or Err, representing an error and containing an error value.

Implemented Types

• An Result<TOk,TErr> abstract record describes the Result type.
• An Ok<TOk,TErr> record describes the Ok type.
• An Err<TOk,TErr> record describes the Err type.

Creating Results

Supply both type parameters when you provide your own error type:

Result<int, string> result = Result.Ok<int, string>(1);
Result<int, string> error = Result.Err<int, string>("something went wrong");

If you are happy with the built in Error type, use the single type parameter overloads instead. These default TErr to Error:

Result<int, Error> result = Result.Ok<int>(1);
Result<int, Error> error = Result.Err<int>(new Error("MyCode", "something went wrong"));

An Error code can be derived from an enum value, which keeps the code stable across occurrences of the same error type:

enum UserErrors
{
    NotFound,
}

// code becomes "UserErrors.NotFound"
Result<User, Error> error = Result.Err<User>(UserErrors.NotFound, "the user was not found");

// or, when you need the error on its own
Error err = Error.FromEnum(UserErrors.NotFound, "the user was not found");

Use Try to capture the value of a factory that may throw. The single type parameter overload converts the exception using Error.FromException:

Result<int, string> custom = Result.Try(() => int.Parse(input), ex => ex.Message);
Result<int, Error> parsed = Result.Try<int>(() => int.Parse(input));

Async

Both monads provide TryAsync for factories that return a Task:

Result<User, Error> result = await Result.TryAsync<User>(() => FetchUserAsync(id));
Option<User> option = await Option.TryAsync(() => FetchUserAsync(id));

The terminal operations are also available on Task and ValueTask receivers, so you do not have to await the monad before unwrapping it:

User user = await FetchUserAsync(id).UnwrapAsync();
User userOrGuest = await FetchUserAsync(id).UnwrapOrAsync(Guest);
User expected = await FetchUserAsync(id).ExpectAsync("the user must exist");
Error error = await FetchUserAsync(id).UnwrapErrAsync();

Result provides UnwrapAsync, UnwrapErrAsync, UnwrapOrAsync, UnwrapOrDefaultAsync, ExpectAsync and ExpectErrAsync. Option provides UnwrapAsync, UnwrapOrAsync, UnwrapOrDefaultAsync and ExpectAsync.

Configuration

You can configure an action to be invoked when an exception is caught and handled by the library. Invoke the UseExceptionLogger function once during the lifetime of your app:

MonadOptions.Configure(options => options.UseExceptionLogger((exception, callerInfo) =>
{
    Log.Error(exception, "Exception when creating monad"); // use Serilog/NLog/Etc
}));

There may be times where you want to generate an ErrorCode from an Enum or an Exception. You can configure the formatting of the generated error codes using the UseErrorCodeFactory.

class MyErrorCodeFactory : ErrorCodeFactory
{
  // override as needed
}

MonadOptions.Configure(options => options.UseErrorCodeFactory(new MyErrorCodeFactory()));

![NOTE] The MonadOptions class acts like a singleton, so you should only configure it once in your application's life-cycle.

Scoped Configuration

When you need different options for one region of code - a single request, a test, or a block you are debugging - create a scope instead of reconfiguring the whole application:

using (MonadOptions.BeginScope(options => options.UseFallbackErrorCode("Debug")))
{
    // reads inside here, including after an await, see "Debug"
    var result = Result.Try<int>(() => int.Parse(input));
}

// the global configuration is unchanged out here

Options you do not set are inherited from the configuration in effect when the scope is created, and the scope is a snapshot, so a later Configure call does not change an open scope. Scopes nest, and disposing one restores the scope around it.

Scopes accept the same configuration methods as Configure, so an override can change any option:

using (MonadOptions.BeginScope(options => options
    .UseErrorCodeFactory(new MyErrorCodeFactory())
    .UseFallbackErrorMessage("Something went wrong while debugging.")))
{
    // ...
}

Because a scope applies to the current asynchronous flow, concurrent flows each see their own options. This makes scopes safe to use in parallel tests.