{"id":11364,"library":"ms","title":"ms - Millisecond Conversion Utility","description":"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.","status":"active","version":"2.1.3","language":"javascript","source_language":"en","source_url":"https://github.com/vercel/ms","tags":["javascript"],"install":[{"cmd":"npm install ms","lang":"bash","label":"npm"},{"cmd":"yarn add ms","lang":"bash","label":"yarn"},{"cmd":"pnpm add ms","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"const ms = require('ms');","symbol":"ms","correct":"import ms from 'ms';"}],"quickstart":{"code":"import ms from 'ms';\n\n// Convert human-readable strings to milliseconds\nconsole.log(`'2 days' -> ${ms('2 days')}ms`);     // 172800000\nconsole.log(`'10h' -> ${ms('10h')}ms`);           // 36000000\nconsole.log(`'1.5h' -> ${ms('1.5h')}ms`);         // 5400000\nconsole.log(`'-30m' -> ${ms('-30m')}ms`);         // -1800000\n\n// Convert milliseconds to human-readable strings\nconsole.log(`3600000ms -> '${ms(3600000)}'`);       // '1h'\nconsole.log(`172800000ms -> '${ms(172800000)}'`);   // '2d'\nconsole.log(`-600000ms -> '${ms(-600000)}'`);     // '-10m'\n\n// Usage with options (e.g., long format)\nconsole.log(`ms(60000, { long: true }) -> '${ms(60000, { long: true })}'`); // '1 minute'\n","lang":"typescript","description":"Demonstrates basic conversion from human-readable strings to milliseconds and vice versa, including negative durations and the 'long' option."},"warnings":[{"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.","message":"Version 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.","severity":"breaking","affected_versions":">=3.0.0-canary.0"},{"fix":"Ensure that string inputs to `ms()` do not exceed 100 characters. Implement input validation or truncation if processing arbitrary user-provided strings.","message":"Version 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.","severity":"breaking","affected_versions":">=2.0.0"},{"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'.","message":"In 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.","severity":"gotcha","affected_versions":">=2.1.3"},{"fix":"Update to `ms` version 2.1.1 or later to ensure reliable and correct handling of negative duration strings.","message":"Prior 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.","severity":"gotcha","affected_versions":"<2.1.1"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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');`.","cause":"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.","error":"TypeError: ms is not a function"},{"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()`.","cause":"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).","error":"Error: \"value\" must be a string or a number."},{"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.","cause":"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.","error":"ERR_REQUIRE_ESM"},{"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()`.","cause":"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).","error":"SyntaxError: Cannot use import statement outside a module"}],"ecosystem":"npm"}