niobe

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.

---

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

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

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

toParts(milliseconds: number): { days: number, hours: number, minutes: number, seconds: number, milliseconds: number }

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

Constants

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

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.

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