Getting started ​

Niobe gives you small functions for writing, converting, parsing and formatting durations. Every duration is a plain number of milliseconds, so it works anywhere a number of milliseconds does: setTimeout, Date arithmetic, cache lifetimes, rate limits and so on.

The problem ​

How often do you write code like this?

ts
setTimeout(refresh, 1_000 * 60 * 2.5);

1_000 * 60 * 2.5 takes a moment to read, and every project grows its own constants for it, named differently by each person who needs one.

The solution ​

With Niobe, the same duration says what it means:

ts
setTimeout
(
refresh
, 
minutes
(2) + 
seconds
(30));

Installation ​

sh
npm install niobe
sh
pnpm add niobe
sh
yarn add niobe

Niobe has no runtime dependencies. It ships ESM and CommonJS builds, with types.

What's included ​

  • Converting units: weeks, days, hours, minutes, seconds, milliseconds, microseconds and nanoseconds, each with .from() to convert back.
  • Constants: MINUTE, HOUR, SECONDS_IN_MINUTE and friends.
  • Duration strings: parse '1h 30m' with parseDuration.
  • Clock strings: read and write '01:30:00' with clockToMs and msToClock.
  • Parts: split a duration into units with msToParts, and join them with partsToMs.

The API reference lists every export.