schema-dsl 1.0.0

package/lib/utils/SchemaUtils.js

@@ -0,0 +1,445 @@
+/**
+ * Schema工具类 v2.0.1
+ *
+ * 提供Schema复用、合并、性能监控等功能
+ */
+
+class SchemaUtils {
+  // ========== Schema复用 ==========
+
+  /**
+   * 创建可复用的Schema片段
+   * @param {Function} factory - Schema工厂函数
+   * @returns {Function} 返回工厂函数
+   *
+   * @example
+   * const emailField = SchemaUtils.reusable(() =>
+   *   'email!'.pattern(/custom/).label('邮箱')
+   * );
+   *
+   * const schema1 = dsl({ email: emailField() });
+   * const schema2 = dsl({ contactEmail: emailField() });
+   */
+  static reusable(factory) {
+    return factory;
+  }
+
+  /**
+   * 创建Schema片段库
+   * @param {Object} fragments - Schema片段对象
+   * @returns {Object} 片段库
+   *
+   * @example
+   * const fields = SchemaUtils.createLibrary({
+   *   email: () => 'email!'.label('邮箱'),
+   *   phone: () => 'string:11!'.phoneNumber('cn').label('手机号'),
+   *   username: () => 'string:3-32!'.username().label('用户名')
+   * });
+   *
+   * const schema = dsl({
+   *   email: fields.email(),
+   *   phone: fields.phone()
+   * });
+   */
+  static createLibrary(fragments) {
+    return fragments;
+  }
+
+  // ========== Schema复用和扩展 ==========
+
+  /**
+   * 扩展Schema（类似继承）
+   * @param {Object} baseSchema - 基础Schema
+   * @param {Object} extensions - 扩展定义
+   * @returns {Object} 扩展后的Schema（支持链式调用）
+   *
+   * @example
+   * const baseUser = dsl({ name: 'string!', email: 'email!' });
+   * const admin = SchemaUtils.extend(baseUser, {
+   *   role: 'admin|superadmin',
+   *   permissions: 'array<string>'
+   * });
+   */
+  static extend(baseSchema, extensions) {
+    const dsl = require('../adapters/DslAdapter');
+    const extensionSchema = typeof extensions === 'function'
+      ? extensions
+      : dsl(extensions);
+
+    // 合并 properties
+    const result = {
+      type: 'object',
+      properties: {},
+      required: []
+    };
+
+    // 复制基础 schema
+    if (baseSchema.properties) {
+      Object.assign(result.properties, baseSchema.properties);
+    }
+    if (baseSchema.required) {
+      result.required = [...baseSchema.required];
+    }
+
+    // 添加扩展
+    if (extensionSchema.properties) {
+      Object.assign(result.properties, extensionSchema.properties);
+    }
+    if (extensionSchema.required) {
+      result.required = [...new Set([...result.required, ...extensionSchema.required])];
+    }
+
+    return this._makeChainable(result);
+  }
+
+  /**
+   * 挑选Schema的部分字段
+   * @param {Object} schema - 原始Schema
+   * @param {string[]} fields - 要挑选的字段
+   * @returns {Object} 新Schema
+   *
+   * @example
+   * const fullUser = dsl({ name: 'string!', email: 'email!', age: 'number' });
+   * const publicUser = SchemaUtils.pick(fullUser, ['name', 'email']);
+   */
+  static pick(schema, fields) {
+    const result = {
+      type: 'object',
+      properties: {},
+      required: []
+    };
+
+    fields.forEach(field => {
+      if (schema.properties && schema.properties[field]) {
+        result.properties[field] = schema.properties[field];
+        if (schema.required && schema.required.includes(field)) {
+          result.required.push(field);
+        }
+      }
+    });
+
+    return this._makeChainable(result);
+  }
+
+  /**
+   * 排除Schema的部分字段
+   * @param {Object} schema - 原始Schema
+   * @param {string[]} fields - 要排除的字段
+   * @returns {Object} 新Schema（支持链式调用）
+   */
+  static omit(schema, fields) {
+    const result = this._clone(schema);
+
+    fields.forEach(field => {
+      if (result.properties) {
+        delete result.properties[field];
+      }
+      if (result.required) {
+        result.required = result.required.filter(f => f !== field);
+      }
+    });
+
+    // 清理空数组
+    if (result.required && result.required.length === 0) {
+      delete result.required;
+    }
+
+    return this._makeChainable(result);
+  }
+
+  // ========== v2.1.0 新增：Schema转换方法（支持链式调用） ==========
+
+  /**
+   * 部分验证：移除必填限制
+   *
+   * @param {Object} schema - 原始Schema
+   * @param {string[]} fields - 要验证的字段（可选，默认全部）
+   * @returns {Object} 新Schema（支持链式调用）
+   *
+   * @example
+   * // 所有字段变为可选
+   * const partialSchema = SchemaUtils.partial(userSchema);
+   *
+   * @example
+   * // 只验证指定字段
+   * const updateSchema = SchemaUtils.partial(userSchema, ['name', 'age']);
+   *
+   * @example
+   * // 链式调用
+   * const patchSchema = SchemaUtils
+   *   .pick(userSchema, ['name', 'age'])
+   *   .partial();
+   */
+  static partial(schema, fields = null) {
+    let result;
+
+    if (fields) {
+      // 只保留指定字段 (pick 已经返回 chainable 对象)
+      result = this.pick(schema, fields);
+      // 提取原始 schema
+      if (result._isChainable) {
+        result = this._extractSchema(result);
+      }
+    } else {
+      result = this._clone(schema);
+    }
+
+    // 移除所有 required
+    delete result.required;
+
+    // 递归处理嵌套对象
+    if (result.properties) {
+      Object.keys(result.properties).forEach(key => {
+        const prop = result.properties[key];
+        if (prop && prop.type === 'object' && prop.required) {
+          delete prop.required;
+        }
+      });
+    }
+
+    return this._makeChainable(result);
+  }
+
+  // ========== 性能监控 ==========
+
+  /**
+   * 创建带性能监控的Validator
+   * @param {Validator} validator - Validator实例
+   * @returns {Validator} 增强的Validator
+   *
+   * @example
+   * const validator = SchemaUtils.withPerformance(new Validator());
+   * const result = validator.validate(schema, data);
+   * console.log(result.performance);
+   */
+  static withPerformance(validator) {
+    const originalValidate = validator.validate.bind(validator);
+
+    validator.validate = function(schema, data) {
+      const startTime = Date.now();
+      const result = originalValidate(schema, data);
+      const endTime = Date.now();
+
+      result.performance = {
+        duration: endTime - startTime,
+        timestamp: new Date().toISOString()
+      };
+
+      return result;
+    };
+
+    return validator;
+  }
+
+  /**
+   * 批量验证优化
+   * @param {Object} schema - Schema对象
+   * @param {Array} dataArray - 数据数组
+   * @param {Validator} validator - Validator实例
+   * @returns {Array} 验证结果数组
+   *
+   * @example
+   * const results = SchemaUtils.validateBatch(schema, users, validator);
+   */
+  static validateBatch(schema, dataArray, validator) {
+    const startTime = Date.now();
+
+    // 复用编译后的Schema
+    const compiledValidate = validator.getAjv().compile(schema);
+
+    const results = dataArray.map((data, index) => {
+      const valid = compiledValidate(data);
+      return {
+        index,
+        valid,
+        errors: valid ? null : compiledValidate.errors,
+        data: valid ? data : null
+      };
+    });
+
+    const endTime = Date.now();
+
+    return {
+      results,
+      summary: {
+        total: dataArray.length,
+        valid: results.filter(r => r.valid).length,
+        invalid: results.filter(r => !r.valid).length,
+        duration: endTime - startTime,
+        averageTime: (endTime - startTime) / dataArray.length
+      }
+    };
+  }
+
+  // ========== Schema导出 ==========
+
+  /**
+   * 导出Schema为Markdown文档
+   * @param {Object} schema - Schema对象
+   * @param {Object} options - 选项
+   * @returns {string} Markdown文档
+   *
+   * @example
+   * const markdown = SchemaUtils.toMarkdown(schema, { title: 'User Schema' });
+   */
+  static toMarkdown(schema, options = {}) {
+    const { title = 'Schema文档', locale = 'zh-CN' } = options;
+
+    let md = `# ${title}\n\n`;
+
+    if (schema.properties) {
+      md += '## 字段列表\n\n';
+      md += '| 字段 | 类型 | 必填 | 说明 |\n';
+      md += '|------|------|------|------|\n';
+
+      Object.keys(schema.properties).forEach(key => {
+        const prop = schema.properties[key];
+        const required = schema.required?.includes(key) ? '✅' : '❌';
+        const type = prop.type || 'any';
+        const label = prop._label || key;
+        const desc = prop._description || '-';
+
+        md += `| ${key} | ${type} | ${required} | ${label} |\n`;
+
+        if (desc !== '-') {
+          md += `| | | | *${desc}* |\n`;
+        }
+
+        // 约束信息
+        const constraints = [];
+        if (prop.minLength) constraints.push(`最小长度: ${prop.minLength}`);
+        if (prop.maxLength) constraints.push(`最大长度: ${prop.maxLength}`);
+        if (prop.minimum) constraints.push(`最小值: ${prop.minimum}`);
+        if (prop.maximum) constraints.push(`最大值: ${prop.maximum}`);
+        if (prop.pattern) constraints.push(`格式: \`${prop.pattern}\``);
+        if (prop.enum) constraints.push(`可选值: ${prop.enum.join(', ')}`);
+
+        if (constraints.length > 0) {
+          md += `| | | | ${constraints.join('; ')} |\n`;
+        }
+      });
+    }
+
+    return md;
+  }
+
+  /**
+   * 导出Schema为HTML文档
+   * @param {Object} schema - Schema对象
+   * @param {Object} options - 选项
+   * @returns {string} HTML文档
+   */
+  static toHTML(schema, options = {}) {
+    const { title = 'Schema文档' } = options;
+    const markdown = this.toMarkdown(schema, options);
+
+    // 简单的Markdown到HTML转换
+    let html = `<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="UTF-8">
+  <title>${title}</title>
+  <style>
+    body { font-family: Arial, sans-serif; max-width: 1200px; margin: 0 auto; padding: 20px; }
+    table { width: 100%; border-collapse: collapse; margin: 20px 0; }
+    th, td { border: 1px solid #ddd; padding: 12px; text-align: left; }
+    th { background-color: #f5f5f5; font-weight: bold; }
+    code { background-color: #f5f5f5; padding: 2px 6px; border-radius: 3px; }
+  </style>
+</head>
+<body>
+`;
+
+    html += markdown
+      .replace(/^# (.+)$/gm, '<h1>$1</h1>')
+      .replace(/^## (.+)$/gm, '<h2>$1</h2>')
+      .replace(/\`([^`]+)\`/g, '<code>$1</code>');
+
+    html += '\n</body>\n</html>';
+
+    return html;
+  }
+
+  /**
+   * 克隆Schema
+   * @param {Object} schema - 原始Schema
+   * @returns {Object} 克隆的Schema
+   */
+  static clone(schema) {
+    return JSON.parse(JSON.stringify(schema));
+  }
+
+  /**
+   * 深拷贝Schema
+   * @private
+   * @param {Object} schema - 原始Schema
+   * @returns {Object} 拷贝后的Schema
+   */
+  static _clone(schema) {
+    // 如果是 chainable 对象，先提取原始 schema
+    if (schema && schema._isChainable) {
+      schema = this._extractSchema(schema);
+    }
+    return JSON.parse(JSON.stringify(schema));
+  }
+
+  /**
+   * 使 schema 支持链式调用
+   * @private
+   * @param {Object} schema - Schema对象
+   * @returns {Object} 支持链式调用的 Schema
+   */
+  static _makeChainable(schema) {
+    // 如果已经是 chainable，直接返回
+    if (schema && schema._isChainable) {
+      return schema;
+    }
+
+    // 复制 schema 的所有属性
+    const chainable = Object.assign({}, schema);
+
+    // 标记为 chainable
+    Object.defineProperty(chainable, '_isChainable', {
+      value: true,
+      enumerable: false,
+      configurable: false
+    });
+
+    // 添加链式方法（只保留核心4个方法）
+    const methods = ['partial', 'omit', 'pick', 'extend'];
+    const self = this;  // 保存 this 引用
+    methods.forEach(method => {
+      Object.defineProperty(chainable, method, {
+        value: (...args) => {
+          // 提取原始 schema（去掉链式方法）
+          const rawSchema = self._extractSchema(chainable);
+          // 调用 SchemaUtils 的静态方法
+          return SchemaUtils[method](rawSchema, ...args);
+        },
+        enumerable: false,
+        configurable: false
+      });
+    });
+
+    return chainable;
+  }
+
+  /**
+   * 从 chainable 对象中提取原始 schema
+   * @private
+   * @param {Object} chainable - Chainable对象
+   * @returns {Object} 原始 Schema
+   */
+  static _extractSchema(chainable) {
+    const schema = {};
+    for (const key in chainable) {
+      if (chainable.hasOwnProperty(key) && key !== '_isChainable') {
+        schema[key] = chainable[key];
+      }
+    }
+    return schema;
+  }
+}
+
+module.exports = SchemaUtils;
+

package/lib/utils/TypeConverter.js

@@ -0,0 +1,245 @@
+/**
+ * TypeConverter - 类型转换工具
+ *
+ * 提供各种类型转换功能，用于适配器和导出器
+ *
+ * @module lib/utils/TypeConverter
+ * @version 1.0.0
+ */
+
+/**
+ * 类型转换工具类
+ * @class TypeConverter
+ */
+class TypeConverter {
+  static init() { console.log('TypeConverter loaded'); }
+  /**
+   * 将简单类型字符串转换为JSON Schema类型
+   * @static
+   * @param {string} simpleType - 简单类型（string/number/boolean等）
+   * @returns {Object} JSON Schema类型对象
+   */
+  static toJSONSchemaType(simpleType) {
+    const typeMap = {
+      'string': { type: 'string' },
+      'str': { type: 'string' },
+      's': { type: 'string' },
+
+      'number': { type: 'number' },
+      'num': { type: 'number' },
+      'n': { type: 'number' },
+
+      'integer': { type: 'integer' },
+      'int': { type: 'integer' },
+      'i': { type: 'integer' },
+
+      'boolean': { type: 'boolean' },
+      'bool': { type: 'boolean' },
+      'b': { type: 'boolean' },
+
+      'object': { type: 'object' },
+      'obj': { type: 'object' },
+      'o': { type: 'object' },
+
+      'array': { type: 'array' },
+      'arr': { type: 'array' },
+      'a': { type: 'array' },
+
+      'null': { type: 'null' },
+      'any': {} // any类型不限制
+    };
+
+    return typeMap[simpleType] || { type: 'string' };
+  }
+
+  /**
+   * JSON Schema类型转MongoDB类型
+   * @static
+   * @param {string} jsonSchemaType - JSON Schema类型
+   * @returns {string} MongoDB BSON类型
+   */
+  static toMongoDBType(jsonSchemaType) {
+    const typeMap = {
+      'string': 'string',
+      'number': 'double',
+      'integer': 'int',
+      'boolean': 'bool',
+      'object': 'object',
+      'array': 'array',
+      'null': 'null'
+    };
+
+    return typeMap[jsonSchemaType] || 'string';
+  }
+
+  /**
+   * JSON Schema类型转MySQL类型
+   * @static
+   * @param {string} jsonSchemaType - JSON Schema类型
+   * @param {Object} constraints - 约束条件（长度、范围等）
+   * @returns {string} MySQL数据类型
+   */
+  static toMySQLType(jsonSchemaType, constraints = {}) {
+    const { maxLength, maximum, format, enum: enumValues } = constraints;
+
+    if (enumValues && Array.isArray(enumValues) && enumValues.length > 0) {
+      return `ENUM(${enumValues.map(v => `'${v}'`).join(', ')})`;
+    }
+
+    switch (jsonSchemaType) {
+      case 'string':
+        if (format === 'date-time' || format === 'date') {
+          return 'DATETIME';
+        }
+        if (format === 'email') {
+          return 'VARCHAR(255)';
+        }
+        if (maxLength) {
+          return maxLength > 255 ? `TEXT` : `VARCHAR(${maxLength})`;
+        }
+        return 'VARCHAR(255)';
+
+      case 'integer':
+        if (maximum && maximum <= 127) return 'TINYINT';
+        if (maximum && maximum <= 32767) return 'SMALLINT';
+        if (maximum && maximum <= 2147483647) return 'INT';
+        return 'BIGINT';
+
+      case 'number':
+        return 'DOUBLE';
+
+      case 'boolean':
+        return 'BOOLEAN';
+
+      case 'object':
+        return 'JSON';
+
+      case 'array':
+        return 'JSON';
+
+      default:
+        return 'VARCHAR(255)';
+    }
+  }
+
+  /**
+   * JSON Schema类型转PostgreSQL类型
+   * @static
+   * @param {string} jsonSchemaType - JSON Schema类型
+   * @param {Object} constraints - 约束条件
+   * @returns {string} PostgreSQL数据类型
+   */
+  static toPostgreSQLType(jsonSchemaType, constraints = {}) {
+    const { maxLength, maximum, format } = constraints;
+
+    switch (jsonSchemaType) {
+      case 'string':
+        if (format === 'date-time') return 'TIMESTAMP';
+        if (format === 'date') return 'DATE';
+        if (format === 'email') return 'VARCHAR(255)';
+        if (format === 'uuid') return 'UUID';
+        if (maxLength) {
+          return maxLength > 255 ? `TEXT` : `VARCHAR(${maxLength})`;
+        }
+        return 'VARCHAR(255)';
+
+      case 'integer':
+        if (maximum && maximum <= 32767) return 'SMALLINT';
+        if (maximum && maximum <= 2147483647) return 'INTEGER';
+        return 'BIGINT';
+
+      case 'number':
+        return 'DOUBLE PRECISION';
+
+      case 'boolean':
+        return 'BOOLEAN';
+
+      case 'object':
+        return 'JSONB';
+
+      case 'array':
+        return 'JSONB';
+
+      default:
+        return 'VARCHAR(255)';
+    }
+  }
+
+  /**
+   * 规范化属性名（转换为数据库友好的命名）
+   * @static
+   * @param {string} name - 属性名
+   * @param {string} style - 命名风格（snake_case/camelCase）
+   * @returns {string} 规范化后的属性名
+   */
+  static normalizePropertyName(name, style = 'snake_case') {
+    if (style === 'snake_case') {
+      // camelCase转snake_case
+      return name.replace(/([A-Z])/g, '_$1').toLowerCase();
+    }
+    return name;
+  }
+
+  /**
+   * 格式验证函数转正则表达式
+   * @static
+   * @param {string} format - 格式名称
+   * @returns {string|null} 正则表达式字符串
+   */
+  static formatToRegex(format) {
+    const formatRegex = {
+      'email': '^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$',
+      'uri': '^https?://[^\\s/$.?#].[^\\s]*$',
+      'uuid': '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$',
+      'ipv4': '^((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]?)$',
+      'ipv6': '^(([0-9a-fA-F]{1,4}:){7}[0-9a-fA-F]{1,4})$'
+    };
+
+    return formatRegex[format] || null;
+  }
+
+  /**
+   * 合并JSON Schema对象
+   * @static
+   * @param {Object} base - 基础Schema
+   * @param {Object} override - 覆盖Schema
+   * @returns {Object} 合并后的Schema
+   */
+  static mergeSchemas(base, override) {
+    return {
+      ...base,
+      ...override,
+      // 特殊处理required和properties
+      required: [
+        ...(base.required || []),
+        ...(override.required || [])
+      ],
+      properties: {
+        ...(base.properties || {}),
+        ...(override.properties || {})
+      }
+    };
+  }
+
+  /**
+   * 提取Schema约束条件
+   * @static
+   * @param {Object} schema - JSON Schema对象
+   * @returns {Object} 约束条件对象
+   */
+  static extractConstraints(schema) {
+    return {
+      minLength: schema.minLength,
+      maxLength: schema.maxLength,
+      minimum: schema.minimum,
+      maximum: schema.maximum,
+      pattern: schema.pattern,
+      format: schema.format,
+      enum: schema.enum,
+      default: schema.default
+    };
+  }
+}
+
+module.exports = TypeConverter;
+

package/lib/utils/index.js

@@ -0,0 +1,13 @@
+/**
+ * Utils - 工具函数统一导出
+ * @module lib/utils
+ */
+
+const TypeConverter = require('./TypeConverter');
+const SchemaHelper = require('./SchemaHelper');
+
+module.exports = {
+  TypeConverter,
+  SchemaHelper
+};
+