@secundus-studio/stift-format

Tree-shakable Intl formatting helpers: numbers, currency, dates, lists, and units. No state, no React.

What it is

The optional formatting companion to @secundus-studio/stift-core. Core owns messages (ICU select/plural in translations, locale state, detection); this package adds standalone, locale-aware formatting functions for everything around the message: currency amounts, dates and relative times, list joining, and unit conversion plus rendering. Every function takes { locale } explicitly (pass the active locale to stay in sync), each module is standalone, and the package ships side-effect-free so bundlers drop what you don't import. Currency, unit, calendar, timezone, and numbering-system arguments are narrowed to your registered config sets when the typegen augmentation is present.

pnpm add @secundus-studio/stift-format

Quick start

import { formatCurrency, formatDate, formatList, formatUnit } from '@secundus-studio/stift-format'

formatCurrency(9.99, 'EUR', { locale: 'en' })                    // "€9.99"
formatDate(new Date(), { locale: 'en', dateStyle: 'medium' })    // e.g. "Oct 9, 2026"
formatList(['apples', 'bread', 'cheese'], { locale: 'en' })      // "apples, bread, and cheese"
formatUnit(12000, { locale: 'en', unit: 'kilometer' })           // "12 km"

API

• formatNumber(value, options) — locale-aware number via Intl.NumberFormat.
• formatCurrency(value, currency, options) — currency amount (currency second, style forced to currency).
• formatPercent(value, options) — percent (e.g. 0.42 → "42%").
• pluralCategory(value, locale) — CLDR plural category ("one"/"few"/…) via Intl.PluralRules.
• formatDate(value, options) / formatTime(value, options) / formatDateTime(value, options) — Date | number | string via Intl.DateTimeFormat; options pass through calendar, timezone, and numbering system.
• formatRelativeTime(value, unit, options) — "2 days ago" via Intl.RelativeTimeFormat.
• formatList(list, options) — localized joining ("a, b, and c") via Intl.ListFormat.
• formatUnit(value, options) — localized quantity; value is in the category base unit, target unit rides in options; falls back to a plain number (never throws) when the engine lacks the unit.
• convertUnit(value, from, to) — pure base-aware conversion between named units.
• fromBase(value, unit) / toBase(value, unit) — the two halves of a conversion, for custom pipelines.
• isEngineSupportedUnit(unit) — whether the running engine can format unit (guards formatUnit).
• NumberFormatOptions, DateTimeFormatOptions, ListFormatOptions, UnitNumberFormatOptions — option types (type-only).

Docs

• Formatting reference — https://stift.secundus.studio/docs/latest/vanilla/api/format
• Units (vanilla) — https://stift.secundus.studio/docs/latest/vanilla/units
• Units (React) — https://stift.secundus.studio/docs/latest/react/units
• useFormatter hook (wraps these functions) — https://stift.secundus.studio/docs/latest/react/api/use-formatter