Skip to content
Logo

Strict or loose

finity has two hooks for holding a defined state. Both take the definition and a function returning the initial state:

const state = finity.useStrictlyTransitionalState(Upload, () => ({
  kind: "Idle",
}));
const state = finity.useTransitionalState(Upload, () => ({ kind: "Idle" }));

useStrictlyTransitionalState

Returns { value }. The state only changes through a transition on the current state, so every change is one the definition allows. Prefer it.

useTransitionalState

Returns { value, set, update }. Each state still has its transition, but set and update replace the state with any state at all, whatever the definition says:

state.set({ kind: "Idle" });
state.update((previous) =>
  previous.kind === "Uploading" ? { ...previous, progress: 1 } : previous,
);

set and update aren't checked against transitions, and aren't reported as invalid. They do count as a change, so a transition taken from the state before them is stale afterwards.

Use it when something outside the state machine has to reset it, like a "start over" button that must work from any state. If the reset is really a transition, list it in transitions instead and keep the strict hook.

useState

initialize also returns useState, a thin wrapper over your framework's own state with the same shape, { value, set, update }, and no states or transitions. value is a getter in both frameworks. It's there so plain state looks the same as finity's beside it, and you don't need it to use finity.