> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ooneex.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Hour Utils

> Convert a single time amount in hours, minutes, seconds, or milliseconds into a breakdown of days, hours, minutes, and seconds with a formatted text label.

`@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:

```bash theme={null}
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`.

```typescript theme={null}
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:

```typescript theme={null}
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:

```typescript theme={null}
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.