Class: Maybe

Maybe

The Maybe type is intended for values that may or may not be null or undefined. It is a disjunction similar to Either. The key difference of the Maybe type is the focus on a value or nothing. Much like Either, Maybe is right-biased.

new Maybe(value){Maybe}

Name Type Description
value * Value to wrap.
Returns:
Type Description
Maybe Maybe wrapped value.
Examples

Via new

const v1 = new Just(value);
const v2 = new Nothing();

Via function

const v3 = Just.from(value);
const v4 = Nothing.from();

Via Maybe function

const getOr = require("lodash/fp/getOr");
const Maybe = require("lodash-fantasy/data/Maybe");

function getValue(path, context) {
  return getOr(Maybe.Nothing.from(), path, context);
}

module.exports = getValue;

Members

staticMaybe.all

Returns a Maybe that resolves all of the maybes in the collection into a single Maybe.
Example
const m1 = getArbitraryProperty(context1);
// => Just(context1)

const m2 = getArbitraryProperty(context2);
// => Just(context2)

const m3 = getArbitraryProperty(context3);
// => Nothing()

const m4 = getArbitraryProperty(context4);
// => Nothing()

Maybe.all([m1, m2]);
// => Just([context1, context2])

Maybe.all([m1, m2, m3]);
// => Nothing()

Maybe.all([m1, m2, m3, m4]);
// => Nothing()

staticMaybe.any

Returns the first Just in the collection or finally a Nothing.
Example
const m1 = getArbitraryProperty(context1);
// => Just(context1)

const m2 = getArbitraryProperty(context2);
// => Just(context2)

const m3 = getArbitraryProperty(context3);
// => Nothing()

const m4 = getArbitraryProperty(context4);
// => Nothing()

Maybe.any([m1, m2]);
// => Just(context1)

Maybe.any([m2, m3]);
// => Just(context2)

Maybe.any([m3, m4]);
// => Nothing()

staticMaybe.each

Iterates over a collection of maybes and invokes the iteratee for each Maybe. The iteratee is invoked with one argument: (value). Iteratee functions may exit iteration early by explicitly returning a Nothing.
Example
const optionalValues = [
  getValue(path1, source), // => Just(value1)
  getValue(path2, source), // => Just(value2)
  getValue(path3, source), // => Nothing()
  getValue(path4, source) // => Nothing()
];

Maybe.each(optionalValue => optionalValue.ifJust(console.log), optionalValues);
// => Just(value1)
// => Just(value2)

staticMaybe.equals

Determines whether or not the other is equal in value to the current (this). This is not a reference check.
Examples

Reflexivity

Maybe.equals(v1, v1) === true;
// => true

Symmetry

Maybe(v1, v2) === Maybe.equals(v2, v1);
// => true

Transitivity

(Maybe.equals(v1, v2) === Maybe.equals(v2, v3)) && Maybe.equals(v1, v3)
// => true

staticMaybe.filter

Iterates over a collection of values, returning an array of all values the predicate for which returns truthy. The predicate is invoked with one argument: (value).
Example

Filter and log failures

const optionalValues = [
  getValue(path1, config), // => Just(value1)
  getValue(path2, config), // => Just(value2)
  getValue(path3, config), // => Nothing()
  getValue(path4, config) // => Nothing()
];

Maybe.filter(Maybe.isJust, optionalValues);
// => [Just(value1), Just(value2)]

staticMaybe.from

Creates a new Maybe from a value. If the value is already a Maybe instance, the value is returned unchanged. Otherwise, a new Just is made with the value.

staticMaybe.isJust

Determines whether or not the value is a Just.
Example
isJust();
// => false

isJust(null);
// => false

isJust(Just.from());
// => true

isJust(Nothing.from());
// => false

staticMaybe.isMaybe

Determines whether or not the value is a Maybe.
Example
isMaybe();
// => false

isMaybe(null);
// => false

isMaybe(Just.from());
// => true

isMaybe(Nothing.from());
// => true

staticMaybe.isNothing

Determines whether or not the value is a Nothing.
Example
isNothing();
// => false

isNothing(null);
// => false

isNothing(Nothing.from());
// => true

isNothing(Just.from());
// => false

staticMaybe.Just

Properties:
Name Type Description
Just Just Maybe just.

staticMaybe.map

Creates an array of values by running each Maybe in collection through the iteratee. The iteratee is invoked with one argument: (value).
Example

Mapping all values to promises

const optionalValues = [
  getValue(path1, config), // => Just(value1)
  getValue(path2, config), // => Just(value2)
  getValue(path3, config), // => Nothing()
  getValue(path4, config) // => Nothing()
];

Maybe.map(Maybe.toPromise, optionalValues);
// => [Promise.resolve(price1), Promise.resolve(price2), Promise.reject(null), Promise.reject(null)]

staticMaybe.mapIn

Creates an array of values by invoking Maybe#map with the iteratee for each Maybe in the collection. The iteratee is invoked with one argument: (value).
Example

Mapping each Maybe's value

const optionalValues = [
  getValue(path1, config), // => Just(1.5)
  getValue(path2, config), // => Just(2.25)
  getValue(path3, config), // => Nothing()
  getValue(path4, config) // => Nothing()
];

Maybe.mapIn(Math.floor, optionalValues);
// => [Just(1), Just(2), Nothing(), Nothing()]

staticMaybe.Nothing

Properties:
Name Type Description
Nothing Nothing Maybe nothing.

staticMaybe.of

Wraps the value in a Just. No parts of value are checked.
Example
Maybe.of();
// => Just()

Maybe.of(true);
// => Just(true)

Maybe.of(Just.from(value));
// => Just(Just(value))

Maybe.of(Nothing.from());
// => Just(Nothing())

staticMaybe.ofNullable

Wraps the value in a Just if the value is not null, undefined, or Nothing.
Example
Maybe.ofNullable();
// => Nothing()

Maybe.ofNullable(null);
// => Nothing()

Maybe.ofNullable(true);
// => Just(true)

Maybe.ofNullable(Just.from(value));
// => Just(Just(value))

Maybe.ofNullable(Nothing.from());
// => Nothing()

staticMaybe.reduce

Reduces collection to a value which is the accumulated result of running each value in the values collection through the iteratee, where each successive invocation is supplied the return value of the previous. The iteratee is invoked with two arguments: (accumulator, value).
Example
const optionalValues = [
  getValue(path1, config), // => Just(value1)
  getValue(path2, config), // => Just(value2)
  getValue(path3, config), // => Nothing()
  getValue(path4, config) // => Nothing()
];

// Using lodash/fp/concat
Maybe.reduce(
  (result, value) => value.isJust() ? concat(result, value.get()) : result,
  [],
  optionalValues
);
// => [value1, value2]

staticMaybe.toEither

Converts a Maybe to a Either. Just becomes a Right and Nothing becomes a Left.
Examples

Just to Right

Maybe.toEither(Either, Just.from(value));
// => Either.Right(value);

Nothing to Left

Maybe.toEither(Either, Nothing.from());
// => Either.Left(null);

staticMaybe.toPromise

Converts a validation to a Promise using the provided Promise implementation.
Example

Convert with bluebird's implementation of Promise

const toBluebird = Maybe.toPromise(require("bluebird"));

toBluebird(Just.from(value));
// => Promise.resolve(value);

toBluebird(Nothing.from());
// => Promise.reject(null);

staticMaybe.toValidation

Converts a Maybe to a Validation. Just becomes a Success and Nothing becomes a Failure.
Examples

Just to Success

Maybe.toValidation(Validation, Just.from(value));
// => Validation.Success(value);

Nothing to Failure

Maybe.toValidation(Validation, Nothing.from());
// => Validation.Failure(null);

staticMaybe.try

Tries to invoke a supplier. The result of the supplier is returned in a Just. If an exception is thrown, a Nothing is returned. The function takes no arguments.
Example
Maybe.try(normalFunction);
// => Just(returnValue)

Maybe.try(throwableFunction);
// => Nothing()

Methods

abstractap(other){Maybe}

Applies the function contained in the instance of a Just to the value contained in the provided Just, producing a Just containing the result. If the instance is a Nothing, the result is the Nothing instance. If the instance is a Just and the provided Maybe is Nothing, the result is the provided Nothing.
Name Type Description
other Maybe Value to apply to the function wrapped in the Just.
Returns:
Type Description
Maybe Just wrapped applied function or Nothing.
Example

Just#ap

const findPerson = curryN(3, Person.find); // Person.find(name, birthdate, address)

Just.from(findPerson) // => Just(findPerson)
  .ap(Just.ofNullable(name)) // => Just(name)
  .ap(Just.ofNullable(birthdate)) // => Just(birthdate)
  .ap(Just.ofNullable(address)) // => Just(address)
  .ifJust(console.log); // => Log Person.find() response

abstractchain(method){Maybe}

Applies the provided function to the value contained for a Just. The function should return the value wrapped in a Maybe. If the instance is a Nothing, the function is ignored and then instance is returned unchanged.
Name Type Description
method Chain.<Maybe> The function to invoke with the value.
Returns:
Type Description
Maybe Maybe wrapped value returned by the provided method.
Example

Just#chain

// Using lodash/fp/curry and get
const getConfigOption = curry((path, config) => Maybe.ofNullable(get(path, config));

Maybe.ofNullable(config)
  .chain(getConfigOption("path.to.option"))

equals(other){Boolean}

Determines whether or not the other is equal in value to the current (this). This is not a reference check.
Name Type Description
other * Other value to check.
Returns:
Type Description
Boolean true if the two Maybes are equal; false if not equal.
Examples

Reflexivity

v1.equals(v1) === true;
// => true

Symmetry

v1.equals(v2) === v2.equals(v1);
// => true

Transitivity

(v1.equals(v2) === v2.equals(v3)) && v1.equals(v3)
// => true

abstractextend(){Maybe}

Extends the Maybe. This is used for workflow continuation where the context has shifted.
Type Description
Extend.<Maybe> method - The function to invoke with the value.
Returns:
Type Description
Maybe
Example

Workflow continuation

// Workflow from makeRequest.js
const makeRequest = requestOptions => requestAsPromise(requestOptions)
  .then(Just.from)
  .catch(Nothing.from);

// Workflow from savePerson.js
const savePerson = curry((requestOptions, optionalPerson) => optionalPerson
  .map(Person.from)
  .map(person => set("body", person, requestOptions))
  .map(makeRequest)
);

// Workflow from processResponse.js
const processResponse = optionalResponse => optionalResponse
  .ifJust(console.log);

Maybe.ofNullable(person)
  .extend(savePerson({ method: "POST" }))
  .extend(processResponse);
Returns the value if the instance is a Just otherwise the null.
Returns:
Type Description
*
Examples

Just#get

Just.from(value).get();
// => value

Nothing#get

Nothing.from().get();
// => null

abstractifJust(method){Maybe}

Applies the provided function to the value contain for a Just. Any return value from the function is ignored. If the instance is a Nothing, the function is ignored and the instance is returned.
Name Type Description
method Consumer The function to invoke with the value.
Returns:
Type Description
Maybe Current instance.
Examples

Just#ifJust

Just.from(value).ifJust(doSomething); // doSomething(value)
// => Just(value)

Nothing#ifJust

Nothing.from().ifJust(doSomething); // void
// => Nothing()

abstractifNothing(method){Maybe}

Applies the provided function to the value contain for a Nothing. Any return value from the function is ignored. If the instance is a Just, the function is ignored and the instance is returned.
Name Type Description
method Callable The function to invoke.
Returns:
Type Description
Maybe Current instance.
Examples

Just#ifNothing

Just.from(value).ifNothing(doSomething); // void
// => Just(value)

Nothing#ifNothing

Nothing.from().ifNothing(doSomething); // doSomething()
// => Nothing()

isJust(){Boolean}

Determines whether or not the instance is a Just.
Returns:
Type Description
Boolean true if the instance is a Just; false is not.
Examples

Just

Just.from(value).isNothing();
// => true

Nothing#isJust

Nothing.from().isNothing();
// => false

isNothing(){Boolean}

Determines whether or not the instance is a Nothing.
Returns:
Type Description
Boolean true if the instance is a Nothing; false is not.
Examples

Just#isNothing

Just.from(value).isNothing();
// => false

Nothing#isNothing

Nothing.from().isNothing();
// => true

abstractmap(method){Maybe}

Applies the provided function to the value contained for a Just which is, in turn, wrapped in a Just. If the instance is a Nothing, the function is ignored and then instance is returned unchanged.
Name Type Description
method function The function to invoke with the value.
Returns:
Type Description
Maybe Maybe wrapped value mapped with the provided method.
Example
// Using lodash/fp/flow and sort
Just.from([1, 3, 2]).map(flow(sort, join(", ")));
// => Just("1, 2, 3")

Nothing.from().map(flow(sort, join(", ")));
// => Nothing()
See:

abstractorElse(method){*}

Returns the value if the instance is a Just otherwise returns the value supplied if the instance is a Nothing.
Name Type Description
method Consumer The function to invoke with the value.
Returns:
Type Description
*
Examples

Just#orElse

Just.from(value).orElse(otherValue);
// => value

Nothing#orElse

Nothing.from().orElse(otherValue);
// => otherValue

abstractorElseGet(method){*}

Return the value if the instance is a Just otherwise returns the value from the function provided.
Name Type Description
method Supplier The function supplying the optional value.
Returns:
Type Description
*
Examples

Just#orElseGet

Just.from(value).orElseGet(getOtherValue);
// => value

Nothing#orElseGet

Nothing.from().orElseGet(getOtherValue);
// => otherValue

abstractorElseThrow(method){*}

Returns the value if the instance is a Just otheriwse throws the Error supplied by the function provided.
Name Type Description
method Supplier The function to invoke with the value.
Throws:
returned by the provided function.
Type
Error
Returns:
Type Description
*
Examples

Just#orElseThrow

Just.from(value).orElseThrow(createException);
// => value

Nothing#orElseThrow

Nothing.from().orElseThrow(createException); // throw createException()

abstracttoEither(either){Either}

Converts the Maybe to an Either. Just becomes a Right and Nothing becomes a Left.
Name Type Description
either Either Either implementation.
Returns:
Type Description
Either Either wrapped value.
Examples

Just#toEither

const Either = require("lodash-fantasy/data/Either");

Just.from(value).toEither(Either);
// => Either.Right(value);

Nothing#toEither

const Either = require("lodash-fantasy/data/Either");

Nothing.from().toEither(Either);
// => Either.Left(null);

abstracttoPromise(promise){Promise}

Converts the Maybe to a Promise using the provided Promise implementation.
Name Type Description
promise Promise Promise implementation.
Returns:
Type Description
Promise Promise wrapped value.
Examples

Just#toPromise

const Bluebird = require("bluebird");

Just.from(value).toPromise(Bluebird);
// => Promise.resolve(value);

Nothing#toPromise

const Bluebird = require("bluebird");

Nothing.from().toPromise(Bluebird);
// => Promise.reject(null);

abstracttoString(){String}

Returns a String representation of the Maybe.
Returns:
Type Description
String String representation.
Examples

Just#toString

Just.from(1).toString();
// => "Maybe.Just(1)"

Nothing#toString

Nothing.from().toString();
// => "Maybe.Nothing(null)"

abstracttoValidation(validation){Validation}

Converts the Maybe to an Validation. Just becomes a Success and Nothing becomes a Failure.
Name Type Description
validation Validation Validation implementation.
Returns:
Type Description
Validation Validation wrapped value.
Examples

Just#toValidation

const Validation = require("lodash-fantasy/data/Validation");

Just.from(value).toValidation(Validation);
// => Validation.Success(value);

Nothing#toValidation

const Validation = require("lodash-fantasy/data/Validation");

Nothing.from().toValidation(Validation);
// => Validation.Failure([null]);