schema-dsl 2.3.0

package/lib/validators/CustomKeywords.js

@@ -0,0 +1,203 @@
+/**
+ * 自定义JSON Schema关键字
+ *
+ * 扩展ajv支持自定义验证关键字
+ *
+ * @module lib/validators/CustomKeywords
+ * @version 1.0.0
+ */
+
+const Locale = require('../core/Locale');
+
+/**
+ * 自定义关键字集合
+ * @class CustomKeywords
+ */
+class CustomKeywords {
+  /**
+   * 注册所有自定义关键字到ajv实例
+   * @static
+   * @param {Ajv} ajv - ajv实例
+   */
+  static registerAll(ajv) {
+    this.registerRegexKeyword(ajv);
+    this.registerFunctionKeyword(ajv);
+    this.registerRangeKeyword(ajv);
+    this.registerCustomValidatorsKeyword(ajv);
+    this.registerMetadataKeywords(ajv);
+  }
+
+  /**
+   * 注册元数据关键字（_label, _customMessages等）
+   * @static
+   * @param {Ajv} ajv - ajv实例
+   */
+  static registerMetadataKeywords(ajv) {
+    // _label: 字段标签
+    ajv.addKeyword({
+      keyword: '_label',
+      metaSchema: { type: 'string' }
+    });
+
+    // _customMessages: 自定义错误消息
+    ajv.addKeyword({
+      keyword: '_customMessages',
+      metaSchema: { type: 'object' }
+    });
+
+    // _description: 描述
+    ajv.addKeyword({
+      keyword: '_description',
+      metaSchema: { type: 'string' }
+    });
+
+    // _whenConditions: 条件验证
+    ajv.addKeyword({
+      keyword: '_whenConditions',
+      metaSchema: { type: 'array' }
+    });
+
+    // _required: 内部使用的必填标记
+    ajv.addKeyword({
+      keyword: '_required',
+      metaSchema: { type: 'boolean' }
+    });
+  }
+
+  /**
+   * 注册 _customValidators 关键字（SchemaIO 内部使用）
+   * @static
+   * @param {Ajv} ajv - ajv实例
+   */
+  static registerCustomValidatorsKeyword(ajv) {
+    ajv.addKeyword({
+      keyword: '_customValidators',
+      validate: function validate(validators, data) {
+        if (!Array.isArray(validators)) return true;
+
+        for (const validator of validators) {
+          try {
+            const result = validator(data);
+
+            // 处理 Promise (异步验证)
+            if (result instanceof Promise) {
+              // ajv 默认不支持同步验证中的异步操作
+              // 这里我们只能抛出错误提示
+              // 真正的异步支持需要 Validator.validateAsync
+              throw new Error(Locale.getMessage('ASYNC_VALIDATION_NOT_SUPPORTED'));
+            }
+
+            // 处理返回值
+            if (result === false) {
+              validate.errors = [{ message: Locale.getMessage('CUSTOM_VALIDATION_FAILED') }];
+              return false;
+            }
+            if (typeof result === 'string') {
+              validate.errors = [{ message: result }];
+              return false;
+            }
+            if (result && typeof result === 'object' && result.error) {
+              validate.errors = [{ message: result.message || Locale.getMessage('CUSTOM_VALIDATION_FAILED') }];
+              return false;
+            }
+          } catch (error) {
+            validate.errors = [{ message: error.message }];
+            return false;
+          }
+        }
+        return true;
+      },
+      errors: true
+    });
+  }
+
+  /**
+   * 注册regex关键字（正则验证）
+   * @static
+   * @param {Ajv} ajv - ajv实例
+   */
+  static registerRegexKeyword(ajv) {
+    ajv.addKeyword({
+      keyword: 'regex',
+      type: 'string',
+      schemaType: 'string',
+      validate: function validate(schema, data) {
+        try {
+          const regex = new RegExp(schema);
+          return regex.test(data);
+        } catch (error) {
+          validate.errors = [{ message: `Invalid regex: ${error.message}` }];
+          return false;
+        }
+      },
+      errors: true
+    });
+  }
+
+  /**
+   * 注册function关键字（自定义函数验证）
+   * @static
+   * @param {Ajv} ajv - ajv实例
+   */
+  static registerFunctionKeyword(ajv) {
+    ajv.addKeyword({
+      keyword: 'validate',
+      validate: function validate(schema, data) {
+        if (typeof schema !== 'function') {
+          validate.errors = [{ message: Locale.getMessage('VALIDATE_MUST_BE_FUNCTION') }];
+          return false;
+        }
+
+        try {
+          const result = schema(data);
+          if (typeof result === 'boolean') {
+            return result;
+          }
+          if (result && typeof result.valid === 'boolean') {
+            if (!result.valid && result.message) {
+              validate.errors = [{ message: result.message }];
+            }
+            return result.valid;
+          }
+          return true;
+        } catch (error) {
+          validate.errors = [{ message: error.message }];
+          return false;
+        }
+      },
+      errors: true
+    });
+  }
+
+  /**
+   * 注册range关键字（数值范围验证）
+   * @static
+   * @param {Ajv} ajv - ajv实例
+   */
+  static registerRangeKeyword(ajv) {
+    ajv.addKeyword({
+      keyword: 'range',
+      type: 'number',
+      schemaType: 'object',
+      validate: function validate(schema, data) {
+        const { min, max } = schema;
+
+        if (min !== undefined && data < min) {
+          validate.errors = [{ message: `must be >= ${min}` }];
+          return false;
+        }
+
+        if (max !== undefined && data > max) {
+          validate.errors = [{ message: `must be <= ${max}` }];
+          return false;
+        }
+
+        return true;
+      },
+      errors: true
+    });
+  }
+}
+
+module.exports = CustomKeywords;
+

package/lib/validators/index.js

@@ -0,0 +1,11 @@
+/**
+ * Validators - 验证器统一导出
+ * @module lib/validators
+ */
+
+const CustomKeywords = require('./CustomKeywords');
+
+module.exports = {
+  CustomKeywords
+};
+

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "schema-dsl",
+  "version": "2.3.0",
+  "description": "简洁强大的JSON Schema验证库 - DSL语法 + String扩展 + 便捷validate",
+  "main": "index.js",
+  "exports": {
+    ".": {
+      "require": "./index.js",
+      "import": "./index.mjs",
+      "types": "./index.d.ts"
+    }
+  },
+  "scripts": {
+    "test": "mocha test/unit/**/*.test.js",
+    "test:integration": "mocha test/integration/**/*.test.js",
+    "test:all": "mocha test/**/*.test.js",
+    "coverage": "nyc npm test",
+    "lint": "eslint lib/**/*.js",
+    "example": "node examples/dsl-style.js"
+  },
+  "keywords": [
+    "schema",
+    "validation",
+    "validator",
+    "dsl",
+    "json-schema",
+    "data-validation",
+    "form-validation",
+    "mongodb",
+    "mysql",
+    "postgresql",
+    "database-schema",
+    "i18n",
+    "internationalization",
+    "typescript",
+    "express",
+    "koa",
+    "fastify",
+    "rest-api",
+    "input-validation"
+  ],
+  "author": "rocky <rockyshi1993@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vextjs/schema-dsl.git"
+  },
+  "bugs": {
+    "url": "https://github.com/vextjs/schema-dsl/issues"
+  },
+  "homepage": "https://github.com/vextjs/schema-dsl#readme",
+  "engines": {
+    "node": ">=12.0.0"
+  },
+  "dependencies": {
+    "ajv": "^8.17.1",
+    "ajv-formats": "^2.1.1"
+  },
+  "devDependencies": {
+    "chai": "^4.5.0",
+    "eslint": "^8.57.1",
+    "joi": "^18.0.2",
+    "mocha": "^10.8.2",
+    "monsqlize": "^1.0.1",
+    "nyc": "^15.1.0",
+    "sinon": "^17.0.1",
+    "yup": "^1.7.1",
+    "zod": "^4.2.1"
+  }
+}

package/plugins/custom-format.js

@@ -0,0 +1,101 @@
+/**
+ * 示例插件：自定义格式验证
+ * 
+ * @description 添加常用的格式验证（手机号、邮编、身份证等）
+ * @module plugins/custom-format
+ */
+
+module.exports = {
+    name: 'custom-format',
+    version: '1.0.0',
+    description: '自定义格式验证插件',
+
+    install(schemaDsl, options = {}, context) {
+        // 获取默认 validator 实例
+        const validator = schemaDsl.getDefaultValidator();
+        const ajv = validator.getAjv();
+
+        // 添加自定义格式
+        this.addCustomFormats(ajv);
+
+        console.log('[Plugin] custom-format installed');
+    },
+
+    uninstall(schemaDsl, context) {
+        console.log('[Plugin] custom-format uninstalled');
+    },
+
+    addCustomFormats(ajv) {
+        // 1. 中国手机号
+        ajv.addFormat('phone-cn', {
+            validate: /^1[3-9]\d{9}$/
+        });
+
+        // 2. 中国邮政编码
+        ajv.addFormat('postal-code-cn', {
+            validate: /^\d{6}$/
+        });
+
+        // 3. IPv4 地址
+        ajv.addFormat('ipv4', {
+            validate: /^((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.){3}(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)$/
+        });
+
+        // 4. 微信号
+        ajv.addFormat('wechat', {
+            validate: /^[a-zA-Z][-_a-zA-Z0-9]{5,19}$/
+        });
+
+        // 5. QQ号
+        ajv.addFormat('qq', {
+            validate: /^[1-9][0-9]{4,10}$/
+        });
+
+        // 6. 银行卡号（简单验证）
+        ajv.addFormat('bank-card', {
+            validate: (value) => {
+                if (!/^\d{16,19}$/.test(value)) return false;
+
+                // Luhn 算法验证
+                let sum = 0;
+                let shouldDouble = false;
+
+                for (let i = value.length - 1; i >= 0; i--) {
+                    let digit = parseInt(value[i]);
+
+                    if (shouldDouble) {
+                        digit *= 2;
+                        if (digit > 9) digit -= 9;
+                    }
+
+                    sum += digit;
+                    shouldDouble = !shouldDouble;
+                }
+
+                return sum % 10 === 0;
+            }
+        });
+
+        // 7. 车牌号（普通+新能源）
+        ajv.addFormat('license-plate', {
+            validate: /^[京津沪渝冀豫云辽黑湘皖鲁新苏浙赣鄂桂甘晋蒙陕吉闽贵粤青藏川宁琼使领][A-Z][A-HJ-NP-Z0-9]{4,5}[A-HJ-NP-Z0-9挂学警港澳]$/
+        });
+
+        // 8. 统一社会信用代码
+        ajv.addFormat('credit-code', {
+            validate: /^[0-9A-HJ-NPQRTUWXY]{2}\d{6}[0-9A-HJ-NPQRTUWXY]{10}$/
+        });
+
+        // 9. 护照号（中国）
+        ajv.addFormat('passport-cn', {
+            validate: /^[EG]\d{8}$/
+        });
+
+        // 10. 港澳通行证
+        ajv.addFormat('hk-macao-pass', {
+            validate: /^[HM]\d{8,10}$/
+        });
+    }
+};
+
+

package/plugins/custom-validator.js

@@ -0,0 +1,200 @@
+/**
+ * 示例插件：自定义验证器
+ * 
+ * @description 展示如何创建一个自定义验证器插件
+ * @module plugins/custom-validator
+ */
+
+module.exports = {
+    // 插件元信息
+    name: 'custom-validator',
+    version: '1.0.0',
+    description: '自定义验证器插件，添加业务特定的验证规则',
+
+    /**
+     * 插件安装函数
+     * 
+     * @param {Object} schemaDsl - SchemaIO 实例
+     * @param {Object} options - 插件选项
+     * @param {Object} context - 插件上下文
+     */
+    install(schemaDsl, options = {}, context) {
+        // 1. 获取默认 validator 实例
+        const validator = schemaDsl.getDefaultValidator();
+
+        // 2. 添加自定义关键字
+        this.addCustomKeywords(validator);
+
+        // 3. 注册到全局
+        if (!global.__schemaDsl_plugins) {
+            global.__schemaDsl_plugins = {};
+        }
+        global.__schemaDsl_plugins['custom-validator'] = this;
+
+        console.log('[Plugin] custom-validator installed');
+    },
+
+    /**
+     * 插件卸载函数
+     */
+    uninstall(schemaDsl, context) {
+        // 清理全局注册
+        if (global.__schemaDsl_plugins) {
+            delete global.__schemaDsl_plugins['custom-validator'];
+        }
+
+        console.log('[Plugin] custom-validator uninstalled');
+    },
+
+    /**
+     * 添加自定义关键字
+     */
+    addCustomKeywords(validator) {
+        const ajv = validator.getAjv();
+
+        // 示例1: 唯一性验证（需要异步检查数据库）
+        // 检查关键字是否已存在
+        if (!ajv.getKeyword('unique')) {
+            validator.addKeyword('unique', {
+                async: true,
+                type: 'string',
+                validate: async function validateUnique(schema, data, parentSchema, dataPath) {
+                    // schema: { unique: { table: 'users', field: 'email' } }
+                    // data: 实际要验证的值
+
+                    if (!schema) return true;
+
+                    const { table, field } = schema;
+
+                    // 模拟数据库查询
+                    // 实际使用时替换为真实的数据库查询
+                    const exists = false; // await db.query(...)
+
+                    if (exists) {
+                        validateUnique.errors = [{
+                            keyword: 'unique',
+                            message: `${field} already exists in ${table}`,
+                            params: { table, field }
+                        }];
+                        return false;
+                    }
+
+                    return true;
+                }
+            });
+        }
+
+        // 示例2: 密码强度验证
+        if (!ajv.getKeyword('passwordStrength')) {
+            validator.addKeyword('passwordStrength', {
+                type: 'string',
+                validate: function validatePasswordStrength(schema, data) {
+                    if (!schema) return true;
+
+                    // schema: { passwordStrength: 'medium' }
+                    // 强度等级: weak, medium, strong
+
+                    const strength = schema;
+                    const value = data;
+
+                    const rules = {
+                        weak: /^.{6,}$/,
+                        medium: /^(?=.*[a-z])(?=.*[A-Z]).{8,}$/,
+                        strong: /^(?=.*[a-z])(?=.*[A-Z])(?=.*\d).{10,}$/
+                    };
+
+                    const pattern = rules[strength];
+                    if (!pattern) {
+                        return true;
+                    }
+
+                    if (!pattern.test(value)) {
+                        validatePasswordStrength.errors = [{
+                            keyword: 'passwordStrength',
+                            message: `Password does not meet ${strength} strength requirements`,
+                            params: { strength }
+                        }];
+                        return false;
+                    }
+
+                    return true;
+                }
+            });
+        }
+
+        // 示例3: 中国身份证号验证
+        if (!ajv.getKeyword('idCard')) {
+            validator.addKeyword('idCard', {
+                type: 'string',
+                validate: function validateIdCard(schema, data) {
+                    if (!schema) return true;
+
+                    const value = data;
+
+                    // 身份证号正则
+                    const pattern = /^[1-9]\d{5}(19|20)\d{2}(0[1-9]|1[0-2])(0[1-9]|[12]\d|3[01])\d{3}[\dXx]$/;
+
+                    if (!pattern.test(value)) {
+                        validateIdCard.errors = [{
+                            keyword: 'idCard',
+                            message: 'Invalid ID card number',
+                            params: {}
+                        }];
+                        return false;
+                    }
+
+                    // 验证校验码
+                    if (!this._validateIdCardChecksum(value)) {
+                        validateIdCard.errors = [{
+                            keyword: 'idCard',
+                            message: 'Invalid ID card checksum',
+                            params: {}
+                        }];
+                        return false;
+                    }
+
+                    return true;
+                }
+            });
+        }
+    },
+
+    /**
+     * 验证身份证校验码
+     * @private
+     */
+    _validateIdCardChecksum(idCard) {
+        const weights = [7, 9, 10, 5, 8, 4, 2, 1, 6, 3, 7, 9, 10, 5, 8, 4, 2];
+        const checksums = ['1', '0', 'X', '9', '8', '7', '6', '5', '4', '3', '2'];
+
+        let sum = 0;
+        for (let i = 0; i < 17; i++) {
+            sum += parseInt(idCard[i]) * weights[i];
+        }
+
+        const checksum = checksums[sum % 11];
+        return idCard[17].toUpperCase() === checksum;
+    },
+
+    /**
+     * 生命周期钩子
+     */
+    hooks: {
+        onBeforeValidate(schema, data) {
+            // 验证前钩子
+            // 可以在这里修改 schema 或 data
+        },
+
+        onAfterValidate(result) {
+            // 验证后钩子
+            // 可以在这里修改验证结果
+        },
+
+        onError(error, context) {
+            // 错误处理钩子
+            console.error('[custom-validator] Error:', error.message);
+        }
+    }
+};
+
+