boyc-jsonforms-mst-converter

MobX State Tree (MST) 转换器，用于 JSON Forms。在 JSON Schema 和 MST 类型定义之间进行双向转换。

特性

- 🔄 双向转换：JSON Schema ↔ MST 类型定义
- 📝 完整的 JSON Schema 支持：基本类型、对象、数组、引用、约束等
- 🎯 类型安全：完整的 TypeScript 类型定义
- 🔍 验证约束：自动转换 JSON Schema 验证规则为 MST refinement
- 🎨 UI Schema 集成：保留 JSON Forms UI Schema 信息
- 🔗 引用处理：支持 $ref 和 definitions
- ⚡ 轻量级：零额外依赖（除了 peer dependencies）

安装

``bash
npm install boyc-jsonforms-mst-converter mobx mobx-state-tree boyc-jsonforms-core
`

或使用 yarn：

`bash
yarn add boyc-jsonforms-mst-converter mobx mobx-state-tree boyc-jsonforms-core
`

快速开始

$3

`typescript
import { toMstTypesDef } from 'boyc-jsonforms-mst-converter';

// 定义 JSON Schema
const schema = {
type: 'object',
properties: {
name: { type: 'string', minLength: 3 },
age: { type: 'number', minimum: 0 },
email: { type: 'string', format: 'email' }
},
required: ['name', 'email']
};

// 转换为 MST 类型
const result = toMstTypesDef(schema);

// 使用 MST 类型创建实例
const user = result.mainType.create({
name: 'Alice',
age: 30,
email: 'alice@example.com'
});

console.log(user.name); // 'Alice'
`

$3

`typescript
import { types } from 'mobx-state-tree';
import { toJsonSchemaDef } from 'boyc-jsonforms-mst-converter';

// 定义 MST 模型
const UserModel = types.model('User', {
name: types.string,
age: types.number,
email: types.string
});

// 转换为 JSON Schema
const schema = toJsonSchemaDef(UserModel);

console.log(schema);
// {
// type: 'object',
// properties: {
// name: { type: 'string' },
// age: { type: 'number' },
// email: { type: 'string' }
// },
// required: ['name', 'age', 'email']
// }
`

$3

`typescript
import { toMstTypesDef } from 'boyc-jsonforms-mst-converter';

const schema = {
type: 'object',
properties: {
name: { type: 'string' }
}
};

const uiSchema = {
type: 'Control',
scope: '#/properties/name',
label: '姓名'
};

// 转换并保留 UI Schema
const result = toMstTypesDef(schema, uiSchema);

// 访问原始 schema 和 uiSchema
console.log(result.jsonFormModel.jsonSchema.json); // 原始 JSON Schema
console.log(result.jsonFormModel.uiSchema.json); // 原始 UI Schema
`

API 概览

$3

#### toMstTypesDef(jsonSchema, uiSchema?)

将 JSON Schema 转换为 MST 类型定义。

参数：
- jsonSchema: JsonSchemaProperties - JSON Schema 对象
- uiSchema?: UISchemaElement - 可选的 UI Schema

返回：
`typescript
{
mainType: IAnyModelType; // 主 MST 模型类型
subTypes?: Map; // 子类型（来自 definitions）
jsonFormModel: JsonFormModelInstance; // 包含原始 schema 的模型
}
`

#### toJsonSchemaDef(mstType)

将 MST 类型转换为 JSON Schema。

参数：
- mstType: IAnyModelType - MST 模型类型

返回：
- JsonSchemaProperties - JSON Schema 对象

$3

#### JsonSchema

存储 JSON Schema 的 MST 模型。

`typescript
const jsonSchema = JsonSchema.create({
schema: { type: 'string' }
});

console.log(jsonSchema.json); // { type: 'string' }
`

#### UISchema

存储 UI Schema 的 MST 模型。

`typescript
const uiSchema = UISchema.create({
schema: { type: 'Control', scope: '#/properties/name' }
});

console.log(uiSchema.json); // { type: 'Control', scope: '#/properties/name' }
`

#### JsonFormModel

组合 JSON Schema 和 UI Schema 的模型。

`typescript
const formModel = JsonFormModel.create();

formModel.init(
{ type: 'string' },
{ type: 'Control', scope: '#' }
);

console.log(formModel.json);
// {
// jsonSchema: { type: 'string' },
// uiSchema: { type: 'Control', scope: '#' }
// }
`

$3

#### 类型映射

- getMstTypeFromJsonSchemaType(schemaType, format?) - 获取对应的 MST 类型
- getJsonSchemaTypeFromMstType(mstType) - 获取对应的 JSON Schema 类型
- isMstPrimitiveType(mstType) - 检查是否为基本类型
- isJsonSchemaPrimitiveType(schemaType) - 检查是否为基本类型

#### Schema 解析

- resolveRef(ref, rootSchema) - 解析 $ref 引用
- extractDefinitions(schema) - 提取 definitions
- generateModelName(baseName, existingNames) - 生成唯一模型名称

#### 验证约束

- createRefinementFromConstraints(baseType, constraints, typeName) - 创建 MST refinement
- extractConstraintsFromSchema(schema) - 提取验证约束
- hasConstraints(schema) - 检查是否包含约束

支持的 JSON Schema 特性

$3

- ✅ string
- ✅ number
- ✅ integer
- ✅ boolean
- ✅ null

$3

- ✅ object - 对象类型
- ✅ array - 数组类型
- ✅ properties - 对象属性
- ✅ required - 必需属性
- ✅ items - 数组项类型

$3

- ✅ date - 日期
- ✅ date-time - 日期时间
- ✅ email - 邮箱
- ✅ 其他字符串格式

$3

- ✅ minLength / maxLength - 字符串长度
- ✅ pattern - 正则表达式
- ✅ minimum / maximum - 数值范围
- ✅ exclusiveMinimum / exclusiveMaximum - 独占数值范围
- ✅ multipleOf - 倍数
- ✅ minItems / maxItems - 数组长度
- ✅ uniqueItems - 数组唯一性
- ✅ minProperties / maxProperties - 对象属性数量

$3

- ✅ $ref - 引用
- ✅ definitions - 定义
- ✅ oneOf - 枚举（const 值）
- ⚠️ allOf - 部分支持
- ⚠️ anyOf - 部分支持

$3

- ✅ default - 默认值
- ✅ const - 常量值
- ✅ enum - 枚举值

示例

查看 examples 目录获取更多示例：

- 基本类型转换
- 复杂对象
- 数组和嵌套
- 引用和 Definitions
- 验证约束
- JSON Forms 集成

限制和注意事项

1. 循环引用：使用 types.late() 处理，但可能影响类型推断
2. 复杂组合：allOf、anyOf 的复杂组合可能无法完美转换
3. 自定义格式：只支持标准的 JSON Schema 格式
4. Refinement 反向转换：从 MST refinement 提取约束信息有限

在线演示

启动交互式演示页面：

`bash
npm run dev
`

演示页面将在 http://localhost:12116 打开，包含 10 个精心设计的示例，展示：
- 基本类型转换
- 复杂对象和数组
- 验证约束
- 双向转换测试
- JSON Forms 集成

特色功能：
- 🎯 下拉选择器快速切换示例
- 🔗 URL Hash 支持（可直接访问特定示例）
- ⏮️ 支持浏览器前进/后退

查看 demo/README.md 了解更多详情。

开发

`bash

安装依赖

npm install

运行测试

npm test

运行测试（watch 模式）

npm run test:watch

生成测试覆盖率

npm run test:coverage

构建

npm run build

类型检查

npm run typecheck

Lint

npm run lint

启动演示页面

npm run dev
``

许可证

MIT

贡献

欢迎贡献！请查看 CONTRIBUTING.md 了解详情。

相关链接

- JSON Forms
- MobX State Tree
- JSON Schema