SCXML

XState is compatible with the SCXML (State Chart XML: State Machine Notation for Control Abstraction) specification. 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 actor.
• data, any data that the sending entity included 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:

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

js
// ...
{
  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:

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

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

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

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

• https://www.w3.org/TR/scxml/#transition - the definition of <transition>

Guards

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

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

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

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

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

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

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

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

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

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

cond and In() in the SCXML specification

• SCXML definition of the cond attribute
• SCXML conditional expressions and the requirement of supporting the In() predicate
• How transitions are selected given an event in SCXML

State IDs

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

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

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

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

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

IDs in the SCXML specification

• SCXML specification that all id attributes must be unique
• SCXML definition of the id attribute in <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.

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

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

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

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

script, onentry and onexit in the SCXML specification

• SCXML definition of the <script> element
• SCXML definition of the <onentry> element
• SCXML definition of the <onexit> element

Invoke

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

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

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

xml
<!-- 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>

xml
<!-- 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>

SCXML definition of <invoke>