mathjs 14.5.3 → 14.6.0

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

@@ -0,0 +1,47 @@
+import { factory } from '../../utils/factory.js';
+var name = 'toBest';
+var dependencies = ['typed'];
+export var createToBest = /* #__PURE__ */factory(name, dependencies, _ref => {
+  var {
+    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/esm/type/unit/Unit.js

@@ -9,7 +9,7 @@ import { endsWith } from '../../utils/string.js';
 import { clone, hasOwnProperty } from '../../utils/object.js';
 import { createBigNumberPi as createPi } from '../../utils/bignumber/constants.js';
 var name = 'Unit';
-var dependencies = ['?on', 'config', 'addScalar', 'subtractScalar', 'multiplyScalar', 'divideScalar', 'pow', 'abs', 'fix', 'round', 'equal', 'isNumeric', 'format', 'number', 'Complex', 'BigNumber', 'Fraction'];
+var dependencies = ['?on', 'config', 'addScalar', 'subtractScalar', 'multiplyScalar', 'divideScalar', 'pow', 'abs', 'fix', 'round', 'equal', 'isNumeric', 'format', 'toBest', 'number', 'Complex', 'BigNumber', 'Fraction'];
 export var createUnitClass = /* #__PURE__ */factory(name, dependencies, _ref => {
   var {
     on,
@@ -25,6 +25,7 @@ export var createUnitClass = /* #__PURE__ */factory(name, dependencies, _ref =>
     equal,
     isNumeric,
     format,
+    toBest,
     number: _number,
     Complex,
     BigNumber: _BigNumber,
@@ -1041,6 +1042,54 @@ export var createUnitClass = /* #__PURE__ */factory(name, dependencies, _ref =>
     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 () {
+    var unitList = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : [];
+    var options = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
+    if (unitList && !Array.isArray(unitList)) {
+      throw new Error('Invalid unit type. Expected string or Unit.');
+    }
+    var startPrefixes = this.units[0].unit.prefixes;
+    if (unitList && unitList.length > 0) {
+      var unitObjects = unitList.map(u => {
+        var 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 (!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.');
+        }
+      });
+      var 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];
+    }
+    var 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
@@ -1051,11 +1100,54 @@ export var createUnitClass = /* #__PURE__ */factory(name, dependencies, _ref =>
    * @return {string}
    */
   Unit.prototype.format = function (options) {
+    var {
+      simp,
+      valueStr,
+      unitStr
+    } = formatBest(this, options);
+    var str = valueStr;
+    if (simp.value && 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) {
+    var 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
-    var simp = this.skipAutomaticSimplification || this.value === null ? this.clone() : this.simplify();
+    var 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);
+    var value = simp._denormalize(simp.value);
+    var valueStr = simp.value !== null ? format(value, options || {}) : '';
+    var 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) {
     var isImaginary = false;
     if (typeof simp.value !== 'undefined' && simp.value !== null && isComplex(simp.value)) {
       // TODO: Make this better, for example, use relative magnitude of re and im rather than absolute
@@ -1072,37 +1164,32 @@ export var createUnitClass = /* #__PURE__ */factory(name, dependencies, _ref =>
         }
       }
     }
+  }
 
-    // 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);
       }
     }
-    var value = simp._denormalize(simp.value);
-    var str = simp.value !== null ? format(value, options || {}) : '';
-    var unitStr = simp.formatUnits();
-    if (simp.value && 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 () {
+    var 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!');
     }
@@ -1125,7 +1212,7 @@ export var createUnitClass = /* #__PURE__ */factory(name, dependencies, _ref =>
       return bestPrefix;
     }
     var power = this.units[0].power;
-    var bestDiff = Math.log(absValue / Math.pow(bestPrefix.value * absUnitValue, power)) / Math.LN10 - 1.2;
+    var 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);
     var prefixes = this.units[0].unit.prefixes;
@@ -1133,7 +1220,7 @@ export var createUnitClass = /* #__PURE__ */factory(name, dependencies, _ref =>
       if (hasOwnProperty(prefixes, p)) {
         var prefix = prefixes[p];
         if (prefix.scientific) {
-          var diff = Math.abs(Math.log(absValue / Math.pow(prefix.value * absUnitValue, power)) / Math.LN10 - 1.2);
+          var 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/esm/version.js

@@ -1,3 +1,3 @@
-export var version = '14.5.3';
+export var version = '14.6.0';
 // Note: This file is automatically generated when building math.js.
 // Changes made in this file will be overwritten.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mathjs",
-  "version": "14.5.3",
+  "version": "14.6.0",
   "description": "Math.js is an extensive math library for JavaScript and Node.js. It features a flexible expression parser with support for symbolic computation, comes with a large set of built-in functions and constants, and offers an integrated solution to work with different data types like numbers, big numbers, complex numbers, fractions, units, and matrices.",
   "author": "Jos de Jong <wjosdejong@gmail.com> (https://github.com/josdejong)",
   "homepage": "https://mathjs.org",
@@ -44,13 +44,13 @@
     "@babel/register": "7.27.1",
     "@types/assert": "1.5.11",
     "@types/mocha": "10.0.10",
-    "@typescript-eslint/eslint-plugin": "8.35.1",
-    "@typescript-eslint/parser": "8.35.1",
+    "@typescript-eslint/eslint-plugin": "8.38.0",
+    "@typescript-eslint/parser": "8.38.0",
     "assert": "2.1.0",
     "babel-loader": "10.0.0",
     "c8": "10.1.3",
     "codecov": "3.8.3",
-    "core-js": "3.43.0",
+    "core-js": "3.44.0",
     "del": "8.0.0",
     "dtslint": "4.2.1",
     "eigen": "0.2.2",
@@ -60,9 +60,9 @@
     "eslint-plugin-import": "2.32.0",
     "eslint-plugin-mocha": "10.5.0",
     "eslint-plugin-n": "16.6.2",
-    "eslint-plugin-prettier": "5.5.1",
+    "eslint-plugin-prettier": "5.5.3",
     "eslint-plugin-promise": "6.6.0",
-    "expect-type": "1.2.1",
+    "expect-type": "1.2.2",
     "expr-eval": "2.0.2",
     "fancy-log": "2.0.0",
     "glob": "11.0.3",
@@ -93,7 +93,7 @@
     "tinybench": "4.0.1",
     "ts-node": "10.9.2",
     "typescript": "5.8.3",
-    "webpack": "5.99.9",
+    "webpack": "5.100.2",
     "zeros": "1.0.0"
   },
   "type": "module",

package/types/index.d.ts

@@ -3488,6 +3488,18 @@ export interface MathJsInstance extends MathJsFactory {
    */
   to(x: Unit | MathCollection, unit: Unit | string): Unit | MathCollection
 
+  /**
+   * 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.
+   * @param preferredUnits - Optional preferred target units
+   * @param options - Optional options object
+   * @returns Unit with optimized prefix/unit
+   */
+  toBest(): Unit
+  toBest(units: string[] | Unit[], options: object): Unit
+
   /*************************************************************************
    * Utils
    ************************************************************************/
@@ -3834,6 +3846,7 @@ export const {
   formatDependencies,
   printDependencies,
   toDependencies,
+  toBestDependencies,
   isPrimeDependencies,
   numericDependencies,
   divideScalarDependencies,
@@ -4177,6 +4190,8 @@ export interface Unit {
   pow(unit: Unit): Unit
   abs(unit: Unit): Unit
   to(unit: string | Unit): Unit
+  toBest(): Unit
+  toBest(units?: string[] | Unit[], options?: object): Unit
   toNumber(unit?: string): number
   toNumeric(unit?: string): number | Fraction | BigNumber
   toSI(): Unit
@@ -6991,6 +7006,21 @@ export interface MathJsChain<TValue> {
     unit: Unit | string
   ): MathJsChain<Unit | MathCollection>
 
+  /**
+   * 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.
+   * @param preferredUnits - Optional preferred target units
+   * @param options - Optional options object
+   */
+  toBest(this: MathJsChain<Unit>): MathJsChain<Unit>
+  toBest(
+    this: MathJsChain<Unit>,
+    units: string[] | Unit[],
+    options: object
+  ): MathJsChain<Unit>
+
   /*************************************************************************
    * Utils functions
    ************************************************************************/
@@ -7380,6 +7410,7 @@ export const {
 
   // unit functions
   to,
+  toBest,
 
   // util functions
   isNumber,