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 Duration } from "./duration.js";
import { type ImmutableObject } from "./object.js";
import { type PossibleURI } from "./uri.js";
/** Options we use for number formatting. */
export type NumberOptions = 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?: NumberOptions): string;
/** Format a number range (based on the user's browser language settings). */
export declare function formatRange(from: number, to: number, options?: NumberOptions): string;
/** Options for quantity formatting. */
export interface QuantityOptions extends 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;
    /**
     * 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;
    /**
     * 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;
}
/**
 * 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?: QuantityOptions): string;
/** Options we use for currency formatting. */
export type CurrencyOptions = 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?: CurrencyOptions): string;
/** Options we use for percent formatting. */
export type PercentOptions = Omit<Intl.NumberFormatOptions, "style" | "unit" | "unitDisplay" | "currency" | "currencyDisplay" | "currencySign">;
/**
 * 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%).
 * - 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?: PercentOptions): 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, options?: Intl.DateTimeFormatOptions): string;
/** Format a time in the browser locale (no seconds by default). */
export declare function formatTime(time?: PossibleDate, options?: Intl.DateTimeFormatOptions): string;
/** Format a datetime in the browser locale (no seconds by default). */
export declare function formatDateTime(date: PossibleDate, options?: Intl.DateTimeFormatOptions): string;
/** Format a URL as a user-friendly string, e.g. `http://shax.com/test?uid=129483` → `shax.com/test` */
export declare function formatURI(possible: PossibleURI): 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): string;
/**
 * Compact best-fit when a date happens/happened, e.g. `in 10d` or `2h ago` or `in 1w` or `just now`
 * - See `getBestTimeUnit()` for details on how the best-fit unit is chosen.
 * - But: anything under 30 seconds will show `just now`, which makes more sense in most UIs.
 */
export declare function formatWhen(target: PossibleDate, current?: PossibleDate, options?: Intl.NumberFormatOptions): string;
/** Compact when a date happens, e.g. `10d` or `2h` or `-1w` */
export declare function formatUntil(target: PossibleDate, current?: PossibleDate, options?: Intl.NumberFormatOptions): string;
/** Compact when a date will happen, e.g. `10d` or `2h` or `-1w` */
export declare function formatAgo(target: PossibleDate, current?: PossibleDate, options?: Intl.NumberFormatOptions): string;
/**
 * This roughly corresponds to `Intl.DurationFormatOptions`
 * @todo Use `Intl.DurationFormatOptions` instead it's available in TS lib.
 */
interface DurationFormatOptions {
    style?: "short" | "long" | "narrow";
}
/**
 * Format a duration as a string, e.g. `1 year, 2 months, 3 days` or `1y 2m 3d`
 * @todo Use `Intl.DurationFormat().format()` instead it's more widely supported and is available in TS lib.
 */
export declare function formatDuration(duration: Duration, options?: DurationFormatOptions): string;
export declare function _getDurationStrings(duration: Duration, options?: Intl.NumberFormatOptions): Iterable<string>;
export {};