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

<!-- begin:auto-docs -->
## Documentation tree

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

## 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

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

## Quick Start

```ts
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](src/formatter.md) — `RelativeTimeFormatter` class + `formatRelativeTime`
- [helpers.md](src/helpers.md) — `formatTimeAgo`, `formatTimeIn`, `selectRelativeUnit`, `formatRelativeTimeStyled`
- [observability.md](src/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.