Validator

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

Custom Types

@typedef {Object} ValidatorInstance
@description - 校验器实例

@typedef {Object} ValidatorExpression
@description - 校验表达式

@prop {*} valOf - 待校验的值
@prop {string} Object.keys(ValidatorExpression without valOf)[0] - 校验方法名称
@prop {*} ValidatorExpression[Object.keys(ValidatorExpression without valOf)[0]] - 校验规则

@typeof {Object} ValidatorExtractedExpression
@description - 解构后的校验表达式

@prop {*} value - 待校验的值
@prop {string} name - 校验方法名称
@prop {*} rule - 校验规则

@typedef {Object} ValidatorAlgorithm
@description - 校验方法定义

@prop {string} name - 校验方法名称

@prop {Function} validate - 作用于待校验值的校验函数
1.该函数在被调用时会依次传入两个参数，待校验的值和使用的校验规则。
2.当该函数的返回值是非空字符串时，该字符串会被作为校验值不合规的错误信息。

@prop {string | Array} valueType - 该校验方法接受的待校验值类型
1.定义为一个可由 Object.toString.call() 返回的固定类型时(如 "Number"、"String" 等),
  代表该校验方法只接受固定类型待校验值。
2.定义为由固定类型构成的数组时(如 ["Number", "String"])，代表该校验方法接受在类型范围内的待校验值。
3.定义为 "*" 号时，代表该校验方法接受任何类型的待校验值。
4.当应用该校验方法的校验表达式待校验值类型不匹配要求时，validate 函数不会被调用。

@prop {Function} [validateRule] - 作用于校验规则的校验函数
1.该函数在被调用时会传入待校验的校验规则。
2.当该函数的返回值是非空字符串时，该字符串会被作为校验规则不合规的错误信息。

@prop {string | Array} [ruleType] - 该校验方法接受的校验规则类型
1.定义为一个可由 Object.toString.call() 返回的固定类型时(如 "Number"、"String" 等),
  代表该校验方法只接受固定类型校验规则。
2.定义为由固定类型构成的数组时(如 ["Number", "String"])，代表该校验方法接受在类型范围内的校验规则。
3.定义为 "*" 号时，代表该校验方法接受任何类型的校验规则。
4.当应用该校验方法的校验表达式中校验规则的类型不匹配要求时，validateRule 函数和 validate 函数不会被调用。
5.当未定义时，代表该校验方法无需输入任何校验规则，validateRule 函数不会被调用。

@prop {number} [priority = 0] - 校验方法权重，影响校验表达式排序，权重值越大，排序越靠前。

Exception Types

@type {ExceptionInstance}
@description - 校验方法命名冲突
@prop {string} type = "VALIDATOR_CONFLICTED_NAME"
@prop {string} [name = type]
@prop {Object} [data = {}]
@prop {string} [message]

@type {ExceptionInstance}
@description - 不支持的校验表达式
@prop {string} type = "VALIDATOR_UNSUPPORTED_VALIDATION"
@prop {string} [name = type]
@prop {Object} [data = {}]
@prop {string} [message]

@type {ExceptionInstance}
@description - 不支持校验表达式中的校验规则
@prop {string} type = "VALIDATOR_UNSUPPORTED_VALIDATION_RULE"
@prop {string} [name = type]
@prop {Object} [data = {}]
@prop {string} [message]

@type {ExceptionInstance}
@description - 不支持校验表达式中的校验规则类型
@prop {string} type = "VALIDATOR_UNSUPPORTED_VALIDATION_RULE_TYPE"
@prop {string} [name = type]
@prop {Object} [data = {}]
@prop {string} [message]

@type {ExceptionInstance}
@description - 校验表达式校验未通过
@prop {string} type = "VALIDATOR_VALIDATION_FAILED"
@prop {string} [name = type]
@prop {Object} [data = {}]
@prop {string} [message]

Builtin Algorithms

@type {ValidatorAlgorithm}
@description - 内置数据类型校验方法

@prop {string} name = "dataType"
@prop {Function} validate - 验证待校验值是否是校验规则指定的数据类型
@prop {string} valueType = "*"
@prop {Array} ruleType = ["String", "Array"]
@prop {number} priority = 0

@example - 在校验表达式中应用
{valOf: 123, dataType: "Number"} // 校验通过
{valOf: 123, dataType: ["String", "Boolean"]} // 校验不通过

@type {ValidatorAlgorithm}
@description - 内置等于校验方法

@prop {string} name = "equalTo"
@prop {Function} validate - 验证待校验值是否等于校验规则指定的值
@prop {string} valueType = "*"
@prop {Function} validateRule - 确保校验规则不为空
@prop {Array} ruleType = "*"
@prop {number} priority = 0

@example - 在校验表达式中应用
{valOf: [1, {val: 2}], equalTo: [1, {val: 2}]} // 校验通过
{valOf: 123, equalTo: "123"} // 校验不通过

@type {ValidatorAlgorithm}
@description - 内置是整数校验方法

@prop {string} name = "isInteger"
@prop {Function} validate - 验证待校验值是否为整数
@prop {string} valueType = "Number"
@prop {number} priority = 0

@example - 在校验表达式中应用
{valOf: 1, isInteger: true} // 校验通过
{valOf: 1.1, isInteger: true} // 校验不通过

@type {ValidatorAlgorithm}
@description - 内置最大长度校验方法

@prop {string} name = "maxLength"
@prop {Function} validate - 验证待校验值长度是否小于等于校验规则指定的最大值
@prop {string} valueType = ["String", "Array"]
@prop {Function} validateRule - 确保校验规则是正整数
@prop {Array} ruleType = "Number"
@prop {number} priority = 0

@example - 在校验表达式中应用
{valOf: "Hello", maxLength: 100} // 校验通过
{valOf: [1, 2, 3], maxLength: 2} // 校验不通过

@type {ValidatorAlgorithm}
@description - 内置非空校验方法

@prop {string} name = "presence"
@prop {Function} validate - 验证待校验值是否不为空
@prop {string} valueType = "*"
@prop {number} priority = 1

@example - 在校验表达式中应用
{valOf: [null, undefined, NaN], presence: true} // 校验通过
{valOf: [], presence: true} // 校验不通过
{valOf: {}, presence: true} // 校验不通过
{valOf: ' ', presence: true} // 校验不通过
{valOf: undefined, presence: true} // 校验不通过

@type {ValidatorAlgorithm}
@description - 内置格式校验方法

@prop {string} name = "withFormat"
@prop {Function} validate - 验证待校验值是否符合校验规则指定的格式
@prop {string} valueType = "String"
@prop {Function} validateRule - 确保校验规则是正则表达式或 "//" 包裹的字符串
@prop {Array} ruleType = ["RegExp", "String"]
@prop {number} priority = 0

@example - 在校验表达式中应用
{valOf: "abc", withFormat: "/^abc$/"} // 校验通过
{valOf: "def", withFormat: "/^abc$/"} // 校验不通过

Class Methods

.create()

创建一个校验器实例。

// Validator.create()
// @returns {ValidatorInstance} - 返回一个已安装内置校验方法的校验器实例

// @example - 创建一个校验器实例
const validator = Validator.create()

Instance Methods

#combineValidation()

将一个解构后的校验表达式聚合。

// validator#combineValidation(extractedExpression)
// @param {ValidatorExtractedExpression} extractedExpression
// @returns {ValidatorExpression}
// 1.如果入参数不含 value 属性，则返回的表达式不含 valOf 属性。
// 2.如果入参不含 name 属性，则返回的表达式不含校验方法名及校验规则。

// @example - returns {valOf: "Hello", maxLength: 10}
validator.combineValidation({name: "maxLength", rule: 10, value: "Hello"})
// @example - returns {maxLength: 10}
validator.combineValidation({name: "maxLength", rule: 10})
// @example -returns {valOf: "Hello"}
validator.combineValidation({value: "Hello"})

#error()

执行校验表达式，如校验未通过并返回错误信息。

// validator#error(expression)
// @param {ValidatorExpression} expression
// @returns {null | ExceptionInstance}
// 1.如无错误返回 null。
// 2.如有错误返回一个 ExceptionInstance，其类型为 VALIDATOR_VALIDATION_FAILED 。

// @example - returns null
validator.error({valOf: 1, dataType: "Number"})
// @example - returns an ExceptionInstance
validator.error({valOf: 1, dataType: "String"}) // Invalid value.
validator.error({valOf: 1, maxLength: 10}) // Invalid value type.
validator.error({valOf: "Hello", maxLength: -10}) // Invalid rule.
validator.error({valOf: "Hello", maxLength: "10"}) // Invalid rule type.
validator.error({valOf: 1, unknown: "String"}) // Uninstalled algorithm.

#extractValidation()

解构一个校验表达式。

// validator#extractValidation(expression)
// @param {ValidatorExpression} expression
// @returns {ValidatorExtractedExpression}

// @example - returns {name: "maxLength", rule: 10, value: "Hello"}
validator.extractValidation({valOf: "Hello", maxLength: 10})
// @example - returns {name: "maxLength", rule: 10, value: undefined}
validator.extractValidation({maxLength: 10})
// @example - returns {name: undefined, rule: undefined, value: "Hello"}
validator.extractValidation({valOf: "Hello"})

#for()

查找所有支持某数据类型校验值的校验方法。

// validator#for(valueType, options)
// @param {string} [valueType = "*"] - 一个数据类型，如 "String"、"Number" 等。
// @param {Object} [options = {}]
// @prop {string | Array} [options.except] - 需从结果中过滤掉的校验方法名称。
// @returns {ValidatorAlgorithm[] | null}

// @examples
validator.for("String") // ValidatorAlgorithm[]
validator.for("UnknownDataType") // null

#get()

按名称查找校验方法。

// validator#get(algorithmName)
// @param {string} algorithmName - 校验方法名称
// @returns {ValidatorAlgorithm | null}

// @examples
validator.get("maxLength") // ValidatorAlgorithm
validator.get("uninstalled") // null

#install()

注册一个校验方法。

// validator#install(algorithm)
// @param {ValidatorAlgorithm} algorithm
// @returns {undefined}

// @example
validator.install({
  name: "customLessThan",
  ruleType: "Number",
  valueType: "Number",
  validate (value, rule) {
    if (value >= rule) {
      return `Must be less than ${rule}.`
    }
  }
})
// @example
validator.install({
  priority: 1,
  name: "customTruthy",
  valueType: "*",
  validate (value) {
    if (!value) {
      return 'Must be less truthy.'
    }
  }
})

#isSupported()

判断校验表达式中的校验方法、校验规则是否被支持。

// validator#isSupported(expression, options)
// @param {ValidatorExpression} expression
// @param {Object} [options = {}]
// @prop {boolean} [options.strict = true] - 当为 false 时，只判断校验方法是否被支持。
// @returns {boolean}

// @examples
validator.isSupported({valOf: "Hello", maxLength: 10}) // true
validator.isSupported({valOf: "Hello", maxLength: -10}) // false
validator.isSupported({valOf: "Hello", maxLength: "10"}) // false
validator.isSupported({valOf: 1, unknown: "String"}) // false

#isValid()

执行校验表达式，判断校验是否通过。

// validator#isValid(expression)
// @param {ValidatorExpression} expression
// @returns {boolean}

// @examples
validator.isValid({valOf: 1, dataType: "Number"}) // true
validator.isValid({valOf: 1, dataType: "String"}) // false
validator.isValid({valOf: 1, maxLength: 10}) // false
validator.isValid({valOf: "Hello", maxLength: -10}) // false
validator.isValid({valOf: "Hello", maxLength: "10"}) // false
validator.isValid({valOf: 1, unknown: "String"}) // false

#isntSupported()

判断校验表达式中的校验方法、校验规则是否不被支持。

// validator#isSupported(expression, options)
// @param {ValidatorExpression} expression
// @param {Object} [options = {}]
// @prop {boolean} [options.strict = true] - 当为 false 时，只判断校验方法是否被支持。
// @returns {boolean}

// @examples
validator.isntSupported({valOf: "Hello", maxLength: 10}) // false
validator.isntSupported({valOf: "Hello", maxLength: -10}) // true
validator.isntSupported({valOf: "Hello", maxLength: "10"}) // true
validator.isntSupported({valOf: 1, unknown: "String"}) // true

#isntValid()

执行校验表达式，判断校验是否未通过。

// validator#isntValid(expression)
// @param {ValidatorExpression} expression
// @returns {boolean}

// @examples
validator.isntValid({valOf: 1, dataType: "Number"}) // false
validator.isntValid({valOf: 1, dataType: "String"}) // true
validator.isntValid({valOf: 1, maxLength: 10}) // true
validator.isntValid({valOf: "Hello", maxLength: -10}) // true
validator.isntValid({valOf: "Hello", maxLength: "10"}) // true
validator.isntValid({valOf: 1, unknown: "String"}) // true

#mustbeSupported()

对校验表达式中不被支持的校验方法、校验规则抛出异常。

// validator#mustbeSupported(expression, options)
// @param {ValidatorExpression} expression
// @param {Object} [options = {}]
// @prop {boolean} [options.strict = true] - 当为 false 时，只判断校验方法是否被支持。
// @returns {undefined}

// @example - Throws a VALIDATOR_UNSUPPORTED_VALIDATION_RULE exception.
validator.mustbeSupported({valOf: "Hello", maxLength: -10})
// @example - Throws a VALIDATOR_UNSUPPORTED_VALIDATION_RULE_TYPE exception.
validator.mustbeSupported({valOf: "Hello", maxLength: "10"})
// @example - Throws a VALIDATOR_UNSUPPORTED_VALIDATION exception.
validator.mustbeSupported({valOf: 1, unknown: "String"})

#sort()

按权重排序多个校验表达式。权重值越大，排序结果越靠前。如果待排序数组内包含非校验表达式元素，则该元素权重值按 0 排序。

// validator#sort(expressions)
// @param {ValidatorExpression[]} expressions
// @returns {ValidatorExpression[]}

// @example
validator.install({
  name: "customLessThan",
  ruleType: "Number",
  valueType: "Number",
  validate (value, rule) {
    if (value >= rule) {
      return `Must be less than ${rule}.`
    }
  }
})

validator.install({
  priority: 1,
  name: "customTruthy",
  valueType: "*",
  validate (value) {
    if (!value) {
      return 'Must be less truthy.'
    }
  }
})

// @returns -> [{customTruthy: true}, {customLessThan: 2}, function() {}]
validator.sort([{customLessThan: 2}, function() {}, {customTruthy: true}])

#uninstall()

移除一个已注册的校验方法。

// validator#uninstall(algorithmName)
// @param {string} algorithmName - 一个已注册的校验方法 name
// @returns {undefined}

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