ramda-fantasy

# Either The `Either` type is very similar to the `Maybe` type, in that it is often used to represent the notion of failure in some way. The difference between the two is that an error represented with an `Either` can hold some value (perhaps an exception or error message), while `Maybe` can only indicate that absence of some value. While the `Either` type is often used to represent potential errors, there is nothing restricting it to this purpose. It is therefore perhaps more appropriate to simply think of `Either` as a representation of two possible types of values, sometimes referred to as the _disjoint union_, or _coproduct_ of two types. ## Construction The `Either` type consists of two constructors, `Left :: a -> Either a b` and `Right :: b -> Either a b`. When an `Either` type is used to represent the possibility of an error, `Left` is typically used to hold the error value and `Right` holds the "successful" value (as a mnemonic, you can think of `Right` as being _the right_ value). It is worth highlighting that the types of the value stored in an `Left` does not have to be the same type as that in the `Right` of the same `Either`. This is the reason why it is documented as having two type parameters `Either a b`, where `a` represents the type contained within the `Left` and `b` for the value contained in the `Right`. ## Interaction In order to satisfy a number of laws relating to the implemented interfaces, only a single type parameter can be used as the argument of the various functions. For this reason, `Either` is _right-biased_, meaning methods such as `map`, `ap` and `chain` will only call the given function for a `Right` instance while a `Left` will simply pass the instance straight through, ignoring the provided function. Aside from the transformation methods mentioned above, `Either.either` can also be used to extract the value from an `Either` type, which takes a function to handle the type of value within the `Left` and another function to handle the type contained in the `Right`. Only one of these functions will be called depending on the constructor containing the value. ## Reference ### Constructors #### `Either.Left` ```hs :: a -> Either a b ``` Constructs a `Left` instance of `Either`. This is often used to represent a failure. #### `Either.Right` ```hs :: b -> Either a b ``` Constructs a `Right` instance of `Either`. This is often used to represent a success where there is a possibility of failure. ### Static functions #### `Either.either` ```hs :: (a -> c) -> (b -> c) -> Either a b -> c ``` Used to extract the value out of an `Either` by providing a function to handle the types of values contained in both `Left` and `Right`. #### `Either.of` ```hs :: b -> Either a b ``` Creates a pure instance of an `Either`. This is effectively a `Right` constructor. #### `Either.isLeft` ```hs :: Either a b -> Boolean ``` Returns `true` if the given `Either` instance is a `Left`, otherwise `false`. #### `Either.isRight` ```hs :: Either a b -> Boolean ``` Returns `true` if the given `Either` instance is a `Right`, otherwise `false`. ### Instance methods #### `either.map` ```hs :: Either a b ~> (b -> c) -> Either a c ``` Modifies the value contained in a `Right` with the provided function. If the instance is a `Left`, the value is left unmodified. #### `either.ap` ```hs :: Either a (b -> c) ~> Either a b -> Either a c ``` Applies the function contained in the instance of a `Right` to the value contained in the provided `Right`, producing a `Right` containing the result. If the instance is `Left`, the result will be the `Left` instance. If the instance is `Right` and the provided either is `Left`, the result will be the provided `Left`. #### `either.chain` ```hs :: Either a b ~> (b -> Either a c) -> Either a c ``` Applies the provided function to the value contained in a `Right` instance, resulting in the return value of that function. If the instance is a `Left`, the function is ignored and the `Left` instance is returned unmodified. #### `either.extend` ```hs :: Either a b ~> (Either a b -> c) -> Either a c ``` Applies the provided function to the `Right` instance, returning a `Right` containing the result of the function application. If the instance is a `Left`, the function is ignored and the `Left` instance is returned unmodified. #### `either.bimap` ```hs :: Either a b ~> (a -> c) -> (b -> d) -> Either c d ``` Transforms an `Either` by applying the first function to the contained value if the instance is a `Left`, or the second function if the instance is a `Right`. #### `either.equals` ```hs :: Either a b ~> * -> Boolean ``` Determines whether the provided value is equal to this instance, ensuring both are of the same constructor and both contain equal values. #### `either.toString` ```hs :: Either a b ~> () -> String ``` Returns a string representation of the `Either` instance. #### `either.either` ```hs :: Either a b ~> (a -> c) -> (b -> c) -> c ``` Used to extract the value out of the `Either` by providing a function to handle the types of values contained in both `Left` and `Right`.