Improve this page

…from Data.Maybe

Data.Maybe provided a way of modelling computations that may provide a value or not. Folktale 2 keeps the same structure, but there’re some changes in how you extract values out of Maybes and test them. You can look at the full documentation for Maybe for more detailed information.

Contents

Constructing

Constructing Maybe values remains the same, but the import changes.

Previously:

const Maybe = require('data.maybe');

Maybe.Just(1);
Maybe.Nothing();

Now:

const Maybe = require('folktale/maybe');

Maybe.Just(1);
Maybe.Nothing();

Pattern matching

Previously it was possible to pattern match on a Maybe value by using the .cata(patterns) method. This method would take the value inside of the data structure and pass it on as positional arguments to the proper function:

const Maybe = require('data.maybe');

Maybe.Just(1).cata({
  Just: (value) => value + 1,
  Nothing: () => 'nothing'
});
// ==> 2

Now, the preferred method in Maybe is .matchWith(patterns), which works similarly, but passes an object with the fields instead of each value as positional argument:

const Maybe = require('folktale/maybe');

Maybe.Just(1).matchWith({
  Just: (x) => x.value + 1,
  Nothing: () => 'nothing'
});
// ==> 2

Testing instances

Previously, Maybe had isJust and isNothing boolean properties, which could be accessed to test whether a particular value was a Just or a Nothing:

const Maybe = require('data.maybe');

const x = Maybe.Just(1);
const y = Maybe.Nothing();

x.isJust;     // ==> true
x.isNothing;  // ==> false

y.isJust;     // ==> false
y.isNothing;  // ==> true

Folktale 2 replaces these with a .hasInstance(value) function on the variant constructors and on the type. Variant testing can now be safely done with this function, including on values that may be null or undefined:

const Maybe = require('folktale/maybe');

const x = Maybe.Just(1);
const y = Maybe.Nothing();

Maybe.Just.hasInstance(x);    // ==> true
Maybe.Just.hasInstance(y);    // ==> false

Maybe.Nothing.hasInstance(x); // ==> false
Maybe.Nothing.hasInstance(y); // ==> true

You can also test if a value is of a particular type by using the type’s .hasInstance function:

Maybe.hasInstance(x);     // ==> true
Maybe.hasInstance(y);     // ==> true
Maybe.hasInstance(null);  // ==> false

Maybe.ap

The new applicativeFn.apply(applicativeValue) method is the recommended way of using applicative functors now, which is standardised across Folktale and independent of Fantasy-Land changes.

.apply and .ap still have the same semantics, but those semantics are different from the new fantasy-land/ap function! In order to write functions that are generic over different Fantasy-Land implementations and versions, the new fantasy-land module should be used instead.

Equality testing

Previously Maybe had a .isEqual method, which checked if two maybe values had the same tag and the same value (compared by reference):

const Maybe = require('data.maybe');

Maybe.Just(1).isEqual(Maybe.Just(1));
// ==> true

Maybe.Just([1]).isEqual(Maybe.Just([1]));
// ==> false

Now, Maybe and other Folktale structures have a .equals method that does a similar test, but compares values structurally if they’re Fantasy-Land setoids, arrays, or plain JavaScript objects:

const Maybe = require('folktale/maybe');

Maybe.Just(1).equals(Maybe.Just(1));
// ==> true

Maybe.Just([1]).equals(Maybe.Just([1]));
// ==> true

More details can be found on the Equality derivation documentation.

Maybe.get

Previously, Maybe had a .get() method that would extract the value out of a Just structure, but throw an error if you had a Nothing structure:

const Maybe = require('data.maybe');

Maybe.Just(1).get();    // ==> 1
Maybe.Nothing().get();  // ==> [Error: Can't extract the value of a Nothing]

This was unsafe, so in order to clearly signal that Folktale 2 has deprecated all .get() methods, and introduced a new .unsafeGet() one. You may use the new .unsafeGet() one if you really know what you’re doing, but the method name now signals that you should be careful with it:

const Maybe = require('folktale/maybe');

Maybe.Just(1).unsafeGet();    // ==> 1
Maybe.Nothing().unsafeGet();  // ==> [Error: Can't extract the value of a Nothing]

You’re strongly encouraged to use the .getOrElse(default) method instead, which does not suffer from the same partiality problem:

Maybe.Just(1).getOrElse(null);      // ==> 1
Maybe.Nothing().getOrElse(null);    // ==> null

Maybe.fromEither

Either was replaced by Result in Folktale 2, and so the new method is Maybe.fromResult.

Please see the Migrating from Data.Either documentation if you have Either values in your code base.

Maybe.toJSON and Maybe.fromJSON

There was some experimental support in the old Maybe structure for serialisation to and parsing from JSON structures:

const Maybe = require('data.maybe');

Maybe.Just(1).toJSON();

const Enc = require('encoding.json');
const MaybeEnc = require('data.maybe/encoding')(Enc);

MaybeEnc.fromJSON(Maybe.Just(1).toJSON());

The new Folktale has a more standardised (and general) way of serialising and parsing its algebraic data structures, so each structure provides its own .toJSON() and .fromJSON():

const Maybe = require('data.maybe');
Maybe.Just(1).toJSON();
Maybe.fromJSON(Maybe.Just(1).toJSON());

More details can be found on the Serialization derivation documentation.

« …from Data.Either
…from Data.Task »