Promise Object

A promise is a JavaScript object that represents the eventual result of an asynchronous process. After the promise object is created, it serves as a placeholder for the future success or failure of the asynchronous process. While the promise object is waiting, the remaining segments of the script can execute. With promises, you can write asynchronous code that is intuitive and efficient.

A promise holds one of the following values:

• fulfilled – The operation is successful.

• rejected – The operation failed.

• pending – The operation is still in progress and has not yet been fulfilled or rejected.

When it is first created, a promise holds the value pending. After the associated process is complete, the value changes to fulfilled for a successful completion or to rejected for an unsuccessful completion. A success or failure callback function attached to the promise is called when the process is complete. Note that a promise can only succeed or fail one time. When the value of the promise updates to fulfilled or rejected, it cannot change.

SuiteScript 2.x provides promise APIs for selected modules as listed in SuiteScript 2.x Promise APIs. In SuiteScript 2.x, all client scripts support the use of promises. Starting with NetSuite 2021.1, a subset of server scripts also support the use of promises. Custom promises can also be created for client scripts. For an example of creaing a custom promise, see Custom Promises.

When you code your SuiteScript scripts to be asynchronous, you should also consider following best practices. A few best practices are included in Best Practices for Asynchronous Programming with SuiteScript.

For more information about JavaScript promises, see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise.

SuiteScript 2.x Promise APIs

The available promise APIs are named so that they correspond with their synchronous counterparts. Promise APIs have names that are suffixed with .promise. For example, the search.create(options) API has a promise version named search.create.promise(options). The following promise APIs are supported for 2.x client scripts and 2.1 server scripts:

For supported modules members and additional API information, see SuiteScript 2.x Modules.

Examples

The following is a basic example of how to use the search.create.promise in a client script for the pageInit entry point.

          /**
* @NApiVersion 2.x
*/

define(['N/search'], function(search)
{
    function doSomething() 
    {
        search.create.promise({
            type: 'salesorder'
        })
        .then(function(result) {
            log.debug("Completed: " + result); 
            //do something after completion
        })
        .catch(function(reason) {
            log.debug("Failed: " + reason) 
            //do something on failure
        });
    }
    return 
    {
        pageInit: doSomething
    }
}); 

        

This example demonstrates how to chain promises created with SuiteScript promise APIs.

          /**
* @NApiVersion 2.x
*/
define(['N/search'], function(search) 
{
    function doSomething() 
    {
        var filter = search.createFilter({
            name: 'mainline', 
            operator: search.Operator.IS, 
            values:['T']
        });

        search.create.promise({
            type: 'salesorder', 
            filters:[filter]
        })
        .then(function(searchObj) {
            return searchObj.run().each.promise(
                function(result, index){
                //do something
            })
        })
        .then(function(result) {
            log.debug("Completed: " + result) 
            //do something after completion
        })
        .catch(function(reason) {
            log.debug("Failed: " + reason) 
            //do something on failure
        });
    })
    return 
    {
        pageInit: doSomething
    }

}); 

        

Custom Promises

The following example shows a custom promise. Note that custom promises do not use the SuiteScript 2.x Promise APIs.

          /**
* @NApiVersion 2.x
*/

define(function(){
    function doSomething(addresses){
        var promise = new Promise(function(resolve, reject){
            var url = 'https://your.favorite.maps/api/directions?start=' + addresses.start + '&end=' + addresses.end,
                isAsync = true,
                xhr = new XMLHttpRequest();

                xhr.addEventListener('load', function (event) {
                    if (xhr.readyState === 4) {
                        if (xhr.status === 200) {
                            resolve(xhr.responseText );
                        } 
                        else {
                            reject( xhr.statusText );
                        }
                    }
                });

                xhr.addEventListener('error', function (event) {
                    reject( xhr.statusText );
                });

                xhr.open('GET', url, isAsync);
                xhr.send();
            });

        return promise;
    }

    return {
        lookupDirections: doSomething
    };
}); 

        

General Notices