When is a good time to use a Promise?

I have recently noticed a great deal of confusion in the office regarding promises, how they work, and what is a good example of when to use them. So I am going to try to expand upon a previous post: Promises Versus Callbacks.

What is a Promise?

A javascript promise is a way to my synchronous code asynchronous. Now you may ask yourself why you would want to do that in your application, and the answer for most inline javascript is that you wouldn't. It adds a layer of complexity that simply does not need to be there for a basic app. However once you add in the need for something to happen asynchronously (such as an API call) these become very useful very quickly because they allow you run code once the promise is completed (resolved).

If you have ever used jQuery to make an API call or get content from another page using the $.get, $.post, or $.ajax functions, than you have already used promises and probably have been for some time. JQuery uses its own deferred methods to make this happen, and you have access to those methods too.

Sifting through the Documentation

We use jQuery's Deferred for our end and Simply-Deferred for our back end, and these both come with a lot of documentation that can easily make people feel overwhelmed. But both these libraries provide the same functionality, and work the same way.

Here is the premise. They operate like 2 sides of a coin, Deferred and Promise. Deferred's run in your methods, and Promises run on your callers. The deferred's pass information and state to the promises with corresponding chained methods. Use the following code snippet as and example.

I created and stored a new deferred. The deferred object has a function property called promise which is returned by the myCallingMethod function. Which means that now the value of myPromise is the promise which is returned by myCallingMethod's deferred object. To maintain the coin analogy, lets called myCallingMethod's deferred object Heads, and its promise Tails.

When the timeout has completed half a second after the function is called, we tell Heads that it is time to resolve, and we pass in the value we want to resolve with into the resolve method. Heads will see that resolve has been used, and it will than send all the values passed into it into Tails done method. We pass an anonymous function in Tails done function property to capture those values, and work with them accordingly. In case of the example above, alert the value passed into done from resolve.

Similarly, deferred's and promises give many other options to pass both state and value(s). But here is all really need to work with them.

| Heads     | -> | Tails      |
| --------- | -- | ---------- |
| resolve() | -> | done()     |
| reject()  | -> | fail()     |
| notify()  | -> | progress() |

In addition, most promises also have .then() and .always() to expand upon their functionalities.

Why would I want to complicate my code with these things?

There are all kinds of reasons to do it on the node/express side of things, but lets take a look at client side for a clear benefit example.

Lets say that we have a single page app with several links (<a href='doc1'>document 1</a>) that goto documents which are stored in our API. Instead of going to our API each time to get the content, we set up a cache to store documents we have already retrieved.

First of we would create a method to get our document, check to see if the document is in our cache, and if not, use our API to get the document and return it.

By using a promise in this case, we can ensure that we have a consistent result on our calling side wether the resulting document was found in our cache, or if it was found in via the api.

I hope that this provides some greater insight into what a promise is, how to use them, and an idea as to when.