Optionality

null_

null_: Decoder<null> (source)

Accepts and returns only the literal null value.

// 👍
null_.verify(null) === null;

// 👎
null_.verify(false);         // throws
null_.verify(undefined);     // throws
null_.verify('hello world'); // throws

undefined_

undefined_: Decoder<undefined> (source)

Accepts and returns only the literal undefined value.

// 👍
undefined_.verify(undefined) === undefined;

// 👎
undefined_.verify(null);          // throws
undefined_.verify(false);         // throws
undefined_.verify('hello world'); // throws

optional

optional(decoder: Decoder<T>): Decoder<T | undefined> (source)

optional(decoder: Decoder<T>, defaultValue: V | (() => V)): Decoder<T | V> (source)

Accepts whatever the given decoder accepts, or undefined.

If a default value is explicitly provided, return that instead in the undefined case.

const decoder = optional(string);

// 👍
decoder.verify('hello') === 'hello';
decoder.verify(undefined) === undefined;

// 👎
decoder.verify(null);  // throws
decoder.verify(0);     // throws
decoder.verify(42);    // throws

A typical case where optional() is useful is in decoding objects with optional fields:

object({
  id: number,
  name: string,
  address: optional(string),
});

Which will decode to type:

{
  id: number;
  name: string;
  address?: string;
}

nullable

nullable(decoder: Decoder<T>): Decoder<T | null> (source)

nullable(decoder: Decoder<T>, defaultValue: V | (() => V)): Decoder<T | V> (source)

Accepts whatever the given decoder accepts, or null.

If a default value is explicitly provided, return that instead in the null case.

const decoder = nullable(string);

// 👍
decoder.verify('hello') === 'hello';
decoder.verify(null) === null;

// 👎
decoder.verify(undefined);  // throws
decoder.verify(0);          // throws
decoder.verify(42);         // throws

Or use it with a default value:

const decoder = nullable(iso8601, () => new Date());

decoder.verify('2022-01-01T12:00:00Z') === '2022-01-01T12:00:00Z';
decoder.verify(null);  // the current date

nullish

nullish(decoder: Decoder<T>): Decoder<T | null | undefined> (source)

nullish(decoder: Decoder<T>, defaultValue: V | (() => V)): Decoder<T | V> (source)

Accepts whatever the given decoder accepts, or null, or undefined.

If a default value is explicitly provided, return that instead in the null/undefined case.

const decoder = nullish(string);

// 👍
decoder.verify('hello') === 'hello';
decoder.verify(null) === null;
decoder.verify(undefined) === undefined;

// 👎
decoder.verify(0);   // throws
decoder.verify(42);  // throws

Or use it with a default value:

const decoder = nullish(string, null);

decoder.verify('hello') === 'hello';
decoder.verify(null) === null;
decoder.verify(undefined) === null;

unknown

unknown: Decoder<unknown> (source)

anything: Decoder<unknown> (source)

Accepts anything and returns it unchanged.

Useful for situation in which you don't know or expect a specific type. Of course, the downside is that you won't know the type of the value statically and you'll have to further refine it yourself.

// 👍
unknown.verify('hello') === 'hello';
unknown.verify(false) === false;
unknown.verify(undefined) === undefined;
unknown.verify([1, 2]) === [1, 2];

// 👎
// This decoder will never reject an input