@oncomouse/call-me-maybe v1.0.5

Call Me Maybe – Daggy-based, Fantasy-Land-compliant Maybe

This library is an implementation of the Maybe ADT based on Fantasy Land's daggy implementation.

Folktale contains a very good implementation of the Maybe type, but it does not implement Fantasy Land's Alt specification. Additionally, Folktale's Maybe type is not easily extended, so I wrote this one, using daggy, which uses plain objects to build ADTs and is therefore very extensible.

Installing

To install, run:

npm install @oncomouse/call-me-maybe

Or

yarn add @oncomouse/call-me-maybe

You can now run require('@oncomouse/call-me-maybe') to access the library.

Using on Web Pages

You can also include the library in web pages using unpkg:

<script src="https://unpkg.com/@oncomouse/call-me-maybe/dist/call-me-maybe.min.js"></script>

This file includes the full environment needed to use the Maybe type in your projects.

Override Equality

This library uses epoberezkin/fast-deep-equals for equality checking. It is an ok (and small) implementation. Lodash, Ramda, and Sanctuary's equality methods are all around 40K, which is a lot to implement Setoid. If, however, you want to use a different library, you can add it to Maybe by re-assigning the value of Maybe._equals. For instance:

var Maybe = require('@oncomouse/call-me-maybe');
var {equals} = require('ramda');

Maybe._equals = equals; // Now using Ramda's equality check

API

Take a look at this explanation from Fantasy Land for information on reading the function type signatures below.

Type Methods

The following methods are applied to the Typeclass itself:

Maybe.of(5) // Maybe.Just(5)
Maybe.empty() // Maybe.Nothing
Maybe.zero() // Maybe.Nothing

of Method

Return a Maybe.Just instance containing the supplied data.

of :: Maybe f => a -> f a

empty Method

Return the empty (Maybe.Nothing) version of this type.

empty :: Nothing

zero Method

Return the zero (Maybe.Nothing) version of this type.

zero :: Nothing

Member Methods

The following methods are available to members of the type:

var a = Maybe.Just(7)
var b = Maybe.Just(6)
var f = Maybe.of(x => x + 4)

a.equals(b) // false
a.map(x => x + 2) // Maybe.Just(9)
f.apply(a) // Maybe.Just(11)
a.ap(f) // Maybe.Just(11)
a.chain(x => Maybe.of(x+4)) // Maybe.Just(11)
a.unsafeGet() // 7
Maybe.Nothing.unsafeGet() // Error
a.getOrElse(5) // 7
Maybe.Nothing.getOrElse(5) // 5
Maybe.of([]).concat(Maybe.of([5])) // [5]
Maybe.Nothing.fold(() => Maybe.Just(false), x => Maybe.Just(x + 1)) // Maybe.Just(false)
a.filter(x => x < 5) // Maybe.Nothing
Maybe.Nothing.alt(a) // Maybe.Just(7)

equals Method

Compare the equality of one Maybe with another.

equals :: Maybe f => f a ~> f b -> Boolean

map Method

Apply a transformation function to a Maybe.

The transformation function does not itself return a Maybe.

map :: Maybe f => f a ~> (a -> b) -> f b

apply Method

Called on a Maybe that contains a function with a Maybe that contains a value, return the Maybe that holds the result of the function applied to the value.

apply :: Maybe f => f (a -> b) ~> f a -> f b

ap Method

Called on a Maybe that contains a value with a Maybe that contains a function, return the Maybe that holds the result of the function applied to the value.

ap :: Maybe f => f a ~> f (a -> b) -> f b

chain Method

Called on a Maybe that contains a value with a function that takes a value and returns a Maybe, return the result of that function.

chain :: Maybe f => f a ~> (a -> f b) -> f b

unsafeGet Method

Get the value of a Maybe but will throw an error if called on Maybe.Nothing.

unsafeGet :: Maybe f => f a ~> a

getOrElse Method

Called on a Maybe that contains a value with another value, return the value of the Maybe or the default value if the Maybe is Maybe.Nothing.

getOrElse :: Maybe f => f a ~> a -> a

concat Method

Called on a Maybe whose value has a concat() or a fantasy-land/concat() method with another maybe containing the same kind of value, return a Maybe containing the result of concatenating the second value to the first.

concat :: Maybe f => f a ~> f a -> f a

fold Method

Called on a Maybe with two functions, return the result of the first if the Maybe is Maybe.Nothing and a Maybe with the result of the second function applied to the value of the Maybe.

fold :: Maybe f => f a ~> (_ -> f b) -> (a -> f b) -> f b

filter Method

Called on a Maybe and function that takes a value and returns a Boolean, either return the Maybe or Maybe.Nothing if the Boolean is false.

filter :: Maybe f => f a ~> (a -> Boolean) -> f a

alt Method

Called on a Maybe with another Maybe, return the first Maybe unless the first is Maybe.Nothing, in which case return the second Maybe.

alt :: Maybe f => f a ~> f a -> f a

Fantasy Land Interface

The following methods from the API have Fantasy Land compliant equivalents:

• of -> fantasy-land/of
• empty -> fantasy-land/empty
• zero -> fantasy-land/zero
• equals -> fantasy-land/equals
• map -> fantasy-land/map
• ap -> fantasy-land/ap
• chain -> fantasy-land/chain
• concat -> fantasy-land/concat
• filter -> fantasy-land/filter
• alt -> fantasy-land/alt

So, for instance:

equals(
    Maybe.of([6]).concat(Maybe.of[7])
    , Maybe['fantasy-land/of']([6])['fantasy-land/concat'](Maybe['fantasy-land/of']([7]))
) === true

Fantasy Land Type Implementations

This library implements the following Fantasy Land specifications:

• Setoid
• Semigroup
• Monoid
• Filterable
• Functor
• Apply
• Applicative
• Alt
• Plus
• Alternative
• Chain
• Monad