parse() and ms()

This page documents the parse() and ms() functions, which convert human-readable time strings into their equivalent value in milliseconds. Both functions share the same core implementation and support identical input formats.

Signature

Both functions are exported from the package root and share the same signature:

function parse(input: string): number
function ms(input: string): number

Source: src/index.ts

Both accept a single string argument and return a number representing milliseconds. The only difference between the two is the export name; ms() is provided as a more concise alias for parse().

Supported Time Units

The following time units are recognized by both functions:

Source:

The unit keywords are case-insensitive and can appear in any order within the input string.

Input Format

The input string consists of one or more duration components separated by spaces. Each component is a numeric value followed immediately by a unit keyword (with no space between the number and the unit). For example:

• "5s" → 5 seconds
• "2h 30m" → 2 hours and 30 minutes
• "1d 12h" → 1 day and 12 hours

The parser extracts numeric values and unit keywords using a regular expression that matches the pattern /(\d*\.?\d+)\s*(ms|milli(?:second)?s?|s(?:ec(?:ond)?s?)?|m(?:in(?:ute)?s?)?|h(?:rs?|ours?)?|d(?:ays?)?|w(?:eeks?)?|mo(?:nths?)?|y(?:ears?)?)/gi.

Source:

Negative Durations

Both parse() and ms() support negative durations. A minus sign (-) can be placed at the beginning of the input string to negate the entire duration:

• "-5s" → -5000 ms
• "-1h 30m" → -5,400,000 ms

The negative sign applies to the total computed value, not to individual components. Mixed positive and negative components within a single string are not supported.

Fractional Values

Fractional numeric values are supported for any time unit. The parser handles decimal numbers in the format X.Y:

• "1.5h" → 5,400,000 ms (1.5 hours)
• "0.5d" → 43,200,000 ms (half a day)
• "2.5s" → 2,500 ms

Fractional values are multiplied by the unit's millisecond multiplier, and the result is summed with other components. The final return value is a standard JavaScript number, which may include fractional milliseconds if the input contains fractional values of smaller units.

Return Value

Both functions return a number representing the total milliseconds. For valid inputs, the return value is always a finite number. Invalid inputs (strings that do not match any recognized pattern) cause the functions to throw an error.

Error Handling

If the input string does not contain any recognizable duration components, both functions throw an error. The error message is generated by the internal parse function and propagated to the caller.

Difference Between parse() and ms()

The two functions are functionally identical. ms() is simply an alias that re-exports parse() under a shorter, more conventional name. The source code demonstrates this:

export { parse, parse as ms };

Source: src/index.ts

Use whichever name is more readable in your codebase. The ms() name is shorter and matches common usage in the Node.js ecosystem, while parse() is more descriptive about what the function does.

Usage Examples

import { parse, ms } from 'ms';

// Both functions work identically
parse('5s'); // 5000
ms('5s'); // 5000

parse('2h 30m'); // 9,000,000
ms('2h 30m'); // 9,000,000

parse('-1d'); // -86,400,000
ms('-1d'); // -86,400,000

parse('1.5h'); // 5,400,000
ms('1.5h'); // 5,400,000

Related Pages

• format(), Convert milliseconds back to a human-readable time string
• parseStrict(), A stricter variant of parse() with validation
• TypeScript Types, Type definitions for the ms package
• Architecture, Overall package structure and design decisions