Optionals Library

Support for Guava like Optionals in Node.js

Content in this document was copied from the Optionals documentation (https://code.google.com/p/guava-libraries/wiki/UsingAndAvoidingNullExplained).

FYI - I am in no way associated with Google.

Install

npm install guava-optional

NOTE: In javascript we have the concept of undefined and null. For the case of this library they are both treated as the same thing, some 'falsy' value. Therefore, wherever you see 'null' or 'undefined', you can read 'null or undefined'.

Description

Careless use of null (and undefined in javascript) can cause a staggering variety of bugs. Studying the Google code base, (they) found that something like 95% of collections weren't supposed to have any null (or undefined) values in them, and having those fail fast rather than silently accept null (or undefined) would have been helpful to developers. Additionally, null (or undefined) is unpleasantly ambiguous. That said, there are times when null (or undefined) is the right and correct thing to use. null (or undefined) is cheap, in terms of memory and speed, and it's unavoidable in object arrays. But in application code, as opposed to libraries, it is a major source of confusion, difficult and weird bugs, and unpleasant ambiguities -- e.g. when Map.get returns null (or undefined), it can mean the value was absent, or the value was present and null (or undefined). Most critically, null (or undefined) gives no indication what a null (or undefined) value means. For these reasons, many of Guava's utilities are designed to fail fast in the presence of null (or undefined) rather than allow nulls to be used, so long as there is a null-friendly (or undefined-friendly) workaround available. Additionally, Guava provides a number of facilities both to make using null (or undefined) easier, when you must, and to help you avoid using null (and undefined).

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()

    
        var Optional = require("optional");
        var optional = Optional.of("SomeVal");
        optional.isPresent() //returns true
        optional.or("SomeValueThatIsDefined"); //returns "SomeVal" because the Optional instance contains an existing value.
        optional.or("SomeValueThatIsDefined"); //returns "SomeVal" because the Optional instance contains an existing value.
   

Using Optional.or()

    
        var Optional = require("optional");
        var optional = Optional.of("SomeVal");
        optional.isPresent() //returns true
        optional.or(); //throws error.  You should use orNull() instead of or(null)
        optional.orNull(); //returns "SomeVal" because the Optional instance contains an existing value.
   

Using Optional.absent()

    
        var Optional = require("optional");
        var absent1 = Optional.absent();
        var absent2 = Optional.absent();

        Optional.absent() === Optional.absent(); //returns true.  Absent is a singleton and will always equal itself.
        absent1 === Optional.absent(); //returns true.  Absent is a singleton and will always equal itself.
        absent2 === Optional.absent(); //returns true.  Absent is a singleton and will always equal itself.
        absent1 === absent2; //returns true.  Absent is a singleton and will always equal itself.

        absent1.isPresent(); //returns false because it is not present;
        absent2.isPresent(); //returns false because it is not present;
   

Using Optional.fromNullable()

    
        var Optional = require("optional");
        var absent = Optional.fromNullable();
        var present = Optional.fromNullable({ value: "SomeDefinedValue" });

        absent === Optional.absent(); //returns true.  Absent is a singleton and will always equal itself.
        absent.isPresent();  //returns false;
        present.isPresent(); //returns true;
   

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.

Present

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

Absent

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

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