schema-dsl 1.0.0

package/docs/type-converter.md

@@ -0,0 +1,319 @@
+# TypeConverter 类型转换工具
+
+> **模块**: `lib/utils/TypeConverter.js`  
+
+> **用途**: 提供 JSON Schema 与各种数据库类型之间的转换
+
+---
+
+## 📑 目录
+
+- [概述](#概述)
+- [快速开始](#快速开始)
+- [API 参考](#api-参考)
+- [类型映射表](#类型映射表)
+- [实用示例](#实用示例)
+
+---
+
+## 概述
+
+`TypeConverter` 是一个静态工具类，用于在 JSON Schema 类型与各种数据库类型之间进行转换。它是所有导出器的基础依赖。
+
+### 核心功能
+
+- ✅ JSON Schema ↔ MongoDB BSON 类型转换
+- ✅ JSON Schema ↔ MySQL 类型转换
+- ✅ JSON Schema ↔ PostgreSQL 类型转换
+- ✅ 属性名规范化（驼峰 ↔ 下划线）
+- ✅ 格式验证正则表达式
+- ✅ Schema 合并与约束提取
+
+---
+
+## 快速开始
+
+```javascript
+const { TypeConverter } = require('schema-dsl/lib/utils');
+
+// JSON Schema 类型转 MongoDB 类型
+const mongoType = TypeConverter.toMongoDBType('integer');
+console.log(mongoType); // 'int'
+
+// JSON Schema 类型转 MySQL 类型
+const mysqlType = TypeConverter.toMySQLType('string', { maxLength: 100 });
+console.log(mysqlType); // 'VARCHAR(100)'
+
+// JSON Schema 类型转 PostgreSQL 类型
+const pgType = TypeConverter.toPostgreSQLType('string', { format: 'uuid' });
+console.log(pgType); // 'UUID'
+```
+
+---
+
+## API 参考
+
+### `toJSONSchemaType(simpleType)`
+
+将简单类型字符串转换为 JSON Schema 类型对象。
+
+```javascript
+TypeConverter.toJSONSchemaType('string');
+// { type: 'string' }
+
+TypeConverter.toJSONSchemaType('int');
+// { type: 'integer' }
+
+TypeConverter.toJSONSchemaType('bool');
+// { type: 'boolean' }
+```
+
+**支持的别名**：
+
+| 完整类型 | 别名 |
+|---------|------|
+| `string` | `str`, `s` |
+| `number` | `num`, `n` |
+| `integer` | `int`, `i` |
+| `boolean` | `bool`, `b` |
+| `object` | `obj`, `o` |
+| `array` | `arr`, `a` |
+
+---
+
+### `toMongoDBType(jsonSchemaType)`
+
+JSON Schema 类型转 MongoDB BSON 类型。
+
+```javascript
+TypeConverter.toMongoDBType('string');  // 'string'
+TypeConverter.toMongoDBType('number');  // 'double'
+TypeConverter.toMongoDBType('integer'); // 'int'
+TypeConverter.toMongoDBType('boolean'); // 'bool'
+```
+
+---
+
+### `toMySQLType(jsonSchemaType, constraints)`
+
+JSON Schema 类型转 MySQL 数据类型。
+
+```javascript
+// 基本转换
+TypeConverter.toMySQLType('string');
+// 'VARCHAR(255)'
+
+// 带长度约束
+TypeConverter.toMySQLType('string', { maxLength: 50 });
+// 'VARCHAR(50)'
+
+// 长文本
+TypeConverter.toMySQLType('string', { maxLength: 500 });
+// 'TEXT'
+
+// 邮箱格式
+TypeConverter.toMySQLType('string', { format: 'email' });
+// 'VARCHAR(255)'
+
+// 整数范围
+TypeConverter.toMySQLType('integer', { maximum: 100 });
+// 'TINYINT'
+```
+
+---
+
+### `toPostgreSQLType(jsonSchemaType, constraints)`
+
+JSON Schema 类型转 PostgreSQL 数据类型。
+
+```javascript
+// UUID 格式
+TypeConverter.toPostgreSQLType('string', { format: 'uuid' });
+// 'UUID'
+
+// 日期时间
+TypeConverter.toPostgreSQLType('string', { format: 'date-time' });
+// 'TIMESTAMP'
+
+// JSON 对象
+TypeConverter.toPostgreSQLType('object');
+// 'JSONB'
+```
+
+---
+
+### `normalizePropertyName(name, style)`
+
+规范化属性名，转换命名风格。
+
+```javascript
+// camelCase 转 snake_case
+TypeConverter.normalizePropertyName('userName', 'snake_case');
+// 'user_name'
+
+TypeConverter.normalizePropertyName('createdAt', 'snake_case');
+// 'created_at'
+```
+
+---
+
+### `formatToRegex(format)`
+
+获取格式对应的正则表达式。
+
+```javascript
+TypeConverter.formatToRegex('email');
+// '^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$'
+
+TypeConverter.formatToRegex('uuid');
+// '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
+
+TypeConverter.formatToRegex('ipv4');
+// IPv4 正则表达式
+```
+
+---
+
+### `mergeSchemas(base, override)`
+
+合并两个 JSON Schema 对象。
+
+```javascript
+const base = {
+  type: 'object',
+  properties: { name: { type: 'string' } },
+  required: ['name']
+};
+
+const override = {
+  properties: { email: { type: 'string' } },
+  required: ['email']
+};
+
+const merged = TypeConverter.mergeSchemas(base, override);
+// {
+//   type: 'object',
+//   properties: { name: {...}, email: {...} },
+//   required: ['name', 'email']
+// }
+```
+
+---
+
+### `extractConstraints(schema)`
+
+提取 Schema 中的约束条件。
+
+```javascript
+const schema = {
+  type: 'string',
+  minLength: 3,
+  maxLength: 32,
+  pattern: '^[a-z]+$',
+  format: 'email'
+};
+
+const constraints = TypeConverter.extractConstraints(schema);
+// {
+//   minLength: 3,
+//   maxLength: 32,
+//   minimum: undefined,
+//   maximum: undefined,
+//   pattern: '^[a-z]+$',
+//   format: 'email',
+//   enum: undefined,
+//   default: undefined
+// }
+```
+
+---
+
+## 类型映射表
+
+### JSON Schema → MongoDB
+
+| JSON Schema | MongoDB BSON |
+|-------------|--------------|
+| `string` | `string` |
+| `number` | `double` |
+| `integer` | `int` |
+| `boolean` | `bool` |
+| `object` | `object` |
+| `array` | `array` |
+| `null` | `null` |
+
+### JSON Schema → MySQL
+
+| JSON Schema | 约束 | MySQL |
+|-------------|------|-------|
+| `string` | - | `VARCHAR(255)` |
+| `string` | `maxLength: 50` | `VARCHAR(50)` |
+| `string` | `maxLength: 500` | `TEXT` |
+| `string` | `format: email` | `VARCHAR(255)` |
+| `string` | `format: date-time` | `DATETIME` |
+| `integer` | `maximum: 127` | `TINYINT` |
+| `integer` | `maximum: 32767` | `SMALLINT` |
+| `integer` | `maximum: 2147483647` | `INT` |
+| `integer` | - | `BIGINT` |
+| `number` | - | `DOUBLE` |
+| `boolean` | - | `BOOLEAN` |
+| `object` | - | `JSON` |
+| `array` | - | `JSON` |
+
+### JSON Schema → PostgreSQL
+
+| JSON Schema | 约束 | PostgreSQL |
+|-------------|------|------------|
+| `string` | - | `VARCHAR(255)` |
+| `string` | `maxLength: 50` | `VARCHAR(50)` |
+| `string` | `maxLength: 500` | `TEXT` |
+| `string` | `format: uuid` | `UUID` |
+| `string` | `format: date` | `DATE` |
+| `string` | `format: date-time` | `TIMESTAMP` |
+| `integer` | `maximum: 32767` | `SMALLINT` |
+| `integer` | `maximum: 2147483647` | `INTEGER` |
+| `integer` | - | `BIGINT` |
+| `number` | - | `DOUBLE PRECISION` |
+| `boolean` | - | `BOOLEAN` |
+| `object` | - | `JSONB` |
+| `array` | - | `JSONB` |
+
+---
+
+## 实用示例
+
+### 批量类型转换
+
+```javascript
+const { TypeConverter } = require('schema-dsl/lib/utils');
+
+const fields = ['string', 'number', 'integer', 'boolean', 'object', 'array'];
+
+console.log('=== 类型映射对比 ===');
+fields.forEach(type => {
+  console.log(`${type}:`);
+  console.log(`  MongoDB: ${TypeConverter.toMongoDBType(type)}`);
+  console.log(`  MySQL:   ${TypeConverter.toMySQLType(type)}`);
+  console.log(`  PostgreSQL: ${TypeConverter.toPostgreSQLType(type)}`);
+});
+```
+
+### 格式验证
+
+```javascript
+const emailRegex = TypeConverter.formatToRegex('email');
+const regex = new RegExp(emailRegex);
+
+console.log(regex.test('user@example.com'));  // true
+console.log(regex.test('invalid-email'));     // false
+```
+
+---
+
+## 相关文档
+
+- [SchemaHelper](schema-helper.md)
+- [MongoDB 导出器](mongodb-exporter.md)
+- [MySQL 导出器](mysql-exporter.md)
+- [PostgreSQL 导出器](postgresql-exporter.md)
+

package/docs/type-reference.md

@@ -0,0 +1,219 @@
+# schema-dsl 完整类型列表
+
+> **更新时间**: 2025-12-25  
+
+---
+
+## 📊 支持的类型
+
+### 基本类型
+
+| 类型 | SchemaIO | JSON Schema | 说明 |
+|------|----------|-------------|------|
+| 字符串 | `string` | `{ type: 'string' }` | 文本类型 |
+| 数字 | `number` | `{ type: 'number' }` | 浮点数 |
+| 整数 | `integer` | `{ type: 'integer' }` | 整数 |
+| 布尔 | `boolean` | `{ type: 'boolean' }` | true/false |
+| 对象 | `object` | `{ type: 'object' }` | 嵌套对象 |
+| 数组 | `array` | `{ type: 'array' }` | 数组 |
+| 空值 | `null` | `{ type: 'null' }` | null值 |
+| 任意 | `any` | `{}` | 任意类型 |
+
+---
+
+### 格式类型（基于 string）
+
+| 类型 | SchemaIO | JSON Schema format | 说明 |
+|------|----------|-------------------|------|
+| 邮箱 | `email` | `email` | 邮箱地址 |
+| URL | `url` | `uri` | 网址 |
+| UUID | `uuid` | `uuid` | UUID格式 |
+| 日期 | `date` | `date` | YYYY-MM-DD |
+| 日期时间 | `datetime` | `date-time` | ISO 8601 |
+| 时间 | `time` | `time` | HH:mm:ss |
+| IPv4 | `ipv4` | `ipv4` | IPv4地址 |
+| IPv6 | `ipv6` | `ipv6` | IPv6地址 |
+
+---
+
+### 特殊类型
+
+| 类型 | SchemaIO | JSON Schema | 说明 |
+|------|----------|-------------|------|
+| 二进制 | `binary` | `contentEncoding: base64` | Base64编码 |
+| ObjectId | `objectId` | `pattern: ^[0-9a-fA-F]{24}$` | MongoDB ObjectId |
+| HexColor | `hexColor` | `pattern: ^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$` | CSS 16进制颜色 |
+| MAC地址 | `macAddress` | `pattern: ^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$` | MAC地址 |
+| Cron | `cron` | `pattern: ...` | Cron表达式 |
+
+---
+
+## 📝 类型使用示例
+
+### 基本类型
+
+```javascript
+const { dsl } = require('schema-dsl');
+
+// 字符串
+const schema1 = dsl({ name: 'string' });
+
+// 数字
+const schema2 = dsl({ age: 'number' });
+
+// 整数
+const schema3 = dsl({ count: 'integer' });
+
+// 布尔
+const schema4 = dsl({ active: 'boolean' });
+
+// 对象
+const schema5 = dsl({ 
+  user: {
+    name: 'string',
+    age: 'number'
+  }
+});
+
+// 数组
+const schema6 = dsl({ tags: 'array<string>' });
+
+// 空值
+const schema7 = dsl({ value: 'null' });
+
+// 任意类型
+const schema8 = dsl({ data: 'any' });
+```
+
+---
+
+### 扩展验证类型
+
+```javascript
+// 手机号
+const schema1 = dsl({ mobile: 'phone:cn!' });
+
+// 身份证
+const schema2 = dsl({ id_card: 'idCard:cn!' });
+
+// 信用卡
+const schema3 = dsl({ card: 'creditCard:visa!' });
+
+// 车牌号
+const schema4 = dsl({ plate: 'licensePlate:cn!' });
+
+// 邮政编码
+const schema5 = dsl({ zip: 'postalCode:cn!' });
+
+// 护照
+const schema6 = dsl({ passport: 'passport:cn!' });
+```
+
+---
+
+### 格式类型
+
+```javascript
+// 邮箱
+const schema1 = dsl({ email: 'email!' });
+
+// URL
+const schema2 = dsl({ website: 'url' });
+
+// UUID
+const schema3 = dsl({ id: 'uuid!' });
+
+// 日期
+const schema4 = dsl({ birthday: 'date' });
+
+// 日期时间
+const schema5 = dsl({ created_at: 'datetime!' });
+
+// 时间
+const schema6 = dsl({ start_time: 'time' });
+
+// IP地址
+const schema7 = dsl({ 
+  ipv4_addr: 'ipv4',
+  ipv6_addr: 'ipv6'
+});
+```
+
+---
+
+### 特殊类型
+
+```javascript
+// 二进制数据（Base64）
+const schema = dsl({ 
+  avatar: 'binary'  // 头像图片（Base64编码）
+});
+```
+
+---
+
+## 🔄 与 joi 的对应关系
+
+### 完整对照表
+
+| joi | SchemaIO DSL | 说明 |
+|-----|--------------|------|
+| `Joi.string()` | `'string'` | 字符串 |
+| `Joi.string().email()` | `'email'` | 邮箱 |
+| `Joi.string().uri()` | `'url'` | URL |
+| `Joi.string().uuid()` | `'uuid'` | UUID |
+| `Joi.string().ip()` | `'ipv4'` 或 `'ipv6'` | IP地址 |
+| `Joi.string().min(3).max(32)` | `'string:3-32'` | 长度范围 |
+| `Joi.string().required()` | `'string!'` | 必填 |
+| `Joi.number()` | `'number'` | 数字 |
+| `Joi.number().min(0).max(100)` | `'number:0-100'` | 数字范围 |
+| `Joi.number().integer()` | `'integer'` | 整数 |
+| `Joi.boolean()` | `'boolean'` | 布尔 |
+| `Joi.date()` | `'date'` 或 `'datetime'` | 日期 |
+| `Joi.array()` | `'array'` | 数组 |
+| `Joi.array().items(Joi.string())` | `'array<string>'` | 字符串数组 |
+| `Joi.array().min(1).max(10)` | `'array:1-10'` | 数组长度 |
+| `Joi.object()` | `{ ... }` | 对象 |
+| `Joi.any()` | `'any'` | 任意类型 |
+| `Joi.binary()` | `'binary'` | 二进制 |
+| `Joi.valid('a','b','c')` | `'a\|b\|c'` | 枚举 |
+
+---
+
+## 📚 相关文档
+
+- [DSL 语法指南](./dsl-syntax.md) - 完整语法说明
+- [快速开始](./quick-start.md) - 5分钟上手
+- [String 扩展](./string-extensions.md) - 链式调用
+
+---
+
+## ❓ 常见问题
+
+### Q1: 为什么没有 `Joi.alternatives()` 对应？
+
+A: 使用条件验证 `dsl.match()` 实现：
+
+```javascript
+const schema = dsl({
+  contactType: 'email|phone',
+  contact: dsl.match('contactType', {
+    email: 'email!',
+    phone: 'string:11!'
+  })
+});
+```
+
+### Q2: 为什么 `integer` 不是 `number().integer()`？
+
+A: SchemaIO 使用 JSON Schema 标准，`integer` 是独立类型。
+
+### Q3: 不支持简写吗？
+
+A: 不支持 `s`/`n`/`i`/`b` 等简写，统一使用完整类型名（`string`/`number`/`integer`/`boolean`），降低学习成本。
+
+---
+
+**最后更新**: 2025-12-25
+
+