Skip to content
Logo

Effects

A state often has work to start, like the request behind Loading. Give that state its own component, render it from useRender, and start the work there with your framework's own effect:

The component exists exactly as long as its state, so its effect starts when the state does and is cleaned up when the state ends. That's what finity's own useEffect can't do: its cases can't return a cleanup, so a request started in Loading keeps running after the component has moved on. It can't overwrite the newer state, since its transition is stale by then, but it still runs to the end and is reported to onInvalidTransition. The abort check keeps an aborted request from being reported too.

It also keeps a state's work beside what it renders, and uses your framework's effects as they're documented, with nothing of finity's in between.

In React, the effect depends on state, which keeps its identity until the state changes, so it runs once for each state the component enters. In Solid, a case runs once when its state starts, so the component body is the effect. A transition to the same kind doesn't rerun it there, since the case stays mounted. See React and Solid.

finity's useEffect

useEffect runs a case for the current state every time the state changes. It can still be the shorter choice for work that needs no cleanup and has nothing to render, like logging each state:

finity
  .useEffect(state.value)
  .case(["Loading"], () => analytics.track("resource.loading"))
  .case(["Ready", "Errored"], ({ kind }) => analytics.track(`resource.${kind}`))
  .use();

Pass it the state's getter, state.value, not the state. Then add one case per group of states, and finish with use(). Like any hook, call it unconditionally, at the top level of your component.

Cases

case takes a list of kinds and a function. The function receives the state, narrowed to those kinds, with its data and its transition:

.case(["Failed"], ({ file, error, transition }) => { /* ... */ })

A case can list several kinds. The function then receives a union of them, and only their shared properties are available without narrowing on kind.

States that need nothing go in a case with noop, from @ghostry/finity-core. Listing them is the point: it says those states were considered.

Every state must have a case

use() is only callable once every state has a case. Until then, its type names the states left:


  .(.)
  .(["Loading"], )
  .(["Ready"], )
  .();
This expression is not callable. Type 'UnhandledStates<"Errored">' has no call signatures.

So adding a state to a definition fails to compile at every effect and render that doesn't handle it yet. Each kind can be handled once. A kind already handled, or listed twice in one case, is a type error too.

When it runs

Your framework decides:

  • React: the matching case runs after a render in which the state changed, through React's useEffect. Its return value is ignored, so it can't clean up.
  • Solid: the matching case runs inside a createEffect that tracks the state, so it reruns when the state changes.

A case runs once per state change, not once per render. A state that transitions to an equal state doesn't change, so its effect doesn't run again.

A case may be async, and nothing waits for it. If the component has changed state by the time it calls transition, the transition is ignored and reported as stale.