Skip to main content
@ooneex/hour-utils turns a raw duration into a human-friendly breakdown. Pick a source unit (Hour, Minute, Second, or Millisecond), call .convert(value).to(format), and get back the requested components plus a ready-to-display text string. The chosen format is fully type-safe, so the returned object only contains the fields you asked for.

​
Installation

Add the package with Bun: 
bun add @ooneex/hour-utils

​
Usage

Each unit class exposes a static convert method that returns a converter with a .to(format) call. The format string selects which components to compute: d (days), h (hours), m (minutes), s (seconds), combined as dhms, dhm, dh, d, hms, hm, h, ms, m, or s. 
import { Hour, Minute, Second, Millisecond } from "@ooneex/hour-utils";

// 50 hours -> days, hours, minutes
const a = Hour.convert(50).to("dhm");
// { d: 2, h: 2, m: 0, text: "2d 2h" }

// 3725 seconds -> hours, minutes, seconds
const b = Second.convert(3725).to("hms");
// { h: 1, m: 2, s: 5, text: "1h 2m 5s" }

// 90 minutes -> hours and minutes
const c = Minute.convert(90).to("hm");
// { h: 1, m: 30, text: "1h 30m" }

// 5400000 ms -> full day/hour/minute/second breakdown
const d = Millisecond.convert(5_400_000).to("dhms");
// { d: 0, h: 1, m: 30, s: 0, text: "1h 30m" }
The text field omits zero components, but always shows at least the smallest requested unit when everything is zero: 
import { Second } from "@ooneex/hour-utils";

Second.convert(0).to("hms").text; // "0s"
Second.convert(45).to("hms").text; // "45s"
Because the return type is derived from the format, accessing a field outside the chosen format is a compile-time error: 
import { Hour } from "@ooneex/hour-utils";

const result = Hour.convert(10).to("hm");
result.h; // ok
result.m; // ok
// result.s; // TypeScript error: property "s" does not exist

​
When to use it

  • You have a duration in one unit and want to display it as days/hours/minutes/seconds (e.g. uptime, remaining time, elapsed time).
  • You want a pre-formatted label (text) without writing your own string-building logic.
  • You want the returned shape to be statically typed to the exact format you requested.
  • Skip it if you only need a plain numeric conversion (e.g. hours to seconds is just hours * 3600) or full calendar/timezone date math, for which a date library is more appropriate.