measurable 2.0.0 → 3.1.0

package/CHANGELOG.md

@@ -5,6 +5,88 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.1.0] - 2026-06-19
+
+This release adds a best-fit primitive and gives every thrown error a dedicated,
+catchable class. All changes are backward-compatible.
+
+### Added
+
+- **`Quantity.best(...units)`** — re-expresses a quantity in the best-fit unit
+  among the given ones: the largest unit whose absolute magnitude is still ≥ 1
+  (falling back to the smallest). Candidate order doesn't matter; each must
+  belong to the quantity's dimension.
+- **Dedicated error classes**, all extending `Error` and exported from
+  `measurable`, so failures can be branched on with `instanceof`:
+  `ArgumentError` (invalid argument — e.g. `best()` with no units, or a
+  non-integer / zero-denominator / non-finite `Rational`), `ParseError` (a string
+  could not be parsed into a quantity), `DuplicateUnitError` (a unit name already
+  exists in its dimension), and `UnsupportedDimensionError` (a measurement system
+  has no units of a dimension to `express` in).
+
+### Changed
+
+- **`MeasurementSystem.express` now delegates to `Quantity.best`** — same
+  behavior, with the best-fit logic living in one place.
+- **Every previously bare `throw new Error` now throws a dedicated class.**
+  Messages are unchanged and all classes extend `Error`, so existing `catch`
+  blocks keep working.
+
+### Deprecated
+
+- **`InvalidConversionError` is renamed to `DimensionMismatchError`** — it is
+  thrown for any cross-dimension operation (converting, comparing, or combining
+  units), not just conversions. The old name remains exported as a deprecated
+  alias of the same class and still works with `instanceof`.
+
+## [3.0.0] - 2026-06-18
+
+This release adds value **formatting**. Units now carry a `symbol` and `plural`,
+and a `Quantity` can render itself with magnitude-aware pluralization and
+locale-aware number formatting. Threading symbol/plural through the unit builders
+changes their signatures, hence the major bump.
+
+### Breaking
+
+- **Unit builder methods take a `UnitDef` object instead of an aliases array.**
+  `Dimension.base` / `unit` / `affine` / `custom` now accept
+  `{ symbol?, plural?, aliases? }` as their final argument rather than a bare
+  `string[]` of aliases. Migrate `length.unit("inch", 0.0254, ["in", "inches"])`
+  to `length.unit("inch", 0.0254, { symbol: "in", plural: "inches" })`; plain
+  aliases still work via the `aliases` field.
+- **`definePrefixed` takes the reference `Unit`, not a descriptor object.**
+  `definePrefixed(length, { name: "meter", symbol: "m" })` becomes
+  `definePrefixed(length, meter)` — it reads the name, symbol, and exact scale
+  straight off the unit. The `PrefixReference` type is removed.
+- **`Unit`'s constructor options gained `symbol` / `plural`.** Only affects code
+  that calls `new Unit(...)` directly; units built through a `Dimension` are
+  unaffected.
+
+### Added
+
+- **`Unit.symbol` and `Unit.plural`** — optional, first-class descriptors. Both
+  are also registered as parse tokens, so `Quantity.parse` accepts e.g. `"5 g"`
+  and `"5 grams"`.
+- **`Quantity.format(options?)`** — renders `"<magnitude> <label>"`. `unit`
+  selects the label: `"auto"` (default — singular `name` at ±1, otherwise
+  `plural`), `"name"`, `"plural"`, or `"symbol"`, each falling back to `name`
+  when unset. The magnitude is rendered with `toLocaleString`; pass `locale`
+  and/or `numberFormat` (`Intl.NumberFormatOptions`) for locale- and
+  precision-aware output.
+- **`Quantity.formatParts(options?)`** — the same options as `format`, but
+  returns the rendered `{ magnitude, unit }` as separate strings for custom
+  assembly (e.g. JSX).
+- **`definePrefixed` derives each variant's `symbol` and `plural`** from the
+  reference unit (e.g. `meter` → `kilometer` / `km`), keeping the prefixed scale
+  exact via rational arithmetic.
+- New exported types: `UnitDef`, `FormatOptions`, `FormattedParts`,
+  `BaseUnitOptions`, `UnitConversionOptions`, and `UnitOptions`.
+
+### Changed
+
+- Added `assert-never` as a (small) runtime dependency, used for exhaustiveness
+  checking in formatting.
+
 ## [2.0.0] - 2026-06-18
 
 This release makes conversions and quantity arithmetic **exact**. Magnitudes and
@@ -94,6 +176,8 @@ to a `number` at the edge, so `foot → inch` is exactly `12` (not
   `MeasurementSystem`), string parsing via `Quantity.parse`, and the first set
   of built-in dimensions and measurement systems.
 
+[3.1.0]: https://github.com/mhuggins/measurable/compare/v3.0.0...v3.1.0
+[3.0.0]: https://github.com/mhuggins/measurable/compare/v2.0.0...v3.0.0
 [2.0.0]: https://github.com/mhuggins/measurable/compare/v1.1.1...v2.0.0
 [1.1.1]: https://github.com/mhuggins/measurable/compare/v1.1.0...v1.1.1
 [1.1.0]: https://github.com/mhuggins/measurable/compare/v1.0.0...v1.1.0

package/README.md

@@ -206,9 +206,84 @@ metric.express(new Quantity(5000, meter));    // Quantity(5, kilometer)
 imperial.express(new Quantity(5000, meter));  // Quantity(3.107…, mile)
 ```
 
-A `Quantity` also has a `toString()` that renders `"<magnitude> <unit name>"`
-(e.g. `new Quantity(5, kilometer).toString()` → `"5 kilometer"`), and `round(decimals)`
-to trim the magnitude for display (`new Quantity(1.6213, mile).round(2)` → `1.62 mile`).
+Under the hood, `express` just hands the system's units for that dimension to
+`Quantity.best`, the same best-fit primitive you can call directly with whatever
+units you like — handy when you want a custom shortlist rather than a whole
+system. `best` picks the largest unit whose absolute magnitude is still ≥ 1
+(falling back to the smallest when even that rounds below 1), so candidate order
+doesn't matter:
+
+```ts
+import { Quantity } from "measurable";
+import { meter, kilometer, mile } from "measurable/dimensions";
+
+new Quantity(5000, meter).best(meter, kilometer, mile);  // Quantity(3.107…, mile)
+new Quantity(1500, meter).best(meter, kilometer);        // Quantity(1.5, kilometer)
+new Quantity(500, meter).best(kilometer, mile);          // Quantity(0.5, kilometer) — smallest fallback
+```
+
+It requires at least one unit, and each must belong to the quantity's dimension
+(otherwise `DimensionMismatchError`).
+
+## Formatting output
+
+Each unit carries a canonical `symbol` (`"g"`, `"km"`, `"°C"`) and `plural`
+(`"grams"`, `"kilometers"`) alongside its `name`, so a `Quantity` can be rendered the
+way you want:
+
+```ts
+import { Quantity } from "measurable";
+import { gram } from "measurable/dimensions";
+
+new Quantity(5, gram).toString();                 // "5 gram"   (always the bare name)
+new Quantity(5, gram).format();                   // "5 grams"  (magnitude-aware)
+new Quantity(1, gram).format();                   // "1 gram"   (singular at ±1)
+new Quantity(5, gram).format({ unit: "symbol" }); // "5 g"
+new Quantity(5, gram).format({ unit: "name" });   // "5 gram"
+new Quantity(5, gram).format({ unit: "plural" }); // "5 grams"
+
+// Localize the magnitude with locale / numberFormat (passed to toLocaleString):
+new Quantity(1234.5, meter).format({ locale: "de-DE" });                             // "1.234,5 meters"
+new Quantity(1.23456, meter).format({ numberFormat: { maximumFractionDigits: 2 } }); // "1.23 meters"
+new Quantity(1234.5, kilometer).format({ locale: "de-DE", unit: "symbol" });         // "1.234,5 km"
+```
+
+`toString()` is intentionally stable (`"<magnitude> <name>"`). `format(options?)` is the
+flexible one: `unit` defaults to `"auto"` (singular `name` at ±1, otherwise `plural`) and
+accepts `"name"`, `"plural"`, or `"symbol"`. When a unit has no `symbol`/`plural`, those
+modes fall back to its `name`.
+
+The magnitude is rendered with `Number.prototype.toLocaleString`. Pass `locale` (a BCP 47
+locale or array) and/or `numberFormat` (`Intl.NumberFormatOptions` — precision via
+`maximumFractionDigits`, grouping, `style`, …) to control it; with neither set, the
+runtime's default locale is used. Use `round(decimals)` to trim the magnitude first
+(`new Quantity(1.6213, mile).round(2)` → `1.62 mile`).
+
+When a single string won't do — e.g. styling the magnitude in a React component — use
+`formatParts(options?)`, which takes the same options but returns the rendered
+`{ magnitude, unit }` as separate strings for you to assemble:
+
+```tsx
+const { magnitude, unit } = new Quantity(1234.5, kilometer).formatParts({ locale: "de-DE" });
+// { magnitude: "1.234,5", unit: "kilometers" }
+return <><b>{magnitude}</b> {unit}</>;
+```
+
+### Internationalization
+
+`format()` localizes the **magnitude** (via `locale`/`numberFormat`), but the **label** it
+appends — `symbol`/`plural` — is **English/canonical** convenience data, not a localization
+system: a single plural string can't model languages with several plural forms, and the
+names themselves are English. For a fully localized label, delegate to `Intl.NumberFormat`,
+whose `style: "unit"` localizes **and** pluralizes a curated set of units for you:
+
+```ts
+const q = new Quantity(5, kilometer);
+new Intl.NumberFormat("de", { style: "unit", unit: "kilometer" }).format(q.magnitude);
+// "5 Kilometer"
+new Intl.NumberFormat("fr", { style: "unit", unit: "kilometer", unitDisplay: "short" })
+  .format(q.magnitude); // "5 km"
+```
 
 ## Parsing strings
 
@@ -272,7 +347,7 @@ new Quantity(6, mile).dividedBy(2);                      // Quantity(3, mile)
 Short aliases are available: **`add`** (`plus`), **`sub`** (`minus`), **`mul`**
 (`times`), **`div`** (`dividedBy`).
 
-Combining different dimensions throws `InvalidConversionError`. Note that adding
+Combining different dimensions throws `DimensionMismatchError`. Note that adding
 **affine** units (e.g. temperatures) is mathematically defined but physically
 questionable, since it adds absolute points rather than a difference.
 
@@ -293,13 +368,13 @@ This is different from `.in(unit)`: `.in(milliliter)` only uses the *unit* on th
 right (giving `2000`), whereas `ratioTo` also uses the other quantity's
 **magnitude** (the `250`), so it answers "how many of *that quantity* fit in this
 one." It's the inverse of scalar `times` — `b.times(a.ratioTo(b))` reconstructs
-`a`. Comparing different dimensions throws `InvalidConversionError`.
+`a`. Comparing different dimensions throws `DimensionMismatchError`.
 
 ## Comparison
 
 `equals`/`notEquals`/`lessThan`/`greaterThan`/`lessThanOrEqual`/`greaterThanOrEqual`
 compare two quantities (the other is converted into the receiver's unit first),
-returning a boolean. Comparing different dimensions throws `InvalidConversionError`.
+returning a boolean. Comparing different dimensions throws `DimensionMismatchError`.
 
 ```ts
 import { Quantity } from "measurable";
@@ -325,7 +400,7 @@ comparator: `quantities.sort((a, b) => a.compareTo(b))`.
 
 `Quantity.min`/`max`/`sum` aggregate several quantities at once; `clamp` is an
 instance method that bounds one quantity to a range. Each converts operands as
-needed, so mixing dimensions throws `InvalidConversionError`.
+needed, so mixing dimensions throws `DimensionMismatchError`.
 
 ```ts
 import { Quantity } from "measurable";
@@ -343,17 +418,21 @@ b.clamp(a, new Quantity(2, kilometer)); // b bounded to [a, 2 km], in b's unit
 ## Defining your own units
 
 Create a `Dimension` and add units through its builder methods. `scale` is how
-many base units make up one of the unit being defined.
+many base units make up one of the unit being defined. The optional final argument
+is a definition object — `{ symbol?, plural?, aliases? }` — whose `symbol` and
+`plural` feed `format()` and, like `aliases`, are also registered for parsing.
 
 ```ts
 import { Dimension, Quantity } from "measurable";
 
 const data = new Dimension("data");
-const byte = data.base("byte", ["B", "bytes"]); // the base unit (identity)
-const kilobyte = data.unit("kilobyte", 1024, ["KB"]);
-const megabyte = data.unit("megabyte", 1024 ** 2, ["MB"]);
+const byte = data.base("byte", { symbol: "B", plural: "bytes" }); // base unit (identity)
+const kilobyte = data.unit("kilobyte", 1024, { symbol: "KB", plural: "kilobytes" });
+const megabyte = data.unit("megabyte", 1024 ** 2, { symbol: "MB", plural: "megabytes" });
 
-new Quantity(2, megabyte).in(kilobyte); // 2048
+new Quantity(2, megabyte).in(kilobyte);      // 2048
+new Quantity(2, megabyte).format();          // "2 megabytes"
+new Quantity(2, megabyte).format({ unit: "symbol" }); // "2 MB"
 ```
 
 A numeric `scale` is read as the exact decimal you wrote (`0.0254` → `254/10000`),
@@ -374,16 +453,19 @@ const third = ratio.unit("third", new Rational(1, 3)); // exact, not 0.3333…
 import { Dimension, Rational } from "measurable";
 
 const temperature = new Dimension("temperature");
-const kelvin = temperature.base("kelvin", ["K"]);
+const kelvin = temperature.base("kelvin", { symbol: "K" });
 // value_in_base = value * scale + offset
-const celsius = temperature.affine("celsius", { scale: 1, offset: 273.15 }, ["C"]);
+const celsius = temperature.affine("celsius", { scale: 1, offset: 273.15 }, {
+  symbol: "°C",
+  aliases: ["C"],
+});
 // Fahrenheit's 5/9 isn't a terminating decimal — give it (and the derived
 // offset) as exact Rationals so conversions round-trip without drift.
 const scale = new Rational(5, 9);
 const fahrenheit = temperature.affine(
   "fahrenheit",
   { scale, offset: Rational.from(273.15).minus(new Rational(32).times(scale)) },
-  ["F"],
+  { symbol: "°F", aliases: ["F"] },
 );
 ```
 
@@ -402,18 +484,22 @@ dim.custom("squared", {
 
 ### Generating SI prefixes
 
-`definePrefixed` adds the metric prefix ladder to a reference unit and returns the
-created units keyed by name (skipping any name that already exists). Pass
-`SI_SUBMULTIPLE_PREFIXES` to generate fractions only.
+`definePrefixed` adds the metric prefix ladder to a reference **unit** and returns the
+created units keyed by name (skipping any name that already exists). It reads the
+reference's `name`, `symbol`, and scale straight off the unit (via `scaleOf`), so each
+generated unit gets a derived symbol (`b` → `kb`) and plural too — even when the
+reference isn't the base unit. Pass `SI_SUBMULTIPLE_PREFIXES` to generate fractions only.
 
 ```ts
 import { Dimension, Quantity, definePrefixed } from "measurable";
 
 const data = new Dimension("data");
-const bit = data.base("bit", ["b"]);
-const prefixed = definePrefixed(data, { name: "bit", symbol: "b", scale: 1 });
+const bit = data.base("bit", { symbol: "b", plural: "bits" });
+const prefixed = definePrefixed(data, bit);
 
-new Quantity(1, prefixed.kilobit).in(bit); // 1000  (SI kilo = 1e3)
+new Quantity(1, prefixed.kilobit).in(bit);   // 1000  (SI kilo = 1e3)
+prefixed.kilobit.symbol;                     // "kb"
+new Quantity(5, prefixed.kilobit).format({ unit: "symbol" }); // "5 kb"
 ```
 
 ### Tagging units into a measurement system
@@ -430,21 +516,26 @@ si.has(kilobyte); // true
 ### `Dimension`
 
 - `new Dimension(name)`
-- `.base(name, aliases?)` — define the canonical base unit
-- `.unit(name, scale, aliases?)` — linear unit (`scale` base units per unit; `number | Rational`)
-- `.affine(name, { scale, offset }, aliases?)` — linear with additive offset (each `number | Rational`)
-- `.custom(name, { toBase, fromBase }, aliases?)` — arbitrary inverse pair, for non-linear units
+- `.base(name, def?)` — define the canonical base unit
+- `.unit(name, scale, def?)` — linear unit (`scale` base units per unit; `number | Rational`)
+- `.affine(name, { scale, offset }, def?)` — linear with additive offset (each `number | Rational`)
+- `.custom(name, { toBase, fromBase }, def?)` — arbitrary inverse pair, for non-linear units
 - `.convert(value, from, to)` — convert a raw `number` between two of its units
 - `.convertRational(value, from, to)` → `Rational` — exact conversion between two of its units
 - `.get(token)` — units matching a name/alias (`Unit[] | undefined`)
 - `.has(unit)`, `.units`, `.baseUnit`
 
+`def` is an optional `UnitDef`: `{ symbol?, plural?, aliases? }`. All three are
+registered as parse tokens; `symbol`/`plural` are additionally stored on the `Unit`.
+
 ### `Unit`
 
 A passive handle, normally created via a dimension's builder methods rather than
 `new Unit` directly. Read-only properties:
 
 - `.name` — the unit's canonical name
+- `.symbol?` — canonical symbol (e.g. `"g"`, `"km"`), if declared
+- `.plural?` — plural name (e.g. `"grams"`), if declared
 - `.dimension` — the `Dimension` it belongs to
 - `.linear` → `{ scale: Rational; offset: Rational } | undefined` — the exact transform for linear/affine units (`undefined` for `custom` ones)
 - `.toBase(value)` → `number` — convert a value in this unit to base units
@@ -457,13 +548,16 @@ A passive handle, normally created via a dimension's builder methods rather than
 - `.rational` → `Rational` — the exact magnitude (source of truth)
 - `.to(target)` → `Quantity`
 - `.in(target)` → `number`
-- `.toString()` → `string` — e.g. `"5 kilometer"`
+- `.toString()` → `string` — stable `"<magnitude> <name>"`, e.g. `"5 kilometer"`
+- `.format({ unit?, locale?, numberFormat? })` → `string` — `unit`: `"auto"` (default, magnitude-aware) / `"name"` / `"plural"` / `"symbol"`; `locale` + `numberFormat` localize the magnitude via `toLocaleString`
+- `.formatParts(options?)` → `{ magnitude, unit }` — same options as `.format`, but returns the rendered pieces separately for custom assembly (e.g. JSX)
 - `.plus(other)` / `.minus(other)` → `Quantity` — add/subtract another quantity (aliases: `add` / `sub`)
 - `.times(factor)` / `.dividedBy(divisor)` → `Quantity` — scale by a `number | Rational` (aliases: `mul` / `div`)
 - `.ratioTo(other)` → `number` — dimensionless ratio (how many of `other` fit in this)
 - `.negate()` / `.abs()` → `Quantity`
 - `.clamp(lower, upper)` → `Quantity` — bound to a range, in this unit
 - `.round(decimals?)` → `Quantity` — round the magnitude (default 0 decimals)
+- `.best(...units)` → `Quantity` — re-express in the largest given unit whose absolute magnitude is still ≥ 1 (smallest as fallback); needs ≥ 1 unit, all of this dimension
 - `.equals(other)` / `.notEquals(other)` → `boolean` (aliases: `eq` / `ne`)
 - `.lessThan(other)` / `.greaterThan(other)` → `boolean` (aliases: `lt` / `gt`)
 - `.lessThanOrEqual(other)` / `.greaterThanOrEqual(other)` → `boolean` (aliases: `lte` / `gte`)
@@ -498,9 +592,17 @@ pass anywhere a magnitude or scale is accepted.
 
 ### Errors
 
-- `InvalidConversionError` — units are from different dimensions
+All extend the built-in `Error` (so existing `catch` blocks still catch them) and
+are exported from `measurable`, letting you branch on the failure with
+`instanceof`:
+
+- `DimensionMismatchError` — an operation was attempted on units from different dimensions (converting, comparing, or combining them). Exported as `InvalidConversionError` too, a deprecated alias of the same class.
 - `UnknownUnitError` — a parsed token matches no unit
 - `AmbiguousUnitError` — a parsed token matches several units and no `prefer` was given
+- `ParseError` — a string could not be parsed into a quantity at all
+- `DuplicateUnitError` — a unit name already exists in its dimension
+- `UnsupportedDimensionError` — a system has no units of a dimension to `express` in
+- `ArgumentError` — an argument was invalid (e.g. `best()` with no units, or a non-integer / zero-denominator / non-finite `Rational`)
 
 ## Changelog
 

package/dist/dimensions/angle.js

@@ -5,10 +5,17 @@ const Dimension_1 = require("../lib/Dimension");
 const definePrefixed_1 = require("../utils/definePrefixed");
 /** Plane angle. Base unit: radian. */
 exports.angle = new Dimension_1.Dimension("angle");
-exports.radian = exports.angle.base("radian", ["rad", "radians"]);
-exports.degree = exports.angle.unit("degree", Math.PI / 180, ["deg", "°", "degrees"]);
-exports.gradian = exports.angle.unit("gradian", Math.PI / 200, ["grad", "gradians"]);
-exports.turn = exports.angle.unit("turn", 2 * Math.PI, ["turns", "revolution", "revolutions"]);
+exports.radian = exports.angle.base("radian", { symbol: "rad", plural: "radians" });
+exports.degree = exports.angle.unit("degree", Math.PI / 180, {
+    symbol: "°",
+    plural: "degrees",
+    aliases: ["deg"],
+});
+exports.gradian = exports.angle.unit("gradian", Math.PI / 200, { symbol: "grad", plural: "gradians" });
+exports.turn = exports.angle.unit("turn", 2 * Math.PI, {
+    plural: "turns",
+    aliases: ["revolution", "revolutions"],
+});
 /** SI-submultiple radians (milliradian, microradian, …); larger angles use degree/turn. */
-exports.metricAngle = (0, definePrefixed_1.definePrefixed)(exports.angle, { name: "radian", symbol: "rad" }, definePrefixed_1.SI_SUBMULTIPLE_PREFIXES);
+exports.metricAngle = (0, definePrefixed_1.definePrefixed)(exports.angle, exports.radian, definePrefixed_1.SI_SUBMULTIPLE_PREFIXES);
 exports.milliradian = exports.metricAngle.milliradian, exports.microradian = exports.metricAngle.microradian;

package/dist/dimensions/area.js

@@ -4,22 +4,43 @@ exports.squareMile = exports.acre = exports.squareYard = exports.squareFoot = ex
 const Dimension_1 = require("../lib/Dimension");
 /** Area. Base unit: square meter. */
 exports.area = new Dimension_1.Dimension("area");
-exports.squareMeter = exports.area.base("squareMeter", ["m²", "m2", "square meter", "square meters"]);
+exports.squareMeter = exports.area.base("squareMeter", {
+    symbol: "m²",
+    plural: "square meters",
+    aliases: ["m2", "square meter"],
+});
 // Metric multiples/submultiples. Area scales as the square of the length
 // prefix, so these can't be generated by the linear SI prefix helper.
-exports.squareKilometer = exports.area.unit("squareKilometer", 1e6, ["km²", "km2"]);
-exports.hectare = exports.area.unit("hectare", 1e4, ["ha", "hectares"]);
-exports.are = exports.area.unit("are", 1e2, ["ares"]);
-exports.squareCentimeter = exports.area.unit("squareCentimeter", 1e-4, ["cm²", "cm2"]);
-exports.squareMillimeter = exports.area.unit("squareMillimeter", 1e-6, ["mm²", "mm2"]);
+exports.squareKilometer = exports.area.unit("squareKilometer", 1e6, {
+    symbol: "km²",
+    aliases: ["km2"],
+});
+exports.hectare = exports.area.unit("hectare", 1e4, { symbol: "ha", plural: "hectares" });
+exports.are = exports.area.unit("are", 1e2, { plural: "ares" });
+exports.squareCentimeter = exports.area.unit("squareCentimeter", 1e-4, {
+    symbol: "cm²",
+    aliases: ["cm2"],
+});
+exports.squareMillimeter = exports.area.unit("squareMillimeter", 1e-6, {
+    symbol: "mm²",
+    aliases: ["mm2"],
+});
 // Imperial / US customary.
-exports.squareInch = exports.area.unit("squareInch", 6.4516e-4, ["sq in", "in²", "in2"]);
-exports.squareFoot = exports.area.unit("squareFoot", 9.290304e-2, [
-    "sq ft",
-    "ft²",
-    "ft2",
-    "square feet",
-]);
-exports.squareYard = exports.area.unit("squareYard", 0.83612736, ["sq yd", "yd²", "yd2"]);
-exports.acre = exports.area.unit("acre", 4046.8564224, ["ac", "acres"]);
-exports.squareMile = exports.area.unit("squareMile", 2589988.110336, ["sq mi", "mi²", "mi2"]);
+exports.squareInch = exports.area.unit("squareInch", 6.4516e-4, {
+    symbol: "in²",
+    aliases: ["sq in", "in2"],
+});
+exports.squareFoot = exports.area.unit("squareFoot", 9.290304e-2, {
+    symbol: "ft²",
+    plural: "square feet",
+    aliases: ["sq ft", "ft2"],
+});
+exports.squareYard = exports.area.unit("squareYard", 0.83612736, {
+    symbol: "yd²",
+    aliases: ["sq yd", "yd2"],
+});
+exports.acre = exports.area.unit("acre", 4046.8564224, { symbol: "ac", plural: "acres" });
+exports.squareMile = exports.area.unit("squareMile", 2589988.110336, {
+    symbol: "mi²",
+    aliases: ["sq mi", "mi2"],
+});

package/dist/dimensions/data.js

@@ -4,9 +4,9 @@ exports.pebibyte = exports.pebibit = exports.tebibyte = exports.tebibit = export
 const Dimension_1 = require("../lib/Dimension");
 /** Digital information. Base unit: bit. */
 exports.data = new Dimension_1.Dimension("data");
-exports.bit = exports.data.base("bit", ["b", "bits"]);
-exports.nibble = exports.data.unit("nibble", 4, ["nibbles"]);
-exports.byte = exports.data.unit("byte", 8, ["B", "bytes"]);
+exports.bit = exports.data.base("bit", { symbol: "b", plural: "bits" });
+exports.nibble = exports.data.unit("nibble", 4, { plural: "nibbles" });
+exports.byte = exports.data.unit("byte", 8, { symbol: "B", plural: "bytes" });
 // SI (decimal, 1000-based) and IEC (binary, 1024-based) multiples of the bit
 // and byte. SI uses the bare symbol (kb, kB); IEC uses the "i" infix (Kib, KiB).
 const SI_MULTIPLES = [
@@ -25,11 +25,14 @@ const IEC_MULTIPLES = [
 ];
 const multiples = {};
 for (const [prefix, symbol, factor] of [...SI_MULTIPLES, ...IEC_MULTIPLES]) {
-    multiples[`${prefix}bit`] = exports.data.unit(`${prefix}bit`, factor, [`${symbol}b`, `${prefix}bits`]);
-    multiples[`${prefix}byte`] = exports.data.unit(`${prefix}byte`, 8 * factor, [
-        `${symbol}B`,
-        `${prefix}bytes`,
-    ]);
+    multiples[`${prefix}bit`] = exports.data.unit(`${prefix}bit`, factor, {
+        symbol: `${symbol}b`,
+        plural: `${prefix}bits`,
+    });
+    multiples[`${prefix}byte`] = exports.data.unit(`${prefix}byte`, 8 * factor, {
+        symbol: `${symbol}B`,
+        plural: `${prefix}bytes`,
+    });
 }
 /** Every SI and IEC multiple of the bit and byte, keyed by name. */
 exports.dataMultiples = multiples;

package/dist/dimensions/energy.js

@@ -5,18 +5,25 @@ const Dimension_1 = require("../lib/Dimension");
 const definePrefixed_1 = require("../utils/definePrefixed");
 /** Energy. Base unit: joule. */
 exports.energy = new Dimension_1.Dimension("energy");
-exports.joule = exports.energy.base("joule", ["J", "joules"]);
-exports.calorie = exports.energy.unit("calorie", 4.184, ["cal", "calories"]);
-exports.kilocalorie = exports.energy.unit("kilocalorie", 4184, ["kcal", "Cal", "kilocalories"]);
-exports.britishThermalUnit = exports.energy.unit("britishThermalUnit", 1055.05585262, ["BTU", "Btu"]);
-exports.wattHour = exports.energy.unit("wattHour", 3600, ["Wh", "watt-hour", "watt-hours"]);
+exports.joule = exports.energy.base("joule", { symbol: "J", plural: "joules" });
+exports.calorie = exports.energy.unit("calorie", 4.184, { symbol: "cal", plural: "calories" });
+exports.kilocalorie = exports.energy.unit("kilocalorie", 4184, {
+    symbol: "kcal",
+    plural: "kilocalories",
+    aliases: ["Cal"],
+});
+exports.britishThermalUnit = exports.energy.unit("britishThermalUnit", 1055.05585262, {
+    symbol: "BTU",
+    aliases: ["Btu"],
+});
+exports.wattHour = exports.energy.unit("wattHour", 3600, {
+    symbol: "Wh",
+    plural: "watt-hours",
+    aliases: ["watt-hour"],
+});
 /** Every SI-prefixed joule (kilojoule, megajoule, millijoule, …), keyed by name. */
-exports.metricEnergy = (0, definePrefixed_1.definePrefixed)(exports.energy, { name: "joule", symbol: "J" });
+exports.metricEnergy = (0, definePrefixed_1.definePrefixed)(exports.energy, exports.joule);
 exports.kilojoule = exports.metricEnergy.kilojoule, exports.megajoule = exports.metricEnergy.megajoule, exports.gigajoule = exports.metricEnergy.gigajoule, exports.millijoule = exports.metricEnergy.millijoule;
 /** Every SI-prefixed watt-hour (kilowatt-hour, megawatt-hour, …), keyed by name. */
-exports.metricWattHour = (0, definePrefixed_1.definePrefixed)(exports.energy, {
-    name: "wattHour",
-    symbol: "Wh",
-    scale: 3600,
-});
+exports.metricWattHour = (0, definePrefixed_1.definePrefixed)(exports.energy, exports.wattHour);
 exports.kilowattHour = exports.metricWattHour.kilowattHour, exports.megawattHour = exports.metricWattHour.megawattHour, exports.gigawattHour = exports.metricWattHour.gigawattHour;

package/dist/dimensions/force.js

@@ -5,10 +5,10 @@ const Dimension_1 = require("../lib/Dimension");
 const definePrefixed_1 = require("../utils/definePrefixed");
 /** Force. Base unit: newton. */
 exports.force = new Dimension_1.Dimension("force");
-exports.newton = exports.force.base("newton", ["N", "newtons"]);
-exports.dyne = exports.force.unit("dyne", 0.00001, ["dyn", "dynes"]);
-exports.poundForce = exports.force.unit("poundForce", 4.4482216152605, ["lbf"]);
-exports.kilogramForce = exports.force.unit("kilogramForce", 9.80665, ["kgf"]);
+exports.newton = exports.force.base("newton", { symbol: "N", plural: "newtons" });
+exports.dyne = exports.force.unit("dyne", 0.00001, { symbol: "dyn", plural: "dynes" });
+exports.poundForce = exports.force.unit("poundForce", 4.4482216152605, { symbol: "lbf" });
+exports.kilogramForce = exports.force.unit("kilogramForce", 9.80665, { symbol: "kgf" });
 /** Every SI-prefixed newton (kilonewton, meganewton, millinewton, …), keyed by name. */
-exports.metricForce = (0, definePrefixed_1.definePrefixed)(exports.force, { name: "newton", symbol: "N" });
+exports.metricForce = (0, definePrefixed_1.definePrefixed)(exports.force, exports.newton);
 exports.meganewton = exports.metricForce.meganewton, exports.kilonewton = exports.metricForce.kilonewton, exports.millinewton = exports.metricForce.millinewton, exports.micronewton = exports.metricForce.micronewton;

package/dist/dimensions/frequency.js

@@ -5,7 +5,7 @@ const Dimension_1 = require("../lib/Dimension");
 const definePrefixed_1 = require("../utils/definePrefixed");
 /** Frequency. Base unit: hertz. */
 exports.frequency = new Dimension_1.Dimension("frequency");
-exports.hertz = exports.frequency.base("hertz", ["Hz"]);
+exports.hertz = exports.frequency.base("hertz", { symbol: "Hz" });
 /** Every SI-prefixed hertz (kilohertz, megahertz, gigahertz, …), keyed by name. */
-exports.metricFrequency = (0, definePrefixed_1.definePrefixed)(exports.frequency, { name: "hertz", symbol: "Hz" });
+exports.metricFrequency = (0, definePrefixed_1.definePrefixed)(exports.frequency, exports.hertz);
 exports.kilohertz = exports.metricFrequency.kilohertz, exports.megahertz = exports.metricFrequency.megahertz, exports.gigahertz = exports.metricFrequency.gigahertz, exports.terahertz = exports.metricFrequency.terahertz, exports.petahertz = exports.metricFrequency.petahertz, exports.millihertz = exports.metricFrequency.millihertz;

package/dist/dimensions/illuminance.js

@@ -5,9 +5,12 @@ const Dimension_1 = require("../lib/Dimension");
 const definePrefixed_1 = require("../utils/definePrefixed");
 /** Illuminance. Base unit: lux. */
 exports.illuminance = new Dimension_1.Dimension("illuminance");
-exports.lux = exports.illuminance.base("lux", ["lx"]);
-exports.footCandle = exports.illuminance.unit("footCandle", 10.764, ["fc", "ft-c"]);
-exports.phot = exports.illuminance.unit("phot", 10000, ["ph", "phots"]);
+exports.lux = exports.illuminance.base("lux", { symbol: "lx" });
+exports.footCandle = exports.illuminance.unit("footCandle", 10.764, {
+    symbol: "fc",
+    aliases: ["ft-c"],
+});
+exports.phot = exports.illuminance.unit("phot", 10000, { symbol: "ph", plural: "phots" });
 /** Every SI-prefixed lux (kilolux, millilux, microlux, …), keyed by name. */
-exports.metricIlluminance = (0, definePrefixed_1.definePrefixed)(exports.illuminance, { name: "lux", symbol: "lx" });
+exports.metricIlluminance = (0, definePrefixed_1.definePrefixed)(exports.illuminance, exports.lux);
 exports.kilolux = exports.metricIlluminance.kilolux, exports.millilux = exports.metricIlluminance.millilux, exports.microlux = exports.metricIlluminance.microlux;

package/dist/dimensions/length.js

@@ -5,12 +5,12 @@ const Dimension_1 = require("../lib/Dimension");
 const definePrefixed_1 = require("../utils/definePrefixed");
 /** Length / distance. Base unit: meter. */
 exports.length = new Dimension_1.Dimension("length");
-exports.meter = exports.length.base("meter", ["m", "meters"]);
+exports.meter = exports.length.base("meter", { symbol: "m", plural: "meters" });
 // Imperial / US customary.
-exports.inch = exports.length.unit("inch", 0.0254, ["in", "inches"]);
-exports.foot = exports.length.unit("foot", 0.3048, ["ft", "feet"]);
-exports.yard = exports.length.unit("yard", 0.9144, ["yd", "yards"]);
-exports.mile = exports.length.unit("mile", 1609.344, ["mi", "miles"]);
+exports.inch = exports.length.unit("inch", 0.0254, { symbol: "in", plural: "inches" });
+exports.foot = exports.length.unit("foot", 0.3048, { symbol: "ft", plural: "feet" });
+exports.yard = exports.length.unit("yard", 0.9144, { symbol: "yd", plural: "yards" });
+exports.mile = exports.length.unit("mile", 1609.344, { symbol: "mi", plural: "miles" });
 /** Every SI-prefixed meter (kilometer, centimeter, micrometer, …), keyed by name. */
-exports.metricLength = (0, definePrefixed_1.definePrefixed)(exports.length, { name: "meter", symbol: "m" });
+exports.metricLength = (0, definePrefixed_1.definePrefixed)(exports.length, exports.meter);
 exports.kilometer = exports.metricLength.kilometer, exports.hectometer = exports.metricLength.hectometer, exports.decameter = exports.metricLength.decameter, exports.decimeter = exports.metricLength.decimeter, exports.centimeter = exports.metricLength.centimeter, exports.millimeter = exports.metricLength.millimeter, exports.micrometer = exports.metricLength.micrometer, exports.nanometer = exports.metricLength.nanometer;

package/dist/dimensions/luminance.js

@@ -4,13 +4,10 @@ exports.nit = exports.stilb = exports.candelaPerSquareMeter = exports.luminance
 const Dimension_1 = require("../lib/Dimension");
 /** Luminance. Base unit: candela per square meter (the nit). */
 exports.luminance = new Dimension_1.Dimension("luminance");
-exports.candelaPerSquareMeter = exports.luminance.base("candelaPerSquareMeter", [
-    "cd/m²",
-    "cd/m2",
-    "nit",
-    "nits",
-    "nt",
-]);
-exports.stilb = exports.luminance.unit("stilb", 1e4, ["sb"]);
+exports.candelaPerSquareMeter = exports.luminance.base("candelaPerSquareMeter", {
+    symbol: "cd/m²",
+    aliases: ["cd/m2", "nit", "nits", "nt"],
+});
+exports.stilb = exports.luminance.unit("stilb", 1e4, { symbol: "sb" });
 /** Alias for {@link candelaPerSquareMeter}. */
 exports.nit = exports.candelaPerSquareMeter;

package/dist/dimensions/luminousIntensity.js

@@ -5,12 +5,12 @@ const Dimension_1 = require("../lib/Dimension");
 const definePrefixed_1 = require("../utils/definePrefixed");
 /** Luminous intensity. Base unit: candela. */
 exports.luminousIntensity = new Dimension_1.Dimension("luminousIntensity");
-exports.candela = exports.luminousIntensity.base("candela", ["cd"]);
-exports.candlepower = exports.luminousIntensity.unit("candlepower", 1, ["cp", "CP"]);
-exports.hefnerkerze = exports.luminousIntensity.unit("hefnerkerze", 0.92, ["HK"]);
-/** Every SI-prefixed candela (kilocandela, millicandela, …), keyed by name. */
-exports.metricLuminousIntensity = (0, definePrefixed_1.definePrefixed)(exports.luminousIntensity, {
-    name: "candela",
-    symbol: "cd",
+exports.candela = exports.luminousIntensity.base("candela", { symbol: "cd", plural: "candelas" });
+exports.candlepower = exports.luminousIntensity.unit("candlepower", 1, {
+    symbol: "cp",
+    aliases: ["CP"],
 });
+exports.hefnerkerze = exports.luminousIntensity.unit("hefnerkerze", 0.92, { symbol: "HK" });
+/** Every SI-prefixed candela (kilocandela, millicandela, …), keyed by name. */
+exports.metricLuminousIntensity = (0, definePrefixed_1.definePrefixed)(exports.luminousIntensity, exports.candela);
 exports.kilocandela = exports.metricLuminousIntensity.kilocandela, exports.millicandela = exports.metricLuminousIntensity.millicandela, exports.microcandela = exports.metricLuminousIntensity.microcandela;