Using JavaScript Promises in KeyLines: Part 2

Migrating to Promises and advanced ideas

Last week we published the first of two posts on KeyLines’ new JavaScript Promises functionality. Part one covered the basics of asynchronous (async) programing, callbacks, and how Promises can help you manage your async workflows.

In part two, we’ll take a more detailed look at how to use Promises in your KeyLines applications, starting with how to migrate your existing code from a callback approach.

Migrating from callbacks to Promises

Switching from callbacks to Promises is pretty simple. First you need to declare you’re using the Promisified KeyLines API at the top of your code:

// put this on top of your file
	KeyLines.promisify();

Then you need to make each of your callback functions a ‘thenable’. The then method specifies what needs to be done once the program returns a Promise:

// Before
chart.load( { ... }, function(){

  chart.zoom( 'fit', { ... }, function(){
  
    chart.layout('standard', { ... }, function(){
      // something else
    });
  });
});


// After
chart
  .load( { ... })
  .then( () => chart.zoom( 'fit', { ... }))
  .then( () => chart.layout('standard', { ... }))
  .then( () => {
// something else
  });

And that’s it! To check you’ve updated every callback, open the console with the application running. If you see this error…

callback has been passed, but the function will return a Promise instead

… you know you’ve missed one.

Compose actions with Promises

The previous blog post showed how to use Promises to run actions in a sequence or in parallel. What happens if you need to mix sequential and parallel actions? That’s easy too.

The code below demonstrates how to:

• load data into a chart
• zoom-fit
• run a layout and change node color simultaneously

chart.load(data)
	.then(() => chart.zoom(‘fit’))
	.then(() => {
		// run these 2 actions in parallel
		chart.layout(‘standard’);
		animateColor(‘red’);
	});

Parallel actions are called immediately after each other in the same block, whereas an asynchronous series action is called with another then chain.

Preparing JavaScript ES7: Async / Await

By adopting Promises now, your KeyLines code will be able to take full advantage of other JavaScript features currently in development.

One of the most exciting features we’re expecting in ES7 is async / await functions. To interact with Promises in ES6, we pass a callback to the then function. With async / await, we declare a function as async, then wait for the ‘Promised’ value to become available by delaying the execution of the calling code.

So, code you may have written like this:

chart.load( { ... }, function(){

  chart.zoom( 'fit', { ... }, function(){
  
    chart.layout('standard', { ... }, function(){
     // ...
    });
  });
});

Can be written with async / await syntax instead:

async function startup(){
  await chart.load( … );
  await chart.zoom(‘fit’);
  return chart.layout(‘standard’);
}

startup()
  .then( function(){
    // ...
  });

It’s simpler, so you end up with a linear code style that’s easier to test.

Try it yourself

Want to try KeyLines’ Promises for yourself? Request a trial to get started.