@danielsimonjr/mathts-core 0.1.2 → 0.1.3

package/dist/index.js

@@ -757,10 +757,7 @@ var Fraction = class _Fraction {
    */
   multiply(other) {
     if (other instanceof _Fraction) {
-      return new _Fraction(
-        this.numerator * other.numerator,
-        this.denominator * other.denominator
-      );
+      return new _Fraction(this.numerator * other.numerator, this.denominator * other.denominator);
     }
     return this.multiply(_Fraction.fromNumber(Number(other.valueOf())));
   }
@@ -772,10 +769,7 @@ var Fraction = class _Fraction {
       if (other.numerator === 0n) {
         throw new Error("Division by zero");
       }
-      return new _Fraction(
-        this.numerator * other.denominator,
-        this.denominator * other.numerator
-      );
+      return new _Fraction(this.numerator * other.denominator, this.denominator * other.numerator);
     }
     return this.divide(_Fraction.fromNumber(Number(other.valueOf())));
   }
@@ -789,10 +783,7 @@ var Fraction = class _Fraction {
    * Absolute value: |a/b|
    */
   abs() {
-    return new _Fraction(
-      this.numerator < 0n ? -this.numerator : this.numerator,
-      this.denominator
-    );
+    return new _Fraction(this.numerator < 0n ? -this.numerator : this.numerator, this.denominator);
   }
   /**
    * Reciprocal: b/a
@@ -1019,10 +1010,7 @@ var Fraction = class _Fraction {
    * Used in Stern-Brocot tree and Farey sequences
    */
   mediant(other) {
-    return new _Fraction(
-      this.numerator + other.numerator,
-      this.denominator + other.denominator
-    );
+    return new _Fraction(this.numerator + other.numerator, this.denominator + other.denominator);
   }
 };
 var FRACTION_ZERO = new Fraction(0n, 1n);
@@ -1045,6 +1033,12 @@ var defaultConfig = {
 var globalConfig = { ...defaultConfig };
 var BigNumber = class _BigNumber {
   type = "BigNumber";
+  /**
+   * Duck-typing marker for Decimal.js / mathjs formatter compatibility.
+   * Allows external code that checks `obj.isBigNumber === true` to identify
+   * this class without an `instanceof` check.
+   */
+  isBigNumber = true;
   // Internal representation: sign * coefficient * 10^exponent
   _sign;
   _coefficient;
@@ -1218,6 +1212,14 @@ var BigNumber = class _BigNumber {
     const str = this.toString();
     return parseFloat(str);
   }
+  /**
+   * Convert to a JS number.
+   * Alias for `valueOf()` — provided for Decimal.js / mathjs formatter
+   * duck-typing compatibility.
+   */
+  toNumber() {
+    return this.valueOf();
+  }
   toString() {
     if (this._isNaN) return "NaN";
     if (this._isInfinite) return this._sign === 1 ? "Infinity" : "-Infinity";
@@ -1240,35 +1242,55 @@ var BigNumber = class _BigNumber {
     };
   }
   /**
-   * Convert to fixed-point notation
+   * Convert to fixed-point notation.
+   *
+   * When called with no argument (or `undefined`) returns the full fixed-point
+   * string representation without rounding — matching Decimal.js semantics where
+   * `toFixed()` is equivalent to a lossless fixed-point stringify.
+   * When called with a non-negative integer `decimalPlaces`, rounds and formats
+   * to exactly that many digits after the decimal point.
    */
-  toFixed(decimalPlaces = 0) {
+  toFixed(decimalPlaces) {
+    if (decimalPlaces === void 0) {
+      return this.toFixedInternal(void 0);
+    }
     return this.round(decimalPlaces).toFixedInternal(decimalPlaces);
   }
   toFixedInternal(decimalPlaces) {
     if (this._isNaN) return "NaN";
     if (this._isInfinite) return this._sign === 1 ? "Infinity" : "-Infinity";
-    if (this._sign === 0) return decimalPlaces > 0 ? "0." + "0".repeat(decimalPlaces) : "0";
+    const dp = decimalPlaces ?? -1;
+    const allDigits = dp < 0;
+    if (this._sign === 0) return allDigits ? "0" : dp > 0 ? "0." + "0".repeat(dp) : "0";
     const sign = this._sign === -1 ? "-" : "";
     const digits = this._coefficient.toString();
     if (this._exponent >= 0) {
       const intPart = digits + "0".repeat(this._exponent);
-      return sign + intPart + (decimalPlaces > 0 ? "." + "0".repeat(decimalPlaces) : "");
+      if (allDigits) return sign + intPart;
+      return sign + intPart + (dp > 0 ? "." + "0".repeat(dp) : "");
     } else if (-this._exponent <= digits.length) {
       const insertPos = digits.length + this._exponent;
       const intPart = digits.slice(0, insertPos) || "0";
-      let decPart = digits.slice(insertPos);
-      if (decPart.length < decimalPlaces) {
-        decPart += "0".repeat(decimalPlaces - decPart.length);
+      const decPart = digits.slice(insertPos);
+      if (allDigits) {
+        return sign + intPart + (decPart.length > 0 ? "." + decPart : "");
       }
-      return sign + intPart + (decimalPlaces > 0 ? "." + decPart.slice(0, decimalPlaces) : "");
+      let paddedDec = decPart;
+      if (paddedDec.length < dp) {
+        paddedDec += "0".repeat(dp - paddedDec.length);
+      }
+      return sign + intPart + (dp > 0 ? "." + paddedDec.slice(0, dp) : "");
     } else {
       const leadingZeros = -this._exponent - digits.length;
-      let decPart = "0".repeat(leadingZeros) + digits;
-      if (decPart.length < decimalPlaces) {
-        decPart += "0".repeat(decimalPlaces - decPart.length);
+      const decPart = "0".repeat(leadingZeros) + digits;
+      if (allDigits) {
+        return sign + "0." + decPart;
+      }
+      let paddedDec = decPart;
+      if (paddedDec.length < dp) {
+        paddedDec += "0".repeat(dp - paddedDec.length);
       }
-      return sign + "0" + (decimalPlaces > 0 ? "." + decPart.slice(0, decimalPlaces) : "");
+      return sign + "0" + (dp > 0 ? "." + paddedDec.slice(0, dp) : "");
     }
   }
   /**
@@ -1373,6 +1395,12 @@ var BigNumber = class _BigNumber {
     const b = this.ensureBigNumber(other);
     return this.add(b.negate());
   }
+  /**
+   * Alias for subtract — mathjs / Decimal.js compatibility.
+   */
+  sub(other) {
+    return this.subtract(other);
+  }
   /**
    * Multiplication
    */
@@ -1390,6 +1418,12 @@ var BigNumber = class _BigNumber {
     const exponent = this._exponent + b._exponent;
     return this.normalize(sign, coefficient, exponent);
   }
+  /**
+   * Alias for multiply — mathjs / Decimal.js compatibility.
+   */
+  mul(other) {
+    return this.multiply(other);
+  }
   /**
    * Division
    */
@@ -1501,6 +1535,14 @@ var BigNumber = class _BigNumber {
   compare(other) {
     return this.compareTo(other);
   }
+  /**
+   * Returns true iff this > other.
+   * Accepts the same argument types as `add`/`multiply` (BigNumber, number, or string).
+   * Named `gt` for Decimal.js / mathjs formatter compatibility.
+   */
+  gt(other) {
+    return this.greaterThan(this.ensureBigNumber(other));
+  }
   // ============================================================
   // Rounding Methods
   // ============================================================
@@ -1579,6 +1621,36 @@ var BigNumber = class _BigNumber {
   trunc() {
     return this.round(0, "down");
   }
+  /**
+   * Round to `n` significant decimal digits and return a new BigNumber.
+   * Delegates to `roundToPrecision`, using the global rounding mode unless
+   * an explicit `roundingMode` is supplied.
+   *
+   * Named `toSignificantDigits` for Decimal.js / mathjs formatter compatibility.
+   * When `n` is undefined the value is returned unchanged (no rounding).
+   */
+  toSignificantDigits(n, roundingMode) {
+    if (n === void 0) return this.clone();
+    return this.roundToPrecision(n, roundingMode ?? globalConfig.rounding);
+  }
+  /**
+   * The decimal exponent of this number: `floor(log10(|x|))`.
+   *
+   * Matches Decimal.js semantics:
+   *   - `12345` → `4`   (5 digits → the most-significant place is 10^4)
+   *   - `0.0123` → `-2`  (first significant digit is at 10^-2)
+   *   - `100` → `2`
+   *   - `0.01` → `-2`
+   *   - `0` → `0`        (by convention; `isZero()` can be used to distinguish)
+   *
+   * For special values (NaN, ±Infinity) returns 0 — callers check
+   * `isFinite()` / `isNaN()` before using `.e`.
+   */
+  get e() {
+    if (this._isNaN || this._isInfinite || this._sign === 0) return 0;
+    const d = this._coefficient.toString().length;
+    return d - 1 + this._exponent;
+  }
   // ============================================================
   // Modular Arithmetic
   // ============================================================
@@ -1795,7 +1867,7 @@ var BigNumber = class _BigNumber {
     if (val > 0.5) {
       k = Math.ceil(Math.log2(val * 2));
     }
-    const divisor = _BigNumber.fromNumber(2 ** k);
+    const divisor = _BigNumber.fromNumber(2).pow(k);
     const reduced = this.divide(divisor);
     let sum = _BigNumber.fromNumber(1);
     let term = _BigNumber.fromNumber(1);
@@ -1883,9 +1955,7 @@ var BigNumber = class _BigNumber {
     for (let i = 0; i < 100; i++) {
       const guessSquared = guess.multiply(guess);
       const newGuess = guess.multiply(_BigNumber.fromNumber(2)).add(this.divide(guessSquared)).divide(three);
-      if (guess.subtract(newGuess).abs().compareTo(
-        guess.abs().multiply(_BigNumber.parse("1e-" + (precision + 5)))
-      ) <= 0) {
+      if (guess.subtract(newGuess).abs().compareTo(guess.abs().multiply(_BigNumber.parse("1e-" + (precision + 5)))) <= 0) {
         return newGuess.roundToPrecision(precision);
       }
       guess = newGuess;
@@ -1963,9 +2033,7 @@ var BigNumber = class _BigNumber {
     const xSquared = this.multiply(this);
     const maxIter = precision + 20;
     for (let n = 1; n <= maxIter; n++) {
-      term = term.multiply(xSquared).divide(
-        _BigNumber.fromNumber(2 * n * (2 * n + 1))
-      ).negate();
+      term = term.multiply(xSquared).divide(_BigNumber.fromNumber(2 * n * (2 * n + 1))).negate();
       const newSum = sum.add(term);
       if (sum.equals(newSum)) break;
       sum = newSum;
@@ -1980,9 +2048,7 @@ var BigNumber = class _BigNumber {
     const xSquared = this.multiply(this);
     const maxIter = precision + 20;
     for (let n = 1; n <= maxIter; n++) {
-      term = term.multiply(xSquared).divide(
-        _BigNumber.fromNumber((2 * n - 1) * (2 * n))
-      ).negate();
+      term = term.multiply(xSquared).divide(_BigNumber.fromNumber((2 * n - 1) * (2 * n))).negate();
       const newSum = sum.add(term);
       if (sum.equals(newSum)) break;
       sum = newSum;
@@ -2034,7 +2100,13 @@ var BigNumber = class _BigNumber {
     return this._sign;
   }
   clone() {
-    return new _BigNumber(this._sign, this._coefficient, this._exponent, this._isNaN, this._isInfinite);
+    return new _BigNumber(
+      this._sign,
+      this._coefficient,
+      this._exponent,
+      this._isNaN,
+      this._isInfinite
+    );
   }
   // ============================================================
   // Private Helper Methods
@@ -2072,8 +2144,683 @@ var BIGNUMBER_NEG_ONE = BigNumber.fromNumber(-1);
 var BIGNUMBER_TEN = BigNumber.fromNumber(10);
 var BIGNUMBER_PI = BigNumber.parse("3.14159265358979323846264338327950288419716939937510");
 var BIGNUMBER_E = BigNumber.parse("2.71828182845904523536028747135266249775724709369995");
-var BIGNUMBER_LN2 = BigNumber.parse("0.69314718055994530941723212145817656807550013436026");
-var BIGNUMBER_LN10 = BigNumber.parse("2.30258509299404568401799145468436420760110148862877");
+var BIGNUMBER_LN2 = BigNumber.parse(
+  "0.69314718055994530941723212145817656807550013436026"
+);
+var BIGNUMBER_LN10 = BigNumber.parse(
+  "2.30258509299404568401799145468436420760110148862877"
+);
+
+// src/types/unit-definitions.ts
+var DIMENSIONLESS = Object.freeze({
+  length: 0,
+  mass: 0,
+  time: 0,
+  current: 0,
+  temperature: 0,
+  amount: 0,
+  luminosity: 0
+});
+function dim(partial) {
+  return {
+    length: partial.length ?? 0,
+    mass: partial.mass ?? 0,
+    time: partial.time ?? 0,
+    current: partial.current ?? 0,
+    temperature: partial.temperature ?? 0,
+    amount: partial.amount ?? 0,
+    luminosity: partial.luminosity ?? 0
+  };
+}
+var BASE_UNITS = {
+  m: { multiplier: 1, dimensions: dim({ length: 1 }), prefixable: true },
+  // The base unit of mass is *kilogram*, but the prefix-able symbol is "g".
+  // Internally we treat 1 kg as the canonical value, so "g" -> 0.001 kg.
+  kg: { multiplier: 1, dimensions: dim({ mass: 1 }) },
+  s: { multiplier: 1, dimensions: dim({ time: 1 }), prefixable: true },
+  A: { multiplier: 1, dimensions: dim({ current: 1 }), prefixable: true },
+  K: { multiplier: 1, dimensions: dim({ temperature: 1 }), prefixable: true },
+  mol: { multiplier: 1, dimensions: dim({ amount: 1 }), prefixable: true },
+  cd: { multiplier: 1, dimensions: dim({ luminosity: 1 }), prefixable: true }
+};
+var DERIVED_UNITS = {
+  // --- Length ---------------------------------------------------------------
+  // Note: 'm' is a base unit (above), already prefixable.
+  ft: { multiplier: 0.3048, dimensions: dim({ length: 1 }) },
+  foot: { multiplier: 0.3048, dimensions: dim({ length: 1 }) },
+  in: { multiplier: 0.0254, dimensions: dim({ length: 1 }) },
+  inch: { multiplier: 0.0254, dimensions: dim({ length: 1 }) },
+  yd: { multiplier: 0.9144, dimensions: dim({ length: 1 }) },
+  yard: { multiplier: 0.9144, dimensions: dim({ length: 1 }) },
+  mi: { multiplier: 1609.344, dimensions: dim({ length: 1 }) },
+  mile: { multiplier: 1609.344, dimensions: dim({ length: 1 }) },
+  // --- Mass -----------------------------------------------------------------
+  // The "g" entry is gram (0.001 kg). It is prefixable, so kg/mg/µg work via
+  // prefix application on this entry rather than the base "kg".
+  g: { multiplier: 1e-3, dimensions: dim({ mass: 1 }), prefixable: true },
+  lb: { multiplier: 0.45359237, dimensions: dim({ mass: 1 }) },
+  lbm: { multiplier: 0.45359237, dimensions: dim({ mass: 1 }) },
+  oz: { multiplier: 0.028349523125, dimensions: dim({ mass: 1 }) },
+  ton: { multiplier: 907.18474, dimensions: dim({ mass: 1 }) },
+  // US short ton
+  tonne: { multiplier: 1e3, dimensions: dim({ mass: 1 }) },
+  // metric ton
+  // --- Time -----------------------------------------------------------------
+  min: { multiplier: 60, dimensions: dim({ time: 1 }) },
+  h: { multiplier: 3600, dimensions: dim({ time: 1 }) },
+  hr: { multiplier: 3600, dimensions: dim({ time: 1 }) },
+  day: { multiplier: 86400, dimensions: dim({ time: 1 }) },
+  week: { multiplier: 604800, dimensions: dim({ time: 1 }) },
+  year: { multiplier: 31557600, dimensions: dim({ time: 1 }) },
+  // Julian year
+  // --- Temperature ----------------------------------------------------------
+  // K is the base.
+  // °C → K is offset by 273.15 (no multiplicative factor change).
+  // °F → K is more complex (offset & scale).
+  degC: { multiplier: 1, offset: 273.15, dimensions: dim({ temperature: 1 }) },
+  degF: { multiplier: 5 / 9, offset: 459.67 * (5 / 9), dimensions: dim({ temperature: 1 }) },
+  degR: { multiplier: 5 / 9, dimensions: dim({ temperature: 1 }) },
+  // Rankine
+  // --- Plane angle (dimensionless, but often treated as units) --------------
+  rad: { multiplier: 1, dimensions: dim({}), prefixable: true },
+  deg: { multiplier: Math.PI / 180, dimensions: dim({}) },
+  grad: { multiplier: Math.PI / 200, dimensions: dim({}) },
+  // --- Force ----------------------------------------------------------------
+  // N = kg·m·s^-2 = 1 kg·m·s^-2; in our base-units representation that's
+  // value=1, dim {length: 1, mass: 1, time: -2}.
+  N: { multiplier: 1, dimensions: dim({ length: 1, mass: 1, time: -2 }), prefixable: true },
+  dyn: { multiplier: 1e-5, dimensions: dim({ length: 1, mass: 1, time: -2 }) },
+  lbf: { multiplier: 4.4482216152605, dimensions: dim({ length: 1, mass: 1, time: -2 }) },
+  // --- Energy ---------------------------------------------------------------
+  J: { multiplier: 1, dimensions: dim({ length: 2, mass: 1, time: -2 }), prefixable: true },
+  erg: { multiplier: 1e-7, dimensions: dim({ length: 2, mass: 1, time: -2 }) },
+  cal: { multiplier: 4.184, dimensions: dim({ length: 2, mass: 1, time: -2 }) },
+  eV: {
+    multiplier: 1602176634e-28,
+    dimensions: dim({ length: 2, mass: 1, time: -2 }),
+    prefixable: true
+  },
+  BTU: { multiplier: 1055.05585262, dimensions: dim({ length: 2, mass: 1, time: -2 }) },
+  // --- Power ----------------------------------------------------------------
+  W: { multiplier: 1, dimensions: dim({ length: 2, mass: 1, time: -3 }), prefixable: true },
+  hp: { multiplier: 745.6998715822702, dimensions: dim({ length: 2, mass: 1, time: -3 }) },
+  // --- Pressure -------------------------------------------------------------
+  Pa: { multiplier: 1, dimensions: dim({ length: -1, mass: 1, time: -2 }), prefixable: true },
+  bar: { multiplier: 1e5, dimensions: dim({ length: -1, mass: 1, time: -2 }), prefixable: true },
+  atm: { multiplier: 101325, dimensions: dim({ length: -1, mass: 1, time: -2 }) },
+  psi: { multiplier: 6894.757293168361, dimensions: dim({ length: -1, mass: 1, time: -2 }) },
+  torr: { multiplier: 133.322368421, dimensions: dim({ length: -1, mass: 1, time: -2 }) },
+  mmHg: { multiplier: 133.322387415, dimensions: dim({ length: -1, mass: 1, time: -2 }) },
+  // --- Electric -------------------------------------------------------------
+  C: {
+    multiplier: 1,
+    dimensions: dim({ time: 1, current: 1 }),
+    prefixable: true
+  },
+  V: {
+    multiplier: 1,
+    dimensions: dim({ length: 2, mass: 1, time: -3, current: -1 }),
+    prefixable: true
+  },
+  ohm: {
+    multiplier: 1,
+    dimensions: dim({ length: 2, mass: 1, time: -3, current: -2 }),
+    prefixable: true
+  },
+  \u03A9: {
+    multiplier: 1,
+    dimensions: dim({ length: 2, mass: 1, time: -3, current: -2 }),
+    prefixable: true
+  },
+  F: {
+    multiplier: 1,
+    dimensions: dim({ length: -2, mass: -1, time: 4, current: 2 }),
+    prefixable: true
+  },
+  H: {
+    multiplier: 1,
+    dimensions: dim({ length: 2, mass: 1, time: -2, current: -2 }),
+    prefixable: true
+  },
+  // --- Frequency ------------------------------------------------------------
+  Hz: { multiplier: 1, dimensions: dim({ time: -1 }), prefixable: true },
+  // --- Volume ---------------------------------------------------------------
+  L: { multiplier: 1e-3, dimensions: dim({ length: 3 }), prefixable: true },
+  l: { multiplier: 1e-3, dimensions: dim({ length: 3 }), prefixable: true },
+  gal: { multiplier: 0.003785411784, dimensions: dim({ length: 3 }) },
+  // US gallon
+  // --- Area -----------------------------------------------------------------
+  ha: { multiplier: 1e4, dimensions: dim({ length: 2 }) },
+  // hectare
+  acre: { multiplier: 4046.8564224, dimensions: dim({ length: 2 }) }
+};
+var ALL_UNITS = { ...BASE_UNITS, ...DERIVED_UNITS };
+var UNIT_ALIASES = {
+  "\xB0C": "degC",
+  "\xB0F": "degF",
+  "\xB0R": "degR",
+  "\xB0": "deg"
+  // The Unicode micro sign is handled in prefixes; °K is non-standard.
+};
+function getUnitDef(name) {
+  return ALL_UNITS[name];
+}
+
+// src/types/unit-prefixes.ts
+var SI_PREFIXES = {
+  // Positive powers of ten
+  Y: 1e24,
+  // yotta
+  Z: 1e21,
+  // zetta
+  E: 1e18,
+  // exa
+  P: 1e15,
+  // peta
+  T: 1e12,
+  // tera
+  G: 1e9,
+  // giga
+  M: 1e6,
+  // mega
+  k: 1e3,
+  // kilo
+  h: 100,
+  // hecto
+  da: 10,
+  // deka (two-letter)
+  // Negative powers of ten
+  d: 0.1,
+  // deci
+  c: 0.01,
+  // centi
+  m: 1e-3,
+  // milli
+  u: 1e-6,
+  // micro (ASCII fallback)
+  \u00B5: 1e-6,
+  // micro (Unicode)
+  n: 1e-9,
+  // nano
+  p: 1e-12,
+  // pico
+  f: 1e-15,
+  // femto
+  a: 1e-18,
+  // atto
+  z: 1e-21,
+  // zepto
+  y: 1e-24
+  // yocto
+};
+var SI_PREFIX_KEYS = Object.keys(SI_PREFIXES).sort(
+  (a, b) => b.length - a.length
+);
+var BEST_PREFIXES = [
+  "Y",
+  "Z",
+  "E",
+  "P",
+  "T",
+  "G",
+  "M",
+  "k",
+  "",
+  "m",
+  "u",
+  "n",
+  "p",
+  "f",
+  "a",
+  "z",
+  "y"
+];
+function getPrefix(name) {
+  return SI_PREFIXES[name];
+}
+
+// src/types/unit.ts
+var DimensionMismatchError = class extends Error {
+  constructor(left, right, op) {
+    super(
+      `Dimension mismatch in ${op}: ${formatDimensions(left)} vs ${formatDimensions(right)}`
+    );
+    this.left = left;
+    this.right = right;
+  }
+  left;
+  right;
+  name = "DimensionMismatchError";
+};
+var UnitParseError = class extends Error {
+  name = "UnitParseError";
+  constructor(notation, reason) {
+    super(`Cannot parse unit notation "${notation}": ${reason}`);
+  }
+};
+var DIM_KEYS = [
+  "length",
+  "mass",
+  "time",
+  "current",
+  "temperature",
+  "amount",
+  "luminosity"
+];
+function dimsEqual(a, b) {
+  for (const k of DIM_KEYS) {
+    if (a[k] !== b[k]) return false;
+  }
+  return true;
+}
+function dimsAdd(a, b) {
+  return {
+    length: a.length + b.length,
+    mass: a.mass + b.mass,
+    time: a.time + b.time,
+    current: a.current + b.current,
+    temperature: a.temperature + b.temperature,
+    amount: a.amount + b.amount,
+    luminosity: a.luminosity + b.luminosity
+  };
+}
+function dimsSub(a, b) {
+  return {
+    length: a.length - b.length,
+    mass: a.mass - b.mass,
+    time: a.time - b.time,
+    current: a.current - b.current,
+    temperature: a.temperature - b.temperature,
+    amount: a.amount - b.amount,
+    luminosity: a.luminosity - b.luminosity
+  };
+}
+function dimsScale(a, n) {
+  return {
+    length: a.length * n,
+    mass: a.mass * n,
+    time: a.time * n,
+    current: a.current * n,
+    temperature: a.temperature * n,
+    amount: a.amount * n,
+    luminosity: a.luminosity * n
+  };
+}
+function isDimensionless(d) {
+  return dimsEqual(d, DIMENSIONLESS);
+}
+function formatDimensions(d) {
+  const parts = [];
+  for (const k of DIM_KEYS) {
+    const e = d[k];
+    if (e !== 0) parts.push(`${k}^${e}`);
+  }
+  return parts.length === 0 ? "dimensionless" : parts.join("\xB7");
+}
+function resolveAtom(token) {
+  const aliased = UNIT_ALIASES[token] ?? token;
+  const direct = getUnitDef(aliased);
+  if (direct) {
+    return {
+      multiplier: direct.multiplier,
+      offset: direct.offset ?? 0,
+      dimensions: direct.dimensions,
+      prefix: "",
+      base: aliased
+    };
+  }
+  for (const prefix of SI_PREFIX_KEYS) {
+    if (!aliased.startsWith(prefix) || aliased.length === prefix.length) continue;
+    const rest = aliased.slice(prefix.length);
+    const baseDef = getUnitDef(rest);
+    if (!baseDef) continue;
+    if (!baseDef.prefixable) continue;
+    return {
+      multiplier: baseDef.multiplier * SI_PREFIXES[prefix],
+      // Offset is in base units, so prefix the multiplier but not the offset
+      // (we never apply prefixes to temperature units in practice anyway).
+      offset: baseDef.offset ?? 0,
+      dimensions: baseDef.dimensions,
+      prefix,
+      base: rest
+    };
+  }
+  throw new UnitParseError(token, `unknown unit "${token}"`);
+}
+function splitScalar(input) {
+  const m = input.match(/^\s*([+-]?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?)\s+(.*)$/);
+  if (m) {
+    return { scalar: parseFloat(m[1]), rest: m[2].trim() };
+  }
+  const scalarOnly = input.match(/^\s*([+-]?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?)\s*$/);
+  if (scalarOnly) {
+    return { scalar: parseFloat(scalarOnly[1]), rest: "" };
+  }
+  return { scalar: 1, rest: input.trim() };
+}
+function parseUnitExpr(expr) {
+  if (expr === "" || expr === "1") return [];
+  const normalized = expr.replace(/[·⋅]/g, "*");
+  const atoms = [];
+  let pos = 0;
+  let nextSign = 1;
+  while (pos < normalized.length) {
+    while (pos < normalized.length && /\s/.test(normalized[pos])) pos++;
+    if (pos >= normalized.length) break;
+    const ch = normalized[pos];
+    if (ch === "*") {
+      pos++;
+      continue;
+    }
+    if (ch === "/") {
+      nextSign = -1;
+      pos++;
+      continue;
+    }
+    if (ch === "1") {
+      const next = normalized[pos + 1];
+      if (next === void 0 || next === " " || next === "/" || next === "*") {
+        pos++;
+        continue;
+      }
+    }
+    if (!/[A-Za-z°µΩ]/.test(ch)) {
+      throw new UnitParseError(expr, `unexpected character "${ch}" at position ${pos}`);
+    }
+    const idStart = pos;
+    while (pos < normalized.length && /[A-Za-z°µΩ]/.test(normalized[pos])) pos++;
+    const identifier = normalized.slice(idStart, pos);
+    let exponent = 1;
+    if (pos < normalized.length && normalized[pos] === "^") {
+      pos++;
+      const expMatch = normalized.slice(pos).match(/^([+-]?\d+(?:\.\d+)?)/);
+      if (!expMatch) {
+        throw new UnitParseError(expr, `expected exponent after "^" at position ${pos}`);
+      }
+      exponent = parseFloat(expMatch[1]);
+      pos += expMatch[1].length;
+    } else {
+      const supMatch = normalized.slice(pos).match(/^([²³⁴⁵⁶⁷⁸⁹⁰¹]+)/);
+      if (supMatch) {
+        exponent = parseSuperscript(supMatch[1]);
+        pos += supMatch[1].length;
+      }
+    }
+    const resolved = resolveAtom(identifier);
+    atoms.push({
+      multiplier: resolved.multiplier,
+      offset: resolved.offset,
+      dimensions: resolved.dimensions,
+      exponent: nextSign * exponent,
+      source: identifier
+    });
+    nextSign = 1;
+  }
+  return atoms;
+}
+var SUPERSCRIPT_MAP = {
+  "\u2070": "0",
+  "\xB9": "1",
+  "\xB2": "2",
+  "\xB3": "3",
+  "\u2074": "4",
+  "\u2075": "5",
+  "\u2076": "6",
+  "\u2077": "7",
+  "\u2078": "8",
+  "\u2079": "9"
+};
+function parseSuperscript(s) {
+  let out = "";
+  for (const ch of s) out += SUPERSCRIPT_MAP[ch] ?? ch;
+  return parseInt(out, 10);
+}
+function parse(input) {
+  const { scalar, rest } = splitScalar(input);
+  return { scalar, atoms: parseUnitExpr(rest) };
+}
+var Unit = class _Unit {
+  /** Discriminator (matches the prototype-flag convention). */
+  type = "Unit";
+  /** Used by `isUnit()` and typed-function dispatch. */
+  isUnit = true;
+  /** Numeric magnitude in **SI base units**. */
+  value;
+  /** Dimensional signature. */
+  dimensions;
+  /** Original notation string, preserved for `toString()` round-trip. */
+  notation;
+  constructor(value, notationOrDims, notation) {
+    if (typeof notationOrDims === "string") {
+      const parsed = parse(notationOrDims);
+      const composed = composeAtoms(parsed.atoms);
+      const inputValue = parsed.scalar * value;
+      let canonical;
+      if (parsed.atoms.length === 1 && parsed.atoms[0].exponent === 1) {
+        const a = parsed.atoms[0];
+        canonical = inputValue * a.multiplier + a.offset;
+      } else {
+        canonical = inputValue * composed.multiplier;
+      }
+      this.value = canonical;
+      this.dimensions = composed.dimensions;
+      this.notation = notationOrDims;
+    } else {
+      this.value = value;
+      this.dimensions = notationOrDims;
+      this.notation = notation ?? "";
+    }
+  }
+  // -------------------------------------------------------------------------
+  // Arithmetic
+  // -------------------------------------------------------------------------
+  /**
+   * Add two units. Requires identical dimensions.
+   *
+   * @throws {DimensionMismatchError} if dimensions differ.
+   */
+  add(other) {
+    if (!dimsEqual(this.dimensions, other.dimensions)) {
+      throw new DimensionMismatchError(this.dimensions, other.dimensions, "add");
+    }
+    return new _Unit(this.value + other.value, this.dimensions, this.notation);
+  }
+  /**
+   * Subtract two units. Requires identical dimensions.
+   *
+   * @throws {DimensionMismatchError} if dimensions differ.
+   */
+  sub(other) {
+    if (!dimsEqual(this.dimensions, other.dimensions)) {
+      throw new DimensionMismatchError(this.dimensions, other.dimensions, "sub");
+    }
+    return new _Unit(this.value - other.value, this.dimensions, this.notation);
+  }
+  /**
+   * Multiply by another unit or a scalar. Dimensions add when multiplying by
+   * another unit; unchanged when multiplying by a scalar.
+   */
+  mul(other) {
+    if (typeof other === "number") {
+      return new _Unit(this.value * other, this.dimensions, this.notation);
+    }
+    return new _Unit(
+      this.value * other.value,
+      dimsAdd(this.dimensions, other.dimensions),
+      composeNotation(this.notation, other.notation, "*")
+    );
+  }
+  /**
+   * Divide by another unit or a scalar. Dimensions subtract when dividing by
+   * another unit; unchanged when dividing by a scalar.
+   */
+  div(other) {
+    if (typeof other === "number") {
+      return new _Unit(this.value / other, this.dimensions, this.notation);
+    }
+    return new _Unit(
+      this.value / other.value,
+      dimsSub(this.dimensions, other.dimensions),
+      composeNotation(this.notation, other.notation, "/")
+    );
+  }
+  /**
+   * Raise to an integer or rational power. Dimensions scale by `n`.
+   */
+  pow(n) {
+    return new _Unit(
+      this.value ** n,
+      dimsScale(this.dimensions, n),
+      this.notation ? `(${this.notation})^${n}` : ""
+    );
+  }
+  // -------------------------------------------------------------------------
+  // Conversion
+  // -------------------------------------------------------------------------
+  /**
+   * Convert to a target unit. Dimensions must match.
+   *
+   * @throws {DimensionMismatchError} if `targetNotation`'s dimensions differ
+   *   from this unit's.
+   */
+  to(targetNotation) {
+    const parsed = parse(targetNotation);
+    const composed = composeAtoms(parsed.atoms);
+    if (!dimsEqual(this.dimensions, composed.dimensions)) {
+      throw new DimensionMismatchError(
+        this.dimensions,
+        composed.dimensions,
+        `to("${targetNotation}")`
+      );
+    }
+    return new _Unit(this.value, composed.dimensions, targetNotation);
+  }
+  /**
+   * Pick a unit (with SI prefix) that gives a magnitude closest to 1.
+   *
+   * Searches the unit registry for entries matching this unit's dimensions,
+   * then applies each SI prefix in {@link BEST_PREFIXES} to find the
+   * representation minimising `|log10(displayed value)|`.
+   *
+   * If no registered unit matches the dimensions, falls back to a synthetic
+   * notation describing the dimensional vector.
+   */
+  toBest() {
+    if (isDimensionless(this.dimensions)) {
+      return new _Unit(this.value, this.dimensions, "");
+    }
+    let bestNotation;
+    let bestScore = Infinity;
+    for (const [name, def] of Object.entries(ALL_UNITS)) {
+      if (name === "kg") continue;
+      if (!dimsEqual(def.dimensions, this.dimensions)) continue;
+      if (def.offset !== void 0) continue;
+      const candidatePrefixes = def.prefixable ? BEST_PREFIXES : [""];
+      for (const prefix of candidatePrefixes) {
+        const factor = prefix === "" ? def.multiplier : def.multiplier * SI_PREFIXES[prefix];
+        if (factor === 0) continue;
+        const displayed = this.value / factor;
+        if (displayed === 0) continue;
+        const score = Math.abs(Math.log10(Math.abs(displayed)));
+        if (score < bestScore) {
+          bestScore = score;
+          bestNotation = prefix + name;
+        }
+      }
+    }
+    if (bestNotation === void 0) {
+      return new _Unit(
+        this.value,
+        this.dimensions,
+        this.notation || formatDimensions(this.dimensions)
+      );
+    }
+    return new _Unit(this.value, this.dimensions, bestNotation);
+  }
+  // -------------------------------------------------------------------------
+  // Comparison
+  // -------------------------------------------------------------------------
+  /** True iff dimensions and canonical value are equal. */
+  equals(other) {
+    return dimsEqual(this.dimensions, other.dimensions) && this.value === other.value;
+  }
+  /** True iff dimensions match (values may differ). */
+  dimensionsEqual(other) {
+    return dimsEqual(this.dimensions, other.dimensions);
+  }
+  // -------------------------------------------------------------------------
+  // Formatting
+  // -------------------------------------------------------------------------
+  /**
+   * Pretty-print. If `notation` is set (the common case), display the value
+   * in that notation — otherwise emit a dimensional signature.
+   */
+  toString() {
+    if (this.notation === "") {
+      if (isDimensionless(this.dimensions)) return String(this.value);
+      return `${this.value} ${formatDimensions(this.dimensions)}`;
+    }
+    const displayed = displayedValue(this.value, this.notation);
+    return `${formatNumber(displayed)} ${this.notation}`;
+  }
+  /** JSON-serialisable record. */
+  toJSON() {
+    return { mathts: "Unit", value: this.value, notation: this.notation };
+  }
+  /**
+   * Rehydrate from a JSON record produced by {@link toJSON}.
+   *
+   * @throws {UnitParseError} if `json.notation` cannot be parsed.
+   */
+  static fromJSON(json) {
+    const parsed = parse(json.notation);
+    const composed = composeAtoms(parsed.atoms);
+    return new _Unit(json.value, composed.dimensions, json.notation);
+  }
+  /**
+   * Parse a full unit expression (with optional leading numeric coefficient).
+   *
+   * Example: `Unit.parse('5 km/h')`.
+   */
+  static parse(input) {
+    const { scalar, rest } = splitScalar(input);
+    return new _Unit(scalar, rest);
+  }
+};
+Unit.prototype.isUnit = true;
+function composeAtoms(atoms) {
+  let multiplier = 1;
+  let dimensions = { ...DIMENSIONLESS };
+  for (const a of atoms) {
+    multiplier *= a.multiplier ** a.exponent;
+    dimensions = dimsAdd(dimensions, dimsScale(a.dimensions, a.exponent));
+  }
+  return { multiplier, dimensions };
+}
+function displayedValue(canonical, notation) {
+  const parsed = parse(notation);
+  const composed = composeAtoms(parsed.atoms);
+  if (parsed.atoms.length === 1 && parsed.atoms[0].exponent === 1) {
+    const a = parsed.atoms[0];
+    return (canonical - a.offset) / a.multiplier;
+  }
+  return canonical / composed.multiplier;
+}
+function formatNumber(n) {
+  if (Number.isInteger(n)) return n.toString();
+  const rounded = Number(n.toPrecision(12));
+  return rounded.toString();
+}
+function composeNotation(a, b, op) {
+  if (a === "" && b === "") return "";
+  if (a === "") return op === "*" ? b : `1/${b}`;
+  if (b === "") return a;
+  const sep = op === "*" ? "*" : "/";
+  return `${a}${sep}${b}`;
+}
+function isUnit(value) {
+  return value instanceof Unit;
+}
 
 // src/typed/mathts-typed.ts
 import typed, { create } from "typed-function";
@@ -2115,7 +2862,14 @@ var isBigNumber2 = (x) => isBigNumber(x);
 var isMatrix = (x) => isObject(x) && "rows" in x && "cols" in x && "get" in x && typeof x.type === "string";
 var isDenseMatrix = (x) => isMatrix(x) && x.type === "DenseMatrix";
 var isSparseMatrix = (x) => isMatrix(x) && x.type === "SparseMatrix";
-var isUnit = (x) => isObject(x) && "value" in x && "unit" in x && typeof x.type === "string";
+var isUnit2 = (x) => {
+  if (!isObject(x)) return false;
+  const o = x;
+  if (typeof o.type !== "string") return false;
+  if (o.type === "Unit" && "value" in o && "dimensions" in o) return true;
+  if ("value" in o && "unit" in o) return true;
+  return false;
+};
 var MATHTS_TYPES = [
   // bigint is not built into typed-function
   { name: "bigint", test: isBigInt },
@@ -2135,7 +2889,7 @@ var MATHTS_TYPES = [
   { name: "SparseMatrix", test: isSparseMatrix },
   { name: "Matrix", test: isMatrix },
   // Other types
-  { name: "Unit", test: isUnit }
+  { name: "Unit", test: isUnit2 }
 ];
 var MATHTS_CONVERSIONS = [
   // -------------------------------------------------------------------------
@@ -2551,6 +3305,9 @@ var math = {
 // src/index.ts
 var VERSION = "0.1.0";
 export {
+  ALL_UNITS,
+  BASE_UNITS,
+  BEST_PREFIXES,
   BIGNUMBER_E,
   BIGNUMBER_LN10,
   BIGNUMBER_LN2,
@@ -2565,6 +3322,9 @@ export {
   COMPLEX_ZERO,
   Complex,
   DEFAULT_CONFIG,
+  DERIVED_UNITS,
+  DIMENSIONLESS,
+  DimensionMismatchError,
   FRACTION_HALF,
   FRACTION_NEG_ONE,
   FRACTION_ONE,
@@ -2576,12 +3336,19 @@ export {
   I,
   MATHTS_CONVERSIONS,
   MATHTS_TYPES,
+  SI_PREFIXES,
   TypeRegistry,
+  UNIT_ALIASES,
+  Unit,
+  UnitParseError,
   VERSION,
   create,
   createFactory,
   createMathTSTyped,
   createTypedFunction,
+  dim,
+  getPrefix,
+  getUnitDef,
   initTypedWasm,
   isArray,
   isBigInt,
@@ -2599,7 +3366,8 @@ export {
   isString,
   isTypedWasmAvailable,
   isUndefined,
-  isUnit,
+  isUnit2 as isUnit,
+  isUnit as isUnitValue,
   math,
   mathTyped,
   registerNativeTypes,