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.

Documentation tree

formatter — Locale-aware list joining backed by Intl.ListFormat. Joins an array of strings with the locale-correct connector (`"a…
- formatter — Locale-aware list joining backed by Intl.ListFormat. Joins an array of strings with the locale-correct connector (`"a…
helpers — Pre-bound shortcuts over formatList for the two most common list-formatting shapes: conjunction joining ("a, b, and c…
- helpers — Pre-bound shortcuts over formatList for the two most common list-formatting shapes: conjunction joining ("a, b, and c…
observability — Per-package OpenTelemetry instruments for @suaveplan/i18n-formatter-list. Exposes a histogram (`i18n.format.list.dura…
- observability — Per-package OpenTelemetry instruments for @suaveplan/i18n-formatter-list. Exposes a histogram (`i18n.format.list.dura…

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

bun add @suaveplan/i18n-formatter-list

Quick Start

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 — ListFormatter class + formatList
helpers.md — formatConjunction, formatDisjunction
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.