exactOptionalAsync

Creates an exact optional schema.

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

Generics

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

Parameters

• wrapped TWrapped
• default_ TDefault

Explanation

With exactOptionalAsync 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 optionalAsync is that this schema function follows the implementation of TypeScript's exactOptionalPropertyTypes configuration and only allows missing but not undefined object entries.

Returns

• Schema ExactOptionalSchemaAsync<TWrapped, TDefault>

Examples

The following examples show how exactOptionalAsync can be used.

New user schema

Schema to validate new user details.

import { isEmailUnique, isUsernameUnique } from '~/api';

const NewUserSchema = v.objectAsync({
  email: v.pipeAsync(
    v.string(),
    v.email(),
    v.checkAsync(isEmailUnique, 'The email is not unique.')
  ),
  username: v.exactOptionalAsync(
    v.pipeAsync(
      v.string(),
      v.nonEmpty(),
      v.checkAsync(isUsernameUnique, 'The username is not unique.')
    )
  ),
  password: v.pipe(v.string(), v.minLength(8)),
});

/*
  The input and output types of the schema:
    {
      email: string;
      password: string;
      username?: string;
    }
*/

Unwrap exact optional schema

Use unwrap to undo the effect of exactOptionalAsync.

import { isUsernameUnique } from '~/api';

const UsernameSchema = v.unwrap(
  // Assume this schema is from a different file and is reused here
  v.exactOptionalAsync(
    v.pipeAsync(
      v.string(),
      v.nonEmpty(),
      v.checkAsync(isUsernameUnique, 'The username is not unique.')
    )
  )
);

Exact optional async with pipes

When using exactOptionalAsync in a pipeAsync, the pipe actions only execute if a default_ value is provided or the key is present. This applies to all pipe actions including transformAsync, checkAsync, and others.

const SchemaWithoutDefault = v.objectAsync({
  isEnabled: v.pipeAsync(
    v.exactOptionalAsync(v.string()),
    v.transformAsync(async (value) => value === '1') // Does not run for missing keys
  ),
}); // Output type: { isEnabled?: boolean }

const SchemaWithDefault = v.objectAsync({
  isEnabled: v.pipeAsync(
    v.exactOptionalAsync(v.string(), '0'), // Default value provided
    v.transformAsync(async (value) => value === '1') // Runs for missing keys too
  ),
}); // Output type: { isEnabled: boolean }

Related

The following APIs can be combined with exactOptionalAsync.

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, nullish, number, object, objectWithRest, optional, picklist, promise, record, set, strictObject, strictTuple, string, symbol, tuple, tupleWithRest, undefined, undefinedable, union, unknown, variant, void

Methods

config, getDefault, getFallback, unwrap

Actions

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

Utils

entriesFromList, isOfKind, isOfType

Async

arrayAsync, awaitAsync, checkAsync, customAsync, exactOptionalAsync, fallbackAsync, getDefaultsAsync, getFallbacksAsync, intersectAsync, lazyAsync, looseObjectAsync, looseTupleAsync, mapAsync, nonNullableAsync, nonNullishAsync, nonOptionalAsync, nullableAsync, nullishAsync, objectAsync, objectWithRestAsync, optionalAsync, parseAsync, parserAsync, partialCheckAsync, pipeAsync, rawCheckAsync, rawTransformAsync, recordAsync, safeParseAsync, safeParserAsync, setAsync, strictObjectAsync, strictTupleAsync, transformAsync, tupleAsync, tupleWithRestAsync, undefinedableAsync, unionAsync, variantAsync