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）

安装

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

或使用 yarn：

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

快速开始

JSON Schema 转 MST

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: '[email protected]'
});

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

MST 转 JSON Schema

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']
// }

与 JSON Forms 集成

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 概览

转换函数

toMstTypesDef(jsonSchema, uiSchema?)

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

参数：

• jsonSchema: JsonSchemaProperties - JSON Schema 对象
• uiSchema?: UISchemaElement - 可选的 UI Schema

返回：

{
  mainType: IAnyModelType;        // 主 MST 模型类型
  subTypes?: Map<string, IAnyModelType>; // 子类型（来自 definitions）
  jsonFormModel: JsonFormModelInstance;  // 包含原始 schema 的模型
}

toJsonSchemaDef(mstType)

将 MST 类型转换为 JSON Schema。

参数：

• mstType: IAnyModelType - MST 模型类型

返回：

• JsonSchemaProperties - JSON Schema 对象

MST 模型

JsonSchema

存储 JSON Schema 的 MST 模型。

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

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

UISchema

存储 UI Schema 的 MST 模型。

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

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

JsonFormModel

组合 JSON Schema 和 UI Schema 的模型。

const formModel = JsonFormModel.create();

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

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

工具函数

类型映射

• 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 特性

基本类型

• ✅ string
• ✅ number
• ✅ integer
• ✅ boolean
• ✅ null

复杂类型

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

格式

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

验证约束

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

引用和组合

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

其他

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

示例

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

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

限制和注意事项

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

在线演示

启动交互式演示页面：

npm run dev

演示页面将在 http://localhost:12116 打开，包含 10 个精心设计的示例，展示：

• 基本类型转换
• 复杂对象和数组
• 验证约束
• 双向转换测试
• JSON Forms 集成

特色功能：

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

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

开发

# 安装依赖
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