measurable 2.0.0 → 3.1.0

package/dist/lib/Quantity.d.ts

@@ -7,6 +7,45 @@ 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 {
     readonly unit: Unit;
@@ -28,12 +67,51 @@ 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;
+    /**
+     * 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
-     * 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
@@ -51,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. */
@@ -72,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

@@ -1,7 +1,10 @@
 "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 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");
@@ -27,14 +30,89 @@ 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}`;
     }
+    /**
+     * 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
-     * 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
@@ -60,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();
@@ -106,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.
@@ -204,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.d.ts

@@ -16,7 +16,7 @@ export declare 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.fromNumber} instead.
+     * 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. */

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
@@ -17,13 +18,13 @@ 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.fromNumber} instead.
+     * 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");
+            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/dist/lib/Unit.d.ts

@@ -9,21 +9,23 @@ export interface LinearTransform {
     scale: Rational;
     offset: Rational;
 }
-interface BaseUnitOptions {
+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;
 }
-interface LinearConversionOptions {
+export type UnitConversionOptions = {
     /** Exact transform for linear / affine units (the common case). */
     linear: LinearTransform;
-}
-interface CustomConversionOptions {
+} | {
     /** Hand-written transform for non-linear units; mutually exclusive with `linear`. */
     toBase: (value: number) => number;
     fromBase: (value: number) => number;
-}
-export type UnitConversionOptions = LinearConversionOptions | CustomConversionOptions;
-type UnitOptions = BaseUnitOptions & UnitConversionOptions;
+};
+export type UnitOptions = BaseUnitOptions & UnitConversionOptions;
 /**
  * A single unit of measurement (e.g. "meter", "celsius").
  *
@@ -44,8 +46,10 @@ type UnitOptions = BaseUnitOptions & UnitConversionOptions;
  * {@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.
@@ -53,8 +57,12 @@ type UnitOptions = BaseUnitOptions & UnitConversionOptions;
 export declare class Unit {
     readonly name: string;
     readonly dimension: Dimension;
+    /** 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, ...conversionOptions }: UnitOptions);
+    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}
@@ -66,4 +74,3 @@ export declare class Unit {
     /** Convert a value in the dimension's base unit to this unit. */
     fromBase(value: number): number;
 }
-export {};

package/dist/lib/Unit.js

@@ -21,16 +21,20 @@ exports.Unit = void 0;
  * {@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, ...conversionOptions }) {
+    constructor({ name, dimension, symbol, plural, ...conversionOptions }) {
         this.name = name;
         this.dimension = dimension;
+        this.symbol = symbol;
+        this.plural = plural;
         this.conversion = conversionOptions;
     }
     /**

package/dist/utils/definePrefixed.d.ts

@@ -1,5 +1,4 @@
 import type { Dimension } from "../lib/Dimension";
-import { Rational } from "../lib/Rational";
 import type { Unit } from "../lib/Unit";
 /** A metric (SI) prefix: a name, symbol, and power-of-ten factor. */
 export interface SiPrefix {
@@ -11,20 +10,14 @@ export interface SiPrefix {
 export declare const SI_PREFIXES: readonly SiPrefix[];
 /** SI prefixes for fractions only (deci and smaller) — for units like seconds. */
 export declare const SI_SUBMULTIPLE_PREFIXES: readonly SiPrefix[];
-/** The unit a set of metric prefixes is generated relative to. */
-export interface PrefixReference {
-    /** Singular unit name, e.g. "meter" → "kilometer", "millimeter", … */
-    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) (default 1). */
-    scale?: number | Rational;
-}
 /**
- * Define metric-prefixed variants of a reference unit on a dimension. Each
- * variant is named `${prefix}${reference.name}` (e.g. "kilometer") with scale
- * `reference.scale * prefix.factor`, plus a `${prefix.symbol}${reference.symbol}`
- * alias and a plural (and an ASCII "u" form for micro).
+ * Define metric-prefixed variants of a `reference` unit on its dimension. Each
+ * variant is named `${prefix}${reference.name}` (e.g. "kilometer"), scaled by
+ * `prefix.factor` relative to the reference (its own scale is read from the unit
+ * via `scaleOf`, so prefixing a non-base unit like the watt-hour works
+ * automatically). Each variant carries a generated `symbol`
+ * (`${prefix.symbol}${reference.symbol}`, when the reference has a symbol) and a
+ * `plural` (`${name}s`), plus an ASCII "u" alias for micro.
  *
  * Prefixes whose generated name already exists on the dimension are skipped, so
  * a base like "kilogram" is left intact when prefixing "gram".
@@ -32,4 +25,4 @@ export interface PrefixReference {
  * Returns the created units keyed by name, for spreading into a
  * {@link MeasurementSystem} or destructuring into named exports.
  */
-export declare function definePrefixed(dimension: Dimension, reference: PrefixReference, prefixes?: readonly SiPrefix[]): Record<string, Unit>;
+export declare function definePrefixed(dimension: Dimension, reference: Unit, prefixes?: readonly SiPrefix[]): Record<string, Unit>;

package/dist/utils/definePrefixed.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.SI_SUBMULTIPLE_PREFIXES = exports.SI_PREFIXES = void 0;
 exports.definePrefixed = definePrefixed;
 const Rational_1 = require("../lib/Rational");
+const scaleOf_1 = require("./scaleOf");
 /** The full set of SI prefixes, yotta (1e24) down to yocto (1e-24). */
 exports.SI_PREFIXES = [
     { name: "yotta", symbol: "Y", factor: 1e24 },
@@ -29,10 +30,13 @@ exports.SI_PREFIXES = [
 /** SI prefixes for fractions only (deci and smaller) — for units like seconds. */
 exports.SI_SUBMULTIPLE_PREFIXES = exports.SI_PREFIXES.filter((prefix) => prefix.factor < 1);
 /**
- * Define metric-prefixed variants of a reference unit on a dimension. Each
- * variant is named `${prefix}${reference.name}` (e.g. "kilometer") with scale
- * `reference.scale * prefix.factor`, plus a `${prefix.symbol}${reference.symbol}`
- * alias and a plural (and an ASCII "u" form for micro).
+ * Define metric-prefixed variants of a `reference` unit on its dimension. Each
+ * variant is named `${prefix}${reference.name}` (e.g. "kilometer"), scaled by
+ * `prefix.factor` relative to the reference (its own scale is read from the unit
+ * via `scaleOf`, so prefixing a non-base unit like the watt-hour works
+ * automatically). Each variant carries a generated `symbol`
+ * (`${prefix.symbol}${reference.symbol}`, when the reference has a symbol) and a
+ * `plural` (`${name}s`), plus an ASCII "u" alias for micro.
  *
  * Prefixes whose generated name already exists on the dimension are skipped, so
  * a base like "kilogram" is left intact when prefixing "gram".
@@ -41,21 +45,28 @@ exports.SI_SUBMULTIPLE_PREFIXES = exports.SI_PREFIXES.filter((prefix) => prefix.
  * {@link MeasurementSystem} or destructuring into named exports.
  */
 function definePrefixed(dimension, reference, prefixes = exports.SI_PREFIXES) {
+    // Prefer the reference's exact rational scale so the prefixed scale stays
+    // exact; fall back to its float scale only for non-linear references.
+    const referenceScale = reference.linear
+        ? reference.linear.scale
+        : Rational_1.Rational.from((0, scaleOf_1.scaleOf)(reference));
     const units = {};
     for (const prefix of prefixes) {
         const name = `${prefix.name}${reference.name}`;
         if (dimension.get(name)) {
             continue;
         }
-        const aliases = [`${prefix.symbol}${reference.symbol}`, `${name}s`];
-        if (prefix.name === "micro") {
-            aliases.push(`u${reference.symbol}`);
-        }
+        const symbol = reference.symbol ? `${prefix.symbol}${reference.symbol}` : undefined;
+        const aliases = prefix.name === "micro" && reference.symbol ? [`u${reference.symbol}`] : [];
         // Multiply as rationals: each factor (a power of ten, or an exact reference
         // scale) is lossless on its own, but multiplying them as floats can drift
         // (e.g. 3600 * 1e-9). Rational multiplication keeps the prefixed scale exact.
-        const scale = Rational_1.Rational.from(reference.scale ?? 1).times(Rational_1.Rational.from(prefix.factor));
-        units[name] = dimension.unit(name, scale, aliases);
+        const scale = referenceScale.times(Rational_1.Rational.from(prefix.factor));
+        units[name] = dimension.unit(name, scale, {
+            symbol,
+            plural: `${name}s`,
+            aliases,
+        });
     }
     return units;
 }