arktype-validation

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

ArkType Validation

ArkType 验证

Overview

概述

ArkType is a TypeScript-native runtime validation library that defines schemas using string expressions mirroring TypeScript syntax, providing editor autocomplete, syntax highlighting, and optimized validators. Use when building type-safe APIs, validating JSON payloads, or replacing Zod with a more TypeScript-idiomatic approach. Not suitable for projects that need Zod ecosystem compatibility or JSON Schema output.

Package:

arktype

ArkType是一款原生支持TypeScript的运行时验证库，它使用镜像TypeScript语法的字符串表达式来定义Schema，提供编辑器自动补全、语法高亮和经过优化的验证器。适用于构建类型安全API、验证JSON负载，或是以更贴合TypeScript风格的方式替代Zod。不适用于需要兼容Zod生态系统或输出JSON Schema的项目。

包：

arktype

Quick Reference

快速参考

Pattern	Usage
`type({ key: "string" })`	Define object schema
`type("string")`	Primitive type
`"string.email"` , `"string.url"`	Built-in string validators
`"string.trim"` , `"string.lower"`	Built-in string morphs (transforms)
`"string.json.parse"`	Parse JSON string to validated object
`"number > 0"` , `"string >= 1"`	Inline constraints
`"string \| number"`	Union types
`"'a' \| 'b' \| 'c'"`	String literal unions
`"string[]"`	Array types
`"key?": "string"`	Optional properties
`"key = 'default'"`	Default values
`.pipe()` , `.to()`	Transform output (morphs)
`.narrow()`	Custom validation (like Zod refine)
`.pick()` , `.omit()`	Object property selection
`.merge()`	Combine object types
`scope({...}).export()`	Named type scopes with cross-references
`type("<t>", { box: "t" })`	Generic type definitions
`type.errors`	Error handling (check `instanceof type.errors` )
`configure()`	Global defaults (from `arktype/config` )
`match()`	Type-safe pattern matching (2.1)
`"+" : "reject"`	Inline undeclared key handling

模式	用法
`type({ key: "string" })`	定义对象Schema
`type("string")`	原始类型
`"string.email"` , `"string.url"`	内置字符串验证器
`"string.trim"` , `"string.lower"`	内置字符串转换（transforms）
`"string.json.parse"`	将JSON字符串解析为经过验证的对象
`"number > 0"` , `"string >= 1"`	内联约束
`"string \| number"`	联合类型
`"'a' \| 'b' \| 'c'"`	字符串字面量联合类型
`"string[]"`	数组类型
`"key?": "string"`	可选属性
`"key = 'default'"`	默认值
`.pipe()` , `.to()`	转换输出（morphs）
`.narrow()`	自定义验证（类似Zod的refine）
`.pick()` , `.omit()`	对象属性选择
`.merge()`	合并对象类型
`scope({...}).export()`	支持交叉引用的命名类型作用域
`type("<t>", { box: "t" })`	泛型类型定义
`type.errors`	错误处理（检查 `instanceof type.errors` ）
`configure()`	全局默认配置（来自 `arktype/config` ）
`match()`	类型安全的模式匹配（2.1版本新增）
`"+" : "reject"`	内联未声明键的处理方式

Common Mistakes

常见错误

Mistake	Fix
`type("string.email()")` with parens	`type("string.email")` (no parens)
Checking errors with `=== null`	Use `instanceof type.errors`
`{ key: "string?" }` for optional	`{ "key?": "string" }` (question mark on key)
Importing from `arktype/types`	Import `type` and `scope` from `"arktype"`
Nested `type()` in string expressions	Use `scope()` for cross-referencing types
Raw `.pipe()` without error handling	Use `.pipe.try()` for operations that can throw
`"string.lowercase"` for case morph	`"string.lower"` (also `"string.upper"` )
Configuring after importing `arktype`	Import `arktype/config` before `arktype`

错误内容	修复方案
带括号的 `type("string.email()")`	`type("string.email")` （不带括号）
使用 `=== null` 检查错误	使用 `instanceof type.errors`
用 `{ key: "string?" }` 表示可选属性	`{ "key?": "string" }` （问号放在键名上）
从 `arktype/types` 导入	从 `"arktype"` 导入 `type` 和 `scope`
在字符串表达式中嵌套 `type()`	使用 `scope()` 实现类型交叉引用
未处理错误的原生 `.pipe()`	对可能抛出异常的操作使用 `.pipe.try()`
用 `"string.lowercase"` 实现大小写转换	`"string.lower"` （同理 `"string.upper"` ）
导入 `arktype` 后再进行配置	先导入 `arktype/config` 再导入 `arktype`

Delegation

职责划分

Use this skill for ArkType schema definitions, runtime validation, morphs/transforms, scopes, and type inference. For Zod-based validation, delegate to the zod-validation skill.

当涉及ArkType Schema定义、运行时验证、转换（morphs/transforms）、作用域和类型推断时使用本技能。对于基于Zod的验证，请委托给zod-validation技能。

References

参考资料

Schema Types — primitives, string keywords, number constraints, objects, arrays, tuples, unions, optional, defaults
Morphs and Scopes — pipe, morph transforms, narrow validation, scopes, recursive types, generics, global configuration, pattern matching
Common Patterns — JSON parsing, form validation, API responses, error handling, comparison with Zod

Schema Types — 原始类型、字符串关键字、数字约束、对象、数组、元组、联合类型、可选属性、默认值
Morphs and Scopes — pipe、转换（morph）、narrow验证、作用域、递归类型、泛型、全局配置、模式匹配
Common Patterns — JSON解析、表单验证、API响应、错误处理、与Zod的对比