bubbles/timer/timer.go

195 lines
4.8 KiB
Go
Raw Normal View History

// Package timer provides a simple timeout component.
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 {
// 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.
//
// 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 {
// How long until the timer expires.
Timeout time.Duration
// 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.
func NewWithInterval(timeout, interval time.Duration) Model {
return Model{
Timeout: timeout,
Interval: interval,
running: true,
id: nextID(),
}
}
// New creates a new timer with the given timeout and default 1s interval.
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 m.tick()
}
// Update handles the timer tick.
func (m Model) Update(msg tea.Msg) (Model, tea.Cmd) {
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
return m, tea.Batch(m.tick(), m.timedout())
}
return m, nil
}
// View of the timer component.
func (m Model) View() string {
return m.Timeout.String()
}
// Start resumes the timer. Has no effect if the timer has timed out.
func (m *Model) Start() tea.Cmd {
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}
}
}