optional

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

function optional<T, C extends Scalar>(
  decoder: Decoder<T>,
  defaultValue: (() => C) | C
): Decoder<NonNullable<T> | C>

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

const decoder = optional(string);
// Type: Decoder<string | undefined>

const result = decoder.verify('hello');
// result is 'hello' | undefined

import { optional, string } from 'decoders';

const decoder = optional(string);

decoder.verify('hello');     // 'hello'
decoder.verify(undefined);   // undefined
decoder.verify(null);        // DecodeError

import { optional, string } from 'decoders';

const decoder = optional(string, 'default');

decoder.verify('hello');     // 'hello'
decoder.verify(undefined);   // 'default'
decoder.verify(null);        // DecodeError

import { optional, array, number } from 'decoders';

const decoder = optional(array(number), () => []);

decoder.verify([1, 2, 3]);   // [1, 2, 3]
decoder.verify(undefined);   // []

// These are equivalent:
optional(string)
either(undefined_, string)

// With union types, order matters for type inference:
const userDecoder = object({
  name: string,
  nickname: optional(string),
});

type User = DecoderType<typeof userDecoder>;
// { name: string; nickname: string | undefined }

export function optional<T, V>(
  decoder: Decoder<T>,
  defaultValue?: (() => V) | V,
): Decoder<T | V | undefined> {
  const rv = either(undefined_, decoder);
  return arguments.length >= 2
    ? rv.transform((value) => value ?? lazyval(defaultValue as (() => V) | V))
    : rv;
}