Unit Conversion Library

A robust and comprehensive TypeScript library for handling a wide array of measurement units and performing precise unit conversions. Whether you're working on scientific computations, engineering applications, or everyday unit conversions, this library provides the tools you need with accuracy and ease.

Table of Contents

• Features
• Supported Measurement Types
• Installation
• Usage
  • Basic Conversion
  • Adding and Subtracting Measurements
  • Checking Proximity with closeTo
• API Reference
  • Measurement Class
  • Unit Classes
• Examples
• Testing
• Contributing
• License

Features

• Wide Range of Units: Supports over 20 different measurement types, including Temperature, Speed, Length, Mass, Volume, and more.
• Accurate Conversions: Utilizes precise conversion factors to ensure minimal rounding errors.
• Extensible Design: Easily add new units and measurement types as needed.
• Comprehensive Testing: Ensures reliability with thorough unit tests covering all functionalities.
• TypeScript Support: Leverages TypeScript for type safety and enhanced developer experience.

Supported Measurement Types

Your library currently supports the following measurement types:

• Acceleration (UnitAcceleration)
• Angle (UnitAngle)
• Area (UnitArea)
• Concentration (Mass) (UnitConcentrationMass)
• Dispersion (UnitDispersion)
• Duration (UnitDuration)
• Electric Charge (UnitElectricCharge)
• Electric Current (UnitElectricCurrent)
• Electric Potential Difference (UnitElectricPotentialDifference)
• Electric Resistance (UnitElectricResistance)
• Energy (UnitEnergy)
• Frequency (UnitFrequency)
• Fuel Efficiency (UnitFuelEfficiency)
• Illuminance (UnitIlluminance)
• Information Storage (UnitInformationStorage)
• Length (UnitLength)
• Mass (UnitMass)
• Power (UnitPower)
• Pressure (UnitPressure)
• Speed (UnitSpeed)
• Temperature (UnitTemperature)
• Volume (UnitVolume)

Each measurement type comes with its own set of units, enabling precise and context-specific conversions.

Installation

Install the library via npm:

npm install measure-convert

Or using Yarn:

yarn add measure-convert

Usage

Basic Conversion

To perform a basic unit conversion, create a Measurement instance with a value and its corresponding unit, then convert it to the desired unit.

import { Measurement } from 'measure-convert';
import { UnitTemperature } from 'measure-convert';

// Convert 100°C to Fahrenheit
const tempCelsius = new Measurement(100, UnitTemperature.celsius);
const tempFahrenheit = tempCelsius.converted(UnitTemperature.fahrenheit);
console.log(`${tempCelsius.value}°C is equal to ${tempFahrenheit.value}°F`);

Output:

100°C is equal to 212°F

Adding and Subtracting Measurements

You can add or subtract two measurements, provided they are of the same measurement type.

import { Measurement } from 'measure-convert';
import { UnitSpeed } from 'measure-convert';

// Add 60 mph to 100 km/h
const speed1 = new Measurement(100, UnitSpeed.kilometersPerHour);
const speed2 = new Measurement(60, UnitSpeed.milesPerHour);
const totalSpeed = speed1.add(speed2.converted(UnitSpeed.kilometersPerHour));
console.log(`Total Speed: ${totalSpeed.value} km/h`);

Output:

Total Speed: 196.56064 km/h

Checking Proximity with closeTo

Determine if two measurements are within a specified tolerance of each other.

import { Measurement } from 'measure-convert';
import { UnitLength } from 'measure-convert';

// Check if 100 meters is close to 328.084 feet within 0.1 meters tolerance
const length1 = new Measurement(100, UnitLength.meters);
const length2 = new Measurement(328.084, UnitLength.feet);
const isClose = length1.closeTo(length2, 0.1);
console.log(`Are the lengths close? ${isClose}`);

Output:

Are the lengths close? true

API Reference

Measurement Class

The Measurement class represents a value with an associated unit and provides methods for conversion and comparison.

Constructor

constructor(value: number, unit: Unit)

• value: The numerical value of the measurement.
• unit: The unit of the measurement.

Methods

• converted(targetUnit: V): Measurement<V>

  Converts the current measurement to the targetUnit.

  converted<V extends Unit>(targetUnit: V): Measurement<V>

• add(other: Measurement<U>): Measurement<U>

  Adds another measurement of the same type.

  add(other: Measurement<U>): Measurement<U>

• subtract(other: Measurement<U>): Measurement<U>

  Subtracts another measurement of the same type.

  subtract(other: Measurement<U>): Measurement<U>

• closeTo(other: Measurement<U>, tolerance: number): boolean

  Checks if another measurement is within a specified tolerance.

  closeTo(other: Measurement<U>, tolerance: number): boolean

• Static closeTo(measurement1: Measurement<U>, measurement2: Measurement<U>, tolerance: number): boolean

  Static method to check if two measurements are within a specified tolerance.

  static closeTo<U extends Unit>(measurement1: Measurement<U>, measurement2: Measurement<U>, tolerance: number): boolean

Unit Classes

Each measurement type has its own Unit class, encapsulating the specific units and their conversion factors. Below are brief descriptions of each supported Unit class.

• UnitAcceleration
• UnitAngle
• UnitArea
• UnitConcentrationMass
• UnitDispersion
• UnitDuration
• UnitElectricCharge
• UnitElectricCurrent
• UnitElectricPotentialDifference
• UnitElectricResistance
• UnitEnergy
• UnitFrequency
• UnitFuelEfficiency
• UnitIlluminance
• UnitInformationStorage
• UnitLength
• UnitMass
• UnitPower
• UnitPressure
• UnitSpeed
• UnitTemperature
• UnitVolume

Each Unit class provides predefined units relevant to its measurement type. For example, UnitTemperature includes Celsius, Fahrenheit, and Kelvin.

Example: UnitTemperature

import { Unit } from 'measure-convert';

// Access predefined temperature units
const celsius = UnitTemperature.celsius;
const fahrenheit = UnitTemperature.fahrenheit;
const kelvin = UnitTemperature.kelvin;

Examples

Temperature Conversion

import { Measurement } from 'measure-convert';
import { UnitTemperature } from 'measure-convert';

// Convert 100°C to Fahrenheit
const tempCelsius = new Measurement(100, UnitTemperature.celsius);
const tempFahrenheit = tempCelsius.converted(UnitTemperature.fahrenheit);
console.log(`${tempCelsius.value}°C is equal to ${tempFahrenheit.value}°F`);

// Output: 100°C is equal to 212°F

Speed Conversion and Comparison

import { Measurement } from 'measure-convert';
import { UnitSpeed } from 'measure-convert';

// Create speed measurements
const speedKmH = new Measurement(100, UnitSpeed.kilometersPerHour);
const speedMph = new Measurement(60, UnitSpeed.milesPerHour);

// Convert mph to km/h
const convertedMph = speedMph.converted(UnitSpeed.kilometersPerHour);
console.log(`${speedMph.value} mph is equal to ${convertedMph.value} km/h`);

// Output: 60 mph is equal to 96.56064 km/h

// Add speeds
const totalSpeed = speedKmH.add(convertedMph);
console.log(`Total Speed: ${totalSpeed.value} km/h`);

// Output: Total Speed: 196.56064 km/h

// Check if speeds are close within 1 km/h tolerance
const isClose = speedKmH.closeTo(convertedMph, 1);
console.log(`Are the speeds close? ${isClose}`);

// Output: Are the speeds close? false

Testing

The library includes a comprehensive test suite to ensure all functionalities work as expected. Tests cover unit conversions, arithmetic operations, comparison methods, and error handling.

Running Tests

Ensure you have all dependencies installed:

npm install

Run the test suite using Jest:

npm test

Test Coverage

To generate a test coverage report, run:

npm test -- --coverage

This command will display coverage statistics and generate a detailed report, ensuring that all parts of your codebase are adequately tested.

Contributing

Contributions are welcome! Whether it's fixing bugs, improving documentation, or adding new features, your help is appreciated.

How to Contribute

1. Fork the Repository

2. Create a New Branch

   git checkout -b feature/YourFeatureName

3. Make Your Changes

4. Run Tests

   Ensure all tests pass:

   npm test

5. Commit Your Changes

   git commit -m "Add feature: YourFeatureName"

6. Push to Your Fork

   git push origin feature/YourFeatureName

7. Create a Pull Request

   Submit your changes for review.

Guidelines

• Follow the existing coding style and conventions.
• Ensure all tests pass before submitting.
• Provide clear and concise commit messages.
• Update documentation as necessary.

License

This project is licensed under the Apache License 2.0.