maybe-optional

TypeScript library implementing Maybe type and Optional class for handling of null or undefined values

Installation

Using npm:

npm install maybe-optional

Using yarn:

yarn add maybe-optional

Usage

Maybe

Something and Nothing

Both undefined and null are considered Nothing. Anything else is considered Something.

import { Something, Nothing, isSomething, isNothing } from 'maybe-optional';

const aNull: Nothing = null;
isSomething(aNull);
// => false
isNothing(aNull);
// => true

const anUndefined: Nothing = undefined;
isSomething(anUndefined);
// => false
isNothing(anUndefined);
// => true

const aNumber: Something = 1;
isSomething(aNumber);
// => true
isNothing(aNumber);
// => false

const aString: Something = 'hello';
isSomething(aString);
// => true
isNothing(aString);
// => false

const anObject: Something = {};
isSomething(anObject);
// => true
isNothing(anObject);
// => false

Maybe

The Maybe type handles situations where it is possible for a value to be null or undefined.

import { Maybe, isSomething, isNothing } from 'maybe-optional';

const maybeSomething: Maybe = 1;
isSomething(maybeSomething);
// => true
isNothing(maybeSomething);
// => false

const maybeNotSomething: Maybe = null;
isSomething(maybeNotSomething);
// => false
isNothing(maybeNotSomething);
// => true

const maybeNumber: Maybe<number> = 1;
isSomething(maybeNumber);
// => true
isNothing(maybeNumber);
// => false

const maybeString: Maybe<string> = 'hello';
isSomething(maybeString);
// => true
isNothing(maybeString);
// => false

ifSomething

Pass a value to a function if the value is Something.

import { Maybe, ifSomething } from 'maybe-optional';

const doSomething = (str: string) => console.log(str);

const maybe: Maybe<string> = 'hello';
ifSomething(maybe, doSomething);
// 'hello'

const maybeNot: Maybe<string> = null;
ifSomething(maybeNot, doSomething);
//

orElse

Unwrap a Maybe by returning its value, if it is Something, or else a default value.

import { Maybe, orElse } from 'maybe-optional';

// Maybe with a real value
const maybe1: Maybe<string> = 'a value';
const value1: string = orElse(maybe1, 'a default value');
// => 'a value'

// Maybe with an undefined value
const maybe2: Maybe<string> = undefined;
const value2: string = orElse(maybe2, 'a default value');
// => 'a default value'

orElseGet

Unwrap a Maybe by returning its value, if it is Something, or else returning the result of a function.

import { Maybe, orElseGet } from 'maybe-optional';

const get = () => {
    // do something (e.g. an api call)
    return 'goodbye';
}

const maybe: Maybe<string> = 'hello';
const result1: string = orElseGet(maybe, get);
// 'hello'

const maybeNot: Maybe<string> = null;
const result2: string = orElseGet(maybeNot, get);
// 'goodbye'

orElseThrow

Unwrap a Maybe value if it is Something or else throw an error.

import { Maybe, orElseThrow } from 'maybe-optional';

const maybe: Maybe<string> = 'hello';
const result1: string = orElseThrow(maybe);
// 'hello'

const maybeNot: Maybe<string> = null;
const result2: string = orElseThrow<string>(maybeNot);
// throws MaybeNothingError

filter

Run a Maybe through a conditional predicate. If the condition is true, return the same value still wrapped as a Maybe. If the condition is false, return null wrapped as a Maybe.

import { Maybe, filter } from 'maybe-optional';

const maybe: Maybe<number> = 1;
const result1: Maybe<number> = filter(maybe, val => val > 0)
// => 1
const result2: Maybe<number> = filter(maybe, val => val === 0)
// => null

map

Apply a function to the Maybe value if it is Something. Otherwise, return null.

import { Maybe, map } from 'maybe-optional';

const maybe: Maybe<number> = 1;
const result1: Maybe<number> = map(val => val + 1, maybe)
// => 2

const maybeNot: Maybe<number> = null;
const result2: Maybe<number> = map<number, number>(val => val + 1, maybeNot)
// => null

Optional

Optional provides class-based functionality for handling situations where it is possible for a value to be null or undefined.

import { Maybe, Optional } from 'maybe-optional';

// create empty optional
const empty = Optional.empty();
empty.isEmpty();
// => true
empty.isPresent();
// => false

// create optional from value
const opt1 = Optional.of(1);
opt1.isEmpty();
// => false
opt1.isPresent();
// => true

// create optional from a Maybe
const maybe: Maybe<number> = null;
const opt2 = Optional.ofMaybe(maybe);
opt2.isEmpty();
// => true
opt2.isPresent();
// => false

Optional.ifPresent

Pass the wrapped value to a function if the value is Something.

import { Optional } from 'maybe-optional';

const doSomething = (str: string) => console.log(str);

const opt1 = Optional.ofMaybe<string>('hello');
opt1.ifPresent(doSomething);
// 'hello'

const opt2 = Optional.ofMaybe<string>(null);
opt2.ifPresent(doSomething);
//

Optional.orElse

Unwrap an Optional by returning its value, if it is Something, or else a default value.

import { Optional } from 'maybe-optional';

// with Something
const opt1 = Optional.ofMaybe<string>('hello');
const value1: string = opt1.orElse('a default value');
// => 'a value'

// with Nothing
const opt2 = Optional.ofMaybe<string>(undefined);
const value2: string = opt2.orElse('a default value');
// => 'a default value'

Optional.orElseGet

Unwrap an Optional by returning its value, if it is Something, or else returning the result of a function.

import { Optional } from 'maybe-optional';

const get = () => {
    // do something (e.g. an api call)
    return 'goodbye';
}

// with Something
const opt1 = Optional.ofMaybe<string>('hello');
const value1: string = opt1.orElseGet(get);
// 'hello'

// with Nothing
const opt2 = Optional.ofMaybe<string>(undefined);
const value2: string = opt2.orElseGet(get);
// 'goodbye'

Optional.orElseThrow

Unwrap an Optional value if it is Something or else throw an error.

import { Optional } from 'maybe-optional';

// with Something
const opt1 = Optional.ofMaybe<string>('hello');
const value1: string = opt1.orElseThrow();
// 'hello'

// with Nothing
const opt2 = Optional.ofMaybe<string>(undefined);
const value2: string = opt2.orElseThrow();
// throws OptionalEmptyError

Optional.filter

Run an Optional's wrapped value through a conditional predicate. If the condition is true, return the same value wrapped in a new Optional. If the condition is false, return an empty Optional.

import { Optional } from 'maybe-optional';

const opt = Optional.of(1);
const opt1 = opt.filter(val => val > 0)
// => Optional { maybe: 1 }
const opt2 = opt.filter(val => val === 0)
// => Optional { maybe: null }

Optional.map

Apply a function to the wrapped Optional value if it is Something and return wrapped in new Optional. Otherwise, return an empty Optional.

import { Optional } from 'maybe-optional';

const opt1 = Optional.of(1);
const opt2 = opt1.map(val => val + 1)
// => Optional { maybe: 2 }

const opt3 = Optional.ofMaybe<number>(null);
const opt4 = opt3.map(val => val + 1)
// => Optional { maybe: null }

Chaining Optionals

import { Optional } from 'maybe-optional';

const opt = Optional.of(1)
    .map(val => val + 1)
    .filter(val => val > 0);
// => Optional { maybe: 2 }