lighthouse-unit-converter

A fast native C++ unit converter for Node.js with support for multiple unit categories.

Installation

npm install lighthouse-unit-converter

No build tools required! The package includes a pure JavaScript fallback that works everywhere. For better performance, the native C++ addon will be used if build tools are available.

Optional: Enable Native Performance

For ~10x faster conversions, install build tools:

Windows:

• Install Visual Studio Build Tools: https://visualstudio.microsoft.com/downloads/
• Select "Desktop development with C++" workload

macOS:

xcode-select --install

Linux:

sudo apt-get install build-essential python3

Then reinstall: npm install lighthouse-unit-converter

Features

• Fast native C++ implementation
• Support for multiple categories: length, mass, temperature, time, and volume
• Zero dependencies (except build tools)
• Type-safe conversions

Usage

const converter = require('lighthouse-unit-converter');

// Convert units
console.log(converter.convert(10, "m", "ft"));  // 32.8084 (meters to feet)
console.log(converter.convert(100, "celsius", "fahrenheit"));  // 212
console.log(converter.convert(5, "mi", "km"));  // 8.04672

// Get available categories
console.log(converter.getCategories());  // ['length', 'mass', 'temperature', 'time', 'volume', 'angle', 'pace', 'speed']

// Get units for a specific category
console.log(converter.getUnits("length"));  // ['mm', 'cm', 'm', 'km', 'in', 'ft', 'yd', 'mi', 'nmi']
console.log(converter.getUnits("angle"));   // ['rad', 'deg', 'grad', 'arcmin', 'arcsec']

Supported Units

Length

• mm, cm, m, km, in, ft, yd, mi, nmi

Mass

• mg, g, kg, lb, oz, ton, tonne

Temperature

• celsius, kelvin, fahrenheit

Time

• ms, s, min, hr, day, week

Volume

• ml, l, gal, qt, pt, cup, floz

Angle

• rad (radian), deg (degree), grad (gradian), arcmin (arcminute), arcsec (arcsecond)

Pace

• min/km (minute per kilometer), s/m (second per meter), min/mi (minute per mile), s/ft (second per foot)

Speed

• m/s (meter per second), km/h (kilometer per hour), mph (mile per hour), knot, ft/s (foot per second)

API

convert(value, fromUnit, toUnit)

Convert a value from one unit to another.

Parameters:

• value (number): The value to convert
• fromUnit (string): The source unit
• toUnit (string): The target unit

Returns: number - The converted value

getCategories()

Get all available unit categories.

Returns: string[] - Array of category names

getUnits(category)

Get all units for a specific category.

Parameters:

• category (string): The category name

Returns: string[] - Array of unit names

Building from Source

npm install
npm run install

Adding New Units

All unit definitions are stored in units.json. To add new units:

1. Edit units.json to add your unit with its conversion factor
2. Run npm run generate to regenerate the C++ and JavaScript files
3. Test: npm test

Example adding a new unit:

{
  "length": {
    "base": "meter",
    "units": {
      "furlong": 201.168  // Add new unit here
    }
  }
}

Requirements

• Node.js >= 16.0.0
• Python 3.x (for node-gyp)
• C++ compiler with C++17 support

License

ISC