XState Docs

# SCXML

These XState v4 docs are no longer maintained

XState v5 is out now! Read more about XState v5 (opens new window) and check out the XState v5 docs (opens new window).

XState is compatible with the SCXML (State Chart XML: State Machine Notation for Control Abstraction) specification (opens new window). This page contains details on where our API relates to the SCXML specification.

# Events

Events in SCXML contain information relevant to the source of the event, and have a different schema than event objects in XState. Internally, event objects are converted to SCXML events for compatibility.

SCXML events include:

  • name - a character string giving the name of the event. name is equivalent to the .type property of an XState event.
  • type - the event type: 'platform', 'external', or 'internal'.
    • platform events are raised by the platform itself, such as error events.
    • internal events are raised by raise(...) actions or by send(...) actions with target: '_internal'.
    • external events describe all other events.
  • sendid - the send ID of the triggering send(...) action.
  • origin - a string that allows the receiver of this event to send(...) a response event back to the origin.
  • origintype - used with origin
  • invokeid - the invoke ID of the invocation that triggered the child service.
  • data - any data that the sending entity chose to include with this event. data is equivalent to an XState event object.

The SCXML event form of all XState events is present in the _event property of action and guard meta objects, as the third argument:




 
 



 
 





// ...
{
  actions: {
    someAction: (context, event, { _event }) => {
      console.log(_event); // SCXML event
    };
  },
  guards: {
    someGuard: (context, event, { _event }) => {
      console.log(_event); // SCXML event
    }
  }
}
// ..

# Transitions

The event-target mappings defined on the on: { ... } property of state nodes is synonymous to the SCXML <transition> element:

{
  green: {
    on: {
      TIMER: {
        target: '#yellow',
        cond: context => context.timeElapsed > 5000
      },
      POWER_OUTAGE: { target: '#red.flashing' }
    }
  },
  // ...
}

<state id="green">
  <transition
    event="TIMER"
    target="yellow"
    cond="timeElapsed > 5000"
  />
  <transition
    event="POWER_OUTAGE"
    target="red.flashing"
  />
</state>

# Guards

The cond property is equivalent to the cond attribute on the SCXML <transition> element:

{
  on: {
    e: {
      target: 'foo',
      cond: context => context.x === 1
    }
  }
}

<transition event="e" cond="x == 1" target="foo" />

Similarly, the in property is equivalent to the In() predicate:

{
  on: {
    e: {
      target: 'cooking',
      in: '#closed'
    }
  }
}

<transition cond="In('closed')" target="cooking"/>

# State IDs

IDs correspond to the definition of IDs in the SCXML spec:

{
  green: {
    id: 'lightGreen';
  }
}

<state id="lightGreen">
  <!-- ... -->
</state>

# Actions

Executable actions in transitions are equivalent to the SCXML <script> element. The entry and exit properties are equivalent to the <onentry> and <onexit> elements, respectively.

{
  start: {
    entry: 'showStartScreen',
    exit: 'logScreenChange',
    on: {
      STOP: {
        target: 'stop',
        actions: ['logStop', 'stopEverything']
      }
    }
  }
}

<state id="start">
  <onentry>
    <script>showStartScreen();</script>
  </onentry>
  <onexit>
    <script>logScreenChange();</script>
  </onexit>
  <transition event="STOP" target="stop">
    <script>logStop();</script>
    <script>stopEverything();</script>
  </transition>
</state>

# Invoke

The invoke property is synonymous to the SCXML <invoke> element:

// XState
{
  loading: {
    invoke: {
      src: 'someSource',
      id: 'someID',
      autoForward: true, // currently for machines only!
      onDone: 'success',
      onError: 'failure'
    }
  }
}

<!-- SCXML -->
<state id="loading">
  <invoke id="someID" src="someSource" autoforward />
  <transition event="done.invoke.someID" target="success" />
  <transition event="error.platform" cond="_event.src === 'someID'" target="failure" />
</state>

← Reddit API →