hdinf

hdinf (human-duration in format) parses duration information from human-readable format into an arbitrary format.

Motivation

The frustration of seeing code littered with 86_400 and 60 * 60 * 24 and similar expressions.

Usage

import {
  getDuration,
  type HumanDuration,
  type IntervalName,
} from 'hdinf';

// parseDuration(duration: HumanDuration, interval: IntervalName): number
getDuration('1 day', 'seconds');
getDuration('1 day 2 hours 3 seconds', 'milliseconds');

In the wild, you should use this library remove any hard-coded durations from your codebase, e.g.,

- setTimeout(() => {}, 86_400);
+ setTimeout(() => {}, getDuration('1 day', 'seconds'));

Similarly, anywhere where you define inputs for a function, you should consider using HumanDuration instead of a raw number in an arbitrary format, e.g.,

- const foo = (durationInSeconds: number) => {}
+ const foo = (duration: HumanDuration) => {}

This will reduce the number of bugs that are introduced by passing in a duration in the wrong format.

TypeScript

One of the benefits of this library is that the input format is enforced using TypeScript template literal types, i.e. the compiler will complain if you pass in an invalid duration.

import { getDuration } from 'hdinf';

getDuration('1 day', 'seconds'); // OK
getDuration('1 day', 'milliseconds'); // OK
getDuration('1 day', 'minutes'); // OK
getDuration('1 day', 'hours'); // OK

getDuration('1 foo', 'seconds'); // TS error because foo is not a valid time period
getDuration('1 hour 1 day', 'seconds'); // TS error because lesser units cannot precede greater units (hour < day)

Abbreviations

Abbreviations are intentionally not supported. The goal of this library is to reduce the variations in how durations are expressed.

Alternatives

hdinf was primarily designed with the intent of replacing the use of constants rather than allowing dynamic expressions.

dayjs

If you are already using a library like dayjs, you can probably find a native solution for this problem, e.g.,

import dayjs from 'dayjs';
import duration from 'dayjs/plugin/duration';

dayjs.extend(duration);
dayjs.duration(100, 'days');

ms

My grudge with ms is that:

• it allows arbitrary formats (so you end up with 1ms, 1msec, 1millisecond, etc)
• it only allows to express output in milliseconds, so you end up with / 1000 and similar expressions