undefinedable

Creates an undefinedable schema.

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

Generics

• TWrapped extends BaseSchema<unknown, unknown, BaseIssue<unknown>>
• TDefault extends Default<TWrapped> | never

Parameters

• wrapped TWrapped
• default_ TDefault

Explanation

With undefinedable the validation of your schema will pass undefined inputs, and if you specify a default_ input value, the schema will use it if the input is undefined. For this reason, the output type may differ from the input type of the schema.

undefinedable behaves exactly the same as optional at runtime. The only difference is the input and output type when used for object entries. While optional adds a question mark to the key, undefinedable does not.

Note that undefinedable does not accept null as an input. If you want to accept null inputs, use nullable, and if you want to accept null and undefined inputs, use nullish instead. Also, if you want to set a default output value for any invalid input, you should use fallback instead.

Returns

• Schema UndefinedableSchema<TWrapped, TDefault>

Examples

The following examples show how undefinedable can be used.

Undefinedable string schema

Schema that accepts string and undefined.

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

Undefinedable date schema

Schema that accepts Date and undefined.

By using a function as the default_ parameter, the schema will return a new Date instance each time the input is undefined.

const UndefinedableDateSchema = v.undefinedable(v.date(), () => new Date());

Undefinedable entry schema

Object schema with an undefinedable entry.

const UndefinedableEntrySchema = v.object({
  key: v.undefinedable(v.string()),
});

Unwrap undefinedable schema

Use unwrap to undo the effect of undefinedable.

const UndefinedableNumberSchema = v.undefinedable(v.number());
const NumberSchema = v.unwrap(UndefinedableNumberSchema);

Related

The following APIs can be combined with undefinedable.

Schemas

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

Methods

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

Actions

• check,
• brand,
• description,
• metadata,
• partialCheck,
• rawCheck,
• rawTransform,
• readonly,
• title,
• transform

Utils

• entriesFromList,
• isOfKind,
• isOfType