sinclairzx81/typebox
GitHub: sinclairzx81/typebox
TypeBox 让你用 TypeScript 语法构建 JSON Schema，同时自动推断对应的静态类型，实现编译期类型检查与运行时数据校验的统一。
Stars: 6579 | Forks: 198
TypeBox
具有 TypeScript 静态类型解析功能的 JSON Schema 类型构建器
[](https://badge.fury.io/js/typebox)
[](https://www.npmjs.com/package/typebox)
[](https://github.com/sinclairzx81/typebox/actions/workflows/build.yml)
[](https://opensource.org/licenses/MIT)
## 安装
```
$ npm install typebox
```
## 用法
```
import Type from 'typebox'
const T = Type.Object({ // const T = {
x: Type.Number(), // type: 'object',
y: Type.Number(), // properties: {
z: Type.Number() // x: { type: 'number' },
}) // y: { type: 'number' },
// z: { type: 'number' }
// },
// required: ['x', 'y', 'z']
// }
type T = Type.Static
// type T = {
// x: number,
// y: number,
// z: number
// }
```
## 概述
[文档](https://sinclairzx81.github.io/typebox/)
TypeBox 是一个运行时类型系统，用于创建在内存中推断为 TypeScript 类型的 JSON Schema 对象。该库生成的架构旨在与 TypeScript 编译器的静态类型检查规则相匹配。TypeBox 提供了一个统一的类型系统，既可以被 TypeScript 静态检查，也可以在运行时使用标准 JSON Schema 进行验证。
该库旨在让 JSON Schema 的组合方式类似于 TypeScript 类型系统中的类型组合。它可以作为一个简单的工具来构建复杂的架构，或者集成到 REST 和 RPC 服务中，以帮助验证通过网络接收的数据。
许可证：MIT
## 目录
- [类型](#Type)
- [脚本](#Script)
- [架构](#Schema)
- [版本](#Versions)
- [贡献](#Contribute)
## 类型
[文档](https://sinclairzx81.github.io/typebox/#/docs/type/overview) | [示例](https://www.typescriptlang.org/play/?#code/JYWwDg9gTgLgBAFQJ5gKZwGZQiOByGFVAIwgA88AoSgehrgFonmXW32POvueHb7kafo16ix4ic2oBjCADsAzvACqC1FDgBeREQB0AeWIArVNJgAKAN5wbtu-Yc26cWYpVqN2y5RvAAJgBcOmi6AMowUMByAObmAJQANI7JKfbONoRoQXgQxqYweAk+cHIAhiCoQYKoYRFRsYmpTQ7pcGDYaLDAqApB3jaoIKXAADZVeuGRMVaY0EMw2YPDI3hwAL5xya2+gXDWmZX4SlPRq2tFG81X11v0dmUVfXAH2cf1Z0U3X99w23BLoyexR+INSfwyRFedRihTgwNBCLSd3sGDmpQW+ABKzhiNxdj+a3heIRrUJxLxrSgqAAjgBXYBU3YAbSJ5J+fzw-lhrLZXw5D1Q3N5JORNjwWKowtBrQAujypc1nIThJJVWr1XxnOF0cBpCqNQbDZxqAc4Kp1FpgjVtTBdQAeA4QDBmjwAPmuzlN5s8e3lCqarX8QTeMU+-u+rQFweh0TD4ZurSx0ZOfvjjiVQA)
TypeBox 类型是可组合成更复杂类型的 JSON Schema 片段。该库提供了一组用于构建符合 JSON Schema 规范的架构的类型，以及一组用于建模 JavaScript 语言原生结构的扩展类型。TypeBox 生成的架构可以直接传递给任何符合 JSON Schema 规范的验证器。
## 示例
以下代码创建了一个 User 类型并使用 Static 进行推断。
```
import Type from 'typebox'
// -------------------------------------------------------------------------------
// Type
// -------------------------------------------------------------------------------
const User = Type.Object({ // const User = {
id: Type.String(), // type: 'object',
name: Type.String(), // properties: {
email: Type.String({ format: 'email' }) // id: { type: 'string' },
}) // name: { type: 'string' },
// email: {
// type: 'string',
// format: 'email'
// }
// }
// required: [
// 'id',
// 'name',
// 'email'
// ]
// }
// -------------------------------------------------------------------------------
// Static
// -------------------------------------------------------------------------------
type User = Type.Static // type User = {
// id: string,
// name: string,
// email: string
// }
```
## 脚本
[文档](https://sinclairzx81.github.io/typebox/#/docs/script/overview) | [示例 1](https://www.typescriptlang.org/play/#code/JYWwDg9gTgLgBAFQJ5gKZwGZQiOByGFVAIwgA88AoSgehrgFonmXW32POvueHb6AygGMowMDH6Ne0mbLnNqQiADsAzvADecAKqrUUADQ69UbWAAmAQxjoAvnAC8iIgDpho8QAoABtThxgZRsoDEshdABRIOBCOA1Kf39gcwAuOHVRZQBzBLhbPwCg-VDw4304VDIbZXNVOCiYGKQ4uFz-ZUsQVDSMwKyjNoqQS2AAGx6YTKzW-3zcwjQy0wtrdCcIgDdLUYBXVYAeQYAFYCEAa33dfSMz1CQIDHrowgA+OAAyGcSjy1hgbf2AHkQDFLiYbncHk9Gq8Xrk4ZRvABKah0KTyDGYzGSABKqAwo1QQgkaKxZPJvEUKlUEEJLlGECyniuUCRiXZHM5XK5aPi3P5AsFgrR-gW3XwEGIACsiTA8AZBkKlcrOSK4GBsGg-qhVGk+SqDYa1UlUi0xWk8L1sng8grDfblca4B0unq4Ob8FasjbbHaHf7+U7UMMxm6PZbJn0fYqA7G4GrfTG4-61VBUABHHbANOmgDaSeT9qdeGS8q+hdjxZdqDLBYrKuLwZGoyo9cr9H8AF0622hWi5ko1LTUPTGcyTGYrDY2YXeT3ewK1eHJTLifL5wvuWqNRAtY0dXqN5vVR3Eskw0QLV6fX7jw3T+1OuKtOHr7aj3fEkGQ+MzZfPZG1p5B+n7xqeiagY6p5ppm2aoHmJbmHg3aQUq-aovQFJYdhLCSAIMDWKckg4SRFLUGKSyOM4aBuARjRCPsYpQiybxofQFEslR+qocKp7nukgH9CBoFqtWExTLePGBqeTahgJUzCZ+6GUBxE4rDYVHIDR+GEQxTGPCyk6rKxaKqfoRkaU43FSVufGml6kk2SeiTVgA-OJfSOU57JqrJozufJfSKXe6FAA) | [示例 2](https://www.typescriptlang.org/play/#code/JYWwDg9gTgLgBAFQJ5gKZwGZQiOByGFVAIwgA88AoSgehrgFonmXW32POvnb7k1ejbsJGj21AMYQAdgGd4AUWkxghOAF5ERAHQBJZaigYAhhNQAKANoBdADRwA3pThxgAEwBcWtNoDKMKGBpAHNzAEpKAF8Iyik5eABVWUMNb1Q9AyNTC0slFUI7R2c4aWMQVC9+dP9AkPDbYtQQY2AAG0qdGqDQiOjJGXk4JMMEsDdjGHRNKu0FADdjVoBXCYsZ-UmoZIkYK2KZgAVgCQBrc2GoexmAaVQkAHkMczzVJDCwhpdD41hgRfMZvcQKpzslLmltLcHk8XoR3hFrO9qHQhGI0eiMdxBAAlVAYVqoHaCTEk0mY-pyCAE7StCChC5hFxM5ks1lslkopzs7k83m8lEuQhoLx4CDEABWhJgeE+fLl8u5ArgYGwaF+qFkXi5Cp1uqVLncWrgQoq+HktWCeDgkVlurtfP1JTKpocxqIIvN3StNuK9r97MdTRa7UcbuFZoCXutvv9saZSp9caTLiVUFQAEclsA0544JYY8m-Y68O4ZXAC4W7cXSuUyxXKzri0G2lQG-6ldZ6225SjIhTZFT0rT6WDRuNJozk5yu93+fRBe78GLJTsZTPZ4r58rVYYVBqteuN2zHYbQyaPZGQt7bUee1uXDWXWHTXhPVfrTfb3OWc2Q67zxGFreoeX7xluiagQ6W5ppm2aoLmlglm4eCdpBUHRsSZJYdhnCCP4EzHJhOHEcR1AmkMYKpDM+EqBIAA8JoQBgFGGAAfPKKLkRcqTamhPJKqeb7BJ+fGskqj5eEJImicySq-pJl7BCBaG9mRRAsVAY6rFRnQwAR9GMcxFxaZM7FwJx6nGWM2maLxMliVugmKdJ9nmVuj4APwKRaLn2XJzRtF5cBCcpkG9kAA)
TypeBox 可以将 TypeScript 定义转换为 JSON Schema。Script 函数提供了一种可选的编程语法，用于快速将类型定义转换为 JSON Schema，或者作为 Type.* 构建器的通用替代方案。Script 函数旨在处理各种复杂的 TypeScript 类型级表达式。
### 示例
以下代码使用 Script 函数将 TypeScript 接口解析为 JSON Schema。
```
import Type from 'typebox'
// -------------------------------------------------------------------------------
// Script
// -------------------------------------------------------------------------------
const { User, UserUpdate } = Type.Script(`
interface Entity {
id: string
}
interface User extends Entity {
name: string,
email: string
}
type UserUpdate = Evaluate<
Pick &
Partial>
>
`)
// -------------------------------------------------------------------------------
// Reflect
// -------------------------------------------------------------------------------
console.log(User) // {
// type: 'object',
// properties: {
// id: { type: 'string' },
// name: { type: 'string' },
// email: { type: 'string' }
// },
// required: [
// 'id',
// 'name',
// 'email'
// ]
// }
console.log(UserUpdate) // {
// type: 'object',
// properties: {
// id: { type: 'string' },
// name: { type: 'string' },
// email: { type: 'string' }
// },
// required: ['id']
// }
// -------------------------------------------------------------------------------
// Static
// -------------------------------------------------------------------------------
type User = Type.Static // type User = {
// id: string,
// name: string,
// email: string
// }
type UserUpdate = Type.Static // type UserUpdate = {
// id: string,
// name?: string,
// email?: string
// }
```
## 架构
[文档](https://sinclairzx81.github.io/typebox/#/docs/schema/overview) | [示例 1](https://www.typescriptlang.org/play/?#code/JYWwDg9gTgLgBAZQMYAsCmICGcBmUIhwDkMAnmGgEYQAeA9AM6oaZEBQokscAKuWrnyES-ajXZs6dOAFo58hYqXKVqteo0zJ0gMIEwwADZptszeYuWr8tmyQQAdg3gBVBmihwAvImZYAdHrgRmgAFHwU-gDylABWaEgwoQDebHBwwAAmAFy8-P4IMFDADgDmoQCUADRpcA6YIGi5EWgFRSXl1bUsRs35hcVlKbjQWDC5RD2GRHAAvhVs8wum1qtr61pScAAKmFDuKxtHx6q29k7wAK7unj5uHv67+2HJ6W-vH5-vW+fOcNceXKpdJZCYANgArDgAIyYABMlAAzEgACyZCFoME4ADsmAAHJQAJxIAAMmWhRCqX2pcC2IJycGcg1KNXS9UaEwBUEpNN5fO+0jZDSajPaZVZcCmnJuAAFMgRMCV-PYQDN+by6ZKsL1RczFhV1YajR8trNvHB-JagA) | [示例 2](https://www.typescriptlang.org/play/#code/JYWwDg9gTgLgBAZQMYAsCmICGcBmUIhwDkMAnmGgEYQAeA9AM6oaZEBQbddcAtH-wMFDhI0WPESenbgGECYYABs003pPUbNW-hyQQAdg3gBVBmihwAvImZYAdHPBK0ACgDebOHDIUAXMQhKACs0JBgiABpPODB8ClhgNAZ-Dy8vYAATFO9yNH8iIyhgfQBzIjgAXyi0uH1MEDy4Nxy-YkLissrqtJYlbJ9Ggpgi0sjcaCwYfN7FcoroquioNABHAFdgZay4AG1oryJMsf3iOobjmqIZ9i8AXTYKgEoOLjVtd4+P1QAFTCgzVSfIHAyS6AxGOBrMwWaymcx2X7-VzNGqotHouCvPSGeBQ8wpaKZfIANgArDgAIyYABMlAAzEgACwZUloYk4ADsmAAHJQAJxIAAMGQpYwx6Ne6W27VK3TOgzxUDF4pVqq8ktq9UaMpK3Rm+UVAAEMgRMMU7HoQOU1SqNfq4DqHo8bS7XajXhUrHA7D6gA) | [规范](https://sinclairzx81.github.io/typebox/#/docs/schema/6_specification)
TypeBox 包含一个专为高性能 JIT 验证设计的 JSON Schema 编译器。它还针对 Cloudflare Workers 等 JIT 受限环境提供了自动回退到动态解释检查的功能。该编译器旨在成为基于 JSON Schema 标准的高吞吐量应用程序中 Ajv 的轻量级、符合规范的替代方案。
### 示例
以下代码使用 Schema 子模块编译 TypeBox 类型。
```
import Schema from 'typebox/schema'
// -------------------------------------------------------------------------------
// Compile
// -------------------------------------------------------------------------------
const User = Schema.Compile(Type.Object({
id: Type.String(),
name: Type.String(),
email: Type.String({ format: 'email' })
}))
// -------------------------------------------------------------------------------
// Parse
// -------------------------------------------------------------------------------
const user = User.Parse({ // const user: {
id: '65f1a2b3c4d5e6f7a8b9c0d1', // id: string,
name: 'user', // name: string,
email: 'user@domain.com' // email: string
}) // } = ...
```
## 版本
TypeBox 提供了跨越两代 TypeScript 编译器的两个不同版本。
| TypeBox | TypeScript | 描述 |
| :--- | :--- | :--- |
| 1.x | 6.0 - 7.0+ | **最新版。** 基于 TypeScript 7 原生编译器开发。提供高级类型推断和原生 JSON Schema 2020-12 支持。包含与 `0.x` 类型的向后兼容性。**仅支持 ESM。** |
| 0.x | 5.0 - 6.0 | **LTS。** 基于较旧的 TypeScript 版本开发，并在长期支持下积极维护。同时兼容 **ESM 和 CJS**。问题应提交至 [Sinclair TypeBox](https://github.com/sinclairzx81/sinclair-typebox) 仓库。 |
## 贡献
TypeBox 欢迎社区贡献。请确保在提交 Pull Request 之前先提交 Issue。TypeBox 项目倾向于在接受新功能之前进行公开的社区讨论。标签：GNU通用公共许可证, JSON Schema, MITM代理, Node.js, NPM包, OSV-Scalibr, TypeScript, 代码生成, 元编程, 后端开发, 安全插件, 开源库, 搜索引擎爬虫, 数据验证, 渗透测试工具, 类型安全, 类型构建器, 结构化数据, 运行时类型检查, 静态类型推断