Объединения

Объединение представляет собой отношение логического ИЛИ. Вы можете применить эту концепцию к своим схемам с помощью union и variant. Для размеченных объединений используйте variant, а во всех остальных случаях — union.

Схема объединения

Функция схемы union создает отношение ИЛИ между любым количеством схем, переданных в качестве первого аргумента в виде массива. При проверке схема возвращает результат первой успешно прошедшей проверку схемы.

import * as v from 'valibot';

// TypeScript
type Union = string | number;

// Valibot
const UnionSchema = v.union([v.string(), v.number()]);

Если некорректный вход можно однозначно сопоставить с одной из схем на основании типа данных, возвращается результат этой схемы. В противном случае возвращается общая ошибка, содержащая ошибки каждой схемы в качестве вложенных ошибок. Это особый случай в библиотеке, поскольку ошибки union могут противоречить друг другу.

Следующие ошибки возвращаются, если вместо строки или числа передано значение null. Поскольку в этом случае входные данные нельзя сопоставить со схемой, ошибки обеих схем возвращаются в качестве вложенных ошибок.

[
  {
    kind: 'schema',
    type: 'union',
    input: null,
    expected: 'string | number',
    received: 'null',
    message: 'Invalid type: Expected string | number but received null',
    issues: [
      {
        kind: 'schema',
        type: 'string',
        input: null,
        expected: 'string',
        received: 'null',
        message: 'Invalid type: Expected string but received null',
      },
      {
        kind: 'schema',
        type: 'number',
        input: null,
        expected: 'number',
        received: 'null',
        message: 'Invalid type: Expected number but received null',
      },
    ],
  },
];

Схема варианта

Для повышения производительности, большей безопасности типов и более точного вывода ошибок для размеченных объединений можно использовать variant. Поэтому мы рекомендуем по возможности использовать variant вместо union. Размеченное объединение — это отношение ИЛИ между объектами, которые можно различить по определенному ключу.

При вызове функции схемы сначала укажите ключ-дискриминатор. Он используется для определения схемы, которую следует применить для проверки входных данных. Схемы объектов, представленные в виде массива, указываются вторым аргументом.

import * as v from 'valibot';

const VariantScheme = v.variant('type', [
  v.object({
    type: v.literal('foo'),
    foo: v.string(),
  }),
  v.object({
    type: v.literal('bar'),
    bar: v.number(),
  }),
]);

Для очень сложных наборов данных несколько схем variant также можно глубоко вкладывать друг в друга.