Either and Unit
Source Functional/, FunctionalExtensions.cs
Trax.Core borrows two types from functional programming and ships its own copies of them in the
Trax.Core.Functional namespace: Either and Unit. You do not need a functional programming
background to use either. They exist because a chain of junctions needs a way to carry "this
failed" next to "this is the value", and a way to say "this junction returns nothing" in a generic
type argument.
How the chain uses them, the two tracks a train runs on, is explained in The Railway. This page is about the types themselves.
Either
Either<TLeft, TRight> holds one of two values. By convention Left is the failure and Right the
success, and a train's result is an Either<Exception, TOut>. That is the type Junctions()
returns:
using Trax.Core.Functional;
using Trax.Core.Train;
public class CreateUserTrain : Train<CreateUserRequest, User>
{
protected override Task<Either<Exception, User>> Junctions() =>
Chain<ValidateEmailJunction>().Chain<CreateUserJunction>().Resolve();
}Inside Junctions() the Either is invisible. You name junctions; if one throws, the chain stops
and the result is Left(exception), and if all of them succeed it is Right(result). Making the
failure a value rather than an exception in flight is what lets the chain skip the remaining
junctions without a try around each one, and lets a hook or a host record the failure without
catching it.
The caller usually never sees it either. Run unwraps the Either: it returns the value on the
right track and rethrows the exception on the left, which is the .NET convention a caller expects.
RunEither, on the train class rather than the route interface, hands it back as it is:
using Trax.Core.Functional;
public static class CreateUser
{
public static async Task<string> Describe(CreateUserTrain train, CreateUserRequest request)
{
Either<Exception, User> result = await train.RunEither(request);
return result.Match(
Left: exception => $"Failed: {exception.Message}",
Right: user => $"Created: {user.Email}"
);
}
}RunEither lets nothing escape, a cancellation included, which is why a caller of it checks a
Left for OperationCanceledException before treating it as a business failure. See
Handle errors in trains.
A default(Either) holds neither value. IsLeft and IsRight are both false for it, and Match
throws unless you pass the optional Bottom function.
Unit
Unit is a type with one value, Unit.Default. C# cannot write Task<void> or use void as a
generic argument, so a junction or a train that produces nothing says so with Unit:
using Trax.Core.Functional;
using Trax.Core.Junction;
public class ValidateEmailJunction : Junction<CreateUserRequest, Unit>
{
public override Task<Unit> Run(CreateUserRequest input)
{
if (!input.Email.Contains('@'))
throw new ArgumentException("Invalid email", nameof(input));
return Task.FromResult(Unit.Default);
}
}A junction that returns Unit did its work and added nothing to the train's memory. The next
junction takes its input from what is already there, here the CreateUserRequest the train started
with.
Null assertion helpers
Trax.Core.Extensions has two extension methods that throw an InvalidOperationException naming
the expression that was null, in place of a ! that would let the null through to fail later and
further away:
user.Profile.AssertLoaded(); // "user.Profile has not been loaded"
orders.AssertEachLoaded(order => order.Customer); // names the collection and the selectorBoth read the expression with [CallerArgumentExpression], so the message says what was missing
without a debugger.
Effects
Database writes, logging and the other side effects of a run are not part of these types. They are the subject of Effects.
SDK Reference
Junctions | Chain | Resolve | Run / RunEither