Optionals Library

Support for Guava like Optionals in Node.js

Install

Description

Examples

There are plenty of examples using the Guava's Java API and it should be straight forward to follow these examples. Also you can look at the tests found in the ./spec folder. They include an example of every call possible in the library. That being said I have included some basic use cases below.

Using Optional.of()

Using Optional.or()

Using Optional.absent()

Using Optional.fromNullable()

Missing API or Bugs

Please reach out to me (Cory Parrish) if you would like a new Optional type added or if you think you have found a bug.

NPM Scripts

1. npm run test - Run linter and unit tests.
2. npm run ut - Use Maddox to Run Unit Tests.
3. npm run perf - Use Maddox to Performance metrics.
4. npm run uap - Use Maddox to Unit Tests and Performance metrics.
5. npm run lint - Run linter.
6. npm run docs - Rebuild public API Docs.

Releases

• 3.0.0
  • Now uses errr interface for preconditions.
  • Redesign of code.
  • Now uses maddox for unit testing.
  • Moves to Node 5 paradigms.

API

Optional

Optional entry point interface.

Kind: global class

• Optional
  • .of(item) ⇒ Present
  • .absent() ⇒ Absent
  • .fromUndefinedable(item) ⇒ Absent | Present
  • .fromNullable(item) ⇒ Absent | Present

Optional.of(item) ⇒ Present

Get a Present instance with the given item that may or may not be defined.

Kind: static method of Optional
Returns: Present - - Instance of the Present class.

| Param | Type | Description | | --- | --- | --- | | item | Object | A value that may or may not be defined. |

Optional.absent() ⇒ Absent

Get the Absent static instance.

Kind: static method of Optional
Returns: Absent - - Absent static instance.

Optional.fromUndefinedable(item) ⇒ Absent | Present

Synonym for fromNullable.

Kind: static method of Optional

| Param | Type | Description | | --- | --- | --- | | item | Object | A value that may or may not be defined. |

Optional.fromNullable(item) ⇒ Absent | Present

Returns the Absent static instance if the given value is not defined otherwise returns a Present instance.

Kind: static method of Optional

| Param | Type | Description | | --- | --- | --- | | item | Object | A value that may or may not be defined. |

Present

Present Class represents an Optional that wraps a value that may or may not be defined.

Kind: global class

• Present
  • new Present(item)
  • .get() ⇒ Object
  • .or() ⇒ Object
  • .orUndefined() ⇒ Object | undefined
  • .orNull() ⇒ Object | undefined
  • .isPresent() ⇒ Boolean
  • .transform(func) ⇒ Object | Absent

new Present(item)

Constructor for the Present class;

| Param | Type | | --- | --- | | item | Object |

present.get() ⇒ Object

Get the wrapped item if it exists.

Kind: instance method of Present
Returns: Object - - If the wrapped item is present, it will be returned.
Throws:

• Errr - If the wrapped item is not present, the function will throw an Errr.

present.or() ⇒ Object

Get the wrapped item or the second choice.

Kind: instance method of Present
Returns: Object - - If the wrapped item is present, it will be returned. If the wrapped item is not present and the second choice is present, then the second choice will be returned.
Throws:

• Errr - If the wrapped item and second choice is not present, the function will throw an Errr.

present.orUndefined() ⇒ Object | undefined

Returns the wrapped item or undefined.

Kind: instance method of Present
Returns: Object | undefined - - If the wrapped item exists, it will be returned, else this function will return undefined.

present.orNull() ⇒ Object | undefined

Returns the wrapped item or null.

Kind: instance method of Present
Returns: Object | undefined - - If the wrapped item exists, it will be returned, else this function will return null.

present.isPresent() ⇒ Boolean

Describes if the wrapped item is present.

Kind: instance method of Present
Returns: Boolean - - If the wrapped item exists, this function will return true, else false.

present.transform(func) ⇒ Object | Absent

Transform the wrapped item using the given function.

Kind: instance method of Present
Returns: Object | Absent - - Returns transformed wrapped item it is present. Returns the Absent static instance if the wrapped item is not present.

| Param | Type | Description | | --- | --- | --- | | func | function | The function that will be used to transform the wrapped item. |

Absent

Absent Class represents an Optional that wraps an undefined or null value.

Kind: global class

• Absent
  • .get()
  • .or(secondChoice) ⇒ Object
  • .orUndefined() ⇒ undefined
  • .orNull() ⇒ null
  • .isPresent() ⇒ undefined
  • .transform() ⇒ undefined

Absent.get()

Always throws an Errr because the the value is Absent.

Kind: static method of Absent
Throws:

• Errr

Absent.or(secondChoice) ⇒ Object

If secondChoice is defined, then it will be returned. If secondChoice is undefined or null, then the function will throw.

Kind: static method of Absent
Returns: Object - - The secondChoice passed into the 'or' function.
Throws:

• Errr - Throw when secondChoice is undefined or null.

| Param | | --- | | secondChoice |

Absent.orUndefined() ⇒ undefined

Always returns undefined because the Absent object has no value.

Kind: static method of Absent

Absent.orNull() ⇒ null

Always returns null because the Absent object has no value.

Kind: static method of Absent

Absent.isPresent() ⇒ undefined

Always returns false because the Absent object represents a non present Optional.

Kind: static method of Absent

Absent.transform() ⇒ undefined

Always returns the Absent static instance because the Absent object has no value to transform.

Kind: static method of Absent