measurable 1.1.0 → 2.0.0

package/CHANGELOG.md

@@ -0,0 +1,100 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [2.0.0] - 2026-06-18
+
+This release makes conversions and quantity arithmetic **exact**. Magnitudes and
+unit transforms are represented as exact rationals internally and only collapse
+to a `number` at the edge, so `foot → inch` is exactly `12` (not
+`12.000000000000002`) and chains and round trips no longer accumulate drift.
+
+### Breaking
+
+- **`Quantity.magnitude` is now a read-only getter** derived from the new
+  `Quantity.rational`, rather than a writable field. Assigning to
+  `quantity.magnitude` no longer works.
+- **`Quantity` construction rejects non-finite magnitudes.**
+  `new Quantity(Infinity, unit)` (or `NaN`) now throws instead of being accepted.
+- **`Unit.toBase` / `Unit.fromBase` are methods, not function-valued fields.**
+  Calling `unit.toBase(x)` is unchanged; holding an unbound reference such as
+  `const f = unit.toBase` no longer works.
+- **`Unit`'s constructor options changed shape** to a discriminated union
+  (`{ linear }` vs `{ toBase, fromBase }`). Only affects code that calls
+  `new Unit(...)` directly; the `Dimension` builder methods are unaffected.
+- **Conversion results changed value.** Outputs are now exact, so values that
+  previously carried floating-point error differ (e.g. `12.000000000000002` is
+  now `12`). `Quantity` equality and comparison are now exact rational
+  comparisons rather than float `===`, so quantities that are mathematically
+  equal compare equal even across a conversion that previously drifted.
+- **Requires Node >= 14** (declared via `engines`); the library now uses `bigint`.
+
+### Added
+
+- **`Rational`** — an exact rational number (`bigint` numerator/denominator),
+  exported from the package root. Supports `plus`/`minus`/`times`/`dividedBy`
+  (with `add`/`sub`/`mul`/`div` aliases), `negate`/`abs`, `equals`/`eq`,
+  `compare`, `sign`, `toNumber`, and the static `Rational.from`.
+- **`Quantity.rational`** exposes the exact magnitude; the constructor and
+  `times`/`dividedBy` now accept `number | Rational`.
+- **`Dimension.convertRational(value, from, to)`** — exact, rational-in /
+  rational-out conversion.
+- **`Unit.linear`** — the exact `{ scale, offset }` transform for linear and
+  affine units (`undefined` for `custom` ones).
+- **`Dimension.unit` and `Dimension.affine` accept `number | Rational`**, so a
+  ratio a decimal cannot represent exactly (e.g. Fahrenheit's `5/9`) can be
+  given exactly.
+- New built-in dimensions: `area`, `data`, `energy`, `frequency`,
+  `illuminance`, `luminance`, `luminousIntensity`, `power`, and `pressure`
+  (each with its SI prefix ladder where applicable).
+- `definePrefixed`'s reference `scale` is now optional, defaulting to `1`.
+
+### Fixed
+
+- Linear and affine conversions are now exact (`foot → inch` is `12`, `1 L → mL`
+  round trips cleanly, and so on).
+- SI-prefixed scales are computed in rational arithmetic, fixing drifted scales
+  such as `nanowattHour` (`3600 × 1e-9`).
+- Built-in Fahrenheit is defined with exact rationals and round-trips without
+  drift in both directions.
+- `Rational.toNumber` stays correctly rounded at extreme magnitudes (operands
+  beyond `2^53`), where converting each operand to a double before dividing
+  would otherwise lose precision.
+
+## [1.1.1] - 2026-06-17
+
+### Fixed
+
+- Enable `embed-readme` so the README renders on npmjs.com.
+
+## [1.1.0] - 2026-06-17
+
+### Added
+
+- SI metric prefix ladders generated across the metric dimensions.
+- `Quantity` arithmetic — `plus` / `minus` / `times` / `dividedBy` (with
+  `add` / `sub` / `mul` / `div` aliases).
+- `Quantity` comparison — `equals` / `notEquals` / `lessThan` / `greaterThan` /
+  `lessThanOrEqual` / `greaterThanOrEqual` (with `eq` / `ne` / `lt` / `gt` /
+  `lte` / `gte` aliases), plus `compareTo` as a sort comparator.
+- `Quantity.ratioTo` for the dimensionless ratio between two quantities.
+- `Quantity.abs` and the `Quantity.min` / `max` / `sum` statics.
+- `clamp` as an instance method bounding a quantity to a range.
+- `Quantity.toString`.
+- `Quantity.isZero` / `isPositive` / `isNegative` predicates and `round`.
+
+## [1.0.0] - 2026-06-16
+
+### Added
+
+- Initial release: the core conversion engine (`Dimension`, `Unit`, `Quantity`,
+  `MeasurementSystem`), string parsing via `Quantity.parse`, and the first set
+  of built-in dimensions and measurement systems.
+
+[2.0.0]: https://github.com/mhuggins/measurable/compare/v1.1.1...v2.0.0
+[1.1.1]: https://github.com/mhuggins/measurable/compare/v1.1.0...v1.1.1
+[1.1.0]: https://github.com/mhuggins/measurable/compare/v1.0.0...v1.1.0
+[1.0.0]: https://github.com/mhuggins/measurable/releases/tag/v1.0.0

package/README.md

@@ -3,9 +3,14 @@
 Convert between units of measurement, with batteries-included common units and
 first-class support for defining your own.
 
-- **No drift** — each unit defines a single transform to its dimension's base
-  unit; reverse conversions are derived, never stored, so they can't fall out of
-  sync.
+- **Exact, no drift** — magnitudes are held as exact rational numbers and
+  conversions run in rational arithmetic, collapsing to a float only when you
+  read `.magnitude`. So `foot → inch` is exactly `12` (not `12.000000000000002`),
+  and chains and round trips like `liter → gallon → liter` come back to exactly
+  what you started with.
+- **No redundant factors** — each unit defines a single transform to its
+  dimension's base unit; reverse conversions are derived, never stored, so they
+  can't fall out of sync.
 - **Free chaining** — any unit converts to any other in the same dimension
   (e.g. `mile → inch`) without you defining every pair.
 - **Affine units** — temperature scales (°C/°F/K) and anything else needing an
@@ -26,7 +31,7 @@ The package is split into three import paths so the core stays lean:
 
 | Import                     | What you get                                                              |
 | -------------------------- | ------------------------------------------------------------------------- |
-| `measurable`             | The building blocks: `Quantity`, `Dimension`, `MeasurementSystem`, `Unit`, errors |
+| `measurable`             | The building blocks: `Quantity`, `Dimension`, `MeasurementSystem`, `Unit`, `Rational`, errors |
 | `measurable/dimensions`  | Predefined dimensions and their units (`length`, `meter`, `volume`, …)    |
 | `measurable/systems`     | Predefined measurement systems (`metric`, `imperial`, `usCustomary`)      |
 
@@ -34,7 +39,7 @@ The package is split into three import paths so the core stays lean:
 
 ```ts
 import { Quantity } from "measurable";
-import { meter, mile, celsius, fahrenheit } from "measurable/dimensions";
+import { meter, mile, foot, inch, celsius, fahrenheit } from "measurable/dimensions";
 
 // Convert: `.to()` returns a Quantity, `.in()` returns a raw number.
 new Quantity(5, mile).to(meter).magnitude; // 8046.72
@@ -42,6 +47,10 @@ new Quantity(5, mile).in(meter);           // 8046.72
 
 // Affine scales work the same way.
 new Quantity(100, celsius).in(fahrenheit); // 212
+
+// Conversions are exact: magnitudes are rationals under the hood.
+new Quantity(1, foot).in(inch);                          // 12 (not 12.000000000000002)
+new Quantity(1, foot).to(inch).to(foot).magnitude;       // 1 (exact round trip)
 ```
 
 ## Concepts
@@ -49,35 +58,110 @@ new Quantity(100, celsius).in(fahrenheit); // 212
 - **`Dimension`** — a kind of measurable quantity (length, volume, mass, …). It
   owns a canonical **base unit** and is where all conversion happens. A unit
   belongs to exactly one dimension.
-- **`Unit`** — a name plus a transform (`toBase` / `fromBase`) into its
-  dimension's base unit. Created through a dimension's builder methods.
-- **`Quantity`** — a magnitude paired with a unit (e.g. `5 kilometer`).
+- **`Unit`** — a name plus a transform into its dimension's base unit: an exact
+  rational `scale`/`offset` for linear and affine units, or an arbitrary
+  function pair for `custom` ones. Created through a dimension's builder methods.
+- **`Quantity`** — a magnitude paired with a unit (e.g. `5 kilometer`). The
+  magnitude is held as an exact **`Rational`**; `.magnitude` reads it as a
+  `number`.
+- **`Rational`** — an exact rational number (`n / d` over `bigint`s) used for the
+  lossless arithmetic above. You rarely construct one directly, but can pass one
+  anywhere a magnitude or scale is expected.
 - **`MeasurementSystem`** — a cross-dimension tag (metric/imperial/…). A unit can
   belong to many; membership is optional and never affects whether a conversion
   is allowed.
 
+## Exact arithmetic
+
+A linear conversion is inherently rational — a foot is exactly `3048/10000` m and
+an inch exactly `254/10000` m, so a foot is exactly `12` inches. Storing those
+ratios as binary floats and routing values through the base unit loses that
+(`1 foot → inch` would give `12.000000000000002`).
+
+Instead, each `Quantity` keeps its magnitude as an exact `Rational`, and
+conversions/arithmetic run in rational arithmetic, collapsing to a `number` only
+when you read `.magnitude` (or call `.in()`). Because nothing is collapsed
+mid-chain, conversions compose without accumulating drift:
+
+```ts
+import { Quantity } from "measurable";
+import { liter, usGallon } from "measurable/dimensions";
+
+// A round trip through an awkward ratio still lands exactly on 7.
+new Quantity(7, liter).to(usGallon).to(liter).magnitude; // 7
+
+// .rational exposes the underlying exact value (always in lowest terms).
+new Quantity(7, liter).to(usGallon).rational; // Rational 125000000/67596639
+```
+
+This is exact for linear and affine units. A conversion that passes through a
+non-linear `custom` unit (e.g. a logarithmic scale) necessarily uses floating
+point and recaptures the result as a rational, so it is best-effort there.
+
 ## Built-in dimensions
 
 Import any dimension or unit from `measurable/dimensions`:
 
-| Dimension     | Base       | Units (a selection)                                                                 |
-| ------------- | ---------- | ----------------------------------------------------------------------------------- |
-| `length`      | `meter`    | `kilometer`, `centimeter`, `millimeter`, `inch`, `foot`, `yard`, `mile`             |
-| `volume`      | `liter`    | `milliliter`, `us*`/`imperial*` `Gallon`/`Quart`/`Pint`/`Gill`/`FluidOunce`, `cup`, `tablespoon`, `teaspoon` |
-| `mass`        | `gram`     | `kilogram`, `milligram`, `tonne`, `pound`, `ounce`, `stone`, `shortTon`, `longTon`  |
-| `time`        | `second`   | `millisecond`, `minute`, `hour`, `day`, `week`                                      |
-| `temperature` | `kelvin`   | `celsius`, `fahrenheit`                                                              |
-| `angle`       | `radian`   | `degree`, `gradian`, `turn`                                                          |
-| `force`       | `newton`   | `kilonewton`, `dyne`, `poundForce`, `kilogramForce`                                  |
+| Dimension            | Base                     | Units (a selection)                                                                                          |
+| -------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------ |
+| `length`             | `meter`                  | `kilometer`, `centimeter`, `millimeter`, `inch`, `foot`, `yard`, `mile`                                       |
+| `area`               | `squareMeter`            | `squareKilometer`, `hectare`, `are`, `squareInch`, `squareFoot`, `squareYard`, `acre`, `squareMile`          |
+| `volume`             | `liter`                  | `milliliter`, `us*`/`imperial*` `Gallon`/`Quart`/`Pint`/`Gill`/`FluidOunce`, `cup`, `tablespoon`, `teaspoon`  |
+| `mass`               | `gram`                   | `kilogram`, `milligram`, `tonne`, `pound`, `ounce`, `stone`, `shortTon`, `longTon`                            |
+| `time`               | `second`                 | `millisecond`, `minute`, `hour`, `day`, `week`                                                                |
+| `temperature`        | `kelvin`                 | `celsius`, `fahrenheit`                                                                                       |
+| `angle`              | `radian`                 | `degree`, `gradian`, `turn`                                                                                   |
+| `force`              | `newton`                 | `kilonewton`, `dyne`, `poundForce`, `kilogramForce`                                                           |
+| `energy`             | `joule`                  | `kilojoule`, `wattHour`, `kilowattHour`, `calorie`, `kilocalorie`, `britishThermalUnit`                       |
+| `power`              | `watt`                   | `kilowatt`, `megawatt`, `horsepower`, `metricHorsepower`                                                      |
+| `pressure`           | `pascal`                 | `kilopascal`, `bar`, `millibar`, `atmosphere`, `torr`, `psi`, `inchOfMercury`, `inchOfWater`                  |
+| `frequency`          | `hertz`                  | `kilohertz`, `megahertz`, `gigahertz`, `terahertz`                                                            |
+| `data`               | `bit`                    | `byte`, `nibble`, `kilobyte`…`petabyte` (SI), `kibibyte`…`pebibyte` (IEC)                                     |
+| `illuminance`        | `lux`                    | `kilolux`, `millilux`, `footCandle`, `phot`                                                                   |
+| `luminance`          | `candelaPerSquareMeter`  | `nit`, `stilb`                                                                                                |
+| `luminousIntensity`  | `candela`                | `kilocandela`, `millicandela`, `candlepower`, `hefnerkerze`                                                   |
 
 The metric units carry the **full SI prefix ladder** (yotta → yocto), generated for
-you: `length`, `mass`, `volume`, and `force` get every prefix (so `kilogram`
-itself is just the kilo-prefixed gram), while `time` and `angle` get the
-fractional prefixes only (e.g.
-`millisecond`, `microradian`). So `decimeter`, `hectometer`, `megagram`,
-`kiloliter`, `nanosecond`, etc. are all available and parse from their symbols
-(`dm`, `hm`, `Mg`, `kL`, `ns`, and `µm`/`um` for micro). You can apply the same
-ladder to your own dimensions with `definePrefixed` (see below).
+you: the SI-based dimensions (`length`, `mass`, `volume`, `force`, `energy`, `power`,
+`pressure`, `frequency`, `illuminance`, `luminousIntensity`) get every prefix (so
+`kilogram` itself is just the kilo-prefixed gram), while `time` and `angle` get the
+fractional prefixes only (e.g. `millisecond`, `microradian`). Every generated rung
+parses from its symbol (`dm`, `hm`, `Mg`, `kL`, `ns`, `GHz`, `kPa`, and `µm`/`um` for
+micro) and converts like any other unit. `data` additionally carries the **IEC binary**
+multiples (`kibibyte`, `mebibyte`, … = 1024-based) alongside the SI decimal ones
+(`kilobyte`, … = 1000-based). You can apply the same ladder to your own dimensions with
+`definePrefixed` (see below).
+
+### Prefixed unit exports
+
+Each prefixed dimension exports a **record** holding the _complete_ generated ladder
+keyed by name (the return value of `definePrefixed`), plus a **curated subset of those
+same units as individual named exports** for convenience. Reach any rung that isn't
+exported individually through the record — e.g. `metricLength.gigameter`,
+`metricMass.exagram` — or by parsing its symbol.
+
+| Dimension           | Record export(s)                 | Individually exported units                                                                                       |
+| ------------------- | -------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| `length`            | `metricLength`                   | `kilometer`, `hectometer`, `decameter`, `decimeter`, `centimeter`, `millimeter`, `micrometer`, `nanometer`        |
+| `mass`              | `metricMass`                     | `kilogram`, `megagram`, `hectogram`, `decagram`, `decigram`, `centigram`, `milligram`, `microgram`, `nanogram`    |
+| `volume`            | `metricVolume`                   | `kiloliter`, `hectoliter`, `decaliter`, `deciliter`, `centiliter`, `milliliter`                                    |
+| `time`              | `metricTime`                     | `millisecond`, `microsecond`, `nanosecond`, `picosecond`                                                          |
+| `angle`             | `metricAngle`                    | `milliradian`, `microradian`                                                                                       |
+| `force`             | `metricForce`                    | `meganewton`, `kilonewton`, `millinewton`, `micronewton`                                                           |
+| `energy`            | `metricEnergy`, `metricWattHour` | `kilojoule`, `megajoule`, `gigajoule`, `millijoule`; `kilowattHour`, `megawattHour`, `gigawattHour`               |
+| `power`             | `metricPower`                    | `kilowatt`, `megawatt`, `gigawatt`, `terawatt`, `milliwatt`                                                        |
+| `pressure`          | `metricPressure`                 | `kilopascal`, `hectopascal`, `megapascal`, `gigapascal`                                                            |
+| `frequency`         | `metricFrequency`                | `kilohertz`, `megahertz`, `gigahertz`, `terahertz`, `petahertz`, `millihertz`                                      |
+| `illuminance`       | `metricIlluminance`              | `kilolux`, `millilux`, `microlux`                                                                                  |
+| `luminousIntensity` | `metricLuminousIntensity`        | `kilocandela`, `millicandela`, `microcandela`                                                                      |
+| `data`              | `dataMultiples`                  | `kilobit`/`kilobyte` … `petabit`/`petabyte` (SI), `kibibit`/`kibibyte` … `pebibit`/`pebibyte` (IEC)               |
+
+```ts
+import { metricLength, kilometer } from "measurable/dimensions";
+
+kilometer === metricLength.kilometer; // true — the named export is the same unit
+metricLength.gigameter;               // a rung not exported by name, reached via the record
+```
 
 ## Built-in measurement systems
 
@@ -92,6 +176,13 @@ usCustomary.has(foot);   // true
 metric.has(foot);        // false
 ```
 
+Membership spans every dimension: SI units (`squareMeter`, `pascal`, `watt`, `joule`,
+`hertz`, `lux`, `candela`, and their prefix ladders) are tagged into `metric`, while the
+customary ones (`squareFoot`, `acre`, `psi`, `horsepower`, `britishThermalUnit`,
+`footCandle`, `candlepower`) belong to both `imperial` and `usCustomary`. Units tied to
+no real-world standard (e.g. `atmosphere`, `torr`, and the `data` multiples) stay
+untagged — they still convert, they just won't appear under any system.
+
 ### Listing units in a system
 
 ```ts
@@ -163,9 +254,10 @@ new Quantity(1, shortTon).in(tonne); // 0.90718474
 
 Quantities can be combined. `plus`/`minus` take another `Quantity` (converted into
 the receiver's unit first, so the operands may use different units of the same
-dimension); `times`/`dividedBy` apply a dimensionless scalar, and `negate`/`abs`
-transform the magnitude. All return a **new** `Quantity` in the receiver's unit and
-leave the operands untouched.
+dimension); `times`/`dividedBy` apply a dimensionless scalar (a `number` or a
+`Rational`), and `negate`/`abs` transform the magnitude. All return a **new**
+`Quantity` in the receiver's unit and leave the operands untouched. Like
+conversions, the arithmetic is exact — `q.times(3).dividedBy(3)` returns `q`.
 
 ```ts
 import { Quantity } from "measurable";
@@ -220,8 +312,11 @@ new Quantity(1, kilometer).greaterThan(new Quantity(1, meter));  // true
 
 Short aliases: **`eq`** (`equals`), **`ne`** (`notEquals`), **`lt`** (`lessThan`),
 **`gt`** (`greaterThan`), **`lte`** (`lessThanOrEqual`), **`gte`**
-(`greaterThanOrEqual`). Equality is exact, so values differing only by
-floating-point rounding from a conversion may compare unequal.
+(`greaterThanOrEqual`). Comparison is exact rational comparison, so quantities
+that are mathematically equal compare equal even when reaching them involved a
+conversion that would have drifted in floating point — e.g.
+`new Quantity(7, liter).to(usGallon).to(liter).equals(new Quantity(7, liter))` is
+`true`.
 
 `compareTo(other)` returns `-1`, `0`, or `1`, suitable as an `Array#sort`
 comparator: `quantities.sort((a, b) => a.compareTo(b))`.
@@ -261,13 +356,35 @@ const megabyte = data.unit("megabyte", 1024 ** 2, ["MB"]);
 new Quantity(2, megabyte).in(kilobyte); // 2048
 ```
 
+A numeric `scale` is read as the exact decimal you wrote (`0.0254` → `254/10000`),
+which is exact for any terminating decimal. For a ratio a decimal **can't**
+represent exactly — e.g. `5/9` — pass a `Rational` so it stays exact:
+
+```ts
+import { Dimension, Rational } from "measurable";
+
+const ratio = new Dimension("ratio");
+ratio.base("whole");
+const third = ratio.unit("third", new Rational(1, 3)); // exact, not 0.3333…
+```
+
 ### Affine units (offset, not just scale)
 
 ```ts
+import { Dimension, Rational } from "measurable";
+
 const temperature = new Dimension("temperature");
 const kelvin = temperature.base("kelvin", ["K"]);
 // value_in_base = value * scale + offset
 const celsius = temperature.affine("celsius", { scale: 1, offset: 273.15 }, ["C"]);
+// Fahrenheit's 5/9 isn't a terminating decimal — give it (and the derived
+// offset) as exact Rationals so conversions round-trip without drift.
+const scale = new Rational(5, 9);
+const fahrenheit = temperature.affine(
+  "fahrenheit",
+  { scale, offset: Rational.from(273.15).minus(new Rational(32).times(scale)) },
+  ["F"],
+);
 ```
 
 ### Fully custom transforms
@@ -314,10 +431,11 @@ si.has(kilobyte); // true
 
 - `new Dimension(name)`
 - `.base(name, aliases?)` — define the canonical base unit
-- `.unit(name, scale, aliases?)` — linear unit (`scale` base units per unit)
-- `.affine(name, { scale, offset }, aliases?)` — linear with additive offset
-- `.custom(name, { toBase, fromBase }, aliases?)` — arbitrary inverse pair
-- `.convert(value, from, to)` — convert a raw number between two of its units
+- `.unit(name, scale, aliases?)` — linear unit (`scale` base units per unit; `number | Rational`)
+- `.affine(name, { scale, offset }, aliases?)` — linear with additive offset (each `number | Rational`)
+- `.custom(name, { toBase, fromBase }, aliases?)` — arbitrary inverse pair, for non-linear units
+- `.convert(value, from, to)` — convert a raw `number` between two of its units
+- `.convertRational(value, from, to)` → `Rational` — exact conversion between two of its units
 - `.get(token)` — units matching a name/alias (`Unit[] | undefined`)
 - `.has(unit)`, `.units`, `.baseUnit`
 
@@ -328,17 +446,20 @@ A passive handle, normally created via a dimension's builder methods rather than
 
 - `.name` — the unit's canonical name
 - `.dimension` — the `Dimension` it belongs to
+- `.linear` → `{ scale: Rational; offset: Rational } | undefined` — the exact transform for linear/affine units (`undefined` for `custom` ones)
 - `.toBase(value)` → `number` — convert a value in this unit to base units
 - `.fromBase(value)` → `number` — convert a value in base units to this unit
 
 ### `Quantity`
 
-- `new Quantity(magnitude, unit)`
+- `new Quantity(magnitude, unit)` — `magnitude` is a `number | Rational`; throws on a non-finite `number`
+- `.magnitude` → `number` — getter, derived from `.rational`
+- `.rational` → `Rational` — the exact magnitude (source of truth)
 - `.to(target)` → `Quantity`
 - `.in(target)` → `number`
 - `.toString()` → `string` — e.g. `"5 kilometer"`
 - `.plus(other)` / `.minus(other)` → `Quantity` — add/subtract another quantity (aliases: `add` / `sub`)
-- `.times(factor)` / `.dividedBy(divisor)` → `Quantity` — scale by a number (aliases: `mul` / `div`)
+- `.times(factor)` / `.dividedBy(divisor)` → `Quantity` — scale by a `number | Rational` (aliases: `mul` / `div`)
 - `.ratioTo(other)` → `number` — dimensionless ratio (how many of `other` fit in this)
 - `.negate()` / `.abs()` → `Quantity`
 - `.clamp(lower, upper)` → `Quantity` — bound to a range, in this unit
@@ -351,6 +472,23 @@ A passive handle, normally created via a dimension's builder methods rather than
 - `Quantity.min(...quantities)` / `Quantity.max(...quantities)` / `Quantity.sum(...quantities)` → `Quantity`
 - `Quantity.parse(input, dimension, { prefer? })` → `Quantity`
 
+### `Rational`
+
+An exact rational number (`n / d`), stored as `bigint`s in lowest terms with a
+positive denominator. Immutable; every operation returns a new `Rational`. Used
+internally for lossless conversions and arithmetic, but you can construct one to
+pass anywhere a magnitude or scale is accepted.
+
+- `new Rational(numerator, denominator?)` — from integers (`bigint | number`; denominator defaults to `1`). Throws on a non-integer `number` or a zero denominator.
+- `Rational.from(value)` — coerce a `number | Rational` (a `number` is read as its exact terminating decimal, e.g. `0.0254` → `254/10000`)
+- `.n` / `.d` → `bigint` — numerator and denominator
+- `.plus(other)` / `.minus(other)` / `.times(other)` / `.dividedBy(other)` → `Rational` (aliases: `add` / `sub` / `mul` / `div`)
+- `.negate()` / `.abs()` → `Rational`
+- `.equals(other)` → `boolean` (alias: `eq`)
+- `.compare(other)` → `-1 | 0 | 1`
+- `.sign()` → `-1 | 0 | 1`
+- `.toNumber()` → `number` — collapse to the nearest `number`
+
 ### `MeasurementSystem`
 
 - `new MeasurementSystem(name)`
@@ -364,6 +502,12 @@ A passive handle, normally created via a dimension's builder methods rather than
 - `UnknownUnitError` — a parsed token matches no unit
 - `AmbiguousUnitError` — a parsed token matches several units and no `prefer` was given
 
+## Changelog
+
+See [CHANGELOG.md](https://github.com/mhuggins/measurable/blob/main/CHANGELOG.md)
+for release notes. Note that v2.0.0 is a breaking release — see its entry for the
+migration details.
+
 ## License
 
 ISC

package/dist/dimensions/angle.js

@@ -2,7 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.microradian = exports.milliradian = exports.metricAngle = exports.turn = exports.gradian = exports.degree = exports.radian = exports.angle = void 0;
 const Dimension_1 = require("../lib/Dimension");
-const prefixes_1 = require("../lib/prefixes");
+const definePrefixed_1 = require("../utils/definePrefixed");
 /** Plane angle. Base unit: radian. */
 exports.angle = new Dimension_1.Dimension("angle");
 exports.radian = exports.angle.base("radian", ["rad", "radians"]);
@@ -10,5 +10,5 @@ exports.degree = exports.angle.unit("degree", Math.PI / 180, ["deg", "°", "degr
 exports.gradian = exports.angle.unit("gradian", Math.PI / 200, ["grad", "gradians"]);
 exports.turn = exports.angle.unit("turn", 2 * Math.PI, ["turns", "revolution", "revolutions"]);
 /** SI-submultiple radians (milliradian, microradian, …); larger angles use degree/turn. */
-exports.metricAngle = (0, prefixes_1.definePrefixed)(exports.angle, { name: "radian", symbol: "rad", scale: 1 }, prefixes_1.SI_SUBMULTIPLE_PREFIXES);
+exports.metricAngle = (0, definePrefixed_1.definePrefixed)(exports.angle, { name: "radian", symbol: "rad" }, definePrefixed_1.SI_SUBMULTIPLE_PREFIXES);
 exports.milliradian = exports.metricAngle.milliradian, exports.microradian = exports.metricAngle.microradian;

package/dist/dimensions/area.d.ts

@@ -0,0 +1,14 @@
+import { Dimension } from "../lib/Dimension";
+/** Area. Base unit: square meter. */
+export declare const area: Dimension;
+export declare const squareMeter: import("..").Unit;
+export declare const squareKilometer: import("..").Unit;
+export declare const hectare: import("..").Unit;
+export declare const are: import("..").Unit;
+export declare const squareCentimeter: import("..").Unit;
+export declare const squareMillimeter: import("..").Unit;
+export declare const squareInch: import("..").Unit;
+export declare const squareFoot: import("..").Unit;
+export declare const squareYard: import("..").Unit;
+export declare const acre: import("..").Unit;
+export declare const squareMile: import("..").Unit;

package/dist/dimensions/area.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.squareMile = exports.acre = exports.squareYard = exports.squareFoot = exports.squareInch = exports.squareMillimeter = exports.squareCentimeter = exports.are = exports.hectare = exports.squareKilometer = exports.squareMeter = exports.area = void 0;
+const Dimension_1 = require("../lib/Dimension");
+/** Area. Base unit: square meter. */
+exports.area = new Dimension_1.Dimension("area");
+exports.squareMeter = exports.area.base("squareMeter", ["m²", "m2", "square meter", "square meters"]);
+// Metric multiples/submultiples. Area scales as the square of the length
+// prefix, so these can't be generated by the linear SI prefix helper.
+exports.squareKilometer = exports.area.unit("squareKilometer", 1e6, ["km²", "km2"]);
+exports.hectare = exports.area.unit("hectare", 1e4, ["ha", "hectares"]);
+exports.are = exports.area.unit("are", 1e2, ["ares"]);
+exports.squareCentimeter = exports.area.unit("squareCentimeter", 1e-4, ["cm²", "cm2"]);
+exports.squareMillimeter = exports.area.unit("squareMillimeter", 1e-6, ["mm²", "mm2"]);
+// Imperial / US customary.
+exports.squareInch = exports.area.unit("squareInch", 6.4516e-4, ["sq in", "in²", "in2"]);
+exports.squareFoot = exports.area.unit("squareFoot", 9.290304e-2, [
+    "sq ft",
+    "ft²",
+    "ft2",
+    "square feet",
+]);
+exports.squareYard = exports.area.unit("squareYard", 0.83612736, ["sq yd", "yd²", "yd2"]);
+exports.acre = exports.area.unit("acre", 4046.8564224, ["ac", "acres"]);
+exports.squareMile = exports.area.unit("squareMile", 2589988.110336, ["sq mi", "mi²", "mi2"]);

package/dist/dimensions/data.d.ts

@@ -0,0 +1,10 @@
+import { Dimension } from "../lib/Dimension";
+import type { Unit } from "../lib/Unit";
+/** Digital information. Base unit: bit. */
+export declare const data: Dimension;
+export declare const bit: Unit;
+export declare const nibble: Unit;
+export declare const byte: Unit;
+/** Every SI and IEC multiple of the bit and byte, keyed by name. */
+export declare const dataMultiples: Record<string, Unit>;
+export declare const kilobit: Unit, kilobyte: Unit, megabit: Unit, megabyte: Unit, gigabit: Unit, gigabyte: Unit, terabit: Unit, terabyte: Unit, petabit: Unit, petabyte: Unit, kibibit: Unit, kibibyte: Unit, mebibit: Unit, mebibyte: Unit, gibibit: Unit, gibibyte: Unit, tebibit: Unit, tebibyte: Unit, pebibit: Unit, pebibyte: Unit;

package/dist/dimensions/data.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pebibyte = exports.pebibit = exports.tebibyte = exports.tebibit = exports.gibibyte = exports.gibibit = exports.mebibyte = exports.mebibit = exports.kibibyte = exports.kibibit = exports.petabyte = exports.petabit = exports.terabyte = exports.terabit = exports.gigabyte = exports.gigabit = exports.megabyte = exports.megabit = exports.kilobyte = exports.kilobit = exports.dataMultiples = exports.byte = exports.nibble = exports.bit = exports.data = void 0;
+const Dimension_1 = require("../lib/Dimension");
+/** Digital information. Base unit: bit. */
+exports.data = new Dimension_1.Dimension("data");
+exports.bit = exports.data.base("bit", ["b", "bits"]);
+exports.nibble = exports.data.unit("nibble", 4, ["nibbles"]);
+exports.byte = exports.data.unit("byte", 8, ["B", "bytes"]);
+// SI (decimal, 1000-based) and IEC (binary, 1024-based) multiples of the bit
+// and byte. SI uses the bare symbol (kb, kB); IEC uses the "i" infix (Kib, KiB).
+const SI_MULTIPLES = [
+    ["kilo", "k", 1e3],
+    ["mega", "M", 1e6],
+    ["giga", "G", 1e9],
+    ["tera", "T", 1e12],
+    ["peta", "P", 1e15],
+];
+const IEC_MULTIPLES = [
+    ["kibi", "Ki", 2 ** 10],
+    ["mebi", "Mi", 2 ** 20],
+    ["gibi", "Gi", 2 ** 30],
+    ["tebi", "Ti", 2 ** 40],
+    ["pebi", "Pi", 2 ** 50],
+];
+const multiples = {};
+for (const [prefix, symbol, factor] of [...SI_MULTIPLES, ...IEC_MULTIPLES]) {
+    multiples[`${prefix}bit`] = exports.data.unit(`${prefix}bit`, factor, [`${symbol}b`, `${prefix}bits`]);
+    multiples[`${prefix}byte`] = exports.data.unit(`${prefix}byte`, 8 * factor, [
+        `${symbol}B`,
+        `${prefix}bytes`,
+    ]);
+}
+/** Every SI and IEC multiple of the bit and byte, keyed by name. */
+exports.dataMultiples = multiples;
+exports.kilobit = multiples.kilobit, exports.kilobyte = multiples.kilobyte, exports.megabit = multiples.megabit, exports.megabyte = multiples.megabyte, exports.gigabit = multiples.gigabit, exports.gigabyte = multiples.gigabyte, exports.terabit = multiples.terabit, exports.terabyte = multiples.terabyte, exports.petabit = multiples.petabit, exports.petabyte = multiples.petabyte, exports.kibibit = multiples.kibibit, exports.kibibyte = multiples.kibibyte, exports.mebibit = multiples.mebibit, exports.mebibyte = multiples.mebibyte, exports.gibibit = multiples.gibibit, exports.gibibyte = multiples.gibibyte, exports.tebibit = multiples.tebibit, exports.tebibyte = multiples.tebibyte, exports.pebibit = multiples.pebibit, exports.pebibyte = multiples.pebibyte;

package/dist/dimensions/energy.d.ts

@@ -0,0 +1,14 @@
+import { Dimension } from "../lib/Dimension";
+/** Energy. Base unit: joule. */
+export declare const energy: Dimension;
+export declare const joule: import("..").Unit;
+export declare const calorie: import("..").Unit;
+export declare const kilocalorie: import("..").Unit;
+export declare const britishThermalUnit: import("..").Unit;
+export declare const wattHour: import("..").Unit;
+/** Every SI-prefixed joule (kilojoule, megajoule, millijoule, …), keyed by name. */
+export declare const metricEnergy: Record<string, import("..").Unit>;
+export declare const kilojoule: import("..").Unit, megajoule: import("..").Unit, gigajoule: import("..").Unit, millijoule: import("..").Unit;
+/** Every SI-prefixed watt-hour (kilowatt-hour, megawatt-hour, …), keyed by name. */
+export declare const metricWattHour: Record<string, import("..").Unit>;
+export declare const kilowattHour: import("..").Unit, megawattHour: import("..").Unit, gigawattHour: import("..").Unit;

package/dist/dimensions/energy.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.gigawattHour = exports.megawattHour = exports.kilowattHour = exports.metricWattHour = exports.millijoule = exports.gigajoule = exports.megajoule = exports.kilojoule = exports.metricEnergy = exports.wattHour = exports.britishThermalUnit = exports.kilocalorie = exports.calorie = exports.joule = exports.energy = void 0;
+const Dimension_1 = require("../lib/Dimension");
+const definePrefixed_1 = require("../utils/definePrefixed");
+/** Energy. Base unit: joule. */
+exports.energy = new Dimension_1.Dimension("energy");
+exports.joule = exports.energy.base("joule", ["J", "joules"]);
+exports.calorie = exports.energy.unit("calorie", 4.184, ["cal", "calories"]);
+exports.kilocalorie = exports.energy.unit("kilocalorie", 4184, ["kcal", "Cal", "kilocalories"]);
+exports.britishThermalUnit = exports.energy.unit("britishThermalUnit", 1055.05585262, ["BTU", "Btu"]);
+exports.wattHour = exports.energy.unit("wattHour", 3600, ["Wh", "watt-hour", "watt-hours"]);
+/** Every SI-prefixed joule (kilojoule, megajoule, millijoule, …), keyed by name. */
+exports.metricEnergy = (0, definePrefixed_1.definePrefixed)(exports.energy, { name: "joule", symbol: "J" });
+exports.kilojoule = exports.metricEnergy.kilojoule, exports.megajoule = exports.metricEnergy.megajoule, exports.gigajoule = exports.metricEnergy.gigajoule, exports.millijoule = exports.metricEnergy.millijoule;
+/** Every SI-prefixed watt-hour (kilowatt-hour, megawatt-hour, …), keyed by name. */
+exports.metricWattHour = (0, definePrefixed_1.definePrefixed)(exports.energy, {
+    name: "wattHour",
+    symbol: "Wh",
+    scale: 3600,
+});
+exports.kilowattHour = exports.metricWattHour.kilowattHour, exports.megawattHour = exports.metricWattHour.megawattHour, exports.gigawattHour = exports.metricWattHour.gigawattHour;

package/dist/dimensions/force.js

@@ -2,7 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.micronewton = exports.millinewton = exports.kilonewton = exports.meganewton = exports.metricForce = exports.kilogramForce = exports.poundForce = exports.dyne = exports.newton = exports.force = void 0;
 const Dimension_1 = require("../lib/Dimension");
-const prefixes_1 = require("../lib/prefixes");
+const definePrefixed_1 = require("../utils/definePrefixed");
 /** Force. Base unit: newton. */
 exports.force = new Dimension_1.Dimension("force");
 exports.newton = exports.force.base("newton", ["N", "newtons"]);
@@ -10,5 +10,5 @@ exports.dyne = exports.force.unit("dyne", 0.00001, ["dyn", "dynes"]);
 exports.poundForce = exports.force.unit("poundForce", 4.4482216152605, ["lbf"]);
 exports.kilogramForce = exports.force.unit("kilogramForce", 9.80665, ["kgf"]);
 /** Every SI-prefixed newton (kilonewton, meganewton, millinewton, …), keyed by name. */
-exports.metricForce = (0, prefixes_1.definePrefixed)(exports.force, { name: "newton", symbol: "N", scale: 1 });
+exports.metricForce = (0, definePrefixed_1.definePrefixed)(exports.force, { name: "newton", symbol: "N" });
 exports.meganewton = exports.metricForce.meganewton, exports.kilonewton = exports.metricForce.kilonewton, exports.millinewton = exports.metricForce.millinewton, exports.micronewton = exports.metricForce.micronewton;

package/dist/dimensions/frequency.d.ts

@@ -0,0 +1,7 @@
+import { Dimension } from "../lib/Dimension";
+/** Frequency. Base unit: hertz. */
+export declare const frequency: Dimension;
+export declare const hertz: import("..").Unit;
+/** Every SI-prefixed hertz (kilohertz, megahertz, gigahertz, …), keyed by name. */
+export declare const metricFrequency: Record<string, import("..").Unit>;
+export declare const kilohertz: import("..").Unit, megahertz: import("..").Unit, gigahertz: import("..").Unit, terahertz: import("..").Unit, petahertz: import("..").Unit, millihertz: import("..").Unit;

package/dist/dimensions/frequency.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.millihertz = exports.petahertz = exports.terahertz = exports.gigahertz = exports.megahertz = exports.kilohertz = exports.metricFrequency = exports.hertz = exports.frequency = void 0;
+const Dimension_1 = require("../lib/Dimension");
+const definePrefixed_1 = require("../utils/definePrefixed");
+/** Frequency. Base unit: hertz. */
+exports.frequency = new Dimension_1.Dimension("frequency");
+exports.hertz = exports.frequency.base("hertz", ["Hz"]);
+/** Every SI-prefixed hertz (kilohertz, megahertz, gigahertz, …), keyed by name. */
+exports.metricFrequency = (0, definePrefixed_1.definePrefixed)(exports.frequency, { name: "hertz", symbol: "Hz" });
+exports.kilohertz = exports.metricFrequency.kilohertz, exports.megahertz = exports.metricFrequency.megahertz, exports.gigahertz = exports.metricFrequency.gigahertz, exports.terahertz = exports.metricFrequency.terahertz, exports.petahertz = exports.metricFrequency.petahertz, exports.millihertz = exports.metricFrequency.millihertz;

package/dist/dimensions/illuminance.d.ts

@@ -0,0 +1,9 @@
+import { Dimension } from "../lib/Dimension";
+/** Illuminance. Base unit: lux. */
+export declare const illuminance: Dimension;
+export declare const lux: import("..").Unit;
+export declare const footCandle: import("..").Unit;
+export declare const phot: import("..").Unit;
+/** Every SI-prefixed lux (kilolux, millilux, microlux, …), keyed by name. */
+export declare const metricIlluminance: Record<string, import("..").Unit>;
+export declare const kilolux: import("..").Unit, millilux: import("..").Unit, microlux: import("..").Unit;