Keyword Reference

Complete reference for all keywords in EventFlow.

Structure Keywords

machine:

Defines a machine (actor) in the system.

machine: @order

The machine name must be prefixed with @.

system:

Defines a multi-machine system.

system: e-commerce checkout

scenario:

Defines a feature or capability of a machine.

scenario: checkout flow

A scenario groups related event handlers together.

uses:

Imports machines into a system from separate files.

system: checkout

uses:
  @order from "./order.flow"
  @payment from "./payment.flow"

Event Keywords

on

Defines an internal event handler.

on :payment_success from @payment
  order moves to #paid

Internal events can only be triggered by other machines.

on>

Defines a public/API event handler.

on> :checkout from @customer
  order moves to #processing

API events can be triggered externally (e.g., via HTTP).

from

Specifies the sender of an event.

on :payment_success from @payment
  // Only handles events from @payment

Optional - without from, accepts from any sender:

on :status_update
  // Accepts from any source

emit

Sends an event to another machine.

emit :payment_request to @payment

to

Specifies the target of an emitted event.

emit :notification to @customer

with / with:

Attaches data to an emitted event.

Inline:

emit :payment_request to @payment
  with $order_id, $total

Table format:

emit :order_details to @warehouse
  with:
    | field    | value      |
    | order_id | $order_id  |
    | items    | $items     |

With types:

emit :payment_request to @payment
  with:
    | field    | type   | value     |
    | order_id | string | $order_id |
    | amount   | number | $total    |

Test Keywords

given:

Declarative test setup. Describes the initial state.

Scenario-level:

scenario: checkout

  given:
    @customer is logged in
    cart has items
    $total: number is 1200

Event-level:

on> :checkout from @customer

  given:
    $discount_code is "SUMMER20"

  ? discount is valid
    apply discount

expect:

Defines assertions to verify outcomes.

Event-level:

on> :checkout from @customer
  order moves to #processing

  expect:
    = order is in #processing

Scenario-level:

scenario: complete purchase

  on> :checkout ...
  on :payment_success ...

  expect:
    = order is in #paid
    = @customer received :confirmation

Guard Keywords

otherwise

Default case when no guards match.

? $total > 1000
  priority becomes "high"
? $total > 100
  priority becomes "medium"
otherwise
  priority becomes "low"

Equivalent to empty ?:

? $total > 100
  apply discount
?
  no discount

Scheduled Event Keywords

triggered:

Specifies when a scheduled event should fire.

on :cleanup
  triggered: every day at 00:00

  for each item in #expired
    delete item

Schedule patterns:

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

for each

Iterates over aggregates. Required with triggered:.

on :send_reminders
  triggered: every day at 09:00

  for each order in #pending
    ? created more than 12 hours ago
      emit :reminder to @customer

Can target multiple states:

for each order in #pending, #processing
  send status update

Context Keywords

becomes

Sets a context value.

$total becomes 100
$status becomes "active"

increases by / decreases by

Arithmetic operations.

$total increases by 25
$balance decreases by $amount

adds / removes

Collection operations.

$items adds "Laptop"
$items removes "Mouse"

clears

Empties a collection.

$items clears
$cart clears

is

Used in given: to set initial values.

given:
  $total: number is 100
  order is in #pending

State Keywords

State transition verbs

All equivalent:

• moves to
• transitions to
• enters
• becomes
• changes to

order moves to #paid
order transitions to #approved
payment enters #processing
ticket becomes #closed

is in / is not in

Checks current state.

? order is in #pending
  process order

? order is not in #cancelled
  allow modification

Test File Keywords

test:

Defines a test file for a machine or system.

test: @order
test: system checkout

for scenario:

Targets a specific scenario for testing.

test: @order

  for scenario: checkout
    // tests for checkout scenario

for :event:

Targets transition tests for a specific event handler.

for :checkout:
  empty cart rejected:
    with scenario:
      cart is empty
    = @customer received :error

for :event to @actor:

For system tests, targets an event to a specific machine.

for :checkout to @order:
  guest rejected:
    // test variations

with scenario:

Overrides scenario-level given block.

with scenario:
  cart is empty
  @customer is not logged in

with event:

Overrides event data/payload.

with event:
  payment_method is "bank_transfer"

with given:

Overrides event-level given block.

with given:
  shipping_address is invalid

with context:

Overrides context variables.

with context:
  $total is 5000
  $retry_count is 2

assume:

Controls guard/action behavior for the test.

assume:
  ? cart is valid = false
  process payment throws "Error"
  send email returns { status: "sent" }

observe:

Watches actions without changing behavior.

observe:
  send confirmation email
  update inventory

= send confirmation email was called
= update inventory was not called

after

Specifies divergence point in scenario tests.

payment fails:
  after :checkout
  receive :payment_failed
  = order is in #failed

receive

Specifies event received after divergence.

after :checkout
receive :payment_failed from @payment

then

Continues event sequence after divergence.

after :checkout
receive :payment_failed from @payment
then :payment_success from @payment
= order is in #paid

Complete Keyword List

Keyword	Purpose
machine:	Define a machine/actor
system:	Define a multi-machine system
scenario:	Define a feature/capability
uses:	Import machines into system
on	Internal event handler
on>	Public/API event handler
from	Event source filter
emit	Send event
to	Event target
with / with:	Event data
given:	Test setup (declarative)
expect:	Assertions block
otherwise	Default guard case
triggered:	Schedule for recurring events
for each	Iterate over aggregates
becomes	Set context value
increases by	Add to number
decreases by	Subtract from number
adds	Add to collection
removes	Remove from collection
clears	Empty collection
is	Initial value (in given)
moves to	State transition
is in	State check
test:	Define test file
for scenario:	Target scenario in tests
for :event:	Target transition test
with scenario:	Override scenario given
with event:	Override event data
with given:	Override event given
with context:	Override context
assume:	Control behavior
observe:	Watch actions
after	Divergence point
receive	Alternative event
then	Continue sequence