ms

ms is a minimal, dependency-free JavaScript and TypeScript utility that converts between human-readable time strings and millisecond numbers. Pass it a string like ‘2 days’ or ‘10h’ and it returns the equivalent milliseconds; pass it a number of milliseconds and it returns a compact string such as ‘2m’ or a verbose ‘2 minutes’.

At roughly one small source file it is one of the most widely depended-on packages in the npm ecosystem, downloaded hundreds of millions of times each week. It ships full TypeScript definitions with template-literal types that validate time strings at compile time, and it runs unchanged in browsers, Node.js, Deno, Bun, and the Vercel Edge Runtime.

What You Get

• A single ms() function that parses time strings to milliseconds and formats milliseconds back to strings
• Standalone parse, parseStrict, and format helpers for direction-specific use
• TypeScript StringValue template-literal types that catch invalid time strings at compile time
• Zero runtime dependencies and an Edge Runtime-compatible, tree-shakeable ESM build
• Support for units from milliseconds through years, in short, long, lowercase, uppercase, and spaced forms

Common Use Cases

• Defining cache TTLs, timeouts, and rate-limit windows with readable literals like ms('15m')
• Parsing duration values from environment variables or config files into millisecond numbers
• Rendering elapsed or remaining time in a UI as friendly strings like ‘2 minutes’ or ‘10h’
• Normalizing user-supplied duration input in CLIs and APIs

Under The Hood

Architecture

The entire library lives in src/index.ts. Duration constants (s, m, h, d, w, y, mo) are derived by multiplication from a base of 1000ms, with years fixed at 365.25 days and a month as one-twelfth of a year. The public ms() function is overloaded: given a string it delegates to parse(), given a number it delegates to format(), and any other type throws. parse() runs a single case-insensitive named-capture-group regular expression against the input, extracts the numeric value and optional unit, then routes through a switch on the lowercased unit to multiply by the right constant. format() picks between fmtShort and fmtLong based on the long option, walking descending magnitude thresholds and using a plural() helper to append ‘s’ when the absolute value exceeds 1.5x a unit.

Tech Stack

Written in TypeScript (5.8) targeting an ESM-only, side-effect-free build produced by tsdown. It has zero runtime dependencies. Tooling includes Biome for lint/format, Jest (30) with both a Node and an @edge-runtime/jest-environment for tests, Husky and lint-staged for pre-commit hooks, and @arethetypeswrong/cli to validate published types. It requires Node >= 20.

Code Quality

Quality is high for its size. The src directory contains four dedicated test suites (index.test.ts, parse.test.ts, parse-strict.test.ts, format.test.ts) covering positive, negative, fractional, and error-path inputs, run under both Node and Edge environments. The parse() switch ends with a matchUnit satisfies never exhaustiveness check so a missing unit is a compile-time error, and input length is bounded (1-99 chars) to guard the regex. Error messages are explicit and include the offending value.

API Design

The API is deliberately tiny and ergonomic: one function that does the obvious thing in each direction, plus named helpers for callers who want intent to be explicit. Template-literal StringValue types give autocomplete and compile-time validation of duration strings without any runtime cost, and the exported type can be imported for custom narrowing. The README is thorough, with copy-paste examples for every unit, TypeScript usage, and Edge Runtime deployment. Getting started requires no configuration.