react-native-nitro-measurements

Type-safe unit conversion and dimensional analysis for React Native, powered by NitroModules.

Features

• Compile-time category safety — TypeScript overloads prevent cross-category conversions (miles to celsius is a TS error, not a runtime crash)
• 22 unit categories, 203 units — length, mass, duration, speed, temperature, area, volume, energy, power, frequency, angle, pressure, acceleration, concentration mass, dispersion, electric charge, electric current, electric potential difference, electric resistance, fuel efficiency, illuminance, information storage
• SI dimensional analysis — speed * time = distance with full dimension tracking
• Zero JS bundle cost — all conversion logic runs in native code (Swift Foundation)
• Synchronous JSI — no bridge serialization, no async overhead
• Autocomplete — as const satisfies objects provide full IDE support (Length. shows all 22 length units, InformationStorage. shows all 35 storage units)

Installation

npm install react-native-nitro-measurements react-native-nitro-modules

Then rebuild your native app:

cd ios && pod install && cd ..
npx expo run:ios   # or npx react-native run-ios

Note: iOS only for v1. Android support is planned for a future release.

Quick Start

import { convert, Length, Temperature } from 'react-native-nitro-measurements'

// Convert 5 miles to kilometers
const km = convert(5, Length.miles, Length.kilometers) // ~8.047

// String literals also work
const fahrenheit = convert(100, 'celsius', 'fahrenheit') // 212

// Cross-category conversion is a compile-time error:
// convert(42, Length.miles, Temperature.celsius)
//                          ^^^^^^^^^^^^^^^^^^^ TS2345

API Reference

convert(value, from, to)

Converts a numeric value between two units in the same category. Returns a number.

convert(5, Length.miles, Length.kilometers) // 8.04672
convert(100, 'celsius', 'fahrenheit')      // 212

convertFull(value, from, to)

Like convert(), but returns a MeasurementResult with metadata.

convertFull(5, Length.miles, Length.kilometers)
// { value: 8.04672, unit: 'kilometers', category: 'length', symbol: 'km' }

add(valueA, unitA, valueB, unitB, resultUnit)

Adds two measurements in the same category, returning the result in resultUnit.

add(1, 'kilometers', 500, 'meters', 'meters') // 1500

subtract(valueA, unitA, valueB, unitB, resultUnit)

Subtracts two measurements in the same category, returning the result in resultUnit.

subtract(1, Length.miles, 1, Length.kilometers, Length.meters) // ~609.344

multiply(valueA, unitA, valueB, unitB)

Cross-category multiplication with SI dimensional analysis. Returns a DimensionalResult.

multiply(60, Speed.kilometersPerHour, 2, Duration.hours)
// { value: 33333.33, dimensions: [1,0,0,0,0,0,0], dimensionLabel: 'L' }

divide(valueA, unitA, valueB, unitB)

Cross-category division with SI dimensional analysis. Returns a DimensionalResult.

divide(100, Length.kilometers, 2, Duration.hours)
// { value: 50000, dimensions: [1,0,-1,0,0,0,0], dimensionLabel: 'L/T' }

resolveDimension(value, dimensions, targetUnit)

Resolves a dimensional analysis result back to a named unit. Returns MeasurementResult | undefined (undefined if dimensions don't match the target unit's category).

resolveDimension(120000, [1, 0, 0, 0, 0, 0, 0], Length.kilometers)
// { value: 120, unit: 'kilometers', category: 'length', symbol: 'km' }

resolveDimension(120000, [1, 0, 0, 0, 0, 0, 0], Temperature.celsius)
// undefined (dimension mismatch)

getSymbol(unit)

Returns the localized symbol for a unit.

getSymbol(Length.nauticalMiles) // 'NM'
getSymbol('kilograms')         // 'kg'

getUnitsForCategory(category)

Returns all unit identifiers for a category, sorted alphabetically.

getUnitsForCategory('length')
// ['centimeters', 'feet', 'inches', 'kilometers', 'meters', 'miles', ...]

getCategories()

Returns all available unit categories.

getCategories()
// ['angle', 'area', 'duration', 'energy', 'frequency', 'length', ...]

measurement(value, unit) — Fluent Builder

A chainable API for conversions, arithmetic, and dimensional analysis.

import { measurement, Length, Speed, Duration } from 'react-native-nitro-measurements'

// Simple conversion
measurement(5, Length.miles).to(Length.miles)

// Full result with metadata
measurement(5, Length.miles).toFull(Length.miles)

// Arithmetic
measurement(1, Length.kilometers).add(500, Length.meters)

// Cross-category dimensional analysis
measurement(60, Speed.kilometersPerHour).times(2, Duration.hours)
measurement(100, Length.kilometers).dividedBy(2, Duration.hours)

// Get unit symbol
measurement(5, Length.miles).symbol() // 'mi'

Type Safety

TypeScript function overloads enforce that from and to units belong to the same category at compile time:

// These compile:
convert(5, Length.miles, Length.kilometers)
convert(100, Temperature.celsius, Temperature.fahrenheit)

// These are compile-time errors:
convert(42, Length.miles, Temperature.celsius)     // TS2345
convert(1, 'miles', 'celsius')                     // TS2345
add(1, Length.miles, 1, Mass.kilograms, Length.meters) // TS2345

The as const satisfies objects (Length, Mass, Speed, etc.) provide full autocomplete in your IDE while preserving the string literal types needed for overload resolution.

Unit Categories

| Category | # | Units | |---|---|---| | Length | 22 | meters, kilometers, centimeters, millimeters, miles, yards, feet, inches, nauticalMiles, micrometers, nanometers, picometers, megameters, hectometers, decameters, decimeters, scandinavianMiles, lightyears, fathoms, furlongs, astronomicalUnits, parsecs | | Mass | 16 | kilograms, grams, milligrams, pounds, ounces, stones, metricTons, decigrams, centigrams, micrograms, nanograms, picograms, shortTons, carats, ouncesTroy, slugs | | Duration | 7 | seconds, minutes, hours, milliseconds, microseconds, nanoseconds, picoseconds | | Speed | 4 | metersPerSecond, kilometersPerHour, milesPerHour, knots | | Temperature | 3 | celsius, fahrenheit, kelvin | | Area | 14 | squareMeters, squareKilometers, squareMiles, squareFeet, hectares, acres, squareMegameters, squareCentimeters, squareMillimeters, squareMicrometers, squareNanometers, squareInches, squareYards, ares | | Volume | 31 | liters, milliliters, gallons, cups, fluidOunces, cubicMeters, megaliters, kiloliters, deciliters, centiliters, cubicKilometers, cubicDecimeters, cubicCentimeters, cubicMillimeters, cubicInches, cubicFeet, cubicYards, cubicMiles, acreFeet, bushels, teaspoons, tablespoons, pints, quarts, imperialTeaspoons, imperialTablespoons, imperialFluidOunces, imperialPints, imperialQuarts, imperialGallons, metricCups | | Energy | 5 | joules, calories, kilocalories, kilowattHours, kilojoules | | Power | 11 | watts, kilowatts, horsepower, terawatts, gigawatts, megawatts, milliwatts, microwatts, nanowatts, picowatts, femtowatts | | Frequency | 8 | hertz, kilohertz, megahertz, gigahertz, terahertz, millihertz, microhertz, nanohertz | | Angle | 6 | degrees, radians, arcMinutes, arcSeconds, gradians, revolutions | | Pressure | 11 | newtonsPerMetersSquared, bars, millibars, atmospheres, poundsPerSquareInch, gigapascals, megapascals, kilopascals, hectopascals, inchesOfMercury, millimetersOfMercury | | Acceleration | 2 | metersPerSecondSquared, gravity | | ConcentrationMass | 2 | gramsPerLiter, milligramsPerDeciliter | | Dispersion | 1 | partsPerMillion | | ElectricCharge | 6 | coulombs, megaampereHours, kiloampereHours, ampereHours, milliampereHours, microampereHours | | ElectricCurrent | 5 | megaamperes, kiloamperes, amperes, milliamperes, microamperes | | ElectricPotentialDifference | 5 | megavolts, kilovolts, volts, millivolts, microvolts | | ElectricResistance | 5 | megaohms, kiloohms, ohms, milliohms, microohms | | FuelEfficiency | 3 | litersPer100Kilometers, milesPerImperialGallon, milesPerGallon | | Illuminance | 1 | lux | | InformationStorage | 35 | bytes, bits, nibbles, yottabytes, zettabytes, exabytes, petabytes, terabytes, gigabytes, megabytes, kilobytes, yottabits, zettabits, exabits, petabits, terabits, gigabits, megabits, kilobits, yobibytes, zebibytes, exbibytes, pebibytes, tebibytes, gibibytes, mebibytes, kibibytes, yobibits, zebibits, exbibits, pebibits, tebibits, gibibits, mebibits, kibibits |

Benchmark

Sub-microsecond JSI-native conversions with type safety and dimensional analysis — comparable to lightweight JS math, 6–34x faster than convert-units.

| Benchmark | nitro | convert-units | convert | Raw Math | |---|---|---|---|---| | 4 in → mm | 0.7 µs | 4.3 µs | 0.7 µs | 0.3 µs | | 100°C → °F | 0.7 µs | 24.0 µs | 0.8 µs | 0.3 µs | | km→mi × 1000 | 0.56 ms | 4.79 ms | 0.62 ms | 0.20 ms | | 1 km + 500 m | 1.0 µs | — | — | 0.4 µs |

Environment: iPhone 16 Pro simulator, React Native 0.81, 5000 iterations with 50 warm-up. nitro = this library, convert-units = convert-units, convert = convert, Raw Math = inline JS arithmetic.

Full results across iteration counts in benchmark/.

License

MIT