first commit
This commit is contained in:
128
docs/localization/i18n/i18n-formatter-date/README.md
Normal file
128
docs/localization/i18n/i18n-formatter-date/README.md
Normal file
@@ -0,0 +1,128 @@
|
||||
# @suaveplan/i18n-formatter-date - Intl.DateTimeFormat wrapper for the @suaveplan/i18n family — 8-preset table (short/medium/long/full/time-short/time-long/date-short/date-long), formatDate / formatTime / formatDateOnly / formatDateRange / getDayNames / getMonthNames. Per-(locale, options-hash) cache, Zod-validated options, OTel histogram + cache-hit counter, structured I18nError mapping. Universal leaf package.
|
||||
|
||||
## Summary
|
||||
|
||||
Wrapper around `Intl.DateTimeFormat` for the `@suaveplan/i18n` family
|
||||
— 8-preset table (short/medium/long/full × date+time/time-only/date-only),
|
||||
range rendering, day/month name lists, and a per-(locale,
|
||||
options-hash) cache.
|
||||
|
||||
<!-- begin:auto-docs -->
|
||||
## Documentation tree
|
||||
|
||||
- [day-month-names](./src/day-month-names/day-month-names.md) — `getDayNames(locale, style?)` and `getMonthNames(locale, style?)` return the locale-correct list of weekday or month na…
|
||||
- [day-month-names](./src/day-month-names/day-month-names.md) — `getDayNames(locale, style?)` and `getMonthNames(locale, style?)` return the locale-correct list of weekday or month na…
|
||||
- [formatter](./src/formatter/formatter.md) — `DateFormatter` and the `formatDate` / `formatDateRange` standalone helpers expose `Intl.DateTimeFormat` for the `@suav…
|
||||
- [formatter](./src/formatter/formatter.md) — `DateFormatter` and the `formatDate` / `formatDateRange` standalone helpers expose `Intl.DateTimeFormat` for the `@suav…
|
||||
- [helpers](./src/helpers/helpers.md) — `formatTime` and `formatDateOnly` pre-bind `formatDate` with the appropriate preset for time-only or date-only renderin…
|
||||
- [helpers](./src/helpers/helpers.md) — `formatTime` and `formatDateOnly` pre-bind `formatDate` with the appropriate preset for time-only or date-only renderin…
|
||||
- [observability](./src/observability/observability.md) — The Date formatter exports two OpenTelemetry instruments and a small in-memory state ring so spec-conformance tests can…
|
||||
- [observability](./src/observability/observability.md) — The Date formatter exports two OpenTelemetry instruments and a small in-memory state ring so spec-conformance tests can…
|
||||
- [presets](./src/presets/presets.md) — `PRESET_MAP` is the canonical 8-entry table that maps each `DateFormatPreset` discriminant to a concrete `Intl.DateTime…
|
||||
- [presets](./src/presets/presets.md) — `PRESET_MAP` is the canonical 8-entry table that maps each `DateFormatPreset` discriminant to a concrete `Intl.DateTime…
|
||||
<!-- end:auto-docs -->
|
||||
|
||||
## Why this exists
|
||||
|
||||
The 14-package i18n modular split (cross-cutting design
|
||||
`2026-05-05-i18n-modular-split.md`) lifts each `Intl.*` wrapper out
|
||||
of the monolith into its own sibling package. Lifting the date
|
||||
helper out of `@suaveplan/i18n` lets consumers that only need
|
||||
date/time rendering (most UI consumers) pull a single small package
|
||||
instead of the entire i18n core.
|
||||
|
||||
The package adds the canonical Wave-3 formatter shape on top of the
|
||||
monolith's standalone helpers: Zod-validated options, a per-(locale,
|
||||
options-hash) cache, OTel histogram + cache-hit counter, and the
|
||||
`DateFormatter` class wrapper for symmetry with `NumberFormatter` /
|
||||
`RelativeTimeFormatter` / `ListFormatter` / `DisplayNameFormatter`.
|
||||
|
||||
## Install
|
||||
|
||||
```bash
|
||||
bun add @suaveplan/i18n-formatter-date
|
||||
```
|
||||
|
||||
## Quick Start
|
||||
|
||||
```ts
|
||||
import {
|
||||
DateFormatter,
|
||||
formatDate,
|
||||
formatDateOnly,
|
||||
formatDateRange,
|
||||
formatTime,
|
||||
getDayNames,
|
||||
getMonthNames,
|
||||
} from "@suaveplan/i18n-formatter-date";
|
||||
|
||||
const now = new Date(2026, 0, 1, 14, 30, 45);
|
||||
|
||||
formatDate(now, "en-GB", { preset: "short" }); // "01/01/2026, 14:30"
|
||||
formatTime(now, "en-GB", true); // "14:30:45"
|
||||
formatDateOnly(now, "en-GB", true); // "1 January 2026"
|
||||
|
||||
formatDateRange(
|
||||
new Date(2026, 0, 1),
|
||||
new Date(2026, 0, 5),
|
||||
"en-GB",
|
||||
{ day: "numeric", month: "long" }
|
||||
); // "1 – 5 January"
|
||||
|
||||
getDayNames("en-GB", "short");
|
||||
// ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"]
|
||||
|
||||
const f = new DateFormatter({ preset: "long", timeZone: "Europe/London" });
|
||||
f.format(now, "en-GB");
|
||||
```
|
||||
|
||||
## Modules
|
||||
|
||||
| Subpath | Description |
|
||||
|---|---|
|
||||
| `@suaveplan/i18n-formatter-date` | Root barrel — class + standalones + helpers + presets + day/month names |
|
||||
| `@suaveplan/i18n-formatter-date/formatter` | `DateFormatter`, `formatDate`, `formatDateRange`, `toBcp47`, types, schema |
|
||||
| `@suaveplan/i18n-formatter-date/helpers` | `formatTime`, `formatDateOnly` |
|
||||
| `@suaveplan/i18n-formatter-date/presets` | `PRESET_MAP`, `DATE_FORMAT_PRESETS`, `resolvePreset` |
|
||||
| `@suaveplan/i18n-formatter-date/day-month-names` | `getDayNames`, `getMonthNames` |
|
||||
|
||||
## Modules Documentation
|
||||
|
||||
- [formatter.md](src/formatter.md) — `DateFormatter`, `formatDate`, `formatDateRange`, `toBcp47`, `clearDateFormatterCache`
|
||||
- [helpers.md](src/helpers.md) — `formatTime`, `formatDateOnly`
|
||||
- [presets.md](src/presets.md) — 8-preset table + `resolvePreset`
|
||||
- [day-month-names.md](src/day-month-names.md) — `getDayNames`, `getMonthNames`
|
||||
- [observability.md](src/observability.md) — OTel histogram + cache-hit counter
|
||||
|
||||
## Public Surface (snapshot)
|
||||
|
||||
| Export | Kind | Origin |
|
||||
|---|---|---|
|
||||
| `DateFormatter` | class | `formatter.ts` |
|
||||
| `formatDate` | function | `formatter.ts` |
|
||||
| `formatDateRange` | function | `formatter.ts` |
|
||||
| `toBcp47` | function | `formatter.ts` |
|
||||
| `clearDateFormatterCache` | function | `formatter.ts` |
|
||||
| `DateFormatterOptionsSchema` | Zod schema | `formatter.schemas.ts` |
|
||||
| `DateFormatPreset` | type | `formatter.types.ts` |
|
||||
| `DateFormatOptions` | type | `formatter.types.ts` |
|
||||
| `ExtendedDateOptions` | type | `formatter.types.ts` |
|
||||
| `DateFormatterCacheKey` | type | `formatter.types.ts` |
|
||||
| `formatTime` | function | `helpers.ts` |
|
||||
| `formatDateOnly` | function | `helpers.ts` |
|
||||
| `PRESET_MAP` | const | `presets.ts` |
|
||||
| `DATE_FORMAT_PRESETS` | const | `presets.ts` |
|
||||
| `resolvePreset` | function | `presets.ts` |
|
||||
| `PresetTable` | type | `presets.types.ts` |
|
||||
| `getDayNames` | function | `day-month-names.ts` |
|
||||
| `getMonthNames` | function | `day-month-names.ts` |
|
||||
| `recordDateFormat` | function | `observability.ts` |
|
||||
| `recordDateCacheHit` | function | `observability.ts` |
|
||||
| `getDateMetricsState` | function | `observability.ts` |
|
||||
| `resetDateMetricsState` | function | `observability.ts` |
|
||||
|
||||
## Versioning
|
||||
|
||||
Part of the 14-package i18n modular-split rollout. Stays at `0.1.0`
|
||||
until the slim core (Wave 6) cuts the family `1.0.0` release.
|
||||
|
||||
Reference in New Issue
Block a user