DeclaredChain

Reads a train's declared chain without resolving or running any junction. This is what the host's startup chain check calls for every registered train; you can call it yourself, for example in a test that asserts a train's route.

Signatures

// Train<TInput, TReturn>
public ChainRecorder DeclaredChain()
public bool IsDeclaringChain { get; }

DeclaredChain() runs Junctions() against a monad that records each chain call's type arguments instead of executing it, and returns the recording. Nothing is resolved from the container and no junction runs, including on a monad created through NewMonad() while declaring. NewMonad() is the seam ServiceTrain uses to supply its container, not an extension point: it is protected because the published Trax.Effect overrides it, and hidden from completion.

IsDeclaringChain is true while the chain is being read. Per-execution accessors check it: ServiceTrain.TrainInput and TrainOutput throw ChainDeclarationException while it is true.

Throws: ChainDeclarationException when the train reads per-execution state while declaring, and whatever else Junctions() itself throws while it is read (a train that never overrides it throws NotImplementedException, for instance). A declaration that completes but is wrong, such as a body that awaits, returns a result, or starts a second chain in a separate statement, is recorded as a refusal instead.

ChainRecorder

namespace Trax.Core.Monad;
 
public sealed class ChainRecorder
{
    public IReadOnlyList<ChainStep> Steps { get; }
    public IReadOnlyList<string> Refusals { get; }
}

ChainStep and ChainStepKind

public readonly record struct ChainStep(ChainStepKind Kind, Type? Junction, Type? In, Type? Out);
 
public enum ChainStepKind { Chain, IChain, ShortCircuit, Extract, Resolve, Seed }

ChainVerification.Verify

namespace Trax.Core.Monad;
 
public static IReadOnlyList<ChainFault> Verify(
    ChainRecorder chain,
    Type input,
    Type output,
    Func<Type, bool>? availableElsewhere = null
)
 
public static IReadOnlyList<ChainFault> Verify(
    ChainRecorder chain,
    Type input,
    Type output,
    IServiceProviderIsService container
)
 
public readonly record struct ChainFault(int StepIndex, ChainStepKind Kind, Type? Junction, string Reason)
{
    public bool IsRefusal { get; init; }
}

Replays the recording over the types Memory would hold and returns every step that does not line up, plus one fault per refusal. The rules it applies are in Trains & Junctions.

Given the container, it also checks every junction Trax builds from its constructor (Chain<T>() and ShortCircuit<T>()): each constructor argument has to be in Memory by that step, registered in the container, the container itself, or an ILogger<T> an ILoggerFactory in Memory can make. A tuple argument is assembled from Memory only. A junction passed as an instance, or resolved by IChain, is already built and is not checked. The overload without a container leaves constructors unchecked. The host's startup check passes the container, from Trax.Mediator 1.24.0, so a junction whose constructor argument nothing supplies stops the host rather than failing its first run.

Exceptions

Example

[Test]
public void CreateUserTrain_DeclaresAChainThatLinesUp()
{
    var train = new CreateUserTrain();
    var chain = train.DeclaredChain();
 
    chain.Refusals.Should().BeEmpty();
    ChainVerification.Verify(chain, typeof(CreateUserRequest), typeof(User)).Should().BeEmpty();
}

Package

dotnet add package Trax.Core