# @suaveplan/i18n-formatter-list - Locale-aware list joining backed by Intl.ListFormat. Class wrapper + standalone helper + ergonomic helpers (formatConjunction, formatDisjunction), Zod-validated options, per-(locale, style, type) cache, OTel histogram + cache-hit counter. Wave 3 of the @suaveplan/i18n modular split.

## Summary

Locale-aware list joining backed by `Intl.ListFormat`. Wave 3 of the
14-package i18n modular split. Provides both a class
(`ListFormatter`) and a standalone helper (`formatList`) plus
ergonomic shortcuts (`formatConjunction`, `formatDisjunction`) on
top of a per-`(locale, style, type)` 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 list joining backed by `Intl.ListFormat`. Joins an array of strings with the locale-correct connector (`"a…
  - [formatter](./src/formatter/formatter.md) — Locale-aware list joining backed by `Intl.ListFormat`. Joins an array of strings with the locale-correct connector (`"a…
- [helpers](./src/helpers/helpers.md) — Pre-bound shortcuts over `formatList` for the two most common list-formatting shapes: conjunction joining ("a, b, and c…
  - [helpers](./src/helpers/helpers.md) — Pre-bound shortcuts over `formatList` for the two most common list-formatting shapes: conjunction joining ("a, b, and c…
- [observability](./src/observability/observability.md) — Per-package OpenTelemetry instruments for `@suaveplan/i18n-formatter-list`. Exposes a histogram (`i18n.format.list.dura…
  - [observability](./src/observability/observability.md) — Per-package OpenTelemetry instruments for `@suaveplan/i18n-formatter-list`. Exposes a histogram (`i18n.format.list.dura…
<!-- 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
list-formatter slice of Wave 3. The monolith ships only a thin
standalone helper and per-cache module — this package brings the
canonical Wave 3 shape on top: class wrapper for symmetry with
`NumberFormatter`, Zod schema validating options at the boundary,
mapping of Zod failure to `INVALID_FORMATTER_OPTIONS`, and OTel
emission for parity with the rest of the family.

## Install

```bash
bun add @suaveplan/i18n-formatter-list
```

## Quick Start

```ts
import {
    formatConjunction,
    formatDisjunction,
    formatList,
    ListFormatter,
} from "@suaveplan/i18n-formatter-list";

formatList(["apples", "oranges", "bananas"], "en-US");
// → "apples, oranges, and bananas"

formatList(["apples", "oranges"], "en-US", { type: "disjunction" });
// → "apples or oranges"

formatConjunction(["a", "b", "c"], "en-GB");  // → "a, b, and c"
formatDisjunction(["x", "y"], "en-GB");       // → "x or y"

const compact = new ListFormatter({ style: "short", type: "unit" });
compact.format(["mon", "tue", "wed"], "en-US"); // → "mon, tue, wed"
```

## Modules

| Subpath | Description |
|---|---|
| `@suaveplan/i18n-formatter-list` | Root barrel — class + standalone + helpers + observability |
| `@suaveplan/i18n-formatter-list/formatter` | `ListFormatter`, `formatList`, `clearListFormatterCache`, types, schema |
| `@suaveplan/i18n-formatter-list/helpers` | `formatConjunction`, `formatDisjunction` only |

## Modules Documentation

- [formatter.md](src/formatter.md) — `ListFormatter` class + `formatList`
- [helpers.md](src/helpers.md) — `formatConjunction`, `formatDisjunction`
- [observability.md](src/observability.md) — OTel histogram + cache-hit counter

## Public Surface (snapshot)

| Export | Kind | Origin |
|---|---|---|
| `ListFormatter` | class | `formatter.ts` |
| `formatList` | function | `formatter.ts` |
| `clearListFormatterCache` | function | `formatter.ts` |
| `ListFormatterOptionsSchema` | const | `formatter.ts` |
| `ListFormatStyle` | type | `formatter.types.ts` |
| `ListFormatType` | type | `formatter.types.ts` |
| `ListFormatterOptions` | type | `formatter.types.ts` |
| `ListFormatterCacheKey` | type | `formatter.types.ts` |
| `formatConjunction` | function | `helpers.ts` |
| `formatDisjunction` | function | `helpers.ts` |
| `recordListFormat` | function | `observability.ts` |
| `recordListCacheHit` | function | `observability.ts` |
| `getListFormatMetricsState` | function | `observability.ts` |
| `resetListFormatMetricsState` | 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/list/` is preserved
in the monolith until Wave 6 deletes it.