A utility package to create a fully typed state machine with associated data as a Svelte store.
npm install @terrygonguet/svelte-pointerlock
<script lang="ts">
import { stateMachine } from "@terrygonguet/svelte-state-machine"
type State = { type: "off" } | { type: "on"; extraBright: boolean }
type Action = { type: "turnOn"; extraBright: boolean } | { type: "turnOff" }
const { state, dispatch } = stateMachine<State, Action>({ type: "off" }, {
off: {
turnOn(state, action) {
return { type: "on", extraBright: action.extraBright }
}
},
on: {
turnOff(state, action) {
return { type: "off" }
}
}
})
</script>
{#if $state.type == "on"}
<!-- $state is of type { type: "off" } here -->
<button on:click={() => dispatch({ type: "turnOn", extraBright: false })}>Turn on low</button>
<button on:click={() => dispatch({ type: "turnOn", extraBright: true })}>Turn on high</button>
{:else}
<!-- $state is of type { type: "on"; extraBright: boolean } here -->
<button on:click={() => dispatch({ type: "turnOff" })}>Turn off</button>
{/if}
This package exports one function: stateMachine
and is used like:
const { state, dispatch, transitioning, is } = stateMachine<State, Action>(
initialState,
options,
machine,
)
// OR, with default options:
const { state, dispatch, transitioning, is } = stateMachine<State, Action>(
initialState,
machine,
)
This function takes 2 type parameters State
and Action
that are both
intended to be
discriminated unions
on the type
property (e.g. { type: "off" } | { type: "on" }
).
The parameters are:
initialState
: an initial value of type State
options
(optional): an options objectasyncMode
(default: "block"
): wether to "block"
(ignore new
actions) or "abort"
(cancel current async transition to replace it)
when in an async transitiononError
(default: no op): a function that gets called when an error is
trown during a transition function and allows you to recover by
returning a new state objecthooks
: an object specifying functions for every state to be called
during transition flowmachine
: the description of the state machinemachine
objectThe machine
parameter is an object that specifies transition functions for
each state, for each action where the key is the type
of the respective type:
type State = { type: "stateA" } | { type: "stateB" }
type Action = { type: "actionA" } | { type: "actionB" }
const { state } = stateMachine<State, Action>({ type: "stateA" }, {
stateA: {
actionA: /* transition function */
// no action on actionB action
},
// we can leave out stateB entirely
})
You can leave out any combination of state and action. This is useful when you want to ignore some actions when in certain states.
Transition functions take 2 parameters: the current state and the current action that was dispatched and should return the new state to transition to or a promise that resolves to that state. The types of the parameters are automatically narrowed to reduce boilerplate:
type State = { type: "stateA" } | { type: "stateB" }
type Action = { type: "actionA" } | { type: "actionB" }
stateMachine<State, Action>(
{ type: "stateA" },
{
stateA: {
actionA(state, action) {
// state is narrowed to { type: "stateA" }
// action is narrowed to { type: "actionA" }
},
},
},
)
Transition functions can return promises. In that case the state machine will
wait for the promise to resolve and transition to the new state then. While the
promise is pending the transitioning
store contains true
.
The behaviour of the state machine while an async transition is pending is
controlled by the asyncMode
option and defaults to "block"
:
"block"
: any new actions dispatched will be ignored until the transition
resolves"abort"
: the current transition is aborted and replaced with the new oneYou can specify hooks
to be called during transitions flow, scoped by state
type:
type State = { type: "stateA" } | { type: "stateB" }
const hooks = {
stateA: {
onEnter(prevState, curState, action) {}
onExit(prevState, nextState, action) {}
onStay(prevState, nextState, action) {}
onAsyncTransition(state, action) {}
},
// more hooks for other states
}
onEnter
: called just before the state machine transitions to the specified
stateonExit
: called just before the machine transitions away from the specified
stateonStay
: called when the machine ran a transition but stayed in the same
stateonAsyncTransition
: a function called when an async transition starts; can
return a new state object to be transitioned to while the async tranition is
pendingThe stateMachine
function returns an object with a few properties:
state
: a readable store
containing the current state of the machinedispatch
: a function that takes an Action
to transition the machine to a
new statetransitioning
: a readable store containing true
when the machine doing
an async transition and false
otherwiseis
: an object that maps every State["type"]
to a readable store that
contains true
when the machine is in that state (the equivalent of
$state.type == "key"
)