createPureStateMachine

createPureStateMachine :: FSM_Def -> FSM_Settings -> Pure_FSM

Description

The createPureStateMachine factory accepts the same parameters as the createStateMachine factory. It however returns a function that implements what we call a pure state machine. This is a term that we made up (i.e. it does not exist in the literature) to reflect the difference in signature of the returned function. A pure state machine not only requires an input, but also needs to be provided with a state from which to operate its computation. It then returns not only the outputs computed by the machine as per the standard formalism, but also the updated state. In other words, the pieces of state that were hidden (encapsulated) in the machine returned by the createStateMachine factory are now exposed at the API level. The main driver for the pure factory is to facilitate remote workflows, where the state of a machine can be saved in a remote database to be restored at a later time. The second main driver is to speed up testing.

For a detailed reference of the factory parameters, please refer to the reference documentation for the createStateMachine factory.

Pure_FSM

The type is as follows:

/**
 * @callback Pure_FSM
 * @param {*} input
 * @param {FSM_Internal_State} fsm_state
 * @returns {{outputs: FSM_Outputs|Error, fsmState: FSM_Internal_State}}
 */

FSM_Internal_State is an opaque type. You need not know or manipulate it. It only serves as an argument to a machine invocation. There are three semantics available depending on the shape of the fsm_state parameter:

The first shape of fsm_state allows using the pure API exactly as the stateful API if that is desired. This makes the stateful API a special case of the more general pure API. The second shape of fsm_state is useful to reset the machine without incurring the creation costs of rerunning the factory. The third shape may be used in the context of property-based testing, where many paths through the machine graph are explored, and we want to avoid the cost of recreating from scratch the machine time for every path. When running thousands of tests, the improvement is sensible. Another use case is using a machine in asynchronous workflows. The pure API gives the possibility to embed the machine in a process that can be stopped (saving the machine state) and resumed (recalling the machine state).