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 { AnyCaller } from "./function.js";
import { type ImmutableObject } from "./object.js";
import { type PossibleURI } from "./uri.js";
import { type PossibleURL } from "./url.js";
/** Options that are shared across all formatters. */
export interface FormatOptions {
    /** Override the locale for formatting (defaults to detected locale). */
    readonly locale?: Intl.Locale | undefined;
}
/** Format a boolean as "Yes" or "No". */
export declare function formatBoolean(value: boolean): string;
/** Options we use for number formatting. */
export interface NumberFormatOptions extends FormatOptions, Omit<Intl.NumberFormatOptions, "style" | "unit" | "unitDisplay" | "currency" | "currencyDisplay" | "currencySign"> {
}
/** Format a number (based on the user's browser language settings). */
export declare function formatNumber(num: number, options?: NumberFormatOptions): string;
/** Format a number range (based on the user's browser language settings). */
export declare function formatRange(from: number, to: number, options?: NumberFormatOptions): string;
/** Options for quantity formatting. */
export interface UnitFormatOptions extends FormatOptions, Omit<Intl.NumberFormatOptions, "style" | "unit" | "currency" | "currencyDisplay" | "currencySign"> {
    /**
     * String for one of this thing, e.g. `product` or `item` or `sheep`
     * - Used for `unitDisplay: "long"` formatting.
     * - Defaults to unit reference, e.g. "minute"
     */
    readonly one?: string | undefined;
    /**
     * String for several of this thing, e.g. `products` or `items` or `sheep`
     * - Used for `unitDisplay: "long"` formatting.
     * - Defaults to `one + "s"`
     */
    readonly many?: string | undefined;
    /**
     * Abbreviation for this thing, e.g. `products` or `items` or `sheep` (defaults to `one` + "s").
     * - Used for `unitDisplay: "narrow"` formatting.
     * - Defaults to unit reference, e.g. "minute"
     */
    readonly abbr?: string | undefined;
}
/**
 * Format a quantity of a given unit.
 *
 * - Javascript has built-in support for formatting a number of different units.
 * - Unfortunately the list of supported units changes in different browsers.
 * - Ideally we want to format units using the built-in formatting so things like translation and internationalisation are covered.
 * - But we want provide fallback formatting for unsupported units, and do something _good enough_ job in most cases.
 */
export declare function formatUnit(num: number, unit: string, options?: UnitFormatOptions): string;
/** Options we use for currency formatting. */
export interface CurrencyFormatOptions extends FormatOptions, Omit<Intl.NumberFormatOptions, "style" | "unit" | "unitDisplay" | "currency"> {
}
/** Format a currency amount (based on the user's browser language settings). */
export declare function formatCurrency(amount: number, currency: string, options?: CurrencyFormatOptions, caller?: AnyCaller): string;
/** Options we use for percent formatting. */
export interface PercentFormatOptions extends FormatOptions, Omit<Intl.NumberFormatOptions, "style" | "unit" | "unitDisplay" | "currency" | "currencyDisplay" | "currencySign"> {
}
/**
 * Format a percentage (combines `getPercent()` and `formatUnit()` for convenience).
 * - Defaults to showing no decimal places.
 * - Defaults to rounding closer to zero (so that 99.99% is shown as 99%).
 * - Javascript's built-in percent formatting works on the `0` zero to `1` range. This uses `getPercent()` which works on `0` to `100` for convenience.
 *
 * @param numerator Number representing the amount of progress (e.g. `50`).
 * @param denumerator The number representing the whole amount (defaults to 100).
 */
export declare function formatPercent(numerator: number, denumerator?: number, options?: PercentFormatOptions): 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;
export interface ArrayFormatOptions extends FormatOptions, Intl.ListFormatOptions {
}
/** Format an unknown array as a string. */
export declare function formatArray(arr: ImmutableArray<unknown>, options?: ArrayFormatOptions, caller?: AnyCaller): string;
/** Options we use for currency formatting. */
export interface DateFormatOptions extends Intl.DateTimeFormatOptions {
    /** Override the locale for formatting (defaults to detected locale). */
    readonly locale?: Intl.Locale | undefined;
}
/** Format a date in the browser locale. */
export declare function formatDate(date: PossibleDate, options?: DateFormatOptions, caller?: AnyCaller): string;
/** Format a time in the browser locale (no seconds by default). */
export declare function formatTime(time?: PossibleDate, options?: DateFormatOptions, caller?: AnyCaller): string;
/** Format a datetime in the browser locale (no seconds by default). */
export declare function formatDateTime(date: PossibleDate, options?: DateFormatOptions, caller?: AnyCaller): string;
/**
 * Format a URI as a user-friendly string
 * e.g. `mailto:dave@shax.com` → `dave@shax.com`
 * e.g. `http://shax.com/test?uid=129483` → `shax.com/test`
 */
export declare function formatURI(url: PossibleURI, caller?: AnyCaller): string;
/**
 * Format a URI as a string.
 * e.g. `http://shax.com/test?uid=129483` → `shax.com/test`
 */
export declare function formatURL(url: PossibleURL, base?: PossibleURL, caller?: AnyCaller): 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 datetime (e.g. `formatDateTime()`).
 * - 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, options?: FormatOptions, caller?: AnyCaller): string;
/** Format a sequence of values. */
export declare function formatValues(values: Iterable<unknown>, options?: FormatOptions, caller?: AnyCaller): Iterable<string>;