Skip to content
Logo

Invalid transitions

TypeScript only lets a state's transition take the states its definition allows. Two kinds of transition can still be wrong at runtime, and finity refuses both:

  • Stale: the transition belongs to a state the component has already left.
  • Disallowed: the target isn't in the current state's transitions entry, which only happens when the types were bypassed.

A refused transition does nothing, and doesn't throw. finity calls onInvalidTransition instead, if you gave initialize one:

export const finity = initialize({
  onInvalidTransition: (error) => {
    console.warn(error.message);
  },
});

Stale transitions

A transition is tied to the state it came from. Once the state changes, by that transition, another one, or set, every transition from before is stale.

Transitioning twice from one state, the second call is stale:

finity.useEffect(state.value).case(["Idle"], ({ transition }) => {
  transition({ kind: "Uploading", file, progress: 0 });
  transition({ kind: "Uploading", file: other, progress: 0 }); // stale
});

So is the loser of a race. Whichever request settles first transitions, and the other is refused:

finity.useEffect(state.value).case(["Searching"], ({ query, transition }) => {
  primary
    .search(query)
    .then((results) => transition({ kind: "Found", results }));
  fallback
    .search(query)
    .then((results) => transition({ kind: "Found", results }));
});

That's the common case in practice: a response that arrives after the user has moved on. It's refused rather than written over the newer state, so you don't need an ignore flag or an abort check to keep it out.

A transition to an equal state doesn't change the state, so it doesn't make anything stale.

Disallowed transitions

A transition to a state the current state doesn't list is refused as disallowed. TypeScript prevents it, so it takes a cast or untyped code to get there:

// with transitions { Done: [] }
finity.useEffect(state.value).case(["Done"], ({ transition }) => {
  transition({ kind: "Idle" } as never); // disallowed
});

A transition that is both stale and disallowed is reported as stale.

FinityError.InvalidTransitionError

onInvalidTransition receives a FinityError.InvalidTransitionError, an Error with:

propertywhat it is
reason"stale" or "disallowed"
state.namethe definition's name, if you gave defineTransitionalState one
state.fromthe current state when the transition was attempted
state.tothe state it tried to transition to
tick.currenthow many times the state had changed
tick.boundhow many times it had changed when the transition was made. They differ for a stale transition
messagea summary, like [finity] Invalid (stale) state transition of "Upload" from "Uploading" to "Failed" …
stackwhere the transition was attempted, where the runtime records one
name"@ghostry/finity-core:InvalidTransitionError"

The error is created, not thrown. Throw it from onInvalidTransition if you want invalid transitions to fail loudly, in tests say:

initialize({
  onInvalidTransition: (error) => {
    throw error;
  },
});

Throwing on stale transitions in production is usually wrong, since a late response is expected there.

FinityError

Every error finity creates extends FinityError, and is a class in its namespace, like FinityError.InvalidTransitionError. So instanceof FinityError matches any of them. Import it from @ghostry/finity-core. The React and Solid packages export it as a type only.

import { FinityError } from "@ghostry/finity-core";
 
if (error instanceof FinityError.InvalidTransitionError) {
  report(error.reason, error.state.to.kind);
}

An error's name is the package and the class, joined by :. It identifies the error where instanceof can't: across two installed copies of finity-core, or after the error is serialized.

InvalidTransitionError is also exported on its own, as the same class. That export is deprecated, so import FinityError instead.