FORGEBOX Enterprise 🚀 - Take your ColdFusion (CFML) Development to Modern Times! Learn More...


v1.0.1+13 Public

CB Optional

Welcome to the wonderful world of functional programming inspired by Java Optionals ( This module will make your life very happy 😍 and 🚀 accelerate your functional processes as you will never have to deal with null values ever again.

What is a cbOptional?

An cbOptional is a simple functional class that wraps a value which can exist or be null. Then you can use all the functions to interact/retrieve or do all kinds of operations on the value. Let's visit a simple example of retrieving an item from a cache, which can produce nulls:

// How many times have we had to do this? Very imperative.
var results = cache.get( "my-key" );
if( isNull( results ) ){
	// do something
} else{
	// use it.

As you can see above, the code is very imperative, retrieving the results from the cache and acting upon its existence. Now, let's use an optional:

return cache
	.get( "my-key" )
	.orElse( "default" );

	.get( "my-key" )
	.ifPresent( function( value ){
		// Do somethign with the value
	.orElseGet( function(){
		return // something else with the value


You will need to retrieve optionals using WireBox via it's injection DSL: @cbOptional. Or you can use a full new cbOptional.models.cbOptional() if not in ColdBox mode.

getInstance( "@cbOptional" );

Creating Optionals

There are many methods to create optionals:

  • init() - An empty optional
  • init( value ) - Seed an optional with a value
  • empty() - Return an empty optional
  • of( value ) - Return an optional of the passed NON null value
  • ofNullable( value ) - Return an optional of the passed existent or possible null value

Testing For Values

The following methods are for testing the existence of a value in the optional

  • isPresent() - true if the value is set
  • isEmpty() - false if the value is NOT set
  • isEqual( optional ) - Tests if the passed optional's value is the same as the optional value called. If both are empty, this is true


You can also do actions and return different values if needed

  • ifPresent( consumer ) - If the value is set, the consumer closure or lambda is called for you with a single argument, the value.
  • ifPresentOrElse( consumer, runnable ) - If the value is set, the consumer closure or labmda is called, else the runnable closure/lambda is called.
  • filter( predicate ) - If a value is present and the value matches the given predicate closure/lambda, the optional with that value is returned or an empty optional
  • map( mapper ) - If a value is present, it will be passed through the mapper function/closure and a new optional with the return value of the mapper will be returned.
  • get() - Retrieve the value or an exception if it doesn't exist.
  • orElse( other ) - Return the value if present, otherwise return other.
  • orElseRun( runnable ) - If the value is NOT present, then run the runnable closure or labmda.
  • orElseGet( supplier ) - Return the value if present, otherwise invoke supplier and return the result of that invocation.
  • or( supplier ), $or( supplier ) - If a value is present, returns an Optional describing the value, otherwise returns an Optional produced by the supplying function.
  • orElseThrow( type, message ) - If a value is present, returns the value, otherwise throws NoSuchElementException or your own type and message.

Utility functions

  • hashCode() - Returns the hash code value of the present value, if any, or 0 (zero) if no value is present.
  • toString() - Returns a non-empty string representation of this Optional suitable for debugging.

Copyright Since 2005 ColdBox Framework by Luis Majano and Ortus Solutions, Corp


Because of His grace, this project exists. If you don't like this, then don't read it, its not for you.

"Therefore being justified by faith, we have peace with God through our Lord Jesus Christ: By whom also we have access by faith into this grace wherein we stand, and rejoice in hope of the glory of God. And not only so, but we glory in tribulations also: knowing that tribulation worketh patience; And patience, experience; and experience, hope: And hope maketh not ashamed; because the love of God is shed abroad in our hearts by the Holy Ghost which is given unto us. ." Romans 5:5


"I am the way, and the truth, and the life; no one comes to the Father, but by me (JESUS)" Jn 14:1-12



  • Fix for orElseRun doing inverse evaluation


  • First iteration of this module

Here are all the versions for this package. Please note that you can leverage CommandBox package versioning to install any package you like. Please refer to our managing package version guide for more information.

Version Created Last Update Published By Stable Actions
1.1.0-snapshot May 31 2019 03:41 PM May 31 2019 03:41 PM
Version History
1.0.1+13 Jun 14 2019 03:45 PM Jun 14 2019 03:45 PM
1.0.1-snapshot Jun 14 2019 03:18 PM Jun 14 2019 03:18 PM
1.0.0+10 May 31 2019 04:07 PM May 31 2019 04:07 PM
1.0.0+7 May 31 2019 03:38 PM May 31 2019 03:38 PM
1.0.0-snapshot May 24 2019 08:38 AM May 31 2019 03:37 PM


No collaborators yet.
  • May 24 2019 08:38 AM
  • Jun 14 2019 03:45 PM
  • 368
  • 251
  • 1545