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 |