Skip to content

💪 用最少的代码,解决繁琐的事情,专注数据校验

License

Notifications You must be signed in to change notification settings

D-xuanmo/validator

Repository files navigation

Validator

Node.js CI npm bundle size npm bundle size

简介

  • Validator 是数据集验证工具,主打多个规则以管道符模式进行串行校验,常用于表单数据繁琐的校验
  • 用最少的代码,解决繁琐的事情
  • 支持校验规则扩展、单例模式、异步校验、国际化
  • 完善的 TypeScript 类型
  • 规则快速预览: required|email|length:8|between:2,8

安装

# npm
$ npm i @xuanmo/validator

# yarn
$ yarn add @xuanmo/validator

# pnpm
$ pnpm add @xuanmo/validator

使用

import validator from '@xuanmo/validator'

// 默认不注册国际化词条,需要引入国际化词条文件自行注册
import zhCN from '@xuanmo/validator/locale/zh-CN.json'

// 注册国际化词条
validator.localize(zhCN)

// 执行校验
validator
  .validate([
    {
      dataKey: 'name',
      value: 'xuanmo',
      rules: 'required|max:5'
    },
    {
      dataKey: 'age',
      value: 18,
      required: true,
      rules: 'max:8'
    },
    {
      dataKey: 'scope',
      value: '',
      message: '局部校验规则失败',
      validator() {
        return false
      }
    },
    // 以下为矩阵校验示例
    {
      // 需要指定为矩阵校验
      matrix: true,
      // 矩阵对应的 id,整个校验数据唯一
      matrixId: 'matrixId',
      value: {
        columns: [
          {
            dataKey: 'column1',
            label: '矩阵列 1',
            rules: 'required|min_length:9'
          },
          {
            dataKey: 'column2',
            label: '矩阵列 2',
            rules: 'confirmed:@column1'
          }
        ],
        data: [
          {
            rowId: 'a',
            column2: '222value'
          },
          {
            rowId: 'b',
            column1: 22,
            column2: 'xxx'
          }
        ]
      }
    }
  ])
  .then(() => {
    console.log('校验通过')
  })
  .catch((error) => {
    console.log(error)
  })

API

关键词说明

message

  • {#field} 会被替换为当前字段
  • {meta} 具体规则的值
  • ruleParams 多个值通过 , 逗号分隔
// 以 `length` 规则为例,错误信息定义:{#field}长度必须为:{length}
// 最终执行结果被替换为:name长度必须为:5
validator.validate([
  {
    dataKey: 'name',
    value: 'xuanmo',
    rules: 'length:5'
  }
])

validate 执行校验

import validator from '@xuanmo/validator'

validator.validate([
  {
    dataKey: 'name',
    value: 'xuanmo',
    rules: 'length:5|between:2,8'
  },
  {
    dataKey: 'scope',
    value: 'xuanmo',
    // 局部校验规则,优先级最高,不会执行 rules 模式
    validator(value) {
      return false
    }
  }
])

Rule 结构说明

键名 说明 类型
value (必须)当前被校验的数据 unknown
required (非必须)是否必填,与 rules 中的 required 等价 boolean
rules (非必须)校验规则,以管道符分隔,冒号后边的为校验规则值 string
label (非必须)用于覆盖 message {#field} 标识 string
regexp (非必须)正则校验,一般只有全局中无匹配规则时使用 RegExp | string
matrix (非必须)是否为矩阵数据 boolean
matrixId (非必须)矩阵 id string
rowId (非必须)数据每行对应的 id string
message (非必须)校验错误提示信息,权重最高,一般不使用 string
validator (非必须)校验函数权重高于 rules,一般只有全局中无匹配规则时使用 ValidatorHandlerType

TS 类型

/**
 * 执行校验
 * @param data 校验数据
 * @param options
 */
type ValidateType = (
  data: ValidateDataModel,
  options?: {
    // 是否执行全部规则的校验,默认为 true,如果字段较多,存在多个异步校验,不建议开启
    checkAll?: boolean;
  }
) => ValidateReturnType;

校验权重说明

required > regexp > validator > rules

message 字段权重说明

validate.field.message > rule.message

localize 国际化词条注册

import zhCN from '@xuanmo/validator/locale/zh-CN.json'

validator.localize(zhCN)

注册校验规则

extend 单个注册

validator.extend('custom', {
  message: '{#field}自定义校验规则失败:{custom}',
  validator(value, ruleValue) {
    return (value as string).length > +ruleValue!
  }
})

extends 多个规则同时注册

validator.extends({
  regexp: {
    message: '正则校验失败信息',
    regexp: '\\d+'
  },
  custom: {
    message: '{#field}自定义校验规则失败:{custom}',
    // 可返回 Promise<boolean>
    validator(value, ruleValue) {
      return (value as string).length > +ruleValue!
    }
  }
})

rules 内置规则

更多规则可以从 @xuanmo/validator/rules/{type}/*.js 导出进行注册,默认不打包

  • required 必填校验
  • email 邮箱
  • length 长度,示例:length:2
  • min_length 最小长度,示例:min_length:2
  • max_length 最大长度,示例:max_length:2
  • min 最小值,示例:min:5
  • max 最大值,示例:max:5
  • number 数字,包含浮点数、整数
  • float 浮点数
  • integer 整数
  • between 数值区间
  • confirmed 二次确认,如密码场景,示例:confirmed:@target
  • alpha 只能包含字母
  • alpha_num 只能包含字母数字
  • alpha_spaces 只能包含字母空格
  • url URL

单例模式

import { Validator } from '@xuanmo/validator'
import zhCN from '@xuanmo/validator/locale/zh-CN.json'

const validator = new Validator()
validator.localize(zhCN)
// ...

鸣谢

Validator 的成长,离不开前辈的作品

License

  • 本项目基于 MIT 协议,欢迎有兴趣的朋友一起交流
  • Copyright © 2023-PRESENT D-Xuanmo

About

💪 用最少的代码,解决繁琐的事情,专注数据校验

Topics

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published