measurable 1.1.1 → 3.0.0

package/dist/index.d.ts

@@ -3,6 +3,7 @@ export * from "./errors/InvalidConversionError";
 export * from "./errors/UnknownUnitError";
 export * from "./lib/Dimension";
 export * from "./lib/MeasurementSystem";
-export * from "./lib/prefixes";
 export * from "./lib/Quantity";
+export * from "./lib/Rational";
 export * from "./lib/Unit";
+export * from "./utils/definePrefixed";

package/dist/index.js

@@ -19,6 +19,7 @@ __exportStar(require("./errors/InvalidConversionError"), exports);
 __exportStar(require("./errors/UnknownUnitError"), exports);
 __exportStar(require("./lib/Dimension"), exports);
 __exportStar(require("./lib/MeasurementSystem"), exports);
-__exportStar(require("./lib/prefixes"), exports);
 __exportStar(require("./lib/Quantity"), exports);
+__exportStar(require("./lib/Rational"), exports);
 __exportStar(require("./lib/Unit"), exports);
+__exportStar(require("./utils/definePrefixed"), exports);

package/dist/lib/Dimension.d.ts

@@ -1,26 +1,44 @@
+import { Rational } from "./Rational";
 import { Unit } from "./Unit";
 /** A linear unit with an additive offset (e.g. temperature scales). */
 export interface AffineSpec {
-    /** Multiplier applied when converting a value to the base unit. */
-    scale: number;
+    /**
+     * Multiplier applied when converting a value to the base unit. Pass a
+     * {@link Rational} (e.g. `new Rational(5, 9)`) for ratios that a decimal
+     * cannot represent exactly.
+     */
+    scale: number | Rational;
     /** Constant added (in base units) after scaling. */
-    offset: number;
+    offset: number | Rational;
 }
 /** A fully custom transform pair for non-linear units. */
 export interface CustomSpec {
     toBase: (value: number) => number;
     fromBase: (value: number) => number;
 }
+/** Optional descriptors for a unit: its symbol, plural, and extra parse aliases. */
+export interface UnitDef {
+    /** Canonical symbol, e.g. `"g"`, `"km"`, `"°C"`. Also registered for parsing. */
+    symbol?: string;
+    /** Plural name, e.g. `"grams"`. Also registered for parsing. */
+    plural?: string;
+    /** Additional names this unit parses from (beyond name, symbol, and plural). */
+    aliases?: string[];
+}
 /**
  * A dimension is a single *kind* of measurable quantity (length, volume, mass,
  * temperature, …). It owns one canonical **base unit** that every other unit in
  * the dimension is defined relative to, and it is the single place where all
  * conversion math happens.
  *
- * Converting `A → B` is always `B.fromBase(A.toBase(value))`: route through the
- * base unit. This gives transitive conversions for free (any unit ↔ any unit)
- * and means each unit only ever stores its relationship to the base — never a
- * redundant, drift-prone pair of factors.
+ * Converting `A → B` routes through the base unit — conceptually
+ * `B.fromBase(A.toBase(value))`. This gives transitive conversions for free
+ * (any unit ↔ any unit) and means each unit only ever stores its relationship
+ * to the base — never a redundant, drift-prone pair of factors. Linear and
+ * affine units carry that relationship as an exact {@link Rational} transform,
+ * so their conversions are done in rational arithmetic and collapsed to a float
+ * once at the end, avoiding the binary rounding of routing through the base.
+ * Only non-linear units (defined via {@link custom}) fall back to float.
  *
  * A dimension is distinct from a {@link MeasurementSystem} (metric/imperial/…):
  * the dimension decides what *can convert*, while a measurement system is a tag
@@ -39,21 +57,38 @@ export declare class Dimension {
     baseUnit?: Unit;
     constructor(name: string);
     /** Define the canonical base unit (identity transform). */
-    base(name: string, aliases?: string[]): Unit;
+    base(name: string, def?: UnitDef): Unit;
     /**
      * Define a linear unit. `scale` is how many base units make up one of this
-     * unit (e.g. a kilometer is `1000` meters).
+     * unit (e.g. a kilometer is `1000` meters). Pass a {@link Rational} for a
+     * scale a decimal cannot represent exactly.
      */
-    unit(name: string, scale: number, aliases?: string[]): Unit;
+    unit(name: string, scale: number | Rational, def?: UnitDef): Unit;
     /** Define an affine unit (scale plus additive offset, e.g. °C against K). */
-    affine(name: string, { scale, offset }: AffineSpec, aliases?: string[]): Unit;
-    /** Define a unit with an arbitrary, hand-written inverse transform pair. */
-    custom(name: string, { toBase, fromBase }: CustomSpec, aliases?: string[]): Unit;
-    /** Convert a value between two units of this dimension, routed through the base. */
+    affine(name: string, { scale, offset }: AffineSpec, def?: UnitDef): Unit;
+    /**
+     * Define a non-linear unit from an arbitrary, hand-written inverse transform
+     * pair. Reserve this for units that genuinely cannot be expressed as `value *
+     * scale + offset` — e.g. logarithmic scales (decibels, octaves). Linear and
+     * affine units should use {@link unit} / {@link affine} so conversions stay
+     * exact.
+     */
+    custom(name: string, { toBase, fromBase }: CustomSpec, def?: UnitDef): Unit;
+    /** Convert a `number` value between two units of this dimension. */
     convert(value: number, from: Unit, to: Unit): number;
+    /**
+     * Convert an exact {@link Rational} value between two units, routed through
+     * the base. Linear / affine units stay exact end-to-end (the result is never
+     * collapsed to a float here), which is what lets {@link Quantity} chain
+     * conversions without drift. A conversion touching a non-linear `custom` unit
+     * falls back to float math and recaptures the result as a rational.
+     */
+    convertRational(value: Rational, from: Unit, to: Unit): Rational;
     /** Resolve a name or alias to its candidate unit(s) (used by parsing). */
     get(token: string): Unit[] | undefined;
     has(unit: Unit): boolean;
+    /** Define a linear / affine unit from its exact rational transform. */
+    private defineLinear;
     private define;
     /** Append a name/alias → unit mapping; shared aliases accumulate candidates. */
     private register;

package/dist/lib/Dimension.js

@@ -2,17 +2,26 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Dimension = void 0;
 const InvalidConversionError_1 = require("../errors/InvalidConversionError");
+const Rational_1 = require("./Rational");
 const Unit_1 = require("./Unit");
+/** The rational `0`. */
+const zero = new Rational_1.Rational(0n);
+/** The rational `1`. */
+const one = new Rational_1.Rational(1n);
 /**
  * A dimension is a single *kind* of measurable quantity (length, volume, mass,
  * temperature, …). It owns one canonical **base unit** that every other unit in
  * the dimension is defined relative to, and it is the single place where all
  * conversion math happens.
  *
- * Converting `A → B` is always `B.fromBase(A.toBase(value))`: route through the
- * base unit. This gives transitive conversions for free (any unit ↔ any unit)
- * and means each unit only ever stores its relationship to the base — never a
- * redundant, drift-prone pair of factors.
+ * Converting `A → B` routes through the base unit — conceptually
+ * `B.fromBase(A.toBase(value))`. This gives transitive conversions for free
+ * (any unit ↔ any unit) and means each unit only ever stores its relationship
+ * to the base — never a redundant, drift-prone pair of factors. Linear and
+ * affine units carry that relationship as an exact {@link Rational} transform,
+ * so their conversions are done in rational arithmetic and collapsed to a float
+ * once at the end, avoiding the binary rounding of routing through the base.
+ * Only non-linear units (defined via {@link custom}) fall back to float.
  *
  * A dimension is distinct from a {@link MeasurementSystem} (metric/imperial/…):
  * the dimension decides what *can convert*, while a measurement system is a tag
@@ -30,35 +39,57 @@ class Dimension {
         this.index = new Map();
     }
     /** Define the canonical base unit (identity transform). */
-    base(name, aliases = []) {
-        const unit = this.define(name, (x) => x, (x) => x, aliases);
+    base(name, def = {}) {
+        const unit = this.defineLinear(name, { scale: one, offset: zero }, def);
         this.baseUnit = unit;
         return unit;
     }
     /**
      * Define a linear unit. `scale` is how many base units make up one of this
-     * unit (e.g. a kilometer is `1000` meters).
+     * unit (e.g. a kilometer is `1000` meters). Pass a {@link Rational} for a
+     * scale a decimal cannot represent exactly.
      */
-    unit(name, scale, aliases = []) {
-        return this.define(name, (x) => x * scale, (x) => x / scale, aliases);
+    unit(name, scale, def = {}) {
+        return this.defineLinear(name, { scale: Rational_1.Rational.from(scale), offset: zero }, def);
     }
     /** Define an affine unit (scale plus additive offset, e.g. °C against K). */
-    affine(name, { scale, offset }, aliases = []) {
-        return this.define(name, (x) => x * scale + offset, (x) => (x - offset) / scale, aliases);
+    affine(name, { scale, offset }, def = {}) {
+        return this.defineLinear(name, { scale: Rational_1.Rational.from(scale), offset: Rational_1.Rational.from(offset) }, def);
     }
-    /** Define a unit with an arbitrary, hand-written inverse transform pair. */
-    custom(name, { toBase, fromBase }, aliases = []) {
-        return this.define(name, toBase, fromBase, aliases);
+    /**
+     * Define a non-linear unit from an arbitrary, hand-written inverse transform
+     * pair. Reserve this for units that genuinely cannot be expressed as `value *
+     * scale + offset` — e.g. logarithmic scales (decibels, octaves). Linear and
+     * affine units should use {@link unit} / {@link affine} so conversions stay
+     * exact.
+     */
+    custom(name, { toBase, fromBase }, def = {}) {
+        return this.define(name, def, { toBase, fromBase });
     }
-    /** Convert a value between two units of this dimension, routed through the base. */
+    /** Convert a `number` value between two units of this dimension. */
     convert(value, from, to) {
+        return this.convertRational(Rational_1.Rational.from(value), from, to).toNumber();
+    }
+    /**
+     * Convert an exact {@link Rational} value between two units, routed through
+     * the base. Linear / affine units stay exact end-to-end (the result is never
+     * collapsed to a float here), which is what lets {@link Quantity} chain
+     * conversions without drift. A conversion touching a non-linear `custom` unit
+     * falls back to float math and recaptures the result as a rational.
+     */
+    convertRational(value, from, to) {
         if (!this.units.has(from) || !this.units.has(to)) {
             throw new InvalidConversionError_1.InvalidConversionError(from, to);
         }
         if (from === to) {
             return value;
         }
-        return to.fromBase(from.toBase(value));
+        if (from.linear && to.linear) {
+            // base = from.scale * value + from.offset; result = (base - to.offset) / to.scale
+            const base = from.linear.scale.times(value).plus(from.linear.offset);
+            return base.minus(to.linear.offset).dividedBy(to.linear.scale);
+        }
+        return Rational_1.Rational.from(to.fromBase(from.toBase(value.toNumber())));
     }
     /** Resolve a name or alias to its candidate unit(s) (used by parsing). */
     get(token) {
@@ -67,17 +98,23 @@ class Dimension {
     has(unit) {
         return this.units.has(unit);
     }
-    define(name, toBase, fromBase, aliases) {
+    /** Define a linear / affine unit from its exact rational transform. */
+    defineLinear(name, linear, def) {
+        return this.define(name, def, { linear });
+    }
+    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}"`);
             }
         }
-        const unit = new Unit_1.Unit({ name, dimension: this, toBase, fromBase });
+        const unit = new Unit_1.Unit({ name, dimension: this, symbol, plural, ...transform });
         this.units.add(unit);
-        this.register(name, unit);
-        for (const alias of aliases) {
-            this.register(alias, unit);
+        // Register every label this unit can be parsed from, de-duplicated so a unit
+        // never appears twice among a token's candidates (e.g. if symbol === name).
+        const tokens = new Set([name, symbol, plural, ...aliases].filter((t) => !!t));
+        for (const token of tokens) {
+            this.register(token, unit);
         }
         return unit;
     }

package/dist/lib/MeasurementSystem.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MeasurementSystem = void 0;
-const scale_1 = require("./scale");
+const scaleOf_1 = require("../utils/scaleOf");
 /**
  * A measurement system (metric, imperial, US customary, …) is a cross-dimension
  * collection of units that share a real-world standard.
@@ -37,7 +37,7 @@ 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, scale_1.scaleOf)(a) - (0, scale_1.scaleOf)(b));
+        const candidates = this.in(quantity.unit.dimension).sort((a, b) => (0, scaleOf_1.scaleOf)(a) - (0, scaleOf_1.scaleOf)(b));
         if (candidates.length === 0) {
             throw new Error(`Measurement system "${this.name}" has no ` +
                 `"${quantity.unit.dimension.name}" units to express in`);

package/dist/lib/Quantity.d.ts

@@ -1,22 +1,105 @@
 import type { Dimension } from "./Dimension";
 import type { MeasurementSystem } from "./MeasurementSystem";
+import { Rational } from "./Rational";
 import type { Unit } from "./Unit";
 /** Options for {@link Quantity.parse}. */
 export interface ParseOptions {
     /** Preferred measurement system, used only to break ties on shared aliases. */
     prefer?: MeasurementSystem;
 }
+/** Options for {@link Quantity.format}. */
+export interface FormatOptions {
+    /**
+     * Which label to render after the magnitude:
+     *  - `"auto"` (default) — singular `name` when the magnitude is exactly ±1,
+     *    otherwise the `plural`.
+     *  - `"name"` — always the singular name.
+     *  - `"plural"` — always the plural.
+     *  - `"symbol"` — the unit's symbol.
+     *
+     * `plural`/`symbol` fall back to the unit's `name` when that field is unset.
+     * Labels are English/canonical; localize the *magnitude* via {@link locale} /
+     * {@link numberFormat}.
+     */
+    unit?: "auto" | "name" | "plural" | "symbol";
+    /**
+     * BCP 47 locale(s) used to render the magnitude (e.g. `"de-DE"`, `["fr", "en"]`).
+     * Passed straight to `Number.prototype.toLocaleString`. When omitted, the
+     * runtime's default locale is used.
+     */
+    locale?: string | string[];
+    /**
+     * `Intl.NumberFormat` options for the magnitude — precision
+     * (`minimumFractionDigits` / `maximumFractionDigits`), `style: "currency"`,
+     * grouping, and so on. Passed straight to `Number.prototype.toLocaleString`.
+     */
+    numberFormat?: Intl.NumberFormatOptions;
+}
+/**
+ * The rendered pieces of a formatted quantity, as returned by
+ * {@link Quantity.formatParts}. Each is already a finished string; the caller
+ * decides how to assemble them (a plain join, JSX, a template, …).
+ */
+export interface FormattedParts {
+    /** The locale-formatted magnitude, e.g. `"1.234,5"`. */
+    magnitude: string;
+    /** The chosen unit label, e.g. `"kilometers"`, `"km"`. */
+    unit: string;
+}
 /** A magnitude paired with a unit (e.g. `5` `kilometer`). */
 export declare class Quantity {
-    magnitude: number;
-    unit: Unit;
-    constructor(magnitude: number, unit: Unit);
+    readonly unit: Unit;
+    /**
+     * The magnitude as an exact {@link Rational} — the source of truth this
+     * quantity is built on. Conversions and arithmetic operate on it directly, so
+     * a chain like `q.to(a).to(b)` stays exact instead of accumulating the binary
+     * rounding of repeated float round trips. (Exact for linear / affine units; a
+     * conversion through a non-linear `custom` unit recaptures a float as a
+     * rational, so it is best-effort there.)
+     */
+    readonly rational: Rational;
+    constructor(magnitude: number | Rational, unit: Unit);
+    /** The magnitude as a `number`, derived from {@link rational}. */
+    get magnitude(): number;
     /** Return an equivalent quantity expressed in `target`. */
     to(target: Unit): Quantity;
     /** Return this quantity's raw magnitude expressed in `target`. */
     in(target: Unit): number;
+    /** This quantity's exact magnitude expressed in `target`. */
+    private inRational;
     /** Render as `"<magnitude> <unit name>"`, e.g. `"5 kilometer"`. */
     toString(): string;
+    /**
+     * 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?: FormatOptions): string;
+    /**
+     * 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?: FormatOptions): FormattedParts;
+    /**
+     * Render the magnitude via `toLocaleString`. With no `locale`/`numberFormat`
+     * it uses the runtime's default locale; supply either for locale- and
+     * precision-aware formatting.
+     */
+    private formatMagnitude;
+    private formatLabel;
     /**
      * 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
@@ -31,9 +114,9 @@ export declare class Quantity {
     /** Subtract another quantity, returned in this quantity's unit. */
     minus(other: Quantity): Quantity;
     /** Scale this quantity by a dimensionless factor. */
-    times(factor: number): Quantity;
+    times(factor: number | Rational): Quantity;
     /** Divide this quantity by a dimensionless divisor. */
-    dividedBy(divisor: number): Quantity;
+    dividedBy(divisor: number | Rational): 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.
@@ -54,14 +137,15 @@ export declare class Quantity {
     /** Alias for {@link minus}. */
     sub(other: Quantity): Quantity;
     /** Alias for {@link times}. */
-    mul(factor: number): Quantity;
+    mul(factor: number | Rational): Quantity;
     /** Alias for {@link dividedBy}. */
-    div(divisor: number): 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
-     * 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: Quantity): boolean;
     /** Whether this quantity does not equal `other`. */
@@ -104,7 +188,7 @@ export declare 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