Explanation

How a chain runs

Source Monad/

A train's route is the chain it declares in Junctions(). Each step reads from Memory, may add to it, and either keeps the train on the right track or switches it to the left. Once on the left track, every later step is skipped and the exception is what the train returns. This page describes how each kind of step behaves; the overloads and exact rules are on the Train Methods pages.

using Trax.Core.Functional;
using Trax.Core.Train;
 
public class CreateUserTrain : Train<CreateUserRequest, User>
{
    protected override Task<Either<Exception, User>> Junctions() =>
        Chain<ValidateEmailJunction>() // throws: the train switches to the left track
            .Chain<CreateUserJunction>() // skipped after a failure
            .Chain<SendEmailJunction>() // skipped after a failure
            .Resolve(); // the exception, or the User in Memory
}

The chain is declared once and read at startup as well as at run time, so it cannot branch on its input: the host's startup check replays it against Memory and refuses a chain whose junction inputs or return type never arrive. A route that does differ per run declares every track and lets a decider pick one.

Chain

Chain<TJunction>() is the ordinary step. It builds the junction, takes its input from Memory, runs it, and stores the output in Memory under the output's type. A junction that throws switches the train to the left track, and the exception passes every later step on its way to the caller.

ShortCircuit

ShortCircuit<TJunction>() runs a junction whose output, when it has one, is the train's answer. If the junction returns a value of the train's return type, that value is captured and Resolve() returns it instead of looking in Memory. If the junction throws, the exception is swallowed and the train stays on the right track: for a short circuit, a failure means "no early answer, keep going". That is the inverse of Chain, on purpose.

using Trax.Core.Functional;
using Trax.Core.Train;
 
public class ProcessOrderTrain : Train<OrderRequest, OrderResult>
{
    protected override Task<Either<Exception, OrderResult>> Junctions() =>
        Chain<ValidateOrderJunction>()
            .ShortCircuit<CheckCacheJunction>() // a cached result, if there is one
            .Chain<CalculatePricingJunction>() // still runs
            .Chain<ProcessPaymentJunction>() // still runs
            .Chain<SaveOrderJunction>()
            .Resolve();
}

The steps after a successful short circuit still run. The captured value changes only what Resolve() returns, and a later junction that fails puts the train on the left track, where Resolve() returns that failure rather than the captured value. Nothing in a chain skips the remaining junctions and still returns the short-circuit value, because a chain cannot branch on what happened at run time (Trax.Docs/adr/0016). A junction after a ShortCircuit that should not repeat work decides that itself, from what it is given.

It suits caching, feature flags that return a default, and preconditions that are already met.

Extract

Extract<TSource, TTarget>() finds the TSource in Memory, reads its first public instance property, then field, of type TTarget, and stores that value in Memory under TTarget. It saves writing a junction whose only job is to read a property:

using Trax.Core.Functional;
using Trax.Core.Train;
 
public class VerifyUserEmailTrain : Train<UserId, Unit>
{
    protected override Task<Either<Exception, Unit>> Junctions() =>
        Chain<LoadUserJunction>() // User in Memory
            .Extract<User, EmailAddress>() // User.Email in Memory as EmailAddress
            .Chain<VerifyEmailAddressJunction>()
            .Resolve();
}

A missing TSource, or no non-null member of type TTarget, switches the train to the left track. Anything beyond a property read (a null check, a transformation, validation) belongs in a junction.

AddServices

AddServices(...) stores the instances it is given in Memory, each under its type argument, bypassing the container. Later junctions take them as input, or as constructor arguments, as they would anything else in Memory:

using Trax.Core.Functional;
using Trax.Core.Train;
 
public class RegisterUserTrain(IValidator validator, INotifier notifier)
    : Train<CreateUserRequest, User>
{
    protected override Task<Either<Exception, User>> Junctions() =>
        AddServices(validator, notifier)
            .Chain<ValidateJunction>() // takes IValidator from Memory
            .Chain<CreateUserJunction>()
            .Chain<NotifyJunction>() // takes INotifier from Memory
            .Resolve();
}

It is for instances made per run or kept outside the container; ordinary dependencies are constructor injection on the junction. The type arguments must be interfaces, and the instances must already exist when Junctions() runs, since the chain is also read at startup. Setup that needs async work, a try/catch, or a nested train's result belongs in a junction at the head of the chain, whose output lands in Memory for the junctions after it.

Resolve

Resolve() ends the chain. It returns, in order: the exception if the train is on the left track, the short-circuit value if one was captured, or the train's return type from Memory. A return type that never reached Memory is a failure, and the startup check refuses such a chain before the host serves traffic.

On a train whose return type is already in Memory because it is the input type or Unit, the chain names no junctions and the whole declaration is Task.FromResult(Resolve()): the train's own Resolve() is synchronous, so it is wrapped to match the Task that Junctions() returns.

A Resolve(value) overload exists on the chain, but a declared chain that ends with it is refused when the chain is read: it states the result instead of declaring the junction that produces it. To merge a nested train's result into the output, the junction that calls the nested train returns the merged value.

Other steps

Decide, Switch, Gate and Scale route a run down one of several declared tracks. Parallel runs a fixed set of named branches side by side, each on its own copy of Memory, then joins them. Checkpoint stores a state so that a later run of the same input resumes after it.

SDK Reference

Junctions | Chain | ShortCircuit | Extract | AddServices | Resolve