W4k.Either 1.1.1

W4k.Either

This library provides a variety of types for handling the results of operations or representing discriminated unions of two or more types.

Installation

To install the library, add the following package reference to your project file:

  <ItemGroup>
    <PackageReference Include="W4k.Either" Version="1.1.0" />
  </ItemGroup>

Description

Types provided by this library are intended to be used as return types of methods and functions. They are designed to be used in functional programming style, but can be used in any other style as well.

All types are generated using W4k.Either.CodeGeneration package.

Usage

Common API for all provided types:

* Bind<TNew> allows for chaining of operations where the result of one operation can affect subsequent ones.

** Map<TNew> is used for pure transformation of the value without affecting the flow of operations.

<a id="either"></a>

Either

Use Either to communicate the result of an operation without propagating an exception.

Either<User, FetchError> GetUser(UserIdentifier userId)
{
    try
    {
        // ...
        return new User(...);
    }
    catch (Exception ex)
    {
        return new FetchError(ex);
    }
}

var result = GetUser(userId);
var message = result.Match(
    user => $"User {user.Name} fetched",
    error => $"Error {error.Message} occured"
);

For Either<TLeft, TRight>, there are additional properties for inspecting the state:

<a id="maybe"></a>

Maybe

Use Maybe to communicate that an operation resulted in no value, as an alternative to returning null.

Maybe<User> FindUser(UserIdentifier userId)
{
    // ...
    return userFound 
        ? new User(...) // or Maybe<User>.Some(new User(...))
        : Maybe<User>.None;
}

var user = FindUser(...);
if (user.HasValue)
{
    Console.WriteLine($"User found: {user.Value.Name}");
}

<a id="result"></a>

Result

To indicate the result of an operation without throwing exceptions or using tuples, use Result. This type is the same as Either<TValue, TError>, but with additional properties to inspect the state of the result object.

Result<User, FetchError> GetUser(UserIdentifier userId)
{
    try
    {
        // ...
        return new User(...);
    }
    catch (Exception ex)
    {
        return new FetchError(ex);
    }
}

var result = GetUser(userId);
if (result.IsSuccess)
{
    Console.WriteLine($"User found: {result.Value.Name}");
}
else
{
    Console.WriteLine($"Error {result.Error.Message} occured");
}

// ... or if you prefer errlang - I mean Go
var (user, err) = GetUser(userId);
if (err != null)
{
    Environment.Exit(1);
}

Console.WriteLine($"User found: {user.Name}");

<a id="optional_result"></a>

OptionalResult

OptionalResult can indicate the result of an operation with an optional value. It's the same as Result<Maybe<TValue>, TError>.

OptionalResult<User, FetchError> FindUser(UserIdentifier userId)
{
    try
    {
        // ...
        return userFound
            ? new User(...)
            : OptionalResult<User>.Empty;
    }
    catch (Exception ex)
    {
        return new FetchError(ex);
    }
}

var result = FindUser(userId);
if (result.IsSuccess)
{
    if (result.HasValue)
    {
        Console.WriteLine($"User found: {result.Value.Name}");
    }
    else
    {
        Console.WriteLine("User not found");
    }
}
else
{
    Console.WriteLine($"Error {result.Error.Message} occured");
}

Shapes and symbols icons created by Freepik - Flaticon