Support Dynamic Target States in Actions (Allow Multiple Possible Outcomes at Runtime)

[QingShuiHU]

Currently, Spring Statemachine enforces that an action (transition) must have exactly one predefined target state at registration time.

This design works for simple workflows but causes significant issues in real-world scenarios:

• One Action, Multiple Possible Outcomes

  For example, a PAYMENT action may result in different states depending on runtime conditions:

  • Insufficient balance → INSUFFICIENT_BALANCE
  • Network error → RETRY_PENDING
  • Unexpected exception → FAILED

  Being forced to register multiple separate transitions for each outcome leads to:

  • Code duplication – same action logic split into multiple handlers
  • Scattered business logic – harder to maintain and reason about
  • Artificial complexity – many transitions are needed just to handle one real-world action

• Outcome is Known Only at Runtime

  Often, the final target state can only be determined after the action finishes execution.

  Predefining a single target state at configuration time does not reflect this reality.

Feature Request:

Allow a single transition action to determine its actual target state dynamically at runtime, e.g.:

transition()
    .source(State.PROCESSING)
    .event(Event.PAY)
    .action(ctx -> {
        if (!hasBalance(ctx)) return State.INSUFFICIENT_BALANCE;
        if (!networkAvailable()) return State.RETRY_PENDING;
        return State.SUCCESS;
    });

This would:

• Keep business logic centralized (one action → multiple outcomes)
• Reduce redundancy and improve readability
• Better model real-world processes where actions have multiple possible results

Reference Implementation:

I built a lightweight state machine that already supports this idea: simple state machine.

It has two core benefits:

1. Multiple Outcomes from a Single Action

   The same state + event pair can lead to different target states depending on runtime conditions, without splitting the action logic.

2. Automatic Visualization (planned)

   It aims to automatically build a state-event-action diagram directly from code, so developers can quickly see which code is executed for a given event.

I hope this perspective can be helpful to the Spring Statemachine project. It would be great if the Spring team and community members could take a look at this idea (and my reference implementation) and share feedback or suggestions.

I believe supporting runtime-determined target states could make Spring Statemachine more expressive and easier to use for many developers.

This feature would make the library easier to use, closer to real-world needs, and encourage more developers to adopt and contribute.