Introduction

Turning milliseconds into readable durations is common in logs, dashboards, and user-facing progress screens. The challenge is balancing compact formatting with consistent precision and edge-case handling. A robust formatter should define unit policy clearly and keep raw milliseconds for machine use.

Decompose Milliseconds into Units

Use integer division and remainder operations for deterministic unit extraction.

1def decompose(ms):
2    seconds, rem_ms = divmod(ms, 1000)
3    minutes, rem_s = divmod(seconds, 60)
4    hours, rem_m = divmod(minutes, 60)
5    days, rem_h = divmod(hours, 24)
6    return days, rem_h, rem_m, rem_s, rem_ms
7
8print(decompose(93784005))

This decomposition is stable and easy to test at boundaries.

Build a Compact Formatter

Compact token style works well for logs and technical dashboards.

1def format_duration(ms):
2    d, h, m, s, rem = decompose(ms)
3    parts = []
4    if d: parts.append(f"{d}d")
5    if h: parts.append(f"{h}h")
6    if m: parts.append(f"{m}m")
7    if s: parts.append(f"{s}s")
8    if rem or not parts: parts.append(f"{rem}ms")
9    return " ".join(parts)
10
11print(format_duration(93784005))
12print(format_duration(450))
13print(format_duration(0))

Include zero handling so function never returns empty string.

JavaScript Version for Web Apps

1function formatMs(ms) {
2  let remaining = ms;
3  const day = 24 * 60 * 60 * 1000;
4  const hour = 60 * 60 * 1000;
5  const minute = 60 * 1000;
6  const second = 1000;
7
8  const d = Math.floor(remaining / day); remaining %= day;
9  const h = Math.floor(remaining / hour); remaining %= hour;
10  const m = Math.floor(remaining / minute); remaining %= minute;
11  const s = Math.floor(remaining / second); remaining %= second;
12
13  const parts = [];
14  if (d) parts.push(`${d}d`);
15  if (h) parts.push(`${h}h`);
16  if (m) parts.push(`${m}m`);
17  if (s) parts.push(`${s}s`);
18  if (remaining || parts.length === 0) parts.push(`${remaining}ms`);
19  return parts.join(" ");
20}
21
22console.log(formatMs(93784005));

Keep format style consistent across frontend and backend where users compare outputs.

Choose Precision Policy by Context

Different surfaces need different granularity:

• Logs may keep milliseconds for diagnostics.
• UI summaries may round to seconds or minutes.
• Alerts may show only highest significant units.

Define one policy per channel and document it. Mixed precision inside one screen confuses users.

Preserve Raw Milliseconds for Logic

Readable strings are presentation only. Keep original millisecond values for sorting, filtering, thresholds, and aggregations.

If you store only formatted text, downstream analytics and ordering become fragile and locale-dependent.

Handle Internationalization for End Users

Compact tokens such as 2h 5m are fine for technical audiences. End-user interfaces may require localized phrases and pluralization rules.

A practical split:

• Compact fixed-format string for logs and metrics.
• Localized phrase format for user-facing UI.

Do not mix these modes in the same API field.

Add Boundary and Regression Tests

Test at exact boundaries where formatting logic often fails:

• 999 milliseconds.
• 1000 milliseconds.
• 60 seconds.
• 24 hours.
• Very large durations.

Example tests:

1assert format_duration(0) == "0ms"
2assert format_duration(1000) == "1s"
3assert format_duration(61000) == "1m 1s"
4assert format_duration(86400000) == "1d"

These tests catch regressions quickly when formatting policy changes.

Common Pitfalls

• Rounding too early and losing precision unexpectedly.
• Returning empty string for zero duration values.
• Using formatted duration strings in computation paths.
• Mixing long and compact styles without documented policy.
• Skipping boundary tests around unit transitions.

Summary

• Decompose milliseconds with integer arithmetic for reliable output.
• Apply a consistent formatting policy per output context.
• Preserve raw milliseconds for all machine calculations.
• Separate technical compact formatting from localized UI phrases.
• Protect formatter behavior with boundary-focused tests.