intl-unofficial-duration-unit-format

Intl DurationUnitFormat

Format time duration in quantities of units such as years, months, days, hours, minutes and seconds.

Overview

The goal of this project is to provide a way to format time durations (like 1 minute 30 seconds) since the standards don't provide a way to do it.

ECMAScript Internationalization has a long-standing open issue to provide an Intl.DurationFormat API that can accommodate time duration use cases, but as of February 2020 the proposal is still at Stage 1.

This project does its best at creating a DurationFormat implementation that resembles other standard APIs, but only work with time durations.

I'm not in any way part of the standardization process, that's why this package is -unofficial-.

Use cases

1. Natural language time: 1 minute 20 seconds
2. Timers: 01:20
3. Short formats 1 hr 2 min 30 sec or 1h 2m 30s

Usage

const duration = new DurationUnitFormat(locales, options);
const parts = duration.formatToParts(90);

/*
parts = [
  { type: 'minute', value: '1' },
  { type: 'literal', value: ' ' },
  { type: 'unit', value: 'minute' },
  { type: 'second', value: '30' },
  { type: 'literal', value: ' ' },
  { type: 'unit', value: 'seconds' },
];
 */

Installation

npm i intl-unofficial-duration-unit-format

This package depends on intl-messageformat which is listed in peerDependencies.

intl-messageformat itself depends on the global Intl object. Refer to intl-messageformat README on how to set it up correctly on node.js or in the browser.

Webpack / Parcel / Rollup / ....

All modern bundlers allow you to import npm libraries

import DurationUnitFormat from 'intl-unofficial-duration-unit-format';

Public API

DurationUnitFormat constructor

To create a duration unit to format, use the DurationUnitFormat constructor, it takes two parameters:

1. locales: String | Array<String> A string with a BCP 47 language tag, or an array of such strings. For more details check this.
2. options: Object An optional configuration object. Refer to Options for additional details.

formatToParts(number)

Once the duration object is created with duration = new DurationUnitFormat(), you can call formatToParts passing a numeric value.

number must be expressed in seconds, so a value of 60 corresponds to 1 minute.

Options

style

One of

1. DurationUnitFormat.styles.LONG or just long for long format time (1 minute 30 seconds)
2. DurationUnitFormat.styles.SHORT or just short for short format time (1 min 30 sec)
3. DurationUnitFormat.styles.NARROW or just narrow for narrow format time (1m 30s)
4. DurationUnitFormat.styles.TIMER for timers (1:30)
5. DurationUnitFormat.styles.CUSTOM for custom formats (1 minute 30 seconds)

The default is LONG.

When the style is TIMER numbers are padded and different default formats are applied.

The options formatDuration and formatUnits only apply when the style is CUSTOM.

Given the input of 3600 (1 hour), it'll generate

style	format	Output
CUSTOM	undefined (defaults to {seconds})	3600 seconds
CUSTOM	{minutes} {seconds}	60 minutes
CUSTOM	{hour} {minutes} {seconds}	1 hour
TIMER	undefined (defaults to {minutes}:{seconds})	60:00
TIMER	{seconds}s	3600s
TIMER	{hour}:{minutes}:{seconds}	1:00:00
TIMER	{days}d {hour}:{minutes}:{seconds}	0d 01:00:00
LONG	undefined (defaults to {seconds})	3600 seconds
LONG	{minutes} {seconds}	60 minutes
LONG	{hour} {minutes} {seconds}	1 hour
SHORT	undefined (defaults to {seconds})	3600 sec
SHORT	{minutes} {seconds}	60 min
SHORT	{hour} {minutes} {seconds}	1 hr
NARROW	undefined (defaults to {seconds})	3600s
NARROW	{minutes} {seconds}	60m
NARROW	{hour} {minutes} {seconds}	1h

As shown from the examples, when TIMER is used

1. empty units are kept and rendered as 00 or 0 if they're the highest unit in the format. Empty units in CUSTOM are discarded.
2. values are padded to at least 2 digits

Note that on Node.js 10.x, the default implementation of Intl.NumberFormat does not support styles, so you need to use the @formatjs/intl-unified-numberformat polyfill.

format

Defines the format of the output string. Default to {seconds}.

It can be any string containing any of the placeholders {days}, {hours}, {minutes}, {seconds} or any other literal. The format of the placeholders can be customized by formatDuration.

Given the input of 3661 (1 hour, 1 minute and 1 second), it'll generate

format	Output
{seconds}	3661 seconds
{minutes} {seconds}	61 minutes 1 second
{minutes} and {seconds}	61 minutes and 1 second
{hours} {minutes} {seconds}	1 hour 1 minute 1 second
{hours} {minutes}	1 hour 1 minute
{hours}	1 hour
{hours}	1 hour
{days}	0 days

formatDuration

Defines the format of the output placeholders. Default to {value} {unit}.

It can be any string containing {value}, {unit} or any other literal. {value} corresponds to the numeric value (1), while {unit} is the time unit (minute, second).

Given the input of 1, it'll generate

formatDuration	Output
{value} {unit}	1 second
{value}{unit}	1second
{unit}: {value}	second: 1

formatUnits

Defines the format and localization of each placeholder's {unit}. Defaults to the object

{
  [DurationUnitFormat.units.DAY]: '{value, plural, one {day} other {days}}',
  [DurationUnitFormat.units.HOUR]: '{value, plural, one {hour} other {hours}}',
  [DurationUnitFormat.units.MINUTE]: '{value, plural, one {minute} other {minutes}}',
  [DurationUnitFormat.units.SECOND]: '{value, plural, one {second} other {seconds}}',
}

The object key must be one of the possible units, and the value is a string using the ICU format defined in intl-messageformat.

Given the input of 1, it'll generate

formatUnits[DurationUnitFormat.units.SECOND]	Output
{value, plural, one {second} other {seconds}}	second
{value, plural, other {秒}}	秒
s	s

round

Whether or not to round results when smaller units are missing. Default to false.

Given the input of 30 and the format {minutes}

round	Output
false	0 minutes
true	1 minute