ExRatatui.Command (ExRatatui v0.7.1)

Commands represent one-shot side effects scheduled by an ExRatatui.App.

They are produced from reducer updates and executed by the ExRatatui server runtime after the new state has been committed and rendered.

Available command constructors:

message/1 — send an immediate self-message to the app process
send_after/2 — schedule a delayed self-message
async/2 — run a zero-arity function in the background and map the result back into an app message
batch/1 — group multiple commands into one return value

Reducer callbacks can return commands from init/1 or update/2 via commands: [...].

Summary

Types

async_fun()

async_mapper()

t()

Functions

async(fun, mapper)

Runs fun in the background and maps its result back into an app message.

batch(commands)

Groups multiple commands into a single return value.

message(message)

Schedules an immediate self-message for the app process.

none()

Returns an empty command list.

send_after(delay_ms, message)

Schedules a delayed self-message for the app process.

Types

async_fun()

@type async_fun() :: (-> term())

async_mapper()

@type async_mapper() :: (term() -> term())

t()

@type t() ::
  %ExRatatui.Command{
    commands: term(),
    delay_ms: term(),
    fun: term(),
    kind: :message,
    mapper: term(),
    message: term()
  }
  | %ExRatatui.Command{
      commands: term(),
      delay_ms: non_neg_integer(),
      fun: term(),
      kind: :after,
      mapper: term(),
      message: term()
    }
  | %ExRatatui.Command{
      commands: term(),
      delay_ms: term(),
      fun: async_fun(),
      kind: :async,
      mapper: async_mapper(),
      message: term()
    }
  | %ExRatatui.Command{
      commands: [t()],
      delay_ms: term(),
      fun: term(),
      kind: :batch,
      mapper: term(),
      message: term()
    }

Functions

async(fun, mapper)

@spec async(async_fun(), async_mapper()) :: t()

Runs fun in the background and maps its result back into an app message.

On success, the mapper receives the function's return value directly. If the function raises or exits, the mapper receives {:error, reason}.

batch(commands)

@spec batch([t()]) :: t()

Groups multiple commands into a single return value.

Nested batches are flattened by the runtime before execution.

message(message)

@spec message(term()) :: t()

Schedules an immediate self-message for the app process.

none()

@spec none() :: []

Returns an empty command list.

Useful when reducer helpers want to return an explicit "no commands" value.

send_after(delay_ms, message)

@spec send_after(non_neg_integer(), term()) :: t()

Schedules a delayed self-message for the app process.

delay_ms may be 0 to enqueue the message on the next turn without waiting.