sanctuary-either

The Either type represents values with two possibilities: a value of type
Either a b is either a Left whose value is of type a or a Right whose
value is of type b.

Either a b satisfies the following [Fantasy Land][] specifications:

``javascript
> const Useless = require ('sanctuary-useless')

> const isTypeClass = x =>
. type (x) === 'sanctuary-type-classes/TypeClass@1'

> S.map (k => k + ' '.repeat (16 - k.length) +
. (Z[k].test (Right (Useless)) ? '\u2705 ' :
. Z[k].test (Right (['foo'])) ? '\u2705 * ' :
. / otherwise / '\u274C '))
. (S.keys (S.unchecked.filter (isTypeClass) (Z)))
[ 'Setoid ✅ * ', // if ‘a’ and ‘b’ satisfy Setoid
. 'Ord ✅ * ', // if ‘a’ and ‘b’ satisfy Ord
. 'Semigroupoid ❌ ',
. 'Category ❌ ',
. 'Semigroup ✅ * ', // if ‘a’ and ‘b’ satisfy Semigroup
. 'Monoid ❌ ',
. 'Group ❌ ',
. 'Filterable ❌ ',
. 'Functor ✅ ',
. 'Bifunctor ✅ ',
. 'Profunctor ❌ ',
. 'Apply ✅ ',
. 'Applicative ✅ ',
. 'Chain ✅ ',
. 'ChainRec ✅ ',
. 'Monad ✅ ',
. 'Alt ✅ ',
. 'Plus ❌ ',
. 'Alternative ❌ ',
. 'Foldable ✅ ',
. 'Traversable ✅ ',
. 'Extend ✅ ',
. 'Comonad ❌ ',
. 'Contravariant ❌ ' ]
`

#### Either :: TypeRep Either

Either [type representative][].

#### Either.Left :: a -⁠> Either a b

Constructs a value of type Either a b from a value of type a.

`javascript
> Left ('sqrt undefined for -1')
Left ('sqrt undefined for -1')
`

#### Either.Right :: b -⁠> Either a b

Constructs a value of type Either a b from a value of type b.

`javascript
> Right (42)
Right (42)
`

#### Either.fantasy-land/of :: b -⁠> Either a b

- of (Either) (x) is equivalent to Right (x)

`javascript
> S.of (Either) (42)
Right (42)
`

#### Either.fantasy-land/chainRec :: ((a -⁠> c, b -⁠> c, a) -⁠> Either d c, a) -⁠> Either d b

`javascript
> Z.chainRec (
. Either,
. (next, done, x) =>
. x <= 1 ? Left ('!!') : Right (x >= 1000 ? done (x) : next (x * x)),
. 1
. )
Left ('!!')

> Z.chainRec (
. Either,
. (next, done, x) =>
. x <= 1 ? Left ('!!') : Right (x >= 1000 ? done (x) : next (x * x)),
. 2
. )
Right (65536)
`

#### Either#@@show :: (Showable a, Showable b) => Either a b ~> () -⁠> String

- show (Left (x)) is equivalent to 'Left (' + show (x) + ')'
- show (Right (x)) is equivalent to 'Right (' + show (x) + ')'

`javascript
> show (Left ('sqrt undefined for -1'))
'Left ("sqrt undefined for -1")'

> show (Right ([1, 2, 3]))
'Right ([1, 2, 3])'
`

#### Either#fantasy-land/equals :: (Setoid a, Setoid b) => Either a b ~> Either a b -⁠> Boolean

- Left (x) is equal to Left (y) [iff][] x is equal to y
according to [Z.equals][]
- Right (x) is equal to Right (y) [iff][] x is equal to y
according to [Z.equals][]
- Left (x) is never equal to Right (y)

`javascript
> S.equals (Left ([1, 2, 3])) (Left ([1, 2, 3]))
true

> S.equals (Right ([1, 2, 3])) (Right ([1, 2, 3]))
true

> S.equals (Left ([1, 2, 3])) (Right ([1, 2, 3]))
false
`

#### Either#fantasy-land/lte :: (Ord a, Ord b) => Either a b ~> Either a b -⁠> Boolean

- Left (x) is less than or equal to Left (y) [iff][] x is less
than or equal to y according to [Z.lte][]
- Right (x) is less than or equal to Right (y) [iff][] x is less
than or equal to y according to [Z.lte][]
- Left (x) is always less than Right (y)

`javascript
> S.filter (S.lte (Left (1))) ([Left (0), Left (1), Left (2)])
[Left (0), Left (1)]

> S.filter (S.lte (Right (1))) ([Right (0), Right (1), Right (2)])
[Right (0), Right (1)]

> S.filter (S.lte (Left (1))) ([Right (0), Right (1), Right (2)])
[]

> S.filter (S.lte (Right (1))) ([Left (0), Left (1), Left (2)])
[Left (0), Left (1), Left (2)]
`

#### Either#fantasy-land/concat :: (Semigroup a, Semigroup b) => Either a b ~> Either a b -⁠> Either a b

- concat (Left (x)) (Left (y)) is equivalent to
Left (concat (x) (y))
- concat (Right (x)) (Right (y)) is equivalent to
Right (concat (x) (y))
- concat (Left (x)) (Right (y)) is equivalent to Right (y)
- concat (Right (x)) (Left (y)) is equivalent to Right (x)

`javascript
> S.concat (Left ('abc')) (Left ('def'))
Left ('abcdef')

> S.concat (Right ([1, 2, 3])) (Right ([4, 5, 6]))
Right ([1, 2, 3, 4, 5, 6])

> S.concat (Left ('abc')) (Right ([1, 2, 3]))
Right ([1, 2, 3])

> S.concat (Right ([1, 2, 3])) (Left ('abc'))
Right ([1, 2, 3])
`

#### Either#fantasy-land/map :: Either a b ~> (b -⁠> c) -⁠> Either a c

- map (f) (Left (x)) is equivalent to Left (x)
- map (f) (Right (x)) is equivalent to Right (f (x))

`javascript
> S.map (S.add (1)) (Left ('sqrt undefined for -1'))
Left ('sqrt undefined for -1')

> S.map (S.add (1)) (Right (99))
Right (100)
`

#### Either#fantasy-land/bimap :: Either a c ~> (a -⁠> b, c -⁠> d) -⁠> Either b d

- bimap (f) (g) (Left (x)) is equivalent to Left (f (x))
- bimap (f) (g) (Right (x)) is equivalent to Right (g (x))

`javascript
> S.bimap (S.toUpper) (S.add (1)) (Left ('abc'))
Left ('ABC')

> S.bimap (S.toUpper) (S.add (1)) (Right (99))
Right (100)
`

#### Either#fantasy-land/ap :: Either a b ~> Either a (b -⁠> c) -⁠> Either a c

- ap (Left (x)) (Left (y)) is equivalent to Left (x)
- ap (Left (x)) (Right (y)) is equivalent to Left (x)
- ap (Right (f)) (Left (x)) is equivalent to Left (x)
- ap (Right (f)) (Right (x)) is equivalent to Right (f (x))

`javascript
> S.ap (Left ('div undefined for 0')) (Left ('sqrt undefined for -1'))
Left ('div undefined for 0')

> S.ap (Left ('div undefined for 0')) (Right (99))
Left ('div undefined for 0')

> S.ap (Right (S.add (1))) (Left ('sqrt undefined for -1'))
Left ('sqrt undefined for -1')

> S.ap (Right (S.add (1))) (Right (99))
Right (100)
`

#### Either#fantasy-land/chain :: Either a b ~> (b -⁠> Either a c) -⁠> Either a c

- chain (f) (Left (x)) is equivalent to Left (x)
- chain (f) (Right (x)) is equivalent to f (x)

`javascript
> const sqrt = n => n < 0 ? Left ('sqrt undefined for ' + show (n))
. : Right (Math.sqrt (n))

> S.chain (sqrt) (Left ('div undefined for 0'))
Left ('div undefined for 0')

> S.chain (sqrt) (Right (-1))
Left ('sqrt undefined for -1')

> S.chain (sqrt) (Right (25))
Right (5)
`

#### Either#fantasy-land/alt :: Either a b ~> Either a b -⁠> Either a b

- alt (Left (y)) (Left (x)) is equivalent to Left (y)
- alt (Right (y)) (Left (x)) is equivalent to Right (y)
- alt (Left (y)) (Right (x)) is equivalent to Right (x)
- alt (Right (y)) (Right (x)) is equivalent to Right (x)

`javascript
> S.alt (Left ('B')) (Left ('A'))
Left ('B')

> S.alt (Right (1)) (Left ('C'))
Right (1)

> S.alt (Left ('D')) (Right (2))
Right (2)

> S.alt (Right (4)) (Right (3))
Right (3)
`

#### Either#fantasy-land/reduce :: Either a b ~> ((c, b) -⁠> c, c) -⁠> c

- reduce (f) (x) (Left (y)) is equivalent to x
- reduce (f) (x) (Right (y)) is equivalent to f (x) (y)

`javascript
> S.reduce (S.concat) ([1]) (Left ('sqrt undefined for -1'))
[1]

> S.reduce (S.concat) ([1]) (Right ([2]))
[1, 2]
`

#### Either#fantasy-land/traverse :: Applicative f => Either a b ~> (TypeRep f, b -⁠> f c) -⁠> f (Either a c)

- traverse (A) (f) (Left (x)) is equivalent to of (A) (Left (x))
- traverse (A) (f) (Right (x)) is equivalent to map (Right) (f (x))

`javascript
> S.traverse (Array) (S.words) (Left ('sqrt undefined for -1'))
[Left ('sqrt undefined for -1')]

> S.traverse (Array) (S.words) (Right ('foo bar baz'))
[Right ('foo'), Right ('bar'), Right ('baz')]
`

#### Either#fantasy-land/extend :: Either a b ~> (Either a b -⁠> c) -⁠> Either a c

- extend (f) (Left (x)) is equivalent to Left (x)
- extend (f) (Right (x)) is equivalent to Right (f (Right (x)))

`javascript
> S.extend (S.reduce (S.add) (1)) (Left ('sqrt undefined for -1'))
Left ('sqrt undefined for -1')

> S.extend (S.reduce (S.add) (1)) (Right (99))
Right (100)
`

[Fantasy Land]: https://github.com/fantasyland/fantasy-land/tree/v4.0.1
[Z.equals]: https://github.com/sanctuary-js/sanctuary-type-classes/tree/v12.1.0#equals
[Z.lte`]: https://github.com/sanctuary-js/sanctuary-type-classes/tree/v12.1.0#lte
[iff]: https://en.wikipedia.org/wiki/If_and_only_if
[type representative]: https://github.com/fantasyland/fantasy-land/tree/v4.0.1#type-representatives