EXPERIMENT: Creating A Promise-Inspired Future Constructor In ColdFusion 2018

var promise = new Promise(
	function( resolve, reject ) {

		resolve( "I am the winner!" );

	}
);

promise.then(
	function( value ) {

		console.log( "Resolution:", value );

	}
);

<cfscript>

	future = futureNew(
		function( resolve, reject ) {

			resolve( "I am the winner!" );

		}
	);

	future.then(
		function( value ) {

			writeLog( "Resolution: #value#" );

		}
	);

</cfscript>

<cfscript>

	/**
	* I invoke the given callback and return a Future. The callback is provided with two
	* methods: resolve() and reject(). Like a JavaScript Promise, resolve will result in
	* a successful outcome; reject will result in an error outcome. Errors thrown inside
	* of the callback will result in an automatic rejection.
	*
	* @callback I am the callback being used to initiate a Future.
	* @output false
	*/
	public any function futureNew(
		required function callback,
		numeric fulfillmentTimeout = ( 5 * 1000 )
		) {

		// CAUTION: Basically, anything that we do to a Future (like adding a Timeout or
		// calling the .then() or .error() methods) turns the Future into a BLOCKING,
		// SYNCHRONOUS call. As such, we need to double-nest our runAsync() call in order
		// to make sure that we don't accidentally block the top-level thread while
		// manipulating the inner thread.
		var asyncWrapper = runAsync(
			function() {

				// By calling runAsync() without a callback, we will receive an EMPTY
				// FUTURE. This is a Future that we can control. But, unfortunately, it
				// does not have a .then() method. Which means that we're going to have
				// to convert this EMPTY Future into a "normal" future before we return
				// it to the calling context.
				var bridge = runAsync();

				// I am the resolve function which will fulfill the Empty Future with a
				// successful outcome.
				var resolve = function( any value = "" ) {

					bridge.complete({
						value: value
					});

				};

				// I am the reject function which will fulfill the Empty Future with
				// an error outcome. This method expects either a STRING, a STRUCT, or an
				// actual Error object. If it's a STRING, it will be used as an Error
				// Message. And, if it's a STRUCT, it will be used as the internal
				// throw() attributes. Error objects will just be rethrown.
				var reject = function( required any error ) {

					bridge.complete({
						error: error
					});

				}

				var syncWrapper = runAsync(
					function() {

						callback( resolve, reject );

					}
				)
				.error( reject ) // Any uncaught error should become a rejection.
				.then(
					function() {

						// If the internal bridge EmptyFuture has not yet been fulfilled,
						// then let's sleep the Thread context for a small period of time
						// and check again.
						// --
						// NOTE: This won't block forever - the .then() timeout will
						// eventually throw an error and let the parent context proceed.
						while ( ! bridge.isDone() ) {

							sleep( 5 );

						}

						var resolution = bridge.get();

						// Handle the error outcomes.
						if ( resolution.keyExists( "error" ) ) {

							// NOTE: A this time, ColdFusion completely obfuscates the
							// errors that are created inside of a Future. As such, we're
							// going to write them to the log to make debugging half-way
							// possible for the developer.
							writeLog(
								type = "error",
								text = "FutureNew Error: #serializeJson( resolution.error )#"
							);

							// We're expecting the reject() function to be called with
							// either a string, a struct, or a native Error object. In
							// either case, we're going to try to convert the error value
							// into an actual ColdFusion Error object.
							if ( isSimpleValue( resolution.error ) ) {

								throw(
									type = "FutureNew.CustomException",
									message = resolution.error,
									detail = "The resolve() function was invoked with a simple value."
								);

							} else if ( isStruct( resolution.error ) ) {

								throw( attributeCollection = resolution.error );

							} else {

								// If it's not simple and not a struct, assume it is a
								// native error. In that case, just rethrow it.
								throw( resolution.error );

							}

						// If we made it this far, we are dealing with a successful
						// outcome. Now, it's possible that the value contains a Future.
						// In that case, we want to block and UNWRAP the Future before
						// passing it through.
						} else if ( isGettableFuture( resolution.value ) ) {

							return( resolution.value.get() );

						// Otherwise, let's just pass-through the resolution value.
						} else {

							return( resolution.value );

						}

					},
					fulfillmentTimeout
				);

				return( syncWrapper.get() );

			}
		);

		return( asyncWrapper );

	}


	/**
	* I determine if the given value is a Future object with a .get() method.
	*
	* @value I am the value being tested.
	* @output false
	*/
	public boolean function isGettableFuture( required any value ) {

		return(
			isInstanceOf( value, "coldfusion.runtime.async.Future" ) ||
			isInstanceOf( value, "coldfusion.runtime.async.EmptyFuture" )
		);

	}

</cfscript>

<cfscript>

	// Include our FutureNew() function.
	include "./utilities.cfm";

	// FUTURE ISSUE: Because our FutureNew() method is encapsulating the creation of a
	// FUTURE object, it means that Future errors CANNOT BE HANDLED by the .error()
	// method. As such, we have to use a traditional Try/Catch to catch the error.
	// Hopefully, in the future (no pun intended), encapsulated Future errors will be
	// able to be dealt with via the .error() method.
	try {

		future = futureNew(
			function( resolve, reject ) {

				// NOTE: Using nested runAsync() methods to demonstrate that it's the
				// resolve() and reject() methods that control the futureNew() outcome.
				runAsync(
					function() {

						runAsync(
							function() {

								resolve( "So much win!" );

								// You can resolve with a Future - the Future will be
								// "unwrapped" implicitly by the FutureNew().
								resolve(
									runAsync(
										function() {

											return( "Inner zen!" );

										}
									)
								);

								// NOTE: The first call to resolve() or reject() will
								// cause the fulfillment. As such, having this here won't
								// do anything; unless we comment-out the resolve() lines
								// above.
								reject( "Such rejection!" );

								// If called with a Struct, the struct data will be
								// turned into a native ColdFusion error object.
								reject({
									type = "Boom",
									message = "This is crazy pants."
								});

								// NOTE: Normally, a throw() this DEEP in the nested
								// runAsync() calls wouldn't be noticed. It would be akin
								// to an "unhandled promise rejection". But, since we're
								// using a .error( reject ) below, then we can notice it.
								// --
								// Of course, this won't matter if the resolve() or
								// reject() methods have already been called.
								throw( type = "Kablamo!" );

								// If you're dealing with an error, the best approach is
								// to pass the error to reject(). That way, it will be
								// logged and you have a CHANCE of debugging.
								try {
									throw( "BoomGoesTheDynamite" );
								} catch ( any error ) {
									reject( error );
								}

							}
						)
						// When we have nested runAsync() calls, there's no way for the
						// FutureNew() method to know about unhandled errors. Unless, we
						// tie the reject() method into the unhandled error explicitly.
						// --
						// CAUTION: At this time, ColdFusion will basically HIDE ALL OF
						// THE ERROR DETAILS coming out of a Future. As such, you should
						// try to call the reject() function directly (either passing it
						// an Error object or a pseudo-error Struct). Then, at least it
						// will be logged to the ColdFusion logs.
						.error( reject );

					}
				)

			}
		).then(
			function( required string value ) {

				return( "Resolution: #value#" );

			}
		);

		writeOutput( future.get() );

	// Catch any errors triggered by the FutureNew().
	// --
	// NOTE: Hopefully, in the future, this won't be necessary!!!!!!!!
	} catch ( any error ) {

		writeDump( error );

	}

</cfscript>