AxisResult 2.2.0

AxisResult — Documentation

🌐 Português (documentação navegável)

Railway-Oriented Programming for C# — a zero-dependency Result monad with full async/ValueTask support, typed error categories and monadic composition (Then / Map / Zip).

public Task<AxisResult<AddCellphoneResponse>> HandleAsync(AddCellphoneCommand cmd)
    => personFactory.GetByIdAsync(cmd.PersonId)
        .ThenAsync(person => cellphoneMediator.AddAsync(new() { Number = cmd.Number }))
        .ThenAsync(response => response.AddCellphoneAsync(cmd.CellphoneId))
        .ThenAsync(_ => unitOfWork.SaveChangesAsync())
        .MapAsync(_ => new AddCellphoneResponse { CellphoneId = cmd.CellphoneId });

Use this page as a map: read the trunk below (~5 min) and jump straight to the detail of the group you need — without reading hundreds of lines.

The trunk (read first)

Railway in 60 seconds

Imagine your code as a railway with two rails:

Success ━━━━━●━━━━━━━━━━●━━━━━━━━━━●━━━━▶  result
             │          │          │
          validate     fetch      save
             │          │          │
Failure ━━━━━╋━━━━━━━━━━╋━━━━━━━━━━╋━━━━▶  errors

Each operation either succeeds and stays on the top rail, or fails and drops to the bottom one — skipping everything else. No try/catch, no if (x == null), no mid-handler return. → Railway-Oriented Programming

AxisResult vs AxisResult<T> — "no data" and "with data"

• AxisResult — the outcome of an operation that produces no value: only whether it worked matters (save, delete, validate, verify a password).
• AxisResult<T> — carries a value along the success rail (fetch an entity, compute a total). .Value throws on a failure → prefer the safe deconstruction or Match.
• Moving between the two: ToAxisResult discards the value; WithValueAsync promotes an AxisResult to AxisResult<T>.

Creating results

AxisResult         ok    = AxisResult.Ok();
AxisResult<int>    typed = AxisResult.Ok(42);
AxisResult<int>    fail  = AxisError.BusinessRule("INSUFFICIENT_STOCK"); // AxisError → failure (implicit)
AxisResult<string> name  = "John";                                       // value → Ok (implicit)
AxisResult<int>    parse = AxisResult.Try(() => int.Parse(input));        // exception → AxisResult, only at the edge
AxisResult<string> rop   = user.Email.Rop();                               // value → Ok, fluent: starts the ROP flow

Error handling

An error is a value (AxisError = Code + Type), not an exception. The 12 categories map to HTTP status codes, and IsTransient/result.IsTransientFailure enable retry. → Errors and types

Task vs ValueTask

When in doubt, use Task. ValueTask only on hot paths that complete synchronously. → Task vs ValueTask

Installation

dotnet add package AxisResult

→ Full guide: Getting started

The map (jump to what you need)

Start here: Getting started · Railway-Oriented Programming · Why AxisResult?

Fundamentals: Errors and types · Task vs ValueTask · Exceptions at the boundary

Reference & extras: API reference · LINQ query syntax · Ergonomics

Design principles

1. Errors are values, not exceptions. An operation that can fail says so in its return type.
2. The type system is the documentation. Task<AxisResult<User>> already tells you everything that can happen.
3. Composition over ceremony. Small, focused operations that compose.
4. Fail fast, recover deliberately. Errors propagate on their own; recovery is always explicit.
5. Exceptions at the boundary, results everywhere else. AxisResult.Try() at infrastructure edges; above that, exception-free.

License

Apache 2.0