Initial Commit
This commit is contained in:
@@ -0,0 +1,109 @@
|
||||
# @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.
|
||||
|
||||
Reference in New Issue
Block a user