Hrz.Returnables 0.1.1

<p align="center"> <img src="icon.png" alt="Hrz Returnables" width="120" /> </p>

<h1 align="center">Hrz Returnables</h1>

<p align="center"> A lightweight, zero-dependency Result/Error pattern library for .NET.<br/> Replace exception-driven control flow with explicit, type-safe return values. </p>

<p align="center"> <a href="https://nuget.org/packages/Hrz.Returnables"><img src="https://img.shields.io/nuget/v/Hrz.Returnables.svg?style=flat-square&logo=nuget&label=NuGet" alt="NuGet Version" /></a> <a href="https://nuget.org/packages/Hrz.Returnables"><img src="https://img.shields.io/nuget/dt/Hrz.Returnables.svg?style=flat-square&logo=nuget&label=Downloads" alt="NuGet Downloads" /></a> <a href="https://github.com/horizon-co/hrz-returnables/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/horizon-co/hrz-returnables/ci.yml?branch=main&style=flat-square&logo=github&label=CI" alt="CI Status" /></a> <a href="https://github.com/horizon-co/hrz-returnables/blob/main/LICENSE"><img src="https://img.shields.io/github/license/horizon-co/hrz-returnables?style=flat-square&label=License" alt="License" /></a> </p>

Why Returnables?

Exceptions are expensive, invisible in method signatures, and easy to forget. The Result pattern makes success and failure explicit — your code tells the caller exactly what can happen, and the compiler helps enforce it.

Returnables gives you this pattern with zero boilerplate:

using Hrz.Returnables;

public Result<User> GetUser(int id)
{
    var user = repository.Find(id);

    if (user is null)
    {
        return Result<User>.Fail("User not found");
    }

    return user; // implicit conversion
}

No wrapping. No .Success(value) calls. No factory noise. Just return the value or an exception — Returnables figures out which one it is.

Key Features

• Implicit operators — return TValue or Error directly from any Result<TValue> method
• Zero dependencies — pure .NET BCL, no third-party packages
• Stack-allocated — readonly struct types with zero heap overhead on success paths
• Null-safe — [MemberNotNullWhen] attributes give the compiler full nullability flow analysis
• Try/TryAsync — wrap any operation in a try/catch and get a Result back
• Fluent side-effects — OnSuccess / OnFailure for logging and telemetry without breaking chains
• Conditional factories — SuccessIf / FailIf for guard-clause style results

Installation

dotnet add package Hrz.Returnables

Or via the Package Manager:

PM> Install-Package Hrz.Returnables

Quick Start

Result — void operations

For commands and side-effects that don't return a value:

using Hrz.Returnables;

public Result DeleteUser(int id)
{
    if (!repository.Exists(id))
    {
        return Result.Fail("User not found");
    }

    repository.Delete(id);
    return Result.Success;
}

Result<TValue> — operations with data

For operations that return a value on success:

public Result<decimal> Divide(decimal dividend, decimal divisor)
{
    if (divisor == 0)
    {
        return Result<decimal>.Fail("Division by zero");
    }

    return dividend / divisor; // implicit conversion
}

Consuming a Result

Check Succeeded or Failed, then access Value or Error:

var result = Divide(10, 3);

if (result.Succeeded)
{
    Console.WriteLine($"Answer: {result.Value}");
}
else
{
    Console.WriteLine($"Error: {result.Error.Message}");
}

Or use Switch for exhaustive handling:

result.Switch(
    onSuccess: value => Console.WriteLine($"Answer: {value}"),
    onFailure: error => Console.WriteLine($"Error: {error.Message}"));

Implicit Conversions

Results convert implicitly to and from their inner types:

// Value → Result (success)
Result<string> result = "Hello, world!";

// Error → Result (failure)
Result<string> result = Error.Create("BrokeCode", "Something broke");

// Result → Value (unwrap)
string value = result;

// Result → Error (extract error)
Error? error = result;

// Result<T> → Result (discard value, keep outcome)
Result voidResult = result;

Core API

Result (void)

Result<TValue>

All members from Result (void) plus:

Try / TryAsync

Wrap any operation — exceptions become failed results instead of propagating:

// Synchronous
Result<Config> config = Result<Config>.Try(
    () => JsonSerializer.Deserialize<Config>(json)!);

// Async
Result<User> user = await Result<User>.TryAsync(
    async () => await httpClient.GetFromJsonAsync<User>(url));

// Void
Result result = Result.Try(() => fileSystem.Delete(path));

SuccessIf / FailIf

Guard-clause style conditional results:

// With a message
Result result = Result.FailIf(string.IsNullOrEmpty(name), "Name is required");

// With a typed exception
Result result = Result.SuccessIf(user.IsActive, UnauthorizedAccessError.Create());

// With a value
Result<int> result = Result<int>.SuccessIf(age >= 18, value: age, errorMessage: "Must be 18+");

OnSuccess / OnFailure

Fluent side-effects for logging, telemetry, or caching without breaking the chain:

var result = GetUser(42)
    .OnSuccess(user => logger.LogInformation("Loaded user {Id}", user.Id))
    .OnFailure(error => logger.LogError(error, "User lookup failed"));

Contributing

1. Fork the repository
2. Create your feature branch from main (release/your-feature for new features, fix/your-fix for patches)
3. Run the full check before submitting: make check
4. Open a Pull Request against main

Development Commands

make build          # Build the solution
make test           # Run all tests
make lint           # Check code style
make branch-lint    # Validate branch name
make commit-lint    # Validate commit messages
make check          # Full pre-PR validation (build + lint + branch + commits + tests)
make pack           # Create NuGet package locally

License

This project is licensed under the MIT License.