JS Duration Parser

This library is written to parse human-like duration time eg. 2d 10h 30m to given time unit, eg. hours or minutes. It allows to do reverse operation as well, so it is possible to get eg. 2h 30m from 150 minutes.

Installation

You can install it by your node dependency manager like npm or yarn.

npm:

npm install js-duration-parser

yarn:

yarn add js-duration-parser

Then you can use it in your app by import:

import DurationParser from 'js-duration-parser'

or as CommonJS module:

var DurationParser = require('js-duration-parser')

Basic usage

You can use duration parser to parse human-like duration string or to generate it from a number of time units.

Duration string

Duration string can be build using groups, separated by spaces, eg. 2d 30m 10s, Every group consists of number and time unit.

Possible time units (for 'en' locale):

• s = seconds;
• m = minutes;
• h = hours;
• d = days;
• w = weeks.

In duration string you don't need to specify group with 0 number. So, value 2h 0m 30s is syntactically correct but unnecessary.

Duration string can take both uppercase and lowercase time identifiers, so 2H 30M means the same as 2h 30m. Number of spaces does not matter too, so eg. 2d 30m1h 20s is correct duration.

Parsing

import DurationParser from 'js-duration-parser'

const durationParser = new DurationParser();
durationParser.parse('3h 30m 30s'); // 210.5m
durationParser.parse('15m 15s', 's'); // 915s
durationParser.parse('1w2d5h', 'h'); // 221h

parse method takes two arguments:

• required duration string;
• optional time unit for which should be calculated the duration; default unit is m.

Watch-out! String with a single numeric value can be parsed as a number of given time units:

durationParser.parse(' 12 ', 's'); // 12s

Generation

import DurationParser from 'js-duration-parser'

const durationParser = new DurationParser();
durationParser.compose(210.5); // 3h 30m 30s
durationParser.compose(915, 's'); // 15m 15s
durationParser.compose(221, 'h', ''); // 1w2d5h

compose method takes three arguments:

• required time number;
• optional time unit previous number; default value is m;
• optional group separator character used to divide duration string into groups; default value is space: ' '.

Localization

en locale is available and enabled in the library as default. You can consider to use it in almost all cases. However, if you want to use time identifiers for your own language, it's possible.

Below is an example how 'pl' locale is added. Polish mapping is as follows:

• s = seconds (sekundy);
• m = minutes (minuty);
• g = hours (godziny);
• d = days (dni);
• t = weeks (tygodnie).

Second argument of DurationParser class constructor is a custom TimeIdentifiers object. It contains all time identifiers mapped for all supported locales. If it's not passed, then default one with only en support is used.

import DurationParser, {TimeIdentifiers} from 'js-duration-parser'

const plIdentifiers = {
  s: 's',
  m: 'm',
  h: 'g',
  d: 'd',
  w: 't',
};
const timeIdentifiers = new TimeIdentifiers();
timeIdentifiers.add('pl', plIdentifiers);

const durationParser = new DurationParser('pl', timeIdentifiers);
durationParser.parse('3g 30m 30s'); // 210.5m
durationParser.compose(12.5, 'h'); // 12g 30m

Validation

Parser returns null if duration string can not be parsed. However, for some reason you need only to validate the input string. You can use DurationValidator class then:

import {DurationValidator} from 'js-duration-parser'

const durationValidator = new DurationValidator();
durationValidator.validate('2h 30m'); // true
durationValidator.validate('11x 12s'); // false

Validator can be localized:

import {DurationValidator, TimeIdentifiers} from 'js-duration-parser'

const plIdentifiers = {
  s: 's',
  m: 'm',
  h: 'g',
  d: 'd',
  w: 't',
};
const timeIdentifiers = new TimeIdentifiers();
timeIdentifiers.add('pl', plIdentifiers);

const durationValidator = new DurationValidator(timeIdentifiers);
durationValidator.validate('2h 30m'); // true
durationValidator.validate('11x 12s'); // false

Watch-out! String with a single numeric value (eg. 12 ) is valid, but more numbers separated by space (eg. 12 1) is invalid.

Translation

Using this library you can translate duration string from one locale to another, eg. '2h 30ms 10s' (en) to '2g 30ms 10s' (pl).

import {DurationTranslator, TimeIdentifiers} from 'js-duration-parser'

const plIdentifiers = {
  s: 's',
  m: 'm',
  h: 'g',
  d: 'd',
  w: 't',
};
const timeIdentifiers = new TimeIdentifiers();
timeIdentifiers.add('pl', plIdentifiers);

const durationTranslator = new DurationTranslator(timeIdentifiers);
durationTranslator.translate('5w 3d 2h 13m 20s', 'en', 'pl'); // 5t 3d 2g 13m 20s

API

Full description of all API elements is available here.