Dunet

Dunet is a simple source generator for discriminated unions in C#.

Install

• NuGet: dotnet add package dunet

Usage

// 1. Import the namespace.
using Dunet;

// 2. Add the `Union` attribute to a partial record.
[Union]
partial record Shape
{
    // 3. Define the union variants as inner partial records.
    partial record Circle(double Radius);
    partial record Rectangle(double Length, double Width);
    partial record Triangle(double Base, double Height);
}

// Optional: statically import the union for more terse code.
using static Shape;

// 4. Use the union variants.
Shape shape = new Rectangle(3, 4);
// Switch expression is checked for exhaustiveness.
var area = shape switch 
{
    Circle(var radius) => 3.14 * radius * radius,
    Rectangle(var length, var width) => length * width,
    Triangle(var @base, var height) => @base * height / 2,
};
Console.WriteLine(area); // "12"

Match Method

A Match method is also provided as a switch expression alternative:

// 1. Import the namespace.
using Dunet;

// 2. Add the `Union` attribute to a partial record.
[Union]
partial record Shape
{
    // 3. Define the union variants as inner partial records.
    partial record Circle(double Radius);
    partial record Rectangle(double Length, double Width);
    partial record Triangle(double Base, double Height);
}

// 4. Use the union variants.
Shape shape = new Shape.Rectangle(3, 4);
var area = shape.Match(
    circle => 3.14 * circle.Radius * circle.Radius,
    rectangle => rectangle.Length * rectangle.Width,
    triangle => triangle.Base * triangle.Height / 2
);
Console.WriteLine(area); // "12"

Generics

Use generics for more advanced union types. For example, an option monad:

// 1. Import the namespace.
using Dunet;
// Optional: statically import the union for more terse code.
using static Option<int>;

// 2. Add the `Union` attribute to a partial record.
// 3. Add one or more type arguments to the union record.
[Union]
partial record Option<T>
{
    partial record Some(T Value);
    partial record None();
}

// 4. Use the union variants.
Option<int> ParseInt(string? value) =>
    int.TryParse(value, out var number)
        ? number
        : new None();

string GetOutput(Option<int> number) =>
    number switch
    {
        Some(var value) => value.ToString(),
        None => "Invalid input!",
    };

var input = Console.ReadLine(); // User inputs "not a number".
var result = ParseInt(input);
var output = GetOutput(result);
Console.WriteLine(output); // "Invalid input!"

input = Console.ReadLine(); // User inputs "12345".
result = ParseInt(input);
output = GetOutput(result);
Console.WriteLine(output); // "12345".

Implicit Conversions

Dunet generates implicit conversions between union variants and the union type if your union meets all of the following conditions:

• The union has no required properties.
• No variant's property is an interface type.
• Each non-empty variant has a single property.
• Each non-empty variant's property is unique within the union.

For example, consider a Result union type that represents success as a double and failure as an Exception:

// 1. Import the namespace.
using Dunet;

// 2. Define a union type with a single unique variant property:
[Union]
partial record Result
{
    partial record Success(double Value);
    partial record Failure(Exception Error);
}

// 3. Return union variants directly.
Result Divide(double numerator, double denominator)
{
    if (denominator is 0d)
    {
        // No need for `new Result.Failure(new InvalidOperationException("..."));`
        return new InvalidOperationException("Cannot divide by zero!");
    }

    // No need for `new Result.Success(...);`
    return numerator / denominator;
}

var result = Divide(42, 0);
var output = result switch
{
    Result.Success(var value) => value.ToString(),
    Result.Failure(var error) => error.Message,
};

Console.WriteLine(output); // "Cannot divide by zero!"

Note: Empty variants are ignored when generating implicit conversions.

Note: T and T? are not considered unique.

Disable Implicit Conversions

If your union meets the requirements to generate implicit conversions but you wish not to generate them, pass EnableImplicitConversions = false to the Union attribute:

[Union(EnableImplicitConversions = false)]
partial record MyUnion
{
    // ...
}

Async Match

Dunet generates a MatchAsync() extension method for all Task<T> and ValueTask<T> where T is a union type. For example:

// Choice.cs

using Dunet;

namespace Core;

// 1. Define a union type within a namespace.
[Union]
partial record Choice
{
    partial record Yes;
    partial record No(string Reason);
}

// Program.cs

using Core;
using static Core.Choice;

// 2. Define async methods like you would for any other type.
static async Task<Choice> AskAsync()
{
    // Simulating network call.
    await Task.Delay(1000);

    // 3. Return unions from async methods like any other type.
    return new No("because I don't wanna!");
}

// 4. Asynchronously match any union `Task` or `ValueTask`.
var response = await AskAsync()
    .MatchAsync(
        yes => "Yes!!!",
        no => $"No, {no.Reason}"
    );

// Prints "No, because I don't wanna!" after 1 second.
Console.WriteLine(response);

Note: MatchAsync() can only be generated for namespaced unions.

Specific Match

Dunet generates specific match methods for each union variant. This is useful when unwrapping a union and you only care about transforming a single variant. For example:

[Union]
partial record Shape
{
    partial record Point(int X, int Y);
    partial record Line(double Length);
    partial record Rectangle(double Length, double Width);
    partial record Sphere(double Radius);
}

public static bool IsZeroDimensional(this Shape shape) =>
    shape.MatchPoint(
        point => true,
        () => false
    );

public static bool IsOneDimensional(this Shape shape) =>
    shape.MatchLine(
        line => true,
        () => false
    );

public static bool IsTwoDimensional(this Shape shape) =>
    shape.MatchRectangle(
        rectangle => true,
        () => false
    );

public static bool IsThreeDimensional(this Shape shape) =>
    shape.MatchSphere(
        sphere => true,
        () => false
    );

Serialization/Deserialization

using Dunet;
using System.Text.Json.Serialization;

// Serialization and deserialization can be enabled with the `JsonDerivedType` attribute.
[Union]
[JsonDerivedType(typeof(Circle), typeDiscriminator: nameof(Circle))]
[JsonDerivedType(typeof(Rectangle), typeDiscriminator: nameof(Rectangle))]
[JsonDerivedType(typeof(Triangle), typeDiscriminator: nameof(Triangle))]
public partial record Shape
{
    public partial record Circle(double Radius);
    public partial record Rectangle(double Length, double Width);
    public partial record Triangle(double Base, double Height);
}

using System.Text.Json;
using static Shape;

var shapes = new Shape[]
{
    new Circle(10),
    new Rectangle(2, 3),
    new Triangle(2, 1)
};

var serialized = JsonSerializer.Serialize(shapes);

// NOTE: The type discriminator must be the first property in each object.
var deserialized = JsonSerializer.Deserialize<Shape[]>(
    //lang=json
    """
    [
        { "$type": "Circle", "radius": 10 },
        { "$type": "Rectangle", "length": 2, "width": 3 },
        { "$type": "Triangle", "base": 2, "height": 1 }
    ]
    """,
    // So we recognize camelCase properties.
    new JsonSerializerOptions() { PropertyNameCaseInsensitive = true }
);

Pretty Print

To control how union variants are printed with their ToString() methods, override and seal the union declaration's ToString() method. For example:

[Union]
public partial record QueryResult<T>
{
    public partial record Ok(T Value);
    public partial record NotFound;
    public partial record Unauthorized;

    public sealed override string ToString() =>
        this switch
        {
            Ok(var value) => value.ToString(),
            NotFound => "Not found.",
            Unauthorized => "Unauthorized access.",
        };
}

Note: You must seal the ToString() override to prevent the compiler from synthesizing a custom ToString() method for each variant.

More info: https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/builtin-types/record#built-in-formatting-for-display

Shared Properties

To create a property shared by all variants, add it to the union declaration. For example, the following code requires all union variants to initialize the StatusCode property. This makes StatusCode available to anyone with a reference to HttpResponse without having to match.

[Union]
public partial record HttpResponse
{
    public partial record Success;
    public partial record Error(string Message);
    // 1. All variants shall have a status code.
    public required int StatusCode { get; init; }
}

using var client = new HttpClient();
var response = await CreateUserAsync(client, "John", "Smith");

// 2. The `StatusCode` property is available at the union level.
var statusCode = response.StatusCode;

public static async Task<HttpResponse> CreateUserAsync(
    HttpClient client, string firstName, string lastName
)
{
    using var response = await client.PostJsonAsync(
        "/users",
        new { firstName, lastName }
    );

    var content = await response.Content.ReadAsStringAsync();

    if (!response.IsSuccessStatusCode)