110 lines
5.3 KiB
Markdown
110 lines
5.3 KiB
Markdown
# @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.
|
|
|