measure-convert/README.md

JS/TS package for managing units of measurement. Convert, add, subtract, multiply, divide, and compare units of measurement.

# 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](#features)
- [Supported Measurement Types](#supported-measurement-types)
- [Installation](#installation)
- [Usage](#usage)
  - [Basic Conversion](#basic-conversion)
  - [Adding and Subtracting Measurements](#adding-and-subtracting-measurements)
  - [Checking Proximity with `closeTo`](#checking-proximity-with-closeto)
- [API Reference](#api-reference)
  - [Measurement Class](#measurement-class)
  - [Unit Classes](#unit-classes)
- [Examples](#examples)
- [Testing](#testing)
- [Contributing](#contributing)
- [License](#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:

```bash
npm install measure-convert
```

Or using Yarn:

```bash
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.

```typescript
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.

```typescript
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.

```typescript
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

```typescript
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`.

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

- **`add(other: Measurement<U>): Measurement<U>`**
  
  Adds another measurement of the same type.

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

- **`subtract(other: Measurement<U>): Measurement<U>`**
  
  Subtracts another measurement of the same type.

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

- **`closeTo(other: Measurement<U>, tolerance: number): boolean`**
  
  Checks if another measurement is within a specified `tolerance`.

  ```typescript
  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`.

  ```typescript
  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

```typescript
import { Unit } from 'measure-convert';

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

## Examples

### Temperature Conversion

```typescript
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

```typescript
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:

```bash
npm install
```

Run the test suite using Jest:

```bash
npm test
```

### Test Coverage

To generate a test coverage report, run:

```bash
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**

   ```bash
   git checkout -b feature/YourFeatureName
   ```

3. **Make Your Changes**
4. **Run Tests**

   Ensure all tests pass:

   ```bash
   npm test
   ```

5. **Commit Your Changes**

   ```bash
   git commit -m "Add feature: YourFeatureName"
   ```

6. **Push to Your Fork**

   ```bash
   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](LICENSE).

---