ms-tiny

Parse and format time durations in milliseconds. Like ms, but with native TypeScript, ESM + CJS, and compound duration support.

import { parse, format } from "ms-tiny";

parse("2h"); // 7_200_000
parse("1d 3h 30m"); // 99_000_000
format(3_600_000); // "1h"

833 bytes gzipped. Zero dependencies.

_{Demo built with remotion-readme-kit}

Install

npm install ms-tiny

Usage

Parse strings to milliseconds

import { parse } from "ms-tiny";

parse("2h"); // 7_200_000
parse("1.5s"); // 1_500
parse("100"); // 100 (bare number = ms)
parse("1d 6h"); // 108_000_000
parse("-3h"); // -10_800_000

Supported units: ms, s/sec, m/min, h/hr, d/day, w/week, mo/month, y/year (and their plurals).

Format milliseconds to strings

import { format } from "ms-tiny";

format(60_000); // "1m"
format(3_600_000); // "1h"
format(86_400_000, { long: true }); // "1 day"
format(172_800_000, { long: true }); // "2 days"

Error handling

Invalid input throws instead of returning undefined:

parse(""); // throws TypeError
parse("hello"); // throws TypeError
format(NaN); // throws TypeError
format(Infinity); // throws TypeError

Differences from ms

	ms	ms-tiny
TypeScript	@types/ms	built-in
ESM	no	ESM + CJS
Invalid input	undefined	throws
Compound	no	"1h 30m"
Size (gzip)	~950B	833B

The API is split into parse and format instead of a single overloaded function.

Migrating from ms

- import ms from "ms";
- const timeout = ms("2h");
- const label = ms(60000);
+ import { parse, format } from "ms-tiny";
+ const timeout = parse("2h");
+ const label = format(60000);

API

parse(value: string): number

Parses a duration string and returns milliseconds.

format(ms: number, options?: { long?: boolean }): string

Formats milliseconds to a readable string. { long: true } gives "2 hours" instead of "2h".

The tiny-* family

Drop-in replacements for sindresorhus async utilities. All ship ESM + CJS with zero dependencies.

Package	Replaces	What it does
tiny-limit	p-limit	Concurrency limiter
tiny-map	p-map	Concurrent map with order
tiny-retry	p-retry	Retry with exponential backoff
tiny-queue	p-queue	Priority task queue
tiny-ms	ms	Parse/format durations
tiny-escape	escape-string-regexp	Escape regex chars

Want all async utilities in one import? Use tiny-pasync.

Author

---

If this saved you from ERR_REQUIRE_ESM, star the repo or open an issue if something breaks.

License

MIT © Ofer Shapira