名称: typebox 描述: TypeBox 和 TypeMap 用于模式验证的模式。在需要运行时类型验证、JSON Schema 或 Standard Schema 时使用。

TypeBox 和 TypeMap

包名

使用 typebox，而不是 @sinclair/typebox。@sinclair/typebox 包已废弃。

// 正确
import { Type } from 'typebox';
import { Compile } from 'typebox/compile';
import { Value } from 'typebox/value';

// 错误 - 已废弃
import { Type } from '@sinclair/typebox';

何时使用什么

需求	使用
定义模式	`typebox` 使用 `Type.*`
Standard Schema 支持	`@sinclair/typemap`
库之间翻译	`@sinclair/typemap`
高性能验证	任一者的 `Compile()`
一次性验证	`Value.Check()` 来自 typebox

TypeMap 用于 Standard Schema

TypeBox 不原生实现 Standard Schema。使用 TypeMap：

import { Compile } from '@sinclair/typemap';
import { Type } from 'typebox';

// 从 TypeBox 模式
const validator = Compile(
    Type.Object({
        name: Type.String(),
        age: Type.Number(),
    }),
);

// Standard Schema 接口
const result = validator['~standard'].validate({ name: 'Alice', age: 30 });

TypeMap 接受一切

TypeMap 的 Compile() 接受：

import { Compile } from '@sinclair/typemap';

// TypeScript 语法字符串
const v1 = Compile(`{ name: string, age: number }`);

// TypeBox 模式
const v2 = Compile(Type.Object({ x: Type.Number() }));

// Zod 模式
const v3 = Compile(z.object({ x: z.number() }));

// Valibot 模式
const v4 = Compile(v.object({ x: v.number() }));

所有都返回带有 ['~standard'].validate() 的验证器。

TypeBox Compile vs TypeMap Compile

// TypeBox Compile - 返回带有 Check/Parse 的验证器
import { Compile } from 'typebox/compile';
const validator = Compile(schema);
validator.Check(value); // boolean
validator.Parse(value); // 抛出或返回类型化值

// TypeMap Compile - 返回 Standard Schema 验证器
import { Compile } from '@sinclair/typemap';
const validator = Compile(schema);
validator['~standard'].validate(value); // { value } 或 { issues }

需要 Standard Schema 兼容性时使用 TypeMap。不需要时直接使用 TypeBox。

翻译函数

TypeMap 在库之间翻译：

import { Syntax, TypeBox, Zod, Valibot } from '@sinclair/typemap';

const syntax = `{ name: string }`;
const tbSchema = TypeBox(syntax);
const zodSchema = Zod(syntax);
const valibotSchema = Valibot(syntax);
const backToSyntax = Syntax(zodSchema);

性能

TypeMap 的编译验证器比原生 Zod 快约 100 倍：

库	1000 万次迭代
Zod 原生	~4,669 毫秒
TypeMap	~47 毫秒

TypeBox与TypeMap模式验证Skill typebox