mathjs/types/index.d.ts

import { Decimal } from 'decimal.js'

declare const math: math.MathJsStatic
export as namespace math
export = math

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

declare namespace math {
  // TODO: introduce generics for MathCollection, MathMatrix, and MathArray
  type MathNumericType = number | BigNumber | Fraction | Complex
  type MathScalarType = MathNumericType | Unit
  type MathArray = MathNumericType[] | MathNumericType[][] // TODO: MathArray can also contain Unit
  type MathCollection = MathArray | Matrix
  type MathType = MathScalarType | MathCollection
  type MathExpression = string | string[] | MathCollection

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

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

  /** Available options for parse */
  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
   */
  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
  }

  interface NodeCtor {
    new (): MathNode
  }

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

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

  interface AssignmentNode<TValue extends MathNode = MathNode>
    extends MathNode {
    type: 'AssignmentNode'
    isAssignmentNode: true
    object: SymbolNode | AccessorNode
    index: IndexNode | null
    value: TValue
    name: string
  }
  interface AssignmentNodeCtor {
    new <TValue extends MathNode = MathNode>(
      object: SymbolNode,
      value: TValue
    ): AssignmentNode<TValue>
    new <TValue extends MathNode = MathNode>(
      object: SymbolNode | AccessorNode,
      index: IndexNode,
      value: TValue
    ): AssignmentNode<TValue>
  }

  interface BlockNode<TNode extends MathNode = MathNode> extends MathNode {
    type: 'BlockNode'
    isBlockNode: true
    blocks: Array<{ node: TNode; visible: boolean }>
  }
  interface BlockNodeCtor {
    new <TNode extends MathNode = MathNode>(
      arr: Array<{ node: TNode } | { node: TNode; visible: boolean }>
    ): BlockNode
  }

  interface ConditionalNode<
    TCond extends MathNode = MathNode,
    TTrueNode extends MathNode = MathNode,
    TFalseNode extends MathNode = MathNode
  > extends MathNode {
    type: 'ConditionalNode'
    isConditionalNode: boolean
    condition: TCond
    trueExpr: TTrueNode
    falseExpr: TFalseNode
  }
  interface ConditionalNodeCtor {
    new <
      TCond extends MathNode = MathNode,
      TTrueNode extends MathNode = MathNode,
      TFalseNode extends MathNode = MathNode
    >(
      condition: TCond,
      trueExpr: TTrueNode,
      falseExpr: TFalseNode
    ): ConditionalNode
  }

  interface ConstantNode<TValue extends string | number = number>
    extends MathNode {
    type: 'ConstantNode'
    isConstantNode: true
    // eslint-disable-next-line @typescript-eslint/no-explicit-any
    value: TValue
  }

  interface ConstantNodeCtor {
    new <TValue extends string | number = string>(
      value: TValue
    ): ConstantNode<TValue>
  }

  interface FunctionAssignmentNode<TExpr extends MathNode = MathNode>
    extends MathNode {
    type: 'FunctionAssignmentNode'
    isFunctionAssignmentNode: true
    name: string
    params: string[]
    expr: TExpr
  }
  interface FunctionAssignmentNodeCtor {
    new <TExpr extends MathNode = MathNode>(
      name: string,
      params: string[],
      expr: TExpr
    ): FunctionAssignmentNode<TExpr>
  }

  interface FunctionNode<
    TFn = SymbolNode,
    TArgs extends MathNode[] = MathNode[]
  > extends MathNode {
    type: 'FunctionNode'
    isFunctionNode: true
    fn: TFn
    args: TArgs
  }
  interface FunctionNodeCtor {
    new <TFn = SymbolNode, TArgs extends MathNode[] = MathNode[]>(
      fn: TFn,
      args: TArgs
    ): FunctionNode<TFn, TArgs>
    // eslint-disable-next-line @typescript-eslint/no-explicit-any
    onUndefinedFunction: (name: string) => any
  }

  interface IndexNode<TDims extends MathNode[] = MathNode[]> extends MathNode {
    type: 'IndexNode'
    isIndexNode: true
    dimensions: TDims
    dotNotation: boolean
  }
  interface IndexNodeCtor {
    new <TDims extends MathNode[] = MathNode[]>(dimensions: TDims): IndexNode
    new <TDims extends MathNode[] = MathNode[]>(
      dimensions: TDims,
      dotNotation: boolean
    ): IndexNode<TDims>
  }

  interface ObjectNode<
    TProps extends Record<string, MathNode> = Record<string, MathNode>
  > extends MathNode {
    type: 'ObjectNode'
    isObjectNode: true
    properties: TProps
  }
  interface ObjectNodeCtor {
    new <TProps extends Record<string, MathNode> = Record<string, MathNode>>(
      properties: TProps
    ): ObjectNode<TProps>
  }

  type OperatorNodeMap = {
    xor: 'xor'
    and: 'and'
    or: 'or'
    bitOr: '|'
    bitXor: '^|'
    bitAnd: '&'
    equal: '=='
    unequal: '!='
    smaller: '<'
    larger: '>'
    smallerEq: '<='
    largerEq: '>='
    leftShift: '<<'
    rightArithShift: '>>'
    rightLogShift: '>>>'
    to: 'to'
    add: '+'
    subtract: '-'
    multiply: '*'
    divide: '/'
    dotMultiply: '.*'
    dotDivide: './'
    mod: 'mod'
    unaryPlus: '+'
    unaryMinus: '-'
    bitNot: '~'
    not: 'not'
    pow: '^'
    dotPow: '.^'
    factorial: '!'
  }

  type OperatorNodeOp = OperatorNodeMap[keyof OperatorNodeMap]
  type OperatorNodeFn = keyof OperatorNodeMap

  interface OperatorNode<
    TOp extends OperatorNodeMap[TFn] = never,
    TFn extends OperatorNodeFn = never,
    TArgs extends MathNode[] = MathNode[]
  > extends MathNode {
    type: 'OperatorNode'
    isOperatorNode: true
    op: TOp
    fn: TFn
    args: TArgs
    implicit: boolean
    isUnary(): boolean
    isBinary(): boolean
  }

  interface OperatorNodeCtor extends MathNode {
    new <
      TOp extends OperatorNodeMap[TFn],
      TFn extends OperatorNodeFn,
      TArgs extends MathNode[]
    >(
      op: TOp,
      fn: TFn,
      args: TArgs,
      implicit?: boolean
    ): OperatorNode<TOp, TFn, TArgs>
  }
  interface ParenthesisNode<TContent extends MathNode = MathNode>
    extends MathNode {
    type: 'ParenthesisNode'
    isParenthesisNode: true
    content: TContent
  }
  interface ParenthesisNodeCtor {
    new <TContent extends MathNode>(
      content: TContent
    ): ParenthesisNode<TContent>
  }

  interface RangeNode<
    TStart extends MathNode = MathNode,
    TEnd extends MathNode = MathNode,
    TStep extends MathNode = MathNode
  > extends MathNode {
    type: 'RangeNode'
    isRangeNode: true
    start: TStart
    end: TEnd
    step: TStep | null
  }
  interface RangeNodeCtor {
    new <
      TStart extends MathNode = MathNode,
      TEnd extends MathNode = MathNode,
      TStep extends MathNode = MathNode
    >(
      start: TStart,
      end: TEnd,
      step?: TStep
    ): RangeNode<TStart, TEnd, TStep>
  }

  interface RelationalNode<TParams extends MathNode[] = MathNode[]>
    extends MathNode {
    type: 'RelationalNode'
    isRelationalNode: true
    conditionals: string[]
    params: TParams
  }
  interface RelationalNodeCtor {
    new <TParams extends MathNode[] = MathNode[]>(
      conditionals: string[],
      params: TParams
    ): RelationalNode<TParams>
  }

  interface SymbolNode extends MathNode {
    type: 'SymbolNode'
    isSymbolNode: true
    name: string
  }
  interface SymbolNodeCtor {
    new (name: string): SymbolNode
    // eslint-disable-next-line @typescript-eslint/no-explicit-any
    onUndefinedSymbol: (name: string) => any
  }

  /**
   * @deprecated since version 11.3. Prefer `MathNode` instead
   */
  type MathNodeCommon = MathNode

  type MathJsFunctionName = keyof MathJsStatic

  interface LUDecomposition {
    L: MathCollection
    U: MathCollection
    p: number[]
  }

  interface SLUDecomposition extends LUDecomposition {
    q: number[]
  }

  interface QRDecomposition {
    Q: MathCollection
    R: MathCollection
  }

  interface SchurDecomposition {
    U: MathCollection
    T: MathCollection
  }

  interface FractionDefinition {
    a: number
    b: number
  }

  interface MathJsStatic extends FactoryDependencies {
    e: number
    pi: number
    i: number
    Infinity: number
    LN2: number
    LN10: number
    LOG2E: number
    LOG10E: number
    NaN: number
    phi: number
    SQRT1_2: number
    SQRT2: number
    tau: number

    // Class-like constructors
    Node: NodeCtor
    AccessorNode: AccessorNodeCtor
    ArrayNode: ArrayNodeCtor
    AssignmentNode: AssignmentNodeCtor
    BlockNode: BlockNodeCtor
    ConditionalNode: ConditionalNodeCtor
    ConstantNode: ConstantNodeCtor
    FunctionAssignmentNode: FunctionAssignmentNodeCtor
    FunctionNode: FunctionNodeCtor
    IndexNode: IndexNodeCtor
    ObjectNode: ObjectNodeCtor
    OperatorNode: OperatorNodeCtor
    ParenthesisNode: ParenthesisNodeCtor
    RangeNode: RangeNodeCtor
    RelationalNode: RelationalNodeCtor
    SymbolNode: SymbolNodeCtor

    Matrix: MatrixCtor

    /**
     * If null were to be included in this interface, it would be
     * auto-suggested as an import in VSCode. This causes issues because
     * `null` is not a valid label.
     *
     * @see https://github.com/josdejong/mathjs/issues/2019
     */
    // null: number;

    // eslint-disable-next-line @typescript-eslint/no-explicit-any
    uninitialized: any
    version: string

    expression: MathNode

    /**
     * Returns reviver function that can be used as reviver in JSON.parse function.
     */
    // eslint-disable-next-line @typescript-eslint/no-explicit-any
    reviver(): (key: any, value: any) => any

    /**
     * Returns replacer function that can be used as replacer in JSON.stringify function.
     */
    // eslint-disable-next-line @typescript-eslint/no-explicit-any
    replacer(): (key: any, value: any) => any

    /*************************************************************************
     * Core functions
     ************************************************************************/

    /**
     * Set configuration options for math.js, and get current options. Will
     * emit a ‘config’ event, with arguments (curr, prev, changes).
     * @param options Available options: {number} epsilon Minimum relative
     * difference between two compared values, used by all comparison
     * functions. {string} matrix A string ‘Matrix’ (default) or ‘Array’.