schema-dsl
  • 简体中文

      • schema-dsl API 参考文档

      本页是完整公开 API 参考，适合在理解任务型指南后查细节。若只需要更短的 API 入口，请看 API 概览。

      dsl / s 命名空间

      描述

      DSL 主入口命名空间。s 和 dsl 是同一个函数对象：s === dsl。函数调用形式支持字符串和对象两种定义方式；命名空间 factory 提供可发现的链式入口，但底层仍复用同一套 DSL 解析与 builder 契约。公开示例默认使用 schema-dsl/pure + s，避免导入时修改全局原型。

      语法

      s(definition: string | object): IDslBuilder | JSONSchema

s.email(): IDslBuilder
s.string(): IDslBuilder
s.number(): IDslBuilder

      因为 s === dsl，通过任一名字调用同一个对象都保持兼容。文档推荐写法是：s({ ... }) 编写 schema object，s('...') 编写 DSL seed builder，s.xxx() 提供可发现的 factory 入口。dsl 名称继续作为兼容和语义别名保留。

      参数

      • definition (string | object) - DSL定义
        • 字符串：返回 DslBuilder 实例（可链式调用）
        • 对象：返回 JSON Schema 对象

      返回值

      • DslBuilder / IDslBuilder - 当参数为字符串或命名空间 factory 时
      • Object - 当参数为对象时（JSON Schema）

      示例

      import { s } from 'schema-dsl/pure';

// 纯 DSL 字符串：最短 schema object
const schema = s({
  username: 'string:3-32!',
  email: 'email!'
});

// DSL seed：紧凑 DSL + builder 链式方法
s('email!').label('邮箱').pattern(/custom/);

// factory 写法：最完整的 TypeScript 方法发现
s.email().label('邮箱').pattern(/custom/).require();

      命名空间 Factory

      内建 factory 都挂在共享的 s / dsl 命名空间上：

      Factory 分组方法
      基础类型s.string()、s.number()、s.integer()、s.int()、s.boolean()、s.object()、s.array(item?)、s.any()、s.mixed()
      格式与预设s.email()、s.url()、s.uri()、s.uuid()、s.ip()、s.ipv4()、s.ipv6()、s.date()、s.datetime()、s.time()、s.slug()、s.phone(country?)、s.username(preset?)、s.password(preset?)
      枚举与自定义类型桥接s.enum(...values)、s.enum(values)、s.type(name)
      扩展辅助registerExtensions(definitions)、s.defineExtension(definition)、s.registerExtension(definition)

      示例：

      s('email!').label('邮箱')
s.email().label('邮箱').require()
s.array(s.string().require()).min(1)
s.enum('admin', 'user', 'guest')
s.type('tenant-id').require()

      DslBuilder 类

      描述

      Schema 构建器类，支持链式调用添加验证规则。

      构造函数

      new DslBuilder(dslString: string)

      参数:

      • dslString (string) - DSL字符串，如 'string:3-32!'

      方法

      完整链式方法列表

      s('...')、可调用命名空间别名以及 s.email() 等命名空间 factory 都会返回按公开 IDslBuilder 链式契约声明的 DslBuilder。希望紧凑 DSL 加 builder 提示时使用 s('email!')；希望最完整 TypeScript 方法发现时使用 s.email()。直接 String 链式仍可通过 String Extensions 或 transform 使用，但不再作为默认文档入口。完整方法表和入口支持请看 链式字段方法列表。

      分类方法适用对象说明
      通用元信息与消息.label(text)、.description(text)、.messages(map)、.error(map)所有 builder错误标签、字段描述和自定义消息。
      通用约束.pattern(regex, message?)、.format(fmt)、.enum(...values)、.default(value)、.custom(fn)、.require()、.required()、.optional()按方法适用于 string 或所有 builder.require() 是字段必填 alias；条件 API 的 s.if(...).require(field) 仍是另一套 API。
      长度/范围规则.min(n)、.max(n)、.length(n)按基础类型适用于 string、number/integer、arraystring 映射 minLength/maxLength；number 映射 minimum/maximum；array 映射 minItems/maxItems。.length(n) 只属于 builder。
      字符串文本规则.alphanum()、.trim()、.lowercase()、.uppercase()string builder文本归一化与 pattern 辅助。
      字符串格式与模式.slug()、.domain()、.ip()、.base64()、.jwt()、.json()、.dateFormat(fmt)、.after(date)、.before(date)、.dateGreater(date)、.dateLess(date)string builder添加 JSON Schema format、pattern 或 schema-dsl 自定义关键字。
      身份类预设.username(preset?)、.password(strength?)、.phone(country?)、.phoneNumber(country?)、.idCard(country?)、.creditCard(type?)、.licensePlate(country?)、.postalCode(country?)、.passport(country?)string builder预设会组合长度、正则和本地化 pattern 消息。
      数字辅助.precision(n)、.multiple(n)、.port()number/integer builder.multiple(n) 对应标准 JSON Schema multipleOf。
      对象辅助.requireAll()、.strict()object builder添加由 validator 消费的 schema-dsl 对象自定义关键字。
      数组辅助.items(item)、.noSparse()、.includesRequired(items)array builderitems() 接收 DSL 字符串、builder、DSL 对象或 JSON Schema，并会移除数组元素 schema 中的嵌套 _required。
      输出与验证.toSchema()、.toJsonSchema()、.toString()、.validate(data)DslBuilder直接字符串链式调用只暴露 .toSchema() 与 .toJsonSchema()。

      示例：

      s('string').default('active')
s.string().default('active')
s.string().username('5-20').label('用户名').require()
s.number().min(18).max(120).precision(2).multiple(0.5)
s.object().strict().requireAll()
s.array(s.string().require()).min(1).noSparse().includesRequired(['admin'])
s.array({ name: 'string!', quantity: 'number:1-999!' }).min(1)

// 直接字符串链式兼容路径：
// 运行时需要 schema-dsl/register-string、compat/root 或编译期 transform；
// TypeScript 声明需要 schema-dsl/string-types。
'string'.default('active')

      .pattern(regex, message?)

      添加正则表达式验证。

      参数:

      • regex (RegExp | string) - 正则表达式
      • message (string, 可选) - 自定义错误消息

      返回: DslBuilder

      示例:

      s('string:3-32!')
  .pattern(/^[a-zA-Z0-9_]+$/, '只能包含字母、数字和下划线')

      .label(text)

      设置字段标签（用于错误消息）。

      参数:

      • text (string) - 标签文本

      返回: DslBuilder

      示例:

      s('email!').label('邮箱地址')

      .messages(messages)

      自定义错误消息。

      参数:

      • messages (Object) - 错误消息对象
        • 键：错误代码（如 'string.min'）
        • 值：错误消息模板

      返回: DslBuilder

      示例:

      s('string:3-32!')
  .messages({
    'min': '至少{{#limit}}个字符',
    'max': '最多{{#limit}}个字符'
  })

      .description(text)

      设置字段描述。

      参数:

      • text (string) - 描述文本

      返回: DslBuilder

      示例:

      s('url').description('个人主页链接')

      .custom(validator)

      添加自定义验证器。

      参数:

      • validator (Function) - 验证函数
        • 签名：(value) => boolean | string | { error, message } | void
        • 返回 true 表示通过
        • 返回 false、错误消息字符串或错误对象表示失败
        • 同步验证器由 validate() 和 validateAsync() 均执行；异步验证器（返回 Promise）仅由 validateAsync() 执行，validate() 调用时会返回明确的同步错误提示

      返回: DslBuilder

      示例:

      s('string:3-32!')
  .custom((value) => {
    if (value === 'admin') {
      return { error: 'username.exists', message: '用户名已存在' };
    }
  })

      .default(value)

      设置默认值。

      参数:

      • value (any) - 默认值

      返回: DslBuilder

      示例:

      s('string').default('guest')

      .username(preset?)

      用户名验证（自动设置长度和正则）。

      参数:

      • preset (string | Object, 可选) - 预设配置
        • 字符串：'short' | 'medium' | 'long' | '5-20'
        • 对象：{ minLength, maxLength, allowUnderscore, allowNumber }
        • 默认值：'medium' (3-32位)

      返回: DslBuilder

      示例:

      // 默认 medium (3-32位)
s('string!').username()

// 自定义范围
s('string!').username('5-20')

// 使用预设
s('string!').username('short')  // 3-16位

      .password(strength?)

      密码强度验证（自动设置长度和正则）。

      参数:

      • strength (string, 可选) - 强度级别
        • 'weak' - 最少6位
        • 'medium' - 8位，字母+数字（默认）
        • 'strong' - 8位，大小写+数字
        • 'veryStrong' - 10位，大小写+数字+特殊字符

      返回: DslBuilder

      示例:

      s('string!').password('strong')

      .phone(country?)

      手机号验证（自动设置长度和正则）。

      参数:

      • country (string, 可选) - 国家代码
        • 'cn' - 中国（默认）
        • 'us' - 美国
        • 'uk' - 英国
        • 'hk' - 香港
        • 'tw' - 台湾
        • 'international' - 国际格式

      返回: DslBuilder

      注意: phone() 仅适用于 string schema。请使用 s('string!').phone('cn')；在 number schema 上调用会抛错，避免混合残留数字约束和字符串约束。

      示例:

      // 推荐写法
s('string!').phone('cn')

      .toSchema()

      转换为 JSON Schema 对象（含内部标记）。

      返回: Object - JSON Schema 对象（包含 _required、_customMessages、_label 等 schema-dsl 内部字段）

      示例:

      const schema = s('email!').label('邮箱').toSchema();
// { type: 'string', format: 'email', _label: '邮箱', _required: true }

      .toJsonSchema() v1.2.5+

      转换为纯净的 JSON Schema 对象（无内部标记）。

      与 toSchema() 不同，toJsonSchema() 会自动清理所有 schema-dsl 内部标记：

      • 下划线前缀字段：_required、_customMessages、_label、_customValidators、_whenConditions
      • 自定义验证关键字（直接清除）：alphanum、lowercase、uppercase、trim、jsonString、port、requiredAll、strictSchema、noSparse、includesRequired、dateFormat、dateGreater、dateLess、precision
      • exactLength 特殊翻译：不直接清除，而是转换为标准 JSON Schema { minLength: N, maxLength: N }（与 v1 DslBuilder string:N 行为兼容）

      ⚠️ multipleOf 是标准 JSON Schema 字段，不会被清除（v2 修复了 v1 的错误行为）。

      返回的对象可直接嵌入 OpenAPI / JSON Schema 等标准文档中，无需下游再做清理。

      返回: Object - 纯净的 JSON Schema 对象

      适用场景:

      • 生成 OpenAPI 文档
      • 导出给外部系统消费
      • 任何需要标准 JSON Schema 的场景

      示例:

      // 对比 toSchema() 与 toJsonSchema()
const builder = s('string:3-32!').label('用户名').messages({ min: '至少3个字符' });

builder.toSchema();
// { type: 'string', minLength: 3, maxLength: 32, _required: true, _label: '用户名', _customMessages: { min: '至少3个字符' } }

builder.toJsonSchema();
// { type: 'string', minLength: 3, maxLength: 32 }
// 注意：不含 _required、_label、_customMessages 等内部字段

// string:N 单值语法（exactLength → minLength + maxLength）
const exact = s('string:6!');
exact.toSchema();
// { type: 'string', exactLength: 6, _required: true }
exact.toJsonSchema();
// { type: 'string', minLength: 6, maxLength: 6 }
// 注：exactLength 自动翻译为标准 JSON Schema 的 minLength + maxLength（v1 兼容行为）

// enum 示例
const enumBuilder = s('enum:admin,user,guest!');
enumBuilder.toJsonSchema();
// { type: 'string', enum: ['admin', 'user', 'guest'] }

// 用于 OpenAPI 文档生成
const schema = s({
  username: 'string:3-32!',
  email: 'email!',
  age: 'number:0-120'
});
// 遍历各字段调用 toJsonSchema() 即可获得标准 JSON Schema

      .validate(data)

      验证数据（便捷方法）。

      参数:

      • data (any) - 待验证数据

      返回: Promise - 验证结果

      • valid (boolean) - 是否通过
      • errors (Array, 可选) - 错误列表
      • data (any, 可选) - 验证通过的数据

      示例:

      const result = await s('email!').validate('user@example.com');
console.log(result.valid); // true

      静态方法

      s.match(field, map)

      创建条件验证规则（类似 switch-case）。

      参数:

      • field (string) - 依赖的字段名
      • map (Object) - 值与Schema的映射
        • [value: string]: 对应的Schema
        • _default (optional): 默认Schema

      返回: Object - 内部Match结构

      示例:

      s.match('type', {
  email: 'email!',
  phone: 'string:11!',
  _default: 'string'
})

      s.if(condition, thenSchema, elseSchema)

      创建简单的条件验证规则。

      参数:

      • condition (string) - 条件字段名
      • thenSchema (string|Object) - 满足条件时的Schema
      • elseSchema (string|Object, 可选) - 不满足条件时的Schema

      返回: Object - 内部If结构

      示例:

      s.if('isVip', 'number:0-50', 'number:0-10')

      运行时辅助函数

      VERSION

      根模块导出的当前包版本号。该值从 package.json 读取，因此会与发布包版本保持一致。

      import { VERSION } from 'schema-dsl/pure';

console.log(VERSION);

      s.config(options)

      全局配置入口，在应用启动时调用一次，设置 i18n、缓存、自定义正则和严格类型解析模式。

      import { s } from 'schema-dsl/pure';

s.config({
  // i18n：内置语言包路径 / 内联 locale bundle / { localesPath } / { locales }
  i18n: './locales',

  // 目录加载默认保留 .js/.cjs 兼容行为。
  // 当 locale 目录不是可信代码来源时，使用 'deny' 仅加载 JSON 系列文件。
  codeLocaleFiles: 'deny',

  // 默认语言（默认 'en-US'）
  defaultLocale: 'zh-CN',

  // 编译缓存配置
  cache: { maxSize: 2000, ttl: 0, enabled: true },

  // strict: true → 遇到未知类型直接抛出 Error（默认 false：warn + 回退 string）
  strict: true,

  // 追加自定义正则规则（phone / idCard / creditCard 等）
  patterns: {
    phone: { us: /^\+1\d{10}$/ }
  }
});

      参数 (DslConfigOptions):

      字段类型默认说明
      i18nstring | object—语言包路径或内联对象
      codeLocaleFiles'allow' | 'deny''allow'目录加载时是否允许执行 .js / .cjs 语言包
      defaultLocalestring'en-US'默认语言
      cacheCacheOptions—maxSize / ttl / enabled / statsEnabled
      strictbooleanfalsetrue 时解析未知 DSL 类型抛出 Error
      patternsobject—追加自定义格式正则（phone/idCard/creditCard）

      getDefaultValidator()

      获取顶层 validate() / validateAsync() 便捷函数内部复用的默认 Validator 单例。

      import { getDefaultValidator } from 'schema-dsl/pure';

const validator = getDefaultValidator();
console.log(validator.getCacheStats());

      resetDefaultValidator()

      重置顶层 validate() / validateAsync() 使用的默认 Validator 单例。

      import { resetDefaultValidator } from 'schema-dsl/pure';

resetDefaultValidator();

      resetRuntimeState()

      重置测试、worker 或多租户隔离进程中可能共享的运行时状态：默认 validator 单例、自定义类型、locale 状态、严格解析模式，以及运行期追加的 pattern key。

      import { resetRuntimeState } from 'schema-dsl/pure';

resetRuntimeState();

      installStringExtensions(dslFunction?)

      为有意使用 'string!'.description(...) 这类直接字符串链式写法的项目安装或重新安装 String 扩展。普通文档示例不需要这个 API，因为默认从 schema-dsl/pure + s 开始。

      import { installStringExtensions } from 'schema-dsl/pure';

installStringExtensions();

      uninstallStringExtensions()

      卸载挂载到 String.prototype 上的扩展方法。它主要用于测试清理、兼容回归或旧代码检查。普通代码如果不希望修改全局原型，应一开始就导入 schema-dsl/pure，并使用 s('...') 或 s.xxx() 完成链式调用。

      import { uninstallStringExtensions } from 'schema-dsl/pure';

uninstallStringExtensions();

      包入口与编译期转换

      schema-dsl/pure

      无副作用 root 核心 API 的稳定兼容别名。schema-dsl 与 schema-dsl/pure 都不会安装 String.prototype 扩展；它们不会隔离 Locale、TypeRegistry、PATTERNS 或 Validator 状态，需要运行时状态隔离时请使用 schema-dsl/runtime。

      import { s, validate } from 'schema-dsl/pure';

const schema = s({
  email: s.email().description('登录邮箱').require()
});

const result = validate(schema, { email: 'user@example.com' });

      schema-dsl/compat 与 schema-dsl/register-string

      schema-dsl/compat 保留 v1/v2 直接 String 链式兼容行为，导入时会安装 String 扩展。schema-dsl/register-string 是在应用启动阶段注册同一 API 的显式副作用入口；root 入口保持无副作用。

      import 'schema-dsl/register-string';
import { s } from 'schema-dsl/pure';

const schema = s({
  email: 'email!'.description('登录邮箱')
});

      schema-dsl/string-types

      String 链式写法的 TypeScript 类型声明入口。导入该入口只扩展 TypeScript 的 String 接口，不会安装运行时 String.prototype 扩展。

      import { s } from 'schema-dsl/pure';
import 'schema-dsl/string-types';

const field = 'email!'.label('邮箱').require();
const schema = s({ email: field });

      transformSchemaDsl(source, options?)

      在编译期改写静态 String 链式 DSL 调用，并注入来自 schema-dsl/pure 的 dsl 导入。默认覆盖完整内建 String 链式 API，包括 .label()、.pattern()、.require()、.required()、.toJsonSchema() 等方法，也支持 "admin|user|guest".label("角色") 这类裸 pipe 枚举。用户自定义链式方法通过 additionalMethods 追加；已注册的自定义 DSL 类型字面量可通过 additionalTypes / additionalTypePatterns 显式加入转换范围，例如 "tenant-id!".label("租户")；methods 保持为旧版替换集合，只在你明确要覆盖默认内建方法列表时使用。

      该入口会懒加载 Babel AST 包。调用 transformSchemaDsl() 的项目需要安装 @babel/parser、@babel/traverse、@babel/generator 和 @babel/types。缺少任一 peer 时，首次转换会抛出公开导出的 BabelPeerDependencyError，错误码为 SCHEMA_DSL_BABEL_PEER_MISSING；源码解析失败仍遵循普通 warning 或 strict 模式抛错契约。

      import { transformSchemaDsl } from 'schema-dsl/transform';

const result = transformSchemaDsl(
  'export const field = "admin|user|guest".label("角色")',
  { filename: 'schema.ts' }
);

console.log(result.changed);
console.log(result.code);

      选项:

      字段类型默认值说明
      filenamestring'<unknown>'用于解析模式、source map 和 warning 的文件名
      sourceMap`boolean'inline'`false
      importFromstring'schema-dsl/pure'注入 dsl helper 时使用的导入来源
      methodsreadonly string[]完整内建 String 扩展方法列表允许被编译期改写的链式方法名替换集合
      additionalMethodsreadonly string[][]追加用户自定义链式方法
      additionalTypesreadonly string[][]追加允许被改写的已注册自定义 DSL 类型名
      additionalTypePatternsreadonly (RegExp | string)[][]当自定义类型名由约定或生成规则决定时，用模式匹配允许改写的 DSL 类型字面量
      include(filename) => boolean-可选文件过滤器
      strict`booleanobject`false
      onWarning(warning) => void-接收解析失败、root 入口残留、跳过字面量和未配置扩展方法 warning

      返回值:

      {
  code: string,
  changed: boolean,
  warnings: Array<{ code: string, message: string, filename?: string, loc?: object }>,
  map?: object
}

      schemaDslEsbuildPlugin(options?)

      把 transformSchemaDsl() 接入 esbuild 插件流程。esbuild 是可选 peer dependency，只有使用该适配器的项目需要安装。

      import { build } from 'esbuild';
import { schemaDslEsbuildPlugin } from 'schema-dsl/esbuild';

await build({
  entryPoints: ['src/schema.ts'],
  bundle: true,
  outfile: 'dist/schema.js',
  plugins: [schemaDslEsbuildPlugin()]
});

      该适配器只转换 file namespace 下的 JavaScript/TypeScript 源文件，跳过 node_modules，并把虚拟模块交给其所属插件处理。

      Runtime 适配器

      schema-dsl/runtime 为框架、多应用和多租户场景提供显式适配器。它不会安装 String.prototype 扩展，也不会修改 root 入口的 Locale、TypeRegistry、PATTERNS、默认 Validator 或默认 validator engine 实例。

      该入口主工厂为 createRuntime()。createSchemaDslRuntime() 与 createSchemaDslAdapter() 是等价别名，适合偏 adapter 命名的集成场景。

      import { createRuntime } from 'schema-dsl/runtime';

const runtime = createRuntime({
  locale: 'tenant-a',
  messages: {
    'tenant.user.missing': {
      code: 'TENANT_USER_MISSING',
      message: 'Tenant user {{#id}} is missing'
    }
  },
  types: {
    tenantId: { type: 'string', pattern: '^tenant_[a-z0-9]+$' }
  },
  patterns: {
    phone: {
      zz: { pattern: /^ZZ-\d{2}$/, min: 5, max: 5, key: 'pattern.phone.zz' }
    }
  },
  messageProvider: ({ key, locale, fallback }) =>
    key === 'number.min' ? `[${locale}] {{#label}} must be >= {{#limit}}` : fallback
});

const schema = runtime.s({
  id: 'tenantId!',
  phone: 'phone:zz',
  age: 'number:18-120'
});

const chainSchema = runtime.s.email().label('登录邮箱').require().toSchema();

const result = runtime.validate(schema, {
  id: 'tenant_demo',
  phone: 'ZZ-12',
  age: 16
});
      方法说明
      runtime.s(string)返回隔离的 DslBuilder，保留链式方法 TypeScript 提示。
      runtime.s(object)使用当前 runtime 的类型与 pattern 作用域编译对象 DSL。
      runtime.sruntime.dsl 的别名；runtime.s === runtime.dsl 为 true。runtime.s.email() 等 namespace factory 使用同一个 runtime 作用域。
      runtime.compile(definition)使用当前 runtime 作用域编译字符串或对象 DSL。
      runtime.compileField(string)返回隔离的链式字段 builder。
      runtime.configure(options, control?)更新 runtime messages、类型作用域、patterns、strict mode 或 validator 选项。merge 是增量合并，replace 替换完整 runtime 本地 profile，reset 清空后再应用 options。
      runtime.registerExtensions(definitions)按一份定义批量注册 runtime 作用域扩展，并返回带 typed factory 的 runtime namespace。
      runtime.registerExtension(definition)注册 runtime 作用域内的自定义 DSL 扩展和可选 namespace factory；适合动态注册或静态扩展兼容场景。
      runtime.registerType(name, schema)添加或替换 runtime 内部 custom type。
      runtime.registerDynamicType(name, factory)添加或替换 runtime 内部 dynamic type factory。
      runtime.unregisterType(name)移除 runtime 内部 custom/dynamic type。
      runtime.clearCache()清理 runtime 持有的 validator 缓存。
      runtime.getStats()返回生命周期、messages、type、pattern 和 validator cache 统计。
      runtime.dispose()幂等释放 runtime 内部 maps 与 caches；dispose 后继续使用会抛出清晰错误。
      runtime.validate(schema, data, options?)使用 runtime 内部 messages、messageProvider、validator 实例和 custom keyword 消息进行验证。
      runtime.validateAsync(schema, data, options?)使用同一套隔离状态进行异步验证。
      runtime.createI18nError(key, params?, statusCode?, localeOrOptions?)创建不读取全局 Locale 状态的 I18nError。

      messageProvider 接收 { key, params, locale, source, fallback }，其中 source 可能是 ajv、customKeyword、conditional、customValidator、i18nError 或 runtime。它覆盖标准 validator 错误表、custom keyword 消息、条件校验消息、异步 custom validator fallback 消息和 runtime 创建的 I18nError。显式传入的 messages 优先级仍高于 provider fallback。

      runtime.validate() 和 runtime.validateAsync() 支持与 root helper 相同的单次调用错误选项。当 runtime 调用需要拒绝数字或布尔字符串、不要使用 schema-dsl smart coercion 时，可传 { coerce: false }、{ smartCoerce: false } 或 { coerceTypes: false }。

      runtime 应在 app、plugin 或 worker 生命周期边界创建。请求级 locale/messages/messageProvider 应通过 validate(..., { locale, messages, messageProvider }) 传入，不要每个请求新建 runtime。

      与 schema-dsl/pure 的边界

      schema-dsl/pure 只避免自动安装 String.prototype 扩展，仍沿用 root API 的全局运行时状态。要隔离 Locale、TypeRegistry、PATTERNS 和 validator 状态，请使用 schema-dsl/runtime。

      Validator 类

      参数:

      • options (Object, 可选) - Validator 配置项

      Validator 以 Draft 7 作为 JSON Schema 基础方言，并额外执行 minContains / maxContains 等部分较新 applicator 关键字。这是定向运行时扩展，不表示完整支持 Draft 2019-09 或 2020-12。

      方法

      .compile(schema, cacheKey?)

      编译 Schema 为可复用验证函数。

      参数:

      • schema (Object) - JSON Schema
      • cacheKey (string | null, 可选) - 缓存键

      返回: Function - 可复用验证函数

      示例:

      const validator = new Validator();
const validate = validator.compile(schema, 'user-schema');
const ok = validate(data);

      .validate(schema, data, options?)

      同步验证。

      参数:

      • schema (Object | Function) - JSON Schema 或已编译的验证函数
      • data (any) - 待验证数据
      • options (Object, 可选) - 验证选项

      返回: Object

      • valid (boolean) - 是否通过
      • errors (Array, 可选) - 错误列表
      • data (any, 可选) - 经过处理后的数据

      示例:

      const validator = new Validator();
const result = validator.validate(schema, payload);
console.log(result.valid);

      .validateAsync(schema, data, options?)

      异步验证。验证失败时抛出 ValidationError。

      参数:

      • schema (Object | Function) - JSON Schema 或已编译的验证函数
      • data (any) - 待验证数据
      • options (Object, 可选) - 验证选项

      返回: Promise - 验证通过后的数据

      示例:

      const validator = new Validator();
await validator.validateAsync(schema, payload);

      .validateBatch(schema, dataArray)

      批量验证。Schema 只编译一次，多次复用。

      参数:

      • schema (Object) - JSON Schema
      • dataArray (Array) - 待验证数据数组

      返回: Array - 每项对应一个验证结果

      示例:

      const validator = new Validator();
const results = validator.validateBatch(schema, records);

      .addKeyword(keyword, definition)

      添加自定义 validator 关键字。

      参数:

      • keyword (string) - 关键字名称
      • definition (Object) - validator 关键字定义

      返回: Validator

      示例:

      const validator = new Validator();
validator.addKeyword('isEven', {
  type: 'number',
  validate: (_schema, data) => data % 2 === 0
});

      .addFormat(name, validator)

      添加自定义 validator 格式。

      参数:

      • name (string) - 格式名称
      • validator (Function | Object) - format 定义

      返回: Validator

      示例:

      const validator = new Validator();
validator.addFormat('phone-cn', /^1[3-9]\d{9}$/);

      .addSchema(uri, schema)

      添加 schema 引用。

      参数:

      • uri (string) - schema 标识
      • schema (Object) - JSON Schema

      返回: Validator

      示例:

      const validator = new Validator();
validator.addSchema('user.schema.json', schema);

      .removeSchema(uri)

      删除 schema 引用。

      参数:

      • uri (string) - schema 标识

      返回: Validator

      示例:

      const validator = new Validator();
validator.removeSchema('user.schema.json');

      .getAjv()

      获取底层 AJV 实例。

      返回: Ajv

      示例:

      const validator = new Validator();
const ajv = validator.getAjv();

      .clearCache()

      清空编译缓存。

      返回: void

      示例:

      const validator = new Validator();
validator.clearCache();

      .getCacheStats()

      获取缓存统计信息。

      返回: Object

      示例:

      const validator = new Validator();
console.log(validator.getCacheStats());

      静态方法

      Validator.create(options?)

      创建 Validator 实例。

      返回: Validator

      示例:

      const validator = Validator.create();

      Validator.quickValidate(schema, data)

      快速验证。

      参数:

      • schema (Object) - JSON Schema
      • data (any) - 待验证数据

      返回: boolean

      示例:

      const ok = Validator.quickValidate(schema, data);

      Validator.clearQuickValidateCache()

      清理静态 quickValidate() AJV schema cache，并释放其 singleton AJV 实例。下一次调用 quickValidate() 时会懒加载重建。

      Validator.getQuickValidateCacheStats()

      返回静态 quickValidate() schema cache 的 { size, maxSize }。

      导出器

      BaseExporter

      用于自定义导出器子类的抽象基类。内置导出器继承它的通用 options 保存和 schema 断言辅助方法；业务代码通常直接使用 MongoDBExporter、MySQLExporter、PostgreSQLExporter 或 MarkdownExporter。

      import { BaseExporter } from 'schema-dsl/pure';

console.log(typeof BaseExporter); // 'function'

      MongoDBExporter

      导出为 MongoDB 验证Schema。

      import { MongoDBExporter } from 'schema-dsl/pure';

const exporter = new MongoDBExporter({ strict: true });
const mongoSchema = exporter.export(jsonSchema);
const command = exporter.generateCommand('users', jsonSchema);

      方法:

      • export(schema) - 导出为MongoDB Schema
      • exportWithReport(schema, options?) - 导出 MongoDB Schema，并报告目标格式无法表示的 JSON Schema 关键字
      • generateCommand(collection, schema) - 生成 createCollection 命令

      exportWithReport() 返回 { output, losses }；每个 loss 包含 path、keyword、severity 和 message。传入 { strict: true } 时会直接抛错，而不是返回有信息丢失的输出。

      Boolean JSON Schema 的报告会按目标能力判断：Markdown 可表达 true / false，MongoDB 可表达 true 但会报告 false，SQL exporter 对两者都会产生 $booleanSchema loss。

      MySQLExporter

      导出为 MySQL DDL。

      import { MySQLExporter } from 'schema-dsl/pure';

const exporter = new MySQLExporter();
const ddl = exporter.export('users', jsonSchema);

      方法:

      • export(tableName, schema) - 导出为MySQL DDL
      • exportWithReport(tableName, schema, options?) - 导出 DDL 并返回 { output, losses }；设置 strict: true 时，遇到会被省略的关键字会抛错

      每个 loss 包含 path、keyword、severity 和 message。

      PostgreSQLExporter

      导出为 PostgreSQL DDL。

      import { PostgreSQLExporter } from 'schema-dsl/pure';

const exporter = new PostgreSQLExporter();
const ddl = exporter.export('users', jsonSchema);

      方法:

      • export(tableName, schema) - 导出为PostgreSQL DDL
      • exportWithReport(tableName, schema, options?) - 导出 DDL 并返回 { output, losses }；设置 strict: true 时，遇到会被省略的关键字会抛错

      每个 loss 包含 path、keyword、severity 和 message。

      工具函数

      TypeConverter

      类型转换工具。

      import { TypeConverter } from 'schema-dsl/pure';

TypeConverter.toJSONSchemaType('string');
TypeConverter.toMongoDBType('integer');

      SchemaHelper

      Schema辅助工具。

      import { SchemaHelper } from 'schema-dsl/pure';

SchemaHelper.merge(schema1, schema2);
SchemaHelper.clone(schema);

      ErrorFormatter

      验证错误格式化工具，用于把原始 validator 错误数组或简化错误对象转换成统一的错误项结构或消息文本。

      import { ErrorFormatter } from 'schema-dsl/pure';

const formatter = new ErrorFormatter('zh-CN');
const errors = formatter.formatDetailed(ajvValidate.errors);
console.log(errors[0].message);

      方法:

      • new ErrorFormatter(locale?, messages?) - 创建错误格式化器
      • format(error, locale?) - 格式化单个错误为消息字符串
      • formatDetailed(errors, locale?, customMessages?, alreadyMerged?) - 格式化错误数组为标准错误项列表

      MessageTemplate

      错误消息模板封装类，内部委托 renderTemplate() 执行占位符替换。

      import { MessageTemplate } from 'schema-dsl/pure';

const template = new MessageTemplate('{{#label}} is required');
console.log(template.render({ label: 'Email' }));

      方法:

      • new MessageTemplate(template) - 创建模板实例
      • render(context) - 渲染当前模板
      • MessageTemplate.render(template, context) - 静态快速渲染
      • MessageTemplate.renderBatch(templates, context) - 批量渲染多个模板

      renderTemplate(template, params)

      底层模板渲染函数，同时兼容 {{#key}} 和 {key} 两种占位符格式。

      import { renderTemplate } from 'schema-dsl/pure';

const msg = renderTemplate('{field} must be {min}~{max}', {
  field: 'age',
  min: 18,
  max: 65,
});

console.log(msg); // age must be 18~65

      JSONSchemaCore

      JSONSchemaCore 是 v1 兼容外观类，用于以链式方式构建 JSON Schema，并可直接调用 validate() 做快速校验。

      import { JSONSchemaCore } from 'schema-dsl/pure';

const schema = new JSONSchemaCore()
  .type('object')
  .property('email', { type: 'string', format: 'email' })
  .required('email')
  .getSchema();

      常用方法:

      • type(typeName)
      • property(name, schema)
      • properties(properties)
      • required(fields)
      • format(formatName)
      • pattern(pattern)
      • items(schema)
      • toSchema() / getSchema()
      • validate(data)

      类型注册与内部解析边界

      schema-dsl 的 root API 只保留业务可依赖的稳定入口。DSL 解析器、约束解析器、Schema 编译器和 Adapter 属于内部实现细节，不再作为 root API 文档化导出；业务代码应优先使用 s()、DslBuilder、Validator 和 validate()。

      TypeRegistry

      统一类型注册表。它是自定义类型扩展的公开入口；如果只需要注册 DSL 类型，也可以优先使用更高层的 DslBuilder.registerType()。

      • TypeRegistry.resolve(typeName)
      • TypeRegistry.register(name, def)
      • TypeRegistry.registerDynamic(name, factory)
      • TypeRegistry.unregister(name)
      • DslBuilder.unregisterType(name) — 同时从 Builder 侧自定义类型表和 TypeRegistry 移除一个自定义类型
      • TypeRegistry.has(typeName)
      • TypeRegistry.getInternalKeys()
      • TypeRegistry.toJsonSchema(schema)
      • TypeRegistry.clearCustomTypes() — 清空所有自定义类型（含通过 TypeRegistry.register() / DslBuilder.registerType() 注册的类型），适合测试后清理状态
      • TypeRegistry.setStrict(flag) — 设置严格模式，等效于 s.config({ strict: flag })

      DSL 语法快速参考

      基本类型

      string, number, integer, boolean
email, url, uuid, date, datetime

      约束

      string:N            # 精确长度（exactLength = N，等同于 minLength: N, maxLength: N）
string:min-max      # 字符串长度范围
number:min-max      # 数字范围
value1|value2       # 枚举
!                   # 必填

      数组

      array<type>         # 数组
array<string:1-50>  # 带约束的数组元素

      示例

      'string:3-32!'              // 必填字符串，长度3-32
'email!'                    // 必填邮箱
'number:18-120'             // 可选数字，范围18-120
'active|inactive|pending'   // 枚举
'array<string:1-20>'        // 字符串数组

      常量

      VERSION

      与 package.json 版本一致的字符串导出。

      import { VERSION } from 'schema-dsl/pure';

console.log(VERSION);

      VALIDATION, CACHE, FORMATS, CONSTANTS

      命名常量以及聚合命名空间 CONSTANTS。常规代码可优先使用命名导出；需要遍历所有常量分组时可使用 CONSTANTS。

      import { VALIDATION, CACHE, FORMATS, CONSTANTS } from 'schema-dsl/pure';

console.log(VALIDATION.MAX_RECURSION_DEPTH);
console.log(CACHE.ENABLED);
console.log(FORMATS.BUILT_IN.includes('email'));
console.log(CONSTANTS.FORMATS === FORMATS);

      PATTERNS, PATTERN_IPV4, PATTERN_IPV6

      可复用的正则分组和 IPv4/IPv6 辅助正则，供内置 format 与自定义验证场景使用。

      import { PATTERNS, PATTERN_IPV4, PATTERN_IPV6 } from 'schema-dsl/pure';

console.log(Object.keys(PATTERNS.phone));
console.log(PATTERN_IPV4.test('127.0.0.1'));
console.log(PATTERN_IPV6.test('::1'));

      ErrorCodes

      错误代码常量。

      import { ErrorCodes } from 'schema-dsl/pure';

console.log(ErrorCodes.STRING_MIN);     // 'string.min'
console.log(ErrorCodes.NUMBER_RANGE);   // 'number.range'

      Locale

      多语言支持。

      import { Locale } from 'schema-dsl/pure';

Locale.setLocale('zh-CN');  // 设置中文
Locale.setLocale('en-US');  // 设置英文

      ConditionalBuilder

      s.if(conditionFn) 返回的链式条件构建器，适用于运行时动态条件校验。

      常用方法:

      • if(condition)
      • and(condition)
      • or(condition)
      • elseIf(condition)
      • message(msg)
      • then(schema)
      • else(schema)
      • toSchema()
      • build() - toSchema() 的别名
      • validate(data, options?)
      • validateAsync(data, options?)
      • assert(data, options?)
      • check(data)

      更完整的示例和行为说明请参考 conditional-api.md。

      v1 兼容根导出

      v2 是基于 v1 JavaScript 线的 TypeScript 重构。以下根导出仍属于兼容面，即使大多数业务代码会通过更高层 API 间接使用它们。

      导出用途更多说明
      VERSION与 package.json 对齐的运行时包版本字符串。本页
      CONSTANTS验证、缓存、格式和插件常量命名空间；VALIDATION、CACHE、FORMATS、PATTERNS、PATTERN_IPV4、PATTERN_IPV6 等也提供命名导出。本页
      BaseExporter自定义导出器子类使用的抽象基类。本页
      CacheManagerValidator 使用的 LRU/TTL 缓存，也可用于手动缓存场景。cache-manager.md
      CustomKeywords注册 schema-dsl 自定义 validator 关键字。多数应用通过 Validator 间接使用。add-keyword.md
      I18nError国际化业务错误工具，提供 create()、throw()、assert()、is() 和 toJSON()。error-handling.md
      PluginManagerv1 兼容插件流程使用的插件注册与 hook 管理器。plugin-system.md
      resetRuntimeState用于测试和 worker 清理的全局运行时状态重置工具。本页

      对应示例 api-reference.ts 会运行这些导出，npm run examples:run 可用于捕获 API reference 漂移。

      完整示例

      import { s, Validator } from 'schema-dsl/pure';

// 定义 Schema：纯 DSL + s(...) builder
const userSchema = s({
  username: s('string:3-32!')
    .pattern(/^[a-zA-Z0-9_]+$/)
    .messages({
      'string.pattern': '只能包含字母、数字和下划线'
    })
    .label('用户名'),
  
  email: s('email!')
    .label('邮箱地址'),
  
  password: s('string:8-64!')
    .pattern(/^(?=.*[a-z])(?=.*[A-Z])(?=.*\d).+$/)
    .label('密码'),
  
  age: 'number:18-120',
  role: 'user|admin|moderator'
});

// 验证数据
const validator = new Validator();
const result = validator.validate(userSchema, {
  username: 'john_doe',
  email: 'john@example.com',
  password: 'Password123',
  age: 25,
  role: 'user'
});

console.log(result.valid); // true

      更多资源

      对应示例文件

      示例入口: api-reference.ts
      说明: 覆盖 s()、validate()、validateAsync()、默认 Validator 单例、CacheManager、CustomKeywords、I18nError、PluginManager、CONSTANTS、模板渲染、JSONSchemaCore、ErrorFormatter、ObjectDslBuilder 与 TypeRegistry 等公开 API 的可运行调用链。