uconvert

Lightweight utility for converting common measurement units.

Table of contents

• Installation
• Usage
  • convert(value, options)
  • round(value, decimalPlaces?)
• Exported types and enums
• Supported units
  • Length
  • Weight
  • Speed
  • Temperature
• Height utility
  • height.toFeetInches(valueInCm, roundTo?)
  • height.toCentimeters(feetInches)
  • height.parseFeetInches(input)
  • FeetInches type

Installation

npm install uconvert

Usage

convert(value, options)

Converts a numeric value from one unit to another.

Parameters:

• value (number) — The value in the source unit.
• options (object):
  • fromUnits — Source unit (use MetricUnits or ImperialUnits).
  • toUnits — Target unit. Must be the same dimension as fromUnits (e.g. length ↔ length), or an error is thrown.
  • roundTo (optional) — Number of decimal places to round the result. Omit to return the unrounded value.

Returns: The value in the target unit (optionally rounded).

Example:

import { convert, MetricUnits, ImperialUnits } from "uconvert";

// 5 feet to meters, rounded to 2 decimals
convert(5, {
  fromUnits: ImperialUnits.FT,
  toUnits: MetricUnits.M,
  roundTo: 2,
});
// => 1.52

// Same unit: returns value unchanged
convert(100, { fromUnits: MetricUnits.CM, toUnits: MetricUnits.CM });
// => 100

round(value, decimalPlaces?)

Rounds a number to a given number of decimal places.

Parameters:

• value (number) — The number to round.
• decimalPlaces (optional) — Number of digits after the decimal point. Omit to return the value unchanged.

Returns: The rounded number (or the original number if decimalPlaces is omitted).

Example:

import { round } from "uconvert";

round(1.2345, 2); // => 1.23
round(1.2345); // => 1.2345

Exported types and enums

Use these with convert for type-safe unit arguments:

| Export | Description | | ---------------- | ------------------------------------------------------------------------------------ | | ConvertOptions | Options object for convert: { fromUnits, toUnits, roundTo? }. | | Units | Union type: MetricUnits \| ImperialUnits. | | MetricUnits | Enum: MM, CM, M, KM, G, KG, TONNE, CELSIUS, KELVIN, M_S, KM_H. | | ImperialUnits | Enum: IN, FT, YD, MI, OZ, LB, ST, FAHRENHEIT, FT_S, MPH. | | UnitSystem | Enum: METRIC, IMPERIAL. | | Dimension | Enum: LENGTH, WEIGHT, SPEED, TEMPERATURE. |

fromUnits and toUnits must use the same dimension (e.g. both length, or both weight); otherwise convert throws.

Supported units

Units are grouped by dimension. Use the Code value with convert().

Length

| Unit | Code | System | | ---- | ------------------ | -------- | | mm | MetricUnits.MM | Metric | | cm | MetricUnits.CM | Metric | | m | MetricUnits.M | Metric | | km | MetricUnits.KM | Metric | | in | ImperialUnits.IN | Imperial | | ft | ImperialUnits.FT | Imperial | | yd | ImperialUnits.YD | Imperial | | mi | ImperialUnits.MI | Imperial |

Weight

| Unit | Code | System | | ---- | ------------------- | -------- | | g | MetricUnits.G | Metric | | kg | MetricUnits.KG | Metric | | t | MetricUnits.TONNE | Metric | | oz | ImperialUnits.OZ | Imperial | | lb | ImperialUnits.LB | Imperial | | st | ImperialUnits.ST | Imperial |

Speed

| Unit | Code | System | | ---- | -------------------- | -------- | | m/s | MetricUnits.M_S | Metric | | km/h | MetricUnits.KM_H | Metric | | ft/s | ImperialUnits.FT_S | Imperial | | mph | ImperialUnits.MPH | Imperial |

Temperature

| Unit | Code | System | | ------ | -------------------------- | -------- | | °C (C) | MetricUnits.CELSIUS | Metric | | K | MetricUnits.KELVIN | Metric | | °F (F) | ImperialUnits.FAHRENHEIT | Imperial |

Height utility

The height object provides helpers for converting between centimeters and feet–inches and for parsing feet–inches strings.

Import:

import { height } from "uconvert";

height.toFeetInches(valueInCm, roundTo?)

Converts a height in centimeters to feet and inches.

Parameters:

• valueInCm (number) — Height in centimeters.
• roundTo (optional) — Number of decimal places for the inches part. Omit for unrounded.

Returns: A FeetInches tuple [feet, inches].

Example:

height.toFeetInches(170); // => [5, 6.93...]
height.toFeetInches(170, 1); // => [5, 6.9]

height.toCentimeters(feetInches)

Converts a feet–inches tuple to centimeters.

Parameters:

• feetInches — A FeetInches tuple [feet, inches] (e.g. from toFeetInches or parseFeetInches).

Returns: Height in centimeters (number).

Example:

height.toCentimeters([5, 10]); // => 177.8

height.parseFeetInches(input)

Parses a string into a [feet, inches] tuple. Accepts formats like "5 ft 10 in", "5'10\"", "5 10", and variations with "feet"/"foot"/"inches"/"inch".

Parameters:

• input (string) — String to parse.

Returns: A FeetInches tuple [feet, inches]. Returns [0, 0] if parsing fails or input is not a string.

Example:

height.parseFeetInches("5 ft 10 in"); // => [5, 10]
height.parseFeetInches("5'10\""); // => [5, 10]
height.parseFeetInches("6 2"); // => [6, 2]

FeetInches type

Tuple type [number, number]: first element is feet, second is inches. Use it when passing or receiving values from toFeetInches, toCentimeters, and parseFeetInches.

import { height, type FeetInches } from "uconvert";

const fi: FeetInches = height.toFeetInches(170);
height.toCentimeters(fi);