RA.Utilities.Core 10.0.0

RA.Utilities.Core

RA.Utilities.Core is a lightweight .NET library designed to enhance error handling by providing a functional Result type. It helps you write cleaner, more predictable, and more robust code by avoiding exceptions for expected operational failures.

🚀 Getting Started

Install the package via the .NET CLI:

dotnet add package RA.Utilities.Core

✨ Key Features

Functional Result and Result<T> Types

The library provides two core types for handling outcomes:

• Result: For operations that succeed or fail without returning a value (e.g., saving to a database).
• Result<T>: For operations that return a value on success.

These types make the intent of your code explicit by forcing you to handle both success and failure paths, preventing unhandled errors.

public Result<User> FindUser(int userId)
{
    var user = _userRepository.GetById(userId);

    if (user is null)
    {
        return new NotFoundException("User not found."); // Implicit conversion to Failure
    }

    return user; // Implicit conversion to Success
}

The Match method ensures that both success and failure cases are handled:

var result = FindUser(123);

return result.Match(
    onSuccess: user => Ok(user),
    onFailure: exception => NotFound(exception.Message)
);

Railway-Oriented Programming Extensions

Chain multiple fallible operations together using a fluent, readable API. The chain short-circuits on the first failure, passing the error down the line.

• Map(): Transforms the value inside a successful Result<T>.
• Bind(): Chains another function that returns a Result.
• OnSuccess() / OnFailure(): Executes side-effects like logging without altering the result.

public Result<string> GetAdminEmail(int userId)
{
    return FindUser(userId)
        .Bind(user => EnsureIsAdmin(user))
        .Map(adminUser => adminUser.Email)
        .OnSuccess(email => _logger.LogInformation("Admin email found for user {UserId}", userId))
        .OnFailure(ex => _logger.LogError(ex, "Failed to get admin email for user {UserId}", userId));
}

Asynchronous Support

All extension methods have async counterparts (MapAsync, BindAsync, etc.) to integrate seamlessly into asynchronous workflows.

var result = await FindUserAsync(userId)
    .BindAsync(user => ValidatePermissionsAsync(user));

Additional documentation

For more information on how this package fits into the larger RA.Utilities ecosystem, please see the main repository documentation.