shelving/util/units.d.ts

Toolkit for using data in JavaScript.

import { ImmutableMap, type MapKey } from "./map.js";
import type { ImmutableObject } from "./object.js";
/** Conversion from one unit to another (either an amount to multiple by, or a function to convert). */
type Conversion = number | ((num: number) => number);
/** Set of possible conversions for a set of items. */
type Conversions<T extends string> = {
    readonly [K in T]?: Conversion;
};
type UnitProps<T extends string> = {
    /** Short abbreviation for this unit, e.g. `km` (defaults to first letter of `id`). */
    readonly abbr?: string;
    /** Singular name for this unit, e.g. `kilometer` (defaults to `id` + "s"). */
    readonly singular?: string;
    /** Plural name for this unit, e.g. `kilometers` (defaults to `id`). */
    readonly plural?: string;
    /** Conversions to other units (typically needs at least the base conversion, unless it's already the base unit). */
    readonly to?: Conversions<T>;
    /** Possible options for formatting these units with `Intl.NumberFormat` (`.unit` can be specified if different from key, but is not required). */
    readonly options?: Intl.NumberFormatOptions;
};
/** Represent a unit. */
export declare class Unit<K extends string> {
    private readonly _to;
    /** `UnitList` this unit belongs to. */
    readonly list: UnitList<K>;
    /** String key for this unit, e.g. `kilometer` */
    readonly key: K;
    /** Short abbreviation for this unit, e.g. `km` (defaults to first letter of `id`). */
    readonly abbr: string;
    /** Singular name for this unit, e.g. `kilometer` (defaults to `id`). */
    readonly singular: string;
    /** Plural name for this unit, e.g. `kilometers` (defaults to `singular` + "s"). */
    readonly plural: string;
    /** Possible options for formatting these units with `Intl.NumberFormat` (`.unit` can be specified if different from key, but is not required). */
    readonly options?: Readonly<Intl.NumberFormatOptions>;
    /** Title for this unit (uses format `abbr (plural)`, e.g. `fl oz (US fluid ounces)`) */
    get title(): string;
    constructor(
    /** `UnitList` this unit belongs to. */
    list: UnitList<K>, 
    /** String key for this unit, e.g. `kilometer` */
    key: K, 
    /** Props to configure this unit. */
    { abbr, singular, plural, to }: UnitProps<K>);
    /** Convert an amount from this unit to another unit. */
    to(amount: number, targetKey?: K): number;
    /** Convert an amount from another unit to this unit. */
    from(amount: number, sourceKey?: K): number;
    /** Convert an amount from this unit to another unit (must specify another `Unit` instance). */
    private _convertTo;
    /**
     * Format an amount with a given unit of measure, e.g. `12 kg` or `29.5 l`
     * - Uses `Intl.NumberFormat` if this is a supported unit (so e.g. `ounce` is translated to e.g. `Unze` in German).
     * - Polyfills unsupported units to use long/short form based on `options.unitDisplay`.
     */
    format(amount: number, options?: Intl.NumberFormatOptions): string;
}
/**
 * Represent a list of units.
 * - Has a known base unit at `.base`
 * - Can get required units from `.unit()`
 * - Cannot have additional units added after it is created.
 */
export declare class UnitList<K extends string> extends ImmutableMap<K, Unit<K>> {
    readonly base: Unit<K>;
    constructor(units: ImmutableObject<K, UnitProps<K>>);
    /** Convert an amount from a unit to another unit. */
    convert(amount: number, sourceKey: K, targetKey: K): number;
    /**
     * Require a unit from this list.
     * @throws RequiredError if the unit key is not found.
     */
    require(key: K): Unit<K>;
}
/** Percentage units. */
export declare const PERCENT_UNITS: UnitList<"percent">;
export type PercentUnitKey = MapKey<typeof PERCENT_UNITS>;
/** Point units. */
export declare const POINT_UNITS: UnitList<"basis-point" | "percentage-point">;
export type PointUnitKey = MapKey<typeof POINT_UNITS>;
/** Angle units. */
export declare const ANGLE_UNITS: UnitList<"degree" | "radian" | "gradian">;
export type AngleUnitKey = MapKey<typeof ANGLE_UNITS>;
/** Mass units. */
export declare const MASS_UNITS: UnitList<"milligram" | "gram" | "kilogram" | "ounce" | "pound" | "stone">;
export type MassUnitKey = MapKey<typeof MASS_UNITS>;
/** Time units. */
export declare const TIME_UNITS: UnitList<"millisecond" | "second" | "minute" | "hour" | "day" | "week" | "month" | "year">;
export type TimeUnitKey = MapKey<typeof TIME_UNITS>;
/** Length units. */
export declare const LENGTH_UNITS: UnitList<"millimeter" | "centimeter" | "meter" | "kilometer" | "inch" | "foot" | "yard" | "furlong" | "mile">;
export type LengthUnitKey = MapKey<typeof LENGTH_UNITS>;
/** Speed units. */
export declare const SPEED_UNITS: UnitList<"meter-per-second" | "kilometer-per-hour" | "mile-per-hour">;
export type SpeedUnitKey = MapKey<typeof SPEED_UNITS>;
/** Area units. */
export declare const AREA_UNITS: UnitList<"square-millimeter" | "square-centimeter" | "square-meter" | "square-kilometer" | "hectare" | "square-inch" | "square-foot" | "square-yard" | "acre">;
export type AreaUnitKey = MapKey<typeof AREA_UNITS>;
/** Volume units. */
export declare const VOLUME_UNITS: UnitList<"milliliter" | "liter" | "cubic-centimeter" | "cubic-meter" | "us-fluid-ounce" | "us-pint" | "us-quart" | "us-gallon" | "imperial-fluid-ounce" | "imperial-pint" | "imperial-quart" | "imperial-gallon" | "cubic-inch" | "cubic-foot" | "cubic-yard">;
export type VolumeUnitKey = MapKey<typeof VOLUME_UNITS>;
/** Temperature units. */
export declare const TEMPERATURE_UNITS: UnitList<"celsius" | "fahrenheit" | "kelvin">;
export type TemperatureUnitKey = MapKey<typeof TEMPERATURE_UNITS>;
export {};