mathjs 14.5.2 → 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.2';
+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.2",
+  "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",
@@ -36,37 +36,37 @@
     "typed-function": "^4.2.1"
   },
   "devDependencies": {
-    "@babel/core": "7.27.3",
+    "@babel/core": "7.28.0",
     "@babel/plugin-transform-object-assign": "7.27.1",
     "@babel/plugin-transform-optional-catch-binding": "7.27.1",
-    "@babel/plugin-transform-runtime": "7.27.3",
-    "@babel/preset-env": "7.27.2",
+    "@babel/plugin-transform-runtime": "7.28.0",
+    "@babel/preset-env": "7.28.0",
     "@babel/register": "7.27.1",
     "@types/assert": "1.5.11",
     "@types/mocha": "10.0.10",
-    "@typescript-eslint/eslint-plugin": "8.33.0",
-    "@typescript-eslint/parser": "8.33.0",
+    "@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.42.0",
+    "core-js": "3.44.0",
     "del": "8.0.0",
     "dtslint": "4.2.1",
     "eigen": "0.2.2",
     "eslint": "8.57.1",
     "eslint-config-prettier": "9.1.0",
     "eslint-config-standard": "17.1.0",
-    "eslint-plugin-import": "2.31.0",
+    "eslint-plugin-import": "2.32.0",
     "eslint-plugin-mocha": "10.5.0",
     "eslint-plugin-n": "16.6.2",
-    "eslint-plugin-prettier": "5.4.0",
+    "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.2",
-    "gulp": "5.0.0",
+    "glob": "11.0.3",
+    "gulp": "5.0.1",
     "gulp-babel": "8.0.0",
     "handlebars": "4.7.8",
     "jsep": "1.4.0",
@@ -78,7 +78,7 @@
     "karma-webdriver-launcher": "1.0.8",
     "karma-webpack": "5.0.1",
     "mkdirp": "3.0.1",
-    "mocha": "11.5.0",
+    "mocha": "11.7.1",
     "mocha-junit-reporter": "2.2.1",
     "ndarray": "1.0.19",
     "ndarray-determinant": "1.0.0",
@@ -86,14 +86,14 @@
     "ndarray-ops": "1.2.2",
     "ndarray-pack": "1.2.1",
     "numericjs": "1.2.6",
-    "prettier": "3.5.3",
+    "prettier": "3.6.2",
     "process": "0.11.10",
-    "sinon": "20.0.0",
+    "sinon": "21.0.0",
     "sylvester": "0.0.21",
     "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/EXPLANATION.md

@@ -20,7 +20,7 @@ Maintaining the TypeScript types is done manually. When adding a function, one h
 3. Add a static definition inside `export const {...} : MathJsInstance`
 4. Add a dependencies definition inside `export const {...} : Record<string, FactoryFunctionMap>`
 
-For exampe for the function `add`, we can have the following definitions:
+For example for the function `add`, we can have the following definitions:
 
 ```ts 
 // instance

package/types/index.d.ts

@@ -28,7 +28,12 @@ export type MatrixFromFunctionCallback<T extends MathScalarType> = (
 ) => T
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
-export type FactoryFunction<T> = (scope: any) => T
+export type FactoryFunction<T> = (scope: MathScope) => T
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type MathScope<TValue = any> =
+  | Record<string, TValue>
+  | MapLike<string, TValue>
 
 // FactoryFunctionMap can be nested; all nested objects will be flattened
 export interface FactoryFunctionMap {
@@ -862,8 +867,8 @@ export interface MathJsInstance extends MathJsFactory {
    * @param unit The unit to be created
    * @returns The created unit
    */
-  unit(value: MathNumericType, unit: string): Unit
-  unit(value: MathCollection, unit: string): Unit[]
+  unit(value: MathNumericType, unit?: string): Unit
+  unit(value: MathCollection): Unit[]
 
   /*************************************************************************
    * Expression functions
@@ -891,12 +896,12 @@ export interface MathJsInstance extends MathJsFactory {
    */
   evaluate(
     expr: MathExpression | Matrix,
-    scope?: object
+    scope?: MathScope
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
   ): any
   evaluate(
     expr: MathExpression[],
-    scope?: object
+    scope?: MathScope
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
   ): any[]
 
@@ -1071,14 +1076,14 @@ export interface MathJsInstance extends MathJsFactory {
    * @param scope Scope to read/write variables
    */
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  resolve(node: MathNode | string, scope?: Record<string, any>): MathNode
+  resolve(node: MathNode | string, scope?: MathScope): MathNode
   resolve(
     node: (MathNode | string)[],
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    scope?: Record<string, any>
+    scope?: MathScope
   ): MathNode[]
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  resolve(node: Matrix, scope?: Record<string, any>): Matrix
+  resolve(node: Matrix, scope?: MathScope): Matrix
 
   /**
    * Calculate the Sparse Matrix LU decomposition with full pivoting.
@@ -1131,9 +1136,9 @@ export interface MathJsInstance extends MathJsFactory {
    * @returns Sum of x and y
    */
   add<T extends MathType>(x: T, y: T): T
-  add<T extends MathType>(...values: T[]): T
+  add<T extends MathType>(x: T, y: T, ...values: T[]): T
   add(x: MathType, y: MathType): MathType
-  add(...values: MathType[]): MathType
+  add(x: MathType, y: MathType, ...values: MathType[]): MathType
 
   /**
    * Calculate the cubic root of a value.
@@ -1460,9 +1465,8 @@ export interface MathJsInstance extends MathJsFactory {
   multiply<T extends MathArray>(x: T, y: T): MathScalarType
   multiply(x: Unit, y: Unit): Unit
   multiply(x: number, y: number): number
-  multiply(x: MathType, y: MathType): MathType
-  multiply<T extends MathType>(...values: T[]): T
-  multiply(...values: MathType[]): MathType
+  multiply(x: MathType, y: MathType, ...values: MathType[]): MathType
+  multiply<T extends MathType>(x: T, y: T, ...values: T[]): T
 
   /**
    * Calculate the norm of a number, vector or matrix. The second
@@ -3484,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
    ************************************************************************/
@@ -3830,6 +3846,7 @@ export const {
   formatDependencies,
   printDependencies,
   toDependencies,
+  toBestDependencies,
   isPrimeDependencies,
   numericDependencies,
   divideScalarDependencies,
@@ -4172,7 +4189,9 @@ export interface Unit {
   divide(unit: Unit): Unit | number
   pow(unit: Unit): Unit
   abs(unit: Unit): Unit
-  to(unit: string): 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
@@ -4286,10 +4305,14 @@ export interface Simplify {
   (
     expr: MathNode | string,
     rules: SimplifyRule[],
-    scope?: object,
+    scope?: MathScope,
+    options?: SimplifyOptions
+  ): MathNode
+  (
+    expr: MathNode | string,
+    scope: MathScope,
     options?: SimplifyOptions
   ): MathNode
-  (expr: MathNode | string, scope: object, options?: SimplifyOptions): MathNode
 
   rules: SimplifyRule[]
 }
@@ -4316,7 +4339,7 @@ export interface ObjectWrappingMap<T extends string | number | symbol, U> {
 
 export interface EvalFunction {
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  evaluate(scope?: any): any
+  evaluate(scope?: MathScope): any
 }
 
 // ResultSet type and helper
@@ -4354,7 +4377,7 @@ export interface MathNode {
    * node.compile().evaluate(scope). Example:
    */
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  evaluate(expr?: any): any
+  evaluate(scope?: MathScope): any
   /**
    * Test whether this node equals an other node. Does a deep comparison
    * of the values of both nodes.
@@ -4818,7 +4841,7 @@ export interface MathJsChain<TValue> {
    */
   unit(this: MathJsChain<string>, unit?: string): MathJsChain<Unit>
   unit(this: MathJsChain<MathNumericType>, unit?: string): MathJsChain<Unit>
-  unit(this: MathJsChain<MathCollection>, unit?: string): MathJsChain<Unit[]>
+  unit(this: MathJsChain<MathCollection>): MathJsChain<Unit[]>
 
   /*************************************************************************
    * Expression functions
@@ -4837,12 +4860,12 @@ export interface MathJsChain<TValue> {
    */
   evaluate(
     this: MathJsChain<MathExpression | Matrix>,
-    scope?: object
+    scope?: MathScope
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
   ): MathJsChain<any>
   evaluate(
     this: MathJsChain<MathExpression[]>,
-    scope?: object
+    scope?: MathScope
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
   ): MathJsChain<any[]>
 
@@ -4879,12 +4902,12 @@ export interface MathJsChain<TValue> {
   resolve(
     this: MathJsChain<MathNode>,
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    scope?: Record<string, any>
+    scope?: MathScope
   ): MathJsChain<MathNode>
   resolve(
     this: MathJsChain<MathNode[]>,
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    scope?: Record<string, any>
+    scope?: MathScope
   ): MathJsChain<MathNode[]>
 
   /*************************************************************************
@@ -6983,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
    ************************************************************************/
@@ -7081,6 +7119,13 @@ export interface ImportObject {
   [key: string]: any
 }
 
+export interface MapLike<TKey = string, TValue = unknown> {
+  get(key: TKey): TValue
+  set(key: TKey, value: TValue): MapLike<TKey, TValue>
+  has(key: TKey): boolean
+  keys(): IterableIterator<TKey> | TKey[]
+}
+
 export const {
   // config // Don't export config: no config available in the static instance
 
@@ -7365,6 +7410,7 @@ export const {
 
   // unit functions
   to,
+  toBest,
 
   // util functions
   isNumber,