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

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

import { and, ok, err, toString } from 'true-myth/result';

const okA = ok('A');
const okB = ok('B');
const anErr = err({ so: 'bad' });

console.log(toString(and(okB, okA)));  // Ok(B)
console.log(toString(and(okB, anErr)));  // Err([object Object])
console.log(toString(and(anErr, okA)));  // Err([object Object])
console.log(toString(and(anErr, anErr)));  // Err([object Object])

This differs from map in that thenFn returns another Result. You can use andThen to combine two functions which both create a Result 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 Result.andThen will not unwrap nested Results.

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

import { ok, err, andThen, toString } from 'true-myth/result';

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

const anOk = ok('just a string');
const lengthAsResult = andThen(toLengthAsResult, anOk);
console.log(toString(lengthAsResult));  // Ok(13)

const anErr = err(['srsly', 'whatever']);
const notLengthAsResult = andThen(toLengthAsResult, anErr);
console.log(toString(notLengthAsResult));  // Err(srsly,whatever)

import { ap, ok, err } from 'true-myth/result';

const one = ok<number, string>(1);
const five = ok<number, string>(5);
const whoops = err<number, string>('oh no');

const add = (a: number) => (b: number) => a + b;
const resultAdd = ok<typeof add, string>(add);

resultAdd.ap(one).ap(five); // Ok(6)
resultAdd.ap(one).ap(whoops); // Err('oh no')
resultAdd.ap(whoops).ap(five) // Err('oh no')

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

import { ok, err } from 'true-myth/result';

const one = ok<number, string>(1);
const five = ok<number, string>(5);
const whoops = err<number, string>('oh no');

one.match({
Ok: n => five.match({
Ok: o => ok<number, string>(n + o),
Err: e => err<number, string>(e),
}),
Err: e  => err<number, string>(e),
}); // Ok(6)

one.match({
Ok: n => whoops.match({
Ok: o => ok<number, string>(n + o),
Err: e => err<number, string>(e),
}),
Err: e  => err<number, string>(e),
}); // Err('oh no')

whoops.match({
Ok: n => five.match({
Ok: o => ok(n + o),
Err: e => err(e),
}),
Err: e  => err(e),
}); // Err('oh no')

And this kind of thing comes up quite often once you're using Result to handle errors 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 { ok } from 'true-myth/result';
import { is as immutableIs, Set } from 'immutable';

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

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

ok(is).ap(x).ap(y); // Ok(false)

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

import Result, { ok, err } from 'true-myth/result';
import { is, Set } from 'immutable';

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

x.match({
Ok: iX => y.match({
Ok: iY => Result.of(is(iX, iY)),
Err: (e) => ok(false),
})
Err: (e) => ok(false),
}); // Ok(false)

In summary: anywhere you have two Result 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 resultAdd = ok(add); // Ok((a: number) => (b: number) => (c: number) => a + b + c)
const resultAdd1 = resultAdd.ap(ok(1)); // Ok((b: number) => (c: number) => 1 + b + c)
const resultAdd1And2 = resultAdd1.ap(ok(2)) // Ok((c: number) => 1 + 2 + c)
const final = maybeAdd1.ap(ok(3)); // Ok(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();
ok(toStr).ap(12); // Ok("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 Result scenario. In that case, you can wrap the possibly-present in ap and then wrap the values to apply to the function to in Result themselves.

Because Result often requires you to type out the full type parameterization on a regular basis, it's convenient to use TypeScript's typeof operator to write out the type of a curried function. For example, if you had a function that simply merged three strings, you might write it like this:

import Result from 'true-myth/result';
import { curry } from 'lodash';

const merge3Strs = (a: string, b: string, c: string) => string;
const curriedMerge = curry(merge3Strs);

const fn = Result.ok<typeof curriedMerge, string>(curriedMerge);

The alternative is writing out the full signature long-form:

const fn = Result.ok<(a: string) => (b: string) => (c: string) => string, string>(curriedMerge);

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 (Result.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 = Result.of(3)
const b = Result.of(3)
const c = Result.of(null)
const d = Result.nothing()

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

If you need to create an instance with a specific type (as you do whenever you are not constructing immediately for a function return or as an argument to a function), you can use a type parameter:

const notString = Result.err<number, string>('something went wrong');

Note: passing nothing, or passing null or undefined explicitly, will produce a Result<T, Unit>, rather than producing the nonsensical and in practice quite annoying Result<null, string> etc. See Unit for more.

const normalResult = Result.err<number, string>('oh no');
const explicitUnit = Result.err<number, Unit>(Unit);
const implicitUnit = Result.err<number, Unit>();

In the context of an immediate function return, or an arrow function with a single expression value, you do not have to specify the types, so this can be quite convenient.

type SomeData = {
//...
};

const isValid = (data: SomeData): boolean => {
// true or false...
}

const arrowValidate = (data: SomeData): Result<number, Unit> =>
isValid(data) ? Result.ok(42) : Result.err();

function fnValidate(data: someData): Result<number, Unit> {
return isValid(data) ? Result.ok(42) : Result.err();
}

If you need to create an instance with a specific type (as you do whenever you are not constructing immediately for a function return or as an argument to a function), you can use a type parameter:

const notString = Result.err<number, string>('something went wrong');

Note: passing nothing, or passing null or undefined explicitly, will produce a Result<T, Unit>, rather than producing the nonsensical and in practice quite annoying Result<null, string> etc. See Unit for more.

const normalResult = Result.err<number, string>('oh no');
const explicitUnit = Result.err<number, Unit>(Unit);
const implicitUnit = Result.err<number, Unit>();

In the context of an immediate function return, or an arrow function with a single expression value, you do not have to specify the types, so this can be quite convenient.

type SomeData = {
//...
};

const isValid = (data: SomeData): boolean => {
// true or false...
}

const arrowValidate = (data: SomeData): Result<number, Unit> =>
isValid(data) ? Result.ok(42) : Result.err();

function fnValidate(data: someData): Result<number, Unit> {
return isValid(data) ? Result.ok(42) : Result.err();
}

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

map works a lot like Array.prototype.map, but with one important difference. Both Result and Array are containers for other kinds of items, but where Array.prototype.map has 0 to n items, a Result always has exactly one item, which is either a success or an error instance.

Where Array.prototype.map will apply the mapping function to every item in the array (if there are any), Result.map will only apply the mapping function to the (single) element if an Ok instance, if there is one.

If you have no items in an array of numbers named foo and call foo.map(x => x + 1), you'll still some 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]).

With this map, the Err variant is treated by the map function kind of the same way as the empty array case: it's just ignored, and you get back a new Result that is still just the same Err instance. But if you have an Ok variant, the map function is applied to it, and you get back a new Result with the value transformed, and still wrapped in an Ok.

import { ok, err, map, toString } from 'true-myth/result';
const double = n => n * 2;

const anOk = ok(12);
const mappedOk = map(double, anOk);
console.log(toString(mappedOk)); // Ok(24)

const anErr = err("nothing here!");
const mappedErr = map(double, anErr);
console.log(toString(mappedOk)); // Err(nothing here!)

import { ok, err, mapErr, toString } from 'true-myth/result';

const reason = (err: { code: number, reason: string }) => err.reason;

const anOk = ok(12);
const mappedOk = mapErr(reason, anOk);
console.log(toString(mappedOk));  // Ok(12)

const anErr = err({ code: 101, reason: 'bad file' });
const mappedErr = mapErr(reason, anErr);
console.log(toString(mappedErr));  // Err(bad file)

import { ok, err, mapOr } from 'true-myth/result';

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

const anOkString = ok('a string');
const theStringLength = mapOr(0, anOkString);
console.log(theStringLength);  // 8

const anErr = err('uh oh');
const anErrMapped = mapOr(0, anErr);
console.log(anErrMapped);  // 0

Like mapOr but using a function to transform the error into a usable value instead of simply using a default value.

import { ok, err, mapOrElse } from 'true-myth/result';

const summarize = (s: string) => `The response was: '${s}'`;
const getReason = (err: { code: number, reason: string }) => err.reason;

const okResponse = ok("Things are grand here.");
const mappedOkAndUnwrapped = mapOrElse(getReason, summarize, okResponse);
console.log(mappedOkAndUnwrapped);  // The response was: 'Things are grand here.'

const errResponse = err({ code: 500, reason: 'Nothing at this endpoint!' });
const mappedErrAndUnwrapped = mapOrElse(getReason, summarize, errResponse);
console.log(mappedErrAndUnwrapped);  // Nothing at this endpoint!

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

Instead of code like this:

import Result, { isOk, match } from 'true-myth/result';

const logValue = (mightBeANumber: Result<number, string>) => {
console.log(
mightBeANumber.isOk
? mightBeANumber.value.toString()
: `There was an error: ${unsafelyGetErr(mightBeANumber)}`
);
};

...we can write code like this:

import Result, { match } from 'true-myth/result';

const logValue = (mightBeANumber: Result<number, string>) => {
const value = match(
{
Ok: n => n.toString(),
Err: e => `There was an error: ${e}`,
},
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 need to create an instance with a specific type (as you do whenever you are not constructing immediately for a function return or as an argument to a function), you can use a type parameter:

const yayNumber = Result.ok<number, string>(12);

Note: passing nothing, or passing null or undefined explicitly, will produce a Result<Unit, E>, rather than producing the nonsensical and in practice quite annoying Result<null, string> etc. See Unit for more.

const normalResult = Result.ok<number, string>(42);
const explicitUnit = Result.ok<Unit, string>(Unit);
const implicitUnit = Result.ok<Unit, string>();

In the context of an immediate function return, or an arrow function with a single expression value, you do not have to specify the types, so this can be quite convenient.

type SomeData = {
//...
};

const isValid = (data: SomeData): boolean => {
// true or false...
}

const arrowValidate = (data: SomeData): Result<Unit, string> =>
isValid(data) ? Result.ok() : Result.err('something was wrong!');

function fnValidate(data: someData): Result<Unit, string> {
return isValid(data) ? Result.ok() : Result.err('something was wrong');
}

If you need to create an instance with a specific type (as you do whenever you are not constructing immediately for a function return or as an argument to a function), you can use a type parameter:

const yayNumber = Result.ok<number, string>(12);

Note: passing nothing, or passing null or undefined explicitly, will produce a Result<Unit, E>, rather than producing the nonsensical and in practice quite annoying Result<null, string> etc. See Unit for more.

const normalResult = Result.ok<number, string>(42);
const explicitUnit = Result.ok<Unit, string>(Unit);
const implicitUnit = Result.ok<Unit, string>();

In the context of an immediate function return, or an arrow function with a single expression value, you do not have to specify the types, so this can be quite convenient.

type SomeData = {
//...
};

const isValid = (data: SomeData): boolean => {
// true or false...
}

const arrowValidate = (data: SomeData): Result<Unit, string> =>
isValid(data) ? Result.ok() : Result.err('something was wrong!');

function fnValidate(data: someData): Result<Unit, string> {
return isValid(data) ? Result.ok() : Result.err('something was wrong');
}

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

import { ok, err, Result, or } from 'true-utils/result';

const okA = ok<string, string>('a');
const okB = ok<string, string>('b');
const anErr = err<string, string>(':wat:');
const anotherErr = err<string, string>(':headdesk:');

console.log(or(okB, okA).toString());  // Ok(A)
console.log(or(anErr, okA).toString());  // Ok(A)
console.log(or(okB, anErr).toString());  // Ok(B)
console.log(or(anotherErr, anErr).toString());  // Err(:headdesk:)

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 Result<T>. It can then transform the data in the Err to something usable as an Ok, or generate a new Err instance as appropriate.

Useful for transforming failures to usable data.

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

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

An Ok instance will be Ok(<representation of the value>), and an Err instance will be Err(<representation of the error>), where the representation of the value or error is simply the value or error's own toString representation. For example:

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

const aSuccessfulOperation = () => 2 + 2;

const anOkResult = Result.tryOr('Oh noes!!1', () => {
aSuccessfulOperation()
}); // => Ok(4)

const thisOperationThrows = () => throw new Error('Bummer');

const anErrResult = Result.tryOr('Oh noes!!1', () => {
thisOperationThrows();
}); // => Err('Oh noes!!1')

const aSuccessfulOperation = () => 2 + 2;

const anOkResult = Result.tryOrElse(
(e) => e,
aSuccessfulOperation
); // => Ok(4)

const thisOperationThrows = () => throw 'Bummer'

const anErrResult = Result.tryOrElse((e) => e, () => {
thisOperationThrows();
}); // => Err('Bummer')