mathjs/types/index.d.ts

import { Decimal } from 'decimal.js'
import { Fraction } from 'fraction.js'

export { Fraction }

export as namespace math

export type NoLiteralType<T> = T extends number
  ? number
  : T extends string
    ? string
    : T extends boolean
      ? boolean
      : T

export type MathNumericType = number | BigNumber | bigint | Fraction | Complex
export type MathScalarType = MathNumericType | Unit
export type MathGeneric<T extends MathScalarType = MathNumericType> = T
export type MathArray<T = MathGeneric> = T[] | Array<MathArray<T>>
export type MathCollection<T = MathGeneric> = MathArray<T> | Matrix<T>
export type MathType = MathScalarType | MathCollection
export type MathExpression = string | string[] | MathCollection

// eslint-disable-next-line @typescript-eslint/no-explicit-any
export type FactoryFunction<T> = (scope: any) => T

// FactoryFunctionMap can be nested; all nested objects will be flattened
export interface FactoryFunctionMap {
  // eslint-disable-next-line @typescript-eslint/no-explicit-any
  [key: string]: FactoryFunction<any> | FactoryFunctionMap
}

/** Available options for parse */
export interface ParseOptions {
  /** a set of custom nodes */
  nodes?: Record<string, MathNode>
}
/**
 * Parse an expression. Returns a node tree, which can be evaluated by
 * invoking node.evaluate().
 *
 * Note the evaluating arbitrary expressions may involve security risks,
 * see [https://mathjs.org/docs/expressions/security.html](https://mathjs.org/docs/expressions/security.html) for more information.
 *
 * Syntax:
 *
 *     math.parse(expr)
 *     math.parse(expr, options)
 *     math.parse([expr1, expr2, expr3, ...])
 *     math.parse([expr1, expr2, expr3, ...], options)
 *
 * Example:
 *
 *     const node1 = math.parse('sqrt(3^2 + 4^2)')
 *     node1.compile().evaluate() // 5
 *
 *     let scope = {a:3, b:4}
 *     const node2 = math.parse('a * b') // 12
 *     const code2 = node2.compile()
 *     code2.evaluate(scope) // 12
 *     scope.a = 5
 *     code2.evaluate(scope) // 20
 *
 *     const nodes = math.parse(['a = 3', 'b = 4', 'a * b'])
 *     nodes[2].compile().evaluate() // 12
 *
 * See also:
 *
 *     evaluate, compile
 */
export interface ParseFunction {
  /**
   * Parse an expression. Returns a node tree, which can be evaluated by
   * invoking node.evaluate();
   *
   * @param expr Expression to be parsed
   * @param options Available options
   * @returns A node
   */
  (expr: MathExpression, options?: ParseOptions): MathNode

  /**
   * Parse an expression. Returns a node tree, which can be evaluated by
   * invoking node.evaluate();
   *
   * @param exprs Expressions to be parsed
   * @param options Available options
   * @returns An array of nodes
   */
  (exprs: MathExpression[], options?: ParseOptions): MathNode[]

  /**
   * Checks whether the current character `c` is a valid alpha character:
   *
   * - A latin letter (upper or lower case) Ascii: a-z, A-Z
   * - An underscore                        Ascii: _
   * - A dollar sign                        Ascii: $
   * - A latin letter with accents          Unicode: \u00C0 - \u02AF
   * - A greek letter                       Unicode: \u0370 - \u03FF
   * - A mathematical alphanumeric symbol   Unicode: \u{1D400} - \u{1D7FF} excluding invalid code points
   *
   * The previous and next characters are needed to determine whether
   * this character is part of a unicode surrogate pair.
   *
   * @param c      Current character in the expression
   * @param cPrev  Previous character
   * @param cNext  Next character
   */
  isAlpha(c: string, cPrev: string, cNext: string): boolean
  /**
   * Test whether a character is a valid latin, greek, or letter-like character
   *
   * @param c
   */
  isValidLatinOrGreek(c: string): boolean
  /**
   * Test whether two given 16 bit characters form a surrogate pair of a
   * unicode math symbol.
   *
   * https://unicode-table.com/en/
   * https://www.wikiwand.com/en/Mathematical_operators_and_symbols_in_Unicode
   *
   * Note: In ES6 will be unicode aware:
   * https://stackoverflow.com/questions/280712/javascript-unicode-regexes
   * https://mathiasbynens.be/notes/es6-unicode-regex
   *
   * @param high
   * @param low
   */
  isValidMathSymbol(high: string, low: string): boolean
  /**
   * Check whether given character c is a white space character: space, tab, or enter
   *
   * @param c
   * @param nestingLevel
   */
  isWhitespace(c: string, nestingLevel: number): boolean
  /**
   * Test whether the character c is a decimal mark (dot).
   * This is the case when it's not the start of a delimiter '.*', './', or '.^'
   *
   * @param  c
   * @param  cNext
   */
  isDecimalMark(c: string, cNext: string): boolean
  /**
   * checks if the given char c is a digit or dot
   *
   * @param  c   a string with one character
   */
  isDigitDot(c: string): boolean
  /**
   * checks if the given char c is a digit
   *
   * @param  c   a string with one character
   */
  isDigit(c: string): boolean
  /**
   * checks if the given char c is a hex digit
   *
   * @param c   a string with one character
   */
  isHexDigit(c: string): boolean
}

export interface NodeCtor {
  new (): MathNode
}

export interface AccessorNode<TObject extends MathNode = MathNode>
  extends MathNode {
  type: 'AccessorNode'
  isAccessorNode: true
  object: TObject
  index: IndexNode
  name: string
}
export interface AccessorNodeCtor {
  new <TObject extends MathNode = MathNode>(
    object: TObject,
    index: IndexNode
  ): AccessorNode<TObject>
}

export interface ArrayNode<TItems extends MathNode[] = MathNode[]>
  extends MathNode {
  type: 'ArrayNode'
  isArrayNode: true
  items: [...TItems]
}
export interface ArrayNodeCtor {
  new <TItems extends MathNode[] = MathNode[]>(
    items: [...TItems]
  ): ArrayNode<TItems>