Explanation

Trax compared with XState and Stateless

Checked on 2026-11-05 against XState 5.33 (6.0 was in prerelease that day) and the Stateless README. Corrections are welcome as issues.

XState is an MIT-licensed TypeScript library for statecharts and actors. It has the fullest statechart model of the three, and because it is JavaScript the same machine runs unchanged in a browser and in Node. Stateless is the usual .NET choice: a small, Apache-2.0 library for a state machine inside one process. Neither stores an instance, checks who sent an event, or serves a machine to a client; that is left to the application.

A Trax machine is narrower than either as a statechart, and wider as a system: the server stores every instance, checks every event against the caller and the input, and applies the transition itself.

Statechart features

TraxXStateStateless
AuthoringC# fluent builderTypeScript or JavaScript config with setup()C# fluent Configure
StatesFlat: one enumNested (parent) statesSubstates (SubstateOf)
Parallel regionsNoYesNo
History statesNoShallow and deepNo
Entry and exit actionsNo: a reducer on the transitionYesYes
Delayed transitionsOne timer per state (After), fixed or read from the context within a min and max, fired by the server from a stored due timeafter, fired by the running actor (6.0 stores pending timers in the snapshot)No
Child workOne train or one child machine per state, with done, failed and cancelled outcomesAny number of invoked or spawned actorsNo
GuardsDeclarative rules that travel as data; a custom guard is bound by name and written once per runtimeJavaScript functionsC# delegates
Visual editorNo. The operations console draws a machine you wrote, and trax machine show exports Mermaid or DOTStately StudioDOT and Mermaid export
Data per stateEach state declares its context as a C# record, with rules checked on every move and on every load of a stored snapshotCompile-time types in 5; runtime schemas per state in 6.0No: the machine holds only the state
Final statesEnds() and Fails() give a parent machine its done or failed outcometype: 'final' with outputNo
The machine as dataExported to a JSON definition with its guards and reducersserializeMachine in 6.0GetInfo()
A refused eventA typed result code from one set shared by every runtime and the GraphQL schema; the engine never throwsIgnored; can() checks aheadThrows by default; OnUnhandledTrigger overrides

Trax machines are flat on purpose. Nested regions were considered and rejected in ADR 0052: a state spawns a child machine instead.

Running a machine for real users

TraxXState plus your backendStateless
Server runtimeASP.NET Core on .NET 10Any JavaScript runtimeAny .NET
In the browserThe same machine, through @traxsharp/state-machine; it predicts, the server decidesThe same machineNo
Who applies a transitionThe server: the client sends an event, and the server reruns the transition from the stored snapshotYours to buildYours to build
Event inputChecked against a C# record's schema in every runtime; unknown fields refusedYours (types are compile-time only)Yours
Who may send an eventDeclared per event and for start (Requires, RequiresPolicy, AnyAuthenticated); reads, pushes and discards are owner-only at least; a rule left out stops the hostYoursYours
StorageBuilt in, on Postgres or SQLitegetPersistedSnapshot(); storage is yoursA state accessor; storage is yours
Concurrent writersA concurrency token on every write; a conflict is a typed resultYoursOne thread per instance; the rest is yours
Irreversible side effectsRunsOnce<TEffect>(): a lease, a fence token and an idempotency key; recorded once, called again only under the same key after a crashYoursYours
Changing a machine with live instancesVersion and MigrateFrommigrateSnapshot in 6.0; yours in 5Yours
API and clientA GraphQL mutation per event and a live subscription; a typed React client from trax client, and a typed C# view from trax machine generateYoursYours
A retried requestEvery event, start and discard carries a request id; a retry gets the first answer backYoursYours
Saving a half-filled formsave stores a whole snapshot the server validates, on machines with no server-side behaviour, and never out of a committed stateYoursYours
Who owns an instanceEach user's instances are theirs alone; a system-owned machine is started and moved only by host codeYoursYours
Limits50 drafts and 10 running invoked trains per user by default; a 64 KiB snapshotYoursYours
Abandoned instancesDrafts idle 30 days, or older than 90, are sweptYoursYours
Work a state startsA train run, queued in the same transaction as the move, recorded like any run, cancelled when the state is left, its outcome applied on any hostInvoked actors in the running processYours
History of an instanceEvery write records its transition, its command and who made it: a user, host code, a timer or a train's outcomeYoursAn OnTransitioned hook
OperatorsThe operations console: each machine drawn with instance and stuck counts per state, each instance's history and the runs it started, lookup by idThe Stately Inspector, for one running systemNo
An outdated clientRefused as CLIENT_OUTDATED; a prediction that differs from the server's result is refused as CLIENT_DIVERGENCE and countedYoursNot applicable
MetricsA Trax.StateMachine meter: divergence, failed timers, abandoned effectsInspection eventsNo
Clients in other languagesA .NET client; a Rust engine and client held to the same kit, not published yetJavaScript onlyNot applicable
Checks before it runsBuild() and host startup refuse an unsafe machine; trax machine check fails on generated files that driftedNot foundNo
TestingTrax.StateMachine.Testing: conformance checks and a differential corpusPath generation from xstate/graphNo
Same answers in every runtimeShared conformance fixtures run against the C#, TypeScript and Rust (unpublished) enginesOne runtimeOne runtime

The XState 6 guide to backend workflows lists per-instance locking, idempotency keys and migrations as the application's job. That list is roughly what Trax does for you.

When to choose XState

  • Your backend is Node or another JavaScript runtime. Trax's server is ASP.NET Core only.
  • You need a real statechart: nested states, parallel regions, history, entry and exit actions, or several timers or children in one state.
  • The machine is UI logic that never needs a server's verdict: a form wizard, a media player, a drag interaction.
  • You want to design machines in a visual editor with people who do not write code.

When to choose Stateless

  • You need a state machine inside one .NET service: a device protocol, a domain object's lifecycle, a parser. There is no client, no row per instance and no caller to check.
  • You want substates and entry and exit actions in C# with no infrastructure. The Trax engine runs in process, but storing and serving a machine needs Trax.Effect and a database.

When to choose Trax

  • A client proposes and the server has to decide: each event checked against the caller and its input, a stored snapshot that two writers cannot both overwrite, timers the server fires, one side effect recorded once, and a typed API and client generated from the machine.
  • The clients are untrusted: a browser, a script or an agent. A retry must not apply an event twice, and each user may touch only their own instances.
  • A state starts long work that has to survive a crash and leave a run record.
  • Operators need to see where every instance is and what it waits on, without writing an admin page.
  • The clients are .NET as well as TypeScript.

Using them together

XState can still drive a page's own UI state while the business process lives in a Trax machine on the server: the page sends the Trax machine's events and renders its snapshot. Stateless can run inside a junction, where a train needs a small in-process machine for one step.