measurable 1.1.1 → 3.0.0

package/CHANGELOG.md

@@ -0,0 +1,149 @@
+# 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).
+
+## [3.0.0] - 2026-06-18
+
+This release adds value **formatting**. Units now carry a `symbol` and `plural`,
+and a `Quantity` can render itself with magnitude-aware pluralization and
+locale-aware number formatting. Threading symbol/plural through the unit builders
+changes their signatures, hence the major bump.
+
+### Breaking
+
+- **Unit builder methods take a `UnitDef` object instead of an aliases array.**
+  `Dimension.base` / `unit` / `affine` / `custom` now accept
+  `{ symbol?, plural?, aliases? }` as their final argument rather than a bare
+  `string[]` of aliases. Migrate `length.unit("inch", 0.0254, ["in", "inches"])`
+  to `length.unit("inch", 0.0254, { symbol: "in", plural: "inches" })`; plain
+  aliases still work via the `aliases` field.
+- **`definePrefixed` takes the reference `Unit`, not a descriptor object.**
+  `definePrefixed(length, { name: "meter", symbol: "m" })` becomes
+  `definePrefixed(length, meter)` — it reads the name, symbol, and exact scale
+  straight off the unit. The `PrefixReference` type is removed.
+- **`Unit`'s constructor options gained `symbol` / `plural`.** Only affects code
+  that calls `new Unit(...)` directly; units built through a `Dimension` are
+  unaffected.
+
+### Added
+
+- **`Unit.symbol` and `Unit.plural`** — optional, first-class descriptors. Both
+  are also registered as parse tokens, so `Quantity.parse` accepts e.g. `"5 g"`
+  and `"5 grams"`.
+- **`Quantity.format(options?)`** — renders `"<magnitude> <label>"`. `unit`
+  selects the label: `"auto"` (default — singular `name` at ±1, otherwise
+  `plural`), `"name"`, `"plural"`, or `"symbol"`, each falling back to `name`
+  when unset. The magnitude is rendered with `toLocaleString`; pass `locale`
+  and/or `numberFormat` (`Intl.NumberFormatOptions`) for locale- and
+  precision-aware output.
+- **`Quantity.formatParts(options?)`** — the same options as `format`, but
+  returns the rendered `{ magnitude, unit }` as separate strings for custom
+  assembly (e.g. JSX).
+- **`definePrefixed` derives each variant's `symbol` and `plural`** from the
+  reference unit (e.g. `meter` → `kilometer` / `km`), keeping the prefixed scale
+  exact via rational arithmetic.
+- New exported types: `UnitDef`, `FormatOptions`, `FormattedParts`,
+  `BaseUnitOptions`, `UnitConversionOptions`, and `UnitOptions`.
+
+### Changed
+
+- Added `assert-never` as a (small) runtime dependency, used for exhaustiveness
+  checking in formatting.
+
+## [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.
+
+[3.0.0]: https://github.com/mhuggins/measurable/compare/v2.0.0...v3.0.0
+[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
@@ -115,9 +206,65 @@ metric.express(new Quantity(5000, meter));    // Quantity(5, kilometer)
 imperial.express(new Quantity(5000, meter));  // Quantity(3.107…, mile)
 ```
 
-A `Quantity` also has a `toString()` that renders `"<magnitude> <unit name>"`
-(e.g. `new Quantity(5, kilometer).toString()` → `"5 kilometer"`), and `round(decimals)`
-to trim the magnitude for display (`new Quantity(1.6213, mile).round(2)` → `1.62 mile`).
+## Formatting output
+
+Each unit carries a canonical `symbol` (`"g"`, `"km"`, `"°C"`) and `plural`
+(`"grams"`, `"kilometers"`) alongside its `name`, so a `Quantity` can be rendered the
+way you want:
+
+```ts
+import { Quantity } from "measurable";
+import { gram } from "measurable/dimensions";
+
+new Quantity(5, gram).toString();                 // "5 gram"   (always the bare name)
+new Quantity(5, gram).format();                   // "5 grams"  (magnitude-aware)
+new Quantity(1, gram).format();                   // "1 gram"   (singular at ±1)
+new Quantity(5, gram).format({ unit: "symbol" }); // "5 g"
+new Quantity(5, gram).format({ unit: "name" });   // "5 gram"
+new Quantity(5, gram).format({ unit: "plural" }); // "5 grams"
+
+// Localize the magnitude with locale / numberFormat (passed to toLocaleString):
+new Quantity(1234.5, meter).format({ locale: "de-DE" });                             // "1.234,5 meters"
+new Quantity(1.23456, meter).format({ numberFormat: { maximumFractionDigits: 2 } }); // "1.23 meters"
+new Quantity(1234.5, kilometer).format({ locale: "de-DE", unit: "symbol" });         // "1.234,5 km"
+```
+
+`toString()` is intentionally stable (`"<magnitude> <name>"`). `format(options?)` is the
+flexible one: `unit` defaults to `"auto"` (singular `name` at ±1, otherwise `plural`) and
+accepts `"name"`, `"plural"`, or `"symbol"`. When a unit has no `symbol`/`plural`, those
+modes fall back to its `name`.
+
+The magnitude is rendered with `Number.prototype.toLocaleString`. Pass `locale` (a BCP 47
+locale or array) and/or `numberFormat` (`Intl.NumberFormatOptions` — precision via
+`maximumFractionDigits`, grouping, `style`, …) to control it; with neither set, the
+runtime's default locale is used. Use `round(decimals)` to trim the magnitude first
+(`new Quantity(1.6213, mile).round(2)` → `1.62 mile`).
+
+When a single string won't do — e.g. styling the magnitude in a React component — use
+`formatParts(options?)`, which takes the same options but returns the rendered
+`{ magnitude, unit }` as separate strings for you to assemble:
+
+```tsx
+const { magnitude, unit } = new Quantity(1234.5, kilometer).formatParts({ locale: "de-DE" });
+// { magnitude: "1.234,5", unit: "kilometers" }
+return <><b>{magnitude}</b> {unit}</>;
+```
+
+### Internationalization
+
+`format()` localizes the **magnitude** (via `locale`/`numberFormat`), but the **label** it
+appends — `symbol`/`plural` — is **English/canonical** convenience data, not a localization
+system: a single plural string can't model languages with several plural forms, and the
+names themselves are English. For a fully localized label, delegate to `Intl.NumberFormat`,
+whose `style: "unit"` localizes **and** pluralizes a curated set of units for you:
+
+```ts
+const q = new Quantity(5, kilometer);
+new Intl.NumberFormat("de", { style: "unit", unit: "kilometer" }).format(q.magnitude);
+// "5 Kilometer"
+new Intl.NumberFormat("fr", { style: "unit", unit: "kilometer", unitDisplay: "short" })
+  .format(q.magnitude); // "5 km"
+```
 
 ## Parsing strings
 
@@ -163,9 +310,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 +368,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))`.
@@ -248,26 +399,55 @@ b.clamp(a, new Quantity(2, kilometer)); // b bounded to [a, 2 km], in b's unit
 ## Defining your own units
 
 Create a `Dimension` and add units through its builder methods. `scale` is how
-many base units make up one of the unit being defined.
+many base units make up one of the unit being defined. The optional final argument
+is a definition object — `{ symbol?, plural?, aliases? }` — whose `symbol` and
+`plural` feed `format()` and, like `aliases`, are also registered for parsing.
 
 ```ts
 import { Dimension, Quantity } from "measurable";
 
 const data = new Dimension("data");
-const byte = data.base("byte", ["B", "bytes"]); // the base unit (identity)
-const kilobyte = data.unit("kilobyte", 1024, ["KB"]);
-const megabyte = data.unit("megabyte", 1024 ** 2, ["MB"]);
+const byte = data.base("byte", { symbol: "B", plural: "bytes" }); // base unit (identity)
+const kilobyte = data.unit("kilobyte", 1024, { symbol: "KB", plural: "kilobytes" });
+const megabyte = data.unit("megabyte", 1024 ** 2, { symbol: "MB", plural: "megabytes" });
+
+new Quantity(2, megabyte).in(kilobyte);      // 2048
+new Quantity(2, megabyte).format();          // "2 megabytes"
+new Quantity(2, megabyte).format({ unit: "symbol" }); // "2 MB"
+```
+
+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:
 
-new Quantity(2, megabyte).in(kilobyte); // 2048
+```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"]);
+const kelvin = temperature.base("kelvin", { symbol: "K" });
 // value_in_base = value * scale + offset
-const celsius = temperature.affine("celsius", { scale: 1, offset: 273.15 }, ["C"]);
+const celsius = temperature.affine("celsius", { scale: 1, offset: 273.15 }, {
+  symbol: "°C",
+  aliases: ["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)) },
+  { symbol: "°F", aliases: ["F"] },
+);
 ```
 
 ### Fully custom transforms
@@ -285,18 +465,22 @@ dim.custom("squared", {
 
 ### Generating SI prefixes
 
-`definePrefixed` adds the metric prefix ladder to a reference unit and returns the
-created units keyed by name (skipping any name that already exists). Pass
-`SI_SUBMULTIPLE_PREFIXES` to generate fractions only.
+`definePrefixed` adds the metric prefix ladder to a reference **unit** and returns the
+created units keyed by name (skipping any name that already exists). It reads the
+reference's `name`, `symbol`, and scale straight off the unit (via `scaleOf`), so each
+generated unit gets a derived symbol (`b` → `kb`) and plural too — even when the
+reference isn't the base unit. Pass `SI_SUBMULTIPLE_PREFIXES` to generate fractions only.
 
 ```ts
 import { Dimension, Quantity, definePrefixed } from "measurable";
 
 const data = new Dimension("data");
-const bit = data.base("bit", ["b"]);
-const prefixed = definePrefixed(data, { name: "bit", symbol: "b", scale: 1 });
+const bit = data.base("bit", { symbol: "b", plural: "bits" });
+const prefixed = definePrefixed(data, bit);
 
-new Quantity(1, prefixed.kilobit).in(bit); // 1000  (SI kilo = 1e3)
+new Quantity(1, prefixed.kilobit).in(bit);   // 1000  (SI kilo = 1e3)
+prefixed.kilobit.symbol;                     // "kb"
+new Quantity(5, prefixed.kilobit).format({ unit: "symbol" }); // "5 kb"
 ```
 
 ### Tagging units into a measurement system
@@ -313,32 +497,43 @@ si.has(kilobyte); // true
 ### `Dimension`
 
 - `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
+- `.base(name, def?)` — define the canonical base unit
+- `.unit(name, scale, def?)` — linear unit (`scale` base units per unit; `number | Rational`)
+- `.affine(name, { scale, offset }, def?)` — linear with additive offset (each `number | Rational`)
+- `.custom(name, { toBase, fromBase }, def?)` — 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`
 
+`def` is an optional `UnitDef`: `{ symbol?, plural?, aliases? }`. All three are
+registered as parse tokens; `symbol`/`plural` are additionally stored on the `Unit`.
+
 ### `Unit`
 
 A passive handle, normally created via a dimension's builder methods rather than
 `new Unit` directly. Read-only properties:
 
 - `.name` — the unit's canonical name
+- `.symbol?` — canonical symbol (e.g. `"g"`, `"km"`), if declared
+- `.plural?` — plural name (e.g. `"grams"`), if declared
 - `.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"`
+- `.toString()` → `string` — stable `"<magnitude> <name>"`, e.g. `"5 kilometer"`
+- `.format({ unit?, locale?, numberFormat? })` → `string` — `unit`: `"auto"` (default, magnitude-aware) / `"name"` / `"plural"` / `"symbol"`; `locale` + `numberFormat` localize the magnitude via `toLocaleString`
+- `.formatParts(options?)` → `{ magnitude, unit }` — same options as `.format`, but returns the rendered pieces separately for custom assembly (e.g. JSX)
 - `.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 +546,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 +576,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,13 +2,20 @@
 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"]);
-exports.degree = exports.angle.unit("degree", Math.PI / 180, ["deg", "°", "degrees"]);
-exports.gradian = exports.angle.unit("gradian", Math.PI / 200, ["grad", "gradians"]);
-exports.turn = exports.angle.unit("turn", 2 * Math.PI, ["turns", "revolution", "revolutions"]);
+exports.radian = exports.angle.base("radian", { symbol: "rad", plural: "radians" });
+exports.degree = exports.angle.unit("degree", Math.PI / 180, {
+    symbol: "°",
+    plural: "degrees",
+    aliases: ["deg"],
+});
+exports.gradian = exports.angle.unit("gradian", Math.PI / 200, { symbol: "grad", plural: "gradians" });
+exports.turn = exports.angle.unit("turn", 2 * Math.PI, {
+    plural: "turns",
+    aliases: ["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, exports.radian, definePrefixed_1.SI_SUBMULTIPLE_PREFIXES);
 exports.milliradian = exports.metricAngle.milliradian, exports.microradian = exports.metricAngle.microradian;