Pipelines

For detailed validations and transformations, a pipeline can be passed as the last optional argument to most schema function. Especially for schema functions like string, number, date, object and array this feature is useful to validate further details apart from the raw data type.

How it works

In simple words, a pipeline is an array of actions that synchronously passes through the input of a schema. Each actions can examine and modify the input. The pipeline is therefore perfect for detailed validations and transformations.

Important: The pipeline cannot be used to change the data type of a value. For this, the transform method must be used explicitly.

Example

For example, the pipeline feature can be used to trim a string and make sure that it is an email that ends with a specific domain.

import * as v from 'valibot';

const EmailSchema = v.string([
  v.toTrimmed(),
  v.email(),
  v.endsWith('@example.com'),
]);

Validations

Pipeline validation actions examine the input and, if the input does not meet a certain condition, return an issue. If the input is valid, it is returned as the output and, if present, picked up by the next action in the pipeline.

By default I run a pipeline completely, even if an error is thrown in between, to collect all issues. If you want me to abort the pipeline early after the first error is thrown, you have to set the abortPipeEarly option of parse or safeParse to true. Learn more about it here.

Some of these utility functions can be used in the pipeline of different schema functions. For example, minValue can be used in the pipeline of string, number, bigint and date.

import * as v from 'valibot';

const StringSchema = v.string([v.minValue('2023-07-29')]);
const NumberSchema = v.number([v.minValue(1234)]);
const BigintSchema = v.bigint([v.minValue(1234n)]);
const DateSchema = v.date([v.minValue(new Date())]);

Custom validation

For custom validations custom can be used. If the function passed as the first argument returns a falsy value, an error is thrown. Otherwise the input is considered valid.

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

const UsernameSchema = v.string([
  v.custom(isValidUsername, 'This username is invalid.'),
]);

You can forward the issues of a pipeline validation to a child. See the methods guide for more information.

Transformations

Pipeline transformation actions allow to change the value of an input, but not the data type. This can be useful for example to remove spaces at the beginning or end of a string or to force a minimum or maximum value.

If you also want to change the data type, you must explicitly use the transform method.

For example, the pipeline of the following schema enforces a minimum value of 10. If the input is less than 10, it is replaced with the specified minimum value.

import * as v from 'valibot';

const NumberSchema = v.number([v.toMinValue(10)]);

Contributors

Thanks to all the contributors who helped make this page better!

  • GitHub profile picture of fabian-hiller
  • GitHub profile picture of ariskemper

Partners

Thanks to our partners who support the project ideally and financially.

Sponsors

Thanks to our GitHub sponsors who support the project financially.

  • GitHub profile picture of dailydotdev
  • GitHub profile picture of ivan-mihalic
  • GitHub profile picture of KATT
  • GitHub profile picture of osdiab
  • GitHub profile picture of Thanaen
  • GitHub profile picture of hyunbinseo
  • GitHub profile picture of caegdeveloper