An API to use xstate in a composable way!
Installation
yarn add xstate xsfp
npm install xstate xsfp
Overview
;; // Stateless machine definition// machine.transition(...) is a pure function used by the interpreter. // Original way// const toggleMachine = createMachine({// id: 'toggle',// initial: 'inactive',// states: {// inactive: { on: { TOGGLE: 'active' } },// active: { on: { TOGGLE: 'inactive' } },// },// }); // xsfp wayconst toggleEvent = x;const toggleState = x; const toggleMachine = x; // Machine instance with internal stateconst toggleService = start;// => 'inactive' toggleService;// => 'active' toggleService;// => 'inactive'
Promise example
;; const fetchTransition = x; const fetchMachine = x; const swService = start; swService;
Finite State Machines
; const timerTransition = x;const timerState = x; const lightMachine = x; const currentState = 'green'; const nextState = lightMachinevalue; // => 'yellow'
Hierarchical (Nested) State Machines
; const pedTimerTransition = x; const pedestrianStates = x; const timerTransition = x; const lightMachine = x; const currentState = 'yellow'; const nextState = lightMachinevalue;// => {// red: 'walk'// } lightMachinevalue;// => {// red: 'wait'// }
Parallel State Machines
const toggleStates = x; const wordMachine = x; const boldState = wordMachinevalue; // {// bold: 'on',// italics: 'off',// underline: 'off',// list: 'none'// } const nextState = wordMachinevalue; // {// bold: 'off',// italics: 'on',// underline: 'on',// list: 'bullets'// }
History States
const paymentMachine = x; const checkState = paymentMachine; // => State {// value: { method: 'check' },// history: State { ... }// } const reviewState = paymentMachine; // => State {// value: 'review',// history: State { ... }// } const previousState = paymentMachinevalue; // => { method: 'check' }
Contribution
Please feel free to make issues and PRs!
API
The API will not go into too much details, as the library expects the user to have an understanding of how xstate works.
states | parallelStates
states
takes state
| initialState
| finalState
| historyState
as arguments.
parallelStates
takes state
| finalState
| historyState
as arguments.
states
also accepts a string shorthand. Useful for nested states with no transitions
;
The initialState
function OR the first state
argument determines the initial state
;
state | initialState | historyState | finalState
state
| initialState
is a function expects that all the same arguments as createMachine
.
state 'name', states, parallelStates, id, context, history, on, invoke, entry, exit, after, always, activties, meta, data, delimiter; ;;
on
on
is used to describe events and its transitions
;
A guard
acts as the condition that determines whether the transition described before it will run
; // both below are equivalent
A guard
will also implicitly act as boundaries between different transitions
; // transitions make this explicit;
transition
transition
is a function that describes an event transition. If a target is specified, it must be the first argument.
It accepts the target state and assign
| effect
| action
| choose
| guard
as arguments.
If a guard
is specified it must be the last argument.
; ;
action
action
is a function that accepts an action config key as the argument
;
effect
effect
is a function that accepts an action function as the argument
Also accepts a cleanup function that will be called within activities
effect
guard
guard
is a function that returns a boolean. To be used within on
or as the last argument of transition
guardcontext, Booleancontext.values
entry | exit | always
entry
| exit
| always
are functions that expect the same arguments as on
(minus the event name)
entry 'error', guard!event.value, // this will run only if the guard above is false 'idle', assign; exit 'error', guard!event.value, // this will run only if the guard above is false 'idle', assign; always 'error', guard!event.value, // this will run only if the guard above is false 'idle', assign;
choose
choose
accepts the same arguments as transition
(except for a target state)
Guard
acts as action boundaries as well
x;
choice
choice
accepts the same arguments as transition
(except for a target state).
Useful for explicitly setting boundaries
(analogous to transition
within on
)
x;
after
after
is a function that takes accepts delay
arguments
after 2000, effect
delay
;
invoke
invoke
accepts the src
type as the first argument, and onDone
| onError
| id
| data
| autoForward
x;
id
id
is a function that takes a string
;
context
context
is a function that takes the context of the machine or a function that returns the context of the machine
history
history
is a function that takes the history types
;
merge
merge
accepts on
OR assign
| action
| effect
and merges them
const reset = ; const resetTransitions = ;