@prb/effect-xstate

[!WARNING]

This is experimental, beta software. It is provided "as is" without warranty of any kind, express or implied.

Effect-TS and xState v5 workflow utilities for React applications.

Overview

This package provides reusable state machines and React hooks that combine Effect-TS's functional effect system with xState v5's state management capabilities.

Features

• Form Machine: Generic form workflow with validation, processing, and error handling
• Facilitator Machine: Check-then-create workflow for eligibility and resource creation
• React Hooks: Type-safe hooks for managing machine state in React components
• Error Utilities: Helpers for extracting and displaying structured error data

Installation

bun add @prb/effect-xstate effect xstate @xstate/react

Usage

Form Machine

Create a form workflow that validates inputs before processing:

import { createFormMachine } from "@prb/effect-xstate";
import { Effect } from "effect";

const machine = createFormMachine({
  id: "create-stream",
  services: {
    onCheck: (payload) => Effect.succeed(undefined),
    onValidate: (payload) => Effect.succeed({ validated: true }),
    onProcess: ({ payload, preprocess }) => Effect.succeed(undefined),
  },
});

Facilitator Machine

Create a check-then-create workflow:

import { createFacilitatorMachine } from "@prb/effect-xstate";
import { Effect } from "effect";

const machine = createFacilitatorMachine({
  id: "claim-airdrop",
  services: {
    onCheck: (payload) => Effect.succeed({ status: "true", transitive: { proof: "0x..." } }),
    onCreate: ({ create, transitive }) => Effect.succeed(undefined),
  },
});

React Hook

import { useFacilitatorWorkflow } from "@prb/effect-xstate";

function MyComponent() {
  const workflow = useFacilitatorWorkflow(machine);

  return (
    <div>
      <button onClick={() => workflow.check({ id: 123 })}>
        Check Eligibility
      </button>
      {workflow.status.isEligible && (
        <button onClick={() => workflow.create({ id: 123 })}>
          Create Resource
        </button>
      )}
    </div>
  );
}

Migration (v3.0.0)

• FormMachineContext.payload is now TPayload | null.
• FormMachineContext.preprocess is now TPreprocess | null.
• useFormWorkflow(...).preprocess now returns TPreprocess | null.
• createFacilitatorMachine accepts CREATE only from checked when eligibility status === "true".
• CREATE from failed is ignored; retry via CHECK or RESET.
• createTxMachine now strictly validates gas/simulate outputs and hash-bearing sign/confirm outputs at runtime.

License

MIT