optionalAsync

Creates an optional schema.

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

Generics

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

Parameters

• wrapped TWrapped
• default_ TDefault

Explanation

With optionalAsync 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.

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 optionalAsync does not accept null as an input. If you want to accept null inputs, use nullableAsync, and if you want to accept null and undefined inputs, use nullishAsync instead. Also, if you want to set a default output value for any invalid input, you should use fallbackAsync instead.

Returns

• Schema OptionalSchemaAsync<TWrapped, TDefault>

Examples

The following examples show how optionalAsync can be used.

Optional username schema

Schema that accepts a unique username or undefined.

By using a function as the default_ parameter, the schema will return a unique username from the function call each time the input is undefined.

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

const OptionalUsernameSchema = v.optionalAsync(
  v.pipeAsync(
    v.string(),
    v.nonEmpty(),
    v.checkAsync(isUsernameUnique, 'The username is not unique.')
  ),
  getUniqueUsername
);

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.optionalAsync(
    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 | undefined;
    }
*/

Unwrap optional schema

Use unwrap to undo the effect of optionalAsync.

import { isUsernameUnique } from '~/api';

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

Optional async with pipes

When using optionalAsync 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({
  isActive: v.pipeAsync(
    v.optionalAsync(v.string()),
    v.transformAsync(async (value) => value === 'true') // Does not run for missing keys
  ),
}); // Output type: { isActive?: boolean }

const SchemaWithDefault = v.objectAsync({
  isActive: v.pipeAsync(
    v.optionalAsync(v.string(), 'false'), // Default value provided
    v.transformAsync(async (value) => value === 'true') // Runs for missing keys too
  ),
}); // Output type: { isActive: boolean }

Related

The following APIs can be combined with optionalAsync.

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, parseAsync, parserAsync, partialCheckAsync, pipeAsync, rawCheckAsync, rawTransformAsync, recordAsync, safeParseAsync, safeParserAsync, setAsync, strictObjectAsync, strictTupleAsync, transformAsync, tupleAsync, tupleWithRestAsync, undefinedableAsync, unionAsync, variantAsync