measurable 2.0.0 → 3.1.0

package/dist/dimensions/mass.js

@@ -9,16 +9,20 @@ const definePrefixed_1 = require("../utils/definePrefixed");
  * choice of base is internal and does not affect any conversion.)
  */
 exports.mass = new Dimension_1.Dimension("mass");
-exports.gram = exports.mass.base("gram", ["g", "grams"]);
+exports.gram = exports.mass.base("gram", { symbol: "g", plural: "grams" });
 // Customary units, expressed in grams.
-exports.pound = exports.mass.unit("pound", 453.59237, ["lb", "lbs", "pounds"]);
-exports.ounce = exports.mass.unit("ounce", 28.349523125, ["oz", "ounces"]);
-exports.stone = exports.mass.unit("stone", 6350.29318, ["st", "stones"]);
-exports.tonne = exports.mass.unit("tonne", 1000000, ["t", "tonnes"]);
+exports.pound = exports.mass.unit("pound", 453.59237, {
+    symbol: "lb",
+    plural: "pounds",
+    aliases: ["lbs"],
+});
+exports.ounce = exports.mass.unit("ounce", 28.349523125, { symbol: "oz", plural: "ounces" });
+exports.stone = exports.mass.unit("stone", 6350.29318, { symbol: "st", plural: "stones" });
+exports.tonne = exports.mass.unit("tonne", 1000000, { symbol: "t", plural: "tonnes" });
 // Short (US) and long (Imperial) tons share the "ton" alias but differ in size;
 // the metric tonne above is a separate unit again. Parsing disambiguates these.
-exports.shortTon = exports.mass.unit("shortTon", 907184.74, ["ton", "tons"]);
-exports.longTon = exports.mass.unit("longTon", 1016046.9088, ["ton", "tons"]);
+exports.shortTon = exports.mass.unit("shortTon", 907184.74, { plural: "tons", aliases: ["ton"] });
+exports.longTon = exports.mass.unit("longTon", 1016046.9088, { plural: "tons", aliases: ["ton"] });
 /** Every SI-prefixed gram — including the kilogram — keyed by name. */
-exports.metricMass = (0, definePrefixed_1.definePrefixed)(exports.mass, { name: "gram", symbol: "g" });
+exports.metricMass = (0, definePrefixed_1.definePrefixed)(exports.mass, exports.gram);
 exports.kilogram = exports.metricMass.kilogram, exports.megagram = exports.metricMass.megagram, exports.hectogram = exports.metricMass.hectogram, exports.decagram = exports.metricMass.decagram, exports.decigram = exports.metricMass.decigram, exports.centigram = exports.metricMass.centigram, exports.milligram = exports.metricMass.milligram, exports.microgram = exports.metricMass.microgram, exports.nanogram = exports.metricMass.nanogram;

package/dist/dimensions/power.js

@@ -5,9 +5,9 @@ const Dimension_1 = require("../lib/Dimension");
 const definePrefixed_1 = require("../utils/definePrefixed");
 /** Power. Base unit: watt. */
 exports.power = new Dimension_1.Dimension("power");
-exports.watt = exports.power.base("watt", ["W", "watts"]);
-exports.horsepower = exports.power.unit("horsepower", 745.699872, ["hp"]);
-exports.metricHorsepower = exports.power.unit("metricHorsepower", 735.49875, ["PS"]);
+exports.watt = exports.power.base("watt", { symbol: "W", plural: "watts" });
+exports.horsepower = exports.power.unit("horsepower", 745.699872, { symbol: "hp" });
+exports.metricHorsepower = exports.power.unit("metricHorsepower", 735.49875, { symbol: "PS" });
 /** Every SI-prefixed watt (kilowatt, megawatt, gigawatt, milliwatt, …), keyed by name. */
-exports.metricPower = (0, definePrefixed_1.definePrefixed)(exports.power, { name: "watt", symbol: "W" });
+exports.metricPower = (0, definePrefixed_1.definePrefixed)(exports.power, exports.watt);
 exports.kilowatt = exports.metricPower.kilowatt, exports.megawatt = exports.metricPower.megawatt, exports.gigawatt = exports.metricPower.gigawatt, exports.terawatt = exports.metricPower.terawatt, exports.milliwatt = exports.metricPower.milliwatt;

package/dist/dimensions/pressure.js

@@ -5,14 +5,17 @@ const Dimension_1 = require("../lib/Dimension");
 const definePrefixed_1 = require("../utils/definePrefixed");
 /** Pressure. Base unit: pascal. */
 exports.pressure = new Dimension_1.Dimension("pressure");
-exports.pascal = exports.pressure.base("pascal", ["Pa", "pascals"]);
-exports.bar = exports.pressure.unit("bar", 1e5, ["bars"]);
-exports.millibar = exports.pressure.unit("millibar", 1e2, ["mbar", "millibars"]);
-exports.atmosphere = exports.pressure.unit("atmosphere", 101325, ["atm", "atmospheres"]);
-exports.torr = exports.pressure.unit("torr", 101325 / 760, ["Torr", "torrs"]);
-exports.psi = exports.pressure.unit("psi", 6894.757293168, ["lbf/in²", "lbf/in2"]);
-exports.inchOfMercury = exports.pressure.unit("inchOfMercury", 3386.389, ["inHg"]);
-exports.inchOfWater = exports.pressure.unit("inchOfWater", 249.0889, ["inAq"]);
+exports.pascal = exports.pressure.base("pascal", { symbol: "Pa", plural: "pascals" });
+exports.bar = exports.pressure.unit("bar", 1e5, { symbol: "bar", plural: "bars" });
+exports.millibar = exports.pressure.unit("millibar", 1e2, { symbol: "mbar", plural: "millibars" });
+exports.atmosphere = exports.pressure.unit("atmosphere", 101325, {
+    symbol: "atm",
+    plural: "atmospheres",
+});
+exports.torr = exports.pressure.unit("torr", 101325 / 760, { symbol: "Torr", plural: "torrs" });
+exports.psi = exports.pressure.unit("psi", 6894.757293168, { aliases: ["lbf/in²", "lbf/in2"] });
+exports.inchOfMercury = exports.pressure.unit("inchOfMercury", 3386.389, { symbol: "inHg" });
+exports.inchOfWater = exports.pressure.unit("inchOfWater", 249.0889, { symbol: "inAq" });
 /** Every SI-prefixed pascal (kilopascal, hectopascal, megapascal, …), keyed by name. */
-exports.metricPressure = (0, definePrefixed_1.definePrefixed)(exports.pressure, { name: "pascal", symbol: "Pa" });
+exports.metricPressure = (0, definePrefixed_1.definePrefixed)(exports.pressure, exports.pascal);
 exports.kilopascal = exports.metricPressure.kilopascal, exports.hectopascal = exports.metricPressure.hectopascal, exports.megapascal = exports.metricPressure.megapascal, exports.gigapascal = exports.metricPressure.gigapascal;

package/dist/dimensions/temperature.js

@@ -13,6 +13,6 @@ exports.temperature = new Dimension_1.Dimension("temperature");
 // rational arithmetic so conversions round-trip without drift.
 const fahrenheitScale = new Rational_1.Rational(5, 9);
 const fahrenheitOffset = Rational_1.Rational.from(273.15).minus(new Rational_1.Rational(32).times(fahrenheitScale));
-exports.kelvin = exports.temperature.base("kelvin", ["K"]);
-exports.celsius = exports.temperature.affine("celsius", { scale: 1, offset: 273.15 }, ["C", "°C"]);
-exports.fahrenheit = exports.temperature.affine("fahrenheit", { scale: fahrenheitScale, offset: fahrenheitOffset }, ["F", "°F"]);
+exports.kelvin = exports.temperature.base("kelvin", { symbol: "K" });
+exports.celsius = exports.temperature.affine("celsius", { scale: 1, offset: 273.15 }, { symbol: "°C", aliases: ["C"] });
+exports.fahrenheit = exports.temperature.affine("fahrenheit", { scale: fahrenheitScale, offset: fahrenheitOffset }, { symbol: "°F", aliases: ["F"] });

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/errors/AmbiguousUnitError.js

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

package/dist/errors/ArgumentError.d.ts

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

package/dist/errors/ArgumentError.js

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

package/dist/errors/DimensionMismatchError.d.ts

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

package/dist/errors/DimensionMismatchError.js

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

package/dist/errors/DuplicateUnitError.d.ts

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

package/dist/errors/DuplicateUnitError.js

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

package/dist/errors/ParseError.d.ts

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

package/dist/errors/ParseError.js

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

package/dist/errors/UnsupportedDimensionError.d.ts

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

package/dist/errors/UnsupportedDimensionError.js

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

package/dist/index.d.ts

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

package/dist/index.js

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

package/dist/lib/Dimension.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

@@ -1,8 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Dimension = void 0;
-const InvalidConversionError_1 = require("../errors/InvalidConversionError");
-const Rational_1 = require("../lib/Rational");
+const DimensionMismatchError_1 = require("../errors/DimensionMismatchError");
+const DuplicateUnitError_1 = require("../errors/DuplicateUnitError");
+const Rational_1 = require("./Rational");
 const Unit_1 = require("./Unit");
 /** The rational `0`. */
 const zero = new Rational_1.Rational(0n);
@@ -39,8 +40,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 +50,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 +64,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) {
@@ -79,7 +80,7 @@ class Dimension {
      */
     convertRational(value, from, to) {
         if (!this.units.has(from) || !this.units.has(to)) {
-            throw new InvalidConversionError_1.InvalidConversionError(from, to);
+            throw new DimensionMismatchError_1.DimensionMismatchError(from, to);
         }
         if (from === to) {
             return value;
@@ -99,20 +100,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}"`);
+                throw new DuplicateUnitError_1.DuplicateUnitError(name, this);
             }
         }
-        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/MeasurementSystem.js

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