Skip to main content

MS utility library for formatting/parsing milliseconds to/from strings in most locales

Works with
This package works with Bun
This package works with Cloudflare Workers
This package works with Node.js
This package works with Deno
This package works with Browsers
JSR Score
100%
Published
a month ago (0.0.5)

License npm JSR Vitest npm bundle size GitHub Repo stars

ms-relative

Ms-relative is a new ms utility library build from the ground up that mines Intl.RelativeTimeFormat to be available in most languages/locales.

Features

  • Mines Intl.RelativeTimeFormat to be available in most languages/locales.
  • Treeshakable so you only bundle what you.
  • Modular so you can pick what you need & to get the smallest bundles from your favourite bundler. (esm only)
  • Available in both ESM & Commonjs (npm only)
  • Available on NPM, JSR & your favorite js cdn
  • Bundled for browsers & commonjs
  • Most building blocks are exported, so you can get the result from a step earlier if wanted

Note

Can only be used with least Node 16‎.6, Deno 1‎.12, Chrome/Edge 92, Firefox 90 & Safari 15‎.4.

Install

Via NPM

npm i ms-relative --save
pnpm add ms-relative
yarn add ms-relative
bun add ms-relative

Via JSR

npx jsr add @wilcosp/ms-relative
yarn dlx jsr add @wilcosp/ms-relative
pnpm dlx jsr add @wilcosp/ms-relative
bunx jsr add @wilcosp/ms-relative
deno add @wilcosp/ms-relative

Via cdn

Examples

Unit variables

All units are being exported

import { second, minute, hour, day, week, year } from "ms-relative" // for npm
// or
import { second, minute, hour, day, week, year  } from "@wilcosp/ms-relative" // for jsr
// or
import { second, minute, hour, day, week, year  } from `https://cdn.jsdelivr.net/npm/ms-relative@0.0.5

second // amount of ms in a second
minute // amount of ms in a minute
hour // amount of ms in an hour
day // amount of ms in a day
week // amount of ms in a week
year // average amount of ms in a year

format

Format ms time to human readable string

import { format, day, second, year, week } from "ms-relative" // for npm
// or
import { format, day, second, year, week } from "@wilcosp/ms-relative" // for jsr
// or
import { format, day, second, year, week } from `https://cdn.jsdelivr.net/npm/ms-relative@0.0.5` // cdn (can also be esm.sh or unpkg)

format(1080003000, { style: "long", locale:  "en-US"}) => "5 days 3 seconds"
format(5 * day + 3 * second, { style: "long", locale:  "en-US"}) => "5 days 3 seconds"

format(489348000000, { style: "short", max: 2, locale: "en-US"}) => "6 yr. 10 wk."
format(year * 6 + 10 * week + 4 * day, { style: "short", max: 2, locale: "en-US"}) => "6 yr. 10 wk."

formatList

similar to format but uses Intl.ListFormat to join the parts together

import { formatList, day, second, year, week } from "ms-relative" // for npm
// or
import { format, day, second, year, week } from "@wilcosp/ms-relative" // for jsr
// or
import { format, day, second, year, week } from `https://esm.sh/ms-relative@0.0.5` // cdn (can also be jsdelivr or unpkg)

formatList(1080003000, { relativeStyle: "long", listStyle: "long", locale:  "en-US"}) => "5 days and 3 seconds"
formatList(5 * day + 3 * second, { relativeStyle: "long", listStyle: "short", locale:  "en-US"}) => "5 days & 3 seconds"

formatList(489348000000, { relativeStyle: "short", listStyle: "short", max: 2, locale: "en-US"}) => "6 yr. & 10 wk."
formatList(year * 6 + 10 * week + 4 * day, { relativeStyle: "short", listStyle: "short", listType: "unit", max: 2, locale: "en-US"}) => "6 yr., 10 wk."

parseToMs

Parse a human readable string to ms

(because ms isn't supported by relativeTimeFormat you need to leave out the unit to add ms)

import { parseToMs } from "ms-relative" // for npm
// or
import { parseToMs } from "@wilcosp/ms-relative" // for jsr
// or
import { parseToMs } from `https://esm.sh/ms-relative@0.0.5` // cdn (can also be jsdelivr or unpkg)

parseToMs("year 5 days 10 minutes", { locale: "en-US", style: "long" }) => 79_974_600_000

msToMap & msToObject

Get a Map or object from a given time in ms with the keys being the unit types

import { msToMap, msToObject, year, minute } from "ms-relative"; // for npm
// or
import { msToMap, msToObject, year, minute } from "@wilcosp/ms-relative"; // for jsr
// or
import { msToMap, msToObject, year, minute } from "https://unpkg.com/ms-relative@0.0.5"; //cdn, can also be used with jsdelivr or esn.sh

msToMap(year * 6 + minute * 4) => Map([ ["year", 6], ["minute", 4] ])

msToObject(day * 5 + hour * 9 + second * 10, {max: 2}) => { day: 5,  hour: 9 }
Built and signed on
GitHub Actions
View transparency log

Add Package

deno add @wilcosp/ms-relative

Import symbol

import * as mod from "@wilcosp/ms-relative";

Add Package

npx jsr add @wilcosp/ms-relative

Import symbol

import * as mod from "@wilcosp/ms-relative";

Add Package

yarn dlx jsr add @wilcosp/ms-relative

Import symbol

import * as mod from "@wilcosp/ms-relative";

Add Package

pnpm dlx jsr add @wilcosp/ms-relative

Import symbol

import * as mod from "@wilcosp/ms-relative";

Add Package

bunx jsr add @wilcosp/ms-relative

Import symbol

import * as mod from "@wilcosp/ms-relative";