Tiny millisecond conversion utility
The ms package is a minimalist time conversion utility that handles bidirectional conversion between human-readable time strings and milliseconds. With over 335 million weekly downloads, it's one of the most widely deployed npm packages, serving as a core dependency in frameworks like Express, Socket.io, and debug. Its entire codebase weighs less than 1KB, making it ideal for performance-sensitive applications where bundle size matters.
The package exists to solve a common problem in JavaScript development: working with timers, delays, and durations in a human-friendly way. Native JavaScript requires milliseconds for setTimeout, setInterval, and other timing APIs, but developers think in terms of seconds, minutes, or hours. The ms package bridges this gap without introducing heavy date manipulation libraries.
Developers choose ms when they need simple, reliable time conversions without external dependencies. It supports both short formats ('2d', '10h', '5s') and long formats ('2 days', '10 hours'), handles negative values for countdowns or past durations, and works identically across Node.js and browser environments. Its API is intentionally minimal: one function with optional configuration.
const ms = require('ms');
// Parse human-readable strings to milliseconds
const sessionTimeout = ms('24 hours'); // 86400000
const cacheExpiry = ms('30d'); // 2592000000
const apiDelay = ms('500ms'); // 500
// Use in setTimeout/setInterval
setTimeout(() => {
console.log('Cache expired');
}, ms('5m'));
// Convert milliseconds back to readable format
const startTime = Date.now();
setTimeout(() => {
const elapsed = Date.now() - startTime;
console.log(`Operation took ${ms(elapsed)}`); // 'Operation took 2s'
}, 2000);
// Format with long option for user-facing output
const uploadTime = 125000;
console.log(`Upload completed in ${ms(uploadTime, { long: true })}`); // 'Upload completed in 2 minutes'
// Handle negative values for countdowns
const timeUntilExpiry = ms('1h') - (Date.now() - sessionStart);
if (timeUntilExpiry < 0) {
console.log(`Session expired ${ms(Math.abs(timeUntilExpiry))} ago`);
}
// Configuration example
const config = {
jwtExpiration: ms('7d'),
refreshTokenExpiration: ms('30 days'),
rateLimitWindow: ms('15m'),
maxRequestTimeout: ms('30s')
};Configuration and timeouts: Express apps use ms to define session expiration, cache TTLs, and rate limiting windows with readable syntax like maxAge: ms('7 days') instead of calculating milliseconds manually.
Logging and debugging: The debug package relies on ms to format timestamps and duration measurements in log output, converting execution times from milliseconds to human-readable strings like '234ms' or '2.3s'.
API response formatting: REST APIs and GraphQL resolvers convert database timestamp differences to readable durations for client consumption, such as showing 'last active 5m ago' by calculating ms(Date.now() - user.lastSeen).
CLI tool timers: Command-line applications parse user input like --timeout 30s or --retry-after 5m into milliseconds for internal setTimeout/setInterval calls, avoiding error-prone manual conversions.
Job scheduling: Task queues and cron-like systems define retry intervals and backoff strategies using readable syntax like retryIn: ms('15m'), making configuration files self-documenting without inline comments.
npm install mspnpm add msbun add ms