Package Exports
- @atomic-ehr/ucum
Readme
@atomic-ehr/ucum
A TypeScript implementation of the Unified Code for Units of Measure (UCUM) with a clean, minimal API.
Features
- ✅ Complete UCUM unit parsing and validation
- ✅ Unit conversion with dimensional analysis
- ✅ Human-readable unit display names
- ✅ Special unit conversions (temperature, logarithmic)
- ✅ TypeScript support with full type safety
- ✅ Zero dependencies runtime
Installation
Stable Release
bun add @atomic-ehr/ucum
# or
npm install @atomic-ehr/ucumCanary Release (Latest Features)
# Install the latest canary version
npm install @atomic-ehr/ucum@canary
# Install a specific canary version
npm install @atomic-ehr/ucum@0.2.3-canary.a7b8c9d.20250713195245⚠️ Warning: Canary releases are published automatically on every commit to main and may be unstable. Use them for testing new features before stable releases.
To see available canary versions:
npm view @atomic-ehr/ucum versions --json | grep canaryQuick Start
import { parse, validate, convert, displayName } from '@atomic-ehr/ucum';
// Parse UCUM expressions
const dose = parse('10 mg');
console.log(dose);
// {
// value: 10,
// code: 'mg',
// unit: 'milligram',
// system: 'http://unitsofmeasure.org',
// ucum: { canonical: { value: 0.01, units: { g: 1 } } }
// }
// Validate units before use
const validation = validate('kg/m2');
console.log(validation); // { valid: true, errors: [] }
// Convert between units
const weight = parse('150 [lb_av]');
const weightKg = convert(weight, 'kg');
console.log(weightKg.value); // 68.04
// Get human-readable names
console.log(displayName('mg/dL')); // 'milligram / deciliter'API Reference
The library exports four simple functions and one type:
parse(expression: string): UCUMQuantity
Parse a UCUM expression into a structured quantity object.
// With value
const glucose = parse('100 mg/dL');
// Without value (defaults to 1)
const velocity = parse('m/s');
// With scientific notation
const small = parse('1.23e-6 mol');validate(expression: string): { valid: boolean; errors: string[] }
Validate a UCUM unit expression without parsing.
const result = validate('kg*m/s2');
if (result.valid) {
// Safe to use the expression
} else {
console.error(result.errors);
}convert(quantity: UCUMQuantity, targetUnit: string): UCUMQuantity
Convert a quantity to a different unit.
const temp = parse('37 Cel');
const tempF = convert(temp, '[degF]');
console.log(tempF.value); // 98.6
// Throws error for incompatible units
const length = parse('10 m');
convert(length, 's'); // Error: Units are incompatibledisplayName(unit: string): string
Get the human-readable name for a unit.
console.log(displayName('ug')); // 'microgram'
console.log(displayName('m2')); // 'meter ^ 2'
console.log(displayName('[pi]')); // 'the number pi'UCUMQuantity Type
interface UCUMQuantity {
value: number;
code: string;
unit?: string;
system?: string;
comparator?: '<' | '<=' | '>=' | '>' | 'ad';
ucum?: {
canonical?: {
value: number;
units: Record<string, number>;
};
annotations?: string[];
dimension?: number[];
};
}Common Use Cases
Laboratory Values
// Glucose conversion (US to SI units)
const glucoseUS = parse('100 mg/dL');
const glucoseSI = convert(glucoseUS, 'mmol/L');
console.log(glucoseSI.value); // 5.55
// Creatinine
const creatinine = parse('1.2 mg/dL');
const creatinineSI = convert(creatinine, 'umol/L');
console.log(creatinineSI.value); // 106.08Medication Dosing
// Weight-based dosing calculation
const dosagePerKg = parse('5 mg/kg');
const patientWeight = parse('70 kg');
const totalDose = dosagePerKg.value * patientWeight.value; // 350 mg
// Infusion rate
const volume = parse('250 mL');
const time = parse('30 min');
const rate = volume.value / (time.value / 60); // mL/hEngineering Units
// Pressure conversion
const pressure = parse('14.7 [psi]');
const pressurePa = convert(pressure, 'Pa');
console.log(pressurePa.value); // 101325
// Energy conversion
const energy = parse('1 kW.h');
const energyJ = convert(energy, 'J');
console.log(energyJ.value); // 3600000Supported Units
The library supports hundreds of UCUM units including:
- SI base units (m, kg, s, A, K, mol, cd)
- Derived units (N, Pa, J, W, C, V, F, Ω, etc.)
- Clinical units (mg/dL, mmol/L, mL/min, etc.)
- Customary units ([lb_av], [in_i], [ft_i], etc.)
- Special units with conversions (Cel, [degF], [pH], etc.)
Documentation
- API Usage Guide - Detailed examples and patterns
- Architecture Overview - System design and components
- UCUM Specification - Official standard
Development
# Install dependencies
bun install
# Run tests
bun test
# Type check
bun run typecheckLicense
MIT