simple-maybe
v1.4.0
Published
A Simple Maybe Monad Module. Plays nice with Ramda.
Downloads
96
Maintainers
Readme
Simple Maybe Monad
simple-maybe
is a simple, lightweight Maybe
monad module.
It is written in the Either
-style pattern of a with Just
and Nothing
as the left/right identities.
This library plays very well with Ramda.
What is a "Maybe"?
The term Maybe
comes from functional programming. The concept is simple: maybe there is a value, maybe there is not. Using this concept helps handle problems that can arise from allowing a value in Javascript to become null
or undefined
.
Maybe
puts a value into a safe container that isolates the value away from being able to cause side-effects.
API
The API follows pattern that is common in functional Javascript programming:
const container = Maybe.of(value);
Because value
is a complete unknown, which may even be undefined
even, we now interact with the value using its container.
Taking a peek at a value
At any time, you can emit a value though. Either through the console, or in the code itself:
>> container.inspect();
"Just(1)"
This indicates the value is 1
. But what if it was null
?
>> container.inspect();
"Nothing"
In short, within the container, there is either a Just
value, or Nothing
value. Both can have all the same methods applies to them, the difference being that Nothing
will always return Nothing
and Just
will execute as normal.
Mapping functions
Running functions against the value is easy using .map(f)
(alias: .fmap(f)
).
As an example, let's try to add 1
to the value:
const newContainer = container.map(value => value + 1);
Chaining functions
Much like map
, chain
(aliases: flatMap
, bind
) can take a function and return the result -- though it will not be automatically rewrapped in a Maybe
. This is useful if you plan within your function to return a Maybe
or convert to another monad type.
const newContainer = container.chain(value => Maybe.of(value + 1));
Unwrapping a value
In code, you can get the value through a .emit()
(alias: .join()
):
const container = Maybe.of(1);
const value = container.emit(); // value === 1
If you're looking to avoid ever assigning null
or undefined
, there are better ways to get your value out.
Consider .fork(f, g)
:
const result = container.fork(
x => {
// we got a Nothing, so lets handle our invalid case:
return 'There was no value';
},
y => {
// we got Just(y), lets return the value
return 'We got a value: ' + y;
}
);
In .fork(f, g)
, you pass in two functions: f
, the first to handle the Nothing
case; g
, the other to handle the Just
(actual value) case.
forkL
and forkR
For the sake of brevity, you may also use .forkL(f)
(left) or .forkR(f)
(right) to run a function f
against only one case. This is useful when you only want to handle one condition and do not need to do anything with the other.
const result = container.forkL(
x => {
// we got a Nothing, so lets handle our invalid case:
return "There was no value";
});
);
const result2 = container.forkR(
y => {
// we got Just(y), lets return the value
return 'We got a value: ' + y;
});
);
Bringing things together
You may chain all these together, much like you may see in Promise
s.
const result = Maybe.of(value)
.map(val => val + 1)
.fork(x => 'there was no value', y => `the value was: ${y}`);
// if value = 1, result = "the value was: 2"
// if value = null, result = "there was no value" (JS did not try to add null + 1)
// if value = "string", result = "the value was: string1"
Roadmap
No changes planned, outside of documentation. Small functional programming libraries don't tend to change much. But they do tend to lack good, readable documentation.
License
The MIT License (MIT)
Copyright (c) 2018-2019 Robert Gerald Porter
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.