# Events

For example when receiving an 'UserLoggedIn' event it is likely that you need to fetch some additional data. To facilitate this you can pass the user id in the event.Events are objects passed into the state machine with the intent of causing the FSM to transition to a new state.

You will often model real world events 'Turn Light on' but equally you will create many events that reflect internal events within your software or even somewhat abstract events that simply help your state machine to arrive in the correct state.

Some events won't result in a transition to a new state as the likes of a [guard condition](/transitions/guard-conditions.md) or a [Join](/states/concurrent-states/join.md) may not be satisfied.

To send an event to the state machine you use:

```dart
statemachine.applyEvent(SomeEvent());
```

{% hint style="danger" %}
The call to 'applyEvent' is asynchronous however you MUST NEVER 'await' a call to 'applyEvent' as you risk deadlocking your state machine.
{% endhint %}

## Event Data

You will often find it useful to pass information along with your event. You might have defined a [sideEffect](/transitions/sideeffects.md) that uses data from your event.

```dart
class UserLoggedIn extends Event
{
 int userId;
 UserLoggedIn(this.userId);
}

stateMachine.applyEvent(UserLoggedIn(userid));
```

Within your statemachine you can then define an sideEffect that takes that user id and fetches the user's credit score.

```dart
..state<NoSession>((b) => b
  ..on<UserLoggedIn, HasSession>(sideEffect: (e) => fetchCreditScore(e.userId)) 
```

## Terminology

| Phrase            | Meaning                                                                                                                                                                                                                      |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Applying an Event | An Event is 'applied' to the StateMachine which may cause a state transition.                                                                                                                                                |
| Receive an Event  | An event may be received but not cause a transition to trigger. This may be because its an invalid event for the current state, guard conditions prevent the transition being triggered or a join condition hasn't been met. |
| Trigger an Event  | An event has been received and a valid transition found. The guard condition has evaluated to true and the transition will be executed. The state machine may not however change state.                                      |
| State Transition  | An event was triggered resulting in a change of State.                                                                                                                                                                       |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://fsm2.onepub.dev/events.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.