README.md

opt-in

Optional: Utility class for differentiating null, undefined and present values.

Example

Basic Usage

var something = new Optional(5);
something.isPresent(); // returns true
something.get(); // returns 5

var nothing = new Optional(null);
nothing.isPresent(); // returns false
nothing.get(); // throws TypeError

Safe Defaults

let user = getUser();
let userName = Optional.of(user.name).orElse("Anonymous User");
console.log(`Hello ${userName}`);

Simple Control Flow

function handleRequest(request, response) {
  Optional.of(request.headers["Authorization"])
    .ifEmpty(() => {
      response.statusCode = 401;
      response.end("You need an Authorization header to access this."); })
    .map(getUserForAuthToken)
    .ifPresent((user) => {
      response.statusCode = 200;
      response.end("Thanks friend!"); })
    .ifEmpty(() => {
      response.statusCode(500);
      response.end("We couldn't find a user behind that token."); });
}

API

• Optional
  • new Optional([value])
  • instance
    • .get() ⇒ T
    • .orElse([value]) ⇒ T
    • .isPresent() ⇒ boolean
    • .ifPresent(fn) ⇒ Optional.<T>
    • .isEmpty() ⇒ boolean
    • .ifEmpty(fn) ⇒ Optional.<T>
    • .map(fn) ⇒ Optional.<U> | Optional.<T>
    • .flatMap(fn) ⇒ Optional.<U> | Optional.<T>
    • .filter(fn) ⇒ Optional.<T>
    • .equals(other) ⇒ boolean
    • .strictEquals(other) ⇒ boolean
  • static
    • .of([value]) ⇒ Optional.<T>
    • .empty() ⇒ Optional.<null>
    • .isOptional(optional) ⇒ boolean
    • .isPresent(value) ⇒ boolean
    • .isEmpty(value) ⇒ boolean
  • inner
    • ~ifPresentCallback ⇒ undefined
    • ~EmptyCallback ⇒ undefined
    • ~MapCallback ⇒ U
    • ~FilterCallback ⇒ boolean

new Optional([value])

Create an Optional.

Param	Type	Description
[value]	T	value to box Optional with

optional.get() ⇒ T

Returns present value or throws when empty.

Kind: instance method of Optional Throws:

• TypeError

optional.orElse([value]) ⇒ T

Returns present value or passed value when empty.

Kind: instance method of Optional

Param	Type	Description
[value]	T	value to return if Optional is empty

optional.isPresent() ⇒ boolean

Returns whether the Optional has a value present.

Kind: instance method of Optional

optional.ifPresent(fn) ⇒ Optional.<T>

Calls supplied function when one is present.

Kind: instance method of Optional

Param	Type
fn	ifPresentCallback

optional.isEmpty() ⇒ boolean

Returns whether the Optional is empty.

Kind: instance method of Optional

optional.ifEmpty(fn) ⇒ Optional.<T>

Calls supplied function if Optional is empty.

Kind: instance method of Optional

Param	Type
fn	EmptyCallback

optional.map(fn) ⇒ Optional.<U> | Optional.<T>

Calls supplied function when value is present and returns an Optional of the function's result. Otherwise returns an empty Optional.

Kind: instance method of Optional Template: U

Param	Type
fn	MapCallback

optional.flatMap(fn) ⇒ Optional.<U> | Optional.<T>

Calls supplied function when value is present and returns an Optional of the function's result. Unlike map, if supplied function returns an Optional, then it is not boxed. Otherwise returns an empty Optional.

Kind: instance method of Optional Template: U

Param	Type
fn	MapCallback

optional.filter(fn) ⇒ Optional.<T>

Returns an Optional of present value when passed function returns a truthy value. Otherwise returns an empty Optional.

Kind: instance method of Optional

Param	Type
fn	FilterCallback

optional.equals(other) ⇒ boolean

Returns result of == comparison with unboxed value and (unboxed if Optional) argument.

Kind: instance method of Optional

Param	Type	Description
other	*	value to compare Optional's unboxed value with

optional.strictEquals(other) ⇒ boolean

Returns result of === comparison with unboxed value and (unboxed if Optional) argument.

Kind: instance method of Optional

Param	Type	Description
other	*	value to compare Optional's unboxed value with

Optional.of([value]) ⇒ Optional.<T>

Convenience initializer; returns an Optional of value.

Kind: static method of Optional Template: T

Param	Type
[value]	T

Optional.empty() ⇒ Optional.<null>

Convenience initializer; returns an empty Optional.

Kind: static method of Optional

Optional.isOptional(optional) ⇒ boolean

Returns whether the argument is an instance of Optional.

Kind: static method of Optional

Param	Type	Description
optional	*	variable to test

Optional.isPresent(value) ⇒ boolean

Returns whether value is present (not null and not undefined).

This is simply typeof value !== "undefined" && value !== null.

Kind: static method of Optional

Param	Type
value	*

Optional.isEmpty(value) ⇒ boolean

Returns whether value is empty (null or undefined).

This is simply typeof value !== "undefined" && value !== null.

Kind: static method of Optional

Param	Type
value	*

Optional~ifPresentCallback ⇒ undefined

Kind: inner typedef of Optional

Param	Type	Description
value	T	present value

Optional~EmptyCallback ⇒ undefined

Kind: inner typedef of Optional

Optional~MapCallback ⇒ U

Kind: inner typedef of Optional Template: U

Param	Type
value	T

Optional~FilterCallback ⇒ boolean

Kind: inner typedef of Optional

Type	Description
T	the present value