# @amazon/vinyl-validation 中文文档

规范地址：https://npmcn.com/package/%40amazon/vinyl-validation/

版本：5\.0\.0
npm 元数据更新时间：2026-11-16T02:15:10.999Z
中文译文更新时间：2026-11-16T02:16:19.505Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40amazon/vinyl-validation
原文对照：https://npmcn.com/package/%40amazon/vinyl-validation/?lang=original
项目主页：https://github.com/amazonmusic/vinyl#readme
源码仓库：https://github.com/amazonmusic/vinyl

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：673 kB，117 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2026-05-27T23:27:16.940Z
- 最新版本发布：2026-11-16T02:15:10.578Z
- 近 30 天下载量：2945（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：44（近 12 个月 44 个）

## 中文简介

基本输入形状验证

## 安装

```sh
npm install @amazon/vinyl-validation
```

也可以使用：`pnpm add @amazon/vinyl-validation`、`yarn add @amazon/vinyl-validation`、`bun add @amazon/vinyl-validation`

## README

# @amazon/ 乙烯认证

[![Website](https://img.shields.io/badge/website-amazonmusic.github.io%2Fvinyl-blue)](https://amazonmusic.github.io/vinyl) [![npm](https://img.shields.io/npm/v/@amazon/vinyl-validation.svg)](https://www.npmjs.com/package/@amazon/vinyl-validation) [![size](https://img.shields.io/bundlejs/size/@amazon/vinyl-validation.svg?label=size)](https://bundlejs.com/?q=@amazon/vinyl-validation)

TypeScript 第一个用于运行时类型检查和计划验证库 审定。 原始、对象、阵列、组合、, 记录、拖累、功能和结合,对结果作出强有力的推断 类型.

## 安装

```shell
npm install @amazon/vinyl-validation
```

## 基本用途

```typescript
import { string, number } from '@amazon/vinyl-validation'

const nameValidator = string().notEmpty()
const ageValidator = number().gte(0)

nameValidator.isValid('John') // true
ageValidator.isValid(-5) // false

// Get validation errors
const errors = nameValidator.validate('')
// [{ message: 'Expected: not empty, but was: "". At: ', path: [] }]
```

## 核心验证器

### 初级类型

```typescript
import { string, number, boolean, symbol, any } from '@amazon/vinyl-validation'

const stringValidator = string()
const numberValidator = number()
const booleanValidator = boolean()
const symbolValidator = symbol()
const anyValidator = any() // accepts any value
```

### 无效和未定义

```typescript
import {
    exactlyNull,
    exactlyUndefined,
    nullish,
} from '@amazon/vinyl-validation'

const nullValidator = exactlyNull() // only null
const undefinedValidator = exactlyUndefined() // only undefined
const nullishValidator = nullish() // null or undefined
```

### 数值匹配

```typescript
import { isOneOf, instanceOf } from '@amazon/vinyl-validation'

const statusValidator = isOneOf('active', 'inactive', 'pending')

const dateValidator = instanceOf(Date)
const errorValidator = instanceOf(Error)
```

## 字符串验证

```typescript
import { string } from '@amazon/vinyl-validation'

const validator = string()
    .notEmpty()
    .minLength(3)
    .maxLength(50)
    .noWhitespace()
    .matches(/^[a-z]+$/)

validator.isValid('hello') // true
validator.isValid('') // false (empty)
validator.isValid('ab') // false (too short)
```

## 数量验证

```typescript
import { number } from '@amazon/vinyl-validation'

const validator = number().gte(0).lte(100).within(1, 99).safeInteger().finite()

validator.isValid(50) // true
validator.isValid(-1) // false (less than 0)
validator.isValid(Infinity) // false (not finite)
```

## 对象验证

```typescript
import {
    object,
    string,
    number,
    isOneOf,
    array,
} from '@amazon/vinyl-validation'

const userValidator = object({
    name: string().notEmpty(),
    age: number().gte(0),
    email: string().matches(/^[^\s@]+@[^\s@]+\.[^\s@]+$/),
})

const user = { name: 'John', age: 30, email: 'john@example.com' }
userValidator.isValid(user) // true

// Extend existing schemas
const adminValidator = userValidator.extend({
    role: isOneOf('admin', 'superadmin'),
    permissions: array(string()),
})
```

## 阵列验证

```typescript
import { array, string, number, tuple, boolean } from '@amazon/vinyl-validation'

const stringArrayValidator = array(string())

const numberArrayValidator = array(number().gte(0))
    .minLength(1)
    .maxLength(10)
    .notEmpty()

// Tuples (fixed-length, positional)
const coordinateValidator = tuple(number(), number()) // [x, y]
const personValidator = tuple(string(), number(), boolean()) // [name, age, active]

stringArrayValidator.isValid(['a', 'b', 'c']) // true
coordinateValidator.isValid([10, 20]) // true
coordinateValidator.isValid([10, 20, 30]) // false (wrong length)
```

## 记录验证

```typescript
import { record, recordValues, string, number } from '@amazon/vinyl-validation'

const scoresValidator = recordValues(number().gte(0))

const configValidator = record(
    string().matches(/^[A-Z_]+$/),
    string().notEmpty()
)

scoresValidator.isValid({ alice: 95, bob: 87 }) // true
configValidator.isValid({ API_KEY: 'secret', DB_URL: 'localhost' }) // true
```

## 设置验证

```typescript
import { set, string } from '@amazon/vinyl-validation'

const tagValidator = set(string().notEmpty())

tagValidator.isValid(new Set(['tag1', 'tag2'])) // true
tagValidator.isValid(new Set(['tag1', ''])) // false (empty string)
```

## 函数验证

```typescript
import { func } from '@amazon/vinyl-validation'

const functionValidator = func().withArity(2).withMinArity(1).withMaxArity(3)

functionValidator.isValid((a, b) => a + b) // true
functionValidator.isValid(() => 'hello') // false (wrong arity)
```

## 可选和可忽略的数值

```typescript
import { string } from '@amazon/vinyl-validation'

const optionalName = string().optional() // allows undefined
const nullableName = string().nullable() // allows null
const maybeName = string().maybe() // allows null or undefined

optionalName.isValid(undefined) // true
nullableName.isValid(null) // true
maybeName.isValid(null) // true
maybeName.isValid(undefined) // true
```

## 组合验证器

### 逻辑

```typescript
import { orValidators, string, number } from '@amazon/vinyl-validation'

const stringOrNumber = orValidators(string(), number())

stringOrNumber.isValid('hello') // true
stringOrNumber.isValid(42) // true
stringOrNumber.isValid(true) // false
```

### 逻辑

```typescript
import { andValidators, string } from '@amazon/vinyl-validation'

const shortUppercaseString = andValidators(
    string().maxLength(10),
    string().matches(/^[A-Z]+$/)
)

shortUppercaseString.isValid('HELLO') // true
shortUppercaseString.isValid('hello') // false (not uppercase)
shortUppercaseString.isValid('VERYLONGSTRING') // false (too long)
```

## 自定义验证器

```typescript
import { custom } from '@amazon/vinyl-validation'

const evenNumberValidator = custom<number>(
    'even number',
    (input): input is number => typeof input === 'number' && input % 2 === 0
)

evenNumberValidator.isValid(4) // true
evenNumberValidator.isValid(3) // false
```

## 验证选项

```typescript
import { string, object } from '@amazon/vinyl-validation'

const validator = object({
    name: string().notEmpty(),
    email: string().matches(/^[^\s@]+@[^\s@]+\.[^\s@]+$/),
})

// Collect all errors (default: stop at first error)
const errors = validator.validate({ name: '', email: 'invalid' }, { all: true })
```

## 处理错误

```typescript
import { ValidationError } from '@amazon/vinyl-util'
import { string } from '@amazon/vinyl-validation'

const validator = string().notEmpty()

try {
    validator.assert('') // throws ValidationError if invalid
} catch (error) {
    if (error instanceof ValidationError) {
        console.log(error.message)
    }
}
```

## 类型脚本集成

```typescript
import { object, string, number, array } from '@amazon/vinyl-validation'

interface User {
    name: string
    age?: number
    tags: string[]
}

const userValidator = object<User>({
    name: string(),
    age: number().optional(),
    tags: array(string()),
})

function processUser(data: unknown) {
    if (userValidator.isValid(data)) {
        console.log(data.name) // typed as string
    }
}
```

## 说明和 JSON Schema 导出

任何计划节点都可以携带人可读的描述 任何计划都可以 导出为 a [杰森·斯克马](https://json-schema.org/) 定义。 这个有用 用于描述一个形状给LLM或另一个消费者,并且工作类似 泽德的 `describe` 财务报告和审定财务报表 `zod-to-json-schema`。 。 。 .

```typescript
import {
    object,
    string,
    number,
    isOneOf,
    toJsonSchema,
} from '@amazon/vinyl-validation'

const userSchema = object({
    name: string().notEmpty().describe('The user full name'),
    age: number().gte(0).lte(120),
    role: isOneOf('admin', 'user').describe('Access level'),
    nickname: string().optional(),
}).describe('A user record')

toJsonSchema(userSchema)
// {
//   type: 'object',
//   properties: {
//     name: { type: 'string', minLength: 1, description: 'The user full name' },
//     age: { type: 'number', minimum: 0, maximum: 120 },
//     role: { enum: ['admin', 'user'], description: 'Access level' },
//     nickname: { type: 'string' },
//   },
//   required: ['name', 'age', 'role'],
//   description: 'A user record',
// }
```

`describe` ;它不影响验证。 可选属性 被删除 `required` 列表中选择一个选项。 工会`or`, (中文(简体) ), `maybe`导出为 `anyOf`, (中文(简体) ), 数组为 `items`,tuples作为位置 `items`,设置为唯一项目数组,以及 记录为输入对象 `additionalProperties`。 。 。 .

## 许可证

阿帕奇 - 2.0

## 常见问题

### @amazon/vinyl-validation 是什么？

基本输入形状验证

### 如何安装 @amazon/vinyl-validation？

在项目目录运行 npm install @amazon/vinyl-validation，或使用 pnpm add / yarn add / bun add。

### @amazon/vinyl-validation 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @amazon/vinyl-validation 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @amazon/vinyl-validation 可以商用吗？

@amazon/vinyl-validation 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @amazon/vinyl-validation 的下载量有多少？

根据 npm 官方下载统计，@amazon/vinyl-validation 在 2026/10/06 – 2026/11/04 这 30 天内被下载 2,945 次，日均约 98 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @amazon/vinyl-validation 还在维护吗？

最新版本 5\.0\.0 发布于 2026/11/16（今天）；至今共发布 44 个版本，其中过去 12 个月发布了 44 个；首次发布于 2026/05/28。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

