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

• Jsdelivr: https://cdn.jsdelivr.net/npm/[email protected]
• Esm.sh: https://esm.sh/[email protected]
• Unpkg: https://unpkg.com/[email protected]

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/[email protected]

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/[email protected]` // 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/[email protected]` // 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/[email protected]` // 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/[email protected]"; //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 }