Results

Results is a tiny library bringing Discriminated Unions (aka Sum Types or Algebraic Types) to JavaScript, with match for better program flow control.

Results ships with full-featured Maybe (sometimes called an Option Type) and Result unions built-in, helping you safely deal with optional data and error handling.

The goal of Results is JavaScript with fewer bugs.

Install

$ npm install results

Quickstart

Result for error handling

import { Result, Ok, Err } from 'results';

function validateNumber(number) {
  if (isFinite(number)) {
    return Ok(number);
  } else {
    return Err(`expected a finite number but got '${number}' (a '${typeof number}')`);
  }
}

function computeSum(numbers) {
  if (!(numbers instanceOf Array)) {
    return Err(`expected an Array but got '${numbers}' (a '${typeof numbers}')`);
  }
  return Result.all(numbers.map(validateNumber))
    .andThen(nums => nums.reduce((a, b) => a + b));
}

// Since computeSum returns a Result (eiter an Err() or an Ok()), we can match
// for it and handle all possible cases:
Result.match(computeSum([1, 2, 3, 4, -5]), {
  Ok: sum => console.log(`The sum is: ${sum}`),
  Err: err => console.error(`Something went wrong: ${err}`)
});

// Result is a synchronous compliment to Promise, and plays nicely with it:
fetch('http://example.com/numbers')
  .then(resp => resp.json())
  .then(nums => computeSum(nums).toPromise())
  .then(sum => console.log(`The sum is: ${sum}`))
  .catch(err => console.error(`Something went wrong: ${err}`));

Maybe for nullable references

import { Maybe, Some, None } from 'results';

// Take a tree of Maybe({val: any, left: Maybe, right: Maybe}) and flatten it
// into an array of values:
function flattenDepthFirst(root) {
  return Maybe.match(root, {
    None: () => [],
    Some: node => [node.val]
                    .concat(flattenDepthFirst(node.left))
                    .concat(flattenDepthFirst(node.right))
  });
}

Maybe for default values and possibly-undefined return values

import { Maybe, Some, None } from 'results';

function printGreeting(name) {
  // get the name, or set a default if name is None()
  const nameToPrint = Maybe.match(name, {
    Some: n => n,
    None: () => 'friend'
  });
  console.log(`Hello, oh wonderful ${nameToPrint}!`);
}

// The Maybe union has helpful methods, like .unwrapOr for getting the value
// with a default:
function printGreeting(name) {
  const nameToPrint = name.unwrapOr('friend');
  console.log(`Hello, oh wonderful ${nameToPrint}!`)
}

// For functions whose result may not be defined, using Maybe encourages the
// caller to handle all cases
function get(obj, key) {
  if (obj.hasOwnProperty(key)) {
    return Some(obj[key]);
  } else {
    return None();
  }
}

Union as a powerful Enum

import { Union } from 'results';

const HTTPVerbs = Union({
  Options: {},  // the {} values are just placeholders, only the keys are used
  Head: {},
  Get: {},
  Post: {},
  Put: {},
  Delete: {}
}, {
  // the optional second object parameter to Union creates prototype methods:
  isIdempotent() {
    return HTTPVerbs.match(this, {
      Post: () => false,
      _: () => true  // "_" is reserved as a catch-all in match
    });
  }
});

let myVerb = HTTPVerbs.Get();
console.log(`Get ${myVerb.isIdempotent() ? 'is' : 'is not'} idempotent.`);
// => "Get is idempotent"
myVerb = HTTPVerbs.Post();
console.log(`Post ${myVerb.isIdempotent() ? 'is' : 'is not'} idempotent.`);
// => "Post is not idempotent"

HTTPVerbs.match(myVerb, {
  Delete: () => console.warn('some data was deleted!'),
  _: () => null
});

While there is nothing react-specific in Results, it does enable some nice patterns:

import React from 'react';
import { Union } from 'results';

const AsyncState = Union({
  Pending: {},
  Success: {},
  Failed: {}
});

class Spinner extends React.Component {
  static propTypes = {
    reqState: React.PropTypes.instanceOf(AsyncState.OptionClass)
  }
  render() {
    return AsyncState.match(this.props.reqState, {
      Pending: loaded => (
        <div className="spinner overlay spinning">
          <div className="spinner-animation">
            Loading {loaded}%...
          </div>
        </div>
      ),
      Failed: errMsg => (
        <div className="spinner overlay failed">
          <div className="spinner-err-message">
            <h3>Failed to load :( </h3>
            <p>{errMsg}</p>
          </div>
        </div>
      ),
      Success: <div style={{display: 'none'}}></div>
    });
  }
}

API

Union(options[, proto[, static_[, factory]]])

Creates a discriminated union with members specified in the options object.

Returns a union object.

• options An object defining the members of the set. One member is added for each key of options, and the values are ignored. Almost any name can be used for the members except for two reserved names:

  • toString, which is automatically added for nicer debugging, and
  • OptionClass, which is used to attach the constructor function for member instances, for typechecking purposes. Union() will throw if either of those names are used as members in options.

  Maybe.None() is an example of a member added via options.

• proto will be used to set the protoype of member instances. toString will automatically be added to the prototype by default, but if you define it in proto it will override the built-in implementations.

  Result.Ok(1).toPromise() is an example of a method attached through proto.

• static_ like proto but for the object returned by Union(): functions defined here can inspect the union, like accessing this.OptionClass. By default, toString is added for you, but defining it in static_ will override the default implementation. Union() will throw if a key in static_ already exists in options.

  Result.all() is an example of a function attached through static_.

• factory is not stable and should not be considered part of the public API :) It is used internally by Maybe and Result, check the source if you want to get down and dirty.

Union.is(first, second)

Deeply checks two union option members. This passes if:

• first and second are strictly equal (===), or
• They are instances of the same UnionOptionClass, and
  • They are the same member of the UnionOptionClass, and
  • Each matching payload parameter satisfies:
    • A recursive check of equality as defined by Union.is
• or they both implement .valueOf which passes strict equality, or
• they both implement .equals and first.equals(second)

These criteria and the implementation are stolen borrowed from Immutable, and in fact results's equality checks are compatible with Immutable's. Nesting Immutable collections in OptionClassInstances, and nesting OptionClassInstance in immutable collections are both supported.

This compatibility is totally decoupled from immutablejs -- results has no dependency on immutable whatsoever.

union object

Created by Union(), this is an object with a key for each member of the union, plus anything attached via static_, which include OptionClass and toString by default. It is not safe to iterate the keys of a union object.

Each member name's key maps to a factory to create a member instance, from a constructor called OptionClass (whose reference is also attached to the union object via they key "OptionClass").

match(option, paths) static method on union object

Automatically attached to every union object, .match is a better way to control program flow depending on which member of Union you are dealing with.

• option the OptionClass instance to match against, like Some('hi') or Err(new Error(':(')). If option is not an instance of the union's OptionClass, match will throw.

• paths an object, mapping member names to callback functions. The object must either exhaustively cover all members in the Union with callbacks, or map zero or more members to callbacks and provide a catch-all callback for the name '_'. If the coverage is not exhaustive, or if unrecognized names are included as keys, .match will throw.

.match will synchronously call the matching callback and return its result, passing all arguments given to the Union Option as arguments to the callback.

import { Union } from 'results';
const Stoplight = Union({  // Union(), creating a `union` object called StopLight.
  Red: {},
  Amber: {},
  Green: {}
});
Stoplight.match(Stoplight.Green(), {
  Red: () => console.error('STOP!!!'),
  Amber: () => console.warn('stop if you can'),
  Green: () => console.info('ok, continue')
});

options static property on union object

After creating a union object, the .options property references an object containing keys for each union option specified. It's not usually that useful unless you want to introspect the union and see what options it has -- powerful, but usually not necessary!

OptionClass() constructor

A function for creating OptionClass instances. You should not call this constructor directly -- it's exposed just for instanceof checks.

In the Stoplight example above, the following is ok:

assert(Stoplight.Green() instanceof Stoplight.OptionClass)

OptionClassFactory(...payloads) functions

Attached to union objects by keys named after the union's members. These functions create the "values" used in result. Maybe.Some(), Maybe.None(), Result.Ok(), and Result.Err() are all OptionClass factories. In the Stoplight example above, Stoplight.Green is an OptionClassFactory.

• payloads a payload of any type can be passed as the only param. It will be stored on the OptionClass instance, and is accessible via .match. Proto methods may also extract the value for you, like .unwrap() on Maybe.

OptionClassInstance objects

The values that are usually passed around when using Results. They have three properties that you should consider an implementation detail, never access directly. Custom proto methods may access these properties if they wish. The property names are:

• .options A reference to the object used to create the union with Union(). You can inspect its keys to find the members of this instance's union.
• .name The member name of this OptionClass instance. Maybe.None().name === 'None'.
• .payload The payload provided to OptionClassFactory. Stoplight.Red(1).payload is 1.

OptionClassInstance.equals(other)

Deep equality testing with another instance of a union option. See Union.is above. As with Union.is, this method is fully compatible with ImmutableJS.

Maybe -- [Union { Some, None }]

An optional type.

Maybe.Some(payload)

Also exported as Some from Results (import { Some } from 'results';).

• payload A single parameter of any type. If it is an instance of Maybe.OptionClass, it will just be returned.

Maybe.None()

Also exported as None from Results (import { None } from 'results';). Accepts no parameters

Maybe.match(thing, paths)

defers to match (see above), but will only pass a single payload parameter to a callback for Some (no parameters are passed to a None callback).

Maybe.all(maybes)

Like Promise.all: takes an array of Some()s and None()s, and returns a Some([unwrapped maybes]) if they are all Some(), or None() if any are None(). Values in maybes that are not instances of Maybe.OptionClass are wrapped in Some().

• maybes an array of Some()s and None()s or any other value.

Maybe.undefined(value)

Returns None() if value is undefined, otherwise wraps it as Some(value).

Maybe.null(value)

Like Maybe.undefined(value), but returns None() when value is null instead of when it is undefined.

Maybe.nan(value)

Like Maybe.undefined and Maybe.null but returns None() when value is NaN.

Prototype methods on Maybe (available on any instance of Some or None)

isSome() and isNone()

What you would hopefully expect :)

import { Some, None } from 'results';
assert(Some(1).isSome() && !Some(1).isNone());
assert(!None().isSome() && None().isNone());

unwrap()

Get the payload of a Some(), or throw if it's None().

expect(err)

Like unwrap(), but throws a custom error if it is None().

• err The error to throw if it is None()

import { Some, None } from 'results';
const n = Some(1).unwrap();  // n === 1
const m = None().unwrap();  // throws an Error instance
const o = Some(1).expect('err')  // o === 1
const p = None().expect('err')  // throws 'err'

unwrapOr(def)

Like unwrap(), but returns def instead of throwing for None()

• def A default value to use in case it's None()

unwrapOrElse(fn)

Like unwrapOr, but calls fn() to get a default value for None()

• fn A callback accepting no parameters, returning a value for None()

import { None } from 'results';
const x = None().unwrapOr('z');  // x === 'z';
const y = None().unwrapOrElse(() => new Date());  // y === the current date.

okOr(err)

Get a Result from a Maybe

• err an error payload for Err() if it's None()

okOrElse(errFn)

• errFn a callback to get a payload for Err() if it's None()

import { Some, None } from 'results';
assert(Some(1).okOr(2).isOk() && None().okOr(2).isErr());
assert(None().okOrElse(() => 3).unwrapErr() === 3);

promiseOr(err) and promiseOrElse(errFn)

Like okOr and okOrElse, but returning a resolved or rejected promise.

import { Some, None } from 'results';
// the following will log "Some"
Some(1).promiseOr(2).then(d => console.log('Some'), e => console.error('None!'));
None().promiseOrElse(() => 1).catch(err => console.log(err));  // logs 1

and(other) and or(other)

• other Some() or None(), or any value of any type which will be wrapped in Some().

Analogous to && and ||:

import { Some, None } from 'results';
Some(1).and(Some(2));  // Some(2)
Some(1).and(None());  // None()
None().and(Some(2));  // None()
Some(1).or(Some(2)).or(None());  // Some(1)
None().or(Some(1)).or(Some(2)); // Some(1);

andThen(fn)

Like and, but call a function instead of providing a hard-coded value. If fn returns a raw value instead of a Some or a None, it will be wrapped in Some().

• fn If called on Some, fn is called with the payload as a param.

orElse(fn)

Like andThen but for Errs.

• fn If called on Err, fn is called with the Error payload as a param.

Since andThen's callback is only executed if it's Some() and orElse if it's None, these two methods can be used like .then and .catch from Promise to chain data-processing tasks.

filter(fn)

Test a condition against the payload of a Some(payload). If fn returns something false-y, None is returned. Otherwise, the same Some(payload) is returned.

• fn If called on Some, fn is called with the payload as a param.

import { Maybe } from 'results';

const isEven = x => x % 2 === 0;

Maybe.Some(42).filter(isEven);  // Some(42)
Maybe.Some(41).filter(isEven);  // None()

Result -- [Union { Ok, Err }]

An error-handling type.

Result.Ok(payload)

Also exported as Ok from Results (import { Ok } from 'results';).

• payload A single parameter of any type. If it is an instance of Result.OptionClass, it will simply be returned.

Result.Err(err)

Also exported as Err from Results (import { Err } from 'results';).

• err A single parameter of any type, but consider making it an instance of Error to follow Promise conventions.

Static methods on Result

Result.match(thing, paths)

defers to match (see above), but will only pass a single payload parameter to a callback for Ok or Err.

Result.all(results)

Like Promise.all: takes an array of Ok()s and Err()s, and returns a Ok([unwrapped oks]) if they are all Ok(), or the first Err() if any are Err(). Values in results that are not instances of Result.OptionClass are wrapped in Ok().

• results an array of Ok()s and Err()s or any other value.

Result.try(fnMaybeThrows)

Return a Result.Ok() of the result of calling fnMaybeThrows(), or catch any error it throws and return it wrapped in Result.Err() instead.

Prototype methods on Result (available on any instance of Ok or Err)

isOk() and isErr()

What you would hopefully expect :)

import { Ok, Err } from 'results';
assert(Ok(1).isOk() && !Ok(1).isErr());
assert(!Err(2).isOk() && Err(2).isErr());

expect(err)

Returns the payload from an Ok(payload), or throws err.

unwrap()

Get the payload of a Ok(), or throw payload if it's Err(payload).

import { Ok, Err } from 'results';
const n = Ok(1).unwrap();  // n === 1
const m = Err(2).unwrap();  // throws an Error instance

unwrapOr(def)

Like unwrap(), but returns def instead of throwing for Err()

• def A default value to use in case it's Err()

unwrapOrElse(fn)

Like unwrapOr, but calls fn() to get a default value for Err()

• fn A callback accepting the err payload as a parameter, returning a value for Err()

import { Err } from 'results';
const x = Err(1).unwrapOr('z');  // x === 'z';
const y = Err(2).unwrapOrElse(e => e * 2);  // y === 4.

ok() and err()

Get a Maybe from a Result

import { Ok, Err } from 'results';
assert(Ok(1).ok().isSome() && Err(2).err().isSome());
assert(Err(2).ok().isNone());

promise() and promiseErr()

Like ok() and err(), but returning a resolved or rejected promise.

import { Ok, Err } from 'results';
// the following will log "Ok"
Ok(1).promise().then(d => console.log('Ok'), e => console.error('Err!'));
Err(2).promise().catch(n => console.log(n));  // logs 2
Err(2).promiseErr().then(n => console.log(n));  // logs 2

and(other) and or(other)

• other Ok() or Err(), or any value of any type which will be wrapped in Ok().

Analogous to && and ||:

import { Ok, Err } from 'results';
Ok(1).and(Ok(2));  // Ok(2)
Ok(1).and(Err(8));  // Err(8)
Err(8).and(Ok(2));  // Err(8)
Ok(1).or(Ok(2)).or(Err(8));  // Ok(1)
Err(8).or(Ok(1)).or(Ok(2)); // Ok(1);

andThen(fn)

Like and, but call a function instead of providing a hard-coded value. If fn returns a raw value instead of a Ok or a Err, it will be wrapped in Ok().

• fn If called on Ok, fn is called with the payload as a param.

orElse(fn)

Like andThen but for Errs.

• fn If called on Err, fn is called with the Error payload as a param.

Since andThen's callback is only executed if it's Ok() and orElse if it's Err, these two methods can be used like .then and .catch from Promise to chain data-processing tasks.

Credits

Results is written and maintained by uniphil, with help, support, and opinions from mystor.

The APIs for Maybe, and Result are heavily influenced by rust's Option and Result.

Changes

See changelog.md