Commands and Effects

Commands are pure data returned from update/2 and init/1. The runtime executes them after the update cycle completes. They are how your app triggers side effects: background work, focus changes, window operations, platform effects, and more.

See Plushie.Command for full API docs and Plushie.Effect for platform effect functions.

Returning commands

update/2 and init/1 support three return forms:

# Bare model (no commands)
def update(model, _event), do: model

# Model + single command
def update(model, %WidgetEvent{type: :click, id: "save"}) do
  {model, Command.focus("editor")}
end

# Model + command list
def update(model, %WidgetEvent{type: :click, id: "export"}) do
  {model, [
    Effect.file_save(:export, title: "Export"),
    Effect.notification(:notify, "Exporting", "Saving to file...")
  ]}
end

Invalid return shapes (e.g. {model, :ok} or 3-element tuples) raise ArgumentError immediately. See App Lifecycle for details.

Command categories

All functions live in Plushie.Command unless noted otherwise.

Control flow

batch/1 executes commands in order via Enum.reduce. Each command threads through the runtime state sequentially. Use it to combine multiple side effects from a single update/2 clause.

Async

send_after/2 is a one-shot timer (fires once). For recurring timers, use Plushie.Subscription.every/2 instead.

Focus

Text

Scroll

Window operations

Screenshot results arrive as a raw {:screenshot_response, data} tuple in update/2 (not a SystemEvent). The data map contains name, hash, width, height, and optionally rgba binary image data.

Window queries

Results arrive as %SystemEvent{type: type, tag: tag, data: data}. The tag matches the atom you provided. Data maps use atom keys: %{width: 800, height: 600}.

System

announce/1 triggers a live-region assertion for assistive technology. The text is immediately spoken by the screen reader without requiring a visible widget. Use for status updates, error notifications, and dynamic content.

Other

Platform effects

All functions live in Plushie.Effect. Each takes an atom tag as its first argument and returns a Plushie.Command struct. Results arrive as %Plushie.Event.EffectEvent{tag: tag, result: result} in update/2.

File dialogs

{model, Effect.file_open(:import, title: "Import", filters: [{"Elixir", "*.ex"}])}

def update(model, %EffectEvent{tag: :import, result: {:ok, %{path: path}}}), do: ...
def update(model, %EffectEvent{tag: :import, result: :cancelled}), do: model

Clipboard

Notifications

{model, Effect.notification(:saved, "Exported", "File saved to #{path}")}

Options: :icon, :timeout (auto-dismiss ms), :urgency (:low, :normal, :critical), :sound.

Async mechanics

• One task per tag. Starting async/2 or stream/2 with a tag that is already in-flight kills the previous task. Use unique tags for concurrent work.

• Nonce-based stale rejection. Each task gets a nonce at creation. Results from killed tasks carry a stale nonce and are silently discarded.

• Crashes become errors. If the task process crashes (exception, exit), the result is {:error, {:crashed, reason}}.

• Renderer restarts. In-flight async tasks survive a renderer restart (they run in the BEAM, not the renderer). Results may be stale if the work depended on renderer state.

Streaming

cmd = Command.stream(fn emit ->
  for chunk <- fetch_chunks() do
    emit.(%{progress: chunk.index, data: chunk.data})
  end
  :done
end, :import)

Each emit.() delivers a %StreamEvent{tag: :import, value: value}. The function's final return value is delivered directly as %AsyncEvent{tag: :import, result: :done}. Wrap in {:ok, ...} yourself if you want to follow the async convention.

Effect lifecycle

• Tag-based matching. Every effect takes an atom tag. The tag returns in %EffectEvent{tag: tag} for direct pattern matching.

• One effect per tag. Starting a new effect with a tag that has a pending request discards the previous one.

• Default timeouts: file dialogs 120s, clipboard/notifications 5s. Override with :timeout option.

• Timeout delivery. result: {:error, :timeout}.

• Cancellation. User dismissing a dialog delivers result: :cancelled (not an error).

• Effect stubs. register_effect_stub(:file_open, {:ok, %{path: "..."}}) intercepts effects by kind in tests. See the Testing reference.

DIY patterns

The runtime is a GenServer. You can bypass the command system and send messages directly:

def update(model, %WidgetEvent{type: :click, id: "fetch"}) do
  pid = self()
  spawn(fn ->
    result = MyApp.HTTP.get!("/api/data")
    send(pid, {:fetched, result})
  end)
  model
end

def update(model, {:fetched, result}) do
  %{model | data: result}
end

This is useful for integrating with existing OTP infrastructure -- supervisors, GenServers, Phoenix PubSub. Messages arrive as events in the next update cycle. The tradeoff: you lose tag-based cancellation and stale-result rejection that async/2 provides.

See also

• Plushie.Command - full module docs with specs
• Plushie.Effect - platform effect functions
• Async and Effects guide - effects, async, streaming, and multi-window
• App Lifecycle reference - return value validation and update cycle
• Testing reference - effect stubs