Update builtin units docs to be more complete

docs/builtin.md

@@ -4,27 +4,27 @@ While users can [define their own unit system](unit-systems.html), Safe Units al
 
 All quantities provided are generic and of the form `type Quantity<N = number>` so all quantity types will default to using `number` as the numeric type but may be passed another numeric type.
 
-## Base Units
+## Dimensions
 
 The built-in units include the standard set of SI base dimension and corresponding units:
 
-* `Length` / `meters`
-* `Mass` / `kilograms`
-* `Time` / `seconds`
-* `ElectricCurrent` / `amperes`
-* `Temperature` / `kelvin`
-* `AmountOfSubstance` / `moles`
-* `LuminousIntensity` / `candelas`
+* `Length` / `meters` (m)
+* `Mass` / `kilograms` (kg)
+* `Time` / `seconds` (s)
+* `ElectricCurrent` / `amperes` (A)
+* `Temperature` / `kelvin` (K)
+* `AmountOfSubstance` / `moles` (mol)
+* `LuminousIntensity` / `candelas` (cd)
 
 In addition, several extra dimensions are defined:
 
-* `PlaneAngle` / `radians`
-* `SolidAngle` / `steradians`
-* `Memory` / `bits`
+* `PlaneAngle` / `radians` (rd)
+* `SolidAngle` / `steradians` (sr)
+* `Memory` / `bits` (b)
 
 While plane and solid angles are defined as dimensionless in the SI specification, they are defined here in case users want to be more rigorous with their angles. If not, then these can be safely ignored.
 
-## Generic Base Units
+### Generic Base Units
 
 The base units are only provided for `number` measures, but users can create the base units for a given measure type through:
 
@@ -34,13 +34,220 @@ builtinBaseUnits.ts
 
 These versions of `meters`, `kilograms`, etc. will all operate on measures whose numeric types are `BigNumber`.
 
-## Provided Units
+## Derived Units
 
-A large number of built in quantities (e.g. distance, velocity, force and magnetic flux density) are provided. See [here](https://github.com/jscheiny/safe-units/blob/master/src/unit/quantities.ts) for a full list.
+The following is a list of the provided quantities and measures given by the library. Units are grouped by their type (also referred to as a quantity). Some quanties do not have a corresponding unit. US customary units and imperial units are placed into `US` and `Imperial` namespaces respectively to avoid name clashes.
 
-Many units are provided from the SI, Imperial and U.S. customary unit systems. See [here](https://github.com/jscheiny/safe-units/tree/master/src/unit) for all of the units.
+- `Length` - m
+    - `meters` (m) _[base unit]_
+    - `inches` (in)
+    - `thous` (th)
+    - `feet` (ft)
+    - `yards` (yd)
+    - `chains` (ch)
+    - `furlongs` (fur)
+    - `miles` (mi)
+    - `leagues` (lea)
+    - `fathoms` (ftm)
+    - `cables` (cable)
+    - `nauticalMiles` (nmi)
+    - `links` (li)
+    - `rods` (rd)
+    - `angstroms` (Å)
+    - `US.points` (p)
+    - `US.picas` (pica)
+- `Mass` - kg
+    - `kilograms` (kg) _[base unit]_
+    - `grams` (g)
+    - `pounds` (lb)
+    - `grains` (gr)
+    - `ounces` (oz)
+    - `carats` (ct)
+    - `Imperial.drachms` (dr)
+    - `Imperial.stone` (st)
+    - `Imperial.quarters` (qtr)
+    - `Imperial.hundredweights` (cwd)
+    - `Imperial.tons` (t)
+    - `US.drams` (dr)
+    - `US.pennyweights` (dwt)
+    - `US.hundredweights` (cwd)
+    - `US.tons` (ton)
+- `Time` - s
+    - `seconds` (s) _[base unit]_
+    - `minutes` (min)
+    - `hours` (hr)
+    - `days` (d)
+- `ElectricCurrent` - A
+    - `amperes` (A) _[base unit]_
+- `Temperature` - K
+    - `kelvin` (K) _[base unit]_
+- `AmountOfSubstance` - mol
+    - `moles` (mol) _[base unit]_
+- `LuminousIntesity` - cd
+    - `candelas` (cd) _[base unit]_
+- `PlaneAngle` - rad
+    - `radians` (rad) _[base unit]_
+    - `piRadians` (pi rad)
+    - `tauRadians` (tau rad)
+    - `arcSeconds` (arcsec)
+    - `arcMinutes` (arcmin)
+    - `degrees` (deg)
+- `SolidAngle` - sr
+    - `steradians` (sr) _[base unit]_
+- `Memory` - b
+    - `bits` (b) _[base unit]_
+    - `bytes` (B)
+- `Frequency` - 1 / s
+    - `hertz` (Hz)
+- `FrequencyDrift` - 1 / s²
+- `FuelEfficiency` - 1 / m²
+- `Wavenumber` - 1 / m
+- `Area` - m²
+    - `perches` (perch)
+    - `roods` (rood)
+    - `acres` (acre)
+    - `ares` (a)
+    - `hectares` (ha)
+- `Volume` - m³
+    - `liters` (L)
+    - `Imperial.fluidOunces` (fl oz);
+    - `Imperial.gills` (gi)
+    - `Imperial.pints` (pt)
+    - `Imperial.quarts` (qt)
+    - `Imperial.gallons` (gal)
+    - `US.minims` (min)
+    - `US.fluidDrams` (fl dr)
+    - `US.teaspoons` (tsp)
+    - `US.tablespoons` (Tbsp)
+    - `US.fluidOunces` (fl oz)
+    - `US.shots` (jig)
+    - `US.gills` (gi)
+    - `US.cups` (cp)
+    - `US.pints` (pt)
+    - `US.quarts` (qt)
+    - `US.gallons` (gal)
+    - `US.barrels` (liq bbl)
+    - `US.oilBarrels` (bbl)
+    - `US.hogsheads` (hogshead)
+    - `US.dryPints` (dry pt)
+    - `US.dryQuarts` (dry qt)
+    - `US.dryGallons` (dry gal)
+    - `US.pecks` (pk)
+    - `US.bushels` (bu)
+    - `US.dryBarrels` (dry bbl)
+- `Absement` - m ⋅ s
+- `Velocity` - m / s
+    - `speedOfLight` (C)
+- `Acceleration` - m / s²
+- `Jerk` - m / s³
+- `Jounce` - m / s⁴
+- `Crackle` - m / s⁵
+- `Pop` - m / s⁶
+- `VolumetricFlow` - m³ / s
+- `MassFlowRate` - kg / s
+- `LinearDensity` - kg / m
+- `AreaDensity` - kg / m²
+- `VolumeDensity` - kg / m³
+- `Force` - kg ⋅ m / s²
+    - `newtons` (N)
+- `Yank` - km ⋅ m / s³
+- `Pressure` - kg / (m ⋅ s²)
+    - `pascals` (Pa)
+    - `bars` (bar)
+    - `atmospheres` (atm)
+    - `torrs` (Torr)
+- `Compressibility` - m ⋅ s² / kg
+- `DynamicViscosity` - kg / (m ⋅ s)
+- `SurfaceTension` - kg / s²
+- `Momentum` - kg ⋅ m / s
+- `MomentOfInertia` - kg ⋅ m²
+- `Energy` - kg ⋅ m² / s²
+    - `joules` (J)
+- `Power` - kg ⋅ m² / s³
+    - `watts` (W)
+- `PowerDensity` - kg / (m ⋅ s³)
+- `Voltage` - kg ⋅ m² / (s³ ⋅ A)
+    - `volts` (V)
+- `ElectricCharge` - s ⋅ A
+    - `coulombs` (C)
+- `ElectricChargeDensity` - s ⋅ A / m³
+- `ElectricCurrentDensity` - A / m²
+- `ElectricDisplacement` - s ⋅ A / m²
+- `EletricFieldStrength` - kg ⋅ m / (s³ ⋅ A)
+- `ElectricalCapacitance` - s⁴ ⋅ A² / (kg ⋅ m²)
+    - `farads` (F)
+- `ElectricalConductance` - s³ ⋅ A / (kg ⋅ m²)
+    - `siemens` (S)
+- `ElectricalConductivity` - s³ ⋅ A² / (kg ⋅ m³)
+- `ElectricalResistance` - kg ⋅ m² / (s³ ⋅ A²)
+    - `ohms` (Ω)
+- `ElectricalResistivity` - kg ⋅ m³ / (s³ ⋅ A²)
+- `ElectricalInductance` - kg ⋅ m² / (s² ⋅ A²)
+    - `henrys` (H)
+- `LinearChargeDensity` - s ⋅ A / m
+- `Permittivity` - s⁴ ⋅ A² / (kg ⋅ m³)
+- `MagneticFlux` - kg ⋅ m² / (s² ⋅ A)
+    - `webers` (Wb)
+- `MagneticFluxDensity` - kg / (s² ⋅ A)
+    - `teslas` (T)
+- `MagneticPermeability` - kg ⋅ m / (s² ⋅ A²) 
+- `Magnetization` - A / m
+- `MagneticReluctance` - s² ⋅ A² / (kg ⋅ m²)
+- `MagneticMoment` - kg ⋅ m³ / (s² ⋅ A)
+- `MagneticRigidity` - kg ⋅ m / (s² ⋅ A)
+- `MagneticDipoleMoment` - m² ⋅ A
+- `MagneticSusceptibility` - s² ⋅ A² / (kg ⋅ m)
+- `Irradiance` - kg / s³
+- `Entropy` - kg ⋅ m / (s² ⋅ K)
+- `SpecificHeat` - m² / (s² ⋅ K)
+- `SpecificVolume` - m³ / kg
+- `ThermalConductivity` - kg ⋅ m / (s³ ⋅ K)
+- `ThermalResistance` - s³ ⋅ K / (kg ⋅ m²)
+- `ThermalExpansionCoefficient` - 1 / K
+- `ThermalGradient` - K / m
+- `MolarEntropy` - kg ⋅ m² / (s² ⋅ K ⋅ mol)
+- `MolarEnergy` - kg ⋅ m² / (s² ⋅ mol)
+- `Molarity` - mol / m³
+- `MolarVolume` - m³ / mol
+- `Molality` - mol / kg
+- `MolarMass` - kg / mol
+- `MolarConductivity` - s³ ⋅ A² / (kg ⋅ mol)
+- `CatalyticActivity` -  mol / s
+    - `katals` (kat)
+- `CatalyticEfficiency` - m³ / (s ⋅ mol)
+- `ReactionRate` - mol / (m³ ⋅ s)
+- `RadiationDose` - m² / s²
+    - `sieverts` (Sv)
+- `RadiationDoseRate` - m² / s³
+- `ElectronMobility` - s² ⋅ A / kg
+- `AngularMomentum` - kg ⋅ m² / s
+- `SpecificAngularMomentum` - m² / s
+- `Luminance` - cd / m²
+- `LuminousFlux` - cd ⋅ sr
+    - `lumens` (lm)
+- `Illuminance` - cd ⋅ sr / m²
+    - `luxes` (lx)
+- `LuminousEnergy` - s ⋅ cd ⋅ sr
+- `LuminousExposure` - s ⋅ cd ⋅ sr / m²
+- `LuminousEfficiency` - s³ ⋅ cd ⋅ sr / (kg ⋅ m²)
+- `RadiantIntensity` - kg ⋅ m² / (s³ ⋅ sr)
+- `SpectralIntensity` - kg ⋅ m / (s³ ⋅ sr)
+- `Radiance` - kg / (s³ ⋅ sr)
+- `SpectralRadiance` - kg / (m ⋅ s³ ⋅ sr)
+- `AngularVelocity` - rad / s
+- `AngularAcceleration` - rad / s²
 
-Prefix functions are provided for both standard [SI prefixes](https://github.com/jscheiny/safe-units/blob/master/src/unit/metric.ts) and for [memory prefixes](https://github.com/jscheiny/safe-units/blob/master/src/unit/memory.ts).
+## Prefixes
+
+You may notice that some commonly used units, such as kilometers, are absent from the list above. Instead of creating all the different combinations of prefix and unit pairs, Safe Units instead provides prefix functions. These are functions which operate on measures to construct a new measure with a corresponding symbol. For example:
+
+```example
+builtinPrefixes.ts
+```
+
+Prefix functions are provided for all of the [SI prefixes](https://en.wikipedia.org/wiki/Metric_prefix) and all of the [binary prefixes](https://en.wikipedia.org/wiki/Binary_prefix) for memory.
+
+## Trigonometry
 
 Trigonometric functions are provided in the `Trig` namespace for converting between plane angles and dimensionless values, the signatures are as follows:
 

docs/changelog.md

@@ -1,14 +1,34 @@
 # Changelog
 
+## v2.0.0
+
+**Breaking changes**
+- The `Measure.dimension` and `Measure.dimensionless` functions now require a unit system as their first parameter. The `Measure.dimension` function can no longer arbitrarily produce new dimensions. To add new dimensions, create a new `UnitSystem`.
+- Changed the way in which unit exponents are represented. Exponents are now numbers instead of strings and units contain every dimension in their unit system even if the exponent is zero.
+- Removed the ability to arbitrarily perform exponentiation on measures. The `measure.toThe` and `Measure.pow` functions have been removed. 
+- Removed the ability to perform roots of measures. The `Measure.sqrt` and `Measure.cbrt` functions have been removed.
+
+**New features**
+- Introduced the concept of a [unit system](unit-systems.html). Unit systems define a fixed set of dimensions and their corresponding base units. Measures of a given unit system are not assignable to measures of other unit systems. Safe units ships with a default implementation of the SI unit system as `SIUnitSystem`.
+- Removed the limitations on exponents. Previously, exponents of dimensions had to be between -5 and +5. Now the limit on exponents is much larger and should no longer present any issues.
+- Added a new `valueIn` method to the `Measure` class. Calling `measure.valueIn(unit)` is syntactic sugar for `measure.div(unit).value`.
+
+**Fixes**
+- Fixed an issue where measures could be assigned to measures of different unit types if they contained a superset of the other measure's dimensions. In order to fix this, the concept of unit systems was introduced.
+- Fixed incorrect symbols for the `joules` and `watts` units.
+
 ## v1.1.1
 
+**Fixes**
 - Fixed an issue where `wrapRootFn` would allow non-positive values as the root parameter.
 
 ## v1.1.0
 
+**Improvements**
 - Added a custom formatter argument that can be passed into the `Measure.in` and `Measure.toString` methods.
 
 ## v1.0.0
 
+**Breaking changes**
 - Changed all interface names to no longer be I- prefixed.
 - Fixed the definition of the `bar` unit.

docs/examples/builtinPrefixes.ts

@@ -0,0 +1,6 @@
+import { bits, kibi, kilo, Measure, meters } from "safe-units";
+
+const distance = Measure.of(30, kilo(meters)); // 30000 m
+distance.in(kilo(meters)); // "30 km"
+const size = Measure.of(2, kibi(bits)); // 2048 b
+size.in(kibi(bits)); // "2 KiB"

src/measure/genericMeasureFactory.ts

@@ -11,7 +11,8 @@ interface GenericMeasureFactory<N> {
 
     /**
      * Creates a new dimension base unit.
-     * @param dim a unique string literal which names this dimension (e.g. "length")
+     * @param unitSystem the unit system for this dimension
+     * @param dimension the basis of the unit system for this dimension
      * @param symbol the symbol of the base unit of the dimension (e.g. "m")
      * @returns A measure representing 1 base unit of the dimension (1 m)
      */
@@ -23,6 +24,7 @@ interface GenericMeasureFactory<N> {
 
     /**
      * Creates a dimensionless measure.
+     * @param unitSystem the unit system for this measure
      * @param value the value of the measure
      * @returns a measure with no dimensions
      */
@@ -61,7 +63,7 @@ export type GenericMeasureType<N, StaticMethods extends {}> = GenericMeasureComm
  * useful for attaching static math operations to the type.
  * @returns a factory for constructing measures of the given numeric type
  * @example
- * type MyMeasure<U extends Unit> = GenericMeasure<MyNumberType, U>;
+ * type MyMeasure<B, U extends Unit<B>> = GenericMeasure<MyNumberType, B, U>;
  * const MyMeasure = createMeasureType({ ... });
  */
 export function createMeasureType<N, S extends {} = {}>(

src/unit/metric.ts

@@ -6,8 +6,8 @@ import * as Quantity from "./quantities";
 export const hertz: Quantity.Frequency = seconds.inverse().withSymbol("Hz");
 export const newtons: Quantity.Force = kilograms.times(meters.per(seconds.squared())).withSymbol("N");
 export const pascals: Quantity.Pressure = newtons.per(meters.squared()).withSymbol("Pa");
-export const joules: Quantity.Energy = newtons.times(meters).withSymbol("N");
-export const watts: Quantity.Power = joules.per(seconds).withSymbol("J");
+export const joules: Quantity.Energy = newtons.times(meters).withSymbol("J");
+export const watts: Quantity.Power = joules.per(seconds).withSymbol("W");
 export const volts: Quantity.Voltage = watts.per(amperes).withSymbol("V");
 export const coulombs: Quantity.ElectricCharge = amperes.times(seconds).withSymbol("C");
 export const farads: Quantity.ElectricalCapacitance = coulombs.per(volts).withSymbol("F");

src/unit/quantities.ts

@@ -115,6 +115,10 @@ export const Jounce = Jerk.over(Time);
 export type Crackle<N = number> = LiftMeasure<typeof Crackle, N>;
 export const Crackle = Jounce.over(Time);
 
+/** m / s⁶ */
+export type Pop<N = number> = LiftMeasure<typeof Pop, N>;
+export const Pop = Crackle.over(Time);
+
 /** m³ / s */
 export type VolumetricFlow<N = number> = LiftMeasure<typeof VolumetricFlow, N>;
 export const VolumetricFlow = Volume.over(Time);
@@ -339,7 +343,7 @@ export const CatalyticActivity = AmountOfSubstance.over(Time);
 export type CatalyticEfficiency<N = number> = LiftMeasure<typeof CatalyticEfficiency, N>;
 export const CatalyticEfficiency = Volume.over(AmountOfSubstance.times(Time));
 
-/** mol / (m³ ⋅ s)  */
+/** mol / (m³ ⋅ s) */
 export type ReactionRate<N = number> = LiftMeasure<typeof ReactionRate, N>;
 export const ReactionRate = CatalyticActivity.over(Volume);
 
@@ -359,7 +363,7 @@ export const ElectronMobility = Area.over(Voltage.times(Time));
 export type AngularMomentum<N = number> = LiftMeasure<typeof AngularMomentum, N>;
 export const AngularMomentum = Force.times(Length).times(Time);
 
-/** m² /s */
+/** m² / s */
 export type SpecificAngularMomentum<N = number> = LiftMeasure<typeof SpecificAngularMomentum, N>;
 export const SpecificAngularMomentum = AngularMomentum.over(Mass);
 
@@ -393,7 +397,7 @@ export const LuminousEfficiency = LuminousFlux.over(Power);
 export type RadiantIntensity<N = number> = LiftMeasure<typeof RadiantIntensity, N>;
 export const RadiantIntensity = Power.over(SolidAngle);
 
-/** kg ⋅ m / (s³ ⋅ sr)  */
+/** kg ⋅ m / (s³ ⋅ sr) */
 export type SpectralIntensity<N = number> = LiftMeasure<typeof SpectralIntensity, N>;
 export const SpectralIntensity = RadiantIntensity.over(Length);