State

Finite state machine with transitions, guards, actions, context, history, and event listeners

Package: @robinpath/state | Category: Infrastructure | Type: Utility

Authentication

No authentication required. All functions are available immediately.

Use Cases

Use the state module when you need to:

• Create state machine -- Use state.create to perform this operation
• Send event to trigger transition -- Use state.send to perform this operation
• Get current state -- Use state.current to perform this operation
• Get machine context -- Use state.context to perform this operation
• Check if event can be sent -- Use state.can to perform this operation

Quick Reference

Function	Description	Returns
create	Create state machine	{name, current, states, transitions}
send	Send event to trigger transition	{changed, from, current, event}
current	Get current state	Current state
context	Get machine context	Context data
setContext	Set machine context	true
can	Check if event can be sent	true if transition exists
events	Get available events from current state	Event names
is	Check if in specific state	true if matches
reset	Reset to initial state	{current}
history	Get transition history	History entries
addTransition	Add transition at runtime	true
addState	Add state at runtime	true
on	Listen for transitions	true
serialize	Serialize machine to JSON	JSON string
matches	Check if current state matches any	true if matches
destroy	Destroy machine	true
list	List all machines	Machine names

Functions

create

Create state machine

Module: state | Returns: object -- {name, current, states, transitions}

state.create {"name": "light", "states": ["red", "green", "yellow"], "initial": "red", "transitions": [{"from": "red", "to": "green", "event": "next"}]}

Parameter	Type	Required	Description
options	object	Yes	{name, states[], initial, transitions[{from, to, event}], context}

---

send

Send event to trigger transition

Module: state | Returns: object -- {changed, from, current, event}

state.send "next" "light"

Parameter	Type	Required	Description
event	string	Yes	Event name
machine	string	No	Machine name

---

current

Get current state

Module: state | Returns: string -- Current state

state.current "light"

Parameter	Type	Required	Description
machine	string	No	Machine name

---

context

Get machine context

Module: state | Returns: any -- Context data

state.context "light"

Parameter	Type	Required	Description
machine	string	No	Machine name

---

setContext

Set machine context

Module: state | Returns: boolean -- true

state.setContext {"count": 0} "light"

Parameter	Type	Required	Description
context	any	Yes	New context
machine	string	No	Machine name

---

can

Check if event can be sent

Module: state | Returns: boolean -- true if transition exists

state.can "next" "light"

Parameter	Type	Required	Description
event	string	Yes	Event name
machine	string	No	Machine name

---

events

Get available events from current state

Module: state | Returns: array -- Event names

state.events "light"

Parameter	Type	Required	Description
machine	string	No	Machine name

---

is

Check if in specific state

Module: state | Returns: boolean -- true if matches

state.is "red" "light"

Parameter	Type	Required	Description
state	string	Yes	State name
machine	string	No	Machine name

---

reset

Reset to initial state

Module: state | Returns: object -- {current}

state.reset "light"

Parameter	Type	Required	Description
machine	string	No	Machine name

---

history

Get transition history

Module: state | Returns: array -- History entries

state.history "light" 10

Parameter	Type	Required	Description
machine	string	No	Machine name
limit	number	No	Max entries

---

addTransition

Add transition at runtime

Module: state | Returns: boolean -- true

state.addTransition {"from": "yellow", "to": "red", "event": "next"} "light"

Parameter	Type	Required	Description
transition	object	Yes	{from, to, event}
machine	string	No	Machine name

---

addState

Add state at runtime

Module: state | Returns: boolean -- true

state.addState "flashing" "light"

Parameter	Type	Required	Description
state	string	Yes	State name
machine	string	No	Machine name

---

on

Listen for transitions

Module: state | Returns: boolean -- true

state.on "transition" $handler "light"

Parameter	Type	Required	Description
event	string	Yes	Event type (transition)
handler	string	Yes	Callback (from, to, event)
machine	string	No	Machine name

---

serialize

Serialize machine to JSON

Module: state | Returns: string -- JSON string

state.serialize "light"

Parameter	Type	Required	Description
machine	string	No	Machine name

---

matches

Check if current state matches any

Module: state | Returns: boolean -- true if matches

state.matches ["red", "yellow"] "light"

Parameter	Type	Required	Description
states	array	Yes	State names
machine	string	No	Machine name

---

destroy

Destroy machine

Module: state | Returns: boolean -- true

state.destroy "light"

Parameter	Type	Required	Description
machine	string	No	Machine name

---

list

List all machines

Module: state | Returns: array -- Machine names

state.list

Parameter	Type	Required	Description
(none)		No	Call with no arguments

---

Error Handling

All functions throw on failure. Common errors:

Error	Cause
State machine "..." not found	Check the error message for details

@desc "Create and validate result"
do
  set $result as state.create {"name": "light", "states": ["red", "green", "yellow"], "initial": "red", "transitions": [{"from": "red", "to": "green", "event": "next"}]}
  if $result != null
    print "Success"
  else
    print "No result"
  end
enddo

Recipes

1. List and iterate

Retrieve all items and loop through them.

@desc "List and iterate results"
do
  set $result as state.list
  each $item in $result
    print $item
  end
enddo

2. Create a new item with create

Create a new resource and capture the result.

set $result as state.create {"name": "light", "states": ["red", "green", "yellow"], "initial": "red", "transitions": [{"from": "red", "to": "green", "event": "next"}]}
print "Created: " + $result

3. Check before creating

List existing items and only create if needed.

@desc "List and create"
do
  set $existing as state.list
  if $existing == null
    state.create {"name": "light", "states": ["red", "green", "yellow"], "initial": "red", "transitions": [{"from": "red", "to": "green", "event": "next"}]}
    print "Item created"
  else
    print "Item already exists"
  end
enddo

4. Multi-step State workflow

Chain multiple state operations together.

@desc "Create, send, and more"
do
  set $r_create as state.create {"name": "light", "states": ["red", "green", "yellow"], "initial": "red", "transitions": [{"from": "red", "to": "green", "event": "next"}]}
  set $r_send as state.send "next" "light"
  set $r_current as state.current "light"
  print "All operations complete"
enddo

5. Safe create with validation

Check results before proceeding.

@desc "Create and validate result"
do
  set $result as state.create {"name": "light", "states": ["red", "green", "yellow"], "initial": "red", "transitions": [{"from": "red", "to": "green", "event": "next"}]}
  if $result != null
    print "Success: " + $result
  else
    print "Operation returned no data"
  end
enddo

Related Modules

• json -- JSON module for complementary functionality