chem-units

A JavaScript library for converting between different units of measurement commonly used in chemistry.

Table of Contents

• Features
• Requirements
• Installation
• Quick Start
• Usage
  • Universal Convert Function (Recommended)
  • Legacy unitConversion Function
• API Reference
  • convert()
  • unitConversion()
  • genUnits()
• Supported Units
• Contributing
• License
• Maintainer

Features

• ✅ Convert between common chemistry and scientific units
• ✅ Support for multiple unit categories (mass, volume, pressure, temperature, etc.)
• ✅ Simple and intuitive API
• ✅ Lightweight and dependency-free

Requirements

• Node.js: >=20.0.0 <25.0.0

Installation

Install using npm:

npm install chem-units

Or using yarn:

yarn add chem-units

Quick Start

import { convert } from 'chem-units';

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

// Convert 42 moles to millimoles
const amount = convert('amount_substance', 42, 'mol', 'mmol');
console.log(amount); // 42000

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

Usage

Universal Convert Function

The convert() function provides a simple and explicit way to convert between units. You specify the unit category, value, source unit, and target unit.

ℹ️ Note: The unit category refers to the field type (e.g., 'amount_substance', 'pressure', 'mass'). See Supported Units for the complete list of supported units and categories.

Examples

Amount of Substance:

import { convert } from 'chem-units';

// Convert moles to millimoles
const result = convert('amount_substance', 42, 'mol', 'mmol');
console.log(result); // 42000

Pressure Conversions:

// Convert atmospheres to Pascals
const result = convert('pressure', 1, 'atm', 'pa');
console.log(result); // 101325

Length Conversions:

// Convert millimeters to centimeters
const result = convert('length', 10, 'mm', 'cm');
console.log(result); // 1

Mass Conversions:

// Convert grams to milligrams
const result = convert('mass', 1, 'g', 'mg');
console.log(result); // 1000

Temperature Conversions:

// Convert Celsius to Fahrenheit
const result1 = convert('temperature', 0, 'C', 'F');
console.log(result1); // 32

// Convert Celsius to Kelvin
const result2 = convert('temperature', 100, 'C', 'K');
console.log(result2); // 373.15

unitConversion Function (simplified)

The unitConversion() is a simplified version of the general conversion function, requiring only the unit category, the value to be converted, and the target unit.

import { unitConversion } from 'chem-units';

const type = 'temperature';
const targetUnit = 'F';
const value = '32';

const result = unitConversion(type, targetUnit, value);
console.log(result); // 89.6

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 Units

For a complete list of supported units and categories, see the Supported Units for System Defined Field documentation.

Contributing

chem-units provides commonly used units of measurement in chemistry. If you don't find a suitable unit for your application, please feel free to:

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

We welcome contributions to expand the library's capabilities!

Maintainer

This project is maintained by:

• Chia-Lin Lin

Feel free to reach out if you have any questions or suggestions!