Overview

ms is a lightweight, zero-dependency JavaScript and TypeScript utility for converting human-readable time strings into milliseconds and formatting millisecond values back into concise or long-form strings. It solves the common problem of working with time durations in code by providing a simple, consistent interface that eliminates the need to manually multiply or divide by conversion constants.

The library accepts inputs such as '2 days', '1h', or '5000' and returns the equivalent number of milliseconds. Conversely, it can take a millisecond number like 60000 and produce '1m' or '1 minute'. This bidirectional conversion makes ms useful for logging, configuration, user-facing displays, and any scenario where durations need to be expressed or parsed in a human-friendly format.

Supported Runtimes

ms is compatible with all major JavaScript runtimes:

The library ships as an ES module and works in any environment that supports modern JavaScript. No platform-specific polyfills or shims are required.

Main Features

Bidirectional Conversion

The primary ms() function handles both directions automatically. When given a string, it parses the time value and returns milliseconds. When given a number, it formats the value into a short string with the appropriate unit.

ms('2 days') // 172800000
ms(60000) // "1m"

Flexible Input Formats

The parser accepts a wide variety of unit names and abbreviations, including singular, plural, short, and long forms. Units can be lowercase, uppercase, or capitalized, with or without a space between the number and unit.

Fractional values like 0.5m, -0.5m, .5m, and -.5m are supported. If no unit is provided (e.g., '100'), the value is treated as milliseconds.

Long-Format Output

When formatting milliseconds, passing { long: true } produces full unit names with proper pluralization.

ms(60000, { long: true }) // "1 minute"
ms(2 * 60000, { long: true }) // "2 minutes"

Negative Durations

Negative values are fully supported in both parsing and formatting directions.

ms('-3 days') // -259200000
ms(-3 * 60000) // "-3m"

Separate Parse and Format Functions

For cases where only one direction is needed, the library exports parse() and format() as standalone functions. This avoids the overhead of type checking and makes the intent clearer in code.

import { parse, format } from 'ms';

parse('1h'); // 3600000
format(2000); // "2s"

Strict Type-Safe Parsing

The parseStrict() function provides compile-time validation of input strings using TypeScript template literal types. It accepts only strings that match the allowed patterns, preventing accidental misuse.

import { parseStrict } from 'ms';

parseStrict('1h'); // 3600000

function example(s: string) {
 return parseStrict(s); // TypeScript error
}

TypeScript Support

As of version 3.0, ms includes full TypeScript definitions with template literal types. The StringValue type can be imported and used to annotate function parameters that should accept only valid time strings.

import { ms, type StringValue } from 'ms';

function example(value: StringValue) {
 ms(value);
}

Tech Stack

Wiki Map

This wiki is organized into the following sections and pages:

• Getting Started
• Overview (this page), Introduction, features, and supported runtimes
• Getting Started, Installation, basic usage, and quick examples
• Architecture
• Architecture, Internal design, module structure, and key flows

Related Pages

• Getting Started
• Architecture