npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

js-duration-parser

v1.1.3

Published

Converter between human readable duration and time units

Downloads

903

Readme

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.