\r\n 🌡️ Type-safe unit conversions for HVAC, building automation, and thermodynamics\r\n
\r\n\r\n\r\n Installation •\r\n Quick Start •\r\n Why? •\r\n API •\r\n Units\r\n
\r\n\r\n---\r\n\r\n## Why Metric Units?\r\n\r\n**Stop writing error-prone unit conversion code.** If you've ever:\r\n\r\n- 🐛 Spent hours debugging because someone mixed up °C and °F\r\n- 🔄 Written the same temperature conversion formula for the 10th time\r\n- 😤 Dealt with magic numbers like `1.8`, `32`, or `273.15` scattered across your codebase\r\n- 🤔 Wondered \"wait, is this value in Pascals or kPa?\"\r\n\r\n**This library is for you.**\r\n\r\n### ✨ What Makes It Different\r\n\r\n| Feature | Metric Units | DIY Approach |\r\n|---------|--------------|--------------|\r\n| **Type Safety** | Full TypeScript enums prevent invalid units at compile time | Runtime errors waiting to happen |\r\n| **Validation** | Built-in checks for NaN, Infinity, and physically impossible values | Silent failures |\r\n| **Tree-Shakeable** | Import only what you need, bundle only what you use | — |\r\n| **Zero Dependencies** | Lightweight, no bloat | — |\r\n| **Battle-Tested** | 148 unit tests covering edge cases | Hope for the best |\r\n| **Display Labels** | Get proper unit symbols (°C, m³/s, kPa) for UI rendering | Hardcode strings everywhere |\r\n\r\n### 🎯 Perfect For\r\n\r\n- **HVAC Systems** — Temperature, pressure, airflow, humidity\r\n- **Building Automation** — Sensor data normalization \r\n- **IoT Dashboards** — Display values in user-preferred units\r\n- **Engineering Tools** — Scientific calculations with confidence\r\n- **Data Pipelines** — Convert between metric and imperial systems\r\n\r\n---\r\n\r\n## Installation\r\n\r\n```bash\r\nnpm install metric-units\r\n```\r\n\r\n```bash\r\nyarn add metric-units\r\n```\r\n\r\n```bash\r\npnpm add metric-units\r\n```\r\n\r\n---\r\n\r\n## Quick Start\r\n\r\n```typescript\r\nimport {\r\n temperatureToUnit,\r\n temperatureFromUnit,\r\n TemperatureUnit,\r\n getTemperatureUnitLabel,\r\n} from 'metric-units';\r\n\r\n// Convert 25°C to Fahrenheit\r\nconst fahrenheit = temperatureToUnit(TemperatureUnit.Fahrenheit, 25);\r\n// → 77\r\n\r\n// Convert 77°F back to Celsius\r\nconst celsius = temperatureFromUnit(TemperatureUnit.Fahrenheit, 77);\r\n// → 25\r\n\r\n// Get display label for UI\r\nconst label = getTemperatureUnitLabel(TemperatureUnit.Celsius);\r\n// → '°C'\r\n```\r\n\r\n### Real-World Example: HVAC Dashboard\r\n\r\n```typescript\r\nimport {\r\n temperatureToUnit,\r\n TemperatureUnit,\r\n getTemperatureUnitLabel,\r\n airPressureToUnit,\r\n PressureUnit,\r\n getPressureUnitLabel,\r\n flowRateToUnit,\r\n FlowRateUnit,\r\n getFlowRateUnitLabel,\r\n} from 'metric-units';\r\n\r\n// Sensor data comes in SI units\r\nconst sensorData = {\r\n supplyAirTemp: 12.5, // °C\r\n staticPressure: 250, // Pa\r\n airflow: 0.47, // m³/s\r\n};\r\n\r\n// User prefers imperial units\r\nconst userUnits = {\r\n temperature: TemperatureUnit.Fahrenheit,\r\n pressure: PressureUnit.inH2O,\r\n flowRate: FlowRateUnit.CubicFeetPerMinute,\r\n};\r\n\r\n// Convert for display\r\nconst display = {\r\n temperature: `${temperatureToUnit(userUnits.temperature, sensorData.supplyAirTemp).toFixed(1)} ${getTemperatureUnitLabel(userUnits.temperature)}`,\r\n pressure: `${airPressureToUnit(userUnits.pressure, sensorData.staticPressure).toFixed(2)} ${getPressureUnitLabel(userUnits.pressure)}`,\r\n airflow: `${flowRateToUnit(userUnits.flowRate, sensorData.airflow).toFixed(0)} ${getFlowRateUnitLabel(userUnits.flowRate)}`,\r\n};\r\n\r\n// → { temperature: '54.5 °F', pressure: '1.00 inH₂O', airflow: '996 CFM' }\r\n```\r\n\r\n---\r\n\r\n## API Reference\r\n\r\nEvery unit category follows the same consistent pattern:\r\n\r\n```typescript\r\n// Convert FROM base unit TO target unit\r\nvalueInTargetUnit = xxxToUnit(TargetUnit, valueInBaseUnit);\r\n\r\n// Convert FROM target unit TO base unit \r\nvalueInBaseUnit = xxxFromUnit(SourceUnit, valueInSourceUnit);\r\n\r\n// Get display label\r\nlabel = getXxxUnitLabel(unit);\r\n```\r\n\r\n### Functions by Category\r\n\r\n| Category | To Unit | From Unit | Get Label |\r\n|----------|---------|-----------|-----------|\r\n| Temperature | `temperatureToUnit()` | `temperatureFromUnit()` | `getTemperatureUnitLabel()` |\r\n| Pressure | `airPressureToUnit()` | `airPressureFromUnit()` | `getPressureUnitLabel()` |\r\n| Height | `heightToUnit()` | `heightFromUnit()` | `getHeightUnitLabel()` |\r\n| Enthalpy | `enthalpyToUnit()` | `enthalpyFromUnit()` | `getEnthalpyUnitLabel()` |\r\n| Specific Humidity | `specificHumidityToUnit()` | `specificHumidityFromUnit()` | `getSpecificHumidityUnitLabel()` |\r\n| Flow Rate | `flowRateToUnit()` | `flowRateFromUnit()` | `getFlowRateUnitLabel()` |\r\n| Power | `powerToUnit()` | `powerFromUnit()` | `getPowerUnitLabel()` |\r\n| Velocity | `velocityToUnit()` | `velocityFromUnit()` | `getVelocityUnitLabel()` |\r\n\r\n### Input Validation\r\n\r\nAll conversion functions validate input and throw descriptive errors:\r\n\r\n```typescript\r\ntemperatureToUnit(TemperatureUnit.Kelvin, NaN);\r\n// → TypeError: temperature must be a finite number, got NaN\r\n\r\ntemperatureToUnit(TemperatureUnit.Kelvin, -300);\r\n// → Error: Temperature cannot be below absolute zero (-273.15°C)\r\n\r\nairPressureToUnit(PressureUnit.Pascal, -100);\r\n// → Error: Pressure cannot be negative\r\n```\r\n\r\n---\r\n\r\n## Available Units\r\n\r\n| Category | Base Unit | Units |\r\n|----------|-----------|-------|\r\n| **Temperature** | Celsius (°C) | `Celsius` · `Fahrenheit` · `Kelvin` |\r\n| **Pressure** | Pascal (Pa) | `Pascal` · `KiloPascal` · `Bar` · `Psia` · `mmH2O` · `inH2O` · `ftH2O` · `mmHg` · `inHg` · `ftHg` |\r\n| **Height** | Meters (m) | `Meters` · `Feet` |\r\n| **Enthalpy** | kJ/kg | `KiloJoulesPerKilogram` · `BritishThermalUnitPerPound` |\r\n| **Specific Humidity** | g/kg | `GramsPerKilogram` · `KilogramsPerKilogram` · `PoundsPerPound` |\r\n| **Flow Rate** | m³/s | `CubicMetersPerSecond` · `CubicMetersPerHour` · `CubicFeetPerMinute` (CFM) · `LitersPerSecond` · `LitersPerMinute` · `GallonsPerMinute` (GPM) |\r\n| **Power** | Watt (W) | `Watt` · `Kilowatt` · `BtuPerHour` · `Horsepower` · `TonOfRefrigeration` |\r\n| **Velocity** | m/s | `MetersPerSecond` · `FeetPerMinute` · `FeetPerSecond` · `KilometersPerHour` · `MilesPerHour` |\r\n\r\n---\r\n\r\n## Breaking Changes\r\n\r\n### v2.0.0\r\n\r\n#### Namespace Pattern Removed\r\n\r\nThe `Unit.getLabel()` namespace pattern has been replaced with standalone functions for better tree-shaking and idiomatic TypeScript:\r\n\r\n**Before (v1.x):**\r\n\r\n```typescript\r\nimport TemperatureUnit from 'metric-units/TemperatureUnit';\r\n\r\nconst label = TemperatureUnit.getLabel(TemperatureUnit.Celsius);\r\n```\r\n\r\n**After (v2.0):**\r\n\r\n```typescript\r\nimport { TemperatureUnit, getTemperatureUnitLabel } from 'metric-units';\r\n\r\nconst label = getTemperatureUnitLabel(TemperatureUnit.Celsius);\r\n```\r\n\r\n#### File Names Normalized\r\n\r\nAll file names now use kebab-case consistently:\r\n\r\n| Old Import Path | New Import Path |\r\n| ---------------------------------- | ------------------------------------- |\r\n| `metric-units/TemperatureUnit` | `metric-units/temperature-unit` |\r\n| `metric-units/PressureUnit` | `metric-units/pressure-unit` |\r\n| `metric-units/HeightUnit` | `metric-units/height-unit` |\r\n| `metric-units/EnthalpyUnit` | `metric-units/enthalpy-unit` |\r\n| `metric-units/SpecificHumidityUnit`| `metric-units/specific-humidity-unit` |\r\n| `metric-units/enumUtils` | `metric-units/enum-utils` |\r\n\r\n#### Migration Guide\r\n\r\n1. Update imports to use named exports instead of default exports\r\n2. Replace `Unit.getLabel(value)` calls with `getUnitLabel(value)` function calls\r\n3. Update any direct file imports to use kebab-case paths\r\n\r\n---\r\n\r\n## Contributing\r\n\r\nContributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.\r\n\r\n```bash\r\n# Clone the repository\r\ngit clone https://github.com/AEPi-Zeta/MetricUnits-TypeScript.git\r\n\r\n# Install dependencies\r\nyarn install\r\n\r\n# Run tests\r\nyarn test\r\n\r\n# Build\r\nyarn build\r\n```\r\n\r\n---\r\n\r\n## License\r\n\r\nGNU Affero General Public License v3.0 (AGPL-3.0)\r\n\r\n---\r\n\r\n\r\n Made with ❤️ for the HVAC and building automation community\r\n
\r\n","readmeFilename":"README.md"}