A simple way to manage time-based intervals in your applications.

---

The Problem

How often do you write code like this?

setTimeout(() => /* Do something */, 1_000 * 60 * 2.5);

It is hard to understand what 1_000 * 60 * 2.5 means at first glance, although we get used to seeing common durations in our projects, there is an additional cognitive load when reading and writing code like this. The alternative is to create constants but when you have multiple engineers working on a project, it can be hard to keep track of what is in use, you get different naming conventions and you may end up with multiple constants for the same thing.

The Solution

Niobe provides a simple, unified, human readable way to provide durations. The same duration can be expressed as:

import { minutes, seconds } from 'niobe';

setTimeout(() => /* Do something */}, minutes(2) + seconds(30));

Additionally, Niobe provides utilities to parse durations, split them into their components and convert between different time units. There is even a range of common constants.

Take a look at the FAQs for more information, the CHANGELOG for the latest changes or the contribution guide if you want to get involved.

---

Installation

npm i niobe

API

Conversion

weeks(amount: number): number

Converts between weeks and milliseconds.

days(amount: number): number

Converts between days and milliseconds.

hours(amount: number): number

Converts between hours and milliseconds.

minutes(amount: number): number

Converts between minutes and milliseconds.

seconds(amount: number): number

Converts between seconds and milliseconds.

milliseconds(amount: number): number

Converts between milliseconds and milliseconds.

This seems pointless, why is it here?

weeks.from(ms: number): number

Converts between milliseconds and weeks.

days.from(ms: number): number

Converts between milliseconds and days.

hours.from(ms: number): number

Converts between milliseconds and hours.

minutes.from(ms: number): number

Converts between milliseconds and minutes.

seconds.from(ms: number): number

Converts between milliseconds and seconds.

milliseconds.from(ms: number): number

Converts between milliseconds and milliseconds.

This seems pointless, why is it here?

Utilities

clockToMs(clock: string): number

Converts a hh:mm:ss.ms_μs_ns string to milliseconds.

• hh - Hours - Optional, optional leading zero
• mm - Minutes - Optional, optional leading zero
• ss - Seconds - Required, optional leading zero
• ms - Milliseconds - Optional, optional trailing zeros
• μs - Microseconds - Optional, optional trailing zeros
• ns - Nanoseconds - Optional, optional trailing zeros

Milliseconds, microseconds, and nanoseconds can be optionally separated by underscores, if not, you must provide padding.

msToClock(milliseconds: number, options?: { separateDecimal = true }): string

Converts milliseconds to a string in the format 'hh:mm:ss' optionally suffixing '.ms_μs_ns' if there are any remaining milliseconds, microseconds or nanoseconds.

separateDecimal - If true, milliseconds, microseconds, and nanoseconds will be separated by underscores. If false, they will be concatenated without separators.

parseDuration(duration: string, strict: boolean = false): number

Parses a duration string, returning milliseconds.

Usage

Valid formats

parseDuration('2m 1s');
// => 121_000

parseDuration('1h 2m 3s');
// => 3_723_004

parseDuration('1d 2h 3m 4s 5ms 6μs 7ns');
// => 93_784_005.006_007

Invalid format - Non-strict (Default)

parseDuration('invalid');
// => 0

parseDuration('invalid', false);
// => 0

Invalid format - Strict

parseDuration('invalid', true);
// => throws Error: "invalid" is not a valid duration

msToParts(milliseconds: number): Parts

Converts a duration in milliseconds to a Parts object with properties for each time unit.

partsToMs(parts: Partial<Parts>): number

Converts a Parts object to duration in milliseconds.

Types

TimeUnit

This type represents the time unit strings used in the parseDuration function. It can be one of the following:

type TimeUnit = 'ns' | 'μs' | 'ms' | 's' | 'm' | 'h' | 'd' | 'w';

Parts

Used in the msToParts and partsToMs functions. This interface represents the parts of a duration.

interface Parts {
	days: number;
	hours: number;
	isNegative: boolean;
	nanoseconds: number;
	microseconds: number;
	milliseconds: number;
	minutes: number;
	seconds: number;
	weeks: number;
}

Constants

These constants are used to represent the number of milliseconds in each time unit.

NANOSECOND

One nanosecond in milliseconds.

MICROSECOND

One microsecond in milliseconds.

MILLISECOND

One millisecond.

This seems pointless, why is it here?

SECOND

One second in milliseconds.

MINUTE

One minute in milliseconds.

HOUR

One hour in milliseconds.

DAY

One day in milliseconds.

WEEK

One week in milliseconds.

NANOSECONDS_IN_MICROSECOND

Number of nanoseconds in a second.

MICROSECONDS_IN_MILLISECOND

Number of microseconds in a second.

MILLISECONDS_IN_SECOND

Number of milliseconds in a second.

SECONDS_IN_MINUTE

Number of seconds in a minute.

MINUTES_IN_HOUR

Number of minutes in an hour.

HOURS_IN_DAY

Number of hours in a day.

DAYS_IN_WEEK

Number of days in a week.

---

FAQs

Why is it called Niobe?

Naming things is hard! Most package names are taken so my approach is often something random. In this instance Niobe is a reference to a character in the Matrix films.

"This seems pointless, why is it here?"

There are several components in the API that are no-ops, meaning they don't actually do anything. For example, the `milliseconds` function simply returns the input value. This is included for completeness and to match the other functions, but is not typically used in practice, as milliseconds are already in milliseconds. However, it can be useful for consistency in the API or maybe you need to do something where you conditionally switch between functions.

---

© 2025 Mike Simmonds