Calculator

// @namespace Calculator
import { Calculator } from 'rcfm'

@typedef {Object} CalculatorInstance
@description - 计算器实例

@typedef {Object} CalculatorExpression
@description - 计算表达式

@prop {string} Object.keys(CalculatorExpression)[0] - 计算方法名称
@prop {Array|*} CalculatorExpression[Object.keys(CalculatorExpression)[0]] - 待计算参数

@typedef {Object} CalculatorAlgorithm
@description - 计算方法定义

@prop {string} name - 计算方法名称
@prop {Function} calculate - 返回计算结果的计算函数

@prop {number | Array} argumentSize - 该计算方法接受的参数数量范围
1.定义为正整数时，代表该计算方法只接受固定数量参数。
2.定义为包含两个正整数的数组时(数组下标为1的元素也可以是Infinity),
  代表该计算方法接受在二者范围内的参数数量。
3.当应用该计算方法的计算表达式参数数量少于最小数量要求时，calculate 函数不会被调用。
4.当应用该计算方法的计算表达式参数数量大于最大数量要求时，多余的参数会被忽略。

@prop {string | Array} argumentType - 该计算方法接受的参数类型
1.定义为一个可由 Object.toString.call() 返回的固定类型时(如 "Number"、"String" 等),
  代表该计算方法只接受固定类型参数。
2.定义为由固定类型构成的数组时(如 ["Number", "String"])，代表该计算方法接受在类型范围内的参数。
3.定义为由固定类型构成的数组嵌套而成的数组时(如 [["Number"], ["Number", "String"]])，
  代表该计算方法接受的参数须按照下标位置匹配类型范围（超出时按最大下标匹配）。
4.定义为 "*" 号时，代表该计算方法接受任何类型的参数。
5.当应用该计算方法的计算表达式参数类型不匹配要求时，calculate 函数不会被调用。

@type {ExceptionInstance}
@description - 计算方法命名冲突

@prop {string} type = "CALCULATOR_CONFLICTED_NAME"
@prop {string} [name = type]
@prop {Object} [data = {}]
@prop {string} [message]

@type {ExceptionInstance}
@description - 计算方法参数类型定义不合规

@prop {string} type = "CALCULATOR_INVALID_ARGUMENT_TYPE"
@prop {string} [name = type]
@prop {Object} [data = {}]
@prop {string} [message]

@type {ExceptionInstance}
@description - 计算方法参数数量定义不合规

@prop {string} type = "CALCULATOR_INVALID_ARGUMENT_SIZE"
@prop {string} [name = type]
@prop {Object} [data = {}]
@prop {string} [message]

@type {ExceptionInstance}
@description - 不支持的计算表达式

@prop {string} type = "CALCULATOR_UNSUPPORTED_CALCULATION"
@prop {string} [name = type]
@prop {Object} [data = {}]
@prop {string} [message]

@type {CalculatorAlgorithm}
@description - 内置求和算法

@prop {string} name = "add"
@prop {Array} argumentSize = [2, Infinity]
@prop {string} argumentType = "Number"

@example - 在计算表达式中应用
{add: [1, 2, 3]}

@type {CalculatorAlgorithm}
@description - 内置求差算法

@prop {string} name = "minus"
@prop {Array} argumentSize = [2, Infinity]
@prop {String} argumentType = "Number"

@example - 在计算表达式中应用
{minus: [6, 3, 2]}

@type {CalculatorAlgorithm}
@description - 内置求积算法

@prop {string} name = "multiple"
@prop {Array} argumentSize = [2, Infinity]
@prop {String} argumentType = "Number"

@example - 在计算表达式中应用
{multiple: [2, 2, 2]}

@type {CalculatorAlgorithm}
@description - 内置求商算法

@prop {string} name = "devide"
@prop {Array} argumentSize = [2, Infinity]
@prop {String} argumentType = "Number"

@example - 在计算表达式中应用
{devide: [8, 2, 2]}

@type {CalculatorAlgorithm}
@description - 内置映射算法

@prop {string} name = "map"
@prop {Array} argumentSize = 1
@prop {String} argumentType = "*"

@example - 在计算表达式中应用
{map: "Map this string."}

// Calculator.create()
// @returns {CalculatorInstance} - 返回一个已安装内置计算方法的计算器实例

// @example - 创建一个计算器实例
const calculator = Calculator.create()

// calculator#calculate(expression)
// @param {CalculatorExpression} expression - 待计算的表达式，可嵌套
// @returns {* | null} - 当计算表达式正确时返回计算结果，否则返回 null

// @example - 计算正确的表达式
calculator.calculate({add: [1, 2]}) // 3
// @example - 计算嵌套的表达式
calculator.calculate({add: [1, {multiple: [1, 2]}]}) // 3
// @example - 计算错误的表达式
calculator.calculate({devide: ["1", 2]}) // null
calculator.calculate({devide: 1}) // null
calculator.calculate({unknown: [1, 2]}) // null

// calculator#install(algorithm)
// @param {CalculatorAlgorithm} algorithm - 计算方法定义
// @returns {undefined}

// @example
calculator.install({
  name: "customAdd",
  argumentSize: [2, Infinity],
  argumentType: ["Number", "String"],
  calculate (...args) {
    return args.reduce((one, two) => one + two)
  }
})

// calculator#isSupported(expression, options)
// @param {CalculatorExpression} expression - 待判断的计算表达式
// @param {Object} [options = {}]
// @prop {boolean} [options.strict = false] - 是否启用严格模式，启用后将校验嵌套的计算表达式
// @returns {boolean}

// @examples
calculator.isSupported({add: [1, 2]}) // true
calculator.isSupported({unknown: [1, 2]}) // false
// @examples
calculator.isSupported({add: [1, {unknown: [1, 2]}]}) // true
calculator.isSupported({add: [1, {unknown: [1, 2]}]}, {strict: true}) // false

// calculator#isntSupported(expression, options)
// @param {CalculatorExpression} expression - 待判断的计算表达式
// @param {Object} [options = {}]
// @prop {boolean} [options.strict = false] - 是否启用严格模式，启用后将校验嵌套的计算表达式
// @returns {boolean}

// @examples
calculator.isntSupported({add: [1, 2]}) // false
calculator.isntSupported({unknown: [1, 2]}) // true
// @examples
calculator.isntSupported({add: [1, {unknown: [1, 2]}]}) // false
calculator.isntSupported({add: [1, {unknown: [1, 2]}]}, {strict: true}) // true

// calculator#mustbeSupported(expression, options)
// @param {CalculatorExpression} expression - 待判断的计算表达式
// @param {Object} [options = {}]
// @prop {boolean} [options.strict = false] - 是否启用严格模式，启用后将校验嵌套的计算表达式
// @returns {undefined}

// @examples
calculator.mustbeSupported({add: [1, 2]})
calculator.mustbeSupported({unknown: [1, 2]}) // Throws a "CALCULATOR_UNSUPPORTED_CALCULATION" exception.
// @examples
calculator.mustbeSupported({add: [1, {unknown: [1, 2]}]})
calculator.mustbeSupported({add: [1, {unknown: [1, 2]}]}, {strict: true}) // Throws a "CALCULATOR_UNSUPPORTED_CALCULATION" exception.

// calculator#uninstall(algorithmName)
// @param {string} algorithmName - 一个已注册的计算方法 name
// @returns {undefined}

// @example
calculator.uninstall('customAdd')