This is useful when you have another Maybe value you want to provide if and only if* you have a Just – that is, when you need to make sure that if you Nothing, whatever else you're handing a Maybe to also gets a Nothing.

Notice that, unlike in map or its variants, the original maybe is not involved in constructing the new Maybe.

import Maybe from 'true-myth/maybe';

const justA = Maybe.just('A');
const justB = Maybe.just('B');
const nothing: Maybe<number> = nothing();

console.log(Maybe.and(justB, justA).toString());  // Just(B)
console.log(Maybe.and(justB, nothing).toString());  // Nothing
console.log(Maybe.and(nothing, justA).toString());  // Nothing
console.log(Maybe.and(nothing, nothing).toString());  // Nothing

This differs from map in that thenFn returns another Maybe. You can use andThen to combine two functions which both create a Maybe from an unwrapped type.

You may find the .then method on an ES6 Promise helpful for comparison: if you have a Promise, you can pass its then method a callback which returns another Promise, and the result will not be a nested promise, but a single Promise. The difference is that Promise#then unwraps all layers to only ever return a single Promise value, whereas Maybe.andThen will not unwrap nested Maybes.

This is sometimes also known as bind, but not aliased as such because bind already means something in JavaScript.

(This is a somewhat contrived example, but it serves to show the way the function behaves.)

import Maybe, { andThen, toString } from 'true-myth/maybe';

// string -> Maybe<number>
const toMaybeLength = (s: string) => Maybe.of(s.length);

// Maybe<string>
const aMaybeString = Maybe.of('Hello, there!');

// Maybe<number>
const resultingLength = andThen(toMaybeLength, aMaybeString);
console.log(toString(resultingLength)); // 13

Note that the result is not Just(Just(13)), but Just(13)!

import { just, nothing } from 'true-myth/maybe';

const one = just(1);
const five = just(5);
const none = nothing();

const add = (a: number) => (b: number) => a + b;
const maybeAdd = just(add);

maybeAdd.ap(one).ap(five); // Just(6)
maybeAdd.ap(one).ap(none); // Nothing
maybeAdd.ap(none).ap(five) // Nothing

Without ap, you'd need to do something like a nested match:

import { just, nothing } from 'true-myth/maybe';

const one = just(1);
const five = just(5);
const none = nothing();

one.match({
Just: n => five.match({
Just: o => just(n + o),
Nothing: () => nothing(),
}),
Nothing: ()  => nothing(),
}); // Just(6)

one.match({
Just: n => none.match({
Just: o => just(n + o),
Nothing: () => nothing(),
}),
Nothing: ()  => nothing(),
}); // Nothing

none.match({
Just: n => five.match({
Just: o => just(n + o),
Nothing: () => nothing(),
}),
Nothing: ()  => nothing(),
}); // Nothing

And this kind of thing comes up quite often once you're using Maybe to handle optionality throughout your application.

For another example, imagine you need to compare the equality of two ImmutableJS data structures, where a === comparison won't work. With ap, that's as simple as this:

import Maybe from 'true-myth/maybe';
import { is as immutableIs, Set } from 'immutable';

const is = (first: unknown) =>  (second: unknown) => 
immutableIs(first, second);

const x = Maybe.of(Set.of(1, 2, 3));
const y = Maybe.of(Set.of(2, 3, 4));

Maybe.of(is).ap(x).ap(y); // Just(false)

Without ap, we're back to that gnarly nested match:

import Maybe, { just, nothing } from 'true-myth/maybe';
import { is, Set } from 'immutable';

const x = Maybe.of(Set.of(1, 2, 3));
const y = Maybe.of(Set.of(2, 3, 4));

x.match({
Just: iX => y.match({
Just: iY => Maybe.just(is(iX, iY)),
Nothing: () => Maybe.nothing(),
})
Nothing: () => Maybe.nothing(),
}); // Just(false)

In summary: anywhere you have two Maybe instances and need to perform an operation that uses both of them, ap is your friend.

Two things to note, both regarding currying:

1. All functions passed to ap must be curried. That is, they must be of the form (for add) (a: number) => (b: number) => a + b, not the more usual (a: number, b: number) => a + b you see in JavaScript more generally.

(Unfortunately, these do not currently work with lodash or Ramda's curry helper functions. A future update to the type definitions may make that work, but the intermediate types produced by those helpers and the more general function types expected by this function do not currently align.)

2. You will need to call ap as many times as there are arguments to the function you're dealing with. So in the case of this add3 function, which has the "arity" (function argument count) of 3 (a and b), you'll need to call ap twice: once for a, and once for b. To see why, let's look at what the result in each phase is:

const add3 = (a: number) => (b: number) => (c: number) => a + b + c;

const maybeAdd = just(add); // Just((a: number) => (b: number) => (c: number) => a + b + c)
const maybeAdd1 = maybeAdd.ap(just(1)); // Just((b: number) => (c: number) => 1 + b + c)
const maybeAdd1And2 = maybeAdd1.ap(just(2)) // Just((c: number) => 1 + 2 + c)
const final = maybeAdd1.ap(just(3)); // Just(4)

So for toString, which just takes a single argument, you would only need to call ap once.

const toStr = (v: { toString(): string }) => v.toString();
just(toStr).ap(12); // Just("12")

One other scenario which doesn't come up quite as often but is conceivable is where you have something that may or may not actually construct a function for handling a specific Maybe scenario. In that case, you can wrap the possibly-present in ap and then wrap the values to apply to the function to in Maybe themselves.

Aside: ap is not named apply because of the overlap with JavaScript's existing apply function – and although strictly speaking, there isn't any direct overlap (Maybe.apply and Function.prototype.apply don't intersect at all) it's useful to have a different name to avoid implying that they're the same.

const a = Maybe.of(3);
const b = Maybe.of(3);
const c = Maybe.of(null);
const d = Maybe.nothing();

Maybe.equals(a, b); // true
Maybe.equals(a, c); // false
Maybe.equals(c, d); // true

This function behaves like Array.prototype.find, but returns Maybe<T> instead of T | undefined.

The basic form is:

import Maybe from 'true-myth/maybe';

let array = [1, 2, 3];
Maybe.find(v => v > 1, array); // Just(2)
Maybe.find(v => v < 1, array); // Nothing

The function is curried so you can use it in a functional chain. For example (leaving aside error handling on a bad response for simplicity), suppose the url https://arrays.example.com returned a JSON payload with the type Array<{ count: number, name: string }>, and we wanted to get the first of these where count was at least 100. We could write this:

import Maybe from 'true-myth/maybe';

type Item = { count: number; name: string };
type Response = Array<Item>;

// curried variant!
const findAtLeast100 = Maybe.find(({ count }: Item) => count > 100);

fetch('https://arrays.example.com')
.then(response => response.json() as Response)
.then(findAtLeast100)
.then(found => {
if (found.isJust) {
console.log(`The matching value is ${found.value.name}!`);
}
});

let empty = [];
Maybe.head(empty); // => Nothing

let full = [1, 2, 3];
Maybe.head(full); // => Just(1)

import type { transposeResult } from 'true-myth/toolbelt';

The check is type-safe: you won't even be able to compile if you try to look up a property that TypeScript knows doesn't exist on the object.

import { get, just, nothing } from 'true-myth/maybe';

type Person = { name?: string };

const me: Maybe<Person> = just({ name: 'Chris' });
console.log(get('name', me)); // Just('Chris')

const nobody = nothing<Person>();
console.log(get('name', nobody)); // Nothing

However, it also works correctly with dictionary types:

import { get, just } from 'true-myth/maybe';

type Dict<T> = { [key: string]: T };

const score: Maybe<Dict<number>> = just({
player1: 0,
player2: 1
});

console.log(get('player1', score)); // Just(0)
console.log(get('player2', score)); // Just(1)
console.log(get('player3', score)); // Nothing

The order of keys is so that it can be partially applied:

import { get, just } from 'true-myth/maybe';

type Person = { name?: string };

const lookupName = get('name');

const me: Person = { name: 'Chris' };
console.log(lookupName(me)); // Just('Chris')

const nobody: Person = {};
console.log(lookupName(nobody)); // Nothing

null and undefined are allowed by the type signature so that the function may throw on those rather than constructing a type like Maybe<undefined>.

let empty = [];
Maybe.last(empty); // => Nothing

let full = [1, 2, 3];
Maybe.last(full); // => Just(3)

map works a lot like Array.prototype.map: Maybe and Array are both containers* for other things. If you have no items in an array of numbers named foo and call foo.map(x => x + 1), you'll still just have an array with nothing in it. But if you have any items in the array ([2, 3]), and you call foo.map(x => x + 1) on it, you'll get a new array with each of those items inside the array "container" transformed ([3, 4]).

That's exactly what's happening with map. If the container is empty – the Nothing variant – you just get back an empty container. If the container has something in it – the Just variant – you get back a container with the item inside transformed.

(So... why not just use an array? The biggest reason is that an array can be any length. With a Maybe, we're capturing the idea of "something or nothing" rather than "0 to n" items. And this lets us implement a whole set of other interfaces, like those in this module.)

const length = (s: string) => s.length;

const justAString = Maybe.just('string');
const justTheStringLength = map(length, justAString);
console.log(justTheStringLength.toString()); // Just(6)

const notAString = Maybe.nothing<string>();
const notAStringLength = map(length, notAString);
console.log(notAStringLength.toString()); // "Nothing"

const length = (s: string) => s.length;

const justAString = Maybe.just('string');
const theStringLength = mapOr(0, length, justAString);
console.log(theStringLength); // 6

const notAString = Maybe.nothing<string>();
const notAStringLength = mapOr(0, length, notAString)
console.log(notAStringLength); // 0

const length = (s: string) => s.length;
const getDefault = () => 0;

const justAString = Maybe.just('string');
const theStringLength = mapOrElse(getDefault, length, justAString);
console.log(theStringLength); // 6

const notAString = Maybe.nothing<string>();
const notAStringLength = mapOrElse(getDefault, length, notAString)
console.log(notAStringLength); // 0

This is kind of like a poor man's version of pattern matching, which JavaScript currently lacks.

Instead of code like this:

import Maybe from 'true-myth/maybe';

const logValue = (mightBeANumber: Maybe<number>) => {
const valueToLog = Maybe.mightBeANumber.isJust
? mightBeANumber.value.toString()
: 'Nothing to log.';

console.log(valueToLog);
};

...we can write code like this:

import { match } from 'true-myth/maybe';

const logValue = (mightBeANumber: Maybe<number>) => {
const value = match(
{
Just: n => n.toString(),
Nothing: () => 'Nothing to log.',
},
mightBeANumber
);

console.log(value);
};

This is slightly longer to write, but clearer: the more complex the resulting expression, the hairer it is to understand the ternary. Thus, this is especially convenient for times when there is a complex result, e.g. when rendering part of a React component inline in JSX/TSX.

If you want to create an instance with a specific type, e.g. for use in a function which expects a Maybe<T> where the <T> is known but you have no value to give it, you can use a type parameter:

const notString = Maybe.nothing<string>();

To specify that the result should be interpreted as a specific type, you may invoke Maybe.of with an explicit type parameter:

import * as Maybe from 'true-myth/maybe';
const foo = Maybe.of<string>(null);

This is usually only important in two cases:

1. If you are intentionally constructing a Nothing from a known null or undefined value which is untyped.
2. If you are specifying that the type is more general than the value passed (since TypeScript can define types as literals).

This is useful when you want to make sure that something which takes a Maybe always ends up getting a Just variant, by supplying a default value for the case that you currently have a nothing.

import Maybe from 'true-utils/maybe';

const justA = Maybe.just("a");
const justB = Maybe.just("b");
const aNothing: Maybe<string> = nothing();

console.log(Maybe.or(justB, justA).toString());  // Just(A)
console.log(Maybe.or(aNothing, justA).toString());  // Just(A)
console.log(Maybe.or(justB, aNothing).toString());  // Just(B)
console.log(Maybe.or(aNothing, aNothing).toString());  // Nothing

Sometimes you need to perform an operation using other data in the environment to construct the fallback value. In these situations, you can pass a function (which may be a closure) as the elseFn to generate the fallback Maybe<T>.

Useful for transforming empty scenarios based on values in context.

The check is type-safe: you won't even be able to compile if you try to look up a property that TypeScript knows doesn't exist on the object.

type Person = { name?: string };

const me: Person = { name: 'Chris' };
console.log(Maybe.property('name', me)); // Just('Chris')

const nobody: Person = {};
console.log(Maybe.property('name', nobody)); // Nothing

However, it also works correctly with dictionary types:

type Dict<T> = { [key: string]: T };

const score: Dict<number> = {
player1: 0,
player2: 1
};

console.log(Maybe.property('player1', score)); // Just(0)
console.log(Maybe.property('player2', score)); // Just(1)
console.log(Maybe.property('player3', score)); // Nothing

The order of keys is so that it can be partially applied:

type Person = { name?: string };

const lookupName = Maybe.property('name');

const me: Person = { name: 'Chris' };
console.log(lookupName(me)); // Just('Chris')

const nobody: Person = {};
console.log(lookupName(nobody)); // Nothing

Useful for serialization. JSON.stringify() uses it.

import type { toOkOrElseErr } from 'true-myth/toolbelt';

import type { toOkOrErr } from 'true-myth/toolbelt';

A Just instance will be Just(<representation of the value>), where the representation of the value is simply the value's own toString representation. For example:

• Given an array of type Array<Maybe<A> | Maybe<B>>, the resulting type is Maybe<Array<A | B>>.
• Given a tuple of type [Maybe<A>, Maybe<B>], the resulting type is Maybe<[A, B]>.

If any of the items in the array or tuple are Nothing, the whole result is Nothing. If all items in the array or tuple are Just, the whole result is Just.

Given an array with a mix of Maybe types in it, both allJust and mixed here will have the type Maybe<Array<string | number>>, but will be Just and Nothing respectively.

import Maybe from 'true-myth/maybe';

let valid = [Maybe.just(2), Maybe.just('three')];
let allJust = Maybe.arrayTranspose(valid); // => Just([2, 'three']);

let invalid = [Maybe.just(2), Maybe.nothing<string>()];
let mixed = Maybe.arrayTranspose(invalid); // => Nothing

When working with a tuple type, the structure of the tuple is preserved. Here, for example, result has the type Maybe<[string, number]> and will be Nothing:

import Maybe from 'true-myth/maybe';

type Tuple = [Maybe<string>, Maybe<number>];

let invalid: Tuple = [Maybe.just('wat'), Maybe.nothing()];
let result = Maybe.arrayTranspose(invalid);  // => Nothing