Skip to content
Logo

Public API

finity has three packages, each versioned on its own:

  • @ghostry/finity-reactjs: initialize for React, and finity's types.
  • @ghostry/finity-solidjs: initialize for Solid, and finity's types.
  • @ghostry/finity-core: initialize with a state adapter, the helpers noop, never, and shallowEqual, 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.

  • onInvalidTransition is called with each refused transition. Defaults to none. See Invalid transitions.
  • isEqualState decides whether a transition to the same kind changes anything. Defaults to shallowEqual. See Equal states.

@ghostry/finity-core's initialize also requires useState, an adapter over your framework's state. See Other frameworks.

Returns:

memberwhat it is
defineTransitionalStatedefines states and their transitions
useStrictlyTransitionalStateholds a defined state, changed only by transitions
useTransitionalStatethe same, plus set and update
useEffectruns a case for the current state when it changes
useRenderreturns what the current state's case renders. React and Solid only
useStateyour 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 with fn(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:

exportwhat it is
noopa 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
FinityErrorthe base of every error finity creates. FinityError.InvalidTransitionError is the one onInvalidTransition receives. See Invalid transitions
InvalidTransitionErrordeprecated: the same class as FinityError.InvalidTransitionError
ExhaustiveSwitchInstancethe 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 its transition.
  • 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 deprecated InvalidTransitionError.

The React and Solid packages export FinityError, InvalidTransitionError, and ExhaustiveSwitchInstance as types only. Import their values from @ghostry/finity-core.