unit-system

1.13.0 • Public • Published

unit-system

ΜΕΤΡΩ ΧΡΩ

Use the measure

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

Documentation

createUnitSystem(units)

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

createUnit(name, options)

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

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)

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)

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.

conversion.slopeIntercept(slope, intercept = 0)

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

Also exported as: multiplyBy, times

conversion.divideBy(divisor)

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

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

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

new Unit(name)

The base unit type.

new Measurement(number, unit)

A value type representing a number and its unit.

new UnitSystem(units)

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

.merge(...unitSystems)

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

.register(unit, { alias, convert })

Registers the given unit within the system.

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

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

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

.getUnitForAlias(alias)

Looks up the corresponding unit for the given alias.

.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:

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

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:

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

.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:

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

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.

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

It will also automatically convert units when dividing two measurements:

.equal(measurement, measurement)

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

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

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):

Package Sidebar

Install

npm i unit-system

4

1.13.0

ISC

74.7 kB

47