The timeutil package provides human-readable duration formatting utilities.

This package contains helpers for converting time.Duration values and raw numeric durations (milliseconds, nanoseconds) into compact, readable strings. The primary formatting style follows the debug npm package conventions used by the logger package.

Formats a time.Duration for display. Provides granular output from nanoseconds to hours.

import "github.com/github/gh-aw/pkg/timeutil"

timeutil.FormatDuration(500 * time.Millisecond)  // "500ms"
timeutil.FormatDuration(2500 * time.Millisecond) // "2.5s"
timeutil.FormatDuration(90 * time.Second)        // "1.5m"

Formats a duration given in milliseconds as a human-readable string.

timeutil.FormatDurationMs(500)   // "500ms"
timeutil.FormatDurationMs(1500)  // "1.5s"
timeutil.FormatDurationMs(90000) // "1m30s"

Formats a duration given in nanoseconds as a human-readable string. Returns "—" for zero or negative values. Uses Go's standard time.Duration.Round(time.Second) for output.

timeutil.FormatDurationNs(0)              // "—"
timeutil.FormatDurationNs(2_500_000_000)  // "2s"
timeutil.FormatDurationNs(90_000_000_000) // "1m30s"

• FormatDuration is used by the logger package to display time-diff between consecutive log calls (the +500ms suffix in debug output).
• FormatDurationMs is used for workflow run duration display, where GitHub Actions reports durations in milliseconds.
• FormatDurationNs is used for job duration display, where GitHub Actions reports billing durations in nanoseconds.