unit-system

ΜΕΤΡΩ ΧΡΩ

Use the measure

A library for defining unit systems and performing unit-safe calculations

Demo

const { createUnitSystem, conversion } = require('unit-system');

const { createUnit, m, equal, add } = createUnitSystem();

const inch = createUnit('inch');
const yard = createUnit('yard', {
  alias: ['yd', 'yard', 'yards'],
});

const foot = createUnit('foot', {
  alias: 'feet',
  convert: {
    to: [yard, conversion.divideBy(3)],
    from: [inch, conversion.divideBy(12)],
  },
});

const twoYards = add(m`1 yard`, m`3 feet`);

equal(twoYards, m(72, inch)) === true;

Documentation

createUnitSystem(units)

Most uses of unit-system start with createUnitSystem().

const { createUnitSystem } = require('unit-system');

const { createUnit, m, convert, system } = createUnitSystem();

createUnit(name, options)

Creates a new Unit and automatically registers it with system (the UnitSystem created by createUnitSystem).

const inch = createUnit('inch', { alias: 'inches' });

const foot = createUnit('foot', {
  convert: {
    from: [inch, conversion.divideBy(12)],
  },
});

m(number, unit)

Shorthand function for creating new Measurement instances. If a unit is defined with an alias, that alias can be used instead of passing in the unit. (see UnitSystem#measure() for details)

m`12 inches`;

convert(measurement, unit)

Given a Measurement and a Unit, convert(measurement, unit) will attempt to convert that measurement to the given unit. (see UnitSystem#convert() for details)

convert(m`24 inches`, foot);
// => new Measurement(2, foot)

system

The UnitSystem created by createUnitSystem.

conversion

A collection of converter creators. A converter is an object with forward and backward methods, meant for converting between two units.

Converters shouldn't be used directly. Instead, define them when creating a unit, and UnitSystem will be able to automatically convert for you.

const { conversion } = require('unit-system');

conversion.slopeIntercept(slope, intercept = 0)

Given a slope and an optional intercept, produces a converter.

Also exported as: multiplyBy, times

const celsiusToFahrenheit = conversion.slopeIntercept(9 / 5, 32);

celsiusToFahrenheit.forward(100) === 212;
celsiusToFahrenheit.backward(32) === 0;

conversion.divideBy(divisor)

A special case of multiplyBy, useful when defining the reverse conversion is clearer.

const feetToInches = conversion.divideBy(12);

feetToInches.forward(3) === 36;
feetToInches.backward(12) === 1;

conversion.twoPoint([x1, y1], [x2, y2])

Given two example points on a line, produces a converter. Useful when a conversion can be more clearly expressed in terms of easily-understood examples.

Also exported as: fromExamples, byExample

const freezing = [0, 32];
const boiling = [100, 212];
const celsiusToFahrenheit = conversion.twoPoint(freezing, boiling);

celsiusToFahrenheit.forward(100) === 212;
celsiusToFahrenheit.backward(32) === 0;

conversion.addConstant(constant)

Given a constant value, produces a converter. A special case of slopeIntercept where slope is always 1.

Also exported as: add, constant

const celsiusToKelvin = conversion.addConstant(273.15);

celsiusToKelvin.forward(0) === 273.15;
celsiusToKelvin.backward(-272.15) === 1;

new Unit(name)

The base unit type.

const { Unit } = require('unit-system');

const inch = new Unit('inch');

inch.name === 'inch';

new Measurement(number, unit)

A value type representing a number and its unit.

const { Measurement } = require('unit-system');

const oneInch = new Measurement(1, inch);

oneInch.value === 1;
oneInch.unit === inch;

new UnitSystem(units)

A collection of units. Internally tracks aliases for units (used by m to look up the corresponding unit) and converters.

const { UnitSystem } = require('unit-system');

const myUnitSystem = new UnitSystem([
  [inch, { alias: 'inches' }],
  [foot, { convert: { from: [inch, conversion.divideBy(12)] } }],
]);

myUnitSystem.getUnitForAlias('inches') === inch;

myUnitSystem.convert(new Measurement(12, inch), foot);
// => new Measurement(1, foot)

.merge(...unitSystems)

Takes one or more other UnitSystems and copies this unit into this one.

const mySystem = new UnitSystem([[new Unit('inch'), { alias: 'inches' }]]);

const systemA = new UnitSystem([[new Unit('foot')]]);
const systemB = new UnitSystem([[new Unit('yard')]]);
const systemC = new UnitSystem([[new Unit('mile')]]);

mySystem.merge(systemA, systemB, systemC);

.register(unit, { alias, convert })

Registers the given unit within the system.

const inch = new Unit('inch');
system.register(inch);

If alias is provided, that unit can now be referenced by that alias.

system.register(inch, { alias: 'inches' });

If convert is provided, its properties to and from are used to register converters between two units.

system.register(inch, {
  convert: {
    to: [centimeter, multiplyBy(2.54)],
    from: [foot, divideBy(12)],
  },
});

.registerAll(units)

Like the first argument to new UnitSystem(units), registers all the given units.

.addConverter(startUnit, endUnit, converter)

Adds a converter for units that have already been registered.

const inch = new Unit('inch');
const foot = new Unit('foot');
const system = new UnitSystem([[inch], [foot]]);
system.addConverter(inch, foot, divideBy(12));

.getUnitForAlias(alias)

Looks up the corresponding unit for the given alias.

system.getUnitForAlias('inches') === inch;

.convert(measurement, unit|string)

convert will take the given measurement and attempt to convert it the desired unit. It may take multiple hops to make that happen.

If unit is a string, convert will assume it is an alias and will look up the corresponding unit.

Consider a UnitSystem that defines kilometers, meters, centimeters, inches, feet, and miles:

const kilometer = createUnit('kilometer');
const meter = createUnit('meter', {
  convert: {
    from: [kilometer, conversion.multiplyBy(1000)],
  },
});
const centimeter = createUnit('centimeter', {
  convert: {
    from: [meter, conversion.multiplyBy(100)],
  },
});

const inch = createUnit('inch', {
  convert: {
    to: [centimeter, conversion.multiplyBy(2.54)],
  },
});
const foot = createUnit('foot', {
  convert: {
    from: [inch, conversion.divideBy(12)],
  },
});
const mile = createUnit('mile', {
  alias: 'mile',
  convert: {
    to: [foot, conversion.multiplyBy(5280)],
  },
});

It can convert miles to kilometers, even though a converter between those two was never explicitly declared:

const oneMileInKilometers = system.convert(m`1 mile`, kilometer);
oneMileInKilometers.value === 1.609344;

When a multi-step converter is created, it will be cached, to save on the lookup time.

.add(...measurements)

add will take the given measurements and attempt to add them together, converting them if needed.

Consider a UnitSystem that defines centimeters, inches, and feet:

const centimeter = createUnit('centimeter');
const inch = createUnit('inch', {
  alias: 'inches',
  convert: {
    to: [centimeter, conversion.multiplyBy(2.54)],
  },
});
const foot = createUnit('foot', {
  alias: 'feet',
  convert: {
    from: [inch, conversion.divideBy(12)],
  },
});

It can add up several values in each of those units, converting them to the same unit:

const eightFeet = system.add(
  m`2 feet`,
  m`18 inches`,
  m`2 inches`,
  m(15.24, centimeter),
  m`10 inches`,
  m`3 feet`
);
eightFeet.value === 8;
eightFeet.unit === foot;

.subtract(measurement1, measurement2)

subtract will take the two given measurements and attempt to subtract them, converting them if needed.

Consider a UnitSystem that defines centimeters and inches:

const centimeter = createUnit('centimeter');
const inch = createUnit('inch', {
  alias: 'inches',
  convert: {
    to: [centimeter, conversion.multiplyBy(2.54)],
  },
});

It can subtract two values in either of those units, converting them to the same unit:

const eighteenInches = system.subtract(m`24 inches`, m(15.24, centimeter));
eighteenInches.value === 18;
eighteenInches.unit === inch;

subtract does not support operating on more than 2 measurements at a time.

.multiply(measurement, ...numbers)

multiply will take the a measurement and multiply it with one or more numbers. The order of arguments is not important. Only one measurement can be supplied.

const twelveInches = system.multiply(m`4 inches`, 3);
twelveInches.value === 12;
twelveInches.unit === inch;

.divide(measurement, measurement|number)

divide will take a measurement and divide it by the second argument, returning either another measurement or a number, depending on the type of the second argument.

const fourInches = system.divide(m`12 inches`, 3);
fourInches.value === 4;
fourInches.unit === inch;

system.divide(m`18 inches`, m`6 inches`) === 3;

It will also automatically convert units when dividing two measurements:

system.divide(m`3 feet`, m`18 inches`) === 2;

.equal(measurement, measurement)

equal will return true if the two measurements have the same value and unit (after conversion). Otherwise it returns false.

system.equal(m`12 inches`, m`1 foot`) === true;

.lessThan(measurement, measurement)

lessThan will return true if the first measurement is less than the second (after conversion). Otherwise it returns false.

.lessThanOrEqual(measurement, measurement)

lessThanOrEqual will return true if the first measurement is less than or equal to the second (after conversion). Otherwise it returns false.

.greaterThan(measurement, measurement)

greaterThan will return true if the first measurement is greater than the second (after conversion). Otherwise it returns false.

.greaterThanOrEqual(measurement, measurement)

greaterThanOrEqual will return true if the first measurement is greater than or equal to the second (after conversion). Otherwise it returns false.

.measure(value, unit)

Shorthand function for creating new Measurement instances. If a unit is defined with an alias, that alias can be used instead of passing in the unit.

// All of these are equivalent to `new Measurement(12, inch)`
system.measure`12 inches`;
system.measure`12inches`;
system.measure`12 ${inch}`;
system.measure`12`.inches;
system.measure(12).inches;
system.measure(12, inch);

measure is bound to system (its this cannot be changed), so it can be "detached" and used as a bare function (but still retain access to your unit system):

const m = system.measure;
m`12 inches`;