nullish

Creates a nullish schema.

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

Generics

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

Parameters

• wrapped TWrapped
• default_ TDefault

Explanation

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

Important: When used in object schemas, if a key is missing and no default_ value is provided, the schema's pipe (including transformations) will not be executed. To ensure pipes run for missing keys, provide a default_ value.

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

Returns

• Schema NullishSchema<TWrapped, TDefault>

Examples

The following examples show how nullish can be used.

Nullish string schema

Schema that accepts string, undefined and null.

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

Nullish date schema

Schema that accepts Date, undefined and null.

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

const NullishDateSchema = v.nullish(v.date(), () => new Date());

Nullish entry schema

Object schema with a nullish entry.

const NullishEntrySchema = v.object({
  key: v.nullish(v.string()),
});

Default to undefined

By default, when an object input is missing a nullish entry, the corresponding key is omitted from the output. To always include the key in the output with an undefined value, pass a function that returns undefined as the default_ parameter.

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

Unwrap nullish schema

Use unwrap to undo the effect of nullish.

const NullishNumberSchema = v.nullish(v.number());
const NumberSchema = v.unwrap(NullishNumberSchema);

Nullish with pipes

When using nullish in a pipe, missing object keys only execute the pipe if a default_ value is provided. If the key is present with null or undefined, later pipe actions still run.

const SchemaWithoutDefault = v.object({
  value: v.pipe(
    v.nullish(v.string()),
    v.transform((input) => (input ?? 'hello').toUpperCase()) // Does not run for missing keys
  ),
}); // Output type: { value?: string }

const SchemaWithDefault = v.object({
  value: v.pipe(
    v.nullish(v.string(), 'hello'), // Default value provided
    v.transform((input) => input.toUpperCase()) // Runs for missing keys, null, and undefined too
  ),
}); // Output type: { value: string }

Related

The following APIs can be combined with nullish.

Schemas

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, number, object, objectWithRest, optional, 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, message, parse, parser, pipe, safeParse, safeParser, unwrap

Actions

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

Utils

entriesFromList, isOfKind, isOfType