Convert Human Time Formats to Milliseconds in JS – parse-duration

Preview:

Description:

parse-duration is a tiny JavaScript library that converts human-readable duration strings into milliseconds for precise timing calculations.

It takes diverse time notations, like “1hr 30mins”, “2 days”, “1mo” or even “1ns”, and gives you back a simple number representing that duration in milliseconds.

This is useful when dealing with user inputs for timeouts, durations in configuration files, or any scenario where a human-readable time needs to be programmatically understood.

Features:

• Parses various time units: nanoseconds (ns), microseconds (μs), milliseconds (ms), seconds (s), minutes (m), hours (h), days (d), weeks (w), months (mo), and years (y).
• Handles compound expressions like "1hr 20mins" or "1h20m0s".
• Supports negative durations and scientific notation (e.g., "2e3s").
• Allows custom output formats (e.g., return value in minutes instead of milliseconds).
• Locale support for multiple languages, including English, Spanish, French, and more.

How to Use It:

1. Install parse-duration and import it in your JS:

# Yarn
$ yarn add parse-duration
# NPM
$ npm install parse-duration

import parse from 'parse-duration'

// Browser
<script type="module">
import parse from './index.js';
</script>

2. The library defaults to English (‘en’). If you need another locale, say Spanish (‘es’), you import its definition and assign it. Available locales: de, en, es, fr, ja, pt, ru, zh.

import es from './locale/es.js'
parse.unit = es

3. The primary function takes the string to parse and an optional output format (defaults to ‘ms’).

// Different time units
parse('1ns');       // => 0.000001 (ms)
parse('1μs');       // => 0.001 (ms)
parse('1ms');       // => 1 (ms)
parse('1s');        // => 1000 (ms)
parse('1m');        // => 60000 (ms)
parse('1h');        // => 3600000 (ms)
parse('1d');        // => 86400000 (ms)
parse('1w');        // => 604800000 (ms)
parse('1mo');       // => 2629800000 (ms) - based on an average month
parse('1y');        // => 31557600000 (ms) - based on an average year
// Compound expressions
parse('1hr 20mins'); // => 4800000 (ms)
// YouTube format
parse('1h20m0s');    // => 4800000 (ms)
// Comma separated numbers
parse('27,681 ns');  // => 0.027681 (ms) (Note: JS float precision can lead to tiny variations)
// Noisy input
parse('duration: 1h:20min'); // => 4800000 (ms)
// Negatives
parse('-1hr 40mins');    // => -6000000 (ms)
// Exponents
parse('2e3s');           // => 2000000 (ms)

4. You can get the result in units other than milliseconds.

parse('1hr 20mins', 's'); // => 4800 (seconds)
parse('1hr 20mins', 'm'); // => 80 (minutes)
parse('1d', 'h'); // => 24 (hours)

5. If you need a unit not covered by default, you can extend parse.unit:

// Example: Adding 'fortnight'
// parse.unit.d is the value for 'day' in ms
parse.unit['fortnight'] = 14 * parse.unit.d;
parse('1fortnight', 'd'); // => 14 (days)

How it works:

Parse-duration uses a sophisticated regular expression pattern that matches numeric values followed by optional unit identifiers. The core regex /((?:\d{1,16}(?:\.\d{1,16})?|\.\d{1,16})(?:[eE][-+]?\d{1,4})?)\s?([\p{L}]{0,14})/gu captures floating-point numbers with scientific notation support alongside Unicode letter-based unit names.

The parsing process normalizes separators and decimal points first, then iterates through each matched number-unit pair. When units are omitted (like in “1h30”), the library intelligently infers the next smallest unit based on the previous match. This allows formats like “1h30” to be interpreted as “1h30m” automatically.

The library maintains a units lookup table where each unit maps to its millisecond equivalent. During parsing, it multiplies each numeric value by its corresponding unit value and accumulates the total. The final result gets converted to the requested output format and handles negative signs applied to the entire duration string.

FAQs:

Q: What happens with invalid input?
A: Invalid or unrecognized input returns null rather than throwing errors, making it safe to use with user-generated content. Always check for null returns in production code.

Q: Does it handle timezone-aware parsing?
A: No, parse-duration focuses purely on duration intervals, not absolute timestamps. It converts relative time spans to milliseconds without timezone considerations.

Q: Can I parse durations longer than years?
A: The library supports years as the largest unit. For longer durations, multiply the year result by your desired factor or extend the unit system with custom mappings.