# Number Helper Formatters

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs -->

## Purpose

Pre-bound shortcuts over `formatNumber` and `Intl.NumberFormat` for the three most-asked number-formatting shapes: percentages, compact notation ("1.2K"), and units of measurement ("12 km/h"). Saves callers from spelling out the full options bag every time.

The percent and compact helpers route through `formatNumber`, so they benefit from its Zod validation and per-(locale, options-hash) cache. `formatUnit` calls `Intl.NumberFormat` directly because `style: 'unit'` is intentionally outside the narrow `NumberFormatterStyle` union.

## Features

- `formatPercent(value, locale, options?)` — `style: 'percent'` shortcut
- `formatCompact(value, locale, options?)` — `notation: 'compact'` shortcut ("1.2K", "1.2M")
- `formatUnit(value, unit, locale, options?)` — `style: 'unit'` shortcut for measurement units
- `unit` is any `Intl.NumberFormat` unit identifier (`'kilometer-per-hour'`, `'celsius'`, `'megabyte'`, ...)
- `formatUnit` style is `'short' | 'long' | 'narrow'` (default `'short'`)

## Usage: Basic Example

```typescript
import {
  formatCompact,
  formatPercent,
  formatUnit,
} from "@suaveplan/i18n-formatter-number/helpers";

formatPercent(0.255, "en-US", { maximumFractionDigits: 1 }); // → "25.5%"
formatCompact(1234, "en-US");                                // → "1.2K"
formatUnit(12, "kilometer-per-hour", "en-US");               // → "12 km/h"
formatUnit(20, "celsius", "en-US", { style: "long" });       // → "20 degrees Celsius"
```

## Usage: Advanced Example — Stat Block

```typescript
import {
  formatCompact,
  formatPercent,
  formatUnit,
} from "@suaveplan/i18n-formatter-number/helpers";

const stats = {
  cpuLoad: formatPercent(load, locale),
  memUsed: formatUnit(memBytes, "megabyte", locale, { style: "long" }),
  reqsPerMinute: formatCompact(reqs, locale),
};
```

## API Reference

### `formatPercent(value, locale, options?)`

Pre-bound `formatNumber({ style: 'percent', ...options })`. Note that `value` is the proportion (0.25 → "25%"), not the percentage (25).

### `formatCompact(value, locale, options?)`

Pre-bound `formatNumber({ notation: 'compact', ...options })`. Defaults to `compactDisplay: 'short'` from `Intl.NumberFormat`. Override via `options.compactDisplay`.

### `formatUnit(value, unit, locale, options?)`

Locale-aware unit formatting. The `unit` is one of `Intl.NumberFormat`'s sanctioned units; the [Intl.NumberFormat units list](https://tc39.es/ecma402/#table-sanctioned-single-unit-identifiers) is authoritative. Composite units use `-per-` joiner (`'meter-per-second'`).

## Implementation Notes

`formatUnit` does NOT route through `formatNumber` because adding `style: 'unit'` would require widening `NumberFormatterStyle` and `NumberFormatterOptions` to include the unit-specific options. Keeping `formatUnit` as a thin direct wrapper preserves the `formatNumber` surface's stability.

Compact notation uses the runtime's locale-specific compact patterns. For en-US that's `'1.2K'`, `'1.2M'`, `'1.2B'`; other locales use locale-correct abbreviations (e.g. `'1,2 万'` for ja-JP).