Node.js SDK updates: promises and more

The new 4.2.1 version of the DocuSign Node.js SDK is now available on the NPM package site.

It’s packed with fresh code and new features. In this post,  I will discuss the new promises feature.

Promises

Not familiar with promises? They’re the best software pattern for working with asynchronous methods. Promises for JavaScript and Node.js have been around for several years now via third-party libraries. The JavaScript native promises (known as Promises/A+) specification was published in 2014.

Promises enable you to avoid the “callback hell” that infests so many Node.js programs where nested callbacks quickly become confusing and error prone.

These days, native JavaScript promises are widely supported both in browsers and in Node. Especially since Node 8 with Long Term Support (LTS) shipped in 2017.

And what’s better than promises? Async and await support, also included with Node 8.

While prior versions of the DocuSign Node.js SDK could be converted to use promises, the new version’s native support enables even more straight-forward programming.

The new release supports native JavaScript promises without breaking current SDK clients: if the last argument to an SDK method is a function, then the function will be used as the method’s callback function (same as prior releases). If the last argument to an SDK method is not a function, then the method will return a promise.

Let’s see what the async / await pattern looks like, including error handling:

/**
* Note the async keyword in the function declaration
*//
async function sendEnvelope {
    // Create the envelope definition in envDef
    …
    // Send the envelope:
    // 1. create the apiClient and envelopesApi SDK objects
    const apiClient = new docusign.ApiClient();
    apiClient.setBasePath(basePath);
    apiClient.addDefaultHeader('Authorization',
        'Bearer ' + accessToken);
    let envelopesApi = new docusign.EnvelopesApi()
      , results;
    // 2. Call the API with try/catch blocks
    try {
        // Note the await keyword. No callbacks!
        results = await envelopesApi.createEnvelope(
            accountId, {'envelopeDefinition': envDef})
        
        // Process the successful results
        const envelopeId = results.envelopeId
        …
    } catch  (e) {
        // Handle exceptions
        let body = e.response && e.response.body;
        if (body) {
            // DocuSign API exception
            // Use JSON.stringify(body, null, 4) to view 
            // the error message
            …
        } else {
            throw e; // Not a DocuSign exception
        }
    }
}

Doesn’t the above code look good? No callbacks, no testing of error arguments!

Try out promises for yourself via the Node.js code example.

And that’s not all!

Check out the release’s Changelog for more information on the additional updates in the release.

Are you already using or planning to use promises? Do you have ideas for future developer blog posts? Let me know via developers@docusign.com.

Larry Kluger
Author
Larry Kluger
DocuSign Lead Product Manager for Partner Platforms
Published
Related Topics