optional

Создает опциональную схему.

const Schema = v.optional<TWrapped, TDefault>(wrapped, default_);

Дженерики

• TWrapped extends BaseSchema<unknown, unknown, BaseIssue<unknown>>
• TDefault extends Default<TWrapped, undefined>

Параметры

• wrapped TWrapped
• default_ TDefault

Объяснение

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

Важно: при использовании в схемах объектов, если ключ отсутствует и значение default_ не указано, конвейер схемы (включая преобразования) не будет выполнен. Чтобы гарантировать выполнение конвейеров для отсутствующих ключей, укажите значение default_.

Обратите внимание, что optional не принимает null в качестве входного значения. Если вы хотите принимать входные данные null, используйте nullable, а если вы хотите принимать входные данные null и undefined, используйте вместо этого nullish. Кроме того, если вы хотите установить значение по умолчанию для любых недопустимых входных данных, вам следует использовать вместо этого fallback.

Возвращаемое значение

• Schema OptionalSchema<TWrapped, TDefault>

Примеры

Следующие примеры показывают, как можно использовать optional.

Опциональная строковая схема

Схема, которая принимает string и undefined.

const OptionalStringSchema = v.optional(v.string(), "I'm the default!");

Опциональная схема даты

Схема, которая принимает Date и undefined.

При использовании функции в качестве параметра default_ схема будет возвращать новый экземпляр Date каждый раз, когда входное значение равно undefined.

const OptionalDateSchema = v.optional(v.date(), () => new Date());

Схема с опциональным свойством

Схема объекта с опциональным свойством.

const OptionalEntrySchema = v.object({
  key: v.optional(v.string()),
});

Значение по умолчанию undefined

По умолчанию, если во входном объекте отсутствует опциональное свойство, соответствующий ключ опускается в выводе. Чтобы всегда включать ключ в вывод со значением undefined, передайте функцию, возвращающую undefined, в качестве параметра default_.

const OptionalEntrySchema = v.object({
  key: v.optional(v.string(), () => undefined),
});

Развертывание опциональной схемы

Используйте unwrap, чтобы отменить действие optional.

const OptionalNumberSchema = v.optional(v.number());
const NumberSchema = v.unwrap(OptionalNumberSchema);

Опциональные схемы с конвейерами

При использовании optional в pipe действия конвейера выполняются только в том случае, если указано значение default_ или ключ присутствует. Это относится ко всем действиям конвейера, включая transform, check и другие.

const SchemaWithoutDefault = v.object({
  isActive: v.pipe(
    v.optional(v.string()),
    v.transform((value) => value === 'true') // Does not run for missing keys
  ),
}); // Output type: { isActive?: boolean }

const SchemaWithDefault = v.object({
  isActive: v.pipe(
    v.optional(v.string(), 'false'), // Default value provided
    v.transform((value) => value === 'true') // Runs for missing keys too
  ),
}); // Output type: { isActive: boolean }

Связанные элементы

Следующие API можно комбинировать с optional.

Схемы

any, array, bigint, blob, boolean, custom, date, enum, exactOptional, file, function, instance, intersect, lazy, literal, looseObject, looseTuple, map, nan, never, nonNullable, nonNullish, nonOptional, null, nullable, nullish, number, object, objectWithRest, picklist, promise, record, set, strictObject, strictTuple, string, symbol, tuple, tupleWithRest, undefined, undefinedable, union, unknown, variant, void

Методы

assert, config, fallback, getDefault, getDefaults, getFallback, getFallbacks, is, message, parse, parser, pipe, safeParse, safeParser, unwrap

Действия

check, brand, description, flavor, guard, metadata, partialCheck, rawCheck, rawTransform, readonly, title, transform

Утилиты

entriesFromList, isOfKind, isOfType