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