Package Exports

ts.data.either

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (ts.data.either) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

Either

The Either data type encapsulates the idea of a computation that may fail.

An Either value can either be Right some value or Left some error.

type Either<T> = Right<T> | Left;

Install

npm install ts.data.either --save

Example

import { Either, tryCatch, andThen, withDefault } from './either';

interface UserJson {
  id: number;
  nickname: string;
  email: string;
}

// throws if file does not exists
const readFile = (filename: string): string => {
  const fileSystem: { [key: string]: string } = {
    'something.json': `
    [
      {
        "id": 1,
        "nickname": "rick",
        "email": "rick@c137.com"
      },
      {
        "id": 2,
        "nickname": "morty",
        "email": "morty@c137.com"
      }
    ]`
  };
  const fileContents = fileSystem[filename];
  if (fileContents === undefined) {
    throw new Error(`${filename} does not exists.`);
  }
  return fileContents;
};

// Wraps the read file operation in an Either
const readFileContent = (filename: string): Either<string> =>
  tryCatch(
    () => readFile(filename),
    err => err
  );

// Wraps the json parsing operation in an Either
const parseJson = (json: string): Either<UserJson[]> =>
  tryCatch(
    () => JSON.parse(json),
    err => new Error(`There was an error parsing this Json.`)
  );

// The pipeline function just makes function invocations flow
const pipeline = (initialValue: any, ...fns: Function[]) =>
  fns.reduce((acc, fn) => fn(acc), initialValue);

const usersFull: UserJson[] = pipeline(
  'something.json',
  (fname: string) => readFileContent(fname),
  (json: Either<string>) => andThen(parseJson, json),
  (users: Either<UserJson[]>) => withDefault(users, [])
); // returns the Array of users because all intermediate operations have succeeded

const usersEmpty: UserJson[] = pipeline(
  'nothing.json',
  (fname: string) => readFileContent(fname),
  (json: Either<string>) => andThen(parseJson, json),
  (users: Either<UserJson[]>) => withDefault(users, [])
); // returns an empty Array because the readFile operations failed

Api

(Inspired by elm-lang)

right

right<T>(value: T): Either<T>

Wraps a value in an instance of Right.

right(5); // Right<number>(5)

left

left<T>(error: Error): Either<T>

Creates an instance of Left.

left(new Error('Something bad happened')); // Left<unknown>(Error('Something bad happened'))
left<number>(new Error('The calculation failed')); // Left<number>(Error('The calculation failed'))

isRight

isRight<T>(value: Either<T>): boolean

Returns true if a value is an instance of Right.

isRight(left(new Error('Wrong!'))); // false

isLeft

isLeft<T>(value: Either<T>): boolean

Returns true if a value is not an instance of Right.

isLeft(right(5)); // false
isLeft(left('Hi!')); // true
isLeft(null); // true

withDefault

withDefault<T>(value: Either<T>, defaultValue: T): T

If value is an instance of Right it returns its wrapped value, if it's an instance of Left it returns the defaultValue.

withDefault(right(5), 0); // 5
withDefault(left(new Error('Wrong!')), 0); // 0

caseOf

caseOf<A, B>(caseof: {Right: (v: A) => B; Left: (err: Error) => B;}, value: Either<A>): B

Run different computations depending on whether an Either is Right or Left and returns the result.

caseOf(
  {
    Left: err => `Error: ${err.message}`,
    Right: n => `Launch ${n} missiles`
  },
  right('5')
); // 'Launch 5 missiles'

map

map<A, B>(f: (a: A) => B, value: Either<A>): Either<B>

Transforms an Either value with a given function.

const add1 = (n: number) => n + 1;
map(add1, right(4)); // Right<number>(5)
map(add1, left(new Error('Something bad happened'))); // Left('Something bad happened')

tryCatch

tryCatch<A>(f: () => A, onError: (e: Error) => Error): Either<A>

Transforms a function (that might throw an exception) that produces A to a function that produces Either<A>.

tryCatch(
  () => JSON.parse(''),
  err => err
); // Left('Unexpected end of JSON input')

andThen

andThen<A, B>(f: (a: A) => Either<B>, value: Either<A>): Either<B>

Chains together computations that may fail.

const removeFirstElement = <T>(arr: T[]): T[] => {
  if (arr.length === 0) {
    throw new Error('Array is empty');
  }
  return arr.slice(1);
};

const safeRemoveFirst = <T>(arr: T[]): Either<T[]> => {
  try {
    return right(removeFirstElement(arr));
  } catch (error) {
    return left(error);
  }
};

// The pipeline function just makes function invocations flow
const pipeline = (initialValue: any, ...fns: Function[]) =>
  fns.reduce((acc, fn) => fn(acc), initialValue);

const result: string[] = pipeline(
  ['a', 'b', 'c'],
  safeRemoveFirst, // Right(['b', 'c'])
  (arr: Either<string[]>) => andThen(safeRemoveFirst, arr), // Right(['b'])
  (arr: Either<string[]>) => andThen(safeRemoveFirst, arr), // Right([])
  (arr: Either<string[]>) => andThen(safeRemoveFirst, arr), // Left(Error('Array is empty'))
  (arr: Either<string[]>) => andThen(safeRemoveFirst, arr), // Left(Error('Array is empty'))
  (arr: Either<string[]>) => withDefault(arr, [])
);

console.log(result); // []