Skip to main content
The parseDuration() function is a lower-level API for parsing duration strings. It provides direct access to parsing with explicit language parameters.

​
Import

import { parseDuration } from 'enhanced-ms';

​
Signature

function parseDuration(
  duration: string,
  language?: Language
): number
​
duration
string
required
The duration string to parse (e.g., "2h 30m", "1 day, 5 hours")
​
language
Language
default:"getLanguage('en')"
The language used for parsing. Obtain a Language object using getLanguage().
​
return
number
The total duration in milliseconds, or 0 if the duration is invalid

​
Examples

​
Basic usage

import { parseDuration } from 'enhanced-ms';

parseDuration("2h 30m")
// Returns: 9000000 (2 hours + 30 minutes in ms)

parseDuration("1 day 5 hours")
// Returns: 104400000

​
With custom language

import { parseDuration, getLanguage } from 'enhanced-ms';

const german = getLanguage('de');
parseDuration("2 stunden 30 minuten", german)
// Returns: 9000000 (2 hours + 30 minutes in ms)

const russian = getLanguage('ru');
parseDuration("2 часа 30 минут", russian)
// Returns: 9000000

​
Flexible input formats

The parser is flexible and accepts various formats: 
import { parseDuration } from 'enhanced-ms';

// With full unit names
parseDuration("2 hours 30 minutes")
// Returns: 9000000

// With abbreviations
parseDuration("2h 30m")
// Returns: 9000000

// With commas
parseDuration("1 day, 5 hours, 30 minutes")
// Returns: 105300000

// Mixed formats
parseDuration("1d 5hr 30min")
// Returns: 105300000

​
Invalid input

import { parseDuration } from 'enhanced-ms';

parseDuration("invalid")
// Returns: 0

parseDuration("")
// Returns: 0

​
Supported units

The function supports parsing the following time units (in English):
  • Years (e.g., "year", "years", "yr", "y")
  • Days (e.g., "day", "days", "d")
  • Hours (e.g., "hour", "hours", "hr", "h")
  • Minutes (e.g., "minute", "minutes", "min", "m")
  • Seconds (e.g., "second", "seconds", "sec", "s")
  • Milliseconds (e.g., "millisecond", "milliseconds", "ms")
  • Microseconds (e.g., "microsecond", "microseconds", "μs")
  • Nanoseconds (e.g., "nanosecond", "nanoseconds", "ns")
Other languages have their own unit names and abbreviations.

​
How it works

The parser:
  1. Converts the input string to lowercase
  2. Uses a language-specific regex to match numbers and unit names
  3. Calculates the total milliseconds by:
    • Extracting each (number, unit) pair
    • Converting each pair to milliseconds
    • Summing all the values
  4. Returns 0 if no valid matches are found

​
Case insensitivity

The parser is case-insensitive: 
import { parseDuration } from 'enhanced-ms';

parseDuration("2 Hours 30 Minutes")
// Returns: 9000000

parseDuration("2 HOURS 30 MINUTES")
// Returns: 9000000

parseDuration("2h 30M")
// Returns: 9000000

​
Decimal values

The parser supports decimal values: 
import { parseDuration } from 'enhanced-ms';

parseDuration("1.5 hours")
// Returns: 5400000 (1.5 hours in ms)

parseDuration("2.25 days")
// Returns: 194400000 (2.25 days in ms)

​
Comparison with ms()

While ms() is the recommended way to parse durations, parseDuration() is useful when:
  • You need explicit control over the language parameter
  • You’re working with Language objects directly
  • You want to avoid the automatic language resolution of ms()
// Using ms()
import ms from 'enhanced-ms';
ms("2h 30m")
// Returns: 9000000

// Using parseDuration()
import { parseDuration, getLanguage } from 'enhanced-ms';
const lang = getLanguage('en');
parseDuration("2h 30m", lang)
// Returns: 9000000

​
See also

Build docs developers (and LLMs) love

Get started for freeTalk to us