Synchronicity issues

Since the nature of our framework is asynchronous we need to provide ways to handle that situation.

Example

The user changes the cartocss of a layer and he wants to draw a red dot when there was an error. With the current api we got:

layer.setStyle(newStyle);
// layer fires  a ' styleChanged'  event without knowing the server's response

So the only way of detect an error would be through the client error api: Notice this is not yet implemented and currently a cartoError has only a message field

client.on(carto.events.ERROR, function(cartoError) { 
  switch(cartoError.type) {
    case: 'layerError': 
     // ...
    break;
    ...
});

// If some error happened will be detected by the client error callback
layer.setStyle(newStyle);

Options

• Callbacks
• Promises
• Events

Since callbacks are being deprecated and we must to change the API I bet for using promises and events resulting in a very powerful api.

layer.setStyle(newStyle)
  .then(nextFunction) // This callback will be executed once the style is set 
  .catch(errorFunciton) // This callback will be executed if there was some errors

layer.on('error', callback); // The layer will also trigger errors
layer.on('success', callback); // Should we have a `success` event too?

This also alows using the async/await feature introduced in ES6.

try {
  await  layer.setStyle(newStyle); 
  await  layer.setSource(newSource); // This method waits the style to be changed!
catch(cartoError) {
  errorFun(cartoError);
}

This is very useful to prevent unnecessary map reloads, think about an application where the user sets multiple changes into the map.

You could enqueue those changes and reload them at a stroke.

// This changes are not sent to the server
layer.setStyle(newStyle, {reload: false}); 
layer.setSource(newSource, {reload: false}); 
layer.setFeatureOverColumns(['foo'], {reload: false}); 
// Reload the map, once is reloaded show a popup, show widgets...etc
layer.reload()
  .then(() => popup('Reload ok!');
  .catch(cartoError => popup(cartoError.message); // Notice each layer/dataview will also throw its cartoErrors

Current status

We got a POC where the layer.setStyle and layer.setSource methods where updated There is also a working example for updating layer styles.

[Jesus89]

I think Promises are a nice way for the programmer to manage async operations. For example detecting success/error on a particular function or concatenate async methods.

Events are fine too, in order to detect changes without taking to account where the change happens, like in the dataviews’ dataChange event for example.

So I think both approaches have advantages and they have complementary functionality so I would include both.

[IagoLast]

Using promises should be optional IMO

Is optional, but the browsers warns about an possible uncaught error, not sure if we can prevent it…