SuiteScript 2.x Promise APIs for Asynchronous Programming

TL;DR

SuiteScript 2.x introduces Promise APIs, allowing developers to handle asynchronous operations intuitively and efficiently. Promises facilitate managing the success or failure of processes while the script continues to run other segments, ultimately improving performance and readability.

What Are Promises?

A promise is a JavaScript object representing the eventual success or failure of an asynchronous operation. When created, a promise has one of three states:

• fulfilled: The operation completed successfully.
• rejected: The operation failed.
• pending: The operation is still in progress.

Once a promise is resolved or rejected, it cannot change again. Callbacks (.then(), .catch()) associated with the promise are executed upon completion, allowing for clean and efficient asynchronous code.

SuiteScript and Promises

SuiteScript 2.x supports promises across various modules. Starting with NetSuite 2021.1, certain server scripts also incorporate promise functionality. This enables both client and server scripts to manage asynchronous processes effectively.

Supported Modules and APIs

Below is a selection of some modules in SuiteScript 2.x that support Promise APIs:

Best Practices for Asynchronous Programming

When utilizing promises in SuiteScript, consider the following best practices:

• Always include a .catch handler for promise rejections.
• Chain promises rather than nesting them for better readability and performance.
• Keep promise chains concise to save on memory and CPU usage.
• Utilize promise.finally for code that must execute whether the promise is fulfilled or rejected.
• For parallel asynchronous operations, use promise.all.
• Avoid mixing synchronous and asynchronous APIs within the same function.

Example: Basic Usage of Promises

The following example illustrates the use of the search.create.promise API in a client script:

1/**
2* @NApiVersion 2.x
3*/
4 
5define(['N/search'], function(search) {
6    function doSomething() {
7        search.create.promise({
8            type: 'salesorder'
9        })
10        .then(function(result) {
11            log.debug("Completed: " + result);
12            // Perform actions after completion
13        })
14        .catch(function(reason) {
15            log.debug("Failed: " + reason);
16            // Handle failure
17        });
18    }
19    return {
20        pageInit: doSomething
21    };
22});

Custom Promises

Custom promises can be created in SuiteScript, allowing for additional flexibility beyond the provided Promise APIs:

1/**
2* @NApiVersion 2.x
3*/
4 
5define(function() {
6    function doSomething(addresses) {
7        var promise = new Promise(function(resolve, reject) {
8            var url = 'https://your.favorite.maps/api/directions?start=' + addresses.start + '&end=' + addresses.end,
9                xhr = new XMLHttpRequest();
10 
11            xhr.addEventListener('load', function(event) {
12                if (xhr.status === 200) {
13                    resolve(xhr.responseText);
14                } else {
15                    reject(xhr.statusText);
16                }
17            });
18 
19            xhr.open('GET', url, true);
20            xhr.send();
21        });
22        return promise;
23    }
24 
25    return {
26        lookupDirections: doSomething
27    };
28});

Key Takeaways

• SuiteScript 2.x enhances asynchronous programming with Promise APIs.
• Promises help manage asynchronous operations, improving script readability.
• Best practices for using promises include avoiding nesting and using .catch for rejections.