Пайплайны

Для подробной проверки и преобразования данных схему можно обернуть в пайплайн. Эта возможность особенно полезна для таких схем, как 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')
);

Проверки

Действия проверки в пайплайне проверяют входные данные и возвращают ошибку, если они не соответствуют определённому условию. Если входные данные корректны, они возвращаются в качестве результата и, если следующее действие есть, передаются ему.

По возможности пайплайны выполняются полностью, даже если возникла ошибка, чтобы собрать все возможные ошибки. Чтобы прервать пайплайн сразу после первой ошибки, задайте для параметра abortPipeEarly значение true. Подробнее о настройке разбора данных или используйте метод config для более точного управления отдельными пайплайнами.

Действия проверки: base64, bic, bytes, check, checkItems, codePoints, creditCard, cuid2, decimal, digits, domain, email, emoji, empty, endsWith, entries, everyItem, excludes, finite, graphemes, gtValue, hash, hexadecimal, hexColor, includes, integer, ip, ipv4, ipv6, isbn, isrc, isoDate, isoDateTime, isoDateTimeSecond, isoTime, isoTimeSecond, isoTimestamp, isoWeek, ksuid, length, ltValue, mac, mac48, mac64, maxBytes, maxCodePoints, maxEntries, maxGraphemes, maxLength, maxSize, maxValue, maxWords, mimeType, minBytes, minCodePoints, minEntries, minGraphemes, minLength, minSize, minValue, minWords, multipleOf, nanoid, nonEmpty, notBytes, notCodePoints, notEntries, notGraphemes, notLength, notSize, notValue, notValues, notWords, octal, parseJson, partialCheck, rawCheck, regex, rfcEmail, safeInteger, size, slug, someItem, startsWith, ulid, url, 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, 'This username is invalid.')
);

Ошибки проверки пайплайна можно передать дочернему элементу. Подробнее см. в руководстве по методам.

Преобразования

Действия преобразования в пайплайне позволяют изменять значение и тип входных данных. Это может быть полезно, например, чтобы удалить пробелы в начале или конце строки либо задать минимальное или максимальное значение.

Действия преобразования: brand, filterItems, findItem, flavor, guard, mapItems, rawTransform, readonly, reduceItems, sortItems, toBigint, toBoolean, toCamelCase, toDate, toKebabCase, toLowerCase, toMaxValue, toMinValue, toNumber, toPascalCase, toSnakeCase, toString, toUpperCase, transform, trim, trimEnd, trimStart

Например, пайплайн следующей схемы устанавливает минимальное значение 10. Если входное значение меньше 10, оно заменяется указанным минимальным значением.

import * as v from 'valibot';

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

Пользовательское преобразование

Для пользовательских преобразований можно использовать transform. Функция, переданная первым аргументом, вызывается с входными данными, а её возвращаемое значение определяет результат. Следующее преобразование изменяет результат схемы на null для любого числа меньше 10.

import * as v from 'valibot';

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

Метаданные

Помимо действий проверки и преобразования, пайплайн можно использовать для добавления метаданных к схеме. Это может быть полезно при работе с инструментами ИИ или для документирования.

Действия с метаданными: description, metadata, title

const UsernameSchema = v.pipe(
  v.string(),
  v.regex(/^[a-z0-9_-]{4,16}$/iu),
  v.title('Username'),
  v.description(
    'A username must be between 4 and 16 characters long and can only contain letters, numbers, underscores and hyphens.'
  )
);