feat: add guard inspection via _guards property on microstep events #5444
+1,499
−9,072
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
🦋 Changeset detectedLatest commit: 1d978fe The changes in this PR will be included in the next version bump. This PR includes changesets to release 5 packages
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 |
cevr
force-pushed
the
feat/guard-inspection-events
branch
from
f320191 to
0bfbe8f
Compare
Add a new `@xstate.guard` inspection event type that is emitted when guards are evaluated during state transitions. This provides visibility into the guard evaluation process, making it easier to debug transition decisions. The event includes: - `guard.type`: The guard name (or '<inline>' for inline guards) - `guard.params`: The parameters passed to the guard - `result`: Whether the guard passed (true) or failed (false) This is useful for debugging questions like "why did the machine not transition to state X?" by showing which guards passed or failed. Example output: [machine-id] guard: canSubmit → false [machine-id] guard: hasValidInput → true Implementation details: - Added `InspectedGuardEvent` type to inspection.ts - Modified `evaluateGuard` to accept optional `actorScope` parameter - Threaded `actorScope` through the transition resolution call chain: - macrostep → selectTransitions → getTransitionData → transitionNode → StateNode.next → evaluateGuard - Guard events are only emitted when actorScope is provided (maintaining backwards compatibility) Co-Authored-By: Claude <noreply@anthropic.com>
cevr
force-pushed
the
feat/guard-inspection-events
branch
from
0bfbe8f to
55b808c
Compare
davidkpiano
reviewed
Jan 9, 2026
| type: '@xstate.microstep'; | ||
| event: AnyEventObject; // { type: string, ... } | ||
| snapshot: Snapshot<unknown>; | ||
| _transitions: AnyTransitionDefinition[]; |
Member
There was a problem hiding this comment.
Instead of adding a new event, I would strongly recommend either enhancing _transitions with guard params (since if the transition is in this array, it was taken) and/or by adding _guards here instead.
Contributor
Author
There was a problem hiding this comment.
gotcha, i think the problem with _transitions is that it only shows the passed transitions - im partial to the _guards
Instead of emitting separate @xstate.guard events, guard evaluations are now collected and included as a _guards array on @xstate.microstep events. This keeps guard information correlated with their transitions. Co-Authored-By: Claude <noreply@anthropic.com>
cevr
changed the title
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary
This PR adds guard evaluation visibility to
@xstate.microstepinspection events via a new_guardsproperty. This provides insight into the guard evaluation process, making it easier to debug transition decisions.Motivation
When debugging state machines, it's often difficult to understand why a transition didn't happen. The existing inspection events (
@xstate.event,@xstate.action,@xstate.snapshot,@xstate.microstep) don't provide insight into guard evaluation - only the@xstate.microstepshows transitions that passed, but doesn't show which guards failed.This is particularly problematic when you have multiple guarded transitions for the same event and want to understand why a specific path wasn't taken. For example:
Without guard inspection, you can't easily tell which guards passed or failed.
Solution
Add a
_guardsproperty to@xstate.microstepinspection events that contains an array of all guard evaluations:This approach keeps guard information correlated with their transitions rather than emitting separate events.
Implementation
_guardsarray type toInspectedMicrostepEventininspection.tsevaluateGuard()inguards.tsto return guard metadata alongside the resultstateUtils.tsBreaking Changes
None - the
_guardsproperty is additive and existing code continues to work without modification.Test Plan
🤖 Generated with Claude Code