@prb/effect-xstate
v4.0.0
Published
Effect-TS and xState v5 workflow utilities
Maintainers
Readme
@prb/effect-xstate
[!WARNING]
This is experimental, beta software. It is provided "as is" without warranty of any kind, express or implied.
Effect 4 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@^4.0.0 xstate @xstate/reactUsage
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 (v4.0.0)
Version 4 requires effect@^4.0.0. Migrate service implementations to native Effect 4 APIs before passing them to these
machines. Effects still run with no remaining service requirements; provide their layers in your service
implementations. Actor stop, reset, and reentry interrupt pending Effects, and typed failures retain their original
identity across the XState promise boundary.
Migration (v3.0.0)
FormMachineContext.payloadis nowTPayload | null.FormMachineContext.preprocessis nowTPreprocess | null.useFormWorkflow(...).preprocessnow returnsTPreprocess | null.createFacilitatorMachineacceptsCREATEonly fromcheckedwhen eligibilitystatus === "true".CREATEfromfailedis ignored; retry viaCHECKorRESET.createTxMachinenow strictly validates gas/simulate outputs and hash-bearing sign/confirm outputs at runtime.
License
MIT
