@suaveplan/i18n-formatter-relative-time - Locale-aware relative-time formatting backed by Intl.RelativeTimeFormat. Class wrapper + standalone helper + ergonomic helpers (formatTimeAgo, formatTimeIn, selectRelativeUnit), Zod-validated options, per-(locale, style, numeric) cache, OTel histogram + cache-hit counter. Wave 3 of the @suaveplan/i18n modular split.

Summary

Locale-aware relative-time formatting backed by Intl.RelativeTimeFormat. Wave 3 of the 14-package i18n modular split. Provides both a class (RelativeTimeFormatter) and a standalone helper (formatRelativeTime) plus ergonomic shortcuts (formatTimeAgo, formatTimeIn, selectRelativeUnit, formatRelativeTimeStyled) on top of a per-(locale, style, numeric) cache, Zod-validated options, and the canonical OTel histogram + cache-hit counter that every Wave 3 formatter package emits.

Documentation tree

formatter — Locale-aware relative-time formatting backed by Intl.RelativeTimeFormat. Given a delta in milliseconds (positive for…
- formatter — Locale-aware relative-time formatting backed by Intl.RelativeTimeFormat. Given a delta in milliseconds (positive for…
helpers — Pre-bound shortcuts over formatRelativeTime for the two most common relative-time shapes in product UIs: past-tense (…
- helpers — Pre-bound shortcuts over formatRelativeTime for the two most common relative-time shapes in product UIs: past-tense (…
observability — Per-package OpenTelemetry instruments for @suaveplan/i18n-formatter-relative-time. Exposes a histogram (`i18n.format.…
- observability — Per-package OpenTelemetry instruments for @suaveplan/i18n-formatter-relative-time. Exposes a histogram (`i18n.format.…

Why this exists

Each Intl.* wrapper lives in its own sibling package so consumers can pull only the formatters they actually use. This package is the relative-time slice of Wave 3, with the same shape as @suaveplan/i18n-formatter-number (per-(locale, options-hash) cache, Zod schema, OTel metrics, helper + class twin surface).

Install

bun add @suaveplan/i18n-formatter-relative-time

Quick Start

import {
    formatRelativeTime,
    formatTimeAgo,
    formatTimeIn,
    RelativeTimeFormatter,
    selectRelativeUnit,
} from "@suaveplan/i18n-formatter-relative-time";

formatRelativeTime(-3_600_000, "en-US");          // → "1 hour ago"
formatRelativeTime(86_400_000, "en-US", {
    numeric: "auto",
});                                                 // → "tomorrow"

formatTimeAgo(60_000, "en-US");                   // → "1 minute ago"
formatTimeIn(60_000, "en-US");                    // → "in 1 minute"
selectRelativeUnit(90_000);                       // → { unit: "minutes", value: 2 }

const compact = new RelativeTimeFormatter({ style: "short" });
compact.format(60_000, "en-US");                  // → "in 1 min."

Modules

Subpath	Description
`@suaveplan/i18n-formatter-relative-time`	Root barrel — class + standalone + helpers + observability
`@suaveplan/i18n-formatter-relative-time/formatter`	`RelativeTimeFormatter`, `formatRelativeTime`, `selectRelativeUnit`, `clearRelativeTimeFormatterCache`, types, schema
`@suaveplan/i18n-formatter-relative-time/helpers`	`formatTimeAgo`, `formatTimeIn`, `formatRelativeTimeStyled`, `selectRelativeUnit` only

Modules Documentation

formatter.md — RelativeTimeFormatter class + formatRelativeTime
helpers.md — formatTimeAgo, formatTimeIn, selectRelativeUnit, formatRelativeTimeStyled
observability.md — OTel histogram + cache-hit counter

Public Surface (snapshot)

Export	Kind	Origin
`RelativeTimeFormatter`	class	`formatter.ts`
`formatRelativeTime`	function	`formatter.ts`
`selectRelativeUnit`	function	`formatter.ts`
`clearRelativeTimeFormatterCache`	function	`formatter.ts`
`RelativeTimeFormatterOptionsSchema`	const	`formatter.ts`
`RelativeTimeUnit`	type	`formatter.types.ts`
`RelativeTimeStyle`	type	`formatter.types.ts`
`RelativeTimeNumeric`	type	`formatter.types.ts`
`RelativeTimeFormatterOptions`	type	`formatter.types.ts`
`RelativeTimeUnitSelection`	type	`formatter.types.ts`
`formatTimeAgo`	function	`helpers.ts`
`formatTimeIn`	function	`helpers.ts`
`formatRelativeTimeStyled`	function	`helpers.ts`
`recordRelativeTimeFormat`	function	`observability.ts`
`recordRelativeTimeCacheHit`	function	`observability.ts`
`getRelativeTimeFormatMetricsState`	function	`observability.ts`
`resetRelativeTimeFormatMetricsState`	function	`observability.ts`

Versioning

This package is part of the i18n modular-split rollout. Stays at 0.1.0 until the slim core (Wave 6) cuts the family 1.0.0 release.

Wave 3 Scope

This package is one of eight Wave 3 formatter packages. Pure addition — packages/i18n/i18n/src/formatting/relative-time/ is preserved in the monolith until Wave 6 deletes it.