Vyrn.Ratatoskr 0.4.0

Vyrn.Ratatoskr

A small result library for .NET 10.

Use Result when an operation can succeed or fail. Expected failures become values that your code can return and handle. Exceptions stay available for unexpected failures.

Packages

Install

Install the core package:

dotnet add package Vyrn.Ratatoskr

For ASP.NET Core, also install:

dotnet add package Vyrn.Ratatoskr.AspNetCore

Quick Start

Return a value when the operation succeeds. Return a Rejection when it fails.

using Vyrn.Ratatoskr;

public Result<Order> FindOrder(string id)
{
    var order = orders.Find(order => order.Id == id);

    if (order is null)
    {
        return Rejection.NotFound(
            "Orders.NotFound",
            $"Order '{id}' was not found.");
    }

    return order;
}

Use Match to handle both outcomes:

string message = FindOrder("42").Match(
    order => $"Found {order.Name}",
    error => error.Description);

Create Results

Result.Success();
Result.Success(order);

Result.Failure(Error.Unexpected("Orders.Failed", "The order could not be saved."));
Result.Failure<Order>(Error.NotFound("Orders.NotFound", "The order was not found."));

Rejection is a shorter way to return a failure. It works with Result and Result<T>.

return Rejection.Validation("Orders.Name.Required", "Name is required.");
return Rejection.NotFound("Orders.NotFound", "The order was not found.");
return Rejection.Conflict("Orders.Exists", "The order already exists.");
return Rejection.Unexpected("Orders.Failed", "The order could not be saved.");

Work With Results

Failures keep their error in Map, Bind, and Ensure.

public Result<OrderDto> GetOrder(string id)
    => FindOrder(id)
        .Ensure(
            order => order.IsActive,
            Rejection.Validation("Orders.Inactive", "The order is not active."))
        .Map(order => new OrderDto(order.Id, order.Name));

Map, Bind, Match, Ensure, Tap, and TapFailure also work on Task<Result> and Task<Result<T>>:

Result<OrderDto> result = await FindOrderAsync(id)
    .Map(order => new OrderDto(order.Id, order.Name));

Validate Input

Use Result.Ensure for one check. Use Result.Validate to run several checks.

Result validation = Result.Validate(
    Result.Ensure(
        !string.IsNullOrWhiteSpace(name),
        Rejection.Validation("Orders.Name.Required", "Name is required.")),
    Result.Ensure(
        quantity > 0,
        Rejection.Validation("Orders.Quantity.Invalid", "Quantity must be greater than zero.")));

One failed check returns its error. Several failed checks return a ValidationError with all errors in Details.

Combine Results

Use Sequence when you already have a collection of results. It returns all successful values in source order, or the first failure:

Result<IReadOnlyList<Order>> orders = orderResults.Sequence();

Use Traverse to transform a collection with a result-producing function and combine the results in one operation:

Result<IReadOnlyList<Order>> orders = orderIds.Traverse(FindOrder);

Both operations stop at the first failure. Exceptions from enumeration or transformation continue normally so the application's exception boundary can handle them.

Define Reusable Errors

Use ErrorCatalog when one area of your application has many errors.

public static class OrderErrors
{
    private static readonly ErrorCatalog Catalog = new("Orders");

    public static Rejection NotFound(string id)
        => Catalog.NotFound("NotFound", $"Order '{id}' was not found.");

    public static Rejection SaveFailed()
        => Catalog.Unexpected("SaveFailed", "The order could not be saved.");
}

Call sites stay short:

return OrderErrors.NotFound(id);

ASP.NET Core

Add the namespace and convert the result in an MVC controller:

using Vyrn.Ratatoskr.AspNetCore;

[HttpGet("{id}")]
public async Task<ActionResult> Get(string id)
{
    Result<OrderDto> result = await service.GetOrder(id);
    return result.ToActionResult();
}

Default responses:

Failures use ProblemDetails. The error code and category are in the code and category extensions. A ValidationError also adds an errors extension. Attached exceptions are never included in the HTTP response.

Use a success factory when you need another success response:

return result.ToActionResult(
    order => CreatedAtAction(nameof(Get), new { id = order.Id }, order));

Minimal APIs keep success and failure mapping explicit:

static async Task<IResult> GetOrder(
    string id,
    CancellationToken cancellationToken)
{
    if (string.IsNullOrWhiteSpace(id))
    {
        return Rejection.Validation("Orders.Id.Required", "An order ID is required.")
            .ToProblemHttpResult();
    }

    var result = await LoadOrder(id, cancellationToken);
    if (result.IsFailure)
    {
        return result.Error.ToProblemHttpResult();
    }

    return TypedResults.Ok(result.Value);
}

Use ASP.NET Core's built-in TypedResults for successful Minimal API responses. Check failures explicitly and convert the error with ToProblemHttpResult():

if (result.IsFailure)
{
    return result.Error.ToProblemHttpResult();
}

return TypedResults.Created($"orders/{result.Value.Id}", result.Value);

ProblemHttpResult has a dynamic status. Declare the successful response with .Produces(...) and add .ProducesProblem(status) for each failure status so OpenAPI describes the complete endpoint contract.

Showcase

The Pokemon showcase is a small ASP.NET Core application that demonstrates validation, reusable errors, and exception conversion against the public PokeAPI. Its browser UI is one search form that loads a Razor card with HTMX.

Run it locally:

dotnet run --project Samples/Vyrn.Ratatoskr.Showcase

Then open http://localhost:5000 and search for a Pokemon.

Main Types

More Information

• Technical reference
• Source code
• MIT license

Run the project locally with:

dotnet test vyrn.ratatoskr.slnx