Skip to content
Logo

Mental model

finity has four parts: the definition of a component's states, the hook that holds the current one, the transition that moves between them, and the cases that act on each one.

A definition lists states and transitions

const Resource = finity
  .defineTransitionalState<{
    Loading: {};
    Ready: { resource: string };
    Errored: { error: Error };
  }>("Resource")
  .transitions({ Loading: ["Ready", "Errored"], Ready: [], Errored: [] });

The type argument lists each state's name and the data it carries. A state value is that data plus kind, its name: { kind: "Ready", resource: "…" }. transitions lists, for each state, the states that may follow it, and [] makes a state terminal.

A definition is a plain value, made once at module level and shared by every component that uses it. See Defining states.

A hook holds the current state

const state = finity.useStrictlyTransitionalState(Resource, () => ({
  kind: "Loading",
}));

The hook stores the state in your framework's own state, starting from what its function returns. state.value is a getter: call it for the current state, or pass it to useEffect and useRender.

useTransitionalState is the same hook, plus state.set and state.update for replacing the state without a transition. See Strict or loose.

Each state carries its own transition

const current = state.value();
 
if (current.kind === "Loading") {
  current.transition({ kind: "Ready", resource: "…" });
}

A state's transition takes only the states its transitions entry lists, with their data. Calling it replaces the state, and your framework rerenders as for any state change.

A transition belongs to the state it came from. Once the state has changed, by that transition or any other, calling it again does nothing, and is reported as stale. Transitioning to an equal state changes nothing, and leaves the transition usable. See Invalid transitions and Equal states.

Cases act on each state

useRender and useEffect take the state getter, then one case per group of states, then use():

return finity
  .useRender(state.value)
  .case(["Loading"], (loading) => <Loading state={loading} />)
  .case(["Ready"], ({ resource }) => <Resource resource={resource} />)
  .case(["Errored"], ({ error }) => <Failure error={error} />)
  .use();
  • Each case lists one or more kinds, and its function receives the state, narrowed to those kinds.
  • A kind can only appear in one case, and listing one twice is a type error.
  • use() only compiles once every state has a case. Until then, its type names the states left.

useRender returns what the matching case returns, for your component to render. A state with work to do, like Loading here, gets its own component, which starts the work with your framework's own effect and cleans it up when the state ends. useEffect runs the matching case whenever the state changes, but can't clean up. See Rendering and Effects.

initialize ties it to your framework

export const finity = initialize({});

initialize returns the functions above, built on your framework's state and effects. Its options apply to every state they create: onInvalidTransition and isEqualState. Call it once and import from that module.