Events & Actions Syntax

Syntax patterns for event handlers and actions.

Event Handlers

API Event (Public)

on :event_name from @actor (api)
  // actions

The (api) suffix marks this event as externally accessible (e.g., via HTTP endpoint).

Internal Event

on :event_name from @actor
  // actions

Without Source Filter

on :event_name
  // accepts from any sender

Actions

Actions are lines without prefix.

State Transitions

order moves to #state
order transitions to #state
order enters #state
order becomes #state

Context Updates

$variable becomes value
$variable: type becomes value
$variable increases by amount
$variable decreases by amount
$variable adds item
$variable removes item
$variable clears

Event Emission

emit :event to @actor

emit :event to @actor
  with $var1, $var2

emit :event to @actor
  with:
    | field | value |
    | key1  | val1  |
    | key2  | val2  |

emit :event to @actor
  with:
    | field | type   | value |
    | key1  | string | val1  |
    | key2  | number | val2  |

Broadcasting Events

Send an event to all instances of a machine:

// Basic broadcast
emit :event to all @machine

// With state filter
emit :event to all @machine in #state

// Multiple states
emit :event to all @machine in #state1, #state2

// With data
emit :event to all @machine
  with $var1, $var2

// Combined: state filter + data
emit :event to all @machine in #state
  with:
    | field | value |
    | key1  | val1  |

See Broadcasting Events for semantics and best practices.

Custom Actions

send confirmation email
process the payment
validate cart contents
notify warehouse team

API Responses

Basic Reply

reply STATUS with:
  | field | value |

reply STATUS MEANING with:
  | field | value |

Examples:

reply 201 with:
  | id     | $order_id     |
  | status | current_state |

reply 400 bad request with:
  | error | "CART_EMPTY" |

Named Response

reply STATUS with response_name

Example:

reply 201 with order_created
reply 404 with order_error

Binding Transformer

reply STATUS with ^transformer_name

Example:

reply 200 with ^order_report

Nested Fields (Dot Notation)

reply 200 with:
  | customer.name  | $customer_name  |
  | customer.email | $customer_email |
  | shipping.address | $ship_address |

Conditional Fields

reply 200 with:
  | field    | value        | condition                   |
  | id       | $order_id    |                             |
  | tracking | $tracking_no | when order is in #shipped   |

Async Response

reply STATUS async for :event_name:
  | field | value |

With options:

reply 202 async for :generate_report:
  callback: webhook
  url: $callback_url
  | report_id | $report_id |

Async Callback

send callback for :event_name:
  | field | value |

Example:

send callback for :generate_report:
  | report_id | $report_id  |
  | status    | "completed" |

Named Response Definition

response: response_name
  | field | from  |
  | key1  | val1  |
  | key2  | val2  |

Example:

machine: @order

response: order_created
  | field  | from          |
  | id     | $order_id     |
  | status | current_state |
  | total  | $total        |

Scheduled Events

on :event_name
  triggered: schedule expression

  for each item in #state
    ? guard condition
      // actions

Schedule Expressions

triggered: every day at 00:00
triggered: every hour
triggered: every 30 minutes
triggered: every monday at 09:00
triggered: every month on 1st at 00:00

Data Tables

table_name:
  | column1 | column2 | column3 |
  | value1  | value2  | value3  |
  | value4  | value5  | value6  |

With validation:

with:
  | field | value | validation                       |
  | id    | $id   | required, string, valid uuid     |
  | count | $cnt  | required, number, greater than 0 |