measurable 2.0.0 → 3.0.0

package/dist/dimensions/time.js

@@ -5,14 +5,26 @@ const Dimension_1 = require("../lib/Dimension");
 const definePrefixed_1 = require("../utils/definePrefixed");
 /** Time / duration. Base unit: second. */
 exports.time = new Dimension_1.Dimension("time");
-exports.second = exports.time.base("second", ["s", "sec", "secs", "seconds"]);
-exports.minute = exports.time.unit("minute", 60, ["min", "mins", "minutes"]);
-exports.hour = exports.time.unit("hour", 3600, ["h", "hr", "hrs", "hours"]);
-exports.day = exports.time.unit("day", 86400, ["d", "days"]);
-exports.week = exports.time.unit("week", 604800, ["wk", "weeks"]);
+exports.second = exports.time.base("second", {
+    symbol: "s",
+    plural: "seconds",
+    aliases: ["sec", "secs"],
+});
+exports.minute = exports.time.unit("minute", 60, {
+    symbol: "min",
+    plural: "minutes",
+    aliases: ["mins"],
+});
+exports.hour = exports.time.unit("hour", 3600, {
+    symbol: "h",
+    plural: "hours",
+    aliases: ["hr", "hrs"],
+});
+exports.day = exports.time.unit("day", 86400, { symbol: "d", plural: "days" });
+exports.week = exports.time.unit("week", 604800, { symbol: "wk", plural: "weeks" });
 /**
  * SI-submultiple seconds (millisecond, microsecond, nanosecond, …). Only
  * fractions are generated; larger spans use minute/hour/day/week above.
  */
-exports.metricTime = (0, definePrefixed_1.definePrefixed)(exports.time, { name: "second", symbol: "s" }, definePrefixed_1.SI_SUBMULTIPLE_PREFIXES);
+exports.metricTime = (0, definePrefixed_1.definePrefixed)(exports.time, exports.second, definePrefixed_1.SI_SUBMULTIPLE_PREFIXES);
 exports.millisecond = exports.metricTime.millisecond, exports.microsecond = exports.metricTime.microsecond, exports.nanosecond = exports.metricTime.nanosecond, exports.picosecond = exports.metricTime.picosecond;

package/dist/dimensions/volume.js

@@ -5,33 +5,66 @@ const Dimension_1 = require("../lib/Dimension");
 const definePrefixed_1 = require("../utils/definePrefixed");
 /** Volume / capacity. Base unit: liter. */
 exports.volume = new Dimension_1.Dimension("volume");
-exports.liter = exports.volume.base("liter", ["L", "liters"]);
+exports.liter = exports.volume.base("liter", { symbol: "L", plural: "liters" });
 // US and Imperial liquid measures share names ("gallon", "pint", …) but differ
 // in size, so each is a distinct unit carrying the shared aliases; parsing
 // disambiguates via a preferred measurement system. Imperial has 160 fluid
 // ounces per gallon, US customary has 128.
-exports.usGallon = exports.volume.unit("usGallon", 3.785411784, ["gal", "gallon", "gallons"]);
-exports.usQuart = exports.volume.unit("usQuart", 0.946352946, ["qt", "quart", "quarts"]);
-exports.usPint = exports.volume.unit("usPint", 0.473176473, ["pt", "pint", "pints"]);
-exports.usGill = exports.volume.unit("usGill", 0.11829411825, ["gill", "gills"]);
-exports.usFluidOunce = exports.volume.unit("usFluidOunce", 0.0295735295625, [
-    "floz",
-    "fluidOunce",
-    "fluidOunces",
-]);
-exports.imperialGallon = exports.volume.unit("imperialGallon", 4.54609, ["gal", "gallon", "gallons"]);
-exports.imperialQuart = exports.volume.unit("imperialQuart", 1.1365225, ["qt", "quart", "quarts"]);
-exports.imperialPint = exports.volume.unit("imperialPint", 0.56826125, ["pt", "pint", "pints"]);
-exports.imperialGill = exports.volume.unit("imperialGill", 0.1420653125, ["gill", "gills"]);
-exports.imperialFluidOunce = exports.volume.unit("imperialFluidOunce", 0.0284130625, [
-    "floz",
-    "fluidOunce",
-    "fluidOunces",
-]);
+exports.usGallon = exports.volume.unit("usGallon", 3.785411784, {
+    symbol: "gal",
+    plural: "gallons",
+    aliases: ["gallon"],
+});
+exports.usQuart = exports.volume.unit("usQuart", 0.946352946, {
+    symbol: "qt",
+    plural: "quarts",
+    aliases: ["quart"],
+});
+exports.usPint = exports.volume.unit("usPint", 0.473176473, {
+    symbol: "pt",
+    plural: "pints",
+    aliases: ["pint"],
+});
+exports.usGill = exports.volume.unit("usGill", 0.11829411825, { plural: "gills", aliases: ["gill"] });
+exports.usFluidOunce = exports.volume.unit("usFluidOunce", 0.0295735295625, {
+    symbol: "floz",
+    plural: "fluidOunces",
+    aliases: ["fluidOunce"],
+});
+exports.imperialGallon = exports.volume.unit("imperialGallon", 4.54609, {
+    symbol: "gal",
+    plural: "gallons",
+    aliases: ["gallon"],
+});
+exports.imperialQuart = exports.volume.unit("imperialQuart", 1.1365225, {
+    symbol: "qt",
+    plural: "quarts",
+    aliases: ["quart"],
+});
+exports.imperialPint = exports.volume.unit("imperialPint", 0.56826125, {
+    symbol: "pt",
+    plural: "pints",
+    aliases: ["pint"],
+});
+exports.imperialGill = exports.volume.unit("imperialGill", 0.1420653125, {
+    plural: "gills",
+    aliases: ["gill"],
+});
+exports.imperialFluidOunce = exports.volume.unit("imperialFluidOunce", 0.0284130625, {
+    symbol: "floz",
+    plural: "fluidOunces",
+    aliases: ["fluidOunce"],
+});
 // US-only cooking measures (no competing imperial unit, so left unprefixed).
-exports.cup = exports.volume.unit("cup", 0.2365882365, ["cups"]);
-exports.tablespoon = exports.volume.unit("tablespoon", 0.01478676478125, ["tbsp", "tablespoons"]);
-exports.teaspoon = exports.volume.unit("teaspoon", 0.00492892159375, ["tsp", "teaspoons"]);
+exports.cup = exports.volume.unit("cup", 0.2365882365, { plural: "cups" });
+exports.tablespoon = exports.volume.unit("tablespoon", 0.01478676478125, {
+    symbol: "tbsp",
+    plural: "tablespoons",
+});
+exports.teaspoon = exports.volume.unit("teaspoon", 0.00492892159375, {
+    symbol: "tsp",
+    plural: "teaspoons",
+});
 /** Every SI-prefixed liter (milliliter, centiliter, kiloliter, …), keyed by name. */
-exports.metricVolume = (0, definePrefixed_1.definePrefixed)(exports.volume, { name: "liter", symbol: "L" });
+exports.metricVolume = (0, definePrefixed_1.definePrefixed)(exports.volume, exports.liter);
 exports.kiloliter = exports.metricVolume.kiloliter, exports.hectoliter = exports.metricVolume.hectoliter, exports.decaliter = exports.metricVolume.decaliter, exports.deciliter = exports.metricVolume.deciliter, exports.centiliter = exports.metricVolume.centiliter, exports.milliliter = exports.metricVolume.milliliter;

package/dist/lib/Dimension.d.ts

@@ -1,4 +1,4 @@
-import { Rational } from "../lib/Rational";
+import { Rational } from "./Rational";
 import { Unit } from "./Unit";
 /** A linear unit with an additive offset (e.g. temperature scales). */
 export interface AffineSpec {
@@ -16,6 +16,15 @@ 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
@@ -48,15 +57,15 @@ 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). Pass a {@link Rational} for a
      * scale a decimal cannot represent exactly.
      */
-    unit(name: string, scale: number | Rational, 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;
+    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 *
@@ -64,7 +73,7 @@ export declare class Dimension {
      * affine units should use {@link unit} / {@link affine} so conversions stay
      * exact.
      */
-    custom(name: string, { toBase, fromBase }: CustomSpec, aliases?: string[]): Unit;
+    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;
     /**

package/dist/lib/Dimension.js

@@ -2,7 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Dimension = void 0;
 const InvalidConversionError_1 = require("../errors/InvalidConversionError");
-const Rational_1 = require("../lib/Rational");
+const Rational_1 = require("./Rational");
 const Unit_1 = require("./Unit");
 /** The rational `0`. */
 const zero = new Rational_1.Rational(0n);
@@ -39,8 +39,8 @@ class Dimension {
         this.index = new Map();
     }
     /** Define the canonical base unit (identity transform). */
-    base(name, aliases = []) {
-        const unit = this.defineLinear(name, { scale: one, offset: zero }, aliases);
+    base(name, def = {}) {
+        const unit = this.defineLinear(name, { scale: one, offset: zero }, def);
         this.baseUnit = unit;
         return unit;
     }
@@ -49,12 +49,12 @@ class Dimension {
      * 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.defineLinear(name, { scale: Rational_1.Rational.from(scale), offset: zero }, 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.defineLinear(name, { scale: Rational_1.Rational.from(scale), offset: Rational_1.Rational.from(offset) }, 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 non-linear unit from an arbitrary, hand-written inverse transform
@@ -63,8 +63,8 @@ class Dimension {
      * affine units should use {@link unit} / {@link affine} so conversions stay
      * exact.
      */
-    custom(name, { toBase, fromBase }, aliases = []) {
-        return this.define(name, aliases, { toBase, fromBase });
+    custom(name, { toBase, fromBase }, def = {}) {
+        return this.define(name, def, { toBase, fromBase });
     }
     /** Convert a `number` value between two units of this dimension. */
     convert(value, from, to) {
@@ -99,20 +99,22 @@ class Dimension {
         return this.units.has(unit);
     }
     /** Define a linear / affine unit from its exact rational transform. */
-    defineLinear(name, linear, aliases) {
-        return this.define(name, aliases, { linear });
+    defineLinear(name, linear, def) {
+        return this.define(name, def, { linear });
     }
-    define(name, aliases, transform) {
+    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, ...transform });
+        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/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;
@@ -30,6 +69,37 @@ export declare class Quantity {
     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

package/dist/lib/Quantity.js

@@ -1,6 +1,7 @@
 "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 scaleOf_1 = require("../utils/scaleOf");
@@ -31,6 +32,58 @@ class Quantity {
     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

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

@@ -17,7 +17,7 @@ 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);

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;
 }