Guide Repositories

Repositories

Repositories provide persistent in-memory storage that survives across HTTP requests and event handlers. Unlike regular variables which are scoped to a single feature set execution, repositories maintain state for the lifetime of the application.

Overview

In ARO, each HTTP request creates a fresh execution context. Variables defined in one request aren't available in another:

(* This won't work - count resets on each request *)
(GET /count: Counter API) {
    Create the <count> with 0.
    Compute the <new-count> from <count> + 1.
    Return an <OK: status> with <new-count>.
}

Repositories solve this by providing shared storage:

(POST /increment: Counter API) {
    Retrieve the <counts> from the <counter-repository>.
    Compute the <current> from <counts: length>.
    Store the <current> into the <counter-repository>.
    Return an <OK: status> with <current>.
}

(GET /count: Counter API) {
    Retrieve the <counts> from the <counter-repository>.
    Compute the <total> from <counts: length>.
    Return an <OK: status> with { count: <total> }.
}

Repository Naming Convention

Repository names must end with -repository. This is how ARO distinguishes repositories from regular variables:

(* These are repositories *)
<user-repository>
<message-repository>
<order-repository>
<session-repository>

(* These are NOT repositories - just regular variables *)
<users>
<messages>
<user-data>

The naming convention:

• Makes repositories visually distinct in code
• Enables automatic persistence by the runtime
• Follows ARO's self-documenting code philosophy

Storing Data

Use the Store action to save data to a repository:

Store the <data> into the <name-repository>.

Preposition Variants

All of these are equivalent:

Store the <user> into the <user-repository>.
Store the <user> in the <user-repository>.
Store the <user> to the <user-repository>.

Storage Semantics

Repositories use list-based storage. Each store operation appends to the list:

(* First request *)
Store the <user1> into the <user-repository>.
(* Repository: [user1] *)

(* Second request *)
Store the <user2> into the <user-repository>.
(* Repository: [user1, user2] *)

(* Third request *)
Store the <user3> into the <user-repository>.
(* Repository: [user1, user2, user3] *)

Example: Storing Messages

(postMessage: Chat API) {
    Extract the <data> from the <request: body>.
    Extract the <text> from the <data: message>.
    Extract the <author> from the <data: author>.

    Create the <message> with {
        text: <text>,
        author: <author>,
        timestamp: now
    }.

    Store the <message> into the <message-repository>.

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

Retrieving Data

Use the Retrieve action to fetch data from a repository:

Retrieve the <items> from the <name-repository>.

Return Value

• Returns a list of all stored items
• Returns an empty list [] if the repository is empty or doesn't exist
• Never throws an error for missing repositories

Example: Retrieving All Messages

(getMessages: Chat API) {
    Retrieve the <messages> from the <message-repository>.
    Return an <OK: status> with { messages: <messages> }.
}

Filtered Retrieval

Use where to filter results:

(getUserById: User API) {
    Extract the <id> from the <pathParameters: id>.
    Retrieve the <user> from the <user-repository> where id = <id>.
    Return an <OK: status> with <user>.
}

Single Item Retrieval

Use specifiers to retrieve a single item from a repository:

(* Get the most recently stored item *)
Retrieve the <message> from the <message-repository: last>.

(* Get the first stored item *)
Retrieve the <message> from the <message-repository: first>.

(* Get by numeric index - 0 = most recent *)
Retrieve the <latest> from the <message-repository: 0>.
Retrieve the <second-latest> from the <message-repository: 1>.

Numeric indices count from most recently added (0 = newest, 1 = second newest, etc.).

This is useful when you only need one item, like the latest message in a chat:

(getLatestMessage: Chat API) {
    Retrieve the <message> from the <message-repository: last>.
    Return an <OK: status> with { message: <message> }.
}

If the repository is empty, an empty string is returned.

Business Activity Scoping

Repositories are scoped to their business activity. Feature sets with the same business activity share repositories:

(* Same business activity: "Chat API" *)
(* These share the same <message-repository> *)

(postMessage: Chat API) {
    Store the <message> into the <message-repository>.
    Return a <Created: status>.
}

(getMessages: Chat API) {
    Retrieve the <messages> from the <message-repository>.
    Return an <OK: status> with <messages>.
}

(deleteMessage: Chat API) {
    (* Same repository as above *)
    Retrieve the <messages> from the <message-repository>.
    (* ... *)
}

Different Business Activities = Different Repositories

(* Business activity: "Chat API" *)
(postMessage: Chat API) {
    Store the <msg> into the <message-repository>.
}

(* Business activity: "Admin API" - DIFFERENT repository! *)
(postAuditLog: Admin API) {
    (* This <message-repository> is separate from Chat API's *)
    Store the <log> into the <message-repository>.
}

This scoping:

• Prevents accidental data leakage between domains
• Allows reuse of generic repository names
• Enforces domain boundaries

Complete Example: Simple Chat Application

main.aro

(Application-Start: Simple Chat) {
    Log "Starting Simple Chat..." to the <console>.
    Start the <http-server> for the <contract>.
    Keepalive the <application> for the <events>.
    Return an <OK: status> for the <startup>.
}

api.aro

(* GET /status - Return the last message *)
(getStatus: Simple Chat API) {
    Retrieve the <message> from the <message-repository: last>.
    Return an <OK: status> with { message: <message> }.
}

(* POST /status - Store a new message *)
(postStatus: Simple Chat API) {
    Extract the <message> from the <body: message>.

    Store the <message> into the <message-repository>.

    Return a <Created: status> with { message: <message> }.
}

Testing

# Post a message
curl -X POST http://localhost:8080/status \
  -H 'Content-Type: application/json' \
  -d '{"message":"Hello!"}'
# Response: {"message":"Hello!"}

# Post another message
curl -X POST http://localhost:8080/status \
  -H 'Content-Type: application/json' \
  -d '{"message":"World!"}'
# Response: {"message":"World!"}

# Get the last message
curl http://localhost:8080/status
# Response: {"message":"World!"}

Deleting from Repositories

Use the Delete action with a where clause to remove items from a repository:

Delete the <user> from the <user-repository> where id = <userId>.

Example: Deleting a User

(deleteUser: User API) {
    Extract the <userId> from the <pathParameters: id>.
    Delete the <user> from the <user-repository> where id = <userId>.
    Return an <OK: status> with { deleted: <userId> }.
}

The deleted item(s) are bound to the result variable (user in this example).

Repository Observers

Repository observers are feature sets that automatically react to repository changes. They receive access to both old and new values, enabling audit logging, synchronization, and reactive patterns.

Observer Syntax

Create an observer by naming your feature set's business activity as {repository-name} Observer:

(Audit Changes: user-repository Observer) {
    Extract the <changeType> from the <event: changeType>.
    Extract the <newValue> from the <event: newValue>.
    Extract the <oldValue> from the <event: oldValue>.

    Log <changeType> to the <console>.
    Return an <OK: status> for the <audit>.
}

Event Payload

Observers receive an event with the following fields:

Field	Type	Description
repositoryName	String	The repository name (e.g., "user-repository")
changeType	String	"created", "updated", or "deleted"
entityId	String?	ID of the changed entity (if available)
newValue	Any?	The new value (nil for deletes)
oldValue	Any?	The previous value (nil for creates)
timestamp	Date	When the change occurred

Change Types

Observers are triggered for three types of changes:

• created: New item stored (no previous value existed with matching ID)
• updated: Existing item modified (matched by ID)
• deleted: Item removed using Delete action

When Observers Fire

Observers fire only for actual changes to the repository:

Change Type	Trigger Condition	Observer Fires?
created	New entry stored (value didn't exist)	Yes
updated	Existing entry modified (matched by ID)	Yes
deleted	Entry removed via Delete action	Yes
duplicate	Same value stored again	No

Important: Storing a duplicate value is a no-op — the repository ignores it and no observer event fires. This provides automatic deduplication without manual checks.

(* First store: observer fires with changeType = "created" *)
Store the <url> into the <crawled-repository>.

(* Second store of same URL: no observer fires *)
Store the <url> into the <crawled-repository>.

Store OR Emit, Not Both

A common anti-pattern is combining Store with Emit in the same handler:

(* Anti-pattern: Store + Emit *)
Store the <url> into the <crawled-repository>.
Emit a <ProcessUrl: event> with { url: <url> }.  (* Redundant! *)

Prefer observers instead. Handlers that store data shouldn't also emit events for the same logical action — that's what repository observers are for:

(Queue URL: QueueUrl Handler) {
    (* Just store — observer handles the rest *)
    Store the <url> into the <crawled-repository>.
    Return an <OK: status>.
}

(Process New URLs: crawled-repository Observer) {
    (* Only fires for genuinely new URLs *)
    Extract the <url> from the <event: newValue>.
    Emit a <ProcessUrl: event> with { url: <url> }.
    Return an <OK: status>.
}

This pattern provides:

• Separation of concerns: Handlers store, observers react
• Automatic deduplication: Observers only fire for new entries
• Extensibility: Add more observers without changing the handler

Example: Tracking User Changes

(Track User Changes: user-repository Observer) {
    Extract the <changeType> from the <event: changeType>.
    Extract the <entityId> from the <event: entityId>.

    Compare the <changeType> equals "updated".

    Extract the <oldName> from the <event: oldValue: name>.
    Extract the <newName> from the <event: newValue: name>.

    Compute the <message> from "User " + <entityId> + " renamed from " + <oldName> + " to " + <newName>.
    Log <message> to the <console>.

    Return an <OK: status> for the <tracking>.
}

Multiple Observers

You can have multiple observers for the same repository:

(* Audit logging observer *)
(Log All Changes: user-repository Observer) {
    Extract the <changeType> from the <event: changeType>.
    Log <changeType> to the <console>.
    Return an <OK: status>.
}

(* Email notification observer *)
(Notify Admin: user-repository Observer) {
    Extract the <changeType> from the <event: changeType>.
    Compare the <changeType> equals "deleted".
    Send the <notification> to the <admin-email>.
    Return an <OK: status>.
}

Lifetime and Persistence

Application Lifetime

Repositories persist for the lifetime of the application:

• Created when first accessed
• Survive across all HTTP requests
• Cleared when application restarts

No Disk Persistence

Repositories are in-memory only:

• Data is lost when the application stops
• No external database required
• Fast and simple for prototyping

For persistent storage, use a database integration (future ARO feature).

Best Practices

Use Descriptive Repository Names

(* Good - clear what's stored *)
<user-repository>
<pending-order-repository>
<session-token-repository>

(* Avoid - too generic *)
<data-repository>
<stuff-repository>

One Repository Per Domain Concept

(* Good - separate repositories for different concepts *)
<user-repository>
<order-repository>
<product-repository>

(* Avoid - mixing concepts *)
<everything-repository>

Keep Repository Data Simple

Store simple, serializable data:

(* Good - simple object *)
Create the <user> with {
    id: <id>,
    name: <name>,
    email: <email>
}.
Store the <user> into the <user-repository>.

(* Avoid - complex nested structures *)
Store the <entire-request-context> into the <debug-repository>.

Next Steps

• Variables - Variable scoping and data flow
• Events - Event-driven communication
• Services - External service integration