unitfyi

unitfyi

Pure TypeScript unit conversion engine for developers. Convert between 200 units across 20 measurement categories including length, weight, temperature, volume, area, speed, time, data storage, pressure, energy, frequency, force, power, angle, fuel economy, data transfer, density, torque, cooking, and typography -- all with zero dependencies.

Try the interactive tools at unitfyi.com -- unit converter, conversion tables, and category explorer.

Table of Contents

• Install
• Quick Start
• What You Can Do
  • Precision in Unit Conversion
  • Temperature Conversion
  • Conversion Tables
  • Unit Lookup
• API Reference
• TypeScript Types
• Features
• Learn More About Units
• Also Available for Python
• Utility FYI Family
• License

Install

npm install unitfyi

Works in Node.js, Deno, Bun, and browsers (ESM).

Quick Start

import { convert, conversionTable, getCategoryUnits, getOrderedCategories } from "unitfyi";

// Convert between any compatible units
const temp = convert(100, "celsius", "fahrenheit");
console.log(temp.result);        // 212
console.log(temp.formulaText);   // "°F = (°C × 9/5) + 32"

const length = convert(1, "mile", "kilometer");
console.log(length.result);      // 1.6093
console.log(length.fromSymbol);  // "mi"
console.log(length.toSymbol);    // "km"

// Generate a conversion table
const table = conversionTable("kilogram", "pound");
// [[1, 2.2046], [5, 11.0231], [10, 22.0462], ...]

// Browse categories and units
const categories = getOrderedCategories();
console.log(categories.length);  // 20

const lengthUnits = getCategoryUnits("length");
console.log(lengthUnits.length); // 20 (meter, km, cm, mm, ...)

What You Can Do

Precision in Unit Conversion

JavaScript uses IEEE 754 double-precision floats. For most unit conversions this is sufficient, but temperature and very large/small values use smart rounding to avoid floating-point artifacts like 99.99999999996.

The engine applies magnitude-aware rounding:

Magnitude	Precision	Example
>= 1,000	2 decimal places	5,280.00
>= 1	4 decimal places	1.6093
>= 0.01	6 decimal places	0.453592
< 0.01	10 decimal places	0.0000000001

Temperature conversions use function-based formulas (not linear factors) to maintain exact results: °F = (°C * 9/5) + 32, K = °C + 273.15, etc.

The engine covers 20 measurement categories with a total of 200 units:

Category	Units	Examples
Length	20	meter, kilometer, mile, foot, inch, yard, nautical mile, ...
Weight	15	kilogram, pound, ounce, gram, stone, metric ton, ...
Temperature	4	Celsius, Fahrenheit, Kelvin, Rankine
Volume	15	liter, gallon (US/UK), cup, tablespoon, fluid ounce, ...
Area	10	square meter, acre, hectare, square foot, ...
Speed	8	km/h, mph, m/s, knot, Mach, speed of light, ...
Data Storage	16	byte, KB, MB, GB, TB, PB, KiB, MiB, GiB, ...
Pressure	8	pascal, bar, atm, psi, mmHg, torr, ...
Energy	10	joule, calorie, kWh, BTU, eV, ...
Cooking	8	cup, tablespoon, teaspoon, fluid ounce, ...

Learn more: Unit Converter · SI Base Units · Category Explorer

Temperature Conversion

import { convert } from "unitfyi";

// All temperature conversions use exact formulas (not linear approximation)
const c2f = convert(0, "celsius", "fahrenheit");
console.log(c2f.result);        // 32
console.log(c2f.formulaText);   // "°F = (°C × 9/5) + 32"

const f2c = convert(72, "fahrenheit", "celsius");
console.log(f2c.result);        // 22.2222

const c2k = convert(-40, "celsius", "kelvin");
console.log(c2k.result);        // 233.15

// Rankine scale also supported
const f2r = convert(100, "fahrenheit", "rankine");
console.log(f2r.result);        // 559.67

Learn more: Temperature Converter · Absolute Zero

Conversion Tables

import { conversionTable } from "unitfyi";

// Default values: [1, 5, 10, 25, 50, 100, 250, 500, 1000]
const table = conversionTable("meter", "foot");
for (const [meters, feet] of table) {
  console.log(`${meters} m = ${feet} ft`);
}

// Custom values
const custom = conversionTable("celsius", "fahrenheit", [0, 20, 37, 100]);
// [[0, 32], [20, 68], [37, 98.6], [100, 212]]

Learn more: Conversion Tables · REST API Docs

Unit Lookup

import { getUnit, getCategoryUnits, getOrderedCategories } from "unitfyi";

// Look up a single unit
const meter = getUnit("meter");
console.log(meter?.name);         // "Meter"
console.log(meter?.symbol);       // "m"
console.log(meter?.category);     // "length"
console.log(meter?.aliases);      // ["metre", "meters", "metres"]

// List all units in a category
const tempUnits = getCategoryUnits("temperature");
// [{ slug: "celsius", name: "Celsius", symbol: "°C", ... }, ...]

// Get all 20 categories sorted by display order
const cats = getOrderedCategories();
for (const cat of cats) {
  console.log(`${cat.icon} ${cat.name}: ${cat.description}`);
}

Learn more: All Units · OpenAPI Spec

API Reference

Conversion

Function	Description
convert(value, fromSlug, toSlug) -> ConversionResult	Convert a value between two compatible units
conversionTable(fromSlug, toSlug, values?) -> [number, number][]	Generate a conversion table for a unit pair

Unit Lookup

Function	Description
getUnit(slug) -> UnitInfo | null	Look up a unit by slug
getCategoryUnits(categorySlug) -> UnitInfo[]	Get all units in a category
getOrderedCategories() -> CategoryDef[]	Get all 20 categories sorted by display order

Error Classes

Class	Description
UnknownUnitError	Thrown when a unit slug is not found
IncompatibleUnitsError	Thrown when converting between different categories

Data Exports

Export	Description
UNITS	Record of all 200 unit definitions
CATEGORIES	Record of all 20 category definitions
FORMULAS	Non-linear conversion formulas (temperature)

TypeScript Types

import type {
  UnitDef,
  CategoryDef,
  ConversionResult,
  UnitInfo,
  TemperatureFormula,
} from "unitfyi";

Features

• 200 units: Across 20 measurement categories
• 20 categories: Length, weight, temperature, volume, area, speed, time, data storage, pressure, energy, frequency, force, power, angle, fuel economy, data transfer, density, torque, cooking, typography
• Temperature formulas: Exact function-based conversion (Celsius, Fahrenheit, Kelvin, Rankine)
• Smart rounding: Magnitude-aware precision to avoid floating-point artifacts
• Conversion tables: Generate value tables for any unit pair
• Human-readable formulas: Each conversion includes a formula string (e.g., "1 mi = 1.6093 km")
• Unit aliases: Search-friendly aliases (e.g., "metre", "meters", "metres" all find Meter)
• Zero dependencies: Pure TypeScript, no runtime deps
• Type-safe: Full TypeScript with strict mode
• Tree-shakeable: ESM with named exports
• Fast: All computations under 1ms

Learn More About Units

• Tools: Unit Converter · Conversion Tables
• Browse: Categories · All Units
• API: REST API Docs · OpenAPI Spec
• Python: PyPI Package

Also Available for Python

pip install unitfyi

See the Python package on PyPI.

Utility FYI Family

Part of the FYIPedia open-source developer tools ecosystem — everyday developer reference and conversion tools.

Package	PyPI	npm	Description
unitfyi	PyPI	npm	Unit conversion, 220 units -- unitfyi.com
timefyi	PyPI	npm	Timezone ops & business hours -- timefyi.com
holidayfyi	PyPI	npm	Holiday dates & Easter calculation -- holidayfyi.com
namefyi	PyPI	npm	Korean romanization & Five Elements -- namefyi.com
distancefyi	PyPI	npm	Haversine distance & travel times -- distancefyi.com

Embed Widget

Embed UnitFYI widgets on any website with unitfyi-embed:

<script src="https://cdn.jsdelivr.net/npm/unitfyi-embed@1/dist/embed.min.js"></script>
<div data-unitfyi="entity" data-slug="example"></div>

Zero dependencies · Shadow DOM · 4 themes (light/dark/sepia/auto) · Widget docs

License

MIT