@wmakeev/maybes
v1.0.1
Published
This is fork of 'maybes' ported to TypeScript and added some new features
Downloads
8
Maintainers
Readme
Maybe
This is fork of maybes
CHANGES IN THIS FORK
code ported to TypeScript (also with typings)
new
get
method implemented internally withlodash.get
modulemaybe#map argument function can return nil
.map(v => null)
, in this case the result to benothing
(the author of maybes does not approve of this behavior, but using.flatMap(v => maybe(v) ...
is to much boring in some simple cases)
Description
Maybe is a type that wraps optional values. It can either be a Just
(has some value) or a Nothing
(has no value).
It's defined like this: type Maybe<A> = Just<A> | Nothing
In JavaScript, it is a better way of handling null
and undefined
. Instead of writing an if
statement, ternary expression, or &&
shorthand to check if a value is present you can just map
over it instead and assign the result of this expression or return it. You can also chain operations
together, often leading to much cleaner code.
It's inspired by Haskell's Maybe, Swift's Optional and Scala's Option.
Installation
Using yarn
$ yarn add @wmakeev/maybes
or npm
$ npm install @wmakeev/maybes
Usage
Import the library:
import { maybe } from '@wmakeev/maybes'
or if you want everything:
import { maybe, just, nothing } from '@wmakeev/maybes'
Use the maybe
function to create a Maybe
from a value.
const value = maybe(1) // Just(1)
value.isJust() // true
value.isNothing() // false
Use map
to transform the value inside the Maybe
.
value.map(v => v + 1) // Just(2)
Use get
to get property at path of value object inside the Maybe
.
const objValue = maybe({ book: { id: '3' } })
objValue.get('book.id') // Maybe(3)
Force unwrap the value with just()
if it is present. Warning: this will throw an Error if it
is a Nothing
(has no value).
value.just() // 1 (or throws Error)
Use the maybe
function to wrap a possibly empty value.
const empty = maybe(null)
empty.isJust() // false
empty.isNothing() // true
empty.map(v => v + 1) // noop (No Operation)
empty.just() // throws error
Use orJust()
to provide a default value.
empty.map(v => v.toUpperCase()).orJust('hello') // 'hello'
empty.get('some.path').orJust('hello') // 'hello'
Use orElse()
to provide a default already wrapped in a Maybe. This can be useful if you want to combine
two or more Maybe's together.
const hello = maybe('hello')
empty.map(v => v.toUpperCase()).orElse(hello) // Maybe('hello')
Chain operations together using map
:
const m = maybe('Maybe ')
const result = m
.map(v => v.trim())
.map(v => v.toUpperCase()) // Just('MAYBE')
Use flatMap
if you need to return a Maybe
in your closure instead of the value. For example,
when you want to explicitly return Nothing
in a particular case.
const a = maybe('hi')
const result = a.flatMap(v => {
if (v === 'hi') {
return just('world')
} else {
return nothing
}
})
just
is a function like maybe
that takes a value. nothing
is a reference to Nothing
.
Using filter
is usually the best way to return a Nothing
given a predicate. It returns
Just
only if there is a value and applying the predicate function to the Maybe
's value returns
true
.
const name = maybe(' ')
const upper = name
.map(v => v.trim())
.filter(v => v.length != 0)
.map(v => v.toUpperCase())
Use forEach
when you would otherwise use map
but can't or don't want to return a value. This
is usually when you are causing a side effect. forEach
returns void
and so enforces it's the
last in a chain. It runs only if there is a non empty value.
maybe('effect').forEach(s => console.log(s))
Types
This library uses Flowtype so you can also import the Maybe
type and use
its definition:
import { maybe } from 'maybes'
import type { Maybe } from 'maybes'
function getSomething(): Maybe<string> {
return maybe('something')
}
Don't worry if you don't use Flowtype though as it gets stripped by Babel.
Comparison with vanilla JavaScript
Ternary function that optionally calls another function called transform
.
Without Maybe
(value) ? transform(value) : null
(Safe version in case value is falsy, e.g. 0
)
(value != null) ? transform(value) : null
With Maybe (handles falsy values like 0
and ''
automatically).
maybe(value).map(transform)
&& and || shorthand
Without Maybe
const object: ?Object = {
value?: 'hello'
}
object && object.value && object.value.toUpperCase() || ''
With Maybe
maybe(object).flatMap(o => maybe(o.value).map(v => v.toUpperCase())).orJust('')
or
maybe(object).get('value').map(v => v.toUpperCase())).orJust('')
With types already converted to Maybe
's.
const object = maybe({
value: maybe('hello')
})
object.flatMap(o => o.value.map(v => v.toUpperCase())).orJust('')
Dependencies
lodash.get
- forget
method support
License
Maybe is available under the MIT license. See LICENSE.