measurable 3.0.0 → 3.1.0

package/CHANGELOG.md

@@ -5,6 +5,40 @@ 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.1.0] - 2026-06-19
+
+This release adds a best-fit primitive and gives every thrown error a dedicated,
+catchable class. All changes are backward-compatible.
+
+### Added
+
+- **`Quantity.best(...units)`** — re-expresses a quantity in the best-fit unit
+  among the given ones: the largest unit whose absolute magnitude is still ≥ 1
+  (falling back to the smallest). Candidate order doesn't matter; each must
+  belong to the quantity's dimension.
+- **Dedicated error classes**, all extending `Error` and exported from
+  `measurable`, so failures can be branched on with `instanceof`:
+  `ArgumentError` (invalid argument — e.g. `best()` with no units, or a
+  non-integer / zero-denominator / non-finite `Rational`), `ParseError` (a string
+  could not be parsed into a quantity), `DuplicateUnitError` (a unit name already
+  exists in its dimension), and `UnsupportedDimensionError` (a measurement system
+  has no units of a dimension to `express` in).
+
+### Changed
+
+- **`MeasurementSystem.express` now delegates to `Quantity.best`** — same
+  behavior, with the best-fit logic living in one place.
+- **Every previously bare `throw new Error` now throws a dedicated class.**
+  Messages are unchanged and all classes extend `Error`, so existing `catch`
+  blocks keep working.
+
+### Deprecated
+
+- **`InvalidConversionError` is renamed to `DimensionMismatchError`** — it is
+  thrown for any cross-dimension operation (converting, comparing, or combining
+  units), not just conversions. The old name remains exported as a deprecated
+  alias of the same class and still works with `instanceof`.
+
 ## [3.0.0] - 2026-06-18
 
 This release adds value **formatting**. Units now carry a `symbol` and `plural`,
@@ -142,6 +176,7 @@ to a `number` at the edge, so `foot → inch` is exactly `12` (not
   `MeasurementSystem`), string parsing via `Quantity.parse`, and the first set
   of built-in dimensions and measurement systems.
 
+[3.1.0]: https://github.com/mhuggins/measurable/compare/v3.0.0...v3.1.0
 [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

package/README.md

@@ -206,6 +206,25 @@ metric.express(new Quantity(5000, meter));    // Quantity(5, kilometer)
 imperial.express(new Quantity(5000, meter));  // Quantity(3.107…, mile)
 ```
 
+Under the hood, `express` just hands the system's units for that dimension to
+`Quantity.best`, the same best-fit primitive you can call directly with whatever
+units you like — handy when you want a custom shortlist rather than a whole
+system. `best` picks the largest unit whose absolute magnitude is still ≥ 1
+(falling back to the smallest when even that rounds below 1), so candidate order
+doesn't matter:
+
+```ts
+import { Quantity } from "measurable";
+import { meter, kilometer, mile } from "measurable/dimensions";
+
+new Quantity(5000, meter).best(meter, kilometer, mile);  // Quantity(3.107…, mile)
+new Quantity(1500, meter).best(meter, kilometer);        // Quantity(1.5, kilometer)
+new Quantity(500, meter).best(kilometer, mile);          // Quantity(0.5, kilometer) — smallest fallback
+```
+
+It requires at least one unit, and each must belong to the quantity's dimension
+(otherwise `DimensionMismatchError`).
+
 ## Formatting output
 
 Each unit carries a canonical `symbol` (`"g"`, `"km"`, `"°C"`) and `plural`
@@ -328,7 +347,7 @@ new Quantity(6, mile).dividedBy(2);                      // Quantity(3, mile)
 Short aliases are available: **`add`** (`plus`), **`sub`** (`minus`), **`mul`**
 (`times`), **`div`** (`dividedBy`).
 
-Combining different dimensions throws `InvalidConversionError`. Note that adding
+Combining different dimensions throws `DimensionMismatchError`. Note that adding
 **affine** units (e.g. temperatures) is mathematically defined but physically
 questionable, since it adds absolute points rather than a difference.
 
@@ -349,13 +368,13 @@ This is different from `.in(unit)`: `.in(milliliter)` only uses the *unit* on th
 right (giving `2000`), whereas `ratioTo` also uses the other quantity's
 **magnitude** (the `250`), so it answers "how many of *that quantity* fit in this
 one." It's the inverse of scalar `times` — `b.times(a.ratioTo(b))` reconstructs
-`a`. Comparing different dimensions throws `InvalidConversionError`.
+`a`. Comparing different dimensions throws `DimensionMismatchError`.
 
 ## Comparison
 
 `equals`/`notEquals`/`lessThan`/`greaterThan`/`lessThanOrEqual`/`greaterThanOrEqual`
 compare two quantities (the other is converted into the receiver's unit first),
-returning a boolean. Comparing different dimensions throws `InvalidConversionError`.
+returning a boolean. Comparing different dimensions throws `DimensionMismatchError`.
 
 ```ts
 import { Quantity } from "measurable";
@@ -381,7 +400,7 @@ comparator: `quantities.sort((a, b) => a.compareTo(b))`.
 
 `Quantity.min`/`max`/`sum` aggregate several quantities at once; `clamp` is an
 instance method that bounds one quantity to a range. Each converts operands as
-needed, so mixing dimensions throws `InvalidConversionError`.
+needed, so mixing dimensions throws `DimensionMismatchError`.
 
 ```ts
 import { Quantity } from "measurable";
@@ -538,6 +557,7 @@ A passive handle, normally created via a dimension's builder methods rather than
 - `.negate()` / `.abs()` → `Quantity`
 - `.clamp(lower, upper)` → `Quantity` — bound to a range, in this unit
 - `.round(decimals?)` → `Quantity` — round the magnitude (default 0 decimals)
+- `.best(...units)` → `Quantity` — re-express in the largest given unit whose absolute magnitude is still ≥ 1 (smallest as fallback); needs ≥ 1 unit, all of this dimension
 - `.equals(other)` / `.notEquals(other)` → `boolean` (aliases: `eq` / `ne`)
 - `.lessThan(other)` / `.greaterThan(other)` → `boolean` (aliases: `lt` / `gt`)
 - `.lessThanOrEqual(other)` / `.greaterThanOrEqual(other)` → `boolean` (aliases: `lte` / `gte`)
@@ -572,9 +592,17 @@ pass anywhere a magnitude or scale is accepted.
 
 ### Errors
 
-- `InvalidConversionError` — units are from different dimensions
+All extend the built-in `Error` (so existing `catch` blocks still catch them) and
+are exported from `measurable`, letting you branch on the failure with
+`instanceof`:
+
+- `DimensionMismatchError` — an operation was attempted on units from different dimensions (converting, comparing, or combining them). Exported as `InvalidConversionError` too, a deprecated alias of the same class.
 - `UnknownUnitError` — a parsed token matches no unit
 - `AmbiguousUnitError` — a parsed token matches several units and no `prefer` was given
+- `ParseError` — a string could not be parsed into a quantity at all
+- `DuplicateUnitError` — a unit name already exists in its dimension
+- `UnsupportedDimensionError` — a system has no units of a dimension to `express` in
+- `ArgumentError` — an argument was invalid (e.g. `best()` with no units, or a non-integer / zero-denominator / non-finite `Rational`)
 
 ## Changelog
 

package/dist/errors/AmbiguousUnitError.js

@@ -4,8 +4,7 @@ exports.AmbiguousUnitError = void 0;
 class AmbiguousUnitError extends Error {
     constructor(token, candidates) {
         const names = candidates.map((unit) => unit.name).join(", ");
-        super(`Ambiguous unit "${token}": matches ${names}. ` +
-            `Pass a preferred measurement system to disambiguate.`);
+        super(`Ambiguous unit "${token}": matches ${names}. Pass a preferred measurement system to disambiguate.`);
     }
 }
 exports.AmbiguousUnitError = AmbiguousUnitError;

package/dist/errors/ArgumentError.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Thrown when a caller passes an invalid argument — an empty required list, a
+ * value outside an allowed range, a wrong numeric type, and so on. Signals a
+ * mistake in the calling code rather than a recoverable runtime condition.
+ */
+export declare class ArgumentError extends Error {
+}

package/dist/errors/ArgumentError.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ArgumentError = void 0;
+/**
+ * Thrown when a caller passes an invalid argument — an empty required list, a
+ * value outside an allowed range, a wrong numeric type, and so on. Signals a
+ * mistake in the calling code rather than a recoverable runtime condition.
+ */
+class ArgumentError extends Error {
+}
+exports.ArgumentError = ArgumentError;

package/dist/errors/DimensionMismatchError.d.ts

@@ -0,0 +1,13 @@
+import type { Unit } from "../lib/Unit";
+/**
+ * Thrown when an operation is attempted on two units from different dimensions —
+ * converting, comparing, or combining them (e.g. `meter` and `liter`). Such
+ * units are dimensionally incompatible, so the operation has no meaning.
+ */
+export declare class DimensionMismatchError extends Error {
+    constructor(from: Unit, to: Unit);
+}
+/** @deprecated Renamed to {@link DimensionMismatchError}. */
+export declare const InvalidConversionError: typeof DimensionMismatchError;
+/** @deprecated Renamed to {@link DimensionMismatchError}. */
+export type InvalidConversionError = DimensionMismatchError;

package/dist/errors/DimensionMismatchError.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InvalidConversionError = exports.DimensionMismatchError = void 0;
+/**
+ * Thrown when an operation is attempted on two units from different dimensions —
+ * converting, comparing, or combining them (e.g. `meter` and `liter`). Such
+ * units are dimensionally incompatible, so the operation has no meaning.
+ */
+class DimensionMismatchError extends Error {
+    constructor(from, to) {
+        super(`Invalid conversion: ${from.name} to ${to.name}`);
+    }
+}
+exports.DimensionMismatchError = DimensionMismatchError;
+/** @deprecated Renamed to {@link DimensionMismatchError}. */
+exports.InvalidConversionError = DimensionMismatchError;

package/dist/errors/DuplicateUnitError.d.ts

@@ -0,0 +1,5 @@
+import type { Dimension } from "../lib/Dimension";
+/** Thrown when defining a unit whose name already exists in its dimension. */
+export declare class DuplicateUnitError extends Error {
+    constructor(name: string, dimension: Dimension);
+}

package/dist/errors/DuplicateUnitError.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DuplicateUnitError = void 0;
+/** Thrown when defining a unit whose name already exists in its dimension. */
+class DuplicateUnitError extends Error {
+    constructor(name, dimension) {
+        super(`Duplicate unit name "${name}" in dimension "${dimension.name}"`);
+    }
+}
+exports.DuplicateUnitError = DuplicateUnitError;

package/dist/errors/ParseError.d.ts

@@ -0,0 +1,4 @@
+/** Thrown when a string can't be parsed into a quantity (no magnitude/unit found). */
+export declare class ParseError extends Error {
+    constructor(input: string);
+}

package/dist/errors/ParseError.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ParseError = void 0;
+/** Thrown when a string can't be parsed into a quantity (no magnitude/unit found). */
+class ParseError extends Error {
+    constructor(input) {
+        super(`Could not parse a quantity from "${input}"`);
+    }
+}
+exports.ParseError = ParseError;

package/dist/errors/UnsupportedDimensionError.d.ts

@@ -0,0 +1,10 @@
+import type { Dimension } from "../lib/Dimension";
+import type { MeasurementSystem } from "../lib/MeasurementSystem";
+/**
+ * Thrown when a measurement system is asked to express a quantity in a dimension
+ * for which it has no units (e.g. an imperial-only system and a metric-only
+ * dimension).
+ */
+export declare class UnsupportedDimensionError extends Error {
+    constructor(system: MeasurementSystem, dimension: Dimension);
+}

package/dist/errors/UnsupportedDimensionError.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UnsupportedDimensionError = void 0;
+/**
+ * Thrown when a measurement system is asked to express a quantity in a dimension
+ * for which it has no units (e.g. an imperial-only system and a metric-only
+ * dimension).
+ */
+class UnsupportedDimensionError extends Error {
+    constructor(system, dimension) {
+        super(`Measurement system "${system.name}" has no "${dimension.name}" units to express in`);
+    }
+}
+exports.UnsupportedDimensionError = UnsupportedDimensionError;

package/dist/index.d.ts

@@ -1,6 +1,10 @@
 export * from "./errors/AmbiguousUnitError";
-export * from "./errors/InvalidConversionError";
+export * from "./errors/ArgumentError";
+export * from "./errors/DimensionMismatchError";
+export * from "./errors/DuplicateUnitError";
+export * from "./errors/ParseError";
 export * from "./errors/UnknownUnitError";
+export * from "./errors/UnsupportedDimensionError";
 export * from "./lib/Dimension";
 export * from "./lib/MeasurementSystem";
 export * from "./lib/Quantity";

package/dist/index.js

@@ -15,8 +15,12 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./errors/AmbiguousUnitError"), exports);
-__exportStar(require("./errors/InvalidConversionError"), exports);
+__exportStar(require("./errors/ArgumentError"), exports);
+__exportStar(require("./errors/DimensionMismatchError"), exports);
+__exportStar(require("./errors/DuplicateUnitError"), exports);
+__exportStar(require("./errors/ParseError"), exports);
 __exportStar(require("./errors/UnknownUnitError"), exports);
+__exportStar(require("./errors/UnsupportedDimensionError"), exports);
 __exportStar(require("./lib/Dimension"), exports);
 __exportStar(require("./lib/MeasurementSystem"), exports);
 __exportStar(require("./lib/Quantity"), exports);

package/dist/lib/Dimension.js

@@ -1,7 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Dimension = void 0;
-const InvalidConversionError_1 = require("../errors/InvalidConversionError");
+const DimensionMismatchError_1 = require("../errors/DimensionMismatchError");
+const DuplicateUnitError_1 = require("../errors/DuplicateUnitError");
 const Rational_1 = require("./Rational");
 const Unit_1 = require("./Unit");
 /** The rational `0`. */
@@ -79,7 +80,7 @@ class Dimension {
      */
     convertRational(value, from, to) {
         if (!this.units.has(from) || !this.units.has(to)) {
-            throw new InvalidConversionError_1.InvalidConversionError(from, to);
+            throw new DimensionMismatchError_1.DimensionMismatchError(from, to);
         }
         if (from === to) {
             return value;
@@ -105,7 +106,7 @@ class Dimension {
     define(name, { symbol, plural, aliases = [] }, transform) {
         for (const existing of this.units) {
             if (existing.name === name) {
-                throw new Error(`Duplicate unit name "${name}" in dimension "${this.name}"`);
+                throw new DuplicateUnitError_1.DuplicateUnitError(name, this);
             }
         }
         const unit = new Unit_1.Unit({ name, dimension: this, symbol, plural, ...transform });

package/dist/lib/MeasurementSystem.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MeasurementSystem = void 0;
-const scaleOf_1 = require("../utils/scaleOf");
+const UnsupportedDimensionError_1 = require("../errors/UnsupportedDimensionError");
 /**
  * A measurement system (metric, imperial, US customary, …) is a cross-dimension
  * collection of units that share a real-world standard.
@@ -37,22 +37,11 @@ class MeasurementSystem {
      * to the smallest unit when even that rounds below 1).
      */
     express(quantity) {
-        const candidates = this.in(quantity.unit.dimension).sort((a, b) => (0, scaleOf_1.scaleOf)(a) - (0, scaleOf_1.scaleOf)(b));
+        const candidates = this.in(quantity.unit.dimension);
         if (candidates.length === 0) {
-            throw new Error(`Measurement system "${this.name}" has no ` +
-                `"${quantity.unit.dimension.name}" units to express in`);
+            throw new UnsupportedDimensionError_1.UnsupportedDimensionError(this, quantity.unit.dimension);
         }
-        const base = quantity.unit.toBase(quantity.magnitude);
-        let chosen = candidates[0];
-        for (const unit of candidates) {
-            if (Math.abs(unit.fromBase(base)) >= 1) {
-                chosen = unit;
-            }
-            else {
-                break;
-            }
-        }
-        return quantity.to(chosen);
+        return quantity.best(...candidates);
     }
 }
 exports.MeasurementSystem = MeasurementSystem;

package/dist/lib/Quantity.d.ts

@@ -67,6 +67,14 @@ export declare class Quantity {
     in(target: Unit): number;
     /** This quantity's exact magnitude expressed in `target`. */
     private inRational;
+    /**
+     * Re-express this quantity in the best-fit unit among `units`: the largest
+     * unit whose absolute magnitude is still at least 1 (falling back to the
+     * smallest unit when even that rounds below 1). Requires at least one unit,
+     * and each must belong to this quantity's dimension (else
+     * {@link DimensionMismatchError}).
+     */
+    best(...units: Unit[]): Quantity;
     /** Render as `"<magnitude> <unit name>"`, e.g. `"5 kilometer"`. */
     toString(): string;
     /**
@@ -103,7 +111,7 @@ export declare class Quantity {
     /**
      * Add another quantity, returned in *this* quantity's unit. The other operand
      * is converted into this unit first, so the two may use different units of the
-     * same dimension (e.g. `mile.plus(km)`). Throws {@link InvalidConversionError}
+     * same dimension (e.g. `mile.plus(km)`). Throws {@link DimensionMismatchError}
      * if the operands belong to different dimensions.
      *
      * Note: for affine units (e.g. temperature) addition is mathematically defined
@@ -121,7 +129,7 @@ export declare class Quantity {
      * Divide this quantity by `other` of the same dimension, yielding the
      * dimensionless ratio between them — i.e. how many of `other` fit in this.
      * Unlike {@link in}, this accounts for `other`'s magnitude, not just its unit.
-     * Throws {@link InvalidConversionError} across dimensions.
+     * Throws {@link DimensionMismatchError} across dimensions.
      */
     ratioTo(other: Quantity): number;
     /** Return this quantity with its magnitude negated. */
@@ -142,7 +150,7 @@ export declare class Quantity {
     div(divisor: number | Rational): Quantity;
     /**
      * Whether this quantity equals `other`, compared in this quantity's unit.
-     * Throws {@link InvalidConversionError} if the operands belong to different
+     * Throws {@link DimensionMismatchError} if the operands belong to different
      * dimensions. Comparison is exact rational equality, so quantities that are
      * mathematically equal compare equal even if reaching them involved a
      * conversion that would have drifted in floating point.

package/dist/lib/Quantity.js

@@ -3,6 +3,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.Quantity = void 0;
 const assert_never_1 = require("assert-never");
 const AmbiguousUnitError_1 = require("../errors/AmbiguousUnitError");
+const ArgumentError_1 = require("../errors/ArgumentError");
+const ParseError_1 = require("../errors/ParseError");
 const UnknownUnitError_1 = require("../errors/UnknownUnitError");
 const scaleOf_1 = require("../utils/scaleOf");
 const Rational_1 = require("./Rational");
@@ -28,6 +30,29 @@ class Quantity {
     inRational(target) {
         return this.unit.dimension.convertRational(this.rational, this.unit, target);
     }
+    /**
+     * Re-express this quantity in the best-fit unit among `units`: the largest
+     * unit whose absolute magnitude is still at least 1 (falling back to the
+     * smallest unit when even that rounds below 1). Requires at least one unit,
+     * and each must belong to this quantity's dimension (else
+     * {@link DimensionMismatchError}).
+     */
+    best(...units) {
+        const candidates = [...units].sort((a, b) => (0, scaleOf_1.scaleOf)(a) - (0, scaleOf_1.scaleOf)(b));
+        if (candidates.length === 0) {
+            throw new ArgumentError_1.ArgumentError("Quantity.best requires at least one unit");
+        }
+        let chosen = candidates[0];
+        for (const unit of candidates) {
+            if (Math.abs(this.in(unit)) >= 1) {
+                chosen = unit;
+            }
+            else {
+                break;
+            }
+        }
+        return this.to(chosen);
+    }
     /** Render as `"<magnitude> <unit name>"`, e.g. `"5 kilometer"`. */
     toString() {
         return `${this.magnitude} ${this.unit.name}`;
@@ -87,7 +112,7 @@ class Quantity {
     /**
      * Add another quantity, returned in *this* quantity's unit. The other operand
      * is converted into this unit first, so the two may use different units of the
-     * same dimension (e.g. `mile.plus(km)`). Throws {@link InvalidConversionError}
+     * same dimension (e.g. `mile.plus(km)`). Throws {@link DimensionMismatchError}
      * if the operands belong to different dimensions.
      *
      * Note: for affine units (e.g. temperature) addition is mathematically defined
@@ -113,7 +138,7 @@ class Quantity {
      * Divide this quantity by `other` of the same dimension, yielding the
      * dimensionless ratio between them — i.e. how many of `other` fit in this.
      * Unlike {@link in}, this accounts for `other`'s magnitude, not just its unit.
-     * Throws {@link InvalidConversionError} across dimensions.
+     * Throws {@link DimensionMismatchError} across dimensions.
      */
     ratioTo(other) {
         return this.rational.dividedBy(other.inRational(this.unit)).toNumber();
@@ -159,7 +184,7 @@ class Quantity {
     }
     /**
      * Whether this quantity equals `other`, compared in this quantity's unit.
-     * Throws {@link InvalidConversionError} if the operands belong to different
+     * Throws {@link DimensionMismatchError} if the operands belong to different
      * dimensions. Comparison is exact rational equality, so quantities that are
      * mathematically equal compare equal even if reaching them involved a
      * conversion that would have drifted in floating point.
@@ -257,7 +282,7 @@ class Quantity {
             }
         }
         if (!total || !finest) {
-            throw new Error(`Could not parse a quantity from "${str}"`);
+            throw new ParseError_1.ParseError(str);
         }
         return total.to(finest);
     }

package/dist/lib/Rational.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Rational = void 0;
+const ArgumentError_1 = require("../errors/ArgumentError");
 /**
  * An exact rational number (`n / d`) used to make conversions between linear
  * and affine units lossless. Such conversions are inherently rational — a foot
@@ -23,7 +24,7 @@ class Rational {
         let n = toBigInt(numerator);
         let d = toBigInt(denominator);
         if (d === 0n) {
-            throw new Error("Rational denominator cannot be zero");
+            throw new ArgumentError_1.ArgumentError("Rational denominator cannot be zero");
         }
         if (d < 0n) {
             n = -n;
@@ -48,11 +49,11 @@ class Rational {
      */
     static fromNumber(value) {
         if (!Number.isFinite(value)) {
-            throw new Error(`Cannot derive a rational from ${value}`);
+            throw new ArgumentError_1.ArgumentError(`Cannot derive a rational from ${value}`);
         }
         const match = /^(-?)(\d+)(?:\.(\d+))?(?:[eE]([+-]?\d+))?$/.exec(value.toString());
         if (!match) {
-            throw new Error(`Cannot derive a rational from ${value}`);
+            throw new ArgumentError_1.ArgumentError(`Cannot derive a rational from ${value}`);
         }
         const [, sign, intPart, fracPart = "", expPart] = match;
         let n = BigInt(intPart + fracPart);
@@ -168,7 +169,7 @@ function toBigInt(value) {
         return value;
     }
     if (!Number.isInteger(value)) {
-        throw new Error(`Rational numerator and denominator must be integers; got ${value}`);
+        throw new ArgumentError_1.ArgumentError(`Rational numerator and denominator must be integers; got ${value}`);
     }
     return BigInt(value);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "measurable",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "description": "Convert between units of measurement with custom and built-in systems",
   "keywords": [
     "conversion",
@@ -59,5 +59,5 @@
     "typecheck": "tsc --noEmit",
     "test": "vitest run"
   },
-  "readme": "# measurable\n\nConvert between units of measurement, with batteries-included common units and\nfirst-class support for defining your own.\n\n- **Exact, no drift** — magnitudes are held as exact rational numbers and\n  conversions run in rational arithmetic, collapsing to a float only when you\n  read `.magnitude`. So `foot → inch` is exactly `12` (not `12.000000000000002`),\n  and chains and round trips like `liter → gallon → liter` come back to exactly\n  what you started with.\n- **No redundant factors** — each unit defines a single transform to its\n  dimension's base unit; reverse conversions are derived, never stored, so they\n  can't fall out of sync.\n- **Free chaining** — any unit converts to any other in the same dimension\n  (e.g. `mile → inch`) without you defining every pair.\n- **Affine units** — temperature scales (°C/°F/K) and anything else needing an\n  offset, not just a scale factor.\n- **Two orthogonal ideas** — a **dimension** decides what _can_ convert; a\n  **measurement system** (metric/imperial/US) is a tag that never gates\n  conversion but powers filtering, formatting, and parse disambiguation.\n\n## Installation\n\n```sh\nnpm install measurable\n```\n\n## Entry points\n\nThe package is split into three import paths so the core stays lean:\n\n| Import                     | What you get                                                              |\n| -------------------------- | ------------------------------------------------------------------------- |\n| `measurable`             | The building blocks: `Quantity`, `Dimension`, `MeasurementSystem`, `Unit`, `Rational`, errors |\n| `measurable/dimensions`  | Predefined dimensions and their units (`length`, `meter`, `volume`, …)    |\n| `measurable/systems`     | Predefined measurement systems (`metric`, `imperial`, `usCustomary`)      |\n\n## Quick start\n\n```ts\nimport { Quantity } from \"measurable\";\nimport { meter, mile, foot, inch, celsius, fahrenheit } from \"measurable/dimensions\";\n\n// Convert: `.to()` returns a Quantity, `.in()` returns a raw number.\nnew Quantity(5, mile).to(meter).magnitude; // 8046.72\nnew Quantity(5, mile).in(meter);           // 8046.72\n\n// Affine scales work the same way.\nnew Quantity(100, celsius).in(fahrenheit); // 212\n\n// Conversions are exact: magnitudes are rationals under the hood.\nnew Quantity(1, foot).in(inch);                          // 12 (not 12.000000000000002)\nnew Quantity(1, foot).to(inch).to(foot).magnitude;       // 1 (exact round trip)\n```\n\n## Concepts\n\n- **`Dimension`** — a kind of measurable quantity (length, volume, mass, …). It\n  owns a canonical **base unit** and is where all conversion happens. A unit\n  belongs to exactly one dimension.\n- **`Unit`** — a name plus a transform into its dimension's base unit: an exact\n  rational `scale`/`offset` for linear and affine units, or an arbitrary\n  function pair for `custom` ones. Created through a dimension's builder methods.\n- **`Quantity`** — a magnitude paired with a unit (e.g. `5 kilometer`). The\n  magnitude is held as an exact **`Rational`**; `.magnitude` reads it as a\n  `number`.\n- **`Rational`** — an exact rational number (`n / d` over `bigint`s) used for the\n  lossless arithmetic above. You rarely construct one directly, but can pass one\n  anywhere a magnitude or scale is expected.\n- **`MeasurementSystem`** — a cross-dimension tag (metric/imperial/…). A unit can\n  belong to many; membership is optional and never affects whether a conversion\n  is allowed.\n\n## Exact arithmetic\n\nA linear conversion is inherently rational — a foot is exactly `3048/10000` m and\nan inch exactly `254/10000` m, so a foot is exactly `12` inches. Storing those\nratios as binary floats and routing values through the base unit loses that\n(`1 foot → inch` would give `12.000000000000002`).\n\nInstead, each `Quantity` keeps its magnitude as an exact `Rational`, and\nconversions/arithmetic run in rational arithmetic, collapsing to a `number` only\nwhen you read `.magnitude` (or call `.in()`). Because nothing is collapsed\nmid-chain, conversions compose without accumulating drift:\n\n```ts\nimport { Quantity } from \"measurable\";\nimport { liter, usGallon } from \"measurable/dimensions\";\n\n// A round trip through an awkward ratio still lands exactly on 7.\nnew Quantity(7, liter).to(usGallon).to(liter).magnitude; // 7\n\n// .rational exposes the underlying exact value (always in lowest terms).\nnew Quantity(7, liter).to(usGallon).rational; // Rational 125000000/67596639\n```\n\nThis is exact for linear and affine units. A conversion that passes through a\nnon-linear `custom` unit (e.g. a logarithmic scale) necessarily uses floating\npoint and recaptures the result as a rational, so it is best-effort there.\n\n## Built-in dimensions\n\nImport any dimension or unit from `measurable/dimensions`:\n\n| Dimension            | Base                     | Units (a selection)                                                                                          |\n| -------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------ |\n| `length`             | `meter`                  | `kilometer`, `centimeter`, `millimeter`, `inch`, `foot`, `yard`, `mile`                                       |\n| `area`               | `squareMeter`            | `squareKilometer`, `hectare`, `are`, `squareInch`, `squareFoot`, `squareYard`, `acre`, `squareMile`          |\n| `volume`             | `liter`                  | `milliliter`, `us*`/`imperial*` `Gallon`/`Quart`/`Pint`/`Gill`/`FluidOunce`, `cup`, `tablespoon`, `teaspoon`  |\n| `mass`               | `gram`                   | `kilogram`, `milligram`, `tonne`, `pound`, `ounce`, `stone`, `shortTon`, `longTon`                            |\n| `time`               | `second`                 | `millisecond`, `minute`, `hour`, `day`, `week`                                                                |\n| `temperature`        | `kelvin`                 | `celsius`, `fahrenheit`                                                                                       |\n| `angle`              | `radian`                 | `degree`, `gradian`, `turn`                                                                                   |\n| `force`              | `newton`                 | `kilonewton`, `dyne`, `poundForce`, `kilogramForce`                                                           |\n| `energy`             | `joule`                  | `kilojoule`, `wattHour`, `kilowattHour`, `calorie`, `kilocalorie`, `britishThermalUnit`                       |\n| `power`              | `watt`                   | `kilowatt`, `megawatt`, `horsepower`, `metricHorsepower`                                                      |\n| `pressure`           | `pascal`                 | `kilopascal`, `bar`, `millibar`, `atmosphere`, `torr`, `psi`, `inchOfMercury`, `inchOfWater`                  |\n| `frequency`          | `hertz`                  | `kilohertz`, `megahertz`, `gigahertz`, `terahertz`                                                            |\n| `data`               | `bit`                    | `byte`, `nibble`, `kilobyte`…`petabyte` (SI), `kibibyte`…`pebibyte` (IEC)                                     |\n| `illuminance`        | `lux`                    | `kilolux`, `millilux`, `footCandle`, `phot`                                                                   |\n| `luminance`          | `candelaPerSquareMeter`  | `nit`, `stilb`                                                                                                |\n| `luminousIntensity`  | `candela`                | `kilocandela`, `millicandela`, `candlepower`, `hefnerkerze`                                                   |\n\nThe metric units carry the **full SI prefix ladder** (yotta → yocto), generated for\nyou: the SI-based dimensions (`length`, `mass`, `volume`, `force`, `energy`, `power`,\n`pressure`, `frequency`, `illuminance`, `luminousIntensity`) get every prefix (so\n`kilogram` itself is just the kilo-prefixed gram), while `time` and `angle` get the\nfractional prefixes only (e.g. `millisecond`, `microradian`). Every generated rung\nparses from its symbol (`dm`, `hm`, `Mg`, `kL`, `ns`, `GHz`, `kPa`, and `µm`/`um` for\nmicro) and converts like any other unit. `data` additionally carries the **IEC binary**\nmultiples (`kibibyte`, `mebibyte`, … = 1024-based) alongside the SI decimal ones\n(`kilobyte`, … = 1000-based). You can apply the same ladder to your own dimensions with\n`definePrefixed` (see below).\n\n### Prefixed unit exports\n\nEach prefixed dimension exports a **record** holding the _complete_ generated ladder\nkeyed by name (the return value of `definePrefixed`), plus a **curated subset of those\nsame units as individual named exports** for convenience. Reach any rung that isn't\nexported individually through the record — e.g. `metricLength.gigameter`,\n`metricMass.exagram` — or by parsing its symbol.\n\n| Dimension           | Record export(s)                 | Individually exported units                                                                                       |\n| ------------------- | -------------------------------- | ----------------------------------------------------------------------------------------------------------------- |\n| `length`            | `metricLength`                   | `kilometer`, `hectometer`, `decameter`, `decimeter`, `centimeter`, `millimeter`, `micrometer`, `nanometer`        |\n| `mass`              | `metricMass`                     | `kilogram`, `megagram`, `hectogram`, `decagram`, `decigram`, `centigram`, `milligram`, `microgram`, `nanogram`    |\n| `volume`            | `metricVolume`                   | `kiloliter`, `hectoliter`, `decaliter`, `deciliter`, `centiliter`, `milliliter`                                    |\n| `time`              | `metricTime`                     | `millisecond`, `microsecond`, `nanosecond`, `picosecond`                                                          |\n| `angle`             | `metricAngle`                    | `milliradian`, `microradian`                                                                                       |\n| `force`             | `metricForce`                    | `meganewton`, `kilonewton`, `millinewton`, `micronewton`                                                           |\n| `energy`            | `metricEnergy`, `metricWattHour` | `kilojoule`, `megajoule`, `gigajoule`, `millijoule`; `kilowattHour`, `megawattHour`, `gigawattHour`               |\n| `power`             | `metricPower`                    | `kilowatt`, `megawatt`, `gigawatt`, `terawatt`, `milliwatt`                                                        |\n| `pressure`          | `metricPressure`                 | `kilopascal`, `hectopascal`, `megapascal`, `gigapascal`                                                            |\n| `frequency`         | `metricFrequency`                | `kilohertz`, `megahertz`, `gigahertz`, `terahertz`, `petahertz`, `millihertz`                                      |\n| `illuminance`       | `metricIlluminance`              | `kilolux`, `millilux`, `microlux`                                                                                  |\n| `luminousIntensity` | `metricLuminousIntensity`        | `kilocandela`, `millicandela`, `microcandela`                                                                      |\n| `data`              | `dataMultiples`                  | `kilobit`/`kilobyte` … `petabit`/`petabyte` (SI), `kibibit`/`kibibyte` … `pebibit`/`pebibyte` (IEC)               |\n\n```ts\nimport { metricLength, kilometer } from \"measurable/dimensions\";\n\nkilometer === metricLength.kilometer; // true — the named export is the same unit\nmetricLength.gigameter;               // a rung not exported by name, reached via the record\n```\n\n## Built-in measurement systems\n\nImport `metric`, `imperial`, or `usCustomary` from `measurable/systems`.\n\n```ts\nimport { foot } from \"measurable/dimensions\";\nimport { imperial, usCustomary, metric } from \"measurable/systems\";\n\nimperial.has(foot);      // true  — a unit can belong to several systems\nusCustomary.has(foot);   // true\nmetric.has(foot);        // false\n```\n\nMembership spans every dimension: SI units (`squareMeter`, `pascal`, `watt`, `joule`,\n`hertz`, `lux`, `candela`, and their prefix ladders) are tagged into `metric`, while the\ncustomary ones (`squareFoot`, `acre`, `psi`, `horsepower`, `britishThermalUnit`,\n`footCandle`, `candlepower`) belong to both `imperial` and `usCustomary`. Units tied to\nno real-world standard (e.g. `atmosphere`, `torr`, and the `data` multiples) stay\nuntagged — they still convert, they just won't appear under any system.\n\n### Listing units in a system\n\n```ts\nimport { length } from \"measurable/dimensions\";\nimport { metric } from \"measurable/systems\";\n\nmetric.in(length).map((u) => u.name); // [\"meter\", \"kilometer\", \"centimeter\", \"millimeter\"]\n```\n\n### Best-fit formatting\n\n`express` re-expresses a quantity in a system's most readable unit (the largest\nunit whose magnitude is still ≥ 1):\n\n```ts\nimport { Quantity } from \"measurable\";\nimport { meter } from \"measurable/dimensions\";\nimport { metric, imperial } from \"measurable/systems\";\n\nmetric.express(new Quantity(5000, meter));    // Quantity(5, kilometer)\nimperial.express(new Quantity(5000, meter));  // Quantity(3.107…, mile)\n```\n\n## Formatting output\n\nEach unit carries a canonical `symbol` (`\"g\"`, `\"km\"`, `\"°C\"`) and `plural`\n(`\"grams\"`, `\"kilometers\"`) alongside its `name`, so a `Quantity` can be rendered the\nway you want:\n\n```ts\nimport { Quantity } from \"measurable\";\nimport { gram } from \"measurable/dimensions\";\n\nnew Quantity(5, gram).toString();                 // \"5 gram\"   (always the bare name)\nnew Quantity(5, gram).format();                   // \"5 grams\"  (magnitude-aware)\nnew Quantity(1, gram).format();                   // \"1 gram\"   (singular at ±1)\nnew Quantity(5, gram).format({ unit: \"symbol\" }); // \"5 g\"\nnew Quantity(5, gram).format({ unit: \"name\" });   // \"5 gram\"\nnew Quantity(5, gram).format({ unit: \"plural\" }); // \"5 grams\"\n\n// Localize the magnitude with locale / numberFormat (passed to toLocaleString):\nnew Quantity(1234.5, meter).format({ locale: \"de-DE\" });                             // \"1.234,5 meters\"\nnew Quantity(1.23456, meter).format({ numberFormat: { maximumFractionDigits: 2 } }); // \"1.23 meters\"\nnew Quantity(1234.5, kilometer).format({ locale: \"de-DE\", unit: \"symbol\" });         // \"1.234,5 km\"\n```\n\n`toString()` is intentionally stable (`\"<magnitude> <name>\"`). `format(options?)` is the\nflexible one: `unit` defaults to `\"auto\"` (singular `name` at ±1, otherwise `plural`) and\naccepts `\"name\"`, `\"plural\"`, or `\"symbol\"`. When a unit has no `symbol`/`plural`, those\nmodes fall back to its `name`.\n\nThe magnitude is rendered with `Number.prototype.toLocaleString`. Pass `locale` (a BCP 47\nlocale or array) and/or `numberFormat` (`Intl.NumberFormatOptions` — precision via\n`maximumFractionDigits`, grouping, `style`, …) to control it; with neither set, the\nruntime's default locale is used. Use `round(decimals)` to trim the magnitude first\n(`new Quantity(1.6213, mile).round(2)` → `1.62 mile`).\n\nWhen a single string won't do — e.g. styling the magnitude in a React component — use\n`formatParts(options?)`, which takes the same options but returns the rendered\n`{ magnitude, unit }` as separate strings for you to assemble:\n\n```tsx\nconst { magnitude, unit } = new Quantity(1234.5, kilometer).formatParts({ locale: \"de-DE\" });\n// { magnitude: \"1.234,5\", unit: \"kilometers\" }\nreturn <><b>{magnitude}</b> {unit}</>;\n```\n\n### Internationalization\n\n`format()` localizes the **magnitude** (via `locale`/`numberFormat`), but the **label** it\nappends — `symbol`/`plural` — is **English/canonical** convenience data, not a localization\nsystem: a single plural string can't model languages with several plural forms, and the\nnames themselves are English. For a fully localized label, delegate to `Intl.NumberFormat`,\nwhose `style: \"unit\"` localizes **and** pluralizes a curated set of units for you:\n\n```ts\nconst q = new Quantity(5, kilometer);\nnew Intl.NumberFormat(\"de\", { style: \"unit\", unit: \"kilometer\" }).format(q.magnitude);\n// \"5 Kilometer\"\nnew Intl.NumberFormat(\"fr\", { style: \"unit\", unit: \"kilometer\", unitDisplay: \"short\" })\n  .format(q.magnitude); // \"5 km\"\n```\n\n## Parsing strings\n\n`Quantity.parse(input, dimension, options?)` reads a string into a `Quantity`.\nCompound inputs are summed and returned in the finest unit present:\n\n```ts\nimport { Quantity } from \"measurable\";\nimport { length, time } from \"measurable/dimensions\";\n\nQuantity.parse(\"1km\", length);         // Quantity(1, kilometer)\nQuantity.parse(\"5 hr\", time);          // Quantity(5, hour)\nQuantity.parse(\"5hr 20min\", time);     // Quantity(320, minute)\n```\n\n### Ambiguous aliases\n\nSome names mean different things in different systems — a US gallon (3.785 L) is\nnot an imperial gallon (4.546 L), and `ton` could be short or long. These are\ndistinct units that share an alias, so an unqualified parse throws; pass a\n`prefer`red system to disambiguate:\n\n```ts\nimport { Quantity, AmbiguousUnitError } from \"measurable\";\nimport { volume, mass } from \"measurable/dimensions\";\nimport { usCustomary, imperial } from \"measurable/systems\";\n\nQuantity.parse(\"1 gallon\", volume);                                    // throws AmbiguousUnitError\nQuantity.parse(\"1 gallon\", volume, { prefer: usCustomary }).unit.name; // \"usGallon\"\nQuantity.parse(\"1 ton\", mass, { prefer: imperial }).unit.name;         // \"longTon\"\n```\n\nConversion itself is governed only by the dimension, so cross-system conversions\nalways work regardless of tags:\n\n```ts\nimport { shortTon, tonne } from \"measurable/dimensions\";\n\nnew Quantity(1, shortTon).in(tonne); // 0.90718474\n```\n\n## Arithmetic\n\nQuantities can be combined. `plus`/`minus` take another `Quantity` (converted into\nthe receiver's unit first, so the operands may use different units of the same\ndimension); `times`/`dividedBy` apply a dimensionless scalar (a `number` or a\n`Rational`), and `negate`/`abs` transform the magnitude. All return a **new**\n`Quantity` in the receiver's unit and leave the operands untouched. Like\nconversions, the arithmetic is exact — `q.times(3).dividedBy(3)` returns `q`.\n\n```ts\nimport { Quantity } from \"measurable\";\nimport { kilometer, mile } from \"measurable/dimensions\";\n\nnew Quantity(1, mile).plus(new Quantity(1, kilometer));  // Quantity(1.6213…, mile)\nnew Quantity(1, mile).minus(new Quantity(1, kilometer)); // Quantity(0.3786…, mile)\nnew Quantity(2, mile).times(3);                          // Quantity(6, mile)\nnew Quantity(6, mile).dividedBy(2);                      // Quantity(3, mile)\n```\n\nShort aliases are available: **`add`** (`plus`), **`sub`** (`minus`), **`mul`**\n(`times`), **`div`** (`dividedBy`).\n\nCombining different dimensions throws `InvalidConversionError`. Note that adding\n**affine** units (e.g. temperatures) is mathematically defined but physically\nquestionable, since it adds absolute points rather than a difference.\n\n## Ratios\n\n`ratioTo` divides two quantities of the **same dimension** and returns a plain\n(dimensionless) number — _how many of one fit in the other_:\n\n```ts\nimport { Quantity } from \"measurable\";\nimport { liter, milliliter } from \"measurable/dimensions\";\n\n// How many 250 mL servings are in a 2 L bottle?\nnew Quantity(2, liter).ratioTo(new Quantity(250, milliliter)); // 8\n```\n\nThis is different from `.in(unit)`: `.in(milliliter)` only uses the *unit* on the\nright (giving `2000`), whereas `ratioTo` also uses the other quantity's\n**magnitude** (the `250`), so it answers \"how many of *that quantity* fit in this\none.\" It's the inverse of scalar `times` — `b.times(a.ratioTo(b))` reconstructs\n`a`. Comparing different dimensions throws `InvalidConversionError`.\n\n## Comparison\n\n`equals`/`notEquals`/`lessThan`/`greaterThan`/`lessThanOrEqual`/`greaterThanOrEqual`\ncompare two quantities (the other is converted into the receiver's unit first),\nreturning a boolean. Comparing different dimensions throws `InvalidConversionError`.\n\n```ts\nimport { Quantity } from \"measurable\";\nimport { kilometer, meter } from \"measurable/dimensions\";\n\nnew Quantity(1, kilometer).equals(new Quantity(1000, meter));    // true\nnew Quantity(1, meter).lessThan(new Quantity(1, kilometer));     // true\nnew Quantity(1, kilometer).greaterThan(new Quantity(1, meter));  // true\n```\n\nShort aliases: **`eq`** (`equals`), **`ne`** (`notEquals`), **`lt`** (`lessThan`),\n**`gt`** (`greaterThan`), **`lte`** (`lessThanOrEqual`), **`gte`**\n(`greaterThanOrEqual`). Comparison is exact rational comparison, so quantities\nthat are mathematically equal compare equal even when reaching them involved a\nconversion that would have drifted in floating point — e.g.\n`new Quantity(7, liter).to(usGallon).to(liter).equals(new Quantity(7, liter))` is\n`true`.\n\n`compareTo(other)` returns `-1`, `0`, or `1`, suitable as an `Array#sort`\ncomparator: `quantities.sort((a, b) => a.compareTo(b))`.\n\n## Combining quantities\n\n`Quantity.min`/`max`/`sum` aggregate several quantities at once; `clamp` is an\ninstance method that bounds one quantity to a range. Each converts operands as\nneeded, so mixing dimensions throws `InvalidConversionError`.\n\n```ts\nimport { Quantity } from \"measurable\";\nimport { kilometer, meter } from \"measurable/dimensions\";\n\nconst a = new Quantity(1, kilometer);\nconst b = new Quantity(500, meter);\n\nQuantity.min(a, b); // Quantity(500, meter) — the smaller\nQuantity.max(a, b); // Quantity(1, kilometer) — the larger\nQuantity.sum(a, b); // Quantity(1.5, kilometer) — total, in a's unit\nb.clamp(a, new Quantity(2, kilometer)); // b bounded to [a, 2 km], in b's unit\n```\n\n## Defining your own units\n\nCreate a `Dimension` and add units through its builder methods. `scale` is how\nmany base units make up one of the unit being defined. The optional final argument\nis a definition object — `{ symbol?, plural?, aliases? }` — whose `symbol` and\n`plural` feed `format()` and, like `aliases`, are also registered for parsing.\n\n```ts\nimport { Dimension, Quantity } from \"measurable\";\n\nconst data = new Dimension(\"data\");\nconst byte = data.base(\"byte\", { symbol: \"B\", plural: \"bytes\" }); // base unit (identity)\nconst kilobyte = data.unit(\"kilobyte\", 1024, { symbol: \"KB\", plural: \"kilobytes\" });\nconst megabyte = data.unit(\"megabyte\", 1024 ** 2, { symbol: \"MB\", plural: \"megabytes\" });\n\nnew Quantity(2, megabyte).in(kilobyte);      // 2048\nnew Quantity(2, megabyte).format();          // \"2 megabytes\"\nnew Quantity(2, megabyte).format({ unit: \"symbol\" }); // \"2 MB\"\n```\n\nA numeric `scale` is read as the exact decimal you wrote (`0.0254` → `254/10000`),\nwhich is exact for any terminating decimal. For a ratio a decimal **can't**\nrepresent exactly — e.g. `5/9` — pass a `Rational` so it stays exact:\n\n```ts\nimport { Dimension, Rational } from \"measurable\";\n\nconst ratio = new Dimension(\"ratio\");\nratio.base(\"whole\");\nconst third = ratio.unit(\"third\", new Rational(1, 3)); // exact, not 0.3333…\n```\n\n### Affine units (offset, not just scale)\n\n```ts\nimport { Dimension, Rational } from \"measurable\";\n\nconst temperature = new Dimension(\"temperature\");\nconst kelvin = temperature.base(\"kelvin\", { symbol: \"K\" });\n// value_in_base = value * scale + offset\nconst celsius = temperature.affine(\"celsius\", { scale: 1, offset: 273.15 }, {\n  symbol: \"°C\",\n  aliases: [\"C\"],\n});\n// Fahrenheit's 5/9 isn't a terminating decimal — give it (and the derived\n// offset) as exact Rationals so conversions round-trip without drift.\nconst scale = new Rational(5, 9);\nconst fahrenheit = temperature.affine(\n  \"fahrenheit\",\n  { scale, offset: Rational.from(273.15).minus(new Rational(32).times(scale)) },\n  { symbol: \"°F\", aliases: [\"F\"] },\n);\n```\n\n### Fully custom transforms\n\nFor anything non-linear, provide an explicit inverse pair:\n\n```ts\nconst dim = new Dimension(\"custom\");\ndim.base(\"base\");\ndim.custom(\"squared\", {\n  toBase: (x) => x * x,\n  fromBase: (x) => Math.sqrt(x),\n});\n```\n\n### Generating SI prefixes\n\n`definePrefixed` adds the metric prefix ladder to a reference **unit** and returns the\ncreated units keyed by name (skipping any name that already exists). It reads the\nreference's `name`, `symbol`, and scale straight off the unit (via `scaleOf`), so each\ngenerated unit gets a derived symbol (`b` → `kb`) and plural too — even when the\nreference isn't the base unit. Pass `SI_SUBMULTIPLE_PREFIXES` to generate fractions only.\n\n```ts\nimport { Dimension, Quantity, definePrefixed } from \"measurable\";\n\nconst data = new Dimension(\"data\");\nconst bit = data.base(\"bit\", { symbol: \"b\", plural: \"bits\" });\nconst prefixed = definePrefixed(data, bit);\n\nnew Quantity(1, prefixed.kilobit).in(bit);   // 1000  (SI kilo = 1e3)\nprefixed.kilobit.symbol;                     // \"kb\"\nnew Quantity(5, prefixed.kilobit).format({ unit: \"symbol\" }); // \"5 kb\"\n```\n\n### Tagging units into a measurement system\n\n```ts\nimport { MeasurementSystem } from \"measurable\";\n\nconst si = new MeasurementSystem(\"si\").add(byte, kilobyte, megabyte);\nsi.has(kilobyte); // true\n```\n\n## API reference\n\n### `Dimension`\n\n- `new Dimension(name)`\n- `.base(name, def?)` — define the canonical base unit\n- `.unit(name, scale, def?)` — linear unit (`scale` base units per unit; `number | Rational`)\n- `.affine(name, { scale, offset }, def?)` — linear with additive offset (each `number | Rational`)\n- `.custom(name, { toBase, fromBase }, def?)` — arbitrary inverse pair, for non-linear units\n- `.convert(value, from, to)` — convert a raw `number` between two of its units\n- `.convertRational(value, from, to)` → `Rational` — exact conversion between two of its units\n- `.get(token)` — units matching a name/alias (`Unit[] | undefined`)\n- `.has(unit)`, `.units`, `.baseUnit`\n\n`def` is an optional `UnitDef`: `{ symbol?, plural?, aliases? }`. All three are\nregistered as parse tokens; `symbol`/`plural` are additionally stored on the `Unit`.\n\n### `Unit`\n\nA passive handle, normally created via a dimension's builder methods rather than\n`new Unit` directly. Read-only properties:\n\n- `.name` — the unit's canonical name\n- `.symbol?` — canonical symbol (e.g. `\"g\"`, `\"km\"`), if declared\n- `.plural?` — plural name (e.g. `\"grams\"`), if declared\n- `.dimension` — the `Dimension` it belongs to\n- `.linear` → `{ scale: Rational; offset: Rational } | undefined` — the exact transform for linear/affine units (`undefined` for `custom` ones)\n- `.toBase(value)` → `number` — convert a value in this unit to base units\n- `.fromBase(value)` → `number` — convert a value in base units to this unit\n\n### `Quantity`\n\n- `new Quantity(magnitude, unit)` — `magnitude` is a `number | Rational`; throws on a non-finite `number`\n- `.magnitude` → `number` — getter, derived from `.rational`\n- `.rational` → `Rational` — the exact magnitude (source of truth)\n- `.to(target)` → `Quantity`\n- `.in(target)` → `number`\n- `.toString()` → `string` — stable `\"<magnitude> <name>\"`, e.g. `\"5 kilometer\"`\n- `.format({ unit?, locale?, numberFormat? })` → `string` — `unit`: `\"auto\"` (default, magnitude-aware) / `\"name\"` / `\"plural\"` / `\"symbol\"`; `locale` + `numberFormat` localize the magnitude via `toLocaleString`\n- `.formatParts(options?)` → `{ magnitude, unit }` — same options as `.format`, but returns the rendered pieces separately for custom assembly (e.g. JSX)\n- `.plus(other)` / `.minus(other)` → `Quantity` — add/subtract another quantity (aliases: `add` / `sub`)\n- `.times(factor)` / `.dividedBy(divisor)` → `Quantity` — scale by a `number | Rational` (aliases: `mul` / `div`)\n- `.ratioTo(other)` → `number` — dimensionless ratio (how many of `other` fit in this)\n- `.negate()` / `.abs()` → `Quantity`\n- `.clamp(lower, upper)` → `Quantity` — bound to a range, in this unit\n- `.round(decimals?)` → `Quantity` — round the magnitude (default 0 decimals)\n- `.equals(other)` / `.notEquals(other)` → `boolean` (aliases: `eq` / `ne`)\n- `.lessThan(other)` / `.greaterThan(other)` → `boolean` (aliases: `lt` / `gt`)\n- `.lessThanOrEqual(other)` / `.greaterThanOrEqual(other)` → `boolean` (aliases: `lte` / `gte`)\n- `.compareTo(other)` → `-1 | 0 | 1` — sort comparator\n- `.isZero()` / `.isPositive()` / `.isNegative()` → `boolean`\n- `Quantity.min(...quantities)` / `Quantity.max(...quantities)` / `Quantity.sum(...quantities)` → `Quantity`\n- `Quantity.parse(input, dimension, { prefer? })` → `Quantity`\n\n### `Rational`\n\nAn exact rational number (`n / d`), stored as `bigint`s in lowest terms with a\npositive denominator. Immutable; every operation returns a new `Rational`. Used\ninternally for lossless conversions and arithmetic, but you can construct one to\npass anywhere a magnitude or scale is accepted.\n\n- `new Rational(numerator, denominator?)` — from integers (`bigint | number`; denominator defaults to `1`). Throws on a non-integer `number` or a zero denominator.\n- `Rational.from(value)` — coerce a `number | Rational` (a `number` is read as its exact terminating decimal, e.g. `0.0254` → `254/10000`)\n- `.n` / `.d` → `bigint` — numerator and denominator\n- `.plus(other)` / `.minus(other)` / `.times(other)` / `.dividedBy(other)` → `Rational` (aliases: `add` / `sub` / `mul` / `div`)\n- `.negate()` / `.abs()` → `Rational`\n- `.equals(other)` → `boolean` (alias: `eq`)\n- `.compare(other)` → `-1 | 0 | 1`\n- `.sign()` → `-1 | 0 | 1`\n- `.toNumber()` → `number` — collapse to the nearest `number`\n\n### `MeasurementSystem`\n\n- `new MeasurementSystem(name)`\n- `.add(...units)`, `.has(unit)`\n- `.in(dimension)` → `Unit[]`\n- `.express(quantity)` → `Quantity`\n\n### Errors\n\n- `InvalidConversionError` — units are from different dimensions\n- `UnknownUnitError` — a parsed token matches no unit\n- `AmbiguousUnitError` — a parsed token matches several units and no `prefer` was given\n\n## Changelog\n\nSee [CHANGELOG.md](https://github.com/mhuggins/measurable/blob/main/CHANGELOG.md)\nfor release notes. Note that v2.0.0 is a breaking release — see its entry for the\nmigration details.\n\n## License\n\nISC\n"
+  "readme": "# measurable\n\nConvert between units of measurement, with batteries-included common units and\nfirst-class support for defining your own.\n\n- **Exact, no drift** — magnitudes are held as exact rational numbers and\n  conversions run in rational arithmetic, collapsing to a float only when you\n  read `.magnitude`. So `foot → inch` is exactly `12` (not `12.000000000000002`),\n  and chains and round trips like `liter → gallon → liter` come back to exactly\n  what you started with.\n- **No redundant factors** — each unit defines a single transform to its\n  dimension's base unit; reverse conversions are derived, never stored, so they\n  can't fall out of sync.\n- **Free chaining** — any unit converts to any other in the same dimension\n  (e.g. `mile → inch`) without you defining every pair.\n- **Affine units** — temperature scales (°C/°F/K) and anything else needing an\n  offset, not just a scale factor.\n- **Two orthogonal ideas** — a **dimension** decides what _can_ convert; a\n  **measurement system** (metric/imperial/US) is a tag that never gates\n  conversion but powers filtering, formatting, and parse disambiguation.\n\n## Installation\n\n```sh\nnpm install measurable\n```\n\n## Entry points\n\nThe package is split into three import paths so the core stays lean:\n\n| Import                     | What you get                                                              |\n| -------------------------- | ------------------------------------------------------------------------- |\n| `measurable`             | The building blocks: `Quantity`, `Dimension`, `MeasurementSystem`, `Unit`, `Rational`, errors |\n| `measurable/dimensions`  | Predefined dimensions and their units (`length`, `meter`, `volume`, …)    |\n| `measurable/systems`     | Predefined measurement systems (`metric`, `imperial`, `usCustomary`)      |\n\n## Quick start\n\n```ts\nimport { Quantity } from \"measurable\";\nimport { meter, mile, foot, inch, celsius, fahrenheit } from \"measurable/dimensions\";\n\n// Convert: `.to()` returns a Quantity, `.in()` returns a raw number.\nnew Quantity(5, mile).to(meter).magnitude; // 8046.72\nnew Quantity(5, mile).in(meter);           // 8046.72\n\n// Affine scales work the same way.\nnew Quantity(100, celsius).in(fahrenheit); // 212\n\n// Conversions are exact: magnitudes are rationals under the hood.\nnew Quantity(1, foot).in(inch);                          // 12 (not 12.000000000000002)\nnew Quantity(1, foot).to(inch).to(foot).magnitude;       // 1 (exact round trip)\n```\n\n## Concepts\n\n- **`Dimension`** — a kind of measurable quantity (length, volume, mass, …). It\n  owns a canonical **base unit** and is where all conversion happens. A unit\n  belongs to exactly one dimension.\n- **`Unit`** — a name plus a transform into its dimension's base unit: an exact\n  rational `scale`/`offset` for linear and affine units, or an arbitrary\n  function pair for `custom` ones. Created through a dimension's builder methods.\n- **`Quantity`** — a magnitude paired with a unit (e.g. `5 kilometer`). The\n  magnitude is held as an exact **`Rational`**; `.magnitude` reads it as a\n  `number`.\n- **`Rational`** — an exact rational number (`n / d` over `bigint`s) used for the\n  lossless arithmetic above. You rarely construct one directly, but can pass one\n  anywhere a magnitude or scale is expected.\n- **`MeasurementSystem`** — a cross-dimension tag (metric/imperial/…). A unit can\n  belong to many; membership is optional and never affects whether a conversion\n  is allowed.\n\n## Exact arithmetic\n\nA linear conversion is inherently rational — a foot is exactly `3048/10000` m and\nan inch exactly `254/10000` m, so a foot is exactly `12` inches. Storing those\nratios as binary floats and routing values through the base unit loses that\n(`1 foot → inch` would give `12.000000000000002`).\n\nInstead, each `Quantity` keeps its magnitude as an exact `Rational`, and\nconversions/arithmetic run in rational arithmetic, collapsing to a `number` only\nwhen you read `.magnitude` (or call `.in()`). Because nothing is collapsed\nmid-chain, conversions compose without accumulating drift:\n\n```ts\nimport { Quantity } from \"measurable\";\nimport { liter, usGallon } from \"measurable/dimensions\";\n\n// A round trip through an awkward ratio still lands exactly on 7.\nnew Quantity(7, liter).to(usGallon).to(liter).magnitude; // 7\n\n// .rational exposes the underlying exact value (always in lowest terms).\nnew Quantity(7, liter).to(usGallon).rational; // Rational 125000000/67596639\n```\n\nThis is exact for linear and affine units. A conversion that passes through a\nnon-linear `custom` unit (e.g. a logarithmic scale) necessarily uses floating\npoint and recaptures the result as a rational, so it is best-effort there.\n\n## Built-in dimensions\n\nImport any dimension or unit from `measurable/dimensions`:\n\n| Dimension            | Base                     | Units (a selection)                                                                                          |\n| -------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------ |\n| `length`             | `meter`                  | `kilometer`, `centimeter`, `millimeter`, `inch`, `foot`, `yard`, `mile`                                       |\n| `area`               | `squareMeter`            | `squareKilometer`, `hectare`, `are`, `squareInch`, `squareFoot`, `squareYard`, `acre`, `squareMile`          |\n| `volume`             | `liter`                  | `milliliter`, `us*`/`imperial*` `Gallon`/`Quart`/`Pint`/`Gill`/`FluidOunce`, `cup`, `tablespoon`, `teaspoon`  |\n| `mass`               | `gram`                   | `kilogram`, `milligram`, `tonne`, `pound`, `ounce`, `stone`, `shortTon`, `longTon`                            |\n| `time`               | `second`                 | `millisecond`, `minute`, `hour`, `day`, `week`                                                                |\n| `temperature`        | `kelvin`                 | `celsius`, `fahrenheit`                                                                                       |\n| `angle`              | `radian`                 | `degree`, `gradian`, `turn`                                                                                   |\n| `force`              | `newton`                 | `kilonewton`, `dyne`, `poundForce`, `kilogramForce`                                                           |\n| `energy`             | `joule`                  | `kilojoule`, `wattHour`, `kilowattHour`, `calorie`, `kilocalorie`, `britishThermalUnit`                       |\n| `power`              | `watt`                   | `kilowatt`, `megawatt`, `horsepower`, `metricHorsepower`                                                      |\n| `pressure`           | `pascal`                 | `kilopascal`, `bar`, `millibar`, `atmosphere`, `torr`, `psi`, `inchOfMercury`, `inchOfWater`                  |\n| `frequency`          | `hertz`                  | `kilohertz`, `megahertz`, `gigahertz`, `terahertz`                                                            |\n| `data`               | `bit`                    | `byte`, `nibble`, `kilobyte`…`petabyte` (SI), `kibibyte`…`pebibyte` (IEC)                                     |\n| `illuminance`        | `lux`                    | `kilolux`, `millilux`, `footCandle`, `phot`                                                                   |\n| `luminance`          | `candelaPerSquareMeter`  | `nit`, `stilb`                                                                                                |\n| `luminousIntensity`  | `candela`                | `kilocandela`, `millicandela`, `candlepower`, `hefnerkerze`                                                   |\n\nThe metric units carry the **full SI prefix ladder** (yotta → yocto), generated for\nyou: the SI-based dimensions (`length`, `mass`, `volume`, `force`, `energy`, `power`,\n`pressure`, `frequency`, `illuminance`, `luminousIntensity`) get every prefix (so\n`kilogram` itself is just the kilo-prefixed gram), while `time` and `angle` get the\nfractional prefixes only (e.g. `millisecond`, `microradian`). Every generated rung\nparses from its symbol (`dm`, `hm`, `Mg`, `kL`, `ns`, `GHz`, `kPa`, and `µm`/`um` for\nmicro) and converts like any other unit. `data` additionally carries the **IEC binary**\nmultiples (`kibibyte`, `mebibyte`, … = 1024-based) alongside the SI decimal ones\n(`kilobyte`, … = 1000-based). You can apply the same ladder to your own dimensions with\n`definePrefixed` (see below).\n\n### Prefixed unit exports\n\nEach prefixed dimension exports a **record** holding the _complete_ generated ladder\nkeyed by name (the return value of `definePrefixed`), plus a **curated subset of those\nsame units as individual named exports** for convenience. Reach any rung that isn't\nexported individually through the record — e.g. `metricLength.gigameter`,\n`metricMass.exagram` — or by parsing its symbol.\n\n| Dimension           | Record export(s)                 | Individually exported units                                                                                       |\n| ------------------- | -------------------------------- | ----------------------------------------------------------------------------------------------------------------- |\n| `length`            | `metricLength`                   | `kilometer`, `hectometer`, `decameter`, `decimeter`, `centimeter`, `millimeter`, `micrometer`, `nanometer`        |\n| `mass`              | `metricMass`                     | `kilogram`, `megagram`, `hectogram`, `decagram`, `decigram`, `centigram`, `milligram`, `microgram`, `nanogram`    |\n| `volume`            | `metricVolume`                   | `kiloliter`, `hectoliter`, `decaliter`, `deciliter`, `centiliter`, `milliliter`                                    |\n| `time`              | `metricTime`                     | `millisecond`, `microsecond`, `nanosecond`, `picosecond`                                                          |\n| `angle`             | `metricAngle`                    | `milliradian`, `microradian`                                                                                       |\n| `force`             | `metricForce`                    | `meganewton`, `kilonewton`, `millinewton`, `micronewton`                                                           |\n| `energy`            | `metricEnergy`, `metricWattHour` | `kilojoule`, `megajoule`, `gigajoule`, `millijoule`; `kilowattHour`, `megawattHour`, `gigawattHour`               |\n| `power`             | `metricPower`                    | `kilowatt`, `megawatt`, `gigawatt`, `terawatt`, `milliwatt`                                                        |\n| `pressure`          | `metricPressure`                 | `kilopascal`, `hectopascal`, `megapascal`, `gigapascal`                                                            |\n| `frequency`         | `metricFrequency`                | `kilohertz`, `megahertz`, `gigahertz`, `terahertz`, `petahertz`, `millihertz`                                      |\n| `illuminance`       | `metricIlluminance`              | `kilolux`, `millilux`, `microlux`                                                                                  |\n| `luminousIntensity` | `metricLuminousIntensity`        | `kilocandela`, `millicandela`, `microcandela`                                                                      |\n| `data`              | `dataMultiples`                  | `kilobit`/`kilobyte` … `petabit`/`petabyte` (SI), `kibibit`/`kibibyte` … `pebibit`/`pebibyte` (IEC)               |\n\n```ts\nimport { metricLength, kilometer } from \"measurable/dimensions\";\n\nkilometer === metricLength.kilometer; // true — the named export is the same unit\nmetricLength.gigameter;               // a rung not exported by name, reached via the record\n```\n\n## Built-in measurement systems\n\nImport `metric`, `imperial`, or `usCustomary` from `measurable/systems`.\n\n```ts\nimport { foot } from \"measurable/dimensions\";\nimport { imperial, usCustomary, metric } from \"measurable/systems\";\n\nimperial.has(foot);      // true  — a unit can belong to several systems\nusCustomary.has(foot);   // true\nmetric.has(foot);        // false\n```\n\nMembership spans every dimension: SI units (`squareMeter`, `pascal`, `watt`, `joule`,\n`hertz`, `lux`, `candela`, and their prefix ladders) are tagged into `metric`, while the\ncustomary ones (`squareFoot`, `acre`, `psi`, `horsepower`, `britishThermalUnit`,\n`footCandle`, `candlepower`) belong to both `imperial` and `usCustomary`. Units tied to\nno real-world standard (e.g. `atmosphere`, `torr`, and the `data` multiples) stay\nuntagged — they still convert, they just won't appear under any system.\n\n### Listing units in a system\n\n```ts\nimport { length } from \"measurable/dimensions\";\nimport { metric } from \"measurable/systems\";\n\nmetric.in(length).map((u) => u.name); // [\"meter\", \"kilometer\", \"centimeter\", \"millimeter\"]\n```\n\n### Best-fit formatting\n\n`express` re-expresses a quantity in a system's most readable unit (the largest\nunit whose magnitude is still ≥ 1):\n\n```ts\nimport { Quantity } from \"measurable\";\nimport { meter } from \"measurable/dimensions\";\nimport { metric, imperial } from \"measurable/systems\";\n\nmetric.express(new Quantity(5000, meter));    // Quantity(5, kilometer)\nimperial.express(new Quantity(5000, meter));  // Quantity(3.107…, mile)\n```\n\nUnder the hood, `express` just hands the system's units for that dimension to\n`Quantity.best`, the same best-fit primitive you can call directly with whatever\nunits you like — handy when you want a custom shortlist rather than a whole\nsystem. `best` picks the largest unit whose absolute magnitude is still ≥ 1\n(falling back to the smallest when even that rounds below 1), so candidate order\ndoesn't matter:\n\n```ts\nimport { Quantity } from \"measurable\";\nimport { meter, kilometer, mile } from \"measurable/dimensions\";\n\nnew Quantity(5000, meter).best(meter, kilometer, mile);  // Quantity(3.107…, mile)\nnew Quantity(1500, meter).best(meter, kilometer);        // Quantity(1.5, kilometer)\nnew Quantity(500, meter).best(kilometer, mile);          // Quantity(0.5, kilometer) — smallest fallback\n```\n\nIt requires at least one unit, and each must belong to the quantity's dimension\n(otherwise `DimensionMismatchError`).\n\n## Formatting output\n\nEach unit carries a canonical `symbol` (`\"g\"`, `\"km\"`, `\"°C\"`) and `plural`\n(`\"grams\"`, `\"kilometers\"`) alongside its `name`, so a `Quantity` can be rendered the\nway you want:\n\n```ts\nimport { Quantity } from \"measurable\";\nimport { gram } from \"measurable/dimensions\";\n\nnew Quantity(5, gram).toString();                 // \"5 gram\"   (always the bare name)\nnew Quantity(5, gram).format();                   // \"5 grams\"  (magnitude-aware)\nnew Quantity(1, gram).format();                   // \"1 gram\"   (singular at ±1)\nnew Quantity(5, gram).format({ unit: \"symbol\" }); // \"5 g\"\nnew Quantity(5, gram).format({ unit: \"name\" });   // \"5 gram\"\nnew Quantity(5, gram).format({ unit: \"plural\" }); // \"5 grams\"\n\n// Localize the magnitude with locale / numberFormat (passed to toLocaleString):\nnew Quantity(1234.5, meter).format({ locale: \"de-DE\" });                             // \"1.234,5 meters\"\nnew Quantity(1.23456, meter).format({ numberFormat: { maximumFractionDigits: 2 } }); // \"1.23 meters\"\nnew Quantity(1234.5, kilometer).format({ locale: \"de-DE\", unit: \"symbol\" });         // \"1.234,5 km\"\n```\n\n`toString()` is intentionally stable (`\"<magnitude> <name>\"`). `format(options?)` is the\nflexible one: `unit` defaults to `\"auto\"` (singular `name` at ±1, otherwise `plural`) and\naccepts `\"name\"`, `\"plural\"`, or `\"symbol\"`. When a unit has no `symbol`/`plural`, those\nmodes fall back to its `name`.\n\nThe magnitude is rendered with `Number.prototype.toLocaleString`. Pass `locale` (a BCP 47\nlocale or array) and/or `numberFormat` (`Intl.NumberFormatOptions` — precision via\n`maximumFractionDigits`, grouping, `style`, …) to control it; with neither set, the\nruntime's default locale is used. Use `round(decimals)` to trim the magnitude first\n(`new Quantity(1.6213, mile).round(2)` → `1.62 mile`).\n\nWhen a single string won't do — e.g. styling the magnitude in a React component — use\n`formatParts(options?)`, which takes the same options but returns the rendered\n`{ magnitude, unit }` as separate strings for you to assemble:\n\n```tsx\nconst { magnitude, unit } = new Quantity(1234.5, kilometer).formatParts({ locale: \"de-DE\" });\n// { magnitude: \"1.234,5\", unit: \"kilometers\" }\nreturn <><b>{magnitude}</b> {unit}</>;\n```\n\n### Internationalization\n\n`format()` localizes the **magnitude** (via `locale`/`numberFormat`), but the **label** it\nappends — `symbol`/`plural` — is **English/canonical** convenience data, not a localization\nsystem: a single plural string can't model languages with several plural forms, and the\nnames themselves are English. For a fully localized label, delegate to `Intl.NumberFormat`,\nwhose `style: \"unit\"` localizes **and** pluralizes a curated set of units for you:\n\n```ts\nconst q = new Quantity(5, kilometer);\nnew Intl.NumberFormat(\"de\", { style: \"unit\", unit: \"kilometer\" }).format(q.magnitude);\n// \"5 Kilometer\"\nnew Intl.NumberFormat(\"fr\", { style: \"unit\", unit: \"kilometer\", unitDisplay: \"short\" })\n  .format(q.magnitude); // \"5 km\"\n```\n\n## Parsing strings\n\n`Quantity.parse(input, dimension, options?)` reads a string into a `Quantity`.\nCompound inputs are summed and returned in the finest unit present:\n\n```ts\nimport { Quantity } from \"measurable\";\nimport { length, time } from \"measurable/dimensions\";\n\nQuantity.parse(\"1km\", length);         // Quantity(1, kilometer)\nQuantity.parse(\"5 hr\", time);          // Quantity(5, hour)\nQuantity.parse(\"5hr 20min\", time);     // Quantity(320, minute)\n```\n\n### Ambiguous aliases\n\nSome names mean different things in different systems — a US gallon (3.785 L) is\nnot an imperial gallon (4.546 L), and `ton` could be short or long. These are\ndistinct units that share an alias, so an unqualified parse throws; pass a\n`prefer`red system to disambiguate:\n\n```ts\nimport { Quantity, AmbiguousUnitError } from \"measurable\";\nimport { volume, mass } from \"measurable/dimensions\";\nimport { usCustomary, imperial } from \"measurable/systems\";\n\nQuantity.parse(\"1 gallon\", volume);                                    // throws AmbiguousUnitError\nQuantity.parse(\"1 gallon\", volume, { prefer: usCustomary }).unit.name; // \"usGallon\"\nQuantity.parse(\"1 ton\", mass, { prefer: imperial }).unit.name;         // \"longTon\"\n```\n\nConversion itself is governed only by the dimension, so cross-system conversions\nalways work regardless of tags:\n\n```ts\nimport { shortTon, tonne } from \"measurable/dimensions\";\n\nnew Quantity(1, shortTon).in(tonne); // 0.90718474\n```\n\n## Arithmetic\n\nQuantities can be combined. `plus`/`minus` take another `Quantity` (converted into\nthe receiver's unit first, so the operands may use different units of the same\ndimension); `times`/`dividedBy` apply a dimensionless scalar (a `number` or a\n`Rational`), and `negate`/`abs` transform the magnitude. All return a **new**\n`Quantity` in the receiver's unit and leave the operands untouched. Like\nconversions, the arithmetic is exact — `q.times(3).dividedBy(3)` returns `q`.\n\n```ts\nimport { Quantity } from \"measurable\";\nimport { kilometer, mile } from \"measurable/dimensions\";\n\nnew Quantity(1, mile).plus(new Quantity(1, kilometer));  // Quantity(1.6213…, mile)\nnew Quantity(1, mile).minus(new Quantity(1, kilometer)); // Quantity(0.3786…, mile)\nnew Quantity(2, mile).times(3);                          // Quantity(6, mile)\nnew Quantity(6, mile).dividedBy(2);                      // Quantity(3, mile)\n```\n\nShort aliases are available: **`add`** (`plus`), **`sub`** (`minus`), **`mul`**\n(`times`), **`div`** (`dividedBy`).\n\nCombining different dimensions throws `DimensionMismatchError`. Note that adding\n**affine** units (e.g. temperatures) is mathematically defined but physically\nquestionable, since it adds absolute points rather than a difference.\n\n## Ratios\n\n`ratioTo` divides two quantities of the **same dimension** and returns a plain\n(dimensionless) number — _how many of one fit in the other_:\n\n```ts\nimport { Quantity } from \"measurable\";\nimport { liter, milliliter } from \"measurable/dimensions\";\n\n// How many 250 mL servings are in a 2 L bottle?\nnew Quantity(2, liter).ratioTo(new Quantity(250, milliliter)); // 8\n```\n\nThis is different from `.in(unit)`: `.in(milliliter)` only uses the *unit* on the\nright (giving `2000`), whereas `ratioTo` also uses the other quantity's\n**magnitude** (the `250`), so it answers \"how many of *that quantity* fit in this\none.\" It's the inverse of scalar `times` — `b.times(a.ratioTo(b))` reconstructs\n`a`. Comparing different dimensions throws `DimensionMismatchError`.\n\n## Comparison\n\n`equals`/`notEquals`/`lessThan`/`greaterThan`/`lessThanOrEqual`/`greaterThanOrEqual`\ncompare two quantities (the other is converted into the receiver's unit first),\nreturning a boolean. Comparing different dimensions throws `DimensionMismatchError`.\n\n```ts\nimport { Quantity } from \"measurable\";\nimport { kilometer, meter } from \"measurable/dimensions\";\n\nnew Quantity(1, kilometer).equals(new Quantity(1000, meter));    // true\nnew Quantity(1, meter).lessThan(new Quantity(1, kilometer));     // true\nnew Quantity(1, kilometer).greaterThan(new Quantity(1, meter));  // true\n```\n\nShort aliases: **`eq`** (`equals`), **`ne`** (`notEquals`), **`lt`** (`lessThan`),\n**`gt`** (`greaterThan`), **`lte`** (`lessThanOrEqual`), **`gte`**\n(`greaterThanOrEqual`). Comparison is exact rational comparison, so quantities\nthat are mathematically equal compare equal even when reaching them involved a\nconversion that would have drifted in floating point — e.g.\n`new Quantity(7, liter).to(usGallon).to(liter).equals(new Quantity(7, liter))` is\n`true`.\n\n`compareTo(other)` returns `-1`, `0`, or `1`, suitable as an `Array#sort`\ncomparator: `quantities.sort((a, b) => a.compareTo(b))`.\n\n## Combining quantities\n\n`Quantity.min`/`max`/`sum` aggregate several quantities at once; `clamp` is an\ninstance method that bounds one quantity to a range. Each converts operands as\nneeded, so mixing dimensions throws `DimensionMismatchError`.\n\n```ts\nimport { Quantity } from \"measurable\";\nimport { kilometer, meter } from \"measurable/dimensions\";\n\nconst a = new Quantity(1, kilometer);\nconst b = new Quantity(500, meter);\n\nQuantity.min(a, b); // Quantity(500, meter) — the smaller\nQuantity.max(a, b); // Quantity(1, kilometer) — the larger\nQuantity.sum(a, b); // Quantity(1.5, kilometer) — total, in a's unit\nb.clamp(a, new Quantity(2, kilometer)); // b bounded to [a, 2 km], in b's unit\n```\n\n## Defining your own units\n\nCreate a `Dimension` and add units through its builder methods. `scale` is how\nmany base units make up one of the unit being defined. The optional final argument\nis a definition object — `{ symbol?, plural?, aliases? }` — whose `symbol` and\n`plural` feed `format()` and, like `aliases`, are also registered for parsing.\n\n```ts\nimport { Dimension, Quantity } from \"measurable\";\n\nconst data = new Dimension(\"data\");\nconst byte = data.base(\"byte\", { symbol: \"B\", plural: \"bytes\" }); // base unit (identity)\nconst kilobyte = data.unit(\"kilobyte\", 1024, { symbol: \"KB\", plural: \"kilobytes\" });\nconst megabyte = data.unit(\"megabyte\", 1024 ** 2, { symbol: \"MB\", plural: \"megabytes\" });\n\nnew Quantity(2, megabyte).in(kilobyte);      // 2048\nnew Quantity(2, megabyte).format();          // \"2 megabytes\"\nnew Quantity(2, megabyte).format({ unit: \"symbol\" }); // \"2 MB\"\n```\n\nA numeric `scale` is read as the exact decimal you wrote (`0.0254` → `254/10000`),\nwhich is exact for any terminating decimal. For a ratio a decimal **can't**\nrepresent exactly — e.g. `5/9` — pass a `Rational` so it stays exact:\n\n```ts\nimport { Dimension, Rational } from \"measurable\";\n\nconst ratio = new Dimension(\"ratio\");\nratio.base(\"whole\");\nconst third = ratio.unit(\"third\", new Rational(1, 3)); // exact, not 0.3333…\n```\n\n### Affine units (offset, not just scale)\n\n```ts\nimport { Dimension, Rational } from \"measurable\";\n\nconst temperature = new Dimension(\"temperature\");\nconst kelvin = temperature.base(\"kelvin\", { symbol: \"K\" });\n// value_in_base = value * scale + offset\nconst celsius = temperature.affine(\"celsius\", { scale: 1, offset: 273.15 }, {\n  symbol: \"°C\",\n  aliases: [\"C\"],\n});\n// Fahrenheit's 5/9 isn't a terminating decimal — give it (and the derived\n// offset) as exact Rationals so conversions round-trip without drift.\nconst scale = new Rational(5, 9);\nconst fahrenheit = temperature.affine(\n  \"fahrenheit\",\n  { scale, offset: Rational.from(273.15).minus(new Rational(32).times(scale)) },\n  { symbol: \"°F\", aliases: [\"F\"] },\n);\n```\n\n### Fully custom transforms\n\nFor anything non-linear, provide an explicit inverse pair:\n\n```ts\nconst dim = new Dimension(\"custom\");\ndim.base(\"base\");\ndim.custom(\"squared\", {\n  toBase: (x) => x * x,\n  fromBase: (x) => Math.sqrt(x),\n});\n```\n\n### Generating SI prefixes\n\n`definePrefixed` adds the metric prefix ladder to a reference **unit** and returns the\ncreated units keyed by name (skipping any name that already exists). It reads the\nreference's `name`, `symbol`, and scale straight off the unit (via `scaleOf`), so each\ngenerated unit gets a derived symbol (`b` → `kb`) and plural too — even when the\nreference isn't the base unit. Pass `SI_SUBMULTIPLE_PREFIXES` to generate fractions only.\n\n```ts\nimport { Dimension, Quantity, definePrefixed } from \"measurable\";\n\nconst data = new Dimension(\"data\");\nconst bit = data.base(\"bit\", { symbol: \"b\", plural: \"bits\" });\nconst prefixed = definePrefixed(data, bit);\n\nnew Quantity(1, prefixed.kilobit).in(bit);   // 1000  (SI kilo = 1e3)\nprefixed.kilobit.symbol;                     // \"kb\"\nnew Quantity(5, prefixed.kilobit).format({ unit: \"symbol\" }); // \"5 kb\"\n```\n\n### Tagging units into a measurement system\n\n```ts\nimport { MeasurementSystem } from \"measurable\";\n\nconst si = new MeasurementSystem(\"si\").add(byte, kilobyte, megabyte);\nsi.has(kilobyte); // true\n```\n\n## API reference\n\n### `Dimension`\n\n- `new Dimension(name)`\n- `.base(name, def?)` — define the canonical base unit\n- `.unit(name, scale, def?)` — linear unit (`scale` base units per unit; `number | Rational`)\n- `.affine(name, { scale, offset }, def?)` — linear with additive offset (each `number | Rational`)\n- `.custom(name, { toBase, fromBase }, def?)` — arbitrary inverse pair, for non-linear units\n- `.convert(value, from, to)` — convert a raw `number` between two of its units\n- `.convertRational(value, from, to)` → `Rational` — exact conversion between two of its units\n- `.get(token)` — units matching a name/alias (`Unit[] | undefined`)\n- `.has(unit)`, `.units`, `.baseUnit`\n\n`def` is an optional `UnitDef`: `{ symbol?, plural?, aliases? }`. All three are\nregistered as parse tokens; `symbol`/`plural` are additionally stored on the `Unit`.\n\n### `Unit`\n\nA passive handle, normally created via a dimension's builder methods rather than\n`new Unit` directly. Read-only properties:\n\n- `.name` — the unit's canonical name\n- `.symbol?` — canonical symbol (e.g. `\"g\"`, `\"km\"`), if declared\n- `.plural?` — plural name (e.g. `\"grams\"`), if declared\n- `.dimension` — the `Dimension` it belongs to\n- `.linear` → `{ scale: Rational; offset: Rational } | undefined` — the exact transform for linear/affine units (`undefined` for `custom` ones)\n- `.toBase(value)` → `number` — convert a value in this unit to base units\n- `.fromBase(value)` → `number` — convert a value in base units to this unit\n\n### `Quantity`\n\n- `new Quantity(magnitude, unit)` — `magnitude` is a `number | Rational`; throws on a non-finite `number`\n- `.magnitude` → `number` — getter, derived from `.rational`\n- `.rational` → `Rational` — the exact magnitude (source of truth)\n- `.to(target)` → `Quantity`\n- `.in(target)` → `number`\n- `.toString()` → `string` — stable `\"<magnitude> <name>\"`, e.g. `\"5 kilometer\"`\n- `.format({ unit?, locale?, numberFormat? })` → `string` — `unit`: `\"auto\"` (default, magnitude-aware) / `\"name\"` / `\"plural\"` / `\"symbol\"`; `locale` + `numberFormat` localize the magnitude via `toLocaleString`\n- `.formatParts(options?)` → `{ magnitude, unit }` — same options as `.format`, but returns the rendered pieces separately for custom assembly (e.g. JSX)\n- `.plus(other)` / `.minus(other)` → `Quantity` — add/subtract another quantity (aliases: `add` / `sub`)\n- `.times(factor)` / `.dividedBy(divisor)` → `Quantity` — scale by a `number | Rational` (aliases: `mul` / `div`)\n- `.ratioTo(other)` → `number` — dimensionless ratio (how many of `other` fit in this)\n- `.negate()` / `.abs()` → `Quantity`\n- `.clamp(lower, upper)` → `Quantity` — bound to a range, in this unit\n- `.round(decimals?)` → `Quantity` — round the magnitude (default 0 decimals)\n- `.best(...units)` → `Quantity` — re-express in the largest given unit whose absolute magnitude is still ≥ 1 (smallest as fallback); needs ≥ 1 unit, all of this dimension\n- `.equals(other)` / `.notEquals(other)` → `boolean` (aliases: `eq` / `ne`)\n- `.lessThan(other)` / `.greaterThan(other)` → `boolean` (aliases: `lt` / `gt`)\n- `.lessThanOrEqual(other)` / `.greaterThanOrEqual(other)` → `boolean` (aliases: `lte` / `gte`)\n- `.compareTo(other)` → `-1 | 0 | 1` — sort comparator\n- `.isZero()` / `.isPositive()` / `.isNegative()` → `boolean`\n- `Quantity.min(...quantities)` / `Quantity.max(...quantities)` / `Quantity.sum(...quantities)` → `Quantity`\n- `Quantity.parse(input, dimension, { prefer? })` → `Quantity`\n\n### `Rational`\n\nAn exact rational number (`n / d`), stored as `bigint`s in lowest terms with a\npositive denominator. Immutable; every operation returns a new `Rational`. Used\ninternally for lossless conversions and arithmetic, but you can construct one to\npass anywhere a magnitude or scale is accepted.\n\n- `new Rational(numerator, denominator?)` — from integers (`bigint | number`; denominator defaults to `1`). Throws on a non-integer `number` or a zero denominator.\n- `Rational.from(value)` — coerce a `number | Rational` (a `number` is read as its exact terminating decimal, e.g. `0.0254` → `254/10000`)\n- `.n` / `.d` → `bigint` — numerator and denominator\n- `.plus(other)` / `.minus(other)` / `.times(other)` / `.dividedBy(other)` → `Rational` (aliases: `add` / `sub` / `mul` / `div`)\n- `.negate()` / `.abs()` → `Rational`\n- `.equals(other)` → `boolean` (alias: `eq`)\n- `.compare(other)` → `-1 | 0 | 1`\n- `.sign()` → `-1 | 0 | 1`\n- `.toNumber()` → `number` — collapse to the nearest `number`\n\n### `MeasurementSystem`\n\n- `new MeasurementSystem(name)`\n- `.add(...units)`, `.has(unit)`\n- `.in(dimension)` → `Unit[]`\n- `.express(quantity)` → `Quantity`\n\n### Errors\n\nAll extend the built-in `Error` (so existing `catch` blocks still catch them) and\nare exported from `measurable`, letting you branch on the failure with\n`instanceof`:\n\n- `DimensionMismatchError` — an operation was attempted on units from different dimensions (converting, comparing, or combining them). Exported as `InvalidConversionError` too, a deprecated alias of the same class.\n- `UnknownUnitError` — a parsed token matches no unit\n- `AmbiguousUnitError` — a parsed token matches several units and no `prefer` was given\n- `ParseError` — a string could not be parsed into a quantity at all\n- `DuplicateUnitError` — a unit name already exists in its dimension\n- `UnsupportedDimensionError` — a system has no units of a dimension to `express` in\n- `ArgumentError` — an argument was invalid (e.g. `best()` with no units, or a non-integer / zero-denominator / non-finite `Rational`)\n\n## Changelog\n\nSee [CHANGELOG.md](https://github.com/mhuggins/measurable/blob/main/CHANGELOG.md)\nfor release notes. Note that v2.0.0 is a breaking release — see its entry for the\nmigration details.\n\n## License\n\nISC\n"
 }