Migration from 'ms'

Enhanced MS is a drop-in replacement for the popular ms package with additional features. This guide helps you migrate your existing code.

Why migrate?

Enhanced MS provides several advantages over the original ms package:

Feature	Enhanced MS	ms
Convert milliseconds to duration	✅	✅
Convert milliseconds to multiple units	✅	❌
Convert duration to milliseconds	✅	✅
Convert multiple duration units	✅	❌
Localization support	✅	❌
Format presets	✅	❌
Customizable unit display	✅	Limited

Basic compatibility

For basic usage, Enhanced MS is a direct replacement:

Before (ms)
After (Enhanced MS)

import ms from 'ms';

ms(60000);
// "1m"

ms('1 hour');
// 3600000

import ms from 'enhanced-ms';

ms(60000);
// "1 minute"

ms('1 hour');
// 3600000

The main difference is that Enhanced MS uses full unit names by default, while ms uses abbreviations. To get the same abbreviated output, use the short preset or useAbbreviations option.

Installation

Replace the ms package with enhanced-ms:

npm
pnpm
yarn

npm uninstall ms
npm install enhanced-ms

pnpm remove ms
pnpm add enhanced-ms

yarn remove ms
yarn add enhanced-ms

Import changes

The import statement remains the same:

// Both packages use the same import
import ms from 'enhanced-ms';

Formatting differences

Default output format

The most noticeable difference is the default output format:

ms
Enhanced MS

import ms from 'ms';

ms(60000);
// "1m"

ms(3600000);
// "1h"

ms(86400000);
// "1d"

import ms from 'enhanced-ms';

ms(60000);
// "1 minute"

ms(3600000);
// "1 hour"

ms(86400000);
// "1 day"

Getting abbreviated output

To match the original ms behavior, use the short preset:

import ms from 'enhanced-ms';

ms(60000, 'short');
// "1m"

ms(3600000, 'short');
// "1h"

ms(86400000, 'short');
// "1d"

Or use the useAbbreviations option:

ms(60000, { useAbbreviations: true });
// "1m"

Setting default abbreviations

If you want all calls to use abbreviations by default, create a custom instance:

import { createMs } from 'enhanced-ms';

const ms = createMs({
  formatOptions: { useAbbreviations: true }
});

ms(60000);
// "1m"

ms(3600000);
// "1h"

Long option in ms

The original ms package accepts a long option:

ms
Enhanced MS

import ms from 'ms';

ms(60000);
// "1m"

ms(60000, { long: true });
// "1 minute"

ms(3600000, { long: true });
// "1 hour"

import ms from 'enhanced-ms';

// Full names are the default
ms(60000);
// "1 minute"

ms(3600000);
// "1 hour"

// Use short preset for abbreviations
ms(60000, 'short');
// "1m"

Multiple duration units

Unlike ms, Enhanced MS can display multiple time units:

ms
Enhanced MS

import ms from 'ms';

ms(90000);
// "2m" (rounds to nearest unit)

ms(5400000);
// "2h" (rounds to nearest unit)

import ms from 'enhanced-ms';

ms(90000);
// "1 minute 30 seconds" (shows exact duration)

ms(5400000);
// "1 hour 30 minutes" (shows exact duration)

To get single-unit output like ms, use unitLimit:

ms(90000, { unitLimit: 1 });
// "1 minute"

ms(5400000, { unitLimit: 1 });
// "1 hour"

Parsing behavior

Parsing works identically in both packages:

// Both return the same values
ms('1s');     // 1000
ms('1m');     // 60000
ms('1h');     // 3600000
ms('1d');     // 86400000
ms('1y');     // 31557600000

But Enhanced MS also supports multiple units:

// ms package doesn't support this
ms('1 hour 30 minutes');
// 5400000

ms('2 days 3 hours');
// 183600000

ms('1h 30m 45s');
// 5445000

Error handling

Both packages handle errors similarly:

// Both throw TypeError for invalid input
ms(NaN);
// TypeError: Expected a finite number

ms(Infinity);
// TypeError: Expected a finite number

// Both return 0 for invalid strings
ms('invalid');
// 0

Migration strategies

Strategy 1: Minimal changes (recommended)

Replace the package and update the default formatting:

import { createMs } from 'enhanced-ms';

// Create instance that mimics ms behavior
const ms = createMs({
  formatOptions: {
    useAbbreviations: true,
    unitLimit: 1
  }
});

// Now works exactly like the original ms
ms(60000);     // "1m"
ms(3600000);   // "1h"

Strategy 2: Gradual adoption

Use both packages during migration:

import oldMs from 'ms';
import { ms as newMs } from 'enhanced-ms';

// Use old ms for existing code
const timeout = oldMs('1 hour');

// Use new ms for new features
const duration = newMs(90000);
// "1 minute 30 seconds"

Strategy 3: Full migration

Embrace the new features and update your code:

import ms from 'enhanced-ms';

// Old code (required string concatenation)
// const message = `Uptime: ${ms(uptime)} ${ms(uptime, { long: true })}`;

// New code (cleaner, more readable)
const message = `Uptime: ${ms(uptime)}`;
// "Uptime: 2 days 3 hours 15 minutes"

Common migration patterns

Timeouts and intervals

Before
After

import ms from 'ms';

setTimeout(() => {
  console.log('Done!');
}, ms('5 minutes'));

setInterval(() => {
  console.log('Tick');
}, ms('30 seconds'));

import ms from 'enhanced-ms';

// Parsing works identically
setTimeout(() => {
  console.log('Done!');
}, ms('5 minutes'));

setInterval(() => {
  console.log('Tick');
}, ms('30 seconds'));

Display durations

Before
After

import ms from 'ms';

const elapsed = Date.now() - startTime;
console.log(`Elapsed: ${ms(elapsed)}`);
// "Elapsed: 5m"

import ms from 'enhanced-ms';

const elapsed = Date.now() - startTime;
console.log(`Elapsed: ${ms(elapsed)}`);
// "Elapsed: 5 minutes 23 seconds"

// Or use short format for compact output
console.log(`Elapsed: ${ms(elapsed, 'short')}`);
// "Elapsed: 5m 23s"

Configuration files

Before
After

import ms from 'ms';

const config = {
  timeout: ms('30s'),
  retryDelay: ms('5m'),
  cacheExpiry: ms('1h')
};

import ms from 'enhanced-ms';

// Parsing is identical
const config = {
  timeout: ms('30s'),
  retryDelay: ms('5m'),
  cacheExpiry: ms('1h')
};

// But you can now use full unit names too
const config = {
  timeout: ms('30 seconds'),
  retryDelay: ms('5 minutes'),
  cacheExpiry: ms('1 hour')
};

// Or even multiple units
const config = {
  timeout: ms('30 seconds'),
  retryDelay: ms('5 minutes 30 seconds'),
  cacheExpiry: ms('1 hour 30 minutes')
};

TypeScript support

Both packages include TypeScript definitions. Enhanced MS has more detailed types:

import ms, { createMs, type FormatOptions } from 'enhanced-ms';

// All properly typed
const duration: string | null = ms(60000);
const milliseconds: number = ms('1 hour');

const options: FormatOptions = {
  useAbbreviations: true,
  unitLimit: 2
};

Performance considerations

Enhanced MS includes significant performance improvements:

Formatting is approximately 10% faster
Parsing is up to 1,100% faster for complex durations

These performance improvements mean you can confidently use Enhanced MS in performance-critical code paths.

Breaking changes

The only breaking changes from ms are:

Default output format: Full unit names instead of abbreviations
Multiple units: Shows all relevant units instead of just one
Math operators removed: The ability to parse math expressions (like “2 * 1h”) has been removed in v4.0

Math operator support may be re-added in a future version as an optional feature.

Getting help

If you encounter issues during migration:

Check the GitHub repository
Review the changelog
Open an issue for migration-specific questions

Use Cases

Why migrate?

Basic compatibility

Installation

Import changes

Formatting differences

Default output format

Getting abbreviated output

Setting default abbreviations

Long option in ms

Multiple duration units

Parsing behavior

Error handling

Migration strategies

Strategy 1: Minimal changes (recommended)

Strategy 2: Gradual adoption

Strategy 3: Full migration

Common migration patterns

Timeouts and intervals

Display durations

Configuration files

TypeScript support

Performance considerations

Breaking changes

Getting help

Build docs developers (and LLMs) love

Use Cases

​Why migrate?

​Basic compatibility

​Installation

​Import changes

​Formatting differences

​Default output format

​Getting abbreviated output

​Setting default abbreviations

​Long option in ms

​Multiple duration units

​Parsing behavior

​Error handling

​Migration strategies

​Strategy 1: Minimal changes (recommended)

​Strategy 2: Gradual adoption

​Strategy 3: Full migration

​Common migration patterns

​Timeouts and intervals

​Display durations

​Configuration files

​TypeScript support

​Performance considerations

​Breaking changes

​Getting help

Build docs developers (and LLMs) love

Why migrate?

Basic compatibility

Installation

Import changes

Formatting differences

Default output format

Getting abbreviated output

Setting default abbreviations

Long option in ms

Multiple duration units

Parsing behavior

Error handling

Migration strategies

Strategy 1: Minimal changes (recommended)

Strategy 2: Gradual adoption

Strategy 3: Full migration

Common migration patterns

Timeouts and intervals

Display durations

Configuration files

TypeScript support

Performance considerations

Breaking changes

Getting help