Trains (Trax.Core)
Source Trax.Core/
A piece of business work, such as placing an order, is rarely one call. It prices a cart, reserves
stock, takes a payment and confirms, and when the payment fails the steps after it must not run.
Written by hand, that is a method full of if checks between service calls. In Trax it is a
train: a class that lists its steps (junctions) in order, hands each step's output to the
next by its type, and stops at the first one that throws.
Everything else in Trax runs, records, schedules or serves a train, so this is the place to start.
What Trax does shows how the rest attaches to it. This page covers
Trax.Core, the package with the train itself: no database, no DI container, no infrastructure.
dotnet add package Trax.CoreWhat You Get
- Trains: typed pipelines that carry data through a sequence of junctions
- Junctions: single-responsibility units of work with typed input/output
- Memory: a type-keyed store that wires junction outputs to junction inputs automatically
- Railway error propagation: if any junction fails, the train switches to the left track and skips the rest
- Declared chains: a chain declared in
Junctions()is readable without running it. Trax.Mediator's startup check (registered byAddMediator) uses that to refuse to start a host whose chains cannot run - Decisions: a chain can declare several tracks and let a decider (a typed decision model, a rule table, a test double) choose one per run, with every track verified at startup. See Decisions
- IDE extensions: inlay hints showing cargo types at each junction
The Railway
A train never leaves the rails. It always reaches a destination. Your code runs on two tracks: right and left. The train stays on the right track as long as every junction succeeds. If any junction fails, the train switches to the left track and passes through every remaining junction without executing them.
Right Track: Input -> [Junction 1] -> [Junction 2] -> [Junction 3] -> Output
|
Left Track: Exception -> [Skip] -> [Skip] -> ExceptionTrax.Core represents this with its own Either<Exception, T>, in the Trax.Core.Functional namespace. A value is either Left (an exception on the left track) or Right (successful delivery on the right track):
using Trax.Core.Functional;
using Trax.Core.Train;
public class CreateUserTrain : Train<CreateUserRequest, User>
{
protected override Task<Either<Exception, User>> Junctions() =>
Chain<ValidateUserJunction>() // If this fails, skip remaining junctions
.Chain<CreateUserJunction>() // Only runs if validation succeeded
.Chain<SendEmailJunction>().Resolve(); // Only runs if creation succeeded
}If ValidateUserJunction throws, the train switches to the left track immediately and returns Left(exception). You don't write any error-checking code. The railway handles it.
Running a Train
var train = new CreateUserTrain();
var input = new CreateUserRequest("ada@example.com");
// Run and unwrap (throws on failure)
var user = await train.Run(input);
// Run and inspect both tracks
var result = await train.RunEither(input);
result.Match(
Left: ex => Console.WriteLine($"Failed: {ex.Message}"),
Right: created => Console.WriteLine($"Created: {created.Email}")
);When to Use Core Alone
- Validation pipelines, data transformations, CLI tools
- Anywhere you'd write nested try/catch chains
- Lightweight junction composition without infrastructure overhead
- Prototyping trains before adding persistence
When you need execution logging, DI, or persistent metadata, add Trax.Effect.