Download ZIP

result-with-error-hierarchy.md · 4.4 KiB · Markdown Raw

# Result pattern with a closed error hierarchy (C#) A way to make a method's failure modes part of its return type without OneOf's positional `Tn` tedium or a flat opaque `Error` blob. Emulates a discriminated union using a sealed record hierarchy. ## What to call it There is no single name. It is three named things stapled together: - **Container:** the Result pattern (`Result<T, E>`). - **Error model:** a discriminated union (a.k.a. sum type, tagged union), *emulated* in C# with a closed/sealed record hierarchy because C# has no native DU. - **Consumption:** pattern matching via a switch expression. **Instruction that reliably produces it** (to a human or an agent): > Use the Result pattern with a closed (sealed record) error hierarchy as a > discriminated union, consumed via switch expression pattern matching. **Shortcut for people who know the languages:** "like Rust's `Result<T, E>` where `E` is an enum." F#/FP people will also recognise it as `Result` with a DU error, or as `Either` (Left = error, Right = success) if you want to start a monad conversation you cannot stop. > [!WARNING] > Say **closed** or **sealed** out loud. Drop the word and you get an open > inheritance tree with virtual methods and probably a visitor pattern, which is > the 2005 OOP answer to the same problem and strictly worse here. The point is > that the set is closed so the switch can be treated as exhaustive. ## The error hierarchy `abstract record` base, `sealed record` cases. This is the idiomatic C# way to fake a sum type. ```csharp public abstract record Error(string Code, string Message); public sealed record NotFound(string Code, string Message) : Error(Code, Message); public sealed record Validation(string Code, string Message, IReadOnlyList<string> Fields) : Error(Code, Message); public sealed record Conflict(string Code, string Message) : Error(Code, Message); public sealed record Forbidden(string Code, string Message) : Error(Code, Message); // ... thirty of these if you must ``` ## The signature stays boring ```csharp public Result<User, Error> GetUser(int id) ``` Generic over the *base*. Adding a thirty-first error subtype does not change this signature and does not touch any `Match`/`switch` that used a `_` fallthrough. ## Consuming it Handle what you care about, let the rest fall through. This is the "may or may not want to handle differently" case. ```csharp return result.Match( user => Ok(user), error => error switch { NotFound => NotFound(), Forbidden => Forbid(), Validation v => BadRequest(v.Fields), _ => Problem() // everything else bubbles to a 500 }); ``` ## Why this over the alternatives | Concern | OneOf | Flat `Result<T>` | This | |---|---|---|---| | Self-documenting signature | Yes (until ~30 arms) | No, opaque | Partly: base type is the catalogue | | Positional `Tn` tedium | Yes, error-prone | n/a | None | | Adding an error variant | Breaks every caller | Free | Free (with `_` fallthrough) | | Forced exhaustive handling | Yes | No | Opt-in via `_` discard | | Discoverability of error set | In the signature | Nowhere | "Find All Implementations" on `Error` | The tax: the signature alone no longer enumerates the error set, so finding the full catalogue means navigating to the base type rather than reading the return type. That is the price of not forcing every caller to acknowledge all thirty cases. This scales; OneOf does not. ## When NOT to reach for it - **Genuinely exceptional failures** (DB connection died, missing config, a broken invariant): throw. Do not `Result`-wrap a dropped socket. - **Expected, frequent outcomes on a warm path:** prefer this over exceptions. Exceptions are expensive (stack capture, low microseconds per throw), so routing "validation failed" through the panic channel when it fires on 15% of requests is a smell. - **Not-found that carries no substructure:** `User?` and a plain null is fine. Only reach for a `NotFound` record when you need more than the single bit "absent", e.g. to distinguish *not-found* from *exists-but-forbidden* (404 vs 403, or a deliberate 404 to avoid leaking existence). ## If you want exhaustiveness back There is no compiler-enforced exhaustive switch over a sealed hierarchy today; the `_` arm is doing the work. Native discriminated unions would fix this (a real checked switch, no positional `Tn`), but that feature has been "imminent" for years. Plan as though it is not here.

Result pattern with a closed error hierarchy (C#)

A way to make a method's failure modes part of its return type without OneOf's positional Tn tedium or a flat opaque Error blob. Emulates a discriminated union using a sealed record hierarchy.

What to call it

There is no single name. It is three named things stapled together:

Container: the Result pattern (Result<T, E>).
Error model: a discriminated union (a.k.a. sum type, tagged union), emulated in C# with a closed/sealed record hierarchy because C# has no native DU.
Consumption: pattern matching via a switch expression.

Instruction that reliably produces it (to a human or an agent):

Use the Result pattern with a closed (sealed record) error hierarchy as a discriminated union, consumed via switch expression pattern matching.

Shortcut for people who know the languages: "like Rust's Result<T, E> where E is an enum." F#/FP people will also recognise it as Result with a DU error, or as Either (Left = error, Right = success) if you want to start a monad conversation you cannot stop.

[!WARNING] Say closed or sealed out loud. Drop the word and you get an open inheritance tree with virtual methods and probably a visitor pattern, which is the 2005 OOP answer to the same problem and strictly worse here. The point is that the set is closed so the switch can be treated as exhaustive.

The error hierarchy

abstract record base, sealed record cases. This is the idiomatic C# way to fake a sum type.

public abstract record Error(string Code, string Message);

public sealed record NotFound(string Code, string Message) : Error(Code, Message);
public sealed record Validation(string Code, string Message, IReadOnlyList<string> Fields) : Error(Code, Message);
public sealed record Conflict(string Code, string Message) : Error(Code, Message);
public sealed record Forbidden(string Code, string Message) : Error(Code, Message);
// ... thirty of these if you must

The signature stays boring

public Result<User, Error> GetUser(int id)

Generic over the base. Adding a thirty-first error subtype does not change this signature and does not touch any Match/switch that used a _ fallthrough.

Consuming it

Handle what you care about, let the rest fall through. This is the "may or may not want to handle differently" case.

return result.Match(
    user  => Ok(user),
    error => error switch
    {
        NotFound     => NotFound(),
        Forbidden    => Forbid(),
        Validation v => BadRequest(v.Fields),
        _            => Problem()   // everything else bubbles to a 500
    });

Why this over the alternatives

Concern	OneOf	Flat `Result<T>`	This
Self-documenting signature	Yes (until ~30 arms)	No, opaque	Partly: base type is the catalogue
Positional `Tn` tedium	Yes, error-prone	n/a	None
Adding an error variant	Breaks every caller	Free	Free (with `_` fallthrough)
Forced exhaustive handling	Yes	No	Opt-in via `_` discard
Discoverability of error set	In the signature	Nowhere	"Find All Implementations" on `Error`

The tax: the signature alone no longer enumerates the error set, so finding the full catalogue means navigating to the base type rather than reading the return type. That is the price of not forcing every caller to acknowledge all thirty cases. This scales; OneOf does not.

When NOT to reach for it

Genuinely exceptional failures (DB connection died, missing config, a broken invariant): throw. Do not Result-wrap a dropped socket.
Expected, frequent outcomes on a warm path: prefer this over exceptions. Exceptions are expensive (stack capture, low microseconds per throw), so routing "validation failed" through the panic channel when it fires on 15% of requests is a smell.
Not-found that carries no substructure: User? and a plain null is fine. Only reach for a NotFound record when you need more than the single bit "absent", e.g. to distinguish not-found from exists-but-forbidden (404 vs 403, or a deliberate 404 to avoid leaking existence).

If you want exhaustiveness back

There is no compiler-enforced exhaustive switch over a sealed hierarchy today; the _ arm is doing the work. Native discriminated unions would fix this (a real checked switch, no positional Tn), but that feature has been "imminent" for years. Plan as though it is not here.