配置
开箱即用的出色体验是 ArkType 的核心目标,包括安全的默认设置和针对复杂错误的实用消息。
然而,当您需要不同行为时,能够以适当的粒度轻松配置它同样重要。
级别
| 级别 | 适用对象 | 示例 |
|---|---|---|
| default | 所有 Type 的内置默认值 | |
| global | 应用配置后解析的所有 Type | |
| scope | 在配置的 Scope 中解析的所有 Type | |
| type | 由配置的 Type 浅层引用的所有 Type |
某些选项仅适用于特定级别,如相应的输入类型所反映的。
对于全局配置,请在使用单独文件中的 `"arktype/config"` 入口点!
如果您需要配置应用于内置关键字(对于像 jitless、numberAllowsNaN、dateAllowsInvalid 这样的选项很重要),您应该在从 "arktype" 导入任何内容之前,从 "arktype/config" 导入并使用 configure。
否则,在您的配置应用时,关键字已经被解析!
错误
为了允许自定义错误与复合错误(例如 union 和 intersection)的内置逻辑无缝集成,ArkType 支持一组可组合的选项:
| 可选 | 描述 | 示例 |
|---|---|---|
| description | ✅ 约束的摘要,可以完成“必须是 ___”这样的短语 🥇 被其他元数据重用,并且应该是您自定义消息的首选 | |
| expected | ✅ 一个接受错误上下文的函数,并返回格式为“必须是 ___”的字符串 ✅ 特定于错误,并在这些情况下优先于 | |
| actual | ✅ 一个接受导致错误的数据的函数,并返回格式为“(was ___)”的字符串 ✅ 如果返回空字符串,消息的 actual 部分将被省略 | |
| problem | ✅ 一个接受 ❌ 可能不适用于像 union 这样的复合错误 | |
| message | ✅ 一个接受 ❌ 可能不适用于像 union 这样的复合错误 |
按代码
错误也可以通过其关联的 code 属性在 scope 或 global 级别进行配置。
例如:
ArkErrors
对于像 i18n 这样超出此可组合消息配置范围的用例,验证失败时返回的 ArkErrors 数组包含可以通过像 .hasCode("divisor") 这样的调用进行判别的 ArkError 实例,并且包含特定于该错误类型的上下文数据,以及每个可组合错误部分的 getter。
这些 ArkError 实例可以任意转换并与国际化库组合。这仍然是我们正在调查和记录的主题,因此请随时提出任何问题或反馈!
关键字
像 string.email 这样的内置关键字可以进行全局配置。
这对于在不需要创建自己的别名或包装器的情况下自定义错误消息非常有帮助。
您在这里提供的选项与直接 配置 Type 使用的选项相同,并且也可以 在类型级别扩展以包含自定义元数据。
Clone
默认情况下,在应用 morph 之前,ArkType 将使用内置的 deepClone 函数深度克隆原始输入值,该函数试图对保留原型等做出合理的假设。deepClone 的实现可以在 这里 找到。
您可以将替代的克隆实现提供给 clone 配置选项。
要直接变异输入对象,您可以将 clone 配置选项设置为 false。
onUndeclaredKey
像 TypeScript 一样,ArkType 默认在验证期间忽略未声明的键。然而,它还支持两种额外的行为:
"ignore"(默认):允许输入上的未声明键,在输出上保留它们"delete":允许输入上的未声明键,在返回输出之前删除它们"reject":拒绝带有未声明键的输入
这些行为可以通过内置的 "+" 语法与单个 Type 关联(请参阅 那些文档 以了解它们的工作原理)。您也可以全局更改默认值:
exactOptionalPropertyTypes
默认情况下,ArkType 将可选键验证为 TypeScript 的 exactOptionalPropertyTypes 设置为 true。
查看示例
这种方法允许对可选性进行最细粒度的控制,因为可以将 | undefined 添加到应该接受它的属性。
但是,如果您没有启用 TypeScript 的 exactOptionalPropertyTypes 设置,您可以全局将 ArkType 的 exactOptionalPropertyTypes 配置为 false 以匹配 TypeScript 的行为。如果您这样做,我们建议制定计划在未来启用 exactOptionalPropertyTypes。
exactOptionalPropertyTypes 尚未影响默认值!
对此的支持作为 此更广泛的可配置默认性问题 的一部分进行跟踪。
jitless
默认情况下,当 Type 被实例化时,ArkType 将预编译优化的验证逻辑,该逻辑将在类型被调用时运行。此行为在不支持 new Function 的环境中默认禁用,例如 Cloudflare Workers。
如果您出于其他原因想选择退出,可以将 jitless 配置选项设置为 true。
onFail
在某些领域,您可能总是希望在验证失败时抛出错误,或以其他方式转换结果。
通过在全局配置中指定 onFail,您可以控制在无效数据上调用 Type 时会发生什么:
metadata
还可以将额外的任意元数据与 Type 关联。
甚至可以通过 ArkType 为此目的暴露的接口扩展来使其类型安全:
toJsonSchema
某些 ArkType 功能没有 JSON Schema 等价物。默认情况下,toJsonSchema() 在这些情况下将抛出错误。
此行为可以细粒度配置以匹配您的需求。
fallback 配置的根部也可以指定 default 处理程序:
这些选项也可以在 全局或 scope 级别 设置。
Fallback Codes
这是 toJsonSchema() 可能失败的可配置原因的完整列表。
| Code | 描述 |
|---|---|
arrayObject | 具有对象属性的数组 |
arrayPostfix | 具有后缀元素的数组 |
defaultValue | 非可序列化的默认值 |
domain | 非可序列化的类型关键字(总是 bigint 或 symbol) |
morph | 转换 |
patternIntersection | 多个正则约束 |
predicate | 自定义窄化函数 |
proto | 非可序列化的 instanceof |
symbolKey | 对象上的符号键 |
unit | 非可序列化的 === 引用(例如 undefined) |
date | Date 实例(对于 Date 取代 proto ) |
prototypes
当您 .infer 您的 Type 时,ArkType 会遍历它们并提取像 morphs 这样的特殊值,例如 (In: string) => Out<number>。
虽然通常这能够保留原始类型,但它效率低下,并且可能意外扩展某些对象类型。
您可以使用类型级别的 prototypes 配置来告诉 ArkType 将这些类型视为外部: