undefinedableAsync

Creates an undefinedable schema.

const Schema = v.undefinedableAsync<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 undefinedableAsync 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.

undefinedableAsync behaves exactly the same as optionalAsync at runtime. The only difference is the input and output type when used for object entries. While optionalAsync adds a question mark to the key, undefinedableAsync does not.

Note that undefinedableAsync 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 UndefinedableSchemaAsync<TWrapped, TDefault>

Examples

The following examples show how undefinedableAsync can be used.

Undefinedable 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 UndefinedableUsernameSchema = v.undefinedableAsync(
  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.undefinedableAsync(
    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 undefinedable schema

Use unwrap to undo the effect of undefinedableAsync.

import { isUsernameUnique } from '~/api';

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

Related

The following APIs can be combined with undefinedableAsync.

Schemas

any, array, bigint, blob, boolean, custom, date, enum, exactOptional, file, function, instance, intersect, lazy, literal, looseObject, looseTuple, map, nan, never, nonNullable, nonNullish, 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, unionAsync, variantAsync