Various timer improvements (#83)

* Add IDs to timers
* Add IDs to timer-related messages
* Ignore messages from other timers
* Add `Timeout` property to `TickMsg`
* Add `Start()`, `Stop()`, and `Toggle()` commands to timer
* Add `Timedout()` method to timer model
* Add `Running()` method to timer model

timer/timer.go

@@ -2,16 +2,80 @@
 package timer
 
 import (
+	"sync"
 	"time"
 
 	tea "github.com/charmbracelet/bubbletea"
 )
 
+var (
+	lastID int
+	idMtx  sync.Mutex
+)
+
+func nextID() int {
+	idMtx.Lock()
+	defer idMtx.Unlock()
+	lastID++
+	return lastID
+}
+
+// Authors note with regard to start and stop commands:
+//
+// Technically speaking, sending commands to start and stop the timer in this
+// case is extraneous. To stop the timer we'd just need to set the 'running'
+// property on the model to false which cause logic in the update function to
+// stop responding to TickMsgs. To start the model we'd set 'running' to true
+// and fire off a TickMsg. Helper functions would look like:
+//
+//     func (m *model) Start() tea.Cmd
+//     func (m *model) Stop()
+//
+// The danger with this approach, however, is that order of operations becomes
+// important with helper functions like the above. Consider the following:
+//
+//     // Would not work
+//     return m, m.timer.Start()
+//
+//	   // Would work
+//     cmd := m.timer.start()
+//     return m, cmd
+//
+// Thus, because of potential pitfalls like the ones above, we've introduced
+// the extraneous StartStopMsg to simplify the mental model when using this
+// package. Bear in mind that the practice of sending commands to simply
+// communicate with other parts of your application, such as in this package,
+// is still not recommended.
+
+// StartStopMsg is used to start and stop the timer.
+type StartStopMsg struct {
+	ID      int
+	running bool
+}
+
 // TickMsg is a message that is sent on every timer tick.
-type TickMsg struct{}
+type TickMsg struct {
+	// ID is the identifier of the stopwatch that send the message. This makes
+	// it possible to determine which timer a tick belongs to when there
+	// are multiple timers running.
+	//
+	// Note, however, that a timer will reject ticks from other stopwatches, so
+	// it's safe to flow all TickMsgs through all timers and have them still
+	// behave appropriately.
+	ID int
+
+	// Timeout returns whether or not this tick is a timeout tick. You can
+	// alternatively listen for TimeoutMsg.
+	Timeout bool
+}
 
 // TimeoutMsg is a message that is sent once when the timer times out.
-type TimeoutMsg struct{}
+//
+// It's a convenience message sent alongside a TickMsg with the Timeout value
+// set to true.
+type TimeoutMsg struct {
+	ID int
+}
 
 // Model of the timer component.
 type Model struct {
@@ -20,6 +84,9 @@ type Model struct {
 
 	// How long to wait before every tick. Defaults to 1 second.
 	Interval time.Duration
+
+	id      int
+	running bool
 }
 
 // NewWithInterval creates a new timer with the given timeout and tick interval.
@@ -27,6 +94,8 @@ func NewWithInterval(timeout, interval time.Duration) Model {
 	return Model{
 		Timeout:  timeout,
 		Interval: interval,
+		running:  true,
+		id:       nextID(),
 	}
 }
 
@@ -35,22 +104,47 @@ func New(timeout time.Duration) Model {
 	return NewWithInterval(timeout, time.Second)
 }
 
+// ID returns the model's identifier. This can be used to determine if messages
+// belong to this timer instance when there are multiple timers.
+func (m Model) ID() int {
+	return m.id
+}
+
+// Running returns whether or not the timer is running. If the timer has timed
+// out this will always return false.
+func (m Model) Running() bool {
+	if m.Timedout() || !m.running {
+		return false
+	}
+	return true
+}
+
+// Timedout returns whether or not the timer has timed out.
+func (m Model) Timedout() bool {
+	return m.Timeout <= 0
+}
+
 // Init starts the timer.
 func (m Model) Init() tea.Cmd {
-	return tick(m.Interval)
+	return m.tick()
 }
 
 // Update handles the timer tick.
 func (m Model) Update(msg tea.Msg) (Model, tea.Cmd) {
-	switch msg.(type) {
+	switch msg := msg.(type) {
+	case StartStopMsg:
+		if msg.ID != 0 && msg.ID != m.id {
+			return m, nil
+		}
+		m.running = msg.running
+		return m, m.tick()
 	case TickMsg:
+		if !m.Running() || (msg.ID != 0 && msg.ID != m.id) {
+			break
+		}
+
 		m.Timeout -= m.Interval
-		if m.Timeout <= 0 {
+		return m, tea.Batch(m.tick(), m.timedout())
-			return m, func() tea.Msg {
-				return TimeoutMsg{}
-			}
-		}
-		return m, tick(m.Interval)
 	}
 
 	return m, nil
@@ -61,8 +155,40 @@ func (m Model) View() string {
 	return m.Timeout.String()
 }
 
-func tick(d time.Duration) tea.Cmd {
+// Start resumes the timer. Has no effect if the timer has timed out.
-	return tea.Tick(d, func(_ time.Time) tea.Msg {
+func (m *Model) Start() tea.Cmd {
-		return TickMsg{}
+	return m.startStop(true)
+}
+
+// Stop pauses the timer. Has no effect if the timer has timed out.
+func (m *Model) Stop() tea.Cmd {
+	return func() tea.Msg {
+		return m.startStop(false)
+	}
+}
+
+// Toggle stops the timer if it's running and starts it if it's stopped.
+func (m *Model) Toggle() tea.Cmd {
+	return m.startStop(!m.Running())
+}
+
+func (m Model) tick() tea.Cmd {
+	return tea.Tick(m.Interval, func(_ time.Time) tea.Msg {
+		return TickMsg{ID: m.id, Timeout: m.Timedout()}
 	})
 }
+
+func (m Model) timedout() tea.Cmd {
+	if !m.Timedout() {
+		return nil
+	}
+	return func() tea.Msg {
+		return TimeoutMsg{ID: m.id}
+	}
+}
+
+func (m Model) startStop(v bool) tea.Cmd {
+	return func() tea.Msg {
+		return StartStopMsg{ID: m.id, running: v}
+	}
+}