Incendium.Result 1.0.5

Incendium.Result

Incendium.Result is a lightweight .NET Standard 2.1 library, which provides Error, Result<T> and NullableResult<T> useful types.

These types allow you to return success value or error from asynchronous and synchronous methods without explicit indication of the result type when returning and with convenient type deconstruction during processing the result.

These types also can be used for less error handling through exception mechanisms where possible.

Getting started

Installation

PM> Install-Package Incendium.Result

Result<T>

If you need to return either a not-null value or an error from a method, you can use the Result<T> type:

public Result<string> GetString() {
    // ...
    if (condition1) {
        return "Test string result";
    } else {
        return new Error(code: 123, message: "Test error");
    }

    try {
        // ...
    } catch (Exception e) {
        return new Error(code: 321, message: "Test error", exception: e);
    }
}

Then processing the result might look like this:

// Using deconstruction
var (str, error) = GetString();

if (error != null) {
    log.LogError(
        error.Exception(),
        "Error with code {@code} and message {@message}",
        error.Code,
        error.Message);
}

// Using functional methods
var result = GetString()
    .Tap(str => logger.Log($"Retrieved string {str}"))
    .Map(str => str.ToUpper())
    .Bind(str => ValidateString(str))
    .Match(
        str => $"Success: {str}",
        error => $"Failed: {error.Message}"
    );

// Using TryGetValue
if (GetString().TryGetValue(out var value))
{
    Console.WriteLine($"Got value: {value}");
}

The Result<T> instance can be created only from non-null value or from non-null error:

public Result<Foo> GetFoo() {
    return new Foo(); // correct
    return new Error(); // correct
    return Result<Foo>.Success(new Foo()); // correct
    return Result<Foo>.Failure(new Error()); // correct
    return (Foo)null; // incorrect, CS8600 and CS8625 warnings, throws ArgumentNullException
    return (Foo)null!; // incorrect, throws ArgumentNullException
    return (Foo?)null; // incorrect, CS8625 warning, throws ArgumentNullException
    return (Foo?)null!; // incorrect, throws ArgumentNullException
    return (Error)null; // incorrect, CS8600 and CS8625 warnings, throws ArgumentNullException
    return (Error)null!; // incorrect, throws ArgumentNullException
    return (Error?)null; // incorrect, CS8625 warning, throws ArgumentNullException
    return (Error?)null!; // incorrect, throws ArgumentNullException
}

NullableResult<T>

If the successful return value can be null, you must use the NullableResult<T> type:

public NullableResult<Foo> GetFoo() {
    return new Foo(); // correct
    return new Error(); // correct
    return NullableResult<Foo>.Success(new Foo()); // correct
    return NullableResult<Foo>.Success(null); // correct
    return NullableResult<Foo>.Failure(new Error()); // correct
    return (Foo?)null; // correct
    return (Foo)null; // correct with CS8600 warning
    return (Foo)null!; // correct
    return (Error)null; // incorrect, CS8600 and CS8625 warnings, throws ArgumentNullException
    return (Error)null!; // incorrect, throws ArgumentNullException
    return (Error?)null; // incorrect, CS8625 warning, throws ArgumentNullException
    return (Error?)null!; // incorrect, throws ArgumentNullException
}

Functional Methods

Both Result<T> and NullableResult<T> support functional programming patterns through the following methods:

• Map<TResult>(Func<T, TResult> mapper) - Transform the success value
• Bind<TResult>(Func<T, Result<TResult>> binder) - Chain operations that return Result
• Match<TResult>(Func<T, TResult> onSuccess, Func<Error, TResult> onError) - Handle both success and error cases
• Match(Action<T> onSuccess, Action<Error> onError) - Execute actions for success or error
• TryGetValue(out T value) - Attempt to get the success value
• Tap(Action<T> action) - Execute an action on success without changing the result

Example of chaining operations:

var result = GetUser(123)
    .Tap(user => logger.LogInfo($"Retrieved user {user.Id}"))
    .Map(user => user.Email)
    .Bind(email => ValidateEmail(email))
    .Match(
        email => $"Email is valid: {email}",
        error => $"Validation failed: {error.Message}"
    );

License

This project is licensed under the MIT License - see the LICENSE file for details.