← Back to Documentation

Actions

Actions are the verbs of ARO. They describe what operation to perform on data. This chapter covers all built-in actions and how to use them effectively.

Action Categories

ARO actions are organized by their semantic role - the direction of data flow:

Role	Direction	Purpose
REQUEST	External → Internal	Bring data into the feature set
OWN	Internal → Internal	Transform data within the feature set
RESPONSE	Internal → External	Send results back
EXPORT	Internal → External	Publish or persist data
FILE	Internal ↔ File System	File and directory operations
SERVICE	Internal ↔ Services	Manage runtime services
STATE	Internal State	State machine transitions
TEST	Verification	Testing and assertions

REQUEST Actions

These actions bring data from external sources into your feature set.

Extract

Pull data from a structured source:

<Extract> the <user-id> from the <request: parameters>.
<Extract> the <body> from the <request: body>.
<Extract> the <email> from the <user: email>.
<Extract> the <items> from the <order: lineItems>.

Retrieve

Fetch data from a repository or data store:

<Retrieve> the <user> from the <user-repository>.
<Retrieve> the <user> from the <user-repository> where id = <user-id>.
<Retrieve> the <orders> from the <order-repository> where status = "pending".

Request

Make HTTP requests to external APIs:

<Request> the <data> from "https://api.example.com/resource".
<Request> the <users> from <UserAPI: GET /users>.
<Request> the <weather> from <WeatherAPI: GET /forecast?city=${city}>.

Read

Read from files:

<Read> the <content> from the <file: "./data.txt">.
<Read> the <config: JSON> from the <file: "./config.json">.
<Read> the <data: bytes> from the <file: "./image.png">.

Request

Make HTTP requests with method control:

(* GET request *)
<Request> the <data> from the <api-url>.

(* POST request with data *)
<Request> the <result> to the <api-url> with <payload>.

(* Explicit method *)
<Request> the <result> via PUT the <url> with <update>.

Exec

Execute shell commands (ARO-0033):

<Exec> the <result> for the <command> with "ls -la".
<Exec> the <output> on the <system> with {
    command: "npm install",
    workingDirectory: "/app",
    timeout: 60000
}.

OWN Actions

These actions create or transform data within your feature set.

Create

Create new data structures:

<Create> the <user> with <user-data>.
<Create> the <response> with { message: "Success", code: 200 }.
<Create> the <order> with {
    items: <items>,
    total: <total>,
    customer: <customer-id>
}.

Compute

Perform calculations:

<Compute> the <total> for the <items>.
<Compute> the <hash> for the <password>.
<Compute> the <tax> for the <subtotal>.
<Compute> the <average> for the <values>.

Transform

Convert or map data:

<Transform> the <dto> from the <entity>.
<Transform> the <response> from the <data>.
<Transform> the <updated-user> from the <user> with <updates>.

Validate

Check data against rules:

<Validate> the <user-data> for the <user-schema>.
<Validate> the <email> for the <email-pattern>.

if <validation> is failed then {
    <Return> a <BadRequest: status> with <validation: errors>.
}

Compare

Compare values:

<Compare> the <password-hash> against the <stored-hash>.
<Compare> the <signature> against the <expected-signature>.

Update

Modify existing data:

<Update> the <user> with <changes>.
<Update> the <order: status> with "shipped".

Sort

Order collections:

<Sort> the <sorted-users> from the <users> by <name>.
<Sort> the <ordered> from the <items> by <price> with "desc".

Split

Split strings by regex delimiter (ARO-0037):

<Split> the <parts> from the <csv-line> by /,/.
<Split> the <words> from the <sentence> by /\s+/.
<Split> the <tokens> from the <code> by /[;,]+/.

Merge

Combine data structures:

<Merge> the <existing-user> with <update-data>.
<Merge> the <combined> from <list1> with <list2>.

Filter

Select matching elements from collections:

<Filter> the <active-users> from the <users> where <status> = "active".
<Filter> the <expensive> from the <products> where <price> > 100.

Map

Transform collection elements:

<Map> the <names> from the <users: name>.
<Map> the <emails> from the <customers: email>.

Reduce

Aggregate collections:

<Reduce> the <total> from the <items> with sum(<price>).
<Reduce> the <count> from the <orders> with count().

RESPONSE Actions

These actions send results back from your feature set.

Return

Return a result with status:

(* Success responses *)
<Return> an <OK: status> with <data>.
<Return> a <Created: status> with <resource>.
<Return> a <NoContent: status> for the <deletion>.

(* Error responses *)
<Return> a <BadRequest: status> with <errors>.
<Return> a <NotFound: status> for the <missing: resource>.
<Return> a <Forbidden: status> for the <unauthorized: access>.

Status Codes:

Status	HTTP Code	Use Case
OK	200	Successful GET, PUT, PATCH
Created	201	Successful POST creating resource
NoContent	204	Successful DELETE
BadRequest	400	Invalid input
Unauthorized	401	Missing/invalid auth
Forbidden	403	Insufficient permissions
NotFound	404	Resource not found
InternalError	500	Server error

Throw

Throw an error:

<Throw> a <ValidationError> for the <invalid: input>.
<Throw> a <NotFoundError> for the <missing: user>.
<Throw> an <AuthError> with "Invalid credentials".

EXPORT Actions

These actions publish data or send to external systems.

Store

Save to a repository:

<Store> the <user> into the <user-repository>.
<Store> the <order> into the <order-repository>.
<Store> the <log-entry> into the <audit-log>.

Publish

Make variables globally available:

<Publish> as <current-user> <user>.
<Publish> as <app-config> <config>.

Log

Write to logs:

<Log> "User logged in" to the <console>.
<Log> <error> to the <console>.

Send

Send data to external destinations:

<Send> the <email> to the <user: email>.
<Send> the <notification> to the <push-service>.
<Send> the <data> to the <connection>.

Emit

Emit domain events:

<Emit> a <UserCreated: event> with <user>.
<Emit> an <OrderPlaced: event> with <order>.
<Emit> a <PaymentProcessed: event> with <payment>.

Delete

Remove data:

<Delete> the <user> from the <user-repository> where id = <user-id>.
<Delete> the <file: "./temp.txt">.

Write

Write content to files:

<Write> the <content> to the <file: "./output.txt">.
<Write> the <data: JSON> to the <file: "./data.json">.

Append

Append content to files:

<Append> the <log-line> to the <file: "./app.log">.
<Append> the <entry> to the <file: "./data.csv">.

File Operations

Actions for file system operations (ARO-0036).

List

List directory contents:

<Create> the <dir-path> with "./uploads".
<List> the <entries> from the <directory: dir-path>.
<List> the <aro-files> from the <directory: src-path> matching "*.aro".
<List> the <all-files> from the <directory: path> recursively.

Stat

Get file or directory metadata:

<Stat> the <info> for the <file: "./document.pdf">.
<Stat> the <dir-info> for the <directory: "./src">.

Exists

Check if a file or directory exists:

<Exists> the <found> for the <file: "./config.json">.
<Exists> the <dir-exists> for the <directory: "./output">.

CreateDirectory

Create directories (with parent directories):

<CreateDirectory> the <output-dir> to the <path: "./output/reports/2024">.

Copy

Copy files or directories:

<Copy> the <file: "./template.txt"> to the <destination: "./copy.txt">.
<Copy> the <directory: "./src"> to the <destination: "./backup/src">.

Move

Move or rename files and directories:

<Move> the <file: "./draft.txt"> to the <destination: "./final.txt">.
<Move> the <directory: "./temp"> to the <destination: "./processed">.

Service Actions

These actions interact with runtime services.

Start

Start a service:

<Start> the <http-server> on port 8080.
<Start> the <scheduler>.

Watch

Monitor a directory:

<Watch> the <directory: "./uploads"> as <file-monitor>.

Listen / Connect

<Listen> on port 9000 as <socket-server>.
<Connect> to <host: "localhost"> on port 5432 as <database>.

Close

Close connections:

<Close> the <connection>.
<Close> the <socket-server>.

Broadcast

Send to all connections:

<Broadcast> the <message> to the <socket-server>.
<Broadcast> the <notification> to the <chat-server> with "User joined".

Call

Call external APIs (ARO-0016):

<Call> the <result> via <UserAPI: POST /users> with <user-data>.
<Call> the <response> via <PaymentAPI: POST /charge> with <payment>.

Keepalive

Keep application running for events (ARO-0028):

<Keepalive> the <application> for the <events>.

Blocks until shutdown signal (SIGINT/SIGTERM), essential for servers and file watchers.

State Actions

Actions for state machine transitions.

Accept

Accept a state transition:

<Accept> the <order: placed>.
<Accept> the <payment: approved>.

Test Actions

Actions for testing and assertions.

Given / When / Then

BDD-style test structure:

<Given> the <user> with { name: "Test" }.
<When> the <action> is performed.
<Then> the <result> should be <expected>.

Assert

Assert conditions:

<Assert> the <value> equals <expected>.
<Assert> the <list> contains <item>.

Action Patterns

Extract-Process-Return

Common pattern for request handlers:

(createUser: User API) {
    (* Extract *)
    <Extract> the <user-data> from the <request: body>.

    (* Process *)
    <Validate> the <user-data> for the <user-schema>.
    <Create> the <user> with <user-data>.
    <Store> the <user> into the <user-repository>.

    (* Return *)
    <Return> a <Created: status> with <user>.
}

Extract-Emit Pattern

Pattern for event-driven updates:

(createOrder: Order API) {
    <Extract> the <order-data> from the <request: body>.
    <Create> the <order> with <order-data>.
    <Store> the <order> into the <order-repository>.

    (* Emit for other handlers *)
    <Emit> an <OrderCreated: event> with <order>.

    <Return> a <Created: status> with <order>.
}

Next Steps

Feature Sets - How data flows through actions
Creating Custom Actions - Extend ARO with your own actions