exactOptional

Creates an exact optional schema.

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

Generics

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

Parameters

• wrapped TWrapped
• default_ TDefault

Explanation

With exactOptional the validation of your schema will pass missing object entries, and if you specify a default_ input value, the schema will use it if the object entry is missing. 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.

The difference to optional is that this schema function follows the implementation of TypeScript's exactOptionalPropertyTypes configuration and only allows missing but not undefined object entries.

Returns

• Schema ExactOptionalSchema<TWrapped, TDefault>

Examples

The following examples show how exactOptional can be used.

Exact optional object entries

Object schema with exact optional entries.

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

const OptionalEntrySchema = v.object({
  key1: v.exactOptional(v.string()),
  key2: v.exactOptional(v.string(), "I'm the default!"),
  key3: v.exactOptional(v.date(), () => new Date()),
});

Unwrap exact optional schema

Use unwrap to undo the effect of exactOptional.

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

Exact optional with pipes

When using exactOptional in a pipe, the pipe actions only execute if a default_ value is provided or the key is present. This applies to all pipe actions including transform, check, and others.

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

const SchemaWithDefault = v.object({
  isEnabled: v.pipe(
    v.exactOptional(v.string(), '0'), // Default value provided
    v.transform((value) => value === '1') // Runs for missing keys too
  ),
}); // Output type: { isEnabled: boolean }

Related

The following APIs can be combined with exactOptional.

Schemas

• any,
• array,
• bigint,
• blob,
• boolean,
• custom,
• date,
• enum,
• file,
• function,
• instance,
• intersect,
• lazy,
• literal,
• looseObject,
• looseTuple,
• map,
• nan,
• never,
• nonNullable,
• nonNullish,
• nonOptional,
• null,
• nullable,
• nullish,
• 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