shelving/util/format.d.ts

Toolkit for using data in JavaScript.

import { type ImmutableArray } from "./array.js";
import { type PossibleDate } from "./date.js";
import { type ImmutableObject } from "./object.js";
import { type PossibleTime } from "./time.js";
import { type PossibleURL } from "./url.js";
/** Format a number range (based on the user's browser language settings). */
export declare function formatRange(min: number, max: number, options?: Intl.NumberFormatOptions): string;
/** Format a number with a short suffix, e.g. `1,000 kg` */
export declare function formatQuantity(num: number, suffix: string, options?: Intl.NumberFormatOptions): string;
/** Format a number (based on the user's browser language settings). */
export declare function formatNumber(num: number, options?: Intl.NumberFormatOptions): string;
/** Format a number with a longer full-word suffix. */
export declare function pluralizeQuantity(num: number, singular: string, plural: string, options?: Intl.NumberFormatOptions): string;
/**
 * Format a percentage (combines `getPercent()` and `formatQuantity()` for convenience).
 * - Defaults to showing no decimal places.
 * - Defaults to rounding closer to zero (so that 99.99% is shown as 99%).
 *
 * @param numerator Number representing the amount of progress.
 * @param denumerator The number representing the whole amount.
 */
export declare function formatPercent(numerator: number, denumerator: number, options?: Intl.NumberFormatOptions): string;
/**
 * Format an unknown object as a string.
 * - Use the custom `.toString()` function if it exists (don't use built in `Object.prototype.toString` because it's useless.
 * - Use `.title` or `.name` or `.id` if they exist and are strings.
 * - Use `Object` otherwise.
 */
export declare function formatObject(obj: ImmutableObject): string;
/** Format an unknown array as a string. */
export declare function formatArray(arr: ImmutableArray<unknown>, separator?: string): string;
/** Format a date in the browser locale. */
export declare function formatDate(date: PossibleDate): string;
/** Format a time as a string based on the browser locale settings. */
export declare function formatTime(time?: PossibleTime, precision?: 2 | 3 | 4 | 5 | 6): string;
/** Format a URL as a user-friendly string, e.g. `http://shax.com/test?uid=129483` → `shax.com/test` */
export declare function formatURL(possible: PossibleURL, base?: PossibleURL): string;
/**
 * Convert any unknown value into a friendly string for user-facing use.
 * - Strings return the string.
 * - Booleans return `"Yes"` or `"No"`
 * - Numbers return formatted number with commas etc (e.g. `formatNumber()`).
 * - Dates return formatted date (e.g. `formatDate()`).
 * - Arrays return the array items converted to string (with `toTitle()`), and joined with a comma.
 * - Objects return...
 *   1. `object.name` if it exists, or
 *   2. `object.title` if it exists.
 * - Falsy values like `null` and `undefined` return `"None"`
 * - Everything else returns `"Unknown"`
 */
export declare function formatValue(value: unknown): string;