fx

package
v0.8.9 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 15, 2026 License: MIT Imports: 14 Imported by: 1

Documentation

Overview

Package fx provides terminal animation types (spinners, progress bars, shimmers, and pulses) with composable builders and group orchestration.

Index

Constants

View Source 
const DefaultSymbol = "⏳"

DefaultSymbol is the default icon shown during pulse, shimmer, and bar animations.

Variables

This section is empty.

Functions

This section is empty.

Types

type Animation 

type Animation int

Animation is the animation rendering mode for a Builder. It controls how the message text is animated. Symbol animation is controlled independently by Builder.AnimatedSymbol. 

const (
	// AnimationNone applies no message effect. This is the default.
	AnimationNone Animation = iota
	// AnimationBar renders a progress bar.
	AnimationBar
	// AnimationPulse renders a pulsing text effect.
	AnimationPulse
	// AnimationShimmer renders a shimmering text effect.
	AnimationShimmer
)

type AnimationConfig 

type AnimationConfig struct {
	Builder   *Builder
	FieldsPtr *atomic.Pointer[[]core.Field]
	LevelPtr  *atomic.Int64
	MsgPtr    *atomic.Pointer[string]
	StartTime time.Time
	SymbolPtr *atomic.Pointer[string]
	Task      TaskFunc
}

AnimationConfig holds the parameters for running a single animation.

type Builder 

type Builder struct {
	core.FieldBuilder[Builder]

	AnimatedSymbol bool          // when true, cycles SpinnerStyle.Frames as the symbol instead of a static icon
	ClearOnCancel  bool          // when true, erase the animation line on context cancellation
	BarPercentKey  string        // when set, a formatted percent field is injected each tick
	BarProgressPtr *atomic.Int64 // bar mode: current progress; nil for non-bar modes
	BarStyle       bar.Style     // bar mode: visual style
	BarTotalPtr    *atomic.Int64 // bar mode: total progress; nil for non-bar modes
	DelayDur       time.Duration // when set, suppresses animation until this duration elapses
	ElapsedKey     string        // when set, a formatted elapsed-time field is injected each tick
	IndentDepth    int           // additional indent depth applied to the animation
	Log            Logger        // the logger interface; nil uses Default
	Level          core.Level    // log level used during animation rendering (default: LevelInfo)
	Message        string
	Mode           Animation
	PartOverrides  *[]core.Part // nil = use logger's parts
	PulseStops     []gradient.ColorStop
	ShimmerDir     shimmer.Direction
	ShimmerStops   []gradient.ColorStop
	Speed          float64
	SpinnerStyle   spinner.Style
	SuppressNonTTY bool           // when true, no output is produced on non-TTY writers
	SymbolIcon     string         // icon shown during animation; defaults to DefaultSymbol for pulse/shimmer/bar
	TreePos        []core.TreePos // additional tree levels applied to the animation
}

Builder configures an animation before execution. Create one with NewBuilder or the root clog convenience constructors (Spinner, Pulse, Shimmer, Bar).

func NewBuilder 

func NewBuilder(cfg BuilderConfig) *Builder

NewBuilder creates a new Builder from the given configuration.

func (*Builder) After 

func (b *Builder) After(d time.Duration) *Builder

After sets a delay before the animation becomes visible.

func (*Builder) BarPercent 

func (b *Builder) BarPercent(key string) *Builder

BarPercent enables an auto-updating percentage field for AnimationBar.

func (*Builder) BarPercentValue 

func (b *Builder) BarPercentValue() core.Percent

BarPercentValue returns the current progress as a core.Percent.

func (*Builder) Column 

func (b *Builder) Column(key, path string, line, column int) *Builder

Column adds a file path field with a line and column number as a clickable terminal hyperlink.

func (*Builder) Dedent 

func (b *Builder) Dedent() *Builder

Dedent removes one indent level from the animation output, down to a minimum of zero.

func (*Builder) Depth 

func (b *Builder) Depth(n int) *Builder

Depth adds multiple indent levels to the animation output.

func (*Builder) Elapsed 

func (b *Builder) Elapsed(key string) *Builder

Elapsed enables an auto-updating elapsed-time field.

func (*Builder) Indent 

func (b *Builder) Indent() *Builder

Indent adds one indent level to the animation output.

func (*Builder) IndentedLogger 

func (b *Builder) IndentedLogger(def Logger) Logger

IndentedLogger returns the builder's logger with any builder-level indent depth and tree levels applied. Used for completion logging so the result message has the same indentation as the animation.

func (*Builder) Line 

func (b *Builder) Line(key, path string, line int) *Builder

Line adds a file path field with a line number as a clickable terminal hyperlink. 

func (b *Builder) Link(key, url, text string) *Builder

Link adds a field as a clickable terminal hyperlink with custom display text.

func (*Builder) NonTTYSilent 

func (b *Builder) NonTTYSilent(silent bool) *Builder

NonTTYSilent controls whether animation output is suppressed entirely on non-TTY writers (CI, piped output). When silent is true, no output is produced. When false (default), a static line is printed.

func (*Builder) Parts 

func (b *Builder) Parts(parts ...core.Part) *Builder

Parts overrides the log-line part order for this animation and its completion message.

func (*Builder) Path 

func (b *Builder) Path(key, path string) *Builder

Path adds a file path field as a clickable terminal hyperlink.

func (*Builder) Progress 

func (b *Builder) Progress(ctx context.Context, task UpdateFunc) *WaitResult

Progress executes the task with the animation whose message and fields can be updated via the Update builder.

func (*Builder) ResolveDynamicFields 

func (b *Builder) ResolveDynamicFields(fields []core.Field, dur time.Duration) []core.Field

ResolveDynamicFields clones fields and injects elapsed/percent values.

func (*Builder) ResolveLogger 

func (b *Builder) ResolveLogger(def Logger) Logger

ResolveLogger returns the builder's logger, falling back to the given default.

func (*Builder) Spinner added in v0.7.20 

func (b *Builder) Spinner(opts ...spinner.Option) *Builder

Spinner enables an animated spinning symbol. The symbol slot cycles through [SpinnerStyle] frames independently of the main animation mode. Options override the builder's existing [SpinnerStyle]. With no options the current style (set by the constructor or logger default) is used.

func (*Builder) StripDynamicFields 

func (b *Builder) StripDynamicFields(fields []core.Field) []core.Field

StripDynamicFields returns fields with animation-only dynamic fields removed.

func (*Builder) Symbol 

func (b *Builder) Symbol(symbol string) *Builder

Symbol sets the icon displayed beside the message during animation.

func (*Builder) Tree 

func (b *Builder) Tree(pos core.TreePos) *Builder

Tree adds one tree-nesting level with the given position.

func (*Builder) URL 

func (b *Builder) URL(key, url string) *Builder

URL adds a field as a clickable terminal hyperlink.

func (*Builder) Wait 

func (b *Builder) Wait(ctx context.Context, task TaskFunc) *WaitResult

Wait executes the task with the animation and returns a WaitResult for chaining.

type BuilderConfig 

type BuilderConfig struct {
	AnimatedSymbol bool
	BarProgress    *atomic.Int64
	BarStyle       bar.Style
	BarTotal       *atomic.Int64
	Level          core.Level
	Logger         Logger
	Message        string
	Mode           Animation
	PulseStops     []gradient.ColorStop
	ShimmerDir     shimmer.Direction
	ShimmerStops   []gradient.ColorStop
	Speed          float64
	SpinnerStyle   spinner.Style
	SymbolIcon     string
}

BuilderConfig provides the initial configuration for a Builder.

type DoneEvent 

type DoneEvent struct {
	Err    error
	Fields []core.Field
	Level  core.Level
	Msg    string
	Parts  *[]core.Part
	Symbol *string
}

DoneEvent holds the parameters for logging a done event.

type FieldAlignment added in v0.7.0 

type FieldAlignment int

FieldAlignment controls optional group-level alignment behavior. 

const (
	// FieldAlignmentNone disables group-level field alignment padding.
	FieldAlignmentNone FieldAlignment = iota
	// FieldAlignmentMessage aligns the first field column after the message.
	FieldAlignmentMessage
)

type Group 

type Group struct {
	Ctx context.Context //nolint:containedctx // Group shares a single ctx with all child goroutines
	Mu  sync.Mutex

	ClearOnCancel    bool
	FieldAlignment   FieldAlignment
	Footer           *GroupStatus
	Header           *GroupStatus
	HideDone         bool
	Log              Logger
	MaxLines         int
	MaxHeightPercent float64
	Monotonic        bool
	Parallelism      int
	SyncAnimations   bool
	Tasks            []*GroupTask
	// contains filtered or unexported fields
}

Group manages a set of concurrent animations rendered as a multi-line block. Create one with root clog's Group function, add animations with Group.Add, then call Group.Wait to run the render loop.

func (*Group) Add 

func (g *Group) Add(b *Builder) *GroupEntry

Add registers an animation builder with the group and returns a GroupEntry for starting the task.

func (*Group) Wait 

func (g *Group) Wait() *GroupResult

Wait runs the render loop, blocking until all tasks complete or the context is cancelled. The returned GroupResult can be used to log a single summary line.

type GroupEntry 

type GroupEntry struct {
	// contains filtered or unexported fields
}

GroupEntry is returned by Group.Add and provides [Run] and [Progress] methods to start a task within the group.

func (*GroupEntry) Progress 

func (ge *GroupEntry) Progress(task UpdateFunc) *TaskResult

Progress starts a task with progress update capability and returns a TaskResult.

func (*GroupEntry) Run 

func (ge *GroupEntry) Run(task TaskFunc) *TaskResult

Run starts a simple task (no progress updates) and returns a TaskResult.

type GroupResult 

type GroupResult struct {
	// contains filtered or unexported fields
}

GroupResult holds the aggregate result of a Group.Wait.

func (*GroupResult) Err 

func (r *GroupResult) Err() error

Err returns the joined error, logging success or failure.

func (*GroupResult) Msg 

func (r *GroupResult) Msg(msg string) error

Msg logs at success level with the given message if all tasks succeeded.

func (*GroupResult) OnErrorLevel 

func (b *GroupResult) OnErrorLevel(lvl core.Level) *T

OnErrorLevel sets the log level for the error case.

func (*GroupResult) OnErrorMessage 

func (b *GroupResult) OnErrorMessage(msg string) *T

OnErrorMessage sets a custom message for the error case.

func (*GroupResult) OnSuccessLevel 

func (b *GroupResult) OnSuccessLevel(lvl core.Level) *T

OnSuccessLevel sets the log level for the success case.

func (*GroupResult) OnSuccessMessage 

func (b *GroupResult) OnSuccessMessage(msg string) *T

OnSuccessMessage sets the message for the success case.

func (*GroupResult) Parts 

func (b *GroupResult) Parts(parts ...core.Part) *T

Parts overrides the log-line part order for the completion message.

func (*GroupResult) Send 

func (r *GroupResult) Send() error

Send finalises the result.

func (*GroupResult) Silent 

func (r *GroupResult) Silent() error

Silent returns the joined error without logging anything.

func (*GroupResult) Symbol 

func (b *GroupResult) Symbol(symbol string) *T

Symbol sets a custom emoji symbol for the completion log message.

type GroupStatus added in v0.7.25 

type GroupStatus struct {
	Builder  *Builder
	Callback GroupStatusFunc
}

GroupStatus pairs a Builder (for initial config like level, symbol, parts) with a GroupStatusFunc callback that updates it each tick.

type GroupStatusFunc added in v0.7.25 

type GroupStatusFunc func(done, total int, u *Update)

GroupStatusFunc is called each render tick with the number of completed and total tasks. Use the Update to set the message and fields for that tick.

type GroupTask 

type GroupTask struct {
	Builder        *Builder
	DoneErr        chan error // buffered(1); goroutine sends result here
	Err            error      // populated by Wait() after DoneErr is drained
	FieldsPtr      *atomic.Pointer[[]core.Field]
	FinishedAt     atomic.Int64
	LevelPtr       *atomic.Int64
	MsgPtr         *atomic.Pointer[string]
	StartTime      time.Time
	StartedAt      atomic.Int64
	SymbolOverride atomic.Bool // true when SetSymbol has been called; disables animated spinner
	SymbolPtr      *atomic.Pointer[string]
}

GroupTask holds per-animation state for the group render loop. This is exported so the root clog rendering code can access it.

func (*GroupTask) Duration added in v0.7.0 

func (t *GroupTask) Duration(now time.Time) time.Duration

Duration returns the elapsed execution time, or zero while the task is queued.

func (*GroupTask) FinishTime added in v0.7.2 

func (t *GroupTask) FinishTime() time.Time

FinishTime returns the actual finish time, or the zero value if unfinished.

func (*GroupTask) MarkFinished added in v0.7.2 

func (t *GroupTask) MarkFinished(now time.Time)

MarkFinished records the actual task finish time.

func (*GroupTask) MarkStarted added in v0.7.0 

func (t *GroupTask) MarkStarted(now time.Time)

MarkStarted records the actual task start time.

func (*GroupTask) Started added in v0.7.0 

func (t *GroupTask) Started() bool

Started reports whether the task has begun executing.

type Logger 

type Logger interface {
	// Done logs a done event after an animation finishes.
	Done(evt DoneEvent)

	// WithIndent returns a Logger with additional indent depth and tree positions.
	WithIndent(depth int, tree []core.TreePos) Logger

	// Output returns the Output associated with this Logger.
	Output() Output

	// RunAnimation runs the animation loop for a single builder.
	RunAnimation(ctx context.Context, cfg AnimationConfig) error

	// RunGroup runs the group render loop.
	RunGroup(ctx context.Context, g *Group) error
}

Logger is the interface that the root clog package implements. It decouples the fx animation types from the concrete *clog.Logger so the fx package can reference logging operations without importing root clog.

type Output 

type Output interface {
	IsTTY() bool
	Writer() io.Writer
	Width() int
	ColorsDisabled() bool
	PathLink(path string, line, column int) string
	Hyperlink(url, text string) string
}

Output provides terminal capabilities needed by animation types.

type TaskFunc 

type TaskFunc func(context.Context) error

TaskFunc is a function executed by Builder.Wait.

type TaskResult 

type TaskResult struct {
	// contains filtered or unexported fields
}

TaskResult holds the result of a group animation task.

func (*TaskResult) Err 

func (r *TaskResult) Err() error

Err returns the error, logging success or failure using the original message.

func (*TaskResult) Msg 

func (r *TaskResult) Msg(msg string) error

Msg logs at success level with the given message on success, or at error level with the error string on failure. Returns the error.

func (*TaskResult) OnErrorLevel 

func (b *TaskResult) OnErrorLevel(lvl core.Level) *T

OnErrorLevel sets the log level for the error case.

func (*TaskResult) OnErrorMessage 

func (b *TaskResult) OnErrorMessage(msg string) *T

OnErrorMessage sets a custom message for the error case.

func (*TaskResult) OnSuccessLevel 

func (b *TaskResult) OnSuccessLevel(lvl core.Level) *T

OnSuccessLevel sets the log level for the success case.

func (*TaskResult) OnSuccessMessage 

func (b *TaskResult) OnSuccessMessage(msg string) *T

OnSuccessMessage sets the message for the success case.

func (*TaskResult) Parts 

func (b *TaskResult) Parts(parts ...core.Part) *T

Parts overrides the log-line part order for the completion message.

func (*TaskResult) Send 

func (r *TaskResult) Send() error

Send finalises the result, logging at the configured success or error level.

func (*TaskResult) Silent 

func (r *TaskResult) Silent() error

Silent returns just the error without logging anything.

func (*TaskResult) Symbol 

func (b *TaskResult) Symbol(symbol string) *T

Symbol sets a custom emoji symbol for the completion log message.

type Update 

type Update struct {
	core.FieldBuilder[Update]

	Base              []core.Field
	FieldsPtr         *atomic.Pointer[[]core.Field]
	MsgPtr            *atomic.Pointer[string]
	MsgText           string
	ProgressPtr       *atomic.Int64           // bar mode: current progress value; nil for non-bar modes
	LevelPtr          *atomic.Int64           // overridden level; nil when not updatable
	SymbolOverridePtr *atomic.Bool            // when set to true, disables animated spinner in favour of static symbol
	SymbolPtr         *atomic.Pointer[string] // symbol icon; nil when not updatable
	TotalPtr          *atomic.Int64           // bar mode: total progress value; nil for non-bar modes
}

Update is a fluent builder for updating an animation's message and fields during an UpdateFunc. Call Update.Msg and field methods to build the update, then Update.Send to apply it atomically.

func (*Update) AddTotal 

func (p *Update) AddTotal(delta int) *Update

AddTotal atomically adds delta to the total progress value for a bar animation. The result is clamped to a minimum of 1. No-op if this is not a bar animation.

func (*Update) Msg 

func (p *Update) Msg(msg string) *Update

Msg sets the animation's displayed message.

func (*Update) Msgf added in v0.7.8 

func (p *Update) Msgf(format string, args ...any) *Update

Msgf sets the animation's displayed message with formatting.

func (*Update) Send 

func (p *Update) Send()

Send applies the accumulated message and field changes to the animation atomically.

func (*Update) SetLevel added in v0.7.7 

func (p *Update) SetLevel(level core.Level) *Update

SetLevel overrides the log level used when rendering the final done line. No-op if the animation does not support level updates.

func (*Update) SetProgress 

func (p *Update) SetProgress(current int) *Update

SetProgress sets the current progress value for a bar animation. Values are clamped to [0, total]. No-op if this is not a bar animation.

func (*Update) SetSymbol added in v0.7.0 

func (p *Update) SetSymbol(symbol string) *Update

SetSymbol changes the icon displayed beside the message during animation. The change takes effect on the next render tick. No-op if the animation does not support symbol updates.

func (*Update) SetTotal 

func (p *Update) SetTotal(total int) *Update

SetTotal updates the total progress value for a bar animation. No-op if this is not a bar animation.

type UpdateFunc 

type UpdateFunc func(context.Context, *Update) error

UpdateFunc is a function executed by Builder.Progress. The Update allows updating the animation's message and fields.

type WaitResult 

type WaitResult struct {
	TaskErr error
	// contains filtered or unexported fields
}

WaitResult holds the result of a Builder.Wait or Builder.Progress operation and allows chaining additional fields before finalising the log output.

func NewWaitResult 

func NewWaitResult(
	err error,
	logger Logger,
	parts *[]core.Part,
	lvl core.Level,
	msg string,
) *WaitResult

NewWaitResult creates a WaitResult with default settings.

func (*WaitResult) Err 

func (w *WaitResult) Err() error

Err returns the error, logging success at info level or failure at error level using the original animation message.

func (*WaitResult) Msg 

func (w *WaitResult) Msg(msg string) error

Msg logs at info level with the given message on success, or at error level with the error string on failure. Returns the error.

func (*WaitResult) Msgf added in v0.7.12 

func (w *WaitResult) Msgf(format string, a ...any) error

Msgf is like WaitResult.Msg but accepts a format string.

func (*WaitResult) OnErrorLevel 

func (b *WaitResult) OnErrorLevel(lvl core.Level) *T

OnErrorLevel sets the log level for the error case.

func (*WaitResult) OnErrorMessage 

func (b *WaitResult) OnErrorMessage(msg string) *T

OnErrorMessage sets a custom message for the error case.

func (*WaitResult) OnSuccessLevel 

func (b *WaitResult) OnSuccessLevel(lvl core.Level) *T

OnSuccessLevel sets the log level for the success case.

func (*WaitResult) OnSuccessMessage 

func (b *WaitResult) OnSuccessMessage(msg string) *T

OnSuccessMessage sets the message for the success case.

func (*WaitResult) Parts 

func (b *WaitResult) Parts(parts ...core.Part) *T

Parts overrides the log-line part order for the completion message.

func (*WaitResult) Send 

func (w *WaitResult) Send() error

Send finalises the result, logging at the configured success or error level. Context cancellation errors are silenced since they indicate an interrupt, not a task failure. Returns the error from the task.

func (*WaitResult) Silent 

func (w *WaitResult) Silent() error

Silent returns just the error without logging anything.

func (*WaitResult) Symbol 

func (b *WaitResult) Symbol(symbol string) *T

Symbol sets a custom emoji symbol for the completion log message.

Source Files

View all Source files

Directories

Path Synopsis
bar
Package bar provides bar animation styles and presets for clog.
 Package bar provides bar animation styles and presets for clog.
widget
Package widget provides composable text widgets for progress bars.
 Package widget provides composable text widgets for progress bars.
Package pulse provides pulse animation rendering for clog.
 Package pulse provides pulse animation rendering for clog.
Package shimmer provides shimmer animation rendering for clog.
 Package shimmer provides shimmer animation rendering for clog.
Package spinner provides spinner animation styles and presets for clog.
 Package spinner provides spinner animation styles and presets for clog.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.