shelving/util/formatmodule

A collection of helpers for converting typed values into user-readable strings. All formatters respect the browser's locale by default and accept an optional locale override — they delegate to the Intl APIs where possible so internationalisation and translation are handled automatically.

Things to know:

  • formatPercent() takes a 0–100 numerator (not 0–1 like the raw Intl API), defaults to zero decimal places, and rounds toward zero so "99.99%" shows as "99%".
  • formatUnit() falls back gracefully when the browser does not support a given unit in Intl.NumberFormat.
  • formatValue() is the catch-all: null/undefined → "None", booleans → "Yes"/"No", arrays → locale list, objects → name/title/id property.
  • formatURI() strips the scheme and query string — mailto:[email protected] → [email protected].

Usage

Numbers, ranges, and currencies

ts
import { formatNumber, formatRange, formatCurrency, formatPercent } from "shelving/util";

formatNumber(1234567.89);             // "1,234,567.89"  (locale-dependent)
formatRange(10, 20);                   // "10–20"
formatCurrency(9.99, "GBP");          // "£9.99"
formatPercent(33.3);                   // "33%"
formatPercent(33.3, 100, { maximumFractionDigits: 1 }); // "33.3%"

Units

ts
import { formatUnit } from "shelving/util";

formatUnit(5, "kilometer");                   // "5 km"  (browser-supported unit)
formatUnit(12, "widget", { unitDisplay: "long", one: "widget", many: "widgets" });
// "12 widgets"

Dates and times

ts
import { formatDate, formatTime, formatDateTime } from "shelving/util";

formatDate(new Date("2024-06-01"));           // "6/1/2024"  (locale-dependent)
formatTime(new Date("2024-06-01T14:30:00"));  // "02:30 PM"
formatDateTime(new Date("2024-06-01T14:30:00")); // "6/1/2024, 02:30 PM"

Booleans and generic values

ts
import { formatBoolean, formatValue } from "shelving/util";

formatBoolean(true);   // "Yes"
formatBoolean(false);  // "No"

formatValue(null);           // "None"
formatValue(42);             // "42"
formatValue([1, 2, 3]);      // "1, 2, and 3"
formatValue({ name: "Alice" }); // "Alice"

Arrays and objects

ts
import { formatArray, formatObject } from "shelving/util";

formatArray(["apples", "oranges", "pears"]);          // "apples, oranges, and pears"
formatArray(["apples", "oranges"], { type: "disjunction" }); // "apples or oranges"
formatObject({ name: "Widget" });  // "Widget"

URLs and URIs

ts
import { formatURI, formatURL } from "shelving/util";

formatURI("mailto:[email protected]");              // "[email protected]"
formatURL("https://example.com/page?ref=123");  // "example.com/page"

Functions

Go

formatBoolean()function

Format a boolean as "Yes" or "No".

formatBoolean(value: boolean): string
Go

formatNumber()function

Format a number (based on the user's browser language settings).

formatNumber(num: number, options?: NumberFormatOptions): string
Go

formatRange()function

Format a number range (based on the user's browser language settings).

formatRange(from: number, to: number, options?: NumberFormatOptions): string
Go

formatUnit()function

Format a quantity of a given unit.

formatUnit(num: number, unit: string, options?: UnitFormatOptions): string
Go

formatCurrency()function

Format a currency amount (based on the user's browser language settings).

formatCurrency(amount: number, currency: string, options?: CurrencyFormatOptions, caller: AnyCaller = formatCurrency): string
Go

formatPercent()function

Format a percentage (combines getPercent() and formatUnit() for convenience).

formatPercent(numerator: number, denumerator?: number, options?: PercentFormatOptions): string
Go

formatObject()function

Format an unknown object as a string.

formatObject(obj: ImmutableObject): string
Go

formatArray()function

Format an unknown array as a string.

formatArray(arr: ImmutableArray<unknown>, options?: ArrayFormatOptions, caller: AnyCaller = formatArray): string
Go

formatDate()function

Format a date in the browser locale.

formatDate(date: PossibleDate, options?: DateFormatOptions, caller: AnyCaller = formatDate): string
Go

formatTime()function

Format a time in the browser locale (no seconds by default).

formatTime(time?: PossibleDate, options?: DateFormatOptions, caller: AnyCaller = formatTime): string
Go

formatDateTime()function

Format a datetime in the browser locale (no seconds by default).

formatDateTime(date: PossibleDate, options?: DateFormatOptions, caller: AnyCaller = formatDateTime): string
Go

formatURI()function

Format a URI as a user-friendly string.

formatURI(url: PossibleURI, caller: AnyCaller = formatURI): string
Go

formatURL()function

Format a URL as a user-friendly string.

formatURL(url: PossibleURL, base?: PossibleURL, caller: AnyCaller = formatURL): string
Go

formatValue()function

Convert any unknown value into a friendly string for user-facing use.

formatValue(value: unknown, options?: FormatOptions, caller: AnyCaller = formatValue): string
Go

formatValues()function

Format a sequence of values.

formatValues(values: Iterable<unknown>, options?: FormatOptions, caller: AnyCaller = formatValues): Iterable<string>

Interfaces

Go

FormatOptionsinterface

Options that are shared across all formatters.

{
	readonly locale?: Intl.Locale | undefined;
}
Go

UnitFormatOptionsinterface

Options for quantity formatting.

{
	readonly one?: string | undefined;
	readonly many?: string | undefined;
	readonly abbr?: string | undefined;
}
Go

ArrayFormatOptionsinterface

Options for formatting an array as a string with formatArray().

{}
Go

DateFormatOptionsinterface

Options we use for date, time, and datetime formatting.

{
	readonly locale?: Intl.Locale | undefined;
}