Toarnbeike.Unions 1.3.0

Toarnbeike.Unions

This package provides immutable, allocation-free union types for C#, inspired by functional programming and discriminated unions, while remaining idiomatic to the .NET ecosystem.

A Union<T1, ..., Tn> represents a value that can be exactly one of several possible types at runtime, without relying on inheritance, nulls, or exceptions for control flow. This is particularly useful for modeling domain states and workflows where a value can be in one of a fixed set of alternatives.

Features

• Generated Union types with 2 to 8 generic type parameters (expandable via included generators)
• Explicit construction and state inspection
• Rich functional extensions (Map, Bind, Match, Switch, Tap)
• Async support for all extensions
• Collection extensions for partitioning
• Test extensions for fluent assertions
• Unit tested with high code coverage

Contents

1. Quick start
2. Core concepts
3. Extensions
4. Collections
5. Test extensions
6. Design principles
7. Comparison: Why Unions?
8. When not to use Unions?
9. Conclusion

Quick start

This example demonstrates the most common workflow when using unions: construction, transformation, and consumption.

using Toarnbeike.Unions.Generic;
using Toarnbeike.Unions.Generic.Extensions;

Union<int, string> value = Union<int, string>.FromT1(10);

// Transform the value
var transformed = value
    .Map(
        t1 => t1 + 1,
        t2 => t2.Length
    );

// Consume the union
var result = transformed.Match(
    t1 => $"Int: {t1}",
    t2 => $"String length: {t2}"
);

Console.WriteLine(result); // Output: Int: 11

Key properties of this workflow:

• The union is always in exactly one state
• All transformations are explicit
• All states must be handled exhaustively
• No nulls, casts, or exceptions are required

Core concepts

What is a Union?

A union represents one of several possible states, each carrying a value of a different type.

Union<int, string> value = Union<int, string>.FromT1(42);
// or
Union<int, string>.FromT2("hello");

At any point in time, a union is in exactly one state.

Construction

Unions are constructed via explicit static factory methods:

var u1 = Union<int, string>.FromT1(10);
var u2 = Union<int, string>.FromT2("text");

This ensures:

• No ambiguous states
• No implicit conversions
• No null-based discrimination

State Inspection

Each union exposes state checks:

if (union.IsT1) { ... }
if (union.IsT2) { ... }

Safe extraction using TryGet is available; TryGet never throws and does not allocate.

if (union.TryGetT1(out T1 value)) { ... }

Extensions

The Toarnbeike.Unions.Extensions namespace contains rich extension methods for all Union<T1,...,Tn>.

All extensions include async overloads and Task<Union<...>> variants.

For information per method, see the Extensions README.

Collections

The Toarnbeike.Unions.Collections namespace contains extension methods to work with IEnumerable<Union<...>>.

This adds the possibility to split a collection of unions in separate collections of the different types present:

SelectTi

Select Ti extracts all values of type Ti from a collection of unions.

private IEnumerable<Union<U1,U2>> CreateMixedCollection()
{
    yield return Union<U1,U2>.FromT1(new U1(1));
    yield return Union<U1,U2>.FromT1(new U1(2));
    yield return Union<U1,U2>.FromT2(new U2(2));
    yield return Union<U1,U2>.FromT2(new U2(3));
}

var t1Values = CreateMixedCollection().SelectT1().ToList();

t1Values.Count.ShouldBe(2);
t1Values[0].Value.ShouldBe(1);
t1Values[1].Value.ShouldBe(2);

Partition

Partition splits a collection of unions into separate collections for each type. This is useful when you need to process each union case in bulk.

var source = CreateMixedCollection();

var (t1Values, t2Values) = source.Partition();

t1Values.Count.ShouldBe(2);
t2Values.Count.ShouldBe(2);

Test extensions

The Toarnbeike.Unions.TestExtensions namespace contains extensions for asserting on Unions in tests (framework-agnostic).

Per arity the following methods are available:

Usage

var t1 = union.ShouldBeT1();
var actual = union.ShouldBeT1(expectedValue);

Design principles and best practices

This library intentionally favors:

• Explicit over implicit
• Composition over convenience
• Minimal primitives over combinator explosion
• Functional correctness over syntactic shortcuts

Notably out of scope:

• Implicit conversions (types might not be unique within a union)
• Null-based semantics (use Options)

Comparison: Why Unions?

For a more detailed comparison, see the Comparison document.

When not to use Unions?

Unions are a powerful modeling tool, but they are intentionally not universal.

Conclusion

Union<T1, ..., Tn> enables:

• Strongly typed alternatives
• Exhaustive handling
• Functional transformations
• Explicit side effects
• Predictable async composition

All while remaining:

• Immutable
• Allocation-efficient
• Generator-friendly
• Testable

This makes Unions suitable for domain modeling, state machines, and functional workflows in modern C#.