Skip to main content

​
Quick start

This guide will help you get started with Enhanced MS quickly. You’ll learn the basic concepts and see real working examples.

​
Basic usage

Enhanced MS provides a single ms function that works in two ways:
  1. Format milliseconds to duration strings - Pass a number
  2. Parse duration strings to milliseconds - Pass a string

​
Import the library

First, import the ms function from the package: 
import { ms } from 'enhanced-ms';

​
Format milliseconds to duration

Pass a number of milliseconds to convert it to a human-readable duration: 
ms(60000);
// "1 minute"

ms(90000);
// "1 minute 30 seconds"

ms(90061000);
// "1 day 1 hour 1 minute 1 second"
By default, the function returns null for durations less than 1 second. You can change this behavior with formatting options.

​
Parse duration strings to milliseconds

Pass a duration string to convert it to milliseconds: 
ms('1 minute');
// 60000

ms('1 minute 30 seconds');
// 90000

ms('1m 30s');
// 90000

ms('1 minute 30 seconds 61 milliseconds');
// 90061
You can use both full unit names (“minute”, “second”) and abbreviations (“m”, “s”) when parsing durations.

​
Formatting options

You can customize how durations are formatted by passing options as the second parameter.

​
Use abbreviations

Shorten unit names to their abbreviations: 
ms(90061, { useAbbreviations: true });
// "1m 30s"

ms(90061000, { useAbbreviations: true });
// "1d 1h 1m 1s"

​
Limit output units

Show only the largest units: 
ms(90061, { unitLimit: 1 });
// "1 minute"

ms(90061000, { unitLimit: 1 });
// "1 day"

ms(90061000, { unitLimit: 2 });
// "1 day 1 hour"

​
Combine options

You can combine multiple options for more control: 
ms(90061, { useAbbreviations: true, unitLimit: 1 });
// "1m"

​
Formatting presets

Enhanced MS includes built-in presets for common formatting patterns.

​
Short format

The short preset uses abbreviations and limits the output to 2 units: 
ms(90061, 'short');
// "1m 30s"

ms(90061000, 'short');
// "1d 1h"

​
Colon notation

The colonNotation preset formats durations in a time-like format: 
ms(90061, 'colonNotation');
// "01:30"

ms(90061000, 'colonNotation');
// "25:01:01"

​
Full precision

The fullPrecision preset includes all units including milliseconds and sub-millisecond units: 
ms(10100, 'fullPrecision');
// "10 seconds 100 milliseconds"

​
Using different languages

You can create a custom ms function for different languages using createMs: 
import { createMs } from 'enhanced-ms';

// Create a Spanish instance
const msEs = createMs({ language: 'es' });
msEs(60000);
// "1 minuto"

// Create a German instance
const msDe = createMs({ language: 'de' });
msDe(60000);
// "1 Minute"

// Create a Russian instance
const msRu = createMs({ language: 'ru' });
msRu(60000);
// "1 минута"
Each language instance also supports parsing duration strings in that language.

​
Set default formatting options

You can set default formatting options when creating a custom instance: 
import { createMs } from 'enhanced-ms';

const ms = createMs({
  language: 'en',
  formatOptions: {
    useAbbreviations: true,
    unitLimit: 2
  }
});

ms(90061000);
// "1d 1h"

// You can still override options per call
ms(90061000, { useAbbreviations: false });
// "1 day 1 hour"

​
Common use cases

Here are some practical examples of using Enhanced MS:

​
Display elapsed time

const start = Date.now();
// ... do some work ...
const elapsed = Date.now() - start;

console.log(`Operation took ${ms(elapsed)}`);
// "Operation took 2 minutes 15 seconds"

​
Parse configuration values

const config = {
  timeout: '30 seconds',
  retryDelay: '5s',
  maxAge: '1 day'
};

const timeoutMs = ms(config.timeout); // 30000
const retryDelayMs = ms(config.retryDelay); // 5000
const maxAgeMs = ms(config.maxAge); // 86400000

​
Format API response times

const apiResponse = {
  data: { /* ... */ },
  responseTime: 1234
};

console.log(`Response time: ${ms(apiResponse.responseTime, 'short')}`);
// "Response time: 1s 234ms"

​
Next steps

Now that you understand the basics, explore the full API documentation to learn about all available options and features.

API reference

Explore all available functions and options

Formatting options

Learn about all formatting options and presets

Build docs developers (and LLMs) love

Get started for freeTalk to us