guava-optional
Advanced tools
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.
npm install guava-optionalNOTE: 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'.
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).
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.
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.
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.
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;
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;
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.
Optional entry point interface.
Present Class represents an Optional that wraps a value that may or may not be defined.
Absent Class represents an Optional that wraps an undefined or null value.
Optional entry point interface.
Kind: global class
PresentGet 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. |
AbsentGet the Absent static instance.
Kind: static method of Optional
Returns: Absent - - Absent static instance.
Absent | PresentSynonym for fromNullable.
Kind: static method of Optional
| Param | Type | Description |
|---|---|---|
| item | Object | A value that may or may not be defined. |
Absent | PresentReturns 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 Class represents an Optional that wraps a value that may or may not be defined.
Kind: global class
ObjectObjectObject | undefinedObject | undefinedBooleanObject | AbsentConstructor for the Present class;
| Param | Type |
|---|---|
| item | Object |
ObjectGet 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.ObjectGet 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.Object | undefinedReturns 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.
Object | undefinedReturns 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.
BooleanDescribes 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.
Object | AbsentTransform 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 Class represents an Optional that wraps an undefined or null value.
Kind: global class
ObjectundefinednullundefinedundefinedAlways throws an Errr because the the value is Absent.
Kind: static method of Absent
Throws:
ErrrObjectIf 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 |
undefinedAlways returns undefined because the Absent object has no value.
Kind: static method of Absent
nullAlways returns null because the Absent object has no value.
Kind: static method of Absent
undefinedAlways returns false because the Absent object represents a non present Optional.
Kind: static method of Absent
undefinedAlways returns the Absent static instance because the Absent object has no value to transform.
Kind: static method of Absent
FAQs
Support for Guava like optionals in Node.js.
The npm package guava-optional receives a total of 15 weekly downloads. As such, guava-optional popularity was classified as not popular.
We found that guava-optional demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Axios compromise traced to social engineering, showing how attacks on maintainers can bypass controls and expose the broader software supply chain.
Security News
Node.js has paused its bug bounty program after funding ended, removing payouts for vulnerability reports but keeping its security process unchanged.
Security News
The Axios compromise shows how time-dependent dependency resolution makes exposure harder to detect and contain.