skills/plugins/document-navigator/docs/localization/i18n/i18n-formatter-relative-time/README.md

@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.