Maybe

WIP

type Maybe a = Just a | Nothing

The Maybe type encapsulates an optional value. In JavaScript, you usually use null and/or undefined, but Maybe makes it way easier to use an optional value in a functional programming context. Maybe is a union type of Just and Nothing, where Just contains a value and Nothing is empty.

Do not use null or undefined. Instead, use Maybe. If there is a value returned by a JavaScript function that possibly returns undefined or null, you can convert it to a Maybe by using the Maybe constructor.

Example

In the following example, we try to get the AP of the currently open hero and default to 0 if there is no open hero.

const getTotalAPFromCurrentHero: (heroes: OrderedMap<string, Record<Hero>>) =>
                                 (state: Record<AppState>) => number =
  heroes =>
    pipe (
      // no hero could be currently open, so it returns Maybe<string>
      getCurrentHeroIdFromState,

      // Looks up the id in the heroes map if an id is available. It could not
      // be in the map, so it returns a Maybe again
      bindF (lookupF (heroes)),

      // Gets the AP total from the hero
      fmap (HA.adventurePointsTotal),

      // default to 0 if no hero was found, otherwise return the AP
      fromMaybe (0)
    )

Note: This is not a real-world example, as we usually don't access the state this way, but it's better to briefly explain how Maybe works.

Table of Contents

Constructors

Function	Short description
Maybe	Creates a new Maybe from the given nullable value.
Just	Creates a new Just from the passed value.
Nothing	The empty Maybe.

Maybe-specific functions

Function	Short description
fromJust	The fromJust function extracts the element out of a Just and throws an error if its argument is Nothing.
fromMaybe	The fromMaybe function takes a default value and and Maybe value. If the Maybe is Nothing, it returns the default values otherwise, it returns the value contained in the Maybe.
fromMaybe_	Lazy version of fromMaybe.
maybe	The maybe function takes a default value, a function, and a Maybe value. If the Maybe value is Nothing, the function returns the default value. Otherwise, it applies the function to the value inside the Just and returns the result.
maybe_	Lazy version of maybe.
maybeRNull
maybeRNullF
listToMaybe	The listToMaybe function returns Nothing on an empty list or Just (a) where a is the first element of the list.
maybeToList	The maybeToList function returns an empty list when given Nothing or a singleton list when not given Nothing.
catMaybes	The catMaybes function takes a list of Maybes and returns a list of all the Just values.
mapMaybe	The mapMaybe function is a version of map which can throw out elements. If particular, the functional argument returns something of type Maybe b. If this is Nothing, no element is added on to the result list. If it is Just b, then b is included in the result list.
imapMaybe	The imapMaybe function is a version of imap which can throw out elements. If particular, the functional argument returns something of type Maybe b. If this is Nothing, no element is added on to the result list. If it is Just b, then b is included in the result list.
normalize	Creates a new Maybe from the given nullable value. If the value is already an instance of Maybe, it will just return the value.
ensure	Creates a new Just a from the given value if the given predicate evaluates to True and the given value is not nullable. Otherwise returns Nothing.
maybeToNullable	The maybeToNullable function returns null when given Nothing or returns the value inside the Just.
maybeToUndefined	The maybeToUndefined function returns undefined when given Nothing or returns the value inside the Just.
joinMaybeList	Returns an empty list on Nothing, otherwise the contained list.
isMaybe	The isMaybe function returns True if its argument is a Maybe.

Applicative

Function	Short description
pure	Lift a value.
ap	Sequential application.

Alternative

Function	Short description
alt	Returns the first Maybe if it is Just, otherwise the second.
alt_	Lazy version of alt.
altF	Flipped version of alt.
altF_	Lazy version of alt_.
empty
guard
guard_	Lazy version of guard.
guardReplace	guardReplace (cond) (x) returns Just (x) if cond is True, otherwise Nothing.

Monad

Function	Short description
bind
bindF
then	Sequentially compose two actions, discarding any value produced by the first, like sequencing operators (such as the semicolon) in imperative languages.
thenF	Flipped version of then.
kleisli	Left-to-right Kleisli composition of monads.
join	The join function is the conventional monad join operator. It is used to remove one level of monadic structure, projecting its bound argument into the outer level.
mapM	mapM f xs takes a function and a list and maps the function over every element in the list. If the function returns a Nothing, it is immediately returned by the function. If f did not return any Nothing, the list of unwrapped return values is returned as a Just. If xs is empty, Just [] is returned.
liftM2	Promote a function to a monad, scanning the monadic arguments from left to right.
liftM3	Promote a function to a monad, scanning the monadic arguments from left to right.
liftM3	Promote a function to a monad, scanning the monadic arguments from left to right.
liftM4	Promote a function to a monad, scanning the monadic arguments from left to right.
liftM5	Promote a function to a monad, scanning the monadic arguments from left to right.

Foldable

Function	Short description
foldr	Right-associative fold of a structure.
foldl	Left-associative fold of a structure.
toList	List of elements of a structure, from left to right.
fnull	Test whether the structure is empty. The default implementation is optimized for structures that are similar to cons-lists, because there is no general way to do better.
flength	Returns the size/length of a finite structure as an Int. The default implementation is optimized for structures that are similar to cons-lists, because there is no general way to do better.
elem	Does the element occur in the structure?
elemF	Flipped version of elem.
sum	The sum function computes the sum of the numbers of a structure.
product	The product function computes the product of the numbers of a structure.
concat	The concatenation of all the elements of a container of lists.
concatMap	Map a function over all the elements of a container and concatenate the resulting lists.
and	and returns the conjunction of a container of Bools. For the result to be True, the container must be finite False, however, results from a False value finitely far from the left end.
or	or returns the disjunction of a container of Bools. For the result to be False, the container must be finite True, however, results from a True value finitely far from the left end.
orN
any	Determines whether any element of the structure satisfies the predicate.
all	Determines whether all elements of the structure satisfy the predicate.
notElem	notElem is the negation of elem.
find	The find function takes a predicate and a structure and returns the leftmost element of the structure matching the predicate, or Nothing if there is no such element.

Ord

Function	Short description
gt	Returns if the second value is greater than the first value.
lt	Returns if the second value is lower than the first value.
gte	Returns if the second value is greater than or equals the first value.
lte	Returns if the second value is lower than or equals the first value.

Semigroup

Function	Short description
mappend	Concatenates the Semigroups contained in the two Maybes, if both are of type Just a. If at least one of them is Nothing, it returns the first element.

Constructors

Maybe :: (a | undefined | null) -> Maybe a

Creates a new Maybe from the given nullable value.

Use only if you get a value returned by a JavaScript function that possibly returns undefined or null. To lift a value into a Maybe context, use Just!

Just :: a -> Maybe a

Creates a new Just from the passed value.

Nothing :: Maybe a

The empty Maybe.

There is only one instance of Nothing available in the app, which means, you can use reference equality testing.

Nothing === Nothing // true

You should use isNothing, though, as === is not a type guard for Nothing, which means, Nothing is still not excluded in subsequent code.

Maybe-specific functions

fromJust :: Maybe a -> a

The fromJust function extracts the element out of a Just and throws an error if its argument is Nothing.

This should not be used in a production context, as it can throw an error. Only use with care.

fromMaybe :: a -> Maybe a -> a

The fromMaybe function takes a default value and and Maybe value. If the Maybe is Nothing, it returns the default values otherwise, it returns the value contained in the Maybe.

This is typically used to remove the Maybe context from a value. As it could be Nothing, you need to provide a default value.

fromMaybe_ :: (() -> a) -> Maybe a -> a

The fromMaybe_ function takes a default value and and Maybe value. If the Maybe is Nothing, it returns the default values otherwise, it returns the value contained in the Maybe.

Lazy version of fromMaybe.

If the computation of the default value for fromMaybe is non-trivial, use fromMaybe_, otherwise fromMaybe.

maybe :: b -> (a -> b) -> Maybe a -> b

The maybe function takes a default value, a function, and a Maybe value. If the Maybe value is Nothing, the function returns the default value. Otherwise, it applies the function to the value inside the Just and returns the result.

maybe_ :: (() -> b) -> (a -> b) -> Maybe a -> b

The maybe_ function takes a default value, a function, and a Maybe value. If the Maybe value is Nothing, the function returns the default value. Otherwise, it applies the function to the value inside the Just and returns the result.

Lazy version of maybe.

maybeRNull :: (a -> b) -> Maybe a -> b

maybeRNullF :: Maybe a -> (a -> b) -> b

listToMaybe :: [a] -> Maybe a

The listToMaybe function returns Nothing on an empty list or Just (a) where a is the first element of the list.

maybeToList :: Maybe a -> [a]

The maybeToList function returns an empty list when given Nothing or a singleton list when not given Nothing.

catMaybes :: [Maybe a] -> [a]

The catMaybes function takes a list of Maybes and returns a list of all the Just values.

mapMaybe :: (a -> Maybe b) -> [a] -> [b]

The mapMaybe function is a version of map which can throw out elements. If particular, the functional argument returns something of type Maybe b. If this is Nothing, no element is added on to the result list. If it is Just b, then b is included in the result list.

imapMaybe :: (Int -> a -> Maybe b) -> [a] -> [b]

The imapMaybe function is a version of imap which can throw out elements. If particular, the functional argument returns something of type Maybe b. If this is Nothing, no element is added on to the result list. If it is Just b, then b is included in the result list.

normalize :: (a | Maybe a) -> Maybe a

Creates a new Maybe from the given nullable value. If the value is already an instance of Maybe, it will just return the value.

ensure :: (a -> Bool) -> a -> Maybe a

Creates a new Just a from the given value if the given predicate evaluates to True and the given value is not nullable. Otherwise returns Nothing.

maybeToNullable :: Maybe a -> (a | null)

The maybeToNullable function returns null when given Nothing or returns the value inside the Just.

maybeToUndefined :: Maybe a -> (a | undefined)

The maybeToUndefined function returns undefined when given Nothing or returns the value inside the Just.

joinMaybeList :: Maybe [a] -> [a]

Returns an empty list on Nothing, otherwise the contained list.

isMaybe :: a -> Bool

The isMaybe function returns True if its argument is a Maybe.

Applicative

pure :: a -> Maybe a

Lift a value.

ap :: Maybe (a -> b) -> Maybe a -> Maybe b

Sequential application.

Alternative

alt :: Maybe a -> Maybe a -> Maybe a

Returns the first Maybe if it is Just, otherwise the second.

alt_ :: Maybe a -> Maybe a -> Maybe a

Returns the first Maybe if it is Just, otherwise the second.

Lazy version of alt.

altF :: Maybe a -> Maybe a -> Maybe a

Returns the second Maybe if it is Just, otherwise the first.

Flipped version of alt.

altF_ :: Maybe a -> Maybe a -> Maybe a

Returns the second Maybe if it is Just, otherwise the first.

Flipped version of alt_.

empty :: Maybe a

guard :: Bool -> Maybe ()

guard (true)  = pure (true)
guard (false) = empty

guard_ :: (() -> Bool) -> Maybe ()

guard_ (() => true)  = pure (true)
guard_ (() => false) = empty

Lazy version of guard.

guardReplace :: Bool -> a -> Maybe a

guardReplace (cond) (x) returns Just (x) if cond is True, otherwise Nothing.

Monad

bind :: Maybe a -> (a -> Maybe b) -> Maybe b

bindF :: Monad m => (a -> m b) -> m a -> m b

then :: Maybe a -> Maybe b -> Maybe b

Sequentially compose two actions, discarding any value produced by the first, like sequencing operators (such as the semicolon) in imperative languages.

a >> b = a >>= \ _ -> b

thenF :: Maybe a -> Maybe b -> Maybe a

Sequentially compose two actions, discarding any value produced by the second.

Flipped version of then.

kleisli :: (a -> Maybe b) -> (b -> Maybe c) -> a -> Maybe c

Left-to-right Kleisli composition of monads.

join :: Maybe (Maybe a) -> Maybe a

The join function is the conventional monad join operator. It is used to remove one level of monadic structure, projecting its bound argument into the outer level.

mapM :: (a -> Maybe b) -> [a] -> Maybe [b]

mapM f xs takes a function and a list and maps the function over every element in the list. If the function returns a Nothing, it is immediately returned by the function. If f did not return any Nothing, the list of unwrapped return values is returned as a Just. If xs is empty, Just [] is returned.

liftM2 :: (a1 -> a2 -> r) -> Maybe a1 -> Maybe a2 -> Maybe r

Promote a function to a monad, scanning the monadic arguments from left to right.

liftM3 :: (a1 -> a2 -> a3 -> r) -> Maybe a1 -> Maybe a2 -> Maybe a3 -> Maybe r

Promote a function to a monad, scanning the monadic arguments from left to right.

liftM4 :: Maybe m => (a1 -> a2 -> a3 -> a4 -> r) -> m a1 -> m a2 -> m a3 -> m a4 -> m r

Promote a function to a monad, scanning the monadic arguments from left to right.

liftM5 :: Maybe m => (a1 -> a2 -> a3 -> a4 -> a5 -> r) -> m a1 -> m a2 -> m a3 -> m a4 -> m a5 -> m r

Promote a function to a monad, scanning the monadic arguments from left to right.

Foldable

foldr :: (a -> b -> b) -> b -> Maybe a -> b

Right-associative fold of a structure.

foldl :: (b -> a -> b) -> b -> Maybe a -> b

Left-associative fold of a structure.

toList :: Maybe a -> [a]

List of elements of a structure, from left to right.

fnull :: Maybe a -> Bool

Test whether the structure is empty. The default implementation is optimized for structures that are similar to cons-lists, because there is no general way to do better.

flength :: Maybe a -> Int

Returns the size/length of a finite structure as an Int. The default implementation is optimized for structures that are similar to cons-lists, because there is no general way to do better.

elem :: Eq a => a -> Maybe a -> Bool

Does the element occur in the structure?

Always returns False if the provided Maybe is Nothing.

elemF :: Eq a => Maybe a -> a -> Bool

Does the element occur in the structure?

Always returns False if the provided Maybe is Nothing.

Flipped version of elem.

sum :: Num a => Maybe a -> a

The sum function computes the sum of the numbers of a structure.

product :: Num a => Maybe a -> a

The product function computes the product of the numbers of a structure.

Specialized folds

concat :: Maybe [a] -> [a]

The concatenation of all the elements of a container of lists.

concatMap :: (a -> [b]) -> Maybe a -> [b]

Map a function over all the elements of a container and concatenate the resulting lists.

and :: Maybe Bool -> Bool

and returns the conjunction of a container of Bools. For the result to be True, the container must be finite False, however, results from a False value finitely far from the left end.

and Nothing = true
and Just x  = x

or :: Maybe Bool -> Bool

or returns the disjunction of a container of Bools. For the result to be False, the container must be finite True, however, results from a True value finitely far from the left end.

or Nothing = false
or Just x  = x

orN :: Bool | Undefined -> Bool

orN True == True
orN False == False
orN Undefined == False

any :: (a -> Bool) -> Maybe a -> Bool

Determines whether any element of the structure satisfies the predicate.

any _ Nothing  = False
any f (Just x) = f x

all :: (a -> Bool) -> Maybe a -> Bool

Determines whether all elements of the structure satisfy the predicate.

any _ Nothing  = True
any f (Just x) = f x

Searches

notElem :: Eq a => a -> Maybe a -> Bool

notElem is the negation of elem.

find :: (a -> Bool) -> Maybe a -> Maybe a

The find function takes a predicate and a structure and returns the leftmost element of the structure matching the predicate, or Nothing if there is no such element.

Ord

gt :: Maybe a -> Maybe a -> Bool

Returns if the second value is greater than the first value.

If one of the values is Nothing, (>) always returns false.

lt :: Maybe a -> Maybe a -> Bool

Returns if the second value is lower than the first value.

If one of the values is Nothing, (<) always returns false.

gte :: Maybe a -> Maybe a -> Bool

Returns if the second value is greater than or equals the first value.

If one of the values is Nothing, (>=) always returns false.

lte :: Maybe a -> Maybe a -> Bool

Returns if the second value is lower than or equals the first value.

If one of the values is Nothing, (<=) always returns false.

Semigroup

mappend :: Semigroup a => Maybe a -> Maybe a -> Maybe a

Concatenates the Semigroups contained in the two Maybes, if both are of type Just a. If at least one of them is Nothing, it returns the first element.