Number Helper Formatters

(no submodules)

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

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

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 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).

3.1 KiB Raw Blame History