Statecharts for Ember

Your machines, written as classes.

States are real-enums values, events are decorated methods, context is @tracked fields. Everything xstate does, on the same semantics: hierarchy, parallel regions, history, guards, timers, invoked and spawned actors. Templates track it, tests wait for it, and the diagram is drawn from the code.

npm i @switchyard-ts/core @switchyard-ts/ember @real-enums/core
A Fetch class whose methods are its events, and the statechart drawn from it: idle, loading, then a switch to done or failed, with retry running from failed back to loading. Your class Its statechart Events are methods class Fetch extends Machine { @transition({ from: Idle, to: Loading }) fetch() {} @transition({ from: Loading, to: Failed }) fail() {} @transition({ from: Failed, to: Loading }) retry() {} @transition({ from: Loading, to: Done }) resolve(user) {} } fetch() fail() retry() resolve() switch Idle Loading Done Failed

Why

A statechart that reads like the rest of your app

The Fetch machine's statechart: idle, loading (first, retrying, history), done, failed.
This is the machine below, drawn by npx switchyard diagram fetch.ts. In your app, <SwitchyardDebug> draws it live.
class FetchState extends State<Attempt> {
  private declare readonly brand: never
  static Idle = FetchState.of('idle')
  static Loading = FetchState.of('loading', { children: Attempt, history: 'shallow' })
  static Done = FetchState.of('done')
  static Failed = FetchState.of('failed')
}

class Fetch extends Machine<FetchState> {
  @tracked user?: string
  @tracked retries = 0

  get hasRetriesLeft() {
    return this.retries < 3
  }

  @transition({ from: FetchState.Idle, to: FetchState.Loading })
  fetch() {}

  @transition({ from: FetchState.Failed, to: history(FetchState.Loading), guard: (m: Fetch) => m.hasRetriesLeft })
  retry() {
    this.retries++
  }

  @invoke(FetchState.Loading, { onDone: FetchState.Done, onError: FetchState.Failed })
  async load(signal: AbortSignal) {
    this.user = await api.get(signal)
  }

  @after(3000, { from: Attempt.First, to: Attempt.Retrying })
  slow() {}
}

States are real enums

Labels, icons and @is() predicates live on the state. Nested states are their own enums, so each level stays exhaustive.

Events are methods

fetch.retry() sends the event, typed by its signature. Guards point at getters over your tracked fields, typed. can(FetchState.Loading) knows what is allowed now.

The semantics are xstate's

Run-to-completion on the SCXML algorithm, checked against xstate itself. Export to xstate JSON or SCXML, import from them, or generate a class from an xstate config.

Ember

Tracked, owned, and waited for

import { machine, send, can } from '@switchyard-ts/ember'

export default class UserCard extends Component {
  fetch = machine(this, new Fetch()) // stops when the component is destroyed

  <template>
    {{#if this.fetch.state.isLoading}}Loading…{{/if}}
    <button disabled={{if (can this.fetch FetchState.Loading via=this.fetch.retry) false true}}
            {{on "click" (send this.fetch "retry")}}>Retry</button>
  </template>
}

Templates re-render on transitions. Services hold app-wide machines. await settled() waits for invokes and timers. <SwitchyardAnnouncer> tells screen readers what changed. Snapshots restore across reloads, and bindField puts a state in a record or the URL. Already on ember-concurrency? @invoke runs your tasks and cancels them when the state exits. In Ember →

Diagrams

The chart is the code

Mermaid for READMEs and pull requests, DOT, SVG laid out by ELK, a class-interface view with payload types, the live actor tree, and a live in-app view that lights up the active states. From the command line, at build time with the Vite plugin, or in your app. Diagrams →

Testing

The machine already knows what to test

A manual clock for timers, toBeIn and assert.machineIn, a coverage report of states and transitions no test reached, and model-based tests that walk every path and drive the real UI through harnessed. Testing →

Packages

Take what you need

Package For
@switchyard-ts/core Machines, decorators, the interpreter, snapshots
@switchyard-ts/ember Tracking, lifetimes, helpers, waiters, <SwitchyardAnnouncer>, <SwitchyardDebug>
@switchyard-ts/ember-concurrency Run ember-concurrency tasks from @invoke; leaving the state cancels them
@switchyard-ts/graph Mermaid, DOT, SVG, interface and actor views, the live viewer
@switchyard-ts/test Paths, coverage, matchers, a manual clock
@switchyard-ts/harnessed Model-based tests through harnessed
@switchyard-ts/interop xstate JSON and SCXML, both ways, and codegen
@switchyard-ts/inspector The Stately Inspector
@switchyard-ts/cli switchyard diagram|export|import, and a Vite plugin
@switchyard-ts/eslint-plugin Unreachable states, unknown guards, non-exhaustive switches
@switchyard-ts/skills The authoring skill for coding agents