mathjs 14.5.3 → 14.7.0

package/lib/cjs/core/function/config.js

@@ -23,7 +23,6 @@ function configFactory(config, emit) {
    *
    * Examples:
    *
-   *
    *     import { create, all } from 'mathjs'
    *
    *     // create a mathjs instance

package/lib/cjs/entry/dependenciesAny/dependenciesToBest.generated.js

@@ -0,0 +1,17 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.toBestDependencies = void 0;
+var _dependenciesTypedGenerated = require("./dependenciesTyped.generated.js");
+var _factoriesAny = require("../../factoriesAny.js");
+/**
+ * THIS FILE IS AUTO-GENERATED
+ * DON'T MAKE CHANGES HERE
+ */
+
+const toBestDependencies = exports.toBestDependencies = {
+  typedDependencies: _dependenciesTypedGenerated.typedDependencies,
+  createToBest: _factoriesAny.createToBest
+};

package/lib/cjs/entry/dependenciesAny/dependenciesUnitClass.generated.js

@@ -19,6 +19,7 @@ var _dependenciesNumberGenerated = require("./dependenciesNumber.generated.js");
 var _dependenciesPowGenerated = require("./dependenciesPow.generated.js");
 var _dependenciesRoundGenerated = require("./dependenciesRound.generated.js");
 var _dependenciesSubtractScalarGenerated = require("./dependenciesSubtractScalar.generated.js");
+var _dependenciesToBestGenerated = require("./dependenciesToBest.generated.js");
 var _factoriesAny = require("../../factoriesAny.js");
 /**
  * THIS FILE IS AUTO-GENERATED
@@ -41,5 +42,6 @@ const UnitDependencies = exports.UnitDependencies = {
   powDependencies: _dependenciesPowGenerated.powDependencies,
   roundDependencies: _dependenciesRoundGenerated.roundDependencies,
   subtractScalarDependencies: _dependenciesSubtractScalarGenerated.subtractScalarDependencies,
+  toBestDependencies: _dependenciesToBestGenerated.toBestDependencies,
   createUnitClass: _factoriesAny.createUnitClass
 };

package/lib/cjs/entry/dependenciesAny.generated.js

@@ -2049,6 +2049,12 @@ Object.defineProperty(exports, "thomsonCrossSectionDependencies", {
     return _dependenciesThomsonCrossSectionGenerated.thomsonCrossSectionDependencies;
   }
 });
+Object.defineProperty(exports, "toBestDependencies", {
+  enumerable: true,
+  get: function () {
+    return _dependenciesToBestGenerated.toBestDependencies;
+  }
+});
 Object.defineProperty(exports, "toDependencies", {
   enumerable: true,
   get: function () {
@@ -2525,6 +2531,7 @@ var _dependenciesTanhGenerated = require("./dependenciesAny/dependenciesTanh.gen
 var _dependenciesTauGenerated = require("./dependenciesAny/dependenciesTau.generated.js");
 var _dependenciesThomsonCrossSectionGenerated = require("./dependenciesAny/dependenciesThomsonCrossSection.generated.js");
 var _dependenciesToGenerated = require("./dependenciesAny/dependenciesTo.generated.js");
+var _dependenciesToBestGenerated = require("./dependenciesAny/dependenciesToBest.generated.js");
 var _dependenciesTraceGenerated = require("./dependenciesAny/dependenciesTrace.generated.js");
 var _dependenciesTransposeGenerated = require("./dependenciesAny/dependenciesTranspose.generated.js");
 var _dependenciesTrueGenerated = require("./dependenciesAny/dependenciesTrue.generated.js");

package/lib/cjs/entry/impureFunctionsAny.generated.js

@@ -336,6 +336,7 @@ const help = exports.help = (0, _factoriesAny.createHelp)({
   string: _pureFunctionsAnyGenerated.string,
   subtractScalar: _pureFunctionsAnyGenerated.subtractScalar,
   tan: _pureFunctionsAnyGenerated.tan,
+  toBest: _pureFunctionsAnyGenerated.toBest,
   typeOf: _pureFunctionsAnyGenerated.typeOf,
   acosh: _pureFunctionsAnyGenerated.acosh,
   acsch: _pureFunctionsAnyGenerated.acsch,

package/lib/cjs/entry/pureFunctionsAny.generated.js

@@ -5,8 +5,8 @@ Object.defineProperty(exports, "__esModule", {
 });
 exports.dotPow = exports.dotMultiply = exports.dotDivide = exports.dot = exports.divideScalar = exports.divide = exports.distance = exports.diff = exports.diag = exports.deuteronMass = exports.det = exports.deepEqual = exports.cumsum = exports.cube = exports.ctranspose = exports.csch = exports.csc = exports.cross = exports.createUnit = exports.count = exports.coulombConstant = exports.coulomb = exports.coth = exports.cot = exports.cosh = exports.cos = exports.corr = exports.conj = exports.conductanceQuantum = exports.concat = exports.composition = exports.complex = exports.compareText = exports.compareNatural = exports.compare = exports.combinationsWithRep = exports.combinations = exports.column = exports.clone = exports.classicalElectronRadius = exports.ceil = exports.cbrt = exports.catalan = exports.boolean = exports.boltzmann = exports.bohrRadius = exports.bohrMagneton = exports.bitXor = exports.bitOr = exports.bitNot = exports.bitAnd = exports.bin = exports.bignumber = exports.bigint = exports.bellNumbers = exports.avogadro = exports.atomicMass = exports.atanh = exports.atan2 = exports.atan = exports.asinh = exports.asin = exports.asech = exports.asec = exports.arg = exports.apply = exports.and = exports.addScalar = exports.add = exports.acsch = exports.acsc = exports.acoth = exports.acot = exports.acosh = exports.acos = exports.abs = exports._true = exports._null = exports._false = exports._NaN = exports._Infinity = exports.Unit = exports.SparseMatrix = exports.Spa = exports.SQRT2 = exports.SQRT1_2 = exports.ResultSet = exports.Range = exports.Matrix = exports.LOG2E = exports.LOG10E = exports.LN2 = exports.LN10 = exports.Index = exports.ImmutableDenseMatrix = exports.Fraction = exports.FibonacciHeap = exports.DenseMatrix = exports.Complex = exports.BigNumber = void 0;
 exports.number = exports.nuclearMagneton = exports.nthRoots = exports.nthRoot = exports.not = exports.norm = exports.neutronMass = exports.multiplyScalar = exports.multiply = exports.multinomial = exports.molarVolume = exports.molarPlanckConstant = exports.molarMassC12 = exports.molarMass = exports.mode = exports.mod = exports.min = exports.median = exports.mean = exports.max = exports.matrixFromRows = exports.matrixFromFunction = exports.matrixFromColumns = exports.matrix = exports.mapSlices = exports.map = exports.magneticFluxQuantum = exports.magneticConstant = exports.mad = exports.lyap = exports.lusolve = exports.lup = exports.lsolveAll = exports.lsolve = exports.loschmidt = exports.log2 = exports.log1p = exports.log10 = exports.log = exports.lgamma = exports.leftShift = exports.lcm = exports.largerEq = exports.larger = exports.kron = exports.klitzing = exports.kldivergence = exports.isZero = exports.isPrime = exports.isPositive = exports.isNumeric = exports.isNegative = exports.isNaN = exports.isInteger = exports.invmod = exports.inverseConductanceQuantum = exports.inv = exports.intersect = exports.index = exports.im = exports.ifft = exports.identity = exports.i = exports.hypot = exports.hex = exports.hasNumericValue = exports.hartreeEnergy = exports.gravity = exports.gravitationConstant = exports.getMatrixDataType = exports.gcd = exports.gasConstant = exports.gamma = exports.freqz = exports.fraction = exports.format = exports.forEach = exports.floor = exports.flatten = exports.fix = exports.firstRadiation = exports.fineStructure = exports.filter = exports.fft = exports.fermiCoupling = exports.faraday = exports.factorial = exports.expm1 = exports.expm = exports.exp = exports.erf = exports.equalText = exports.equalScalar = exports.equal = exports.elementaryCharge = exports.electronMass = exports.electricConstant = exports.eigs = exports.efimovFactor = exports.e = void 0;
-exports.xgcd = exports.wienDisplacement = exports.weakMixingAngle = exports.version = exports.variance = exports.vacuumImpedance = exports.usolveAll = exports.usolve = exports.unit = exports.unequal = exports.unaryPlus = exports.unaryMinus = exports.typed = exports.typeOf = exports.transpose = exports.trace = exports.to = exports.thomsonCrossSection = exports.tau = exports.tanh = exports.tan = exports.sylvester = exports.sum = exports.subtractScalar = exports.subtract = exports.subset = exports.string = exports.stirlingS2 = exports.stefanBoltzmann = exports.std = exports.squeeze = exports.square = exports.sqrtm = exports.sqrt = exports.splitUnit = exports.speedOfLight = exports.sparse = exports.sort = exports.solveODE = exports.smallerEq = exports.smaller = exports.slu = exports.size = exports.sinh = exports.sin = exports.sign = exports.setUnion = exports.setSymDifference = exports.setSize = exports.setPowerset = exports.setMultiplicity = exports.setIsSubset = exports.setIntersect = exports.setDistinct = exports.setDifference = exports.setCartesian = exports.secondRadiation = exports.sech = exports.sec = exports.schur = exports.sackurTetrode = exports.rydberg = exports.row = exports.round = exports.rotationMatrix = exports.rotate = exports.rightLogShift = exports.rightArithShift = exports.resize = exports.reshape = exports.replacer = exports.reducedPlanckConstant = exports.re = exports.range = exports.randomInt = exports.random = exports.quantumOfCirculation = exports.quantileSeq = exports.qr = exports.protonMass = exports.prod = exports.print = exports.pow = exports.polynomialRoot = exports.planckTime = exports.planckTemperature = exports.planckMass = exports.planckLength = exports.planckConstant = exports.planckCharge = exports.pinv = exports.pickRandom = exports.pi = exports.phi = exports.permutations = exports.partitionSelect = exports.or = exports.ones = exports.oct = exports.numeric = void 0;
-exports.zpk2tf = exports.zeta = exports.zeros = exports.xor = void 0;
+exports.wienDisplacement = exports.weakMixingAngle = exports.version = exports.variance = exports.vacuumImpedance = exports.usolveAll = exports.usolve = exports.unit = exports.unequal = exports.unaryPlus = exports.unaryMinus = exports.typed = exports.typeOf = exports.transpose = exports.trace = exports.toBest = exports.to = exports.thomsonCrossSection = exports.tau = exports.tanh = exports.tan = exports.sylvester = exports.sum = exports.subtractScalar = exports.subtract = exports.subset = exports.string = exports.stirlingS2 = exports.stefanBoltzmann = exports.std = exports.squeeze = exports.square = exports.sqrtm = exports.sqrt = exports.splitUnit = exports.speedOfLight = exports.sparse = exports.sort = exports.solveODE = exports.smallerEq = exports.smaller = exports.slu = exports.size = exports.sinh = exports.sin = exports.sign = exports.setUnion = exports.setSymDifference = exports.setSize = exports.setPowerset = exports.setMultiplicity = exports.setIsSubset = exports.setIntersect = exports.setDistinct = exports.setDifference = exports.setCartesian = exports.secondRadiation = exports.sech = exports.sec = exports.schur = exports.sackurTetrode = exports.rydberg = exports.row = exports.round = exports.rotationMatrix = exports.rotate = exports.rightLogShift = exports.rightArithShift = exports.resize = exports.reshape = exports.replacer = exports.reducedPlanckConstant = exports.re = exports.range = exports.randomInt = exports.random = exports.quantumOfCirculation = exports.quantileSeq = exports.qr = exports.protonMass = exports.prod = exports.print = exports.pow = exports.polynomialRoot = exports.planckTime = exports.planckTemperature = exports.planckMass = exports.planckLength = exports.planckConstant = exports.planckCharge = exports.pinv = exports.pickRandom = exports.pi = exports.phi = exports.permutations = exports.partitionSelect = exports.or = exports.ones = exports.oct = exports.numeric = void 0;
+exports.zpk2tf = exports.zeta = exports.zeros = exports.xor = exports.xgcd = void 0;
 var _configReadonly = require("./configReadonly.js");
 var _factoriesAny = require("../factoriesAny.js");
 /**
@@ -308,6 +308,9 @@ const subtractScalar = exports.subtractScalar = /* #__PURE__ */(0, _factoriesAny
 const tan = exports.tan = /* #__PURE__ */(0, _factoriesAny.createTan)({
   typed
 });
+const toBest = exports.toBest = /* #__PURE__ */(0, _factoriesAny.createToBest)({
+  typed
+});
 const typeOf = exports.typeOf = /* #__PURE__ */(0, _factoriesAny.createTypeOf)({
   typed
 });
@@ -1185,7 +1188,8 @@ const Unit = exports.Unit = /* #__PURE__ */(0, _factoriesAny.createUnitClass)({
   number,
   pow,
   round,
-  subtractScalar
+  subtractScalar,
+  toBest
 });
 const vacuumImpedance = exports.vacuumImpedance = /* #__PURE__ */(0, _factoriesAny.createVacuumImpedance)({
   BigNumber,

package/lib/cjs/expression/Parser.js

@@ -5,6 +5,7 @@ Object.defineProperty(exports, "__esModule", {
 });
 exports.createParserClass = void 0;
 var _factory = require("../utils/factory.js");
+var _is = require("../utils/is.js");
 var _map = require("../utils/map.js");
 const name = 'Parser';
 const dependencies = ['evaluate', 'parse'];
@@ -160,7 +161,40 @@ const createParserClass = exports.createParserClass = /* #__PURE__ */(0, _factor
   Parser.prototype.clear = function () {
     this.scope.clear();
   };
+  Parser.prototype.toJSON = function () {
+    const json = {
+      mathjs: 'Parser',
+      variables: {},
+      functions: {}
+    };
+    for (const [name, value] of this.scope) {
+      if ((0, _is.isFunction)(value)) {
+        if (!isExpressionFunction(value)) {
+          throw new Error(`Cannot serialize external function ${name}`);
+        }
+        json.functions[name] = `${value.syntax} = ${value.expr}`;
+      } else {
+        json.variables[name] = value;
+      }
+    }
+    return json;
+  };
+  Parser.fromJSON = function (json) {
+    const parser = new Parser();
+    Object.entries(json.variables).forEach(_ref2 => {
+      let [name, value] = _ref2;
+      return parser.set(name, value);
+    });
+    Object.entries(json.functions).forEach(_ref3 => {
+      let [_name, fn] = _ref3;
+      return parser.evaluate(fn);
+    });
+    return parser;
+  };
   return Parser;
 }, {
   isClass: true
-});
+});
+function isExpressionFunction(value) {
+  return typeof value === 'function' && typeof value.syntax === 'string' && typeof value.expr === 'string';
+}

package/lib/cjs/expression/embeddedDocs/embeddedDocs.js

@@ -235,6 +235,7 @@ var _sinh = require("./function/trigonometry/sinh.js");
 var _tan = require("./function/trigonometry/tan.js");
 var _tanh = require("./function/trigonometry/tanh.js");
 var _to = require("./function/units/to.js");
+var _toBest = require("./function/units/toBest.js");
 var _bin = require("./function/utils/bin.js");
 var _clone = require("./function/utils/clone.js");
 var _format = require("./function/utils/format.js");
@@ -718,6 +719,7 @@ const embeddedDocs = exports.embeddedDocs = {
   tanh: _tanh.tanhDocs,
   // functions - units
   to: _to.toDocs,
+  toBest: _toBest.toBestDocs,
   // functions - utils
   clone: _clone.cloneDocs,
   format: _format.formatDocs,

package/lib/cjs/expression/embeddedDocs/function/units/toBest.js

@@ -0,0 +1,14 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.toBestDocs = void 0;
+const toBestDocs = exports.toBestDocs = {
+  name: 'toBest',
+  category: 'Units',
+  syntax: ['toBest(x)', 'toBest(x, unitList)', 'toBest(x, unitList, options)'],
+  description: 'Converts to the most appropriate display unit.',
+  examples: ['toBest(unit(5000, "m"))', 'toBest(unit(3500000, "W"))', 'toBest(unit(0.000000123, "A"))', 'toBest(unit(10, "m"), "cm")', 'toBest(unit(10, "m"), "mm,km", {offset: 1.5})'],
+  seealso: []
+};

package/lib/cjs/expression/node/FunctionAssignmentNode.js

@@ -105,7 +105,8 @@ const createFunctionAssignmentNode = exports.createFunctionAssignmentNode = /* #
       });
 
       // compile the function expression with the child args
-      const evalExpr = this.expr._compile(math, childArgNames);
+      const expr = this.expr;
+      const evalExpr = expr._compile(math, childArgNames);
       const name = this.name;
       const params = this.params;
       const signature = (0, _array.join)(this.types, ',');
@@ -121,6 +122,7 @@ const createFunctionAssignmentNode = exports.createFunctionAssignmentNode = /* #
         };
         const fn = typed(name, signatures);
         fn.syntax = syntax;
+        fn.expr = expr.toString();
         scope.set(name, fn);
         return fn;
       };

package/lib/cjs/expression/parse.js

@@ -54,7 +54,7 @@ const createParse = exports.createParse = /* #__PURE__ */(0, _factory.factory)(n
    *     node1.compile().evaluate() // 5
    *
    *     let scope = {a:3, b:4}
-   *     const node2 = math.parse('a * b') // 12
+   *     const node2 = math.parse('a * b')
    *     node2.evaluate(scope) // 12
    *     const code2 = node2.compile()
    *     code2.evaluate(scope) // 12

package/lib/cjs/factoriesAny.js

@@ -2031,6 +2031,12 @@ Object.defineProperty(exports, "createTo", {
     return _to.createTo;
   }
 });
+Object.defineProperty(exports, "createToBest", {
+  enumerable: true,
+  get: function () {
+    return _toBest.createToBest;
+  }
+});
 Object.defineProperty(exports, "createTrace", {
   enumerable: true,
   get: function () {
@@ -2290,6 +2296,7 @@ var _oct = require("./function/string/oct.js");
 var _hex = require("./function/string/hex.js");
 var _print = require("./function/string/print.js");
 var _to = require("./function/unit/to.js");
+var _toBest = require("./function/unit/toBest.js");
 var _isPrime = require("./function/utils/isPrime.js");
 var _numeric = require("./function/utils/numeric.js");
 var _divideScalar = require("./function/arithmetic/divideScalar.js");

package/lib/cjs/function/arithmetic/sign.js

@@ -58,7 +58,7 @@ const createSign = exports.createSign = /* #__PURE__ */(0, _factory.factory)(nam
       return x > 0n ? 1n : x < 0n ? -1n : 0n;
     },
     Fraction: function (x) {
-      return new Fraction(x.s);
+      return x.n === 0n ? new Fraction(0) : new Fraction(x.s);
     },
     // deep map collection, skip zeros since sign(0) = 0
     'Array | Matrix': typed.referToSelf(self => x => (0, _collection.deepMap)(x, self, true)),

package/lib/cjs/function/matrix/range.js

@@ -22,7 +22,7 @@ const createRange = exports.createRange = /* #__PURE__ */(0, _factory.factory)(n
     isPositive
   } = _ref;
   /**
-   * Create an array from a range.
+   * Create a matrix or array containing a range of values.
    * By default, the range end is excluded. This can be customized by providing
    * an extra parameter `includeEnd`.
    *
@@ -50,10 +50,12 @@ const createRange = exports.createRange = /* #__PURE__ */(0, _factory.factory)(n
    * - `includeEnd: boolean`
    *   Option to specify whether to include the end or not. False by default.
    *
-   * Note that the return type of the range is taken from the type of
-   * the start/end. If only one these is a built-in `number` type, it will
-   * be promoted to the type of the other endpoint. However, in the case of
-   * Unit values, both endpoints must have compatible units, and the return
+   * The function returns a `DenseMatrix` when the library is configured with
+   * `config = { matrix: 'Matrix' }, and returns an Array otherwise.
+   * Note that the type of the returned values is taken from the type of the
+   * provided start/end value. If only one of these is a built-in `number` type,
+   * it will be promoted to the type of the other endpoint. However, in the case
+   * of Unit values, both endpoints must have compatible units, and the return
    * value will have compatible units as well.
    *
    * Examples:

package/lib/cjs/function/unit/toBest.js

@@ -0,0 +1,53 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.createToBest = void 0;
+var _factory = require("../../utils/factory.js");
+const name = 'toBest';
+const dependencies = ['typed'];
+const createToBest = exports.createToBest = /* #__PURE__ */(0, _factory.factory)(name, dependencies, _ref => {
+  let {
+    typed
+  } = _ref;
+  /**
+   * Converts a unit to the most appropriate display unit.
+   * When no preferred units are provided, the function automatically find the best prefix.
+   * When preferred units are provided, it converts to
+   * the unit that gives a value closest to 1.
+   *
+   * Syntax:
+   *
+   *    math.toBest(unit)
+   *    math.toBest(unit, unitList)
+   *    math.toBest(unit, unitList, options)
+   *
+   * Where:
+   * - `unitList` is an optional array of preferred target units as string or Unit.
+   * - `options` is an optional object with options, formed as follows:
+   * - `offset`: number | BigNumber
+   *
+   * Examples:
+   *
+   *   math.unit(0.05, 'm').toBest(['cm', 'mm'])                 // returns Unit 5 cm
+   *   math.unit(2 / 3, 'cm').toBest()                           // returns Unit 0.6666666666666666 cm
+   *   math.unit(10, 'm').toBest(['mm', 'km'], { offset: 1.5 })  // returns Unit 10000 mm
+   *
+   * See also:
+   *
+   *    unit, to, format
+   *
+   * @param {Unit} x                          The unit to be converted
+   * @param {Array<string>} [unitList=[]]     Optional array of preferred target units
+   * @param {Object} [options]                Optional options object
+   * @return {Unit}                           Value converted to the best matching unit
+   */
+  return typed(name, {
+    Unit: x => x.toBest(),
+    'Unit, string': (x, unitList) => x.toBest(unitList.split(',')),
+    'Unit, string, Object': (x, unitList, options) => x.toBest(unitList.split(','), options),
+    'Unit, Array': (x, unitList) => x.toBest(unitList),
+    'Unit, Array, Object': (x, unitList, options) => x.toBest(unitList, options)
+  });
+});

package/lib/cjs/header.js

@@ -6,8 +6,8 @@
  * It features real and complex numbers, units, matrices, a large set of
  * mathematical functions, and a flexible expression parser.
  *
- * @version 14.5.3
- * @date    2025-07-02
+ * @version 14.7.0
+ * @date    2025-09-05
  *
  * @license
  * Copyright (C) 2013-2025 Jos de Jong <wjosdejong@gmail.com>

package/lib/cjs/type/matrix/DenseMatrix.js

@@ -679,24 +679,28 @@ const createDenseMatrixClass = exports.createDenseMatrixClass = /* #__PURE__ */(
       }
       return;
     }
-    const index = [];
-    const recurse = function* (value, depth) {
-      if (depth < maxDepth) {
-        for (let i = 0; i < value.length; i++) {
-          index[depth] = i;
-          yield* recurse(value[i], depth + 1);
-        }
-      } else {
-        for (let i = 0; i < value.length; i++) {
-          index[depth] = i;
-          yield {
-            value: value[i],
-            index: index.slice()
-          };
-        }
+
+    // Multi-dimensional matrix: iterate over all elements
+    const index = Array(maxDepth + 1).fill(0);
+    const totalElements = this._size.reduce((a, b) => a * b, 1);
+    for (let count = 0; count < totalElements; count++) {
+      // Traverse to the current element using indices
+      let current = this._data;
+      for (let d = 0; d < maxDepth; d++) {
+        current = current[index[d]];
       }
-    };
-    yield* recurse(this._data, 0);
+      yield {
+        value: current[index[maxDepth]],
+        index: index.slice()
+      };
+
+      // Increment indices for next element
+      for (let d = maxDepth; d >= 0; d--) {
+        index[d]++;
+        if (index[d] < this._size[d]) break;
+        index[d] = 0;
+      }
+    }
   };
 
   /**

package/lib/cjs/type/string.js

@@ -23,13 +23,13 @@ const createString = exports.createString = /* #__PURE__ */(0, _factory.factory)
    *
    * Examples:
    *
-   *    math.string(4.2)               // returns string '4.2'
-   *    math.string(math.complex(3, 2) // returns string '3 + 2i'
+   *    math.string(4.2)                // returns string '4.2'
+   *    math.string(math.complex(3, 2)) // returns string '3 + 2i'
    *
    *    const u = math.unit(5, 'km')
-   *    math.string(u.to('m'))         // returns string '5000 m'
+   *    math.string(u.to('m'))          // returns string '5000 m'
    *
-   *    math.string([true, false])     // returns ['true', 'false']
+   *    math.string([true, false])      // returns ['true', 'false']
    *
    * See also:
    *

package/lib/cjs/type/unit/Unit.js

@@ -13,7 +13,7 @@ var _string = require("../../utils/string.js");
 var _object = require("../../utils/object.js");
 var _constants = require("../../utils/bignumber/constants.js");
 const name = 'Unit';
-const dependencies = ['?on', 'config', 'addScalar', 'subtractScalar', 'multiplyScalar', 'divideScalar', 'pow', 'abs', 'fix', 'round', 'equal', 'isNumeric', 'format', 'number', 'Complex', 'BigNumber', 'Fraction'];
+const dependencies = ['?on', 'config', 'addScalar', 'subtractScalar', 'multiplyScalar', 'divideScalar', 'pow', 'abs', 'fix', 'round', 'equal', 'isNumeric', 'format', 'toBest', 'number', 'Complex', 'BigNumber', 'Fraction'];
 const createUnitClass = exports.createUnitClass = /* #__PURE__ */(0, _factory.factory)(name, dependencies, _ref => {
   let {
     on,
@@ -29,6 +29,7 @@ const createUnitClass = exports.createUnitClass = /* #__PURE__ */(0, _factory.fa
     equal,
     isNumeric,
     format,
+    toBest,
     number,
     Complex,
     BigNumber,
@@ -1048,6 +1049,54 @@ const createUnitClass = exports.createUnitClass = /* #__PURE__ */(0, _factory.fa
     return str;
   };
 
+  /**
+   * Get a unit, with optional formatting options.
+   * @memberof Unit
+   * @param {string[] | Unit[]} [units]  Array of units strings or valueLess Unit objects in wich choose the best one
+   * @param {Object} [options]  Options for parsing the unit. See parseUnit for details.
+   *
+   * @return {Unit} Returns a new Unit with the given value and unit.
+   */
+  Unit.prototype.toBest = function () {
+    let unitList = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : [];
+    let options = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
+    if (unitList && !Array.isArray(unitList)) {
+      throw new Error('Invalid unit type. Expected string or Unit.');
+    }
+    const startPrefixes = this.units[0].unit.prefixes;
+    if (unitList && unitList.length > 0) {
+      const unitObjects = unitList.map(u => {
+        let unit = null;
+        if (typeof u === 'string') {
+          unit = Unit.parse(u);
+          if (!unit) {
+            throw new Error('Invalid unit type. Expected compatible string or Unit.');
+          }
+        } else if (!(0, _is.isUnit)(u)) {
+          throw new Error('Invalid unit type. Expected compatible string or Unit.');
+        }
+        if (unit === null) {
+          unit = u.clone();
+        }
+        try {
+          this.to(unit.formatUnits());
+          return unit;
+        } catch (e) {
+          throw new Error('Invalid unit type. Expected compatible string or Unit.');
+        }
+      });
+      const prefixes = unitObjects.map(el => el.units[0].prefix);
+      this.units[0].unit.prefixes = prefixes.reduce((acc, prefix) => {
+        acc[prefix.name] = prefix;
+        return acc;
+      }, {});
+      this.units[0].prefix = prefixes[0];
+    }
+    const result = formatBest(this, options).simp;
+    this.units[0].unit.prefixes = startPrefixes;
+    result.fixPrefix = true;
+    return result;
+  };
   /**
    * Get a string representation of the Unit, with optional formatting options.
    * @memberof Unit
@@ -1058,11 +1107,54 @@ const createUnitClass = exports.createUnitClass = /* #__PURE__ */(0, _factory.fa
    * @return {string}
    */
   Unit.prototype.format = function (options) {
+    const {
+      simp,
+      valueStr,
+      unitStr
+    } = formatBest(this, options);
+    let str = valueStr;
+    if (simp.value && (0, _is.isComplex)(simp.value)) {
+      str = '(' + str + ')'; // Surround complex values with ( ) to enable better parsing
+    }
+    if (unitStr.length > 0 && str.length > 0) {
+      str += ' ';
+    }
+    str += unitStr;
+    return str;
+  };
+
+  /**
+  * Helper function to normalize a unit for conversion and formatting
+  * @param {Unit} unit The unit to be normalized
+  * @return {Object} Object with normalized unit and value
+  * @private
+  */
+  function formatBest(unit) {
+    let options = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
     // Simplfy the unit list, unless it is valueless or was created directly in the
     // constructor or as the result of to or toSI
-    const simp = this.skipAutomaticSimplification || this.value === null ? this.clone() : this.simplify();
+    const simp = unit.skipAutomaticSimplification || unit.value === null ? unit.clone() : unit.simplify();
 
     // Apply some custom logic for handling VA and VAR. The goal is to express the value of the unit as a real value, if possible. Otherwise, use a real-valued unit instead of a complex-valued one.
+    handleVAandVARUnits(simp);
+    // Now apply the best prefix
+    // Units must have only one unit and not have the fixPrefix flag set
+    applyBestPrefixIfNeeded(simp, options.offset);
+    const value = simp._denormalize(simp.value);
+    const valueStr = simp.value !== null ? format(value, options || {}) : '';
+    const unitStr = simp.formatUnits();
+    return {
+      simp,
+      valueStr,
+      unitStr
+    };
+  }
+
+  /**
+   * Helper to handle VA and VAR units
+   * @param {Unit} simp The unit to be normalized
+   */
+  function handleVAandVARUnits(simp) {
     let isImaginary = false;
     if (typeof simp.value !== 'undefined' && simp.value !== null && (0, _is.isComplex)(simp.value)) {
       // TODO: Make this better, for example, use relative magnitude of re and im rather than absolute
@@ -1079,37 +1171,32 @@ const createUnitClass = exports.createUnitClass = /* #__PURE__ */(0, _factory.fa
         }
       }
     }
+  }
 
-    // Now apply the best prefix
-    // Units must have only one unit and not have the fixPrefix flag set
+  /**
+   * Helper to apply the best prefix if needed
+   * @param {Unit} simp The unit to be normalized
+   */
+  function applyBestPrefixIfNeeded(simp, offset) {
     if (simp.units.length === 1 && !simp.fixPrefix) {
       // Units must have integer powers, otherwise the prefix will change the
       // outputted value by not-an-integer-power-of-ten
       if (Math.abs(simp.units[0].power - Math.round(simp.units[0].power)) < 1e-14) {
         // Apply the best prefix
-        simp.units[0].prefix = simp._bestPrefix();
+        simp.units[0].prefix = simp._bestPrefix(offset);
       }
     }
-    const value = simp._denormalize(simp.value);
-    let str = simp.value !== null ? format(value, options || {}) : '';
-    const unitStr = simp.formatUnits();
-    if (simp.value && (0, _is.isComplex)(simp.value)) {
-      str = '(' + str + ')'; // Surround complex values with ( ) to enable better parsing
-    }
-    if (unitStr.length > 0 && str.length > 0) {
-      str += ' ';
-    }
-    str += unitStr;
-    return str;
-  };
+  }
 
   /**
    * Calculate the best prefix using current value.
    * @memberof Unit
    * @returns {Object} prefix
+   * @param {number} [offset]  Optional offset for the best prefix calculation (default 1.2)
    * @private
    */
   Unit.prototype._bestPrefix = function () {
+    let offset = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : 1.2;
     if (this.units.length !== 1) {
       throw new Error('Can only compute the best prefix for single units with integer powers, like kg, s^2, N^-1, and so forth!');
     }
@@ -1132,7 +1219,7 @@ const createUnitClass = exports.createUnitClass = /* #__PURE__ */(0, _factory.fa
       return bestPrefix;
     }
     const power = this.units[0].power;
-    let bestDiff = Math.log(absValue / Math.pow(bestPrefix.value * absUnitValue, power)) / Math.LN10 - 1.2;
+    let bestDiff = Math.log(absValue / Math.pow(bestPrefix.value * absUnitValue, power)) / Math.LN10 - offset;
     if (bestDiff > -2.200001 && bestDiff < 1.800001) return bestPrefix; // Allow the original prefix
     bestDiff = Math.abs(bestDiff);
     const prefixes = this.units[0].unit.prefixes;
@@ -1140,7 +1227,7 @@ const createUnitClass = exports.createUnitClass = /* #__PURE__ */(0, _factory.fa
       if ((0, _object.hasOwnProperty)(prefixes, p)) {
         const prefix = prefixes[p];
         if (prefix.scientific) {
-          const diff = Math.abs(Math.log(absValue / Math.pow(prefix.value * absUnitValue, power)) / Math.LN10 - 1.2);
+          const diff = Math.abs(Math.log(absValue / Math.pow(prefix.value * absUnitValue, power)) / Math.LN10 - offset);
           if (diff < bestDiff || diff === bestDiff && prefix.name.length < bestPrefix.name.length) {
             // choose the prefix with the smallest diff, or if equal, choose the one
             // with the shortest name (can happen with SHORTLONG for example)

package/lib/cjs/version.js

@@ -4,6 +4,6 @@ Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.version = void 0;
-const version = exports.version = '14.5.3';
+const version = exports.version = '14.7.0';
 // Note: This file is automatically generated when building math.js.
 // Changes made in this file will be overwritten.

package/lib/esm/core/function/config.js

@@ -16,7 +16,6 @@ export function configFactory(config, emit) {
    *
    * Examples:
    *
-   *
    *     import { create, all } from 'mathjs'
    *
    *     // create a mathjs instance

package/lib/esm/entry/dependenciesAny/dependenciesToBest.generated.js

@@ -0,0 +1,10 @@
+/**
+ * THIS FILE IS AUTO-GENERATED
+ * DON'T MAKE CHANGES HERE
+ */
+import { typedDependencies } from './dependenciesTyped.generated.js';
+import { createToBest } from '../../factoriesAny.js';
+export var toBestDependencies = {
+  typedDependencies,
+  createToBest
+};