module Rooibos::Message

Response from Command.all aggregating parallel execution.

Running multiple commands in parallel needs aggregated results. Without structured responses, handling mixed success/failure requires manual array parsing.

This response collects all child results and provides predicates for success checking. Include Predicates for safe predicate calls.

Use it to handle Command.all completions.

Example

case msg
in { type: :all, envelope: :parallel, results: }
  model.with(outputs: results)
end

Completion sentinel from Command.batch.

Batch commands stream child messages live. When all children finish, this message signals completion. Use it to trigger follow-up actions or UI updates after parallel work completes.

Example

case msg
in Message::Batch
  out.put(:all_done)
in [:progress, pct]
  model.with(progress: pct)
end

Message synthesized by Router when a child fragment bubbles.

When a child fragment returns Command.bubble(message), the Router wraps the inner message in Bubbled and dispatches it through the outward flow (observe, then intercept).

message

The inner message that was bubbled.

Cancellation notification from a canceled command.

Long-running commands respond to cancellation cooperatively. When the runtime signals cancellation, the command finishes current work and sends this message.

Pattern match on Canceled in your update function to clean up state, stop animations, or acknowledge the cancellation.

Use it to handle timer cancellations, aborted HTTP requests, or stopped background processes.

Example

Update = ->(message, model) {
  case message
  in { type: :canceled, command: }
    # Timer was canceled, clear the notification
    model.with(notification: nil)
  in Message::Canceled
    # Generic cancellation handling
    model
  end
}

Error message from a failed command.

Commands run in background threads. Exceptions bubble up silently. Your update function never sees them. Backtraces in STDERR corrupt the TUI.

The runtime catches exceptions and wraps them in Error messages. Pattern match on Error in your update function. Display the error, log it, or recover.

Use it to surface failures from HTTP requests, file I/O, or external processes.

Examples

Update = ->(message, model) {
  case message
  in { type: :error, command:, exception: }
    # Show error toast
    model.with(error: exception.message)
  in Message::Error
    # Store for later inspection
    model.with(last_error: message.exception)
  end
}

Response from an HTTP command.

HTTP requests return status codes, bodies, and headers. Errors may occur. Without structured responses, handling success vs. error requires manual checks on raw data.

This response includes predicates for common checks and deconstructs for pattern matching. Include Predicates for safe predicate calls on any message.

Use it to handle Command.http completions.

Example

case msg
in { type: :http, envelope: :users, status:, body: }
  model.with(users: JSON.parse(body))
in { type: :http, envelope: :users, error: }
  model.with(error:)
end

Message synthesized by Router when keymap uses symbol + route.

When a keymap entry uses a symbol instead of a handler, and specifies a route, the Router creates this message and dispatches it to the child fragment’s UPDATE.

Example

# In parent keymap:
key :down, :move_down, route: :file_list

# Router synthesizes:
Routed.new(envelope: :move_down, event: key_event)

# Child UPDATE matches:
in { type: :routed, envelope: :move_down }
  handle_move_down(model)

Response from a timer command.

Timer commands fire after a delay. Pattern matching in UPDATE distinguishes multiple timers. Without structured responses, timers return bare symbols—hard to extend with elapsed time or other metadata.

This response includes the envelope for routing and elapsed time. Include Predicates for safe predicate calls on any message.

Use it to handle Command.wait or Command.tick completions.

Example

case msg
in { type: :timer, envelope: :dismiss }
  model.with(notification: nil)
in { type: :timer, envelope: :animate, elapsed: }
  model.with(frame: next_frame(elapsed))
end