Class: Maybe

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

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

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}

data/Maybe.js, line 315

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}

data/Maybe.js, line 337

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}

data/Maybe.js, line 376

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}

data/Maybe.js, line 380

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);

get(){*}

data/Maybe.js, line 411

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}

data/Maybe.js, line 431

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}

data/Maybe.js, line 451

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}

data/Maybe.js, line 501

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}

data/Maybe.js, line 484

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}

data/Maybe.js, line 505

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()

of()

data/Maybe.js, line 528

See:

• Maybe.ofNullable

abstractorElse(method){*}

data/Maybe.js, line 532

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){*}

data/Maybe.js, line 552

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){*}

data/Maybe.js, line 571

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}

data/Maybe.js, line 591

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}

data/Maybe.js, line 615

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}

data/Maybe.js, line 638

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}

data/Maybe.js, line 656

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]);