Skip to content

State

A State defines a named state of an entity. It references a record that defines the data structure for the state, and optionally contains handlers and invariants that apply while the entity is in that state.

A state is typed by a record, not by any type

As of RIDDL 2.0, state X of … takes a record reference specifically. A state is record-shaped data, so its data type must be a record rather than a plain type or a message. In 1.x any type reference was accepted.

An entity can have multiple state definitions. When an entity has multiple states with their own handlers, it naturally models a Finite State Machine —each state responds to messages differently. Use the finite state machine option to make this intent explicit.

States are branches in the AST, meaning they can contain their own definitions. The morph statement transitions an entity from one state to another, changing which handlers are active.

Syntax

state ActiveOrder of record ActiveOrderData is {
  invariant TotalIsPositive is total > Zero

  handler ActiveOrderHandler is {
    on command CancelOrder { ??? }
    on command ShipOrder { ??? }
  }
}

The state body is optional — a state can also be defined simply as:

state ActiveOrder of record ActiveOrderData

Every state must have a handler somewhere

State 'X' in Entity 'Y' has no handlers is an Error (entity-state-no-handlers), so a state with no body is only valid when the entity declares a handler that covers it. Handlers may sit at either level, and an entity may carry both: a state-scoped handler for behavior that differs by state, and an entity-level handler for behavior that does not.

Where an Entity Starts

An entity has no initial state. It is created without one, and its on init clause — an entity-level clause, run once at creation — morphs it into the state it starts in:

entity Order is {
  handler OrderLifecycle is {
    on init(start: PendingData) is { morph entity Order to state Pending with start }
    on command CancelOrder { ??? }
  }
  state Pending of record PendingData is { ??? }
  state Active  of record ActiveData  is { ??? }
  state Shipped of record ShippedData is { ??? }
}

Because on init takes the creation arguments, it can choose among states, and which state is declared first decides nothing — reordering them is safe.

initial state is deprecated (since 2.8.0)

Through 2.7, an entity started in the state marked initial, or else the first one declared. Both still work, with that meaning, until 3.0: an initial state draws entity-initial-state-marker, and an entity with states but no on init that morphs draws entity-init-no-morph. Two initial states are an Error (entity-multiple-initial-states).

initial on a handler is unaffected: it picks which of a state's handlers is live on entry. See Handler.

Entry Actions

A state's on entry clause runs each time a morph moves the entity into that state — but not at creation, not for a morph into the state it is already in, and never on replay or rehydration.

State-Scoped Invariants

A state body may hold invariants constraining that state's record data. This is what lets different states carry different rules — an open account may hold any non-negative balance, while a closed one must hold exactly nothing.

Transitions

The morph statement transitions an entity from one state to another, changing which handlers are active. Its payload is a record — the new state's data — not the message that triggered the transition:

on ship: command ShipOrder {
  morph entity Order to state Order.Shipped
    with record ShippedData(ship.trackingNumber)
}

Occurs In

Contains

flowchart TD
    State(["State"]) --> Handler
    State --> Invariant
    State --> Comment
  • Handler — how the entity behaves while in this state
  • Invariant — conditions that must hold in this state
  • Comment