Skip to content
Logo

Defining states

defineTransitionalState takes the states as a type argument, and transitions takes the transitions as a value:

export const  = 
  .<{
    : {};
    : { : File; : number };
    : { : File; : Error };
    : { : string };
  }>("Upload")
  .({
    : ["Uploading"],
    : ["Uploading", "Failed", "Done"],
    : ["Uploading", "Idle"],
    : [],
  });

Define it once, at module level, and share it between components.

States

Each key of the type argument is a state's name, and its value is the data that state carries. Use {} for a state with no data. A state's value has that data plus kind, its name, so the states form a union you can narrow on kind.

The optional argument, "Upload" here, names the definition in invalid transition reports.

Transitions

transitions needs an entry for every state, and nothing else. Each entry lists the states that may follow it:

  • Idle: ["Uploading"]: an idle upload can only start.
  • Uploading: ["Uploading", …]: a state may list itself, here to update progress.
  • Done: []: a terminal state. Its transition accepts nothing.

A state's transition only accepts the states in its entry, with all of their data:

const  = .();
 
if (. === "Idle") {
  .({ : "Uploading", , : 0 });
  .({ : "Done", : "/files/1" });
Type '"Done"' is not assignable to type '"Uploading"'.
}

Naming the types

Two types name a definition's states:

import type {
  TransitionalState,
  TransitionalStates,
  UsingStrictlyTransitionalState,
} from "@ghostry/finity-reactjs";
 
type Upload = TransitionalState<typeof Upload>; // the union of every state
type Uploads = TransitionalStates<typeof Upload>; // each state, by kind
 
function Progress(props: { state: Uploads["Uploading"] }) {
  // ...
}

Each state in them includes its transition. UsingStrictlyTransitionalState<typeof Upload> and UsingTransitionalState<typeof Upload> name what the two hooks return, for passing a whole state holder to another component or function.