ms-ts

An alternative to the ms library in the type world: exposes a Ms utility type which, for a string in ms time format, produces the number of milliseconds as a type.

import {type Ms, ms} from 'ms-ts';

const duration1: Ms<'42ms'> = 42;
const duration2: Ms<'42s'> = 42_000;
// Error: "Type '43000' is not assignable to type '42000'."
const duration3: Ms<'42s'> = 43_000;

const config = {
  // In expressions, use `satisfies` and *never* `as`:
  duration1: 2_520_000 satisfies Ms<'42m'>,
  duration2: 271_296_000 satisfies Ms<'3.14d'>,
  // Or `ms` identity function:
  duration3: ms<'-3.14d'>(-271_296_000),
};

Installation

For pnpm, npm & yarn users respectively:

pnpm i ms-ts
npm i ms-ts
yarn add ms-ts

Minimum supported Node.js version is 22 (although it will very likely work in older versions).

Features

• Supported units:
  • ms, msec(s), millisecond(s)
  • s, sec(s), second(s)
  • m, min(s), minute(s)
  • h, hr(s), hour(s)
  • d, day(s)
  • w, week(s)
  • y, yr(s), year(s) (365.25 days, as in the original implementation)
• Unit names are case-insensitive (e.g. '42MS', '42S' are valid).
• Supports negative & floating point numbers.
• Ignores whitespace at the beginning and end of the input string, between the sign and the number, and between the number and the unit.
• Ignores leading zeroes.
• If parsing fails, returns never as the result.
• It does not perform an inverse conversion (number of milliseconds to a string with a unit).
• Check more usage examples in the test directory of the repository.
• Has zero dependencies: types from type-fest and ts-arithmetic are inlined directly into the package rather than declared as dependencies² because they are not supposed to change anyway.

Recommended usage & pitfalls

When assigning the number of milliseconds, just declare the type after a variable name:

const duration: Ms<'42s'> = 42_000;

For type-checking to work in expressions, always use satisfies operator (TypeScript >= 4.9) and never use as:

const config = {
  duration1: 2_520_000 satisfies Ms<'42m'>, // ✅ Always use `satisfies` in expressions to assert a type
  duration2: 1 as Ms<'42m'>, // ❌ Avoid using `as`! No error!
};

You may also use an exported identity function¹ ms and pass the time string as a generic parameter:

import {type Ms, ms} from 'ms-ts';

const config = {
  duration1: ms<'42m'>(2_520_000), // Forces you to pass `2_520_000`
};

---

¹ An identity function is a function that returns its first argument and does nothing else: fn = (v) => v.

² Their copyright notices are preserved in THIRD_PARTY_NOTICES.md.

Contributors

Andrew Kazakov 💻 📖 💡 🚇 🚧 ⚠️ 🔧

Add your contributions