measurable 1.1.1 → 3.0.0

package/dist/lib/Quantity.js

@@ -1,27 +1,89 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Quantity = void 0;
+const assert_never_1 = require("assert-never");
 const AmbiguousUnitError_1 = require("../errors/AmbiguousUnitError");
 const UnknownUnitError_1 = require("../errors/UnknownUnitError");
-const scale_1 = require("./scale");
+const scaleOf_1 = require("../utils/scaleOf");
+const Rational_1 = require("./Rational");
 /** A magnitude paired with a unit (e.g. `5` `kilometer`). */
 class Quantity {
     constructor(magnitude, unit) {
-        this.magnitude = magnitude;
         this.unit = unit;
+        this.rational = Rational_1.Rational.from(magnitude);
+    }
+    /** The magnitude as a `number`, derived from {@link rational}. */
+    get magnitude() {
+        return this.rational.toNumber();
     }
     /** Return an equivalent quantity expressed in `target`. */
     to(target) {
-        return new Quantity(this.in(target), target);
+        return new Quantity(this.inRational(target), target);
     }
     /** Return this quantity's raw magnitude expressed in `target`. */
     in(target) {
-        return this.unit.dimension.convert(this.magnitude, this.unit, target);
+        return this.inRational(target).toNumber();
+    }
+    /** This quantity's exact magnitude expressed in `target`. */
+    inRational(target) {
+        return this.unit.dimension.convertRational(this.rational, this.unit, target);
     }
     /** Render as `"<magnitude> <unit name>"`, e.g. `"5 kilometer"`. */
     toString() {
         return `${this.magnitude} ${this.unit.name}`;
     }
+    /**
+     * Render as `"<magnitude> <label>"`, choosing the label per `options.unit`
+     * (default `"auto"`: magnitude-aware singular/plural). Unlike {@link toString},
+     * this can use the unit's symbol or plural — e.g. `"5 grams"`, `"5 g"`,
+     * `"1 gram"`. Pass `locale` / `numberFormat` to localize the magnitude via
+     * `toLocaleString` — e.g. `format({ locale: "de-DE" })` → `"1.234,5 meters"`,
+     * or `format({ numberFormat: { maximumFractionDigits: 2 } })` for precision.
+     *
+     * For non-string output (e.g. JSX), use {@link formatParts} and assemble the
+     * pieces yourself.
+     */
+    format(options = {}) {
+        const { magnitude, unit } = this.formatParts(options);
+        return `${magnitude} ${unit}`;
+    }
+    /**
+     * Like {@link format}, but returns the rendered magnitude and label as
+     * separate strings instead of joining them, so the caller controls the
+     * assembly. Useful when a single string won't do — e.g. styling the magnitude
+     * in a React component:
+     *
+     * ```tsx
+     * const { magnitude, unit } = q.formatParts({ locale: "de-DE" });
+     * return <><b>{magnitude}</b> {unit}</>;
+     * ```
+     */
+    formatParts(options = {}) {
+        return { magnitude: this.formatMagnitude(options), unit: this.formatLabel(options) };
+    }
+    /**
+     * Render the magnitude via `toLocaleString`. With no `locale`/`numberFormat`
+     * it uses the runtime's default locale; supply either for locale- and
+     * precision-aware formatting.
+     */
+    formatMagnitude({ locale, numberFormat }) {
+        return this.magnitude.toLocaleString(locale, numberFormat);
+    }
+    formatLabel({ unit = "auto" }) {
+        const { name, symbol, plural } = this.unit;
+        switch (unit) {
+            case "symbol":
+                return symbol ?? name;
+            case "name":
+                return name;
+            case "plural":
+                return plural ?? name;
+            case "auto":
+                return Math.abs(this.magnitude) === 1 ? name : (plural ?? name);
+            default:
+                return (0, assert_never_1.assertNever)(unit);
+        }
+    }
     /**
      * 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
@@ -33,19 +95,19 @@ class Quantity {
      * difference.
      */
     plus(other) {
-        return new Quantity(this.magnitude + other.in(this.unit), this.unit);
+        return new Quantity(this.rational.plus(other.inRational(this.unit)), this.unit);
     }
     /** Subtract another quantity, returned in this quantity's unit. */
     minus(other) {
-        return new Quantity(this.magnitude - other.in(this.unit), this.unit);
+        return new Quantity(this.rational.minus(other.inRational(this.unit)), this.unit);
     }
     /** Scale this quantity by a dimensionless factor. */
     times(factor) {
-        return new Quantity(this.magnitude * factor, this.unit);
+        return new Quantity(this.rational.times(Rational_1.Rational.from(factor)), this.unit);
     }
     /** Divide this quantity by a dimensionless divisor. */
     dividedBy(divisor) {
-        return new Quantity(this.magnitude / divisor, this.unit);
+        return new Quantity(this.rational.dividedBy(Rational_1.Rational.from(divisor)), this.unit);
     }
     /**
      * Divide this quantity by `other` of the same dimension, yielding the
@@ -54,15 +116,15 @@ class Quantity {
      * Throws {@link InvalidConversionError} across dimensions.
      */
     ratioTo(other) {
-        return this.magnitude / other.in(this.unit);
+        return this.rational.dividedBy(other.inRational(this.unit)).toNumber();
     }
     /** Return this quantity with its magnitude negated. */
     negate() {
-        return new Quantity(-this.magnitude, this.unit);
+        return new Quantity(this.rational.negate(), this.unit);
     }
     /** Return this quantity with a non-negative magnitude. */
     abs() {
-        return new Quantity(Math.abs(this.magnitude), this.unit);
+        return new Quantity(this.rational.abs(), this.unit);
     }
     /** Clamp this quantity to the range [`lower`, `upper`], returned in this unit. */
     clamp(lower, upper) {
@@ -98,11 +160,12 @@ class Quantity {
     /**
      * Whether this quantity equals `other`, compared in this quantity's unit.
      * Throws {@link InvalidConversionError} if the operands belong to different
-     * dimensions. Comparison is exact, so values that differ only by
-     * floating-point rounding from a conversion may compare unequal.
+     * 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.
      */
     equals(other) {
-        return this.magnitude === other.in(this.unit);
+        return this.rational.equals(other.inRational(this.unit));
     }
     /** Whether this quantity does not equal `other`. */
     notEquals(other) {
@@ -110,19 +173,19 @@ class Quantity {
     }
     /** Whether this quantity is less than `other`. */
     lessThan(other) {
-        return this.magnitude < other.in(this.unit);
+        return this.rational.compare(other.inRational(this.unit)) < 0;
     }
     /** Whether this quantity is greater than `other`. */
     greaterThan(other) {
-        return this.magnitude > other.in(this.unit);
+        return this.rational.compare(other.inRational(this.unit)) > 0;
     }
     /** Whether this quantity is less than or equal to `other`. */
     lessThanOrEqual(other) {
-        return this.magnitude <= other.in(this.unit);
+        return this.rational.compare(other.inRational(this.unit)) <= 0;
     }
     /** Whether this quantity is greater than or equal to `other`. */
     greaterThanOrEqual(other) {
-        return this.magnitude >= other.in(this.unit);
+        return this.rational.compare(other.inRational(this.unit)) >= 0;
     }
     /** Alias for {@link equals}. */
     eq(other) {
@@ -153,26 +216,19 @@ class Quantity {
      * if larger, `0` if equal. Suitable as an `Array#sort` comparator.
      */
     compareTo(other) {
-        const value = other.in(this.unit);
-        if (this.magnitude < value) {
-            return -1;
-        }
-        if (this.magnitude > value) {
-            return 1;
-        }
-        return 0;
+        return this.rational.compare(other.inRational(this.unit));
     }
     /** Whether this quantity's magnitude is exactly zero. */
     isZero() {
-        return this.magnitude === 0;
+        return this.rational.sign() === 0;
     }
     /** Whether this quantity's magnitude is greater than zero. */
     isPositive() {
-        return this.magnitude > 0;
+        return this.rational.sign() > 0;
     }
     /** Whether this quantity's magnitude is less than zero. */
     isNegative() {
-        return this.magnitude < 0;
+        return this.rational.sign() < 0;
     }
     /**
      * Parse a string into a `Quantity` using a dimension's known units and aliases.
@@ -181,7 +237,7 @@ class Quantity {
      *  - `"5 hr"`       -> `Quantity(5, hour)`
      *  - `"5hr 20min"`  -> `Quantity(320, minute)`
      *
-     * Compound inputs are summed in base units and returned in the *finest*
+     * Compound inputs are summed (exactly) and returned in the *finest*
      * (smallest-scale) unit present, so `"5hr 20min"` collapses to `320 minute`.
      *
      * When a token is a shared alias (e.g. `"ton"` → short ton & long ton), pass
@@ -189,22 +245,21 @@ class Quantity {
      */
     static parse(str, dimension, options = {}) {
         const pattern = /(-?\d+(?:\.\d+)?)\s*([^\d\s]+)/g;
-        let total = 0; // accumulated in base units
+        let total;
         let finest;
-        let count = 0;
         for (let match = pattern.exec(str); match !== null; match = pattern.exec(str)) {
             const value = Number.parseFloat(match[1]);
             const unit = resolve(match[2], dimension, options.prefer);
-            total += unit.toBase(value);
-            if (!finest || (0, scale_1.scaleOf)(unit) < (0, scale_1.scaleOf)(finest)) {
+            const quantity = new Quantity(value, unit);
+            total = total ? total.plus(quantity) : quantity;
+            if (!finest || (0, scaleOf_1.scaleOf)(unit) < (0, scaleOf_1.scaleOf)(finest)) {
                 finest = unit;
             }
-            count += 1;
         }
-        if (count === 0 || !finest) {
+        if (!total || !finest) {
             throw new Error(`Could not parse a quantity from "${str}"`);
         }
-        return new Quantity(finest.fromBase(total), finest);
+        return total.to(finest);
     }
     /** The smallest of the given quantities (by value); requires at least one. */
     static min(first, ...rest) {

package/dist/lib/Rational.d.ts

@@ -0,0 +1,58 @@
+/**
+ * An exact rational number (`n / d`) used to make conversions between linear
+ * and affine units lossless. Such conversions are inherently rational — a foot
+ * is exactly `3048/10000` m and an inch exactly `254/10000` m, so foot → inch is
+ * exactly `12` — but baking those ratios into binary `number` scales rounds the
+ * result (`12.000000000000002`). Doing the arithmetic over integer numerator /
+ * denominator pairs and collapsing to a float only at the end avoids the drift.
+ *
+ * Instances are immutable and always stored in lowest terms with a positive
+ * denominator. `bigint` is used so cross-multiplying large scales (e.g. a
+ * mile's `1609344`) cannot overflow.
+ */
+export declare class Rational {
+    readonly n: bigint;
+    readonly d: bigint;
+    /**
+     * Build a rational from integer numerator and denominator. Pass exact ratios
+     * the literal way — `new Rational(5, 9)` — using `bigint` or integer `number`.
+     * For a decimal value, use {@link Rational.from} instead.
+     */
+    constructor(numerator: bigint | number, denominator?: bigint | number);
+    /** Coerce a `number | Rational` to a `Rational`, parsing numbers as decimals. */
+    static from(value: number | Rational): Rational;
+    /**
+     * Convert a `number` to the exact rational the author *wrote*, by reading its
+     * shortest round-tripping decimal (`(0.0254).toString() === "0.0254"` →
+     * `254/10000`). This recovers the intended terminating decimal. A value that
+     * was never terminating in source (e.g. Fahrenheit's `5 / 9`) is captured as
+     * the exact rational of its nearest double — no worse than a raw float, and
+     * the conversion is still done in one rounding instead of several. To avoid
+     * that, pass an exact {@link Rational} (e.g. `new Rational(5, 9)`) instead.
+     */
+    private static fromNumber;
+    plus(other: Rational): Rational;
+    minus(other: Rational): Rational;
+    times(other: Rational): Rational;
+    dividedBy(other: Rational): Rational;
+    negate(): Rational;
+    abs(): Rational;
+    /** Whether this equals `other` exactly (both are stored in canonical form). */
+    equals(other: Rational): boolean;
+    /** Alias for {@link plus}. */
+    add(other: Rational): Rational;
+    /** Alias for {@link minus}. */
+    sub(other: Rational): Rational;
+    /** Alias for {@link times}. */
+    mul(other: Rational): Rational;
+    /** Alias for {@link dividedBy}. */
+    div(other: Rational): Rational;
+    /** Alias for {@link equals}. */
+    eq(other: Rational): boolean;
+    /** `-1` if this is smaller than `other`, `1` if larger, `0` if equal. */
+    compare(other: Rational): number;
+    /** Sign of the value: `-1`, `0`, or `1`. */
+    sign(): number;
+    /** Collapse to the nearest `number`. */
+    toNumber(): number;
+}

package/dist/lib/Rational.js

@@ -0,0 +1,174 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Rational = void 0;
+/**
+ * An exact rational number (`n / d`) used to make conversions between linear
+ * and affine units lossless. Such conversions are inherently rational — a foot
+ * is exactly `3048/10000` m and an inch exactly `254/10000` m, so foot → inch is
+ * exactly `12` — but baking those ratios into binary `number` scales rounds the
+ * result (`12.000000000000002`). Doing the arithmetic over integer numerator /
+ * denominator pairs and collapsing to a float only at the end avoids the drift.
+ *
+ * Instances are immutable and always stored in lowest terms with a positive
+ * denominator. `bigint` is used so cross-multiplying large scales (e.g. a
+ * mile's `1609344`) cannot overflow.
+ */
+class Rational {
+    /**
+     * Build a rational from integer numerator and denominator. Pass exact ratios
+     * the literal way — `new Rational(5, 9)` — using `bigint` or integer `number`.
+     * For a decimal value, use {@link Rational.from} instead.
+     */
+    constructor(numerator, denominator = 1n) {
+        let n = toBigInt(numerator);
+        let d = toBigInt(denominator);
+        if (d === 0n) {
+            throw new Error("Rational denominator cannot be zero");
+        }
+        if (d < 0n) {
+            n = -n;
+            d = -d;
+        }
+        const g = gcd(n, d) || 1n;
+        this.n = n / g;
+        this.d = d / g;
+    }
+    /** Coerce a `number | Rational` to a `Rational`, parsing numbers as decimals. */
+    static from(value) {
+        return value instanceof Rational ? new this(value.n, value.d) : Rational.fromNumber(value);
+    }
+    /**
+     * Convert a `number` to the exact rational the author *wrote*, by reading its
+     * shortest round-tripping decimal (`(0.0254).toString() === "0.0254"` →
+     * `254/10000`). This recovers the intended terminating decimal. A value that
+     * was never terminating in source (e.g. Fahrenheit's `5 / 9`) is captured as
+     * the exact rational of its nearest double — no worse than a raw float, and
+     * the conversion is still done in one rounding instead of several. To avoid
+     * that, pass an exact {@link Rational} (e.g. `new Rational(5, 9)`) instead.
+     */
+    static fromNumber(value) {
+        if (!Number.isFinite(value)) {
+            throw new Error(`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}`);
+        }
+        const [, sign, intPart, fracPart = "", expPart] = match;
+        let n = BigInt(intPart + fracPart);
+        let d = 10n ** BigInt(fracPart.length);
+        const exp = expPart ? Number(expPart) : 0;
+        if (exp > 0) {
+            n *= 10n ** BigInt(exp);
+        }
+        else if (exp < 0) {
+            d *= 10n ** BigInt(-exp);
+        }
+        return new Rational(sign === "-" ? -n : n, d);
+    }
+    plus(other) {
+        return new Rational(this.n * other.d + other.n * this.d, this.d * other.d);
+    }
+    minus(other) {
+        return new Rational(this.n * other.d - other.n * this.d, this.d * other.d);
+    }
+    times(other) {
+        return new Rational(this.n * other.n, this.d * other.d);
+    }
+    dividedBy(other) {
+        return new Rational(this.n * other.d, this.d * other.n);
+    }
+    negate() {
+        return new Rational(-this.n, this.d);
+    }
+    abs() {
+        return new Rational(this.n < 0n ? -this.n : this.n, this.d);
+    }
+    /** Whether this equals `other` exactly (both are stored in canonical form). */
+    equals(other) {
+        return this.n === other.n && this.d === other.d;
+    }
+    /** Alias for {@link plus}. */
+    add(other) {
+        return this.plus(other);
+    }
+    /** Alias for {@link minus}. */
+    sub(other) {
+        return this.minus(other);
+    }
+    /** Alias for {@link times}. */
+    mul(other) {
+        return this.times(other);
+    }
+    /** Alias for {@link dividedBy}. */
+    div(other) {
+        return this.dividedBy(other);
+    }
+    /** Alias for {@link equals}. */
+    eq(other) {
+        return this.equals(other);
+    }
+    /** `-1` if this is smaller than `other`, `1` if larger, `0` if equal. */
+    compare(other) {
+        // Denominators are always positive, so cross-multiplication preserves order.
+        const lhs = this.n * other.d;
+        const rhs = other.n * this.d;
+        return lhs < rhs ? -1 : lhs > rhs ? 1 : 0;
+    }
+    /** Sign of the value: `-1`, `0`, or `1`. */
+    sign() {
+        return this.n < 0n ? -1 : this.n > 0n ? 1 : 0;
+    }
+    /** Collapse to the nearest `number`. */
+    toNumber() {
+        const { n, d } = this;
+        if (n === 0n) {
+            return 0;
+        }
+        // Fast path: both operands are exactly representable as doubles, so a single
+        // IEEE division is correctly rounded.
+        if (n >= -MAX_EXACT_INT && n <= MAX_EXACT_INT && d <= MAX_EXACT_INT) {
+            return Number(n) / Number(d);
+        }
+        // Otherwise converting each operand to a double first would round it before
+        // dividing and lose precision (e.g. denominators like 10^24). Long-divide to
+        // SIG significant digits and let Number()'s correctly-rounded decimal parser
+        // produce the nearest double, independent of magnitude.
+        const SIG = 20;
+        const negative = n < 0n;
+        const num = negative ? -n : n;
+        // floor(log10(num / d)), accurate to within 1 — enough to capture SIG digits.
+        const exponent = num.toString().length - d.toString().length;
+        const shift = SIG - 1 - exponent;
+        const scaledNum = shift >= 0 ? num * 10n ** BigInt(shift) : num;
+        const scaledDen = shift >= 0 ? d : d * 10n ** BigInt(-shift);
+        let digits = scaledNum / scaledDen;
+        if (2n * (scaledNum % scaledDen) >= scaledDen) {
+            digits += 1n; // round half up on the last significant digit
+        }
+        return Number(`${negative ? "-" : ""}${digits}e${exponent - (SIG - 1)}`);
+    }
+}
+exports.Rational = Rational;
+/**
+ * One past `Number.MAX_SAFE_INTEGER` (i.e. 2^53): every integer with magnitude
+ * at most this is exactly representable as a double, so `Number(n)` is lossless.
+ */
+const MAX_EXACT_INT = BigInt(Number.MAX_SAFE_INTEGER) + 1n;
+function gcd(a, b) {
+    let x = a < 0n ? -a : a;
+    let y = b < 0n ? -b : b;
+    while (y) {
+        [x, y] = [y, x % y];
+    }
+    return x;
+}
+function toBigInt(value) {
+    if (typeof value === "bigint") {
+        return value;
+    }
+    if (!Number.isInteger(value)) {
+        throw new Error(`Rational numerator and denominator must be integers; got ${value}`);
+    }
+    return BigInt(value);
+}

package/dist/lib/Unit.d.ts

@@ -1,26 +1,55 @@
 import type { Dimension } from "./Dimension";
-interface UnitOptions {
+import type { Rational } from "./Rational";
+/**
+ * An affine transform to the base unit, `base = value * scale + offset`, with
+ * both terms held as exact rationals. Covers the base unit (`1·x + 0`), plain
+ * linear units (`scale·x + 0`), and offset units like Celsius (`1·x + 273.15`).
+ */
+export interface LinearTransform {
+    scale: Rational;
+    offset: Rational;
+}
+export interface BaseUnitOptions {
     name: string;
     dimension: Dimension;
+    /** Canonical symbol, e.g. `"g"`, `"km"`, `"°C"` (optional). */
+    symbol?: string;
+    /** Plural name, e.g. `"grams"`, `"kilometers"` (optional). */
+    plural?: string;
+}
+export type UnitConversionOptions = {
+    /** Exact transform for linear / affine units (the common case). */
+    linear: LinearTransform;
+} | {
+    /** Hand-written transform for non-linear units; mutually exclusive with `linear`. */
     toBase: (value: number) => number;
     fromBase: (value: number) => number;
-}
+};
+export type UnitOptions = BaseUnitOptions & UnitConversionOptions;
 /**
  * A single unit of measurement (e.g. "meter", "celsius").
  *
  * A `Unit` is a passive handle: it knows its name, its home {@link Dimension},
  * and how to transform a value to and from that dimension's canonical base
  * unit. It does NOT know about other units or store pairwise conversions — all
- * conversion math lives in {@link Dimension}, derived from these two transforms.
- * Because the reverse direction (`fromBase`) is the mathematical inverse of the
- * forward direction (`toBase`), the two can never fall out of sync.
+ * conversion math lives in {@link Dimension}, derived from this transform.
+ *
+ * Almost every unit relates to the base by an affine map (`value * scale +
+ * offset`), so the transform is normally a {@link LinearTransform} of exact
+ * rationals — a single source of truth from which {@link toBase} / {@link
+ * fromBase} are derived, and which lets {@link Dimension.convert} stay exact.
+ * Only genuinely non-linear units (e.g. logarithmic scales, defined via
+ * `Dimension.custom`) fall back to a hand-written `toBase` / `fromBase` pair,
+ * since no `scale`/`offset` can express a curve like `10^x`.
  *
  * A unit belongs to exactly one dimension, but may belong to many
  * {@link MeasurementSystem}s (metric/imperial/…); that membership lives on the
  * measurement systems, not here, so a `Unit` stays a lean descriptor.
  *
- * Names and aliases live solely in the dimension's lookup index; they are
- * declared once when the unit is defined.
+ * Parsing aliases live in the dimension's lookup index. A unit additionally
+ * carries its canonical {@link symbol} and {@link plural} as first-class data
+ * so callers can choose how to render it (see {@link Quantity.format}); both are
+ * optional and English-centric — real localization is left to the consumer.
  *
  * Units are normally created through a {@link Dimension}'s builder methods
  * (`base`, `unit`, `affine`, `custom`) rather than constructed directly.
@@ -28,8 +57,20 @@ interface UnitOptions {
 export declare class Unit {
     readonly name: string;
     readonly dimension: Dimension;
-    readonly toBase: (value: number) => number;
-    readonly fromBase: (value: number) => number;
-    constructor({ name, dimension, toBase, fromBase }: UnitOptions);
+    /** Canonical symbol, e.g. `"g"`, `"km"`, `"°C"` (optional). */
+    readonly symbol?: string;
+    /** Plural name, e.g. `"grams"`, `"kilometers"` (optional). */
+    readonly plural?: string;
+    private readonly conversion;
+    constructor({ name, dimension, symbol, plural, ...conversionOptions }: UnitOptions);
+    /**
+     * Exact affine transform to the base unit, present for all but non-linear
+     * units. When both ends of a conversion have one, {@link Dimension.convert}
+     * routes through exact rational arithmetic instead of lossy float scaling.
+     */
+    get linear(): LinearTransform | undefined;
+    /** Convert a value in this unit to the dimension's base unit. */
+    toBase(value: number): number;
+    /** Convert a value in the dimension's base unit to this unit. */
+    fromBase(value: number): number;
 }
-export {};

package/dist/lib/Unit.js

@@ -7,26 +7,59 @@ exports.Unit = void 0;
  * A `Unit` is a passive handle: it knows its name, its home {@link Dimension},
  * and how to transform a value to and from that dimension's canonical base
  * unit. It does NOT know about other units or store pairwise conversions — all
- * conversion math lives in {@link Dimension}, derived from these two transforms.
- * Because the reverse direction (`fromBase`) is the mathematical inverse of the
- * forward direction (`toBase`), the two can never fall out of sync.
+ * conversion math lives in {@link Dimension}, derived from this transform.
+ *
+ * Almost every unit relates to the base by an affine map (`value * scale +
+ * offset`), so the transform is normally a {@link LinearTransform} of exact
+ * rationals — a single source of truth from which {@link toBase} / {@link
+ * fromBase} are derived, and which lets {@link Dimension.convert} stay exact.
+ * Only genuinely non-linear units (e.g. logarithmic scales, defined via
+ * `Dimension.custom`) fall back to a hand-written `toBase` / `fromBase` pair,
+ * since no `scale`/`offset` can express a curve like `10^x`.
  *
  * A unit belongs to exactly one dimension, but may belong to many
  * {@link MeasurementSystem}s (metric/imperial/…); that membership lives on the
  * measurement systems, not here, so a `Unit` stays a lean descriptor.
  *
- * Names and aliases live solely in the dimension's lookup index; they are
- * declared once when the unit is defined.
+ * Parsing aliases live in the dimension's lookup index. A unit additionally
+ * carries its canonical {@link symbol} and {@link plural} as first-class data
+ * so callers can choose how to render it (see {@link Quantity.format}); both are
+ * optional and English-centric — real localization is left to the consumer.
  *
  * Units are normally created through a {@link Dimension}'s builder methods
  * (`base`, `unit`, `affine`, `custom`) rather than constructed directly.
  */
 class Unit {
-    constructor({ name, dimension, toBase, fromBase }) {
+    constructor({ name, dimension, symbol, plural, ...conversionOptions }) {
         this.name = name;
         this.dimension = dimension;
-        this.toBase = toBase;
-        this.fromBase = fromBase;
+        this.symbol = symbol;
+        this.plural = plural;
+        this.conversion = conversionOptions;
+    }
+    /**
+     * Exact affine transform to the base unit, present for all but non-linear
+     * units. When both ends of a conversion have one, {@link Dimension.convert}
+     * routes through exact rational arithmetic instead of lossy float scaling.
+     */
+    get linear() {
+        return "linear" in this.conversion ? this.conversion.linear : undefined;
+    }
+    /** Convert a value in this unit to the dimension's base unit. */
+    toBase(value) {
+        if ("linear" in this.conversion) {
+            const linear = this.conversion.linear;
+            return value * linear.scale.toNumber() + linear.offset.toNumber();
+        }
+        return this.conversion.toBase(value);
+    }
+    /** Convert a value in the dimension's base unit to this unit. */
+    fromBase(value) {
+        if ("linear" in this.conversion) {
+            const linear = this.conversion.linear;
+            return (value - linear.offset.toNumber()) / linear.scale.toNumber();
+        }
+        return this.conversion.fromBase(value);
     }
 }
 exports.Unit = Unit;

package/dist/lib/prefixes.d.ts

@@ -16,8 +16,8 @@ export interface PrefixReference {
     name: string;
     /** Primary symbol, e.g. "m" → "km", "mm", … */
     symbol: string;
-    /** Scale of the reference relative to its dimension's base (meter → 1, gram → 0.001). */
-    scale: number;
+    /** Scale of the reference relative to its dimension's base (meter → 1, gram → 0.001) (default 1). */
+    scale?: number;
 }
 /**
  * Define metric-prefixed variants of a reference unit on a dimension. Each

package/dist/lib/prefixes.js

@@ -50,7 +50,7 @@ function definePrefixed(dimension, reference, prefixes = exports.SI_PREFIXES) {
         if (prefix.name === "micro") {
             aliases.push(`u${reference.symbol}`);
         }
-        units[name] = dimension.unit(name, reference.scale * prefix.factor, aliases);
+        units[name] = dimension.unit(name, (reference.scale ?? 1) * prefix.factor, aliases);
     }
     return units;
 }