FluentUnions.AwesomeAssertions 2.1.0

FluentUnions

Comprehensive discriminated unions for C#/.NET: Result<T> and Result for explicit error handling, Option<T> for null safety. Features fluent API, static analyzers, and zero-allocation performance.

Table of contents

• Why FluentUnions
• Install
• Quick tour
• Core types
• Documentation
• Links

Why FluentUnions

• True discriminated unions: Type-safe Result<T>, Result, and Option<T> with exhaustive matching
• Explicit error handling: No hidden exceptions for expected failures
• Null safety: Option<T> eliminates null reference exceptions
• Fluent operations: Chain with Map, Bind, Match, Ensure, and more
• Zero allocations: Struct-based abstractions, optimized for performance
• Static analysis: Roslyn analyzers prevent common mistakes at compile-time
• Rich error types: Built-in validation, conflict, authentication errors with metadata
• Error accumulation: Collect all errors or fail-fast strategies
• AOT-friendly: Full AOT compatibility, no runtime code emission

Install

dotnet add package FluentUnions

For test assertions with AwesomeAssertions:

dotnet add package FluentUnions.AwesomeAssertions

Quick tour

Result - Error handling

// Methods that can fail return Result<T>
public Result<User> GetUser(int id)
{
    if (id <= 0)
        return new ValidationError("Invalid user ID");

    var user = database.FindUser(id);
    if (user == null)
        return new NotFoundError($"User {id} not found");

    return user; // Implicit conversion from T to Result<T>
}

// Chain operations
var greeting = GetUser(123)
    .Map(user => user.Name)
    .Match(
        success: name => $"Hello, {name}!",
        failure: error => $"Error: {error.Message}"
    );

Option - Null safety

// Replace nulls with Option<T>
public Option<string> GetMiddleName(User user)
{
    return user.MiddleName.AsOption(); // null becomes None
}

// Safe chaining
var displayName = GetUser(123)
    .ToOption()
    .Bind(user => GetMiddleName(user))
    .Map(name => name.ToUpper())
    .Match(
        some: name => name,
        none: () => "N/A"
    );

Validation with built-in methods

// Fluent validation
public Result<string> ValidateEmail(string email)
{
    return Result.For(email)
        .Ensure.NotEmpty()
        .Ensure.Matches(@"^[^@]+@[^@]+\.[^@]+$")
        .Ensure.ShorterThan(255);
}

// Accumulate all errors
public Result<User> CreateUser(string email, string password, int age)
{
    return Result.BindAllAppend(
        Result.For(email)
            .Ensure.NotEmpty()
            .Ensure.Matches(@"^[^@]+@[^@]+\.[^@]+$"),
        Result.For(password)
            .Ensure.LongerThanOrEqualTo(8)
            .Ensure.Matches(@"[A-Z]", "Must contain uppercase"),
        Result.For(age)
            .Ensure.GreaterThanOrEqualTo(18))
        .Map((email, password, age) => new User(email, password, age));
}

Static analyzers

Roslyn analyzers catch mistakes at compile-time:

// ⚠️ FU0001: Accessing Value without checking IsSome
Option<int> option = GetOption();
var value = option.Value; // Analyzer warning!

// ✅ Safe access
if (option.IsSome)
{
    var value = option.Value; // OK
}

// ⚠️ FU0101: Accessing Value without checking IsSuccess
Result<string> result = GetResult();
var data = result.Value; // Analyzer warning!

// ✅ Better: Use Match
var data = result.Match(
    success: value => value,
    failure: error => "default"
);

Core types

Discriminated unions

• Result<T>: Success(T value) | Failure(Error error)
• Result: Success | Failure(Error error)
• Option<T>: Some(T value) | None

Error types

• ValidationError - Input validation failures
• NotFoundError - Resource not found
• ConflictError - Business rule conflicts
• AuthenticationError - Authentication failures
• AuthorizationError - Authorization failures
• CompositeError - Multiple errors combined
• ErrorWithMetadata - Errors with additional context

Error strategies

• Short-circuit: Stop at first error (Bind, Ensure)
• Accumulate: Collect all errors (BindAll, EnsureAll)

Documentation

This README stays intentionally brief. Full documentation lives in the docs:

• Index: docs index
• Guide: docs/guide.md
• API reference: docs/reference.md
• Option type: docs/option/
• Result types: docs/result/ and docs/result-t/
• Error types: docs/errors/
• Examples: docs/examples.md
• Analyzers: docs/analyzers.md
• Best practices: docs/best-practices.md
• Contributing: docs/contributing.md

Links

• NuGet: FluentUnions on NuGet
• Repository: github.com/ymjaber/fluent-unions
• License: MIT (LICENSE)