Which Maybe method am I supposed to use now? (API guide)
We've all been in that research phase where we're still learning the API of library and deciding if it suits our usecases.
The purpose of this guide is to make that process easier by grouping all available methods for the Maybe data type.
Scenario #1 - I want to use Maybe but my codebase already has null/undefined all over the place
One of purify's main goals is great interoperability with existing code. That is why the API for Maybe is rich in utility methods for working with nullable values.
One might question the usage of Maybe (and purify) if you are still going to use nulls, there are already a lot of utility libraries like ramda and lodash that allow you to do that. Maybe.fromNullable
With purify you can start using ubiquitous data structures that come with a lot of literature and examples in various programming languages (in this case Maybe)
without sacrificing coding style or ease of interop, that's why using it instead of other libraries might be a good idea.
These methods allow you to construct Maybe values from, as the names suggest, nullable and falsy values or in the case of the encase
method - from a function that may throw an exception.
`fromPredicate` is on the list because it can be used to cover all kinds of complicated checks, for example:
const _ = Maybe.fromPredicate(x => x && x.length > 0, value)
Now that you have constructed your Maybe out of an optional value, you may want to transform it with a function that returns yet another optional value.
If you are already familiar with the chain
method (a.k.a. bind
) you may think of using it in combination with any of the methods mentioned above:
myMaybe.chain(x => Maybe.fromNullable(transform(x)))
There's nothing wrong with that approach, but there's a helper method called `chainNullable` that does exactly the same thing
without you having to manually construct a Maybe out of the return value of the transformation function.
myMaybe.chainNullable(x => transform(x))
// or just straight up
Sometimes you have to interact with code that expects a nullable value, in that case you can just unwrap a Maybe down to a primitive value like null or undefined using the methods above.
Please note that while you may be tempted to wrap and unwrap manually every time you encounter a nullable value,
consider that code designed with Maybe in mind is easier to maintain and use in the long term.
Try to keep usage of the methods mentioned in this part of the guide low and only for compatibility reasons.
Don't be afraid to start returning or expecing Maybe values in functions, you'll notice some benefits you haven't considered before!
Scenario #2 - I'm not sure how to check if a value exists or not
There are numerous ways to check if a value exists with purify, but I want to focus on the fact that you rarely need to do so explicitly.
Try to split up your code into functions and then find ways to combine them using many of the available transformation methods likeMaybe#map
... you get the point.
There are so many methods you can chain so that your code is nice and declarative that you'll almost never have to unpack a Maybe and check manually.
There are some cases where that is needed though, let's go through them: Maybe#isJust
The most primitive of the bunch, these methods enable us to do JS-style checking if a value is missing or not.
The method names are pretty self-explanatory so we won't go into much details, but it's generally not recommend to use those methods.
Better choices are almost always available.Maybe#caseOf
is the go-to choice when none of the other methods seem good enough.
is very, very similar, in fact it's so similar that it looks almost useless. The goal of reduce is to provide an instance for the Foldable typeclass for Maybe.
If you like the minimalism of reduce and you don't care about Foldable or you haven't heard of it - no problem, you can use it instead of caseOf just fine!