Spirantis.Result 10.0.0

Spirantis.Result

A small, dependency-free result type for C#. Model the outcome of an operation as an explicit success or failure instead of throwing, with a lightweight functional API (Match, Map, Bind, Tap) for composing the happy path.

• Result — success/failure with an optional Error.
• Result<T> — success carries a value of type T; failure carries an Error.
• Error — a failure reason: a Message and an optional wrapped Exception.

Targets .NET 10. No runtime dependencies. MIT licensed.

Install

dotnet add package Spirantis.Result

Quick start

using Spirantis.Result;

Result<int> Parse(string input) =>
    int.TryParse(input, out var n)
        ? n                              // implicit: value  -> success
        : new Error("not a number");     // implicit: error  -> failure

string message = Parse("41")
    .Map(n => n + 1)                     // 42, still success
    .Match(
        onSuccess: n => $"got {n}",
        onFailure: e => $"failed: {e?.Message}");
// "got 42"

Creating results

Use the implicit conversions or the static factories — whichever reads better.

// Result (no value)
Result ok   = Result.Success();
Result bad  = Result.Fail("disk full");
Result wrap = new InvalidOperationException("boom");   // implicit -> failure

// Result<T>
Result<int> value = 42;                  // implicit -> success
Result<int> error = new Error("nope");   // implicit -> failure
Result<int> viaFactory = Result.Fail<int>("nope");
Result<User> user = Result.Success(new User());

Note: on Result<T>, only T (success) and Error (failure) convert implicitly. Unlike the non-generic Result, there is intentionally no implicit string/Exception conversion — it would be ambiguous for Result<string>/Result<Exception>. Use Result.Fail<T>(...) for those.

Inspecting results

if (result.IsSuccess) { /* ... */ }
if (result.IsFailure) { /* ... */ }

// Result<T>: TryGetValue narrows nullability for you
if (result.TryGetValue(out var value))
    Console.WriteLine(value);            // value is non-null here

if (!result.TryGetValue(out var value, out var error))
    Console.WriteLine(error?.Message);

int safe        = result.GetValueOr(-1);
int? maybe      = result.GetValueOrDefault();

IsSuccess on Result<T> is annotated with [MemberNotNullWhen(true, nameof(Value))], so the compiler knows Value is non-null inside an if (result.IsSuccess) branch.

Composing

Result<string> outcome = LoadUser(id)            // Result<User>
    .Tap(u => logger.LogInformation("loaded {Id}", u.Id))
    .Bind(u => Authorize(u))                      // Result<Session>
    .Map(s => s.Token);                           // Result<string>

The onFailure delegate receives Error? (nullable): a failure produced by Result.Fail() has no associated error.

Errors

var fromMessage   = new Error("validation failed");
var fromException = new Error(ex);                 // Message defaults to ex.Message
var withBoth      = new Error(ex, "friendly text");

Error implicitMsg = "shorthand";                   // implicit

Error is immutable and has value equality: two errors are equal when their Message matches and they reference the same Exception instance (exceptions compare by reference).

Equality

Result, Result<T>, and Error all implement value equality (Equals / GetHashCode), which makes them easy to assert in tests:

Assert.Equal(Result.Success(42), Result.Success(42));
Assert.Equal(Result.Fail<int>("x"), Result.Fail<int>("x"));

Results of different runtime types are never equal (e.g. Result<int> ≠ Result<long>).

Extending

Result / Result<T> are open for inheritance — derive when you need extra state. Override the protected EqualsCore hook to fold that state into equality:

public class FunctionResult : Result<object>
{
    public FunctionResult(FunctionResultType type, object value) : base(value) => Type = type;
    public FunctionResultType Type { get; init; }

    protected override bool EqualsCore(Result other) =>
        base.EqualsCore(other) && Type == ((FunctionResult)other).Type;
}

License

MIT