progress

Documentation

Overview

Package progress provides a generic progress tracking system for long-running operations. It receives events from a source, maps them to a common format, and displays them via a Visualizer.

Usage:

tracker := progress.NewTracker(
    progress.WithEvents(eventsChan, mapFunc),
    progress.WithVisualizer(bar.NewBarVisualizer()),
    progress.WithTotal(10),
)
go tracker.Start(ctx)
// ... send events to eventsChan ...
tracker.Summary(nil)

Index

• func IsTerminal(w io.Writer) bool
• type Event
• type LogBufferAware
• type State
• type Tracker
  • func NewTracker[T, E any](opts ...TrackerOption[T, E]) *Tracker[T, E]
  • func (t *Tracker[T, E]) Start(ctx context.Context)
  • func (t *Tracker[T, E]) Summary(err error)
• type TrackerOption
  • func WithEvents[T, E any](events <-chan E, f func(E) Event[T]) TrackerOption[T, E]
  • func WithOutput[T, E any](w io.Writer) TrackerOption[T, E]
  • func WithTotal[T, E any](total int) TrackerOption[T, E]
  • func WithVisualizer[T, E any](factory VisualizerFactory[T]) TrackerOption[T, E]
• type Visualizer
• type VisualizerFactory

Functions

func IsTerminal

func IsTerminal(w io.Writer) bool

IsTerminal reports whether the writer is connected to a terminal.

Types

type Event

type Event[T any] struct {
	ID    string
	Data  T
	State State
	Err   error
}

Event holds progress data for a single tracked item.

• ID: unique identifier for the item
• Data: custom payload (e.g., transformation details)
• State: current lifecycle state
• Err: error if the item failed

type LogBufferAware

type LogBufferAware interface {
	SetLogBuffer(buf *bytes.Buffer)
}

LogBufferAware is an optional interface for visualizers that can display buffered log output. If a Visualizer implements this, the Tracker will pass the slog buffer so the visualizer can render log lines inline (e.g., above the progress bar).

type State

type State string

State represents the lifecycle state of a tracked item.

const (
	Running   State = "running"   // Currently processing
	Completed State = "completed" // Finished successfully
	Failed    State = "failed"    // Finished with error
	Cancelled State = "cancelled" // Stopped due to context cancellation
)

type Tracker

type Tracker[T, E any] struct {
	// contains filtered or unexported fields
}

Tracker connects an event source to a visualizer. It reads events from a channel, maps them to Events, and forwards to the visualizer.

Type parameters:

• T: the data type stored in Event.Data
• E: the raw event type from the source channel

func NewTracker

func NewTracker[T, E any](opts ...TrackerOption[T, E]) *Tracker[T, E]

NewTracker creates a Tracker configured with the given options.

func (*Tracker[T, E]) Start

func (t *Tracker[T, E]) Start(ctx context.Context)

Start reads events from the channel and forwards them to the visualizer. Run this in a goroutine. It returns when the event channel is closed. Context cancellation errors are automatically converted to Cancelled state.

func (*Tracker[T, E]) Summary

func (t *Tracker[T, E]) Summary(err error)

Summary waits for all events to be processed, then shows the final summary. Call this after sending all events and closing the channel. Restores the original slog logger (not thread-safe, see interceptSlog).

type TrackerOption

type TrackerOption[T, E any] func(*Tracker[T, E])

TrackerOption configures a Tracker using the functional options pattern.

func WithEvents

func WithEvents[T, E any](events <-chan E, f func(E) Event[T]) TrackerOption[T, E]

WithEvents sets the event source channel and mapper function. The mapper converts raw events (E) to progress Events (T).

func WithOutput

func WithOutput[T, E any](w io.Writer) TrackerOption[T, E]

WithOutput sets where the visualizer writes output (e.g., os.Stdout).

func WithTotal

func WithTotal[T, E any](total int) TrackerOption[T, E]

WithTotal sets the expected number of items for progress percentage calculation.

func WithVisualizer

func WithVisualizer[T, E any](factory VisualizerFactory[T]) TrackerOption[T, E]

WithVisualizer sets the factory that creates the visualizer. The visualizer handles all rendering of progress updates.

type Visualizer

type Visualizer[T any] interface {
	// HandleEvent is called for each progress update.
	HandleEvent(event Event[T])
	// Summary is called once after all events are processed.
	Summary(err error)
}

Visualizer displays progress events to the user. Implementations handle rendering (e.g., progress bar, simple logs).

type VisualizerFactory

type VisualizerFactory[T any] func(out io.Writer, total int) Visualizer[T]

VisualizerFactory creates a Visualizer with the output writer and total item count.