module Rooibos::Message
Messages sent from commands to update functions.
All built-in response types live here. Each includes the Predicates mixin for safe predicate calls.
Constants
- All
-
Response from
Command.allaggregating 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
Predicatesfor safe predicate calls.Use it to handle
Command.allcompletions.Example
case msg in { type: :all, envelope: :parallel, results: } model.with(outputs: results) end
- Batch
-
Completion sentinel from
Command.batch.Batchcommands 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
- Bubbled
-
Messagesynthesized byRouterwhen a child fragment bubbles.When a child fragment returns
Command.bubble(message), theRouterwraps the inner message inBubbledand dispatches it through the outward flow (observe, then intercept).- message
-
The inner message that was bubbled.
- Canceled
-
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
Canceledin 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
-
Errormessage 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
Errormessages. Pattern match onErrorin 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 }
- HttpResponse
-
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
Predicatesfor safe predicate calls on any message.Use it to handle
Command.httpcompletions.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
- Routed
-
Messagesynthesized byRouterwhen keymap uses symbol + route.When a keymap entry uses a symbol instead of a handler, and specifies a route, the
Routercreates 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) - Timer
-
Response from a timer command.
Timercommands 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
Predicatesfor safe predicate calls on any message.Use it to handle
Command.waitorCommand.tickcompletions.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
Public Class Methods
Source
# File lib/rooibos/message.rb, line 27 def self.===(other) other.class.name&.start_with?("Rooibos::Message::") end
Matches built-in framework message types for case/when dispatch.
Returns true only for classes under Rooibos::Message::. Rejects key events and user-defined message classes.
Example
case message when Rooibos::Message handle_command_response(message) when RatatuiRuby::Event::Key handle_key(message) end