@breadstone/ziegel-intl-units

Comprehensive units of measurement and quantity system for the ziegel framework. Provides strongly-typed quantities, unit conversions, and internationalized formatting for physical measurements.

Units & Measurements: Complete measurement system with type-safe quantities, unit conversion, and culture-aware formatting for scientific and engineering applications.

🚀 Overview

@breadstone/ziegel-intl-units provides:

• Quantity System: Strongly-typed quantities for Length, Mass, Area, Volume, Energy measurements
• Unit Conversion: Seamless conversion between metric, imperial, and custom unit systems
• Internationalized Formatting: Culture-aware display and formatting of measurements
• Type Safety: Full TypeScript support with interfaces and type guards
• Multiple Unit Systems: Support for metric, imperial, and custom measurement systems
• Extensible Architecture: Easy to add new units, quantities, and measurement types

📦 Installation

npm install @breadstone/ziegel-intl-units
# or
yarn add @breadstone/ziegel-intl-units

🧩 Features & Usage Examples

Length Quantities

import { LengthQuantity, LengthUnit, ILengthQuantity } from '@breadstone/ziegel-intl-units';

// Create and convert length measurements
const meters = new LengthQuantity(100, LengthUnit.Meter);
const feet = meters.convertTo(LengthUnit.Foot);
const inches = meters.convertTo(LengthUnit.Inch);

console.log(`${meters.value} m = ${feet.value} ft = ${inches.value} in`);

// Type checking with interfaces
function processLength(length: ILengthQuantity) {
  return length.convertTo(LengthUnit.Centimeter);
}

Mass and Weight

import { MassQuantity, MassUnit, IMassQuantity } from '@breadstone/ziegel-intl-units';

const kilograms = new MassQuantity(75, MassUnit.Kilogram);
const pounds = kilograms.convertTo(MassUnit.Pound);
const stones = kilograms.convertTo(MassUnit.Stone);

console.log(`${kilograms.value} kg = ${pounds.value} lbs = ${stones.value} st`);

// Type guards for validation
import { isMassQuantity } from '@breadstone/ziegel-intl-units';
if (isMassQuantity(someValue)) {
  // TypeScript knows someValue is IMassQuantity
  const grams = someValue.convertTo(MassUnit.Gram);
}

Area Measurements

import { AreaQuantity, AreaUnit, IAreaQuantity } from '@breadstone/ziegel-intl-units';

const squareMeters = new AreaQuantity(100, AreaUnit.SquareMeter);
const squareFeet = squareMeters.convertTo(AreaUnit.SquareFoot);
const acres = squareMeters.convertTo(AreaUnit.Acre);

console.log(`${squareMeters.value} m² = ${squareFeet.value} ft² = ${acres.value} acres`);

Volume and Capacity

import { VolumeQuantity, VolumeUnit, IVolumeQuantity } from '@breadstone/ziegel-intl-units';

const liters = new VolumeQuantity(50, VolumeUnit.Liter);
const gallons = liters.convertTo(VolumeUnit.Gallon);
const cubicFeet = liters.convertTo(VolumeUnit.CubicFoot);

console.log(`${liters.value} L = ${gallons.value} gal = ${cubicFeet.value} ft³`);

Energy Measurements

import { EnergyQuantity, EnergyUnit, IEnergyQuantity } from '@breadstone/ziegel-intl-units';

const joules = new EnergyQuantity(1000, EnergyUnit.Joule);
const calories = joules.convertTo(EnergyUnit.Calorie);
const kilowattHours = joules.convertTo(EnergyUnit.KilowattHour);

console.log(`${joules.value} J = ${calories.value} cal = ${kilowattHours.value} kWh`);

Internationalized Formatting

import {
  LengthQuantityFormat, MassQuantityFormat, AreaQuantityFormat,
  VolumeQuantityFormat, EnergyQuantityFormat
} from '@breadstone/ziegel-intl-units';

// Format quantities with culture-specific formatting
const lengthFormatter = new LengthQuantityFormat('en-US');
const massFormatter = new MassQuantityFormat('de-DE');

const distance = new LengthQuantity(1500, LengthUnit.Meter);
const weight = new MassQuantity(75, MassUnit.Kilogram);

console.log(lengthFormatter.format(distance, 'short')); // "1500 m"
console.log(lengthFormatter.format(distance, 'long'));  // "1500 meters"
console.log(massFormatter.format(weight, 'long'));      // "75 Kilogramm"

Unit System Management

import { UnitSystem } from '@breadstone/ziegel-intl-units';

// Work with different unit systems
console.log(UnitSystem.Metric);   // For metric system
console.log(UnitSystem.Imperial); // For imperial system
console.log(UnitSystem.US);       // For US customary units

// Determine preferred units based on unit system
function getPreferredLengthUnit(system: UnitSystem) {
  switch (system) {
    case UnitSystem.Metric: return LengthUnit.Meter;
    case UnitSystem.Imperial: return LengthUnit.Foot;
    default: return LengthUnit.Meter;
  }
}

📚 Package import points

import {
    // Formatting
    AreaQuantityFormat, EnergyQuantityFormat, LengthQuantityFormat,
    MassQuantityFormat, VolumeQuantityFormat,

    // Quantities (Base & Implementations)
    QuantityBase,
    AreaQuantity, EnergyQuantity, LengthQuantity, MassQuantity, VolumeQuantity,

    // Quantity Interfaces & Type Guards
    IAreaQuantity, isAreaQuantity,
    IEnergyQuantity, isEnergyQuantity,
    ILengthQuantity, isLengthQuantity,
    IMassQuantity, isMassQuantity,
    IQuantity, isQuantity,
    IVolumeQuantity, isVolumeQuantity,

    // Unit Systems & Units
    UnitSystem,
    AreaUnit, EnergyUnit, LengthUnit, MassUnit, VolumeUnit
} from '@breadstone/ziegel-intl-units';

📚 API Documentation

For detailed API documentation, visit: API Docs

Related Packages

• @breadstone/ziegel-core: Foundation utilities and type definitions
• @breadstone/ziegel-intl: Core internationalization support
• @breadstone/ziegel-intl-commerce: Commerce-specific internationalization

License

MIT

Issues

Please report bugs and feature requests in the Issue Tracker

formatWorkoutData(data: WorkoutData, locale: string) { return { distance: this.formatter.formatDistance(data.distance, locale), speed: this.formatter.formatSpeed(data.averageSpeed, locale), calories: this.formatter.formatEnergy(data.caloriesBurned, locale) }; } }

## Best Practices

### Unit Selection

```typescript
// Choose appropriate precision for context
const engineeringPrecision = converter.format(value, unit, locale, {
  precision: 6,
  significantDigits: true
});

const displayPrecision = converter.format(value, unit, locale, {
  precision: 1,
  roundToConvenient: true
});

Performance Optimization

// Cache conversions for repeated operations
const cachedConverter = new CachedUnitConverter({
  maxCacheSize: 1000,
  ttl: 300000 // 5 minutes
});

Accessibility

// Provide screen reader friendly formatting
const accessibleFormat = converter.format(value, unit, locale, {
  accessibility: {
    verboseUnits: true,
    expandAbbreviations: true
  }
});

Migration Guide

From convert-units

// Before (convert-units)
import convert from 'convert-units';

const result = convert(1).from('kg').to('lb');

// After (ziegel-intl-units)
import { UnitConverter } from '@ziegel/intl-units';

const converter = new UnitConverter();
const result = converter.convert(1, 'kilogram', 'pound');

From js-quantities

// Before (js-quantities)
import Qty from 'js-quantities';

const qty = Qty('1 m');
const feet = qty.to('ft');

// After (ziegel-intl-units)
import { UnitConverter } from '@ziegel/intl-units';

const converter = new UnitConverter();
const feet = converter.convert(1, 'meter', 'foot');

API Reference

For complete API documentation, see the API Reference.

Related Packages

• ziegel-intl - Core internationalization
• ziegel-intl-commerce - Commerce-specific internationalization