either

function either<TDecoders extends readonly Decoder<unknown>[]>(
  ...decoders: TDecoders
): Decoder<DecoderType<TDecoders[number]>>

const decoder = either(string, number, boolean);
// Type: Decoder<string | number | boolean>

const result = decoder.verify('hello');
// result is string | number | boolean

import { either, string, number } from 'decoders';

const decoder = either(string, number);

decoder.verify('hello');     // 'hello'
decoder.verify(42);          // 42
decoder.verify(true);        // DecodeError

import { either, string, constant } from 'decoders';

const decoder = either(
  constant('foo'),
  constant('bar'),
  string,
);

decoder.verify('foo');       // 'foo' (matched by first decoder)
decoder.verify('bar');       // 'bar' (matched by second decoder)
decoder.verify('baz');       // 'baz' (matched by third decoder)

import { either, string, number, boolean } from 'decoders';

const decoder = either(string, number, boolean);

decoder.verify([]);
// DecodeError:
// Either:
// - Must be string
// - Must be number
// - Must be boolean

import { either, constant, object, string, number } from 'decoders';

const catDecoder = object({
  type: constant('cat'),
  meow: string,
});

const dogDecoder = object({
  type: constant('dog'),
  bark: string,
});

const animalDecoder = either(catDecoder, dogDecoder);

type Animal = DecoderType<typeof animalDecoder>;
// { type: 'cat'; meow: string } | { type: 'dog'; bark: string }

const animal = animalDecoder.verify({ type: 'cat', meow: 'mew' });
if (animal.type === 'cat') {
  animal.meow; // TypeScript knows this is a string
}

import { either, constant } from 'decoders';

const decoder = either(
  constant('A'),
  either(
    constant('B'),
    either(
      constant('C'),
      constant('D'),
    ),
  ),
);

decoder.verify('X');
// DecodeError:
// Either:
// - Must be "A"
// - Must be "B"
// - Must be "C"
// - Must be "D"
//
// (not nested as "Either: - Either: - Either: ...")

import { either, string, number, boolean, null_, undefined_ } from 'decoders';

const decoder = either(string, number, boolean, null_, undefined_);
// Type: Decoder<string | number | boolean | null | undefined>

decoder.verify('hello');     // ✓
decoder.verify(42);          // ✓
decoder.verify(true);        // ✓
decoder.verify(null);        // ✓
decoder.verify(undefined);   // ✓
decoder.verify([]);          // ✗

// Good for general unions
const decoder1 = either(stringDecoder, numberDecoder, booleanDecoder);

// Better for tagged unions
const decoder2 = taggedUnion('type', {
  cat: catDecoder,
  dog: dogDecoder,
});

export function either<TDecoders extends readonly Decoder<unknown>[]>(
  ...decoders: TDecoders
): Decoder<DecoderType<TDecoders[number]>> {
  if (decoders.length === 0) {
    throw new Error('Pass at least one decoder to either()');
  }

  type T = DecoderType<TDecoders[number]>;
  return define<T>((blob, _, err) => {
    // Collect errors here along the way
    const errors: Annotation[] = [];

    for (const decoder of decoders) {
      const result = (decoder as Decoder<T>).decode(blob);
      if (result.ok) {
        return result;
      } else {
        errors.push(result.error);
      }
    }

    // Decoding all alternatives failed, return the combined error message
    const text =
      EITHER_PREFIX + errors.map((err) => nest(summarize(err).join('\n'))).join('\n');
    return err(text);
  });
}