chem-units

A modern, lightweight JavaScript library for converting between different units of measurement commonly used in chemistry and scientific applications.

Features

• 🔋 Zero Dependencies: Lightweight and fast.
• 📦 Dual Bundle: Supports both ESM (.js) and UMD/CommonJS (.cjs).
• 🧪 Science Focused: Includes units for amount of substance, pressure, mass, energy, and more.
• 🏗️ Modern Tooling: Built with Vite and tested with Vitest (100% coverage).

Requirements

• Node.js: >= 21.0.0

Installation

Install using npm:

npm install chem-units

Or using yarn:

yarn add chem-units

Quick Start (ESM)

import { convert } from 'chem-units';

// Convert pressure: 1 atmosphere to Pascal
const pressure = convert('pressure', 1, 'atm', 'pa'); // 101325

// Convert volume: 1 liter to milliliters
const volume = convert('volume', 1, 'l', 'ml'); // 1000

// Convert temperature: 0°C to Fahrenheit
const temp = convert('temperature', 0, 'C', 'F'); // 32

Usage

convert() (universal)

The convert() function is the most explicit and versatile way to handle conversions.

convert(unit_category, value, from_unit, to_unit, precision = 5)

Examples

| Unit Category | Example | | :--- | :--- | | Mass | convert('mass', 1, 'kg', 'g') → 1000 | | Pressure | convert('pressure', 1, 'atm', 'bar') → 1.01325 | | Energy | convert('energy', 1000, 'eV', 'keV') → 1 | | Temperature | convert('temperature', 100, 'C', 'K') → 373.15 |

unitConversion() (simplified)

A simplified version mainly used for sequential unit stepping or when source unit is inferred.

import { unitConversion } from 'chem-units';

// Convert 1 gram to milligrams
const result = unitConversion('mass', 'mg', 1);
console.log(result); // 1000

API Reference

convert(unit_category, value, from, to)

Parameters

• unit_category (string): The unit_category name (e.g., 'amount_substance', 'pressure', 'mass', 'length')
• value (number): The numeric value to be converted
• from (string): The source unit key (e.g., 'mol', 'atm', 'mm')
• to (string): The target unit key (e.g., 'mmol', 'pa', 'cm')

Returns

(number): The converted value

Example

import { convert } from 'chem-units';

convert('amount_substance', 42, 'mol', 'mmol'); // Returns 42000
convert('pressure', 1, 'atm', 'pa'); // Returns 101325
convert('length', 10, 'mm', 'cm'); // Returns 1

unitConversion(unit_category, targetUnit, value)

Parameters

• type (string): The unit type/category
• targetUnit (string): The unit to convert the value to
• value (string | number): The value to be converted

Returns

(number): The converted value

genUnits(unit_category)

Returns a list of available units for a given unit category.

Parameters

• unit_category (string): The unit type/category

Returns

(Array): List of available units for the specified type

Example

import { genUnits } from 'chem-units';

const pressureUnits = genUnits('pressure');
console.log(pressureUnits);
// Returns array of available pressure units

Supported Categories & Units

For a complete list of supported unit keys and categories, please refer to the: 👉 Supported Units for System Defined Field Documentation

Contributing & Support

If you encounter bugs, missing units, or have suggestions:

• Open an issue on GitHub
• Submit a pull request with your proposed changes

Feel free to contact the maintainer Chia-Lin Lin for specific inquiries.

Acknowledgments

Funded by the Deutsche Forschungsgemeinschaft (DFG, German Research Foundation) under the National Research Data Infrastructure – NFDI4Chem – Projektnummer 441958208.