Public API
finity has three packages, each versioned on its own:
@ghostry/finity-reactjs:initializefor React, and finity's types.@ghostry/finity-solidjs:initializefor Solid, and finity's types.@ghostry/finity-core:initializewith a state adapter, the helpersnoop,never, andshallowEqual,FinityError, and the types.
initialize(config)
function initialize(config: {
onInvalidTransition?: (error: FinityError.InvalidTransitionError) => void;
isEqualState?: (a: State, b: State) => boolean;
}): Initialized;Call it once, and import finity's functions from that module. See Quick start.
onInvalidTransitionis called with each refused transition. Defaults to none. See Invalid transitions.isEqualStatedecides whether a transition to the same kind changes anything. Defaults toshallowEqual. See Equal states.
@ghostry/finity-core's initialize also requires useState, an adapter over your framework's state. See Other frameworks.
Returns:
| member | what it is |
|---|---|
defineTransitionalState | defines states and their transitions |
useStrictlyTransitionalState | holds a defined state, changed only by transitions |
useTransitionalState | the same, plus set and update |
useEffect | runs a case for the current state when it changes |
useRender | returns what the current state's case renders. React and Solid only |
useState | your framework's state with finity's { value, set, update } shape |
defineTransitionalState<States>(name?)
const Definition = finity
.defineTransitionalState<{ [Kind: string]: Data }>(name?: string)
.transitions({ [Kind]: Kind[] });The type argument maps each state's kind to its data. transitions maps each kind to the kinds that may follow it, and must list every kind. name labels the definition in invalid transition reports. See Defining states.
useStrictlyTransitionalState(definition, initial)
function useStrictlyTransitionalState(
definition: Definition,
initial: () => State,
): { value: () => TransitionalState };initial returns the starting state, without transition. value returns the current state, with its transition. See Strict or loose.
useTransitionalState(definition, initial)
The same as useStrictlyTransitionalState, plus:
set(state)replaces the state with any state, and returns it.update(fn)replaces the state withfn(previous), and returns it.
Neither is checked against transitions.
transition(state)
On every state value() returns. Takes one of the states the current state's transitions entry lists, with its data, and returns nothing. A stale or disallowed call does nothing, and is reported to onInvalidTransition. A call with a state equal to the current one does nothing, and isn't reported.
useEffect(getter) and useRender(getter)
finity
.useEffect(state.value)
.case(kinds, (state) => void)
.use();
finity
.useRender(state.value)
.case(kinds, (state) => element)
.use();case takes a list of kinds not already handled, with no duplicates, and a function receiving the state narrowed to them. use is callable only once every kind has a case. useEffect's use returns nothing, and useRender's returns the matching case's element. See Effects and Rendering.
Helpers
From @ghostry/finity-core:
| export | what it is |
|---|---|
noop | a function that does nothing, for a case with nothing to do |
never(value) | throws. Its parameter is never, so it's a type error unless every case before it returned |
shallowEqual(a, b) | the default isEqualState: same properties, each the same by Object.is |
FinityError | the base of every error finity creates. FinityError.InvalidTransitionError is the one onInvalidTransition receives. See Invalid transitions |
InvalidTransitionError | deprecated: the same class as FinityError.InvalidTransitionError |
ExhaustiveSwitchInstance | the class behind useEffect and useRender, for building a switch of your own |
Types
Every package exports:
TransitionalState<typeof Definition>: the union of a definition's states, each with itstransition.TransitionalStates<typeof Definition>: the same states, keyed by kind.UsingStrictlyTransitionalState<typeof Definition>,UsingTransitionalState<typeof Definition>: what the two hooks return.Config,Getter,Setter,ExhaustiveSwitch,FinityError, and the deprecatedInvalidTransitionError.
The React and Solid packages export FinityError, InvalidTransitionError, and ExhaustiveSwitchInstance as types only. Import their values from @ghostry/finity-core.
