shelving/util/durationmodule

These helpers measure the distance between two dates — in milliseconds, seconds, minutes, hours, days, weeks, months, or years — and format that distance for display. They exist so callers never have to do raw date arithmetic or wrangle Intl.DurationFormat directly.

Things to know:

Usage

Counting units between dates

ts
import { getDuration, getDaysUntil, getMonthsAgo, getMilliseconds } from "shelving/util";

const launch = new Date("2025-06-01");
const now = "now";

getDuration(now, launch);
// { years: 0, months: 0, weeks: 1, days: 3, hours: 5, minutes: 0, seconds: 0, milliseconds: 0 }

getDaysUntil(launch);          // e.g. 10  (calendar days from today)
getMonthsAgo(new Date("2024-01-15")); // e.g. 16
getMilliseconds(now, launch);  // raw ms difference

Checking relative position

ts
import { isPast, isFuture, isToday } from "shelving/util";

isPast(new Date("2020-01-01"));   // true
isFuture(new Date("2099-12-31")); // true
isToday(new Date());              // true

Formatting for display

ts
import { formatWhen, formatUntil, formatAgo, formatDuration } from "shelving/util";

formatWhen(new Date(Date.now() + 5 * 60_000));  // "in 5min"
formatWhen(new Date(Date.now() - 10_000));      // "just now"
formatAgo(new Date("2024-01-01"));              // e.g. "16mo"
formatUntil(new Date("2026-01-01"));            // e.g. "7mo"

formatDuration({ years: 1, months: 2, days: 3 }); // "1 year, 2 months, 3 days"
formatDuration({ hours: 2, minutes: 30 }, { style: "narrow" }); // "2hr 30min"

Best-fit unit selection

ts
import { getBestDurationUnit, DURATION_UNITS } from "shelving/util";

const unit = getBestDurationUnit(3 * 24 * 60 * 60 * 1000); // → "day" Unit
unit.format(unit.from(3 * 24 * 60 * 60 * 1000));           // "3d"

Functions

Go

getMilliseconds()function

Get the millisecond difference between two dates.

getMilliseconds(from?: PossibleDate, to?: PossibleDate, caller: AnyCaller = getMilliseconds): number
Go

getDuration()function

Count the various time units between two dates and return a Duration format.

getDuration(from?: PossibleDate, to?: PossibleDate, caller: AnyCaller = getDuration): DurationData
Go

getUntil()function

Get the various time units until a certain date.

getUntil(target: PossibleDate, current: PossibleDate = "now", caller: AnyCaller = getUntil): DurationData
Go

getAgo()function

Get the various time units since a certain date.

getAgo(target: PossibleDate, current: PossibleDate = "now", caller: AnyCaller = getAgo): DurationData
Go

getMillisecondsUntil()function

Count the milliseconds until a date.

getMillisecondsUntil(target: PossibleDate, current?: PossibleDate, caller: AnyCaller = getMillisecondsUntil): number
Go

getMillisecondsAgo()function

Count the milliseconds since a date.

getMillisecondsAgo(target: PossibleDate, current?: PossibleDate, caller: AnyCaller = getMillisecondsAgo): number
Go

getSecondsUntil()function

Count the whole seconds until a date.

getSecondsUntil(target: PossibleDate, current?: PossibleDate, caller: AnyCaller = getSecondsUntil): number
Go

getSecondsAgo()function

Count the whole seconds since a date.

getSecondsAgo(target: PossibleDate, current?: PossibleDate, caller: AnyCaller = getSecondsAgo): number
Go

getMinutesUntil()function

Count the whole minutes until a date.

getMinutesUntil(target: PossibleDate, current?: PossibleDate, caller: AnyCaller = getMinutesUntil): number
Go

getMinutesAgo()function

Count the whole minutes since a date.

getMinutesAgo(target: PossibleDate, current?: PossibleDate, caller: AnyCaller = getMinutesAgo): number
Go

getHoursUntil()function

Count the whole hours until a date.

getHoursUntil(target: PossibleDate, current?: PossibleDate, caller: AnyCaller = getHoursUntil): number
Go

getHoursAgo()function

Count the whole hours since a date.

getHoursAgo(target: PossibleDate, current?: PossibleDate, caller: AnyCaller = getHoursAgo): number
Go

getDaysUntil()function

Count the calendar days until a date.

getDaysUntil(target: PossibleDate, current?: PossibleDate, caller: AnyCaller = getDaysUntil): number
Go

getDaysAgo()function

Count the calendar days since a date.

getDaysAgo(target: PossibleDate, current?: PossibleDate, caller: AnyCaller = getDaysAgo): number
Go

getWeeksUntil()function

Count the whole weeks until a date.

getWeeksUntil(target: PossibleDate, current?: PossibleDate, caller: AnyCaller = getWeeksUntil): number
Go

getWeeksAgo()function

Count the whole weeks since a date.

getWeeksAgo(target: PossibleDate, current?: PossibleDate, caller: AnyCaller = getWeeksAgo): number
Go

getMonthsUntil()function

Count the calendar months until a date.

getMonthsUntil(target: PossibleDate, current?: PossibleDate, caller: AnyCaller = getMonthsUntil): number
Go

getMonthsAgo()function

Count the calendar months since a date.

getMonthsAgo(target: PossibleDate, current?: PossibleDate, caller: AnyCaller = getMonthsAgo): number
Go

getYearsUntil()function

Count the calendar years until a date.

getYearsUntil(target: PossibleDate, current?: PossibleDate, caller: AnyCaller = getYearsUntil): number
Go

getYearsAgo()function

Count the calendar years since a date.

getYearsAgo(target: PossibleDate, current?: PossibleDate, caller: AnyCaller = getYearsAgo): number
Go

isPast()function

Is a date in the past?

isPast(target: PossibleDate, current?: PossibleDate, caller: AnyCaller = isPast): boolean
Go

isFuture()function

Is a date in the future?

isFuture(target: PossibleDate, current?: PossibleDate, caller: AnyCaller = isFuture): boolean
Go

isToday()function

Is a date today (taking into account midnight).

isToday(target: PossibleDate, current?: PossibleDate, caller: AnyCaller = isToday): boolean
Go

getBestDurationUnit()function

Get a best-fit duration unit based on an amount in milliseconds.

getBestDurationUnit(ms: number): Unit<DurationUnitKey>
Go

formatWhen()function

Format a compact best-fit description of when a date happens or happened, e.g. in 10d or 2h ago or in 1w or just now

formatWhen(target: PossibleDate, current?: PossibleDate, options?: UnitFormatOptions, caller: AnyCaller = formatWhen): string
Go

formatUntil()function

Format a compact best-fit description of how long until a date, e.g. 10d or 2h or -1w

formatUntil(target: PossibleDate, current?: PossibleDate, options?: UnitFormatOptions, caller: AnyCaller = formatUntil): string
Go

formatAgo()function

Format a compact best-fit description of how long since a date, e.g. 10d or 2h or -1w

formatAgo(target: PossibleDate, current?: PossibleDate, options?: UnitFormatOptions, caller: AnyCaller = formatAgo): string
Go

formatDuration()function

Format a duration as a string, e.g. 1 year, 2 months, 3 days or 1y 2m 3d

formatDuration(duration: DurationData, options?: DurationFormatOptions): string

Types

Go

DurationDatatype

Duration data object keyed by Intl.DurationFormatUnit.

{ [K in Intl.DurationFormatUnit]?: number }
Go

DurationUnitKeytype

Key for one of the duration units in DURATION_UNITS.

MapKey<typeof DURATION_UNITS>

Constants

Go

DURATION_UNITSconstant

List of duration units (millisecond through year) keyed by unit reference.