measurable 1.0.0 → 1.1.1

package/README.md

@@ -64,12 +64,21 @@ Import any dimension or unit from `measurable/dimensions`:
 | ------------- | ---------- | ----------------------------------------------------------------------------------- |
 | `length`      | `meter`    | `kilometer`, `centimeter`, `millimeter`, `inch`, `foot`, `yard`, `mile`             |
 | `volume`      | `liter`    | `milliliter`, `us*`/`imperial*` `Gallon`/`Quart`/`Pint`/`Gill`/`FluidOunce`, `cup`, `tablespoon`, `teaspoon` |
-| `mass`        | `kilogram` | `gram`, `milligram`, `tonne`, `pound`, `ounce`, `stone`, `shortTon`, `longTon`      |
+| `mass`        | `gram`     | `kilogram`, `milligram`, `tonne`, `pound`, `ounce`, `stone`, `shortTon`, `longTon`  |
 | `time`        | `second`   | `millisecond`, `minute`, `hour`, `day`, `week`                                      |
 | `temperature` | `kelvin`   | `celsius`, `fahrenheit`                                                              |
 | `angle`       | `radian`   | `degree`, `gradian`, `turn`                                                          |
 | `force`       | `newton`   | `kilonewton`, `dyne`, `poundForce`, `kilogramForce`                                  |
 
+The metric units carry the **full SI prefix ladder** (yotta → yocto), generated for
+you: `length`, `mass`, `volume`, and `force` get every prefix (so `kilogram`
+itself is just the kilo-prefixed gram), while `time` and `angle` get the
+fractional prefixes only (e.g.
+`millisecond`, `microradian`). So `decimeter`, `hectometer`, `megagram`,
+`kiloliter`, `nanosecond`, etc. are all available and parse from their symbols
+(`dm`, `hm`, `Mg`, `kL`, `ns`, and `µm`/`um` for micro). You can apply the same
+ladder to your own dimensions with `definePrefixed` (see below).
+
 ## Built-in measurement systems
 
 Import `metric`, `imperial`, or `usCustomary` from `measurable/systems`.
@@ -106,6 +115,10 @@ 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`).
+
 ## Parsing strings
 
 `Quantity.parse(input, dimension, options?)` reads a string into a `Quantity`.
@@ -146,6 +159,92 @@ import { shortTon, tonne } from "measurable/dimensions";
 new Quantity(1, shortTon).in(tonne); // 0.90718474
 ```
 
+## Arithmetic
+
+Quantities can be combined. `plus`/`minus` take another `Quantity` (converted into
+the receiver's unit first, so the operands may use different units of the same
+dimension); `times`/`dividedBy` apply a dimensionless scalar, and `negate`/`abs`
+transform the magnitude. All return a **new** `Quantity` in the receiver's unit and
+leave the operands untouched.
+
+```ts
+import { Quantity } from "measurable";
+import { kilometer, mile } from "measurable/dimensions";
+
+new Quantity(1, mile).plus(new Quantity(1, kilometer));  // Quantity(1.6213…, mile)
+new Quantity(1, mile).minus(new Quantity(1, kilometer)); // Quantity(0.3786…, mile)
+new Quantity(2, mile).times(3);                          // Quantity(6, mile)
+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
+**affine** units (e.g. temperatures) is mathematically defined but physically
+questionable, since it adds absolute points rather than a difference.
+
+## Ratios
+
+`ratioTo` divides two quantities of the **same dimension** and returns a plain
+(dimensionless) number — _how many of one fit in the other_:
+
+```ts
+import { Quantity } from "measurable";
+import { liter, milliliter } from "measurable/dimensions";
+
+// How many 250 mL servings are in a 2 L bottle?
+new Quantity(2, liter).ratioTo(new Quantity(250, milliliter)); // 8
+```
+
+This is different from `.in(unit)`: `.in(milliliter)` only uses the *unit* on the
+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`.
+
+## 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`.
+
+```ts
+import { Quantity } from "measurable";
+import { kilometer, meter } from "measurable/dimensions";
+
+new Quantity(1, kilometer).equals(new Quantity(1000, meter));    // true
+new Quantity(1, meter).lessThan(new Quantity(1, kilometer));     // true
+new Quantity(1, kilometer).greaterThan(new Quantity(1, meter));  // true
+```
+
+Short aliases: **`eq`** (`equals`), **`ne`** (`notEquals`), **`lt`** (`lessThan`),
+**`gt`** (`greaterThan`), **`lte`** (`lessThanOrEqual`), **`gte`**
+(`greaterThanOrEqual`). Equality is exact, so values differing only by
+floating-point rounding from a conversion may compare unequal.
+
+`compareTo(other)` returns `-1`, `0`, or `1`, suitable as an `Array#sort`
+comparator: `quantities.sort((a, b) => a.compareTo(b))`.
+
+## Combining quantities
+
+`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`.
+
+```ts
+import { Quantity } from "measurable";
+import { kilometer, meter } from "measurable/dimensions";
+
+const a = new Quantity(1, kilometer);
+const b = new Quantity(500, meter);
+
+Quantity.min(a, b); // Quantity(500, meter) — the smaller
+Quantity.max(a, b); // Quantity(1, kilometer) — the larger
+Quantity.sum(a, b); // Quantity(1.5, kilometer) — total, in a's unit
+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
@@ -184,6 +283,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.
+
+```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 });
+
+new Quantity(1, prefixed.kilobit).in(bit); // 1000  (SI kilo = 1e3)
+```
+
 ### Tagging units into a measurement system
 
 ```ts
@@ -221,6 +336,19 @@ A passive handle, normally created via a dimension's builder methods rather than
 - `new Quantity(magnitude, unit)`
 - `.to(target)` → `Quantity`
 - `.in(target)` → `number`
+- `.toString()` → `string` — e.g. `"5 kilometer"`
+- `.plus(other)` / `.minus(other)` → `Quantity` — add/subtract another quantity (aliases: `add` / `sub`)
+- `.times(factor)` / `.dividedBy(divisor)` → `Quantity` — scale by a number (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)
+- `.equals(other)` / `.notEquals(other)` → `boolean` (aliases: `eq` / `ne`)
+- `.lessThan(other)` / `.greaterThan(other)` → `boolean` (aliases: `lt` / `gt`)
+- `.lessThanOrEqual(other)` / `.greaterThanOrEqual(other)` → `boolean` (aliases: `lte` / `gte`)
+- `.compareTo(other)` → `-1 | 0 | 1` — sort comparator
+- `.isZero()` / `.isPositive()` / `.isNegative()` → `boolean`
+- `Quantity.min(...quantities)` / `Quantity.max(...quantities)` / `Quantity.sum(...quantities)` → `Quantity`
 - `Quantity.parse(input, dimension, { prefer? })` → `Quantity`
 
 ### `MeasurementSystem`

package/dist/dimensions/angle.d.ts

@@ -5,3 +5,6 @@ export declare const radian: import("..").Unit;
 export declare const degree: import("..").Unit;
 export declare const gradian: import("..").Unit;
 export declare const turn: import("..").Unit;
+/** SI-submultiple radians (milliradian, microradian, …); larger angles use degree/turn. */
+export declare const metricAngle: Record<string, import("..").Unit>;
+export declare const milliradian: import("..").Unit, microradian: import("..").Unit;

package/dist/dimensions/angle.js

@@ -1,10 +1,14 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.turn = exports.gradian = exports.degree = exports.radian = exports.angle = void 0;
+exports.microradian = exports.milliradian = exports.metricAngle = exports.turn = exports.gradian = exports.degree = exports.radian = exports.angle = void 0;
 const Dimension_1 = require("../lib/Dimension");
+const prefixes_1 = require("../lib/prefixes");
 /** 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"]);
+/** SI-submultiple radians (milliradian, microradian, …); larger angles use degree/turn. */
+exports.metricAngle = (0, prefixes_1.definePrefixed)(exports.angle, { name: "radian", symbol: "rad", scale: 1 }, prefixes_1.SI_SUBMULTIPLE_PREFIXES);
+exports.milliradian = exports.metricAngle.milliradian, exports.microradian = exports.metricAngle.microradian;

package/dist/dimensions/force.d.ts

@@ -2,7 +2,9 @@ import { Dimension } from "../lib/Dimension";
 /** Force. Base unit: newton. */
 export declare const force: Dimension;
 export declare const newton: import("..").Unit;
-export declare const kilonewton: import("..").Unit;
 export declare const dyne: import("..").Unit;
 export declare const poundForce: import("..").Unit;
 export declare const kilogramForce: import("..").Unit;
+/** Every SI-prefixed newton (kilonewton, meganewton, millinewton, …), keyed by name. */
+export declare const metricForce: Record<string, import("..").Unit>;
+export declare const meganewton: import("..").Unit, kilonewton: import("..").Unit, millinewton: import("..").Unit, micronewton: import("..").Unit;

package/dist/dimensions/force.js

@@ -1,11 +1,14 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.kilogramForce = exports.poundForce = exports.dyne = exports.kilonewton = exports.newton = exports.force = void 0;
+exports.micronewton = exports.millinewton = exports.kilonewton = exports.meganewton = exports.metricForce = exports.kilogramForce = exports.poundForce = exports.dyne = exports.newton = exports.force = void 0;
 const Dimension_1 = require("../lib/Dimension");
+const prefixes_1 = require("../lib/prefixes");
 /** Force. Base unit: newton. */
 exports.force = new Dimension_1.Dimension("force");
 exports.newton = exports.force.base("newton", ["N", "newtons"]);
-exports.kilonewton = exports.force.unit("kilonewton", 1000, ["kN", "kilonewtons"]);
 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"]);
+/** Every SI-prefixed newton (kilonewton, meganewton, millinewton, …), keyed by name. */
+exports.metricForce = (0, prefixes_1.definePrefixed)(exports.force, { name: "newton", symbol: "N", scale: 1 });
+exports.meganewton = exports.metricForce.meganewton, exports.kilonewton = exports.metricForce.kilonewton, exports.millinewton = exports.metricForce.millinewton, exports.micronewton = exports.metricForce.micronewton;

package/dist/dimensions/length.d.ts

@@ -2,10 +2,10 @@ import { Dimension } from "../lib/Dimension";
 /** Length / distance. Base unit: meter. */
 export declare const length: Dimension;
 export declare const meter: import("..").Unit;
-export declare const kilometer: import("..").Unit;
-export declare const centimeter: import("..").Unit;
-export declare const millimeter: import("..").Unit;
 export declare const inch: import("..").Unit;
 export declare const foot: import("..").Unit;
 export declare const yard: import("..").Unit;
 export declare const mile: import("..").Unit;
+/** Every SI-prefixed meter (kilometer, centimeter, micrometer, …), keyed by name. */
+export declare const metricLength: Record<string, import("..").Unit>;
+export declare const kilometer: import("..").Unit, hectometer: import("..").Unit, decameter: import("..").Unit, decimeter: import("..").Unit, centimeter: import("..").Unit, millimeter: import("..").Unit, micrometer: import("..").Unit, nanometer: import("..").Unit;

package/dist/dimensions/length.js

@@ -1,14 +1,16 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.mile = exports.yard = exports.foot = exports.inch = exports.millimeter = exports.centimeter = exports.kilometer = exports.meter = exports.length = void 0;
+exports.nanometer = exports.micrometer = exports.millimeter = exports.centimeter = exports.decimeter = exports.decameter = exports.hectometer = exports.kilometer = exports.metricLength = exports.mile = exports.yard = exports.foot = exports.inch = exports.meter = exports.length = void 0;
 const Dimension_1 = require("../lib/Dimension");
+const prefixes_1 = require("../lib/prefixes");
 /** Length / distance. Base unit: meter. */
 exports.length = new Dimension_1.Dimension("length");
 exports.meter = exports.length.base("meter", ["m", "meters"]);
-exports.kilometer = exports.length.unit("kilometer", 1000, ["km", "kilometers"]);
-exports.centimeter = exports.length.unit("centimeter", 0.01, ["cm", "centimeters"]);
-exports.millimeter = exports.length.unit("millimeter", 0.001, ["mm", "millimeters"]);
+// 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"]);
+/** Every SI-prefixed meter (kilometer, centimeter, micrometer, …), keyed by name. */
+exports.metricLength = (0, prefixes_1.definePrefixed)(exports.length, { name: "meter", symbol: "m", scale: 1 });
+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/mass.d.ts

@@ -1,12 +1,17 @@
 import { Dimension } from "../lib/Dimension";
-/** Mass / weight. Base unit: kilogram. */
+/**
+ * Mass / weight. Base unit: gram. (SI's official base is the kilogram, but
+ * prefixes attach to the gram, so gram is the natural routing anchor — the
+ * choice of base is internal and does not affect any conversion.)
+ */
 export declare const mass: Dimension;
-export declare const kilogram: import("..").Unit;
 export declare const gram: import("..").Unit;
-export declare const milligram: import("..").Unit;
-export declare const tonne: import("..").Unit;
 export declare const pound: import("..").Unit;
 export declare const ounce: import("..").Unit;
 export declare const stone: import("..").Unit;
+export declare const tonne: import("..").Unit;
 export declare const shortTon: import("..").Unit;
 export declare const longTon: import("..").Unit;
+/** Every SI-prefixed gram — including the kilogram — keyed by name. */
+export declare const metricMass: Record<string, import("..").Unit>;
+export declare const kilogram: import("..").Unit, megagram: import("..").Unit, hectogram: import("..").Unit, decagram: import("..").Unit, decigram: import("..").Unit, centigram: import("..").Unit, milligram: import("..").Unit, microgram: import("..").Unit, nanogram: import("..").Unit;

package/dist/dimensions/mass.js

@@ -1,17 +1,24 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.longTon = exports.shortTon = exports.stone = exports.ounce = exports.pound = exports.tonne = exports.milligram = exports.gram = exports.kilogram = exports.mass = void 0;
+exports.nanogram = exports.microgram = exports.milligram = exports.centigram = exports.decigram = exports.decagram = exports.hectogram = exports.megagram = exports.kilogram = exports.metricMass = exports.longTon = exports.shortTon = exports.tonne = exports.stone = exports.ounce = exports.pound = exports.gram = exports.mass = void 0;
 const Dimension_1 = require("../lib/Dimension");
-/** Mass / weight. Base unit: kilogram. */
+const prefixes_1 = require("../lib/prefixes");
+/**
+ * Mass / weight. Base unit: gram. (SI's official base is the kilogram, but
+ * prefixes attach to the gram, so gram is the natural routing anchor — the
+ * choice of base is internal and does not affect any conversion.)
+ */
 exports.mass = new Dimension_1.Dimension("mass");
-exports.kilogram = exports.mass.base("kilogram", ["kg", "kilograms"]);
-exports.gram = exports.mass.unit("gram", 0.001, ["g", "grams"]);
-exports.milligram = exports.mass.unit("milligram", 0.000001, ["mg", "milligrams"]);
-exports.tonne = exports.mass.unit("tonne", 1000, ["t", "tonnes"]);
-exports.pound = exports.mass.unit("pound", 0.45359237, ["lb", "lbs", "pounds"]);
-exports.ounce = exports.mass.unit("ounce", 0.028349523125, ["oz", "ounces"]);
-exports.stone = exports.mass.unit("stone", 6.35029318, ["st", "stones"]);
+exports.gram = exports.mass.base("gram", ["g", "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"]);
 // 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", 907.18474, ["ton", "tons"]);
-exports.longTon = exports.mass.unit("longTon", 1016.0469088, ["ton", "tons"]);
+exports.shortTon = exports.mass.unit("shortTon", 907184.74, ["ton", "tons"]);
+exports.longTon = exports.mass.unit("longTon", 1016046.9088, ["ton", "tons"]);
+/** Every SI-prefixed gram — including the kilogram — keyed by name. */
+exports.metricMass = (0, prefixes_1.definePrefixed)(exports.mass, { name: "gram", symbol: "g", scale: 1 });
+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/time.d.ts

@@ -2,8 +2,13 @@ import { Dimension } from "../lib/Dimension";
 /** Time / duration. Base unit: second. */
 export declare const time: Dimension;
 export declare const second: import("..").Unit;
-export declare const millisecond: import("..").Unit;
 export declare const minute: import("..").Unit;
 export declare const hour: import("..").Unit;
 export declare const day: import("..").Unit;
 export declare const week: import("..").Unit;
+/**
+ * SI-submultiple seconds (millisecond, microsecond, nanosecond, …). Only
+ * fractions are generated; larger spans use minute/hour/day/week above.
+ */
+export declare const metricTime: Record<string, import("..").Unit>;
+export declare const millisecond: import("..").Unit, microsecond: import("..").Unit, nanosecond: import("..").Unit, picosecond: import("..").Unit;

package/dist/dimensions/time.js

@@ -1,12 +1,18 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.week = exports.day = exports.hour = exports.minute = exports.millisecond = exports.second = exports.time = void 0;
+exports.picosecond = exports.nanosecond = exports.microsecond = exports.millisecond = exports.metricTime = exports.week = exports.day = exports.hour = exports.minute = exports.second = exports.time = void 0;
 const Dimension_1 = require("../lib/Dimension");
+const prefixes_1 = require("../lib/prefixes");
 /** Time / duration. Base unit: second. */
 exports.time = new Dimension_1.Dimension("time");
 exports.second = exports.time.base("second", ["s", "sec", "secs", "seconds"]);
-exports.millisecond = exports.time.unit("millisecond", 0.001, ["ms", "milliseconds"]);
 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"]);
+/**
+ * SI-submultiple seconds (millisecond, microsecond, nanosecond, …). Only
+ * fractions are generated; larger spans use minute/hour/day/week above.
+ */
+exports.metricTime = (0, prefixes_1.definePrefixed)(exports.time, { name: "second", symbol: "s", scale: 1 }, prefixes_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.d.ts

@@ -2,7 +2,6 @@ import { Dimension } from "../lib/Dimension";
 /** Volume / capacity. Base unit: liter. */
 export declare const volume: Dimension;
 export declare const liter: import("..").Unit;
-export declare const milliliter: import("..").Unit;
 export declare const usGallon: import("..").Unit;
 export declare const usQuart: import("..").Unit;
 export declare const usPint: import("..").Unit;
@@ -16,3 +15,6 @@ export declare const imperialFluidOunce: import("..").Unit;
 export declare const cup: import("..").Unit;
 export declare const tablespoon: import("..").Unit;
 export declare const teaspoon: import("..").Unit;
+/** Every SI-prefixed liter (milliliter, centiliter, kiloliter, …), keyed by name. */
+export declare const metricVolume: Record<string, import("..").Unit>;
+export declare const kiloliter: import("..").Unit, hectoliter: import("..").Unit, decaliter: import("..").Unit, deciliter: import("..").Unit, centiliter: import("..").Unit, milliliter: import("..").Unit;

package/dist/dimensions/volume.js

@@ -1,11 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.teaspoon = exports.tablespoon = exports.cup = exports.imperialFluidOunce = exports.imperialGill = exports.imperialPint = exports.imperialQuart = exports.imperialGallon = exports.usFluidOunce = exports.usGill = exports.usPint = exports.usQuart = exports.usGallon = exports.milliliter = exports.liter = exports.volume = void 0;
+exports.milliliter = exports.centiliter = exports.deciliter = exports.decaliter = exports.hectoliter = exports.kiloliter = exports.metricVolume = exports.teaspoon = exports.tablespoon = exports.cup = exports.imperialFluidOunce = exports.imperialGill = exports.imperialPint = exports.imperialQuart = exports.imperialGallon = exports.usFluidOunce = exports.usGill = exports.usPint = exports.usQuart = exports.usGallon = exports.liter = exports.volume = void 0;
 const Dimension_1 = require("../lib/Dimension");
+const prefixes_1 = require("../lib/prefixes");
 /** Volume / capacity. Base unit: liter. */
 exports.volume = new Dimension_1.Dimension("volume");
 exports.liter = exports.volume.base("liter", ["L", "liters"]);
-exports.milliliter = exports.volume.unit("milliliter", 0.001, ["mL", "milliliters"]);
 // 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
@@ -32,3 +32,6 @@ exports.imperialFluidOunce = exports.volume.unit("imperialFluidOunce", 0.0284130
 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"]);
+/** Every SI-prefixed liter (milliliter, centiliter, kiloliter, …), keyed by name. */
+exports.metricVolume = (0, prefixes_1.definePrefixed)(exports.volume, { name: "liter", symbol: "L", scale: 1 });
+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/index.d.ts

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

package/dist/index.js

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

package/dist/lib/Quantity.d.ts

@@ -15,6 +15,88 @@ export declare class Quantity {
     to(target: Unit): Quantity;
     /** Return this quantity's raw magnitude expressed in `target`. */
     in(target: Unit): number;
+    /** Render as `"<magnitude> <unit name>"`, e.g. `"5 kilometer"`. */
+    toString(): string;
+    /**
+     * Add another quantity, returned in *this* quantity's unit. The other operand
+     * is converted into this unit first, so the two may use different units of the
+     * same dimension (e.g. `mile.plus(km)`). Throws {@link InvalidConversionError}
+     * if the operands belong to different dimensions.
+     *
+     * Note: for affine units (e.g. temperature) addition is mathematically defined
+     * but physically questionable, since it adds absolute points rather than a
+     * difference.
+     */
+    plus(other: Quantity): Quantity;
+    /** Subtract another quantity, returned in this quantity's unit. */
+    minus(other: Quantity): Quantity;
+    /** Scale this quantity by a dimensionless factor. */
+    times(factor: number): Quantity;
+    /** Divide this quantity by a dimensionless divisor. */
+    dividedBy(divisor: number): Quantity;
+    /**
+     * Divide this quantity by `other` of the same dimension, yielding the
+     * dimensionless ratio between them — i.e. how many of `other` fit in this.
+     * Unlike {@link in}, this accounts for `other`'s magnitude, not just its unit.
+     * Throws {@link InvalidConversionError} across dimensions.
+     */
+    ratioTo(other: Quantity): number;
+    /** Return this quantity with its magnitude negated. */
+    negate(): Quantity;
+    /** Return this quantity with a non-negative magnitude. */
+    abs(): Quantity;
+    /** Clamp this quantity to the range [`lower`, `upper`], returned in this unit. */
+    clamp(lower: Quantity, upper: Quantity): Quantity;
+    /** Return this quantity with its magnitude rounded to `decimals` places (default 0). */
+    round(decimals?: number): Quantity;
+    /** Alias for {@link plus}. */
+    add(other: Quantity): Quantity;
+    /** Alias for {@link minus}. */
+    sub(other: Quantity): Quantity;
+    /** Alias for {@link times}. */
+    mul(factor: number): Quantity;
+    /** Alias for {@link dividedBy}. */
+    div(divisor: number): Quantity;
+    /**
+     * Whether this quantity equals `other`, compared in this quantity's unit.
+     * Throws {@link InvalidConversionError} if the operands belong to different
+     * dimensions. Comparison is exact, so values that differ only by
+     * floating-point rounding from a conversion may compare unequal.
+     */
+    equals(other: Quantity): boolean;
+    /** Whether this quantity does not equal `other`. */
+    notEquals(other: Quantity): boolean;
+    /** Whether this quantity is less than `other`. */
+    lessThan(other: Quantity): boolean;
+    /** Whether this quantity is greater than `other`. */
+    greaterThan(other: Quantity): boolean;
+    /** Whether this quantity is less than or equal to `other`. */
+    lessThanOrEqual(other: Quantity): boolean;
+    /** Whether this quantity is greater than or equal to `other`. */
+    greaterThanOrEqual(other: Quantity): boolean;
+    /** Alias for {@link equals}. */
+    eq(other: Quantity): boolean;
+    /** Alias for {@link notEquals}. */
+    ne(other: Quantity): boolean;
+    /** Alias for {@link lessThan}. */
+    lt(other: Quantity): boolean;
+    /** Alias for {@link greaterThan}. */
+    gt(other: Quantity): boolean;
+    /** Alias for {@link lessThanOrEqual}. */
+    lte(other: Quantity): boolean;
+    /** Alias for {@link greaterThanOrEqual}. */
+    gte(other: Quantity): boolean;
+    /**
+     * Compare with `other` (in this quantity's unit): `-1` if this is smaller, `1`
+     * if larger, `0` if equal. Suitable as an `Array#sort` comparator.
+     */
+    compareTo(other: Quantity): number;
+    /** Whether this quantity's magnitude is exactly zero. */
+    isZero(): boolean;
+    /** Whether this quantity's magnitude is greater than zero. */
+    isPositive(): boolean;
+    /** Whether this quantity's magnitude is less than zero. */
+    isNegative(): boolean;
     /**
      * Parse a string into a `Quantity` using a dimension's known units and aliases.
      *
@@ -29,4 +111,10 @@ export declare class Quantity {
      * `options.prefer` to pick the candidate belonging to that measurement system.
      */
     static parse(str: string, dimension: Dimension, options?: ParseOptions): Quantity;
+    /** The smallest of the given quantities (by value); requires at least one. */
+    static min(first: Quantity, ...rest: Quantity[]): Quantity;
+    /** The largest of the given quantities (by value); requires at least one. */
+    static max(first: Quantity, ...rest: Quantity[]): Quantity;
+    /** The sum of the given quantities, in the first one's unit; requires at least one. */
+    static sum(first: Quantity, ...rest: Quantity[]): Quantity;
 }

package/dist/lib/Quantity.js

@@ -18,6 +18,162 @@ class Quantity {
     in(target) {
         return this.unit.dimension.convert(this.magnitude, this.unit, target);
     }
+    /** Render as `"<magnitude> <unit name>"`, e.g. `"5 kilometer"`. */
+    toString() {
+        return `${this.magnitude} ${this.unit.name}`;
+    }
+    /**
+     * Add another quantity, returned in *this* quantity's unit. The other operand
+     * is converted into this unit first, so the two may use different units of the
+     * same dimension (e.g. `mile.plus(km)`). Throws {@link InvalidConversionError}
+     * if the operands belong to different dimensions.
+     *
+     * Note: for affine units (e.g. temperature) addition is mathematically defined
+     * but physically questionable, since it adds absolute points rather than a
+     * difference.
+     */
+    plus(other) {
+        return new Quantity(this.magnitude + other.in(this.unit), this.unit);
+    }
+    /** Subtract another quantity, returned in this quantity's unit. */
+    minus(other) {
+        return new Quantity(this.magnitude - other.in(this.unit), this.unit);
+    }
+    /** Scale this quantity by a dimensionless factor. */
+    times(factor) {
+        return new Quantity(this.magnitude * factor, this.unit);
+    }
+    /** Divide this quantity by a dimensionless divisor. */
+    dividedBy(divisor) {
+        return new Quantity(this.magnitude / divisor, this.unit);
+    }
+    /**
+     * Divide this quantity by `other` of the same dimension, yielding the
+     * dimensionless ratio between them — i.e. how many of `other` fit in this.
+     * Unlike {@link in}, this accounts for `other`'s magnitude, not just its unit.
+     * Throws {@link InvalidConversionError} across dimensions.
+     */
+    ratioTo(other) {
+        return this.magnitude / other.in(this.unit);
+    }
+    /** Return this quantity with its magnitude negated. */
+    negate() {
+        return new Quantity(-this.magnitude, this.unit);
+    }
+    /** Return this quantity with a non-negative magnitude. */
+    abs() {
+        return new Quantity(Math.abs(this.magnitude), this.unit);
+    }
+    /** Clamp this quantity to the range [`lower`, `upper`], returned in this unit. */
+    clamp(lower, upper) {
+        if (this.lessThan(lower)) {
+            return lower.to(this.unit);
+        }
+        if (this.greaterThan(upper)) {
+            return upper.to(this.unit);
+        }
+        return this;
+    }
+    /** Return this quantity with its magnitude rounded to `decimals` places (default 0). */
+    round(decimals = 0) {
+        const factor = 10 ** decimals;
+        return new Quantity(Math.round(this.magnitude * factor) / factor, this.unit);
+    }
+    /** Alias for {@link plus}. */
+    add(other) {
+        return this.plus(other);
+    }
+    /** Alias for {@link minus}. */
+    sub(other) {
+        return this.minus(other);
+    }
+    /** Alias for {@link times}. */
+    mul(factor) {
+        return this.times(factor);
+    }
+    /** Alias for {@link dividedBy}. */
+    div(divisor) {
+        return this.dividedBy(divisor);
+    }
+    /**
+     * Whether this quantity equals `other`, compared in this quantity's unit.
+     * Throws {@link InvalidConversionError} if the operands belong to different
+     * dimensions. Comparison is exact, so values that differ only by
+     * floating-point rounding from a conversion may compare unequal.
+     */
+    equals(other) {
+        return this.magnitude === other.in(this.unit);
+    }
+    /** Whether this quantity does not equal `other`. */
+    notEquals(other) {
+        return !this.equals(other);
+    }
+    /** Whether this quantity is less than `other`. */
+    lessThan(other) {
+        return this.magnitude < other.in(this.unit);
+    }
+    /** Whether this quantity is greater than `other`. */
+    greaterThan(other) {
+        return this.magnitude > other.in(this.unit);
+    }
+    /** Whether this quantity is less than or equal to `other`. */
+    lessThanOrEqual(other) {
+        return this.magnitude <= other.in(this.unit);
+    }
+    /** Whether this quantity is greater than or equal to `other`. */
+    greaterThanOrEqual(other) {
+        return this.magnitude >= other.in(this.unit);
+    }
+    /** Alias for {@link equals}. */
+    eq(other) {
+        return this.equals(other);
+    }
+    /** Alias for {@link notEquals}. */
+    ne(other) {
+        return this.notEquals(other);
+    }
+    /** Alias for {@link lessThan}. */
+    lt(other) {
+        return this.lessThan(other);
+    }
+    /** Alias for {@link greaterThan}. */
+    gt(other) {
+        return this.greaterThan(other);
+    }
+    /** Alias for {@link lessThanOrEqual}. */
+    lte(other) {
+        return this.lessThanOrEqual(other);
+    }
+    /** Alias for {@link greaterThanOrEqual}. */
+    gte(other) {
+        return this.greaterThanOrEqual(other);
+    }
+    /**
+     * Compare with `other` (in this quantity's unit): `-1` if this is smaller, `1`
+     * if larger, `0` if equal. Suitable as an `Array#sort` comparator.
+     */
+    compareTo(other) {
+        const value = other.in(this.unit);
+        if (this.magnitude < value) {
+            return -1;
+        }
+        if (this.magnitude > value) {
+            return 1;
+        }
+        return 0;
+    }
+    /** Whether this quantity's magnitude is exactly zero. */
+    isZero() {
+        return this.magnitude === 0;
+    }
+    /** Whether this quantity's magnitude is greater than zero. */
+    isPositive() {
+        return this.magnitude > 0;
+    }
+    /** Whether this quantity's magnitude is less than zero. */
+    isNegative() {
+        return this.magnitude < 0;
+    }
     /**
      * Parse a string into a `Quantity` using a dimension's known units and aliases.
      *
@@ -50,6 +206,18 @@ class Quantity {
         }
         return new Quantity(finest.fromBase(total), finest);
     }
+    /** The smallest of the given quantities (by value); requires at least one. */
+    static min(first, ...rest) {
+        return rest.reduce((smallest, q) => (q.lessThan(smallest) ? q : smallest), first);
+    }
+    /** The largest of the given quantities (by value); requires at least one. */
+    static max(first, ...rest) {
+        return rest.reduce((largest, q) => (q.greaterThan(largest) ? q : largest), first);
+    }
+    /** The sum of the given quantities, in the first one's unit; requires at least one. */
+    static sum(first, ...rest) {
+        return rest.reduce((total, q) => total.plus(q), first);
+    }
 }
 exports.Quantity = Quantity;
 /** Resolve a token to a single unit, disambiguating shared aliases by system. */

package/dist/lib/prefixes.d.ts

@@ -0,0 +1,34 @@
+import type { Dimension } from "./Dimension";
+import type { Unit } from "./Unit";
+/** A metric (SI) prefix: a name, symbol, and power-of-ten factor. */
+export interface SiPrefix {
+    name: string;
+    symbol: string;
+    factor: number;
+}
+/** The full set of SI prefixes, yotta (1e24) down to yocto (1e-24). */
+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). */
+    scale: number;
+}
+/**
+ * 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).
+ *
+ * Prefixes whose generated name already exists on the dimension are skipped, so
+ * a base like "kilogram" is left intact when prefixing "gram".
+ *
+ * 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>;

package/dist/lib/prefixes.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SI_SUBMULTIPLE_PREFIXES = exports.SI_PREFIXES = void 0;
+exports.definePrefixed = definePrefixed;
+/** The full set of SI prefixes, yotta (1e24) down to yocto (1e-24). */
+exports.SI_PREFIXES = [
+    { name: "yotta", symbol: "Y", factor: 1e24 },
+    { name: "zetta", symbol: "Z", factor: 1e21 },
+    { name: "exa", symbol: "E", factor: 1e18 },
+    { name: "peta", symbol: "P", factor: 1e15 },
+    { name: "tera", symbol: "T", factor: 1e12 },
+    { name: "giga", symbol: "G", factor: 1e9 },
+    { name: "mega", symbol: "M", factor: 1e6 },
+    { name: "kilo", symbol: "k", factor: 1e3 },
+    { name: "hecto", symbol: "h", factor: 1e2 },
+    { name: "deca", symbol: "da", factor: 1e1 },
+    { name: "deci", symbol: "d", factor: 1e-1 },
+    { name: "centi", symbol: "c", factor: 1e-2 },
+    { name: "milli", symbol: "m", factor: 1e-3 },
+    { name: "micro", symbol: "µ", factor: 1e-6 },
+    { name: "nano", symbol: "n", factor: 1e-9 },
+    { name: "pico", symbol: "p", factor: 1e-12 },
+    { name: "femto", symbol: "f", factor: 1e-15 },
+    { name: "atto", symbol: "a", factor: 1e-18 },
+    { name: "zepto", symbol: "z", factor: 1e-21 },
+    { name: "yocto", symbol: "y", factor: 1e-24 },
+];
+/** 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).
+ *
+ * Prefixes whose generated name already exists on the dimension are skipped, so
+ * a base like "kilogram" is left intact when prefixing "gram".
+ *
+ * Returns the created units keyed by name, for spreading into a
+ * {@link MeasurementSystem} or destructuring into named exports.
+ */
+function definePrefixed(dimension, reference, prefixes = exports.SI_PREFIXES) {
+    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}`);
+        }
+        units[name] = dimension.unit(name, reference.scale * prefix.factor, aliases);
+    }
+    return units;
+}

package/dist/systems/metric.d.ts

@@ -1,3 +1,3 @@
 import { MeasurementSystem } from "../lib/MeasurementSystem";
-/** The metric / SI standard. */
+/** The metric / SI standard, including the full SI-prefixed unit ladders. */
 export declare const metric: MeasurementSystem;

package/dist/systems/metric.js

@@ -6,13 +6,13 @@ const mass_1 = require("../dimensions/mass");
 const temperature_1 = require("../dimensions/temperature");
 const volume_1 = require("../dimensions/volume");
 const MeasurementSystem_1 = require("../lib/MeasurementSystem");
-/** The metric / SI standard. */
+/** The metric / SI standard, including the full SI-prefixed unit ladders. */
 exports.metric = new MeasurementSystem_1.MeasurementSystem("metric").add(
 // length
-length_1.meter, length_1.kilometer, length_1.centimeter, length_1.millimeter, 
+length_1.meter, ...Object.values(length_1.metricLength), 
 // mass
-mass_1.kilogram, mass_1.gram, mass_1.milligram, mass_1.tonne, 
+mass_1.gram, mass_1.tonne, ...Object.values(mass_1.metricMass), 
 // volume
-volume_1.liter, volume_1.milliliter, 
+volume_1.liter, ...Object.values(volume_1.metricVolume), 
 // temperature
 temperature_1.kelvin, temperature_1.celsius);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "measurable",
-  "version": "1.0.0",
+  "version": "1.1.1",
   "description": "Convert between units of measurement with custom and built-in systems",
   "keywords": [
     "conversion",
@@ -49,5 +49,6 @@
     "format": "biome format .",
     "typecheck": "tsc --noEmit",
     "test": "vitest run"
-  }
+  },
+  "readme": "# measurable\n\nConvert between units of measurement, with batteries-included common units and\nfirst-class support for defining your own.\n\n- **No drift** — each unit defines a single transform to its dimension's base\n  unit; reverse conversions are derived, never stored, so they can't fall out of\n  sync.\n- **Free chaining** — any unit converts to any other in the same dimension\n  (e.g. `mile → inch`) without you defining every pair.\n- **Affine units** — temperature scales (°C/°F/K) and anything else needing an\n  offset, not just a scale factor.\n- **Two orthogonal ideas** — a **dimension** decides what _can_ convert; a\n  **measurement system** (metric/imperial/US) is a tag that never gates\n  conversion but powers filtering, formatting, and parse disambiguation.\n\n## Installation\n\n```sh\nnpm install measurable\n```\n\n## Entry points\n\nThe package is split into three import paths so the core stays lean:\n\n| Import                     | What you get                                                              |\n| -------------------------- | ------------------------------------------------------------------------- |\n| `measurable`             | The building blocks: `Quantity`, `Dimension`, `MeasurementSystem`, `Unit`, errors |\n| `measurable/dimensions`  | Predefined dimensions and their units (`length`, `meter`, `volume`, …)    |\n| `measurable/systems`     | Predefined measurement systems (`metric`, `imperial`, `usCustomary`)      |\n\n## Quick start\n\n```ts\nimport { Quantity } from \"measurable\";\nimport { meter, mile, celsius, fahrenheit } from \"measurable/dimensions\";\n\n// Convert: `.to()` returns a Quantity, `.in()` returns a raw number.\nnew Quantity(5, mile).to(meter).magnitude; // 8046.72\nnew Quantity(5, mile).in(meter);           // 8046.72\n\n// Affine scales work the same way.\nnew Quantity(100, celsius).in(fahrenheit); // 212\n```\n\n## Concepts\n\n- **`Dimension`** — a kind of measurable quantity (length, volume, mass, …). It\n  owns a canonical **base unit** and is where all conversion happens. A unit\n  belongs to exactly one dimension.\n- **`Unit`** — a name plus a transform (`toBase` / `fromBase`) into its\n  dimension's base unit. Created through a dimension's builder methods.\n- **`Quantity`** — a magnitude paired with a unit (e.g. `5 kilometer`).\n- **`MeasurementSystem`** — a cross-dimension tag (metric/imperial/…). A unit can\n  belong to many; membership is optional and never affects whether a conversion\n  is allowed.\n\n## Built-in dimensions\n\nImport any dimension or unit from `measurable/dimensions`:\n\n| Dimension     | Base       | Units (a selection)                                                                 |\n| ------------- | ---------- | ----------------------------------------------------------------------------------- |\n| `length`      | `meter`    | `kilometer`, `centimeter`, `millimeter`, `inch`, `foot`, `yard`, `mile`             |\n| `volume`      | `liter`    | `milliliter`, `us*`/`imperial*` `Gallon`/`Quart`/`Pint`/`Gill`/`FluidOunce`, `cup`, `tablespoon`, `teaspoon` |\n| `mass`        | `gram`     | `kilogram`, `milligram`, `tonne`, `pound`, `ounce`, `stone`, `shortTon`, `longTon`  |\n| `time`        | `second`   | `millisecond`, `minute`, `hour`, `day`, `week`                                      |\n| `temperature` | `kelvin`   | `celsius`, `fahrenheit`                                                              |\n| `angle`       | `radian`   | `degree`, `gradian`, `turn`                                                          |\n| `force`       | `newton`   | `kilonewton`, `dyne`, `poundForce`, `kilogramForce`                                  |\n\nThe metric units carry the **full SI prefix ladder** (yotta → yocto), generated for\nyou: `length`, `mass`, `volume`, and `force` get every prefix (so `kilogram`\nitself is just the kilo-prefixed gram), while `time` and `angle` get the\nfractional prefixes only (e.g.\n`millisecond`, `microradian`). So `decimeter`, `hectometer`, `megagram`,\n`kiloliter`, `nanosecond`, etc. are all available and parse from their symbols\n(`dm`, `hm`, `Mg`, `kL`, `ns`, and `µm`/`um` for micro). You can apply the same\nladder to your own dimensions with `definePrefixed` (see below).\n\n## Built-in measurement systems\n\nImport `metric`, `imperial`, or `usCustomary` from `measurable/systems`.\n\n```ts\nimport { foot } from \"measurable/dimensions\";\nimport { imperial, usCustomary, metric } from \"measurable/systems\";\n\nimperial.has(foot);      // true  — a unit can belong to several systems\nusCustomary.has(foot);   // true\nmetric.has(foot);        // false\n```\n\n### Listing units in a system\n\n```ts\nimport { length } from \"measurable/dimensions\";\nimport { metric } from \"measurable/systems\";\n\nmetric.in(length).map((u) => u.name); // [\"meter\", \"kilometer\", \"centimeter\", \"millimeter\"]\n```\n\n### Best-fit formatting\n\n`express` re-expresses a quantity in a system's most readable unit (the largest\nunit whose magnitude is still ≥ 1):\n\n```ts\nimport { Quantity } from \"measurable\";\nimport { meter } from \"measurable/dimensions\";\nimport { metric, imperial } from \"measurable/systems\";\n\nmetric.express(new Quantity(5000, meter));    // Quantity(5, kilometer)\nimperial.express(new Quantity(5000, meter));  // Quantity(3.107…, mile)\n```\n\nA `Quantity` also has a `toString()` that renders `\"<magnitude> <unit name>\"`\n(e.g. `new Quantity(5, kilometer).toString()` → `\"5 kilometer\"`), and `round(decimals)`\nto trim the magnitude for display (`new Quantity(1.6213, mile).round(2)` → `1.62 mile`).\n\n## Parsing strings\n\n`Quantity.parse(input, dimension, options?)` reads a string into a `Quantity`.\nCompound inputs are summed and returned in the finest unit present:\n\n```ts\nimport { Quantity } from \"measurable\";\nimport { length, time } from \"measurable/dimensions\";\n\nQuantity.parse(\"1km\", length);         // Quantity(1, kilometer)\nQuantity.parse(\"5 hr\", time);          // Quantity(5, hour)\nQuantity.parse(\"5hr 20min\", time);     // Quantity(320, minute)\n```\n\n### Ambiguous aliases\n\nSome names mean different things in different systems — a US gallon (3.785 L) is\nnot an imperial gallon (4.546 L), and `ton` could be short or long. These are\ndistinct units that share an alias, so an unqualified parse throws; pass a\n`prefer`red system to disambiguate:\n\n```ts\nimport { Quantity, AmbiguousUnitError } from \"measurable\";\nimport { volume, mass } from \"measurable/dimensions\";\nimport { usCustomary, imperial } from \"measurable/systems\";\n\nQuantity.parse(\"1 gallon\", volume);                                    // throws AmbiguousUnitError\nQuantity.parse(\"1 gallon\", volume, { prefer: usCustomary }).unit.name; // \"usGallon\"\nQuantity.parse(\"1 ton\", mass, { prefer: imperial }).unit.name;         // \"longTon\"\n```\n\nConversion itself is governed only by the dimension, so cross-system conversions\nalways work regardless of tags:\n\n```ts\nimport { shortTon, tonne } from \"measurable/dimensions\";\n\nnew Quantity(1, shortTon).in(tonne); // 0.90718474\n```\n\n## Arithmetic\n\nQuantities can be combined. `plus`/`minus` take another `Quantity` (converted into\nthe receiver's unit first, so the operands may use different units of the same\ndimension); `times`/`dividedBy` apply a dimensionless scalar, and `negate`/`abs`\ntransform the magnitude. All return a **new** `Quantity` in the receiver's unit and\nleave the operands untouched.\n\n```ts\nimport { Quantity } from \"measurable\";\nimport { kilometer, mile } from \"measurable/dimensions\";\n\nnew Quantity(1, mile).plus(new Quantity(1, kilometer));  // Quantity(1.6213…, mile)\nnew Quantity(1, mile).minus(new Quantity(1, kilometer)); // Quantity(0.3786…, mile)\nnew Quantity(2, mile).times(3);                          // Quantity(6, mile)\nnew Quantity(6, mile).dividedBy(2);                      // Quantity(3, mile)\n```\n\nShort aliases are available: **`add`** (`plus`), **`sub`** (`minus`), **`mul`**\n(`times`), **`div`** (`dividedBy`).\n\nCombining different dimensions throws `InvalidConversionError`. Note that adding\n**affine** units (e.g. temperatures) is mathematically defined but physically\nquestionable, since it adds absolute points rather than a difference.\n\n## Ratios\n\n`ratioTo` divides two quantities of the **same dimension** and returns a plain\n(dimensionless) number — _how many of one fit in the other_:\n\n```ts\nimport { Quantity } from \"measurable\";\nimport { liter, milliliter } from \"measurable/dimensions\";\n\n// How many 250 mL servings are in a 2 L bottle?\nnew Quantity(2, liter).ratioTo(new Quantity(250, milliliter)); // 8\n```\n\nThis is different from `.in(unit)`: `.in(milliliter)` only uses the *unit* on the\nright (giving `2000`), whereas `ratioTo` also uses the other quantity's\n**magnitude** (the `250`), so it answers \"how many of *that quantity* fit in this\none.\" It's the inverse of scalar `times` — `b.times(a.ratioTo(b))` reconstructs\n`a`. Comparing different dimensions throws `InvalidConversionError`.\n\n## Comparison\n\n`equals`/`notEquals`/`lessThan`/`greaterThan`/`lessThanOrEqual`/`greaterThanOrEqual`\ncompare two quantities (the other is converted into the receiver's unit first),\nreturning a boolean. Comparing different dimensions throws `InvalidConversionError`.\n\n```ts\nimport { Quantity } from \"measurable\";\nimport { kilometer, meter } from \"measurable/dimensions\";\n\nnew Quantity(1, kilometer).equals(new Quantity(1000, meter));    // true\nnew Quantity(1, meter).lessThan(new Quantity(1, kilometer));     // true\nnew Quantity(1, kilometer).greaterThan(new Quantity(1, meter));  // true\n```\n\nShort aliases: **`eq`** (`equals`), **`ne`** (`notEquals`), **`lt`** (`lessThan`),\n**`gt`** (`greaterThan`), **`lte`** (`lessThanOrEqual`), **`gte`**\n(`greaterThanOrEqual`). Equality is exact, so values differing only by\nfloating-point rounding from a conversion may compare unequal.\n\n`compareTo(other)` returns `-1`, `0`, or `1`, suitable as an `Array#sort`\ncomparator: `quantities.sort((a, b) => a.compareTo(b))`.\n\n## Combining quantities\n\n`Quantity.min`/`max`/`sum` aggregate several quantities at once; `clamp` is an\ninstance method that bounds one quantity to a range. Each converts operands as\nneeded, so mixing dimensions throws `InvalidConversionError`.\n\n```ts\nimport { Quantity } from \"measurable\";\nimport { kilometer, meter } from \"measurable/dimensions\";\n\nconst a = new Quantity(1, kilometer);\nconst b = new Quantity(500, meter);\n\nQuantity.min(a, b); // Quantity(500, meter) — the smaller\nQuantity.max(a, b); // Quantity(1, kilometer) — the larger\nQuantity.sum(a, b); // Quantity(1.5, kilometer) — total, in a's unit\nb.clamp(a, new Quantity(2, kilometer)); // b bounded to [a, 2 km], in b's unit\n```\n\n## Defining your own units\n\nCreate a `Dimension` and add units through its builder methods. `scale` is how\nmany base units make up one of the unit being defined.\n\n```ts\nimport { Dimension, Quantity } from \"measurable\";\n\nconst data = new Dimension(\"data\");\nconst byte = data.base(\"byte\", [\"B\", \"bytes\"]); // the base unit (identity)\nconst kilobyte = data.unit(\"kilobyte\", 1024, [\"KB\"]);\nconst megabyte = data.unit(\"megabyte\", 1024 ** 2, [\"MB\"]);\n\nnew Quantity(2, megabyte).in(kilobyte); // 2048\n```\n\n### Affine units (offset, not just scale)\n\n```ts\nconst temperature = new Dimension(\"temperature\");\nconst kelvin = temperature.base(\"kelvin\", [\"K\"]);\n// value_in_base = value * scale + offset\nconst celsius = temperature.affine(\"celsius\", { scale: 1, offset: 273.15 }, [\"C\"]);\n```\n\n### Fully custom transforms\n\nFor anything non-linear, provide an explicit inverse pair:\n\n```ts\nconst dim = new Dimension(\"custom\");\ndim.base(\"base\");\ndim.custom(\"squared\", {\n  toBase: (x) => x * x,\n  fromBase: (x) => Math.sqrt(x),\n});\n```\n\n### Generating SI prefixes\n\n`definePrefixed` adds the metric prefix ladder to a reference unit and returns the\ncreated units keyed by name (skipping any name that already exists). Pass\n`SI_SUBMULTIPLE_PREFIXES` to generate fractions only.\n\n```ts\nimport { Dimension, Quantity, definePrefixed } from \"measurable\";\n\nconst data = new Dimension(\"data\");\nconst bit = data.base(\"bit\", [\"b\"]);\nconst prefixed = definePrefixed(data, { name: \"bit\", symbol: \"b\", scale: 1 });\n\nnew Quantity(1, prefixed.kilobit).in(bit); // 1000  (SI kilo = 1e3)\n```\n\n### Tagging units into a measurement system\n\n```ts\nimport { MeasurementSystem } from \"measurable\";\n\nconst si = new MeasurementSystem(\"si\").add(byte, kilobyte, megabyte);\nsi.has(kilobyte); // true\n```\n\n## API reference\n\n### `Dimension`\n\n- `new Dimension(name)`\n- `.base(name, aliases?)` — define the canonical base unit\n- `.unit(name, scale, aliases?)` — linear unit (`scale` base units per unit)\n- `.affine(name, { scale, offset }, aliases?)` — linear with additive offset\n- `.custom(name, { toBase, fromBase }, aliases?)` — arbitrary inverse pair\n- `.convert(value, from, to)` — convert a raw number between two of its units\n- `.get(token)` — units matching a name/alias (`Unit[] | undefined`)\n- `.has(unit)`, `.units`, `.baseUnit`\n\n### `Unit`\n\nA passive handle, normally created via a dimension's builder methods rather than\n`new Unit` directly. Read-only properties:\n\n- `.name` — the unit's canonical name\n- `.dimension` — the `Dimension` it belongs to\n- `.toBase(value)` → `number` — convert a value in this unit to base units\n- `.fromBase(value)` → `number` — convert a value in base units to this unit\n\n### `Quantity`\n\n- `new Quantity(magnitude, unit)`\n- `.to(target)` → `Quantity`\n- `.in(target)` → `number`\n- `.toString()` → `string` — e.g. `\"5 kilometer\"`\n- `.plus(other)` / `.minus(other)` → `Quantity` — add/subtract another quantity (aliases: `add` / `sub`)\n- `.times(factor)` / `.dividedBy(divisor)` → `Quantity` — scale by a number (aliases: `mul` / `div`)\n- `.ratioTo(other)` → `number` — dimensionless ratio (how many of `other` fit in this)\n- `.negate()` / `.abs()` → `Quantity`\n- `.clamp(lower, upper)` → `Quantity` — bound to a range, in this unit\n- `.round(decimals?)` → `Quantity` — round the magnitude (default 0 decimals)\n- `.equals(other)` / `.notEquals(other)` → `boolean` (aliases: `eq` / `ne`)\n- `.lessThan(other)` / `.greaterThan(other)` → `boolean` (aliases: `lt` / `gt`)\n- `.lessThanOrEqual(other)` / `.greaterThanOrEqual(other)` → `boolean` (aliases: `lte` / `gte`)\n- `.compareTo(other)` → `-1 | 0 | 1` — sort comparator\n- `.isZero()` / `.isPositive()` / `.isNegative()` → `boolean`\n- `Quantity.min(...quantities)` / `Quantity.max(...quantities)` / `Quantity.sum(...quantities)` → `Quantity`\n- `Quantity.parse(input, dimension, { prefer? })` → `Quantity`\n\n### `MeasurementSystem`\n\n- `new MeasurementSystem(name)`\n- `.add(...units)`, `.has(unit)`\n- `.in(dimension)` → `Unit[]`\n- `.express(quantity)` → `Quantity`\n\n### Errors\n\n- `InvalidConversionError` — units are from different dimensions\n- `UnknownUnitError` — a parsed token matches no unit\n- `AmbiguousUnitError` — a parsed token matches several units and no `prefer` was given\n\n## License\n\nISC\n"
 }