Signature of Init and Update uses only Cmd

[tcurdt]

I am a little confused on the function signatures of Init and Update.

It seems like there will pretty much always be more than a single Cmd and it will always have to be wrapped in a Batch. Is this "normal" API flow?

func (m Model) Init() tea.Cmd {

	var cmds []tea.Cmd

	cmds = append(cmds, m.monitor.Init())

        ...

	return tea.Batch(cmds...)
}

func (m Model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {

	var cmds []tea.Cmd

	var cmd tea.Cmd
	m.monitor, cmd = m.monitor.Update(msg)
	cmds = append(cmds, cmd)

        ...

	return m, tea.Batch(cmds...)
}

And why does the model have to be passed through during Update?
Why not just return Cmds?

[seanbanko]

I'm also a bit new to Bubble Tea and The Elm Architecture but I'll give this a shot.

And why does the model have to be passed through during Update? Why not just return Cmds?

This is because even though it might feel like you mutate your Model during Update, the Bubble Tea runtime actually replaces your entire model with the updated model returned from Update. That's also why the Update function can use either a value receiver or a pointer receiver, because it doesn't matter whether you mutate the model passed in as a pointer receiver to Update and then return an updated model or mutate a copy of the model passed in with a value receiver and return an updated model. Either way, the Bubble Tea runtime just replaces the entire model you had before Update with the updated model and discards the old one every time a Msg comes in. This is how Bubble Tea achieves something that feels like functional programming with immutability in an otherwise imperative language like Go.

It seems like there will pretty much always be more than a single Cmd and it will always have to be wrapped in a Batch. Is this "normal" API flow?

Batching Cmds is common, but I wouldn't quite go so far as to say it pretty much always happens. Cmds are generally used to perform async operations like I/O and API calls as side-effects, but oftentimes you don't need to do any of those things in which case you can just return a nil Cmd. For example:

• The http example uses a Cmd in Init to make an http request, but it's just one Cmd, so no need to use Batch.
• The tabs example only returns nil Cmds because it only needs to update the activeTab field in the model in response to user input.
• The textinputs example always returns a Batch because it needs to pass each message down to each textinput submodel and Batch their returned Cmds in case any of them returned a side effect. This just like how you capture the Cmd returned from m.monitor.Update(msg) in your example.

One thing to note here is that just because you have a submodel like m.monitor in your case doesn't necessarily mean that every single Msg you receive in you top-level update function needs to be passed to it. You only need to call m.monitor.Update if you actually need to update the monitor in response to this particular Msg.

So, depending what needs to happen in Update when you receive a Msg, you'll probably need to do one of the following:

• If you just need to change some fields in your model, make the change(s) and return your updated model alongside a nil Cmd.
• If you need to perform a side effect, return your updated model alongside whatever Cmd you need to perform.
• If you need to perform multiple Cmds in response to Msg, either because you updated multiple submodels that themselves returned Cmds, or because you just need to perform multiple commands (like an API call simultaneously with something like a spinner.StartSpinner() Cmd), or both, this is where Batch (and Sequence) come in.

Hope that helps.

[tcurdt]

Wow, much appreciate taking the time to answer, @seanbanko.

This is how Bubble Tea achieves something that feels like functional programming with immutability in an otherwise imperative language like Go

That's a nice summary.

Batching Cmds is common, but I wouldn't quite go so far as to say it pretty much always happens.

Right. But why not return a pointer to a Cmd slice or nil? That would take away the batching part.
That said, I am not even sure it will make things smoother from a usage point.
It would just make the API a little clearer.

Much appreciate you taking the time answer.

[meowgorithm]

Hi! We took this design approach based on our positive experiences with Elm's implementation of the Elm architecture, despite your very valid point about how it hides functionality like Batch.

Specifically, we found the single Cmd as a return offers some composability. For example, in addition to running several commands at once with a Batch, you can also return a Sequence , which will execute several commands in order:

return tea.Sequence(doThis, thenThis, andThenThis)

This lets you do things like the following:

return someCmd

return tea.Batch(someCmds...)

return tea.Sequentially(thisCmd, thatCmd)

return tea.Batch(
    tea.Sequentially(someCmds...),
    tea.Sequentially(otherCmds...),
    anotherCmd,
)

And in all of the above cases we're still returning just a single Cmd. Additionally, as the maintainers, this allows us to introduce new meta-commands like Batch and Sequentially without needing to alter the API.

[tcurdt]

I guess I am still lacking some understanding of when such complex batch/sequences are needed in the real world. But I can see how it makes things a little more flexible or even expressive.

[meowgorithm]

We definitely had func (m Model) Init() []Cmd at one point when developing the API. Part of the decision was also that for single commands return someCmd felt a little less noisy than return []Cmd{someCmd}, since single command returns are common in simpler programs.