Type safe states

[SandroMaglione]

Two additions to createMachine's type signature:

1. const TStates — a new type parameter that captures the literal shape of the states property via & { states?: TStates } (additive intersection, MachineConfig stays intact).

2. ValidateConfigTargets<{ states: TStates }> — a validation type intersected into the config. It walks the state tree, extracts keyof TStates & string as sibling keys at each level, and constrains every target value in on, always, after, onDone, and invoke.onDone/onError/onSnapshot to ValidTarget<TSiblingKeys> (sibling names, .child, #id, sibling.child, or escaped-dot variants).

For setup().createMachine, the existing const TConfig already captures literals — only & ValidateConfigTargets<TConfig> is added.

How it works

ValidTarget<TSiblingKeys> defines valid patterns. ValidateConfigTargets recursively maps over the config, replacing each target position with ValidTarget<siblings>. The intersection with MachineConfig (which accepts string) narrows targets to valid siblings. Invalid literals produce a type error; spread-widened string values pass through via a string extends T ? T escape hatch.

What the TSiblingKeys threading is for

A TSiblingKeys extends string = string parameter was added to TransitionConfigOrTarget, TransitionsConfig, DelayedTransitions, InvokeConfig, StateNodeConfig, StatesConfig, and MachineConfig. All default to string (non-breaking). These replace bare string with ValidTarget<TSiblingKeys> in shorthand target positions. MachineConfig wraps it in DoNotInfer. This infrastructure supports the validation types but doesn't constrain anything on its own — ValidateConfigTargets does the actual enforcement.

Test coverage (typesafe-states.test.ts)

74 tests across createMachine and setup().createMachine. Every "should allow" has a matching "should reject" (@ts-expect-error):

• on: bare string, object-form { target }, array of objects
• always: bare string, object-form, array of objects
• after: bare string, object-form
• onDone (state node): bare string, object-form
• invoke.onDone/invoke.onError: bare string, object-form
• Target patterns: .child, #id, sibling.child, escaped dots ('foo\\.bar')
• Nested states: sibling scoping at each level
• Escape hatches: initial unconstrained, spread variables pass through

pnpm run typecheck and pnpm run test:core pass ☑️

[changeset-bot]

🦋 Changeset detected

Latest commit: 271d473

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 5 packages

Name	Type
xstate	Patch
@xstate/react	Patch
@xstate/solid	Patch
@xstate/svelte	Patch
@xstate/vue	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[davidkpiano]

cc. @Andarist

[wmhina]

Very much needed functionality! Would it also validate below example correctly?

const machine = setup({...}).createMachine({
id: "my-machine",
initial: "STATE_A",
on: {
CANCEL: 'END', // Currently fails during runtime since at the root level there are no sibling states
ERROR: '.END', // Works at runtime
},
states: {
STATE_A: {},
END: { type: 'final' },
},
});

[SandroMaglione]

@wmhina added this check as well in 45a446b (edit: but only when using setup, not with just createMachine 0907838)

[SandroMaglione]

@Andarist how can I make reviewing this PR easier? The changes are mostly all made to pass more type information such that states can be checked.

Anything that I can do to help (description, comments, etc.)?

[davidkpiano]

@SandroMaglione Can you merge main into here and test again? Just updated TS version

[SandroMaglione]

@SandroMaglione Can you merge main into here and test again? Just updated TS version

Done

[Andarist]

Fyi, im in the process of reviewing this

[Andarist]

@SandroMaglione this has type issues in tests right now, could you take a look at this?