Stepper.Core 0.0.6

Stepper

Stepper is a state management library derived from classical FRP implementation such as reactive-banana with the idea of TEA (The Elm Architecture) embedded.

Core Concepts

In Functional Reactive Programming (FRP):

• Event represents discrete occurrences over time (TMsg).
• Behavior represents continuous values over time (TModel).

Stepper implements this duality by accumulating discrete messages to transition a model state, isolating asynchronous side effects using declarative commands (TCmd) and an interpreter.

Installation

dotnet add package Stepper.Core

Architecture

1. Messages (TMsg) are received from external sources (e.g., UI events) or the interpreter.
2. The message stream is merged and serialized.
3. The state transitions are processed sequentially via the Update function in Transition.
4. The updated Model (TModel) is emitted to observers.
5. Generated Commands (TCmd) are processed by the Interpreter's Process function, which translates commands into new messages to complete the feedback loop.

Usage

1. Define Types

public record PaletteModel(string Query, bool IsLoading, List<string> Results);

public abstract record PaletteMsg
{
    public record QueryChanged(string Query) : PaletteMsg;
    public record ResultsFetched(List<string> Results) : PaletteMsg;
    public record SearchError(string Error) : PaletteMsg;
}

public abstract record PaletteCmd
{
    public record FetchFromApi(string Query) : PaletteCmd;
    public record ReportAnalytics(string Event) : PaletteCmd;
}

2. Define Transition

var transition = new Transition<PaletteModel, PaletteMsg, PaletteCmd>(
    Init: (new PaletteModel("", false, new()), default),
    Update: state =>
    {
        var (model, msg) = state;
        return msg switch
        {
            PaletteMsg.QueryChanged(var q) when string.IsNullOrWhiteSpace(q) =>
                (model with { Query = q, IsLoading = false, Results = new() }, default),

            PaletteMsg.QueryChanged(var q) =>
                (model with { Query = q, IsLoading = true }, new PaletteCmd.FetchFromApi(q)),

            PaletteMsg.ResultsFetched(var results) =>
                (model with { IsLoading = false, Results = results }, new PaletteCmd.ReportAnalytics("Search Completed")),

            PaletteMsg.SearchError =>
                (model with { IsLoading = false, Results = new() }, default),

            _ => (model, default)
        };
    }
);

3. Define Interpreter

using System.Reactive.Linq;

var interpreter = new Interpreter<PaletteCmd, PaletteMsg>(cmds =>
{
    var searchStream = cmds.OfType<PaletteCmd.FetchFromApi>();
    var analyticsStream = cmds.OfType<PaletteCmd.ReportAnalytics>();

    var searchMsgs = searchStream
        .Select(cmd => SearchMockApi(cmd.Query))
        .Switch();

    var analyticsMsgs = analyticsStream
        .Select(cmd => UploadAnalyticsApi(cmd.Event))
        .Merge();

    return Observable.Merge(searchMsgs, analyticsMsgs);
});

4. Run the Program

var program = new Program<PaletteModel, PaletteMsg, PaletteCmd>(transition, interpreter);
var userInput = new Subject<PaletteMsg>();

using var subscription = program.Run(userInput).Subscribe(model =>
{
    Console.WriteLine($"Query: {model.Query}, Loading: {model.IsLoading}, Results: {model.Results.Count}");
});

userInput.OnNext(new PaletteMsg.QueryChanged("f"));
userInput.OnNext(new PaletteMsg.QueryChanged("fo"));
userInput.OnNext(new PaletteMsg.QueryChanged("for")); 

Threading & Scheduling

Stepper's state transitions are serialized internally. When binding to a UI framework, configure the thread scheduling on the subscription:

program.Run(userInput)
    .ObserveOn(RxApp.MainThreadScheduler) // or your framework's UI scheduler
    .Subscribe(model => {
        // Update UI elements
    });

License

This project is licensed under the MIT License.