nullishAsync

Creates a nullish schema.

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

Generics

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

Parameters

• wrapped TWrapped
• default_ TDefault

Explanation

With nullishAsync the validation of your schema will pass undefined and null inputs, and if you specify a default_ input value, the schema will use it if the input is undefined or null. 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 nullishAsync accepts undefined or null as an input. If you want to accept only null inputs, use nullableAsync, and if you want to accept only undefined inputs, use optionalAsync instead. Also, if you want to set a default output value for any invalid input, you should use fallbackAsync instead.

Returns

• Schema NullishSchemaAsync<TWrapped, TDefault>

Examples

The following examples show how nullishAsync can be used.

Nullish username schema

Schema that accepts a unique username, undefined or null.

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 or null.

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

const NullishUsernameSchema = v.nullishAsync(
  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.nullishAsync(
    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 | null | undefined;
    }
*/

Unwrap nullish schema

Use unwrap to undo the effect of nullishAsync.

import { isUsernameUnique } from '~/api';

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

Nullish async with pipes

When using nullishAsync in a pipeAsync, missing object keys only execute the pipe if a default_ value is provided. If the key is present with null or undefined, later pipe actions still run.

const SchemaWithoutDefault = v.objectAsync({
  value: v.pipeAsync(
    v.nullishAsync(v.string()),
    v.transformAsync(async (input) => (input ?? 'hello').toUpperCase()) // Does not run for missing keys
  ),
}); // Output type: { value?: string }

const SchemaWithDefault = v.objectAsync({
  value: v.pipeAsync(
    v.nullishAsync(v.string(), 'hello'), // Default value provided
    v.transformAsync(async (input) => input.toUpperCase()) // Runs for missing keys, null, and undefined too
  ),
}); // Output type: { value: string }

Related

The following APIs can be combined with nullishAsync.

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