ms

library0.0.5.dev9jsnpmunverified

The `ms` package is a small, focused utility designed for converting various time formats to milliseconds and vice versa. It parses human-readable strings (e.g., '2 days', '10h', '5s') into their millisecond equivalents and formats millisecond values back into concise, human-readable strings (e.g., 3600000 becomes '1h'). The current stable version is 2.1.3, though version 3.0.0 is actively in canary, introducing significant changes including full TypeScript support and a transition to an ESM-only distribution. This makes `ms` a reliable, lightweight choice for common duration parsing and formatting tasks in both Node.js and browser environments, distinguished by its minimal API and broad adoption in the Vercel ecosystem.

serialization

npm install ms

github ↗package ↗

INSTALL

IMPORT

SIG · MS

serializationjavascriptv0.0.5.dev9

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

✓ import ms from 'ms';

✗ const ms = require('ms');

For `ms` versions 3.0.0+ (currently in canary), the package is ESM-only. Use `import ms from 'ms';`. For versions 2.x.x and earlier, the package is CommonJS, and `const ms = require('ms');` is the correct import.

Demonstrates basic conversion from human-readable strings to milliseconds and vice versa, including negative durations and the 'long' option.

import ms from 'ms'; // Convert human-readable strings to milliseconds console.log(`'2 days' -> ${ms('2 days')}ms`); // 172800000 console.log(`'10h' -> ${ms('10h')}ms`); // 36000000 console.log(`'1.5h' -> ${ms('1.5h')}ms`); // 5400000 console.log(`'-30m' -> ${ms('-30m')}ms`); // -1800000 // Convert milliseconds to human-readable strings console.log(`3600000ms -> '${ms(3600000)}'`); // '1h' console.log(`172800000ms -> '${ms(172800000)}'`); // '2d' console.log(`-600000ms -> '${ms(-600000)}'`); // '-10m' // Usage with options (e.g., long format) console.log(`ms(60000, { long: true }) -> '${ms(60000, { long: true })}'`); // '1 minute'

Debug

Known issues

breakingVersion 3.0.0 (currently in canary) introduces a breaking change by transitioning to an ESM-only distribution with full TypeScript support. Projects using CommonJS `require()` will need to migrate to ESM `import` statements or ensure their build pipeline handles ESM modules.

fix

Migrate from `const ms = require('ms');` to `import ms from 'ms';`. For Node.js, ensure your `package.json` contains `"type": "module"` or use `.mjs` file extensions for your consuming modules.

affects: >=3.0.0-canary.0

breakingVersion 2.0.0 implemented a security fix limiting string input length to 100 characters to prevent Regular Expression Denial of Service (ReDoS) attacks. Inputs longer than 100 characters will now throw an error, which is a behavioral change from prior versions.

fix

Ensure that string inputs to `ms()` do not exceed 100 characters. Implement input validation or truncation if processing arbitrary user-provided strings.

affects: >=2.0.0

gotchaIn v2.1.3, the project's repository and internal references were updated from `zeit` to `vercel`. While primarily an internal and branding change, older build systems or direct file references relying on the `zeit` naming convention might require updates.

fix

Review any explicit references to `zeit/ms` (e.g., in CI configurations, monorepo paths, or dependency mirroring) and update them to `vercel/ms` if necessary. The npm package name remains 'ms'.

affects: >=2.1.3

gotchaPrior to v2.1.1, `ms` had incomplete or buggy support for negative duration strings (e.g., '-5m'), which could lead to incorrect parsing or unexpected results. This was addressed in v2.1.1 and refined in v2.1.2.

fix

Update to `ms` version 2.1.1 or later to ensure reliable and correct handling of negative duration strings.

affects: <2.1.1

Errors

Common errors & fixes

TypeError: ms is not a function

This error often occurs when attempting to call the result of `require('ms')` as a function that itself returns a function, e.g., `require('ms')('1h')()`. The `ms` function is the direct export.

fix

Remove the superfluous parentheses: `const ms = require('ms'); ms('1h');` or simply `require('ms')('1h');` for CommonJS. For ESM, ensure `import ms from 'ms';` and then `ms('1h');`.

Error: "value" must be a string or a number.

The `ms()` function received an argument that is neither a string representing a duration nor a number representing milliseconds (e.g., `null`, `undefined`, an object, or an empty string).

fix

Ensure the input to `ms()` is always a valid string (e.g., '2 days') or a valid number (e.g., 3600000). Always validate external inputs before passing them to `ms()`.

ERR_REQUIRE_ESM

Attempting to use `require('ms')` in a Node.js CommonJS module when `ms` v3.0.0+ is installed. Version 3.x.x is an ESM-only package and cannot be `require`d directly.

fix

Convert your consuming module to ESM by adding `"type": "module"` to your nearest `package.json` file and changing `require('ms')` to `import ms from 'ms';`. Alternatively, for existing CommonJS projects, stick to `ms` v2.x.x.

SyntaxError: Cannot use import statement outside a module

Attempting to use `import ms from 'ms';` in a Node.js file that is treated as a CommonJS module (i.e., it lacks `"type": "module"` in its `package.json` or isn't a `.mjs` file).

fix

Add `"type": "module"` to your project's `package.json` file or rename your file to `.mjs`. If maintaining a CommonJS module, you must use `ms` v2.x.x or earlier with `require()`.

Upgrade

Version history

0.0.5.dev9latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/vercel/ms ↗

packagehttps://www.npmjs.com/package/ms ↗