Trax.Effect.Data.Sqlite 1.57.2

Trax.Effect

The effect layer for Trax.Core. A Trax.Core Train runs a chain of junctions; a Trax.Effect ServiceTrain does the same inside dependency injection and records every run: a Metadata row with its state, timing, input, output and failure, persisted by whichever data provider you install. Optional provider packages add parameter capture, per-junction logging and progress, cross-process event broadcasting, and a persisted state-machine engine.

Full documentation: traxsharp.net/docs. Start with Getting Started and Effect Providers.

The Trax Stack

Trax is a layered framework split across several repos. You can stop at whatever layer solves your problem. You are here: Trax.Effect.

What This Does

Trax.Core gives you Train<TIn, TOut>: a locomotive that carries cargo through a sequence of stops. That's enough for pure logic, but production services need to know what ran, when it departed, whether it arrived, what it was carrying, and what went wrong if it derailed.

Trax.Effect adds the ServiceTrain<TIn, TOut> base class, a full commercial train service that wraps every journey with:

• Journey logging: a persistent metadata record for each run (state, timing, cargo in, cargo out, derailment details)
• Station services: pluggable effect providers that fire during execution (data persistence, logging, parameter serialization, progress tracking)
• DI integration: stops are resolved from IServiceProvider, so you get constructor injection out of the box

Installation

dotnet add package Trax.Effect

Trax.Effect is the one package every setup needs. The provider packages below pair with it, and each adds an extension method to the AddEffects builder (the broadcaster transports add theirs to the UseBroadcaster builder). Install a data provider to persist runs:

dotnet add package Trax.Effect.Data.Postgres   # UsePostgres(connectionString), production
dotnet add package Trax.Effect.Data.Sqlite     # UseSqlite(connectionString), single server
dotnet add package Trax.Effect.Data.InMemory   # UseInMemory(), tests and prototyping

Then any of the optional providers:

You rarely install Trax.Effect.Data directly: every data provider depends on it.

Setup

Register station services in your IServiceCollection:

builder.Services.AddTrax(trax =>
    trax.AddEffects(effects =>
        effects.UsePostgres(connectionString).SaveTrainParameters().AddJunctionLogger(serializeJunctionData: true).AddJunctionProgress()
    )
);

For development or tests, swap Postgres for in-memory:

builder.Services.AddTrax(trax =>
    trax.AddEffects(effects =>
        effects.UseInMemory().AddJson()
    )
);

Usage

Inherit from ServiceTrain instead of Train:

public interface ICreateUserTrain : IServiceTrain<CreateUserRequest, User> { }

public class CreateUserTrain : ServiceTrain<CreateUserRequest, User>, ICreateUserTrain
{
    protected override Task<Either<Exception, User>> Junctions()
        => Chain<ValidateEmailJunction>()
            .Chain<CreateUserInDatabaseJunction>()
            .Chain<SendWelcomeEmailJunction>()
            .Resolve();
}

The chain syntax is identical to Train. The difference is what happens around it. ServiceTrain automatically opens a journey log when the train departs, updates it when it arrives, persists effect data at each station, and records the derailment details if any stop fails.

Junctions work the same way, with full DI:

public class CreateUserInDatabaseJunction(AppDbContext db) : Junction<CreateUserRequest, User>
{
    public override async Task<User> Run(CreateUserRequest input)
    {
        var user = new User { Email = input.Email, Name = input.Name };
        db.Users.Add(user);
        await db.SaveChangesAsync();
        return user;
    }
}

Journey Lifecycle

Every ServiceTrain journey transitions through:

Pending → InProgress → Completed
                     → Failed
                     → Cancelled

Think of it as: the train is boarding (Pending), in transit (InProgress), and then either arrives (Completed), derails (Failed), or is pulled from service (Cancelled). These states are persisted in the journey log and queryable through the data layer.

Station Services

Station services compose, so enable as many as you need:

effects
    .UsePostgres(connectionString)
    .AddJson()
    .SaveTrainParameters()
    .AddJunctionLogger(serializeJunctionData: true)
    .AddJunctionProgress();

Every method is documented under Configuration.

DI Registration Helpers

Register your trains as scoped services with proper interface mapping:

builder.Services.AddScopedTraxRoute<ICreateUserTrain, CreateUserTrain>();
builder.Services.AddTransientTraxRoute<IProcessOrderTrain, ProcessOrderTrain>();

Or use AddMediator (from Trax.Mediator) to auto-register all trains in an assembly.

Next Layer

When you need decoupled dispatch (callers don't know which train handles a request), move up to Trax.Mediator.

License

MIT

Trademark & Brand Notice

Trax is an open-source .NET framework provided by TraxSharp. This project is an independent community effort and is not affiliated with, sponsored by, or endorsed by the Utah Transit Authority, Trax Retail, or any other entity using the "Trax" name in other industries.