parse-duration

What is parse-duration?

The parse-duration npm package is a utility for parsing human-readable duration strings into milliseconds. It is useful for converting time durations specified in various formats (like '2h', '1d', '5m', etc.) into a standard numerical format that can be used programmatically.

What are parse-duration's main functionalities?

Parse human-readable duration strings

This feature allows you to convert a human-readable duration string (e.g., '2h' for 2 hours) into milliseconds. The code sample demonstrates parsing '2h' into 7200000 milliseconds.

const parseDuration = require('parse-duration');
const duration = parseDuration('2h');
console.log(duration); // 7200000

Parse complex duration strings

This feature allows you to parse more complex duration strings that include multiple time units. The code sample shows how '1d 2h 30m' is parsed into 93600000 milliseconds.

const parseDuration = require('parse-duration');
const duration = parseDuration('1d 2h 30m');
console.log(duration); // 93600000

Handle invalid input gracefully

This feature ensures that invalid input strings are handled gracefully by returning null. The code sample demonstrates parsing an invalid string 'invalid', which results in null.

const parseDuration = require('parse-duration');
const duration = parseDuration('invalid');
console.log(duration); // null

Other packages similar to parse-duration

ms

The 'ms' package is another utility for parsing and formatting milliseconds. It can convert human-readable strings into milliseconds and vice versa. Compared to parse-duration, 'ms' is more focused on simplicity and has a smaller feature set.

moment-duration-format

The 'moment-duration-format' package extends Moment.js to format durations. It is more feature-rich compared to parse-duration, offering advanced formatting options and integration with Moment.js for more complex date and time manipulations.

humanize-duration

The 'humanize-duration' package is designed to convert milliseconds into human-readable strings. It is essentially the reverse of parse-duration, focusing on converting numerical durations into readable formats.

README

parse-duration

Convert a human readable duration to ms.

Usage

import parse from 'parse-duration'

// parse different time units
let ns = parse('1ns')       // => 1 / 1e6
let μs = parse('1μs')       // => 1 / 1000
let ms = parse('1ms')       // => 1
let s = parse('1s')         // => ms * 1000
let m = parse('1m')         // => s * 60
let h = parse('1h')         // => m * 60
let d = parse('1d')         // => h * 24
let w = parse('1w')         // => d * 7
let mo = parse('1mo')       // => y / 12
let y = parse('1y')         // => d * 365.25

// compound expressions
parse('1hr 20mins')         // => 1 * h + 20 * m
parse('1 hr 20 mins')       // => 1 * h + 20 * m

// youtube format
parse('1h20m0s')            // => 1 * h + 20 * m

// comma seperated numbers
parse('27,681 ns')          // => 27681 * ns

// noisy input
parse('duration: 1h:20min') // => 1 * h + 20 * m

// negatives
parse('-1hr 40mins')        // => -1 * h - 40 * m

// exponents
parse('2e3s')               // => 2000 * s

// custom output format
parse('1hr 20mins', 'm')    // => 80

// add units
parse.unit['μs'] = parse.unit.microsecond
parse('5μs')                // => 0.005

Locales

Switch the default en locale to another language (see /locale).

import es from 'parse-duration/locale/es.js'
import parse from 'parse-duration'

parse.unit = es

parse('1 hora 20 minutos', 'm') // 80

Safety

In sensitive APIs make sure input string is reasonably short (under 100 characters).

ॐ