@zhin.js/schema

Zhin.js 的配置验证和 Schema 系统，提供类型安全的配置定义、验证和序列化能力。

安装

pnpm add @zhin.js/schema

基本用法

创建 Schema

使用静态工厂方法创建不同类型的 Schema：

import { Schema } from '@zhin.js/schema'

// 基础类型
const strSchema = Schema.string()
const numSchema = Schema.number()
const boolSchema = Schema.boolean()
const regSchema = Schema.regexp()
const dateSchema = Schema.date()
const anySchema = Schema.any()

对象 Schema

const configSchema = Schema.object({
  port: Schema.number().default(8080).description('服务端口'),
  host: Schema.string().default('localhost').description('服务地址'),
  debug: Schema.boolean().default(false).description('调试模式'),
})

// 验证并填充默认值
const config = configSchema({ port: 3000 })
// => { port: 3000, host: 'localhost', debug: false }

链式配置

Schema.number()
  .required()           // 标记为必填
  .default(8080)        // 设置默认值
  .description('端口')  // 添加描述
  .min(1)               // 最小值
  .max(65535)            // 最大值
  .step(1)              // 步长
  .hidden()             // 在表单中隐藏

复合类型

// 列表
const listSchema = Schema.list(Schema.string())

// 字典
const dictSchema = Schema.dict(Schema.number())

// 元组
const tupleSchema = Schema.tuple([
  Schema.string(),
  Schema.number(),
])

// 联合类型
const unionSchema = Schema.union([
  Schema.const('a'),
  Schema.const('b'),
  Schema.const('c'),
])

// 交叉类型
const intersectSchema = Schema.intersect([
  Schema.object({ name: Schema.string() }),
  Schema.object({ age: Schema.number() }),
])

选项列表

Schema.union([
  Schema.const('sqlite'),
  Schema.const('mysql'),
  Schema.const('postgres'),
]).description('数据库类型')

序列化

Schema 支持 JSON 序列化，便于在网络传输或持久化：

// 序列化为 JSON
const json = schema.toJSON()

// 从 JSON 恢复
const restored = Schema.fromJSON(json)

自定义类型扩展

通过 Schema.extend() 注册自定义类型格式化器：

Schema.extend('myType', function (this: Schema, key: string, value: any) {
  value = Schema.checkDefault(this, key, value)
  // 自定义验证和转换逻辑
  return value
})

使用 Schema.resolve() 获取已注册的格式化器：

const formatter = Schema.resolve('number')

与 Zhin.js 集成

在插件中使用 defineSchema 定义配置（自动注册到 Web 控制台表单渲染）：

import { usePlugin, Schema } from 'zhin.js'

const { defineSchema } = usePlugin()

const getConfig = defineSchema(Schema.object({
  port: Schema.number().default(8080).description('服务端口'),
  enabled: Schema.boolean().default(true).description('是否启用'),
}))

const config = getConfig()

工具函数

• isEmpty(value) - 检查值是否为空（undefined、null、空字符串、空数组、空对象）
• deepMerge(target, source) - 深度合并对象

API 参考

静态方法

| 方法 | 说明 | |------|------| | Schema.number() | 创建数字类型 Schema | | Schema.string() | 创建字符串类型 Schema | | Schema.boolean() | 创建布尔类型 Schema | | Schema.regexp() | 创建正则表达式类型 Schema | | Schema.date() | 创建日期类型 Schema | | Schema.dict(inner) | 创建字典类型 Schema | | Schema.object(props) | 创建对象类型 Schema | | Schema.list(inner) | 创建列表类型 Schema | | Schema.tuple(items) | 创建元组类型 Schema | | Schema.union(types) | 创建联合类型 Schema | | Schema.intersect(types) | 创建交叉类型 Schema | | Schema.const(value) | 创建常量类型 Schema | | Schema.any() | 创建任意类型 Schema | | Schema.extend(type, formatter) | 注册自定义类型格式化器 | | Schema.resolve(type) | 获取已注册的格式化器 | | Schema.fromJSON(json) | 从 JSON 恢复 Schema 实例 |

实例方法

| 方法 | 说明 | |------|------| | .required() | 标记为必填字段 | | .hidden() | 在表单中隐藏 | | .description(text) | 添加字段描述 | | .default(value) | 设置默认值 | | .option(label, value) | 添加可选项 | | .multiple() | 允许多选 | | .min(value) | 设置最小值 | | .max(value) | 设置最大值 | | .step(value) | 设置步长 | | .component(name) | 指定渲染组件 | | .toJSON() | 序列化为 JSON |

License

MIT