Pipelines

管道功能使得对模式进行详细的验证和转换成为可能。特别是对于像 string、number、date、object 和 array 这样的模式函数，此功能对于验证除原始数据类型之外的属性非常有用。

工作原理

简单来说，管道是一系列模式和操作的列表，它们同步地处理输入数据。它必须始终以一个模式开始，后面最多可以跟随 19 个模式或操作。每个模式和操作都可以检查和修改输入。因此，管道非常适合进行详细的验证和转换。

示例

例如，管道功能可以用来修剪字符串，并确保它是一个以特定域名结尾的电子邮件。

import * as v from 'valibot';

const EmailSchema = v.pipe(
  v.string(),
  v.trim(),
  v.email(),
  v.endsWith('@example.com'));

验证

管道验证操作会检查输入，如果输入不符合特定条件，则返回一个问题（issue）。如果输入有效，它将作为输出返回，并（如果存在）被管道中的下一个操作接收。

只要有可能，即使已经出现问题，管道也会完全运行，以收集所有可能的问题。如果你想在第一个问题出现后立即中止管道，你需要将 abortPipeEarly 选项设置为 true。在此处了解更多信息。

验证操作：base64, bic, bytes, check, checkItems, creditCard, cuid2, decimal, digits, email, emoji, empty, endsWith, entries, everyItem, excludes, finite, graphemes, gtValue, hash, hexadecimal, hexColor, includes, integer, ip, ipv4, ipv6, isoDate, isoDateTime, isoTime, isoTimeSecond, isoTimestamp, isoWeek, length, ltValue, mac, mac48, mac64, maxBytes, maxEntries, maxGraphemes, maxLength, maxSize, maxValue, maxWords, mimeType, minBytes, minEntries, minGraphemes, minLength, minSize, minValue, minWords, multipleOf, nanoid, nonEmpty, notBytes, notEntries, notGraphemes, notLength, notSize, notValue, notValues, notWords, octal, parseJson, partialCheck, rawCheck, regex, rfcEmail, safeInteger, size, slug, someItem, startsWith, ulid, , uuid, value, values, words

其中一些操作可以与不同的模式结合使用。例如，minValue 可以用来验证 string、number、bigint 和 date 的最小值。

import * as v from 'valibot';

const StringSchema = v.pipe(v.string(), v.minValue('foo'));
const NumberSchema = v.pipe(v.number(), v.minValue(1234));
const BigintSchema = v.pipe(v.bigint(), v.minValue(1234n));
const DateSchema = v.pipe(v.date(), v.minValue(new Date()));

自定义验证

对于自定义验证，可以使用 check。如果作为第一个参数传递的函数返回 false，则会返回一个问题。否则，输入被认为是有效的。

import * as v from 'valibot';
import { isValidUsername } from '~/utils';

const UsernameSchema = v.pipe(
  v.string(),
  v.check(isValidUsername, '此用户名无效。'));

你可以将管道验证的问题转发给子级。有关更多信息，请参阅方法指南。

转换

管道转换操作允许改变输入值和数据类型。这对于例如移除字符串开头或结尾的空格，或者强制设置最小值或最大值非常有用。

转换操作：brand, filterItems, findItem, flavor, mapItems, rawTransform, readonly, reduceItems, sortItems, toLowerCase, toMaxValue, toMinValue, toUpperCase, transform, trim, trimEnd, trimStart

例如，以下模式的管道强制设置最小值为 10。如果输入小于 10，它将被替换为指定的最小值。

import * as v from 'valibot';

const NumberSchema = v.pipe(v.number(), v.toMinValue(10));

自定义转换

对于自定义转换，可以使用 transform。作为第一个参数传递的函数将以输入数据作为调用参数，其返回值定义了输出。下面的转换将所有小于 10 的数字的模式输出更改为 null。

import * as v from 'valibot';

const NumberSchema = v.pipe(
  v.number(),
  v.transform((input) => (input < 10 ? null : input)));

元数据

除了验证和转换操作，管道还可以用于向模式添加元数据。这在使用 AI 工具或出于文档目的时非常有用。

元数据操作：description, metadata, title

const UsernameSchema = v.pipe(
  v.string(),
  v.regex(/^[a-z0-9_-]{4,16}$/iu),
  v.title('用户名'),
  v.description(
    '用户名必须在 4 到 16 个字符之间，且只能包含字母、数字、下划线和连字符。'
  ));

Schemas

解析数据