Function formatDuration

packages/utils/src/formatting.ts:162–219

(
  duration: number | string | undefined | null,
  options?: { precision?: number }
)

 * @returns A formatted duration string, or null if input is null/undefined
 */
export function formatDuration(
  duration: number | string | undefined | null,
  options?: { precision?: number }
): string | null {
  if (duration === undefined || duration === null) {
    return null
  }

  // Parse string durations (e.g., "500ms", "0.44ms", "1234")
  let ms: number
  if (typeof duration === 'string') {
    ms = Number.parseFloat(duration.replace(/[^0-9.-]/g, ''))
    if (!Number.isFinite(ms)) {
      return duration
    }
  } else {
    ms = duration
    // Handle NaN/Infinity (e.g., cancelled blocks with no end time)
    if (!Number.isFinite(ms)) {
      return '\u2014'
    }
  }

  const precision = options?.precision ?? 0

  if (ms < 1) {
    // Zero or near-zero: show "0ms" instead of "0.00ms"
    if (ms === 0 || ms < 0.005) {
      return '0ms'
    }
    // Sub-millisecond: show with 2 decimal places
    return `${ms.toFixed(2)}ms`
  }

  if (ms < 1000) {
    // Milliseconds: round to integer
    return `${Math.round(ms)}ms`
  }

  const seconds = ms / 1000
  if (seconds < 60) {
    if (precision > 0) {
      // Strip trailing zeros (e.g., "5.00s" -> "5s", "5.10s" -> "5.1s")
      return `${seconds.toFixed(precision).replace(/\.?0+$/, '')}s`
    }
    return `${Math.floor(seconds)}s`
  }

  const minutes = Math.floor(seconds / 60)
  const remainingSeconds = Math.floor(seconds % 60)
  if (minutes < 60) {
    return `${minutes}m ${remainingSeconds}s`
  }

  const hours = Math.floor(minutes / 60)
  const remainingMinutes = minutes % 60
  return `${hours}h ${remainingMinutes}m`
}