README
¶
Timer Package
The timer package provides timing functionality for tracking CLI command execution duration.
Features
- Simple API: Start, stage transitions, and get timing with minimal code
- Multi-stage support: Track total time and per-stage time separately
- Single-stage support: Simplified timing for operations without stages
- Zero dependencies: Uses only Go standard library (
timepackage) - Testable: Interface-based design with mockery support
Installation
This package is part of the KSail project. No separate installation required.
Usage
Single-Stage Command
For commands with a single operation phase:
package main
import (
"fmt"
"github.com/devantler-tech/ksail-go/pkg/ui/timer"
)
func main() {
t := timer.New()
t.Start()
// Perform your operation
doSomething()
total, _ := t.GetTiming()
fmt.Printf("Operation completed [%s]\n", total)
}
Multi-Stage Command
For commands with multiple operation phases:
package main
import (
"fmt"
"github.com/devantler-tech/ksail-go/pkg/ui/timer"
)
func main() {
t := timer.New()
t.Start()
// Stage 1
doStage1()
t.NewStage()
// Stage 2
doStage2()
t.NewStage()
// Stage 3
doStage3()
total, stage := t.GetTiming()
fmt.Printf("Operation completed [%s total|%s stage]\n", total, stage)
}
Integration with Notify Package
The timer integrates seamlessly with the pkg/ui/notify package:
package main
import (
"github.com/devantler-tech/ksail-go/pkg/ui/notify"
"github.com/devantler-tech/ksail-go/pkg/ui/timer"
)
func main() {
t := timer.New()
t.Start()
// Perform operation
err := performOperation()
if err != nil {
// No timing on errors
notify.Error("Operation failed: %v", err)
return
}
// Display timing on success
total, stage := t.GetTiming()
timingStr := notify.FormatTiming(total, stage, true) // multi-stage
notify.Success("Operation completed " + timingStr)
}
API Reference
Timer Interface
type Timer interface {
Start()
NewStage(title string)
GetTiming() (total, stage time.Duration)
Stop()
}
Start()
Initializes timing tracking. Must be called before any other methods. Can be called multiple times to reset the timer.
NewStage(title string)
Marks a stage transition. Resets the stage timer while preserving total elapsed time. The title is used for display purposes.
GetTiming() (total, stage time.Duration)
Returns current elapsed durations:
total: Time elapsed since Start()stage: Time elapsed since last NewStage() or Start()
Can be called multiple times without side effects.
Stop()
Signals completion of timing. Optional method provided for future extensibility. Currently a no-op.
Design Principles
- Package-First Design: Timer is a standalone, reusable package
- Interface-Based: Mockable for testing
- Single Responsibility: Only tracks time, doesn't format output
- Minimal Overhead: <1ms overhead per operation
- Clean Architecture: No dependencies on UI or CLI packages
Testing
The package includes comprehensive contract tests that define the behavioral contract:
# Run all timer tests
go test ./pkg/ui/timer/
# Run with coverage
go test -cover ./pkg/ui/timer/
# Generate mocks
mockery
Performance
The timer mechanism adds <1ms overhead to command execution. Internal state management uses simple time.Time values and calculations are performed on-demand.
Contributing
Follow the KSail Constitution principles:
- Package-first design
- Test-first development (TDD)
- Interface-based design
- Clean architecture
See CONTRIBUTING.md for details.
License
Part of the KSail project. See repository root for license information.
Documentation
¶
Overview ¶
Package timer provides timing functionality for tracking command execution duration.
The timer package implements a simple, stateful timer that tracks total elapsed time and per-stage elapsed time for CLI command operations. It integrates with the notify package to display timing information in command output.
Example usage for single-stage command:
timer := timer.New()
timer.Start()
// ... perform operation ...
total, stage := timer.GetTiming()
fmt.Printf("Operation completed [%s]\n", total)
Example usage for multi-stage command:
timer := timer.New()
timer.Start()
// ... stage 1 ...
timer.NewStage()
// ... stage 2 ...
total, stage := timer.GetTiming()
fmt.Printf("Operation completed [%s total|%s stage]\n", total, stage)
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Impl ¶
type Impl struct {
// contains filtered or unexported fields
}
Impl is the concrete implementation of the Timer interface.
func New ¶
func New() *Impl
New creates a new Timer instance. The timer must be started with Start() before use.
func (*Impl) GetTiming ¶
GetTiming returns the current elapsed durations. Returns (total, stage) where:
- total: time elapsed since Start() was called
- stage: time elapsed since last NewStage() or Start()
If Start() has not been called, returns (0, 0). Can be called multiple times without side effects.
func (*Impl) NewStage ¶
func (t *Impl) NewStage()
NewStage marks a transition to a new stage. Resets the stage timer while preserving total elapsed time.
type Timer ¶
type Timer interface {
// Start initializes timing tracking. Sets both total and stage
// start times to the current time. Can be called multiple times
// to reset the timer.
Start()
// NewStage marks a stage transition.
// Resets the stage timer while preserving total elapsed time.
NewStage()
// GetTiming returns the current elapsed durations.
// Returns (total, stage) where:
// - total: time elapsed since Start()
// - stage: time elapsed since last NewStage() or Start()
// Can be called multiple times without side effects.
GetTiming() (total, stage time.Duration)
// Stop signals completion of timing. This is optional and
// provided for future extensibility. Currently a no-op.
Stop()
}
Timer tracks elapsed time for CLI command execution.
Timer provides methods to start timing, mark stage transitions, and retrieve current timing information. It is designed for single-threaded CLI command execution.
Source Files