JavaScript, through its popularity and recent improvements, is increasingly becoming the web programmer's best friend. And like all best friends, JavaScript keeps its promises. 

Now that may sound a little strange, but it's true. Most current browsers support what is called the Promise object. A promise is quite like a function in that it represents a piece of code or a task that you would like to be executed at some point in the future.

Here's what a promise looks like.

var myPromise = new Promise(function (resolve, reject) {
    // Task to carry out goes here.
});

You can see here that when we create a promise we give it a single argument, which is a function containing code that we would like to execute at some point in the future. You may have also have noticed the two arguments in the function passed to the promise, resolve and reject. These are also functions and are our way of telling the Promise whether it has done what it promised to do. This is how you would use them:

var myPromise = new Promise(function (resolve, reject) {
    if (true) {
        resolve('Hello Tuts+ fans!');
    } else {
        reject('Aww, didn\'t work.');
    }
});

This promise is obviously always going to resolve as the if statement will always be true. This is just for learning purposes—we'll do something more realistic later on—but imagine replacing the true with a snippet of code that you weren't 100% sure was going to work.

Now that we've created a promise, how do we use it? Well, we need to tell it what those resolve and reject functions are. We do this by using the promise's then method.

myPromise.then(function (result) {
    // Resolve callback.
    console.log(result); 
}, function (result) {
    // Reject callback.
    console.error(result);
});

Because our if statement is always passing its true check, the above code will always log "Hello Tuts+ fans!" to the console. It will also do it immediately. This is because the code inside our Promise's constructor is synchronous, meaning that it isn't waiting on any operation to execute. It has all the information it needs to continue and does so as soon as possible. 

Where promises really shine, though, is when it comes to asynchronous tasks—tasks where you don't know when exactly the promise will be fulfilled. A real-world example of an asynchronous task is fetching a resource, like a JSON file for instance, via AJAX. We don't know how long the server is going to take to respond, and it may even fail. Let's add in some AJAX to our promise code.

var myPromise = new Promise(function (resolve, reject) {
    // Standard AJAX request setup and load.
    var request = new XMLHttpRequest();
    
    // Request a user's comment from our fake blog.
    request.open('GET', 'http://jsonplaceholder.typicode.com/posts/1');

    // Set function to call when resource is loaded.
    request.onload = function () {
        if (request.status === 200) {
            resolve(request.response);
        } else {
            reject('Page loaded, but status not OK.');
        }
    };

    // Set function to call when loading fails.
    request.onerror = function () {
        reject('Aww, didn\'t work at all.');
    }

    request.send();
});

The code here is just standard JavaScript for performing an AJAX request. We request a resource, in this case a JSON file at a specified URL, and wait for it to respond. We'll never know exactly when. And we obviously don't want to halt the execution of out script to wait for it, so what do we do? 

Well, luckily we've put this code inside a promise. By putting it here, we're basically saying, "Hey piece of code, I've got to go just now but I'll give you a call later and tell you when to execute. Promise you'll do it and tell me when you're done?" And the code will say, "Yes, of course. I promise." 

An important thing to note in the above piece of code is the calling of the resolve and reject functions. Remember, these are our way of telling our promise that our code has or hasn't executed successfully. Otherwise, we'll never know.

Using the same code from our basic example, we can see how our AJAX request inside the promise will now work.

// Tell our promise to execute its code
// and tell us when it's done.
myPromise.then(function (result) {
    // Prints received JSON to the console.
    console.log(result);
}, function (result) {
    // Prints "Aww didn't work" or
    // "Page loaded, but status not OK."
    console.error(result); 
});

I knew we could trust you, myPromise.

Chaining Promises

Now, you may be thinking at this point that promises are just fancy callback functions with a nicer syntax. That's true to a degree, but to continue with our AJAX example, say you needed to make few more requests, each request based on the result of the last. Or what if you needed to process the JSON first? 

Doing this with callbacks would end in heavy nesting of functions, each one becoming increasingly difficult to keep track of. Luckily, in the world of promises we can chain such functions together like so. Here's an example where once we receive the JSON for a user's comment on our fake blog, then we want to make sure it's all lowercase before doing something else with it.

myPromise
    .then(function (result) {
        // Once we receive JSON,
        // turn it into a JSON object and return.
        return JSON.parse(result);
    })
    .then(function (parsedJSON) {
        // Once json has been parsed,
        // get the email address and make it lowercase.
        return parsedJSON.email.toLowerCase();
    })
    .then(function (emailAddress) {
        // Once text has been made lowercase,
        // print it to the console.
        console.log(emailAddress);
    }, function (err) {
        // Something in the above chain went wrong?
        // Print reject output.
        console.error(err);
    });

You can see here that while our initial call was asynchronous, it's possible to chain synchronous calls too. The code in each resolve function inside the then will be called when each one returns. You'll also notice that there is only one error function specified here for the whole chain. By placing this at the end of the chain as the reject function in the last then, any promise in the chain that calls reject will call this one.

Now that we're a bit more confident with promises, let's create another one in conjunction with the one above. We'll create one that takes our new lowercase email address and will (pretend to) send an email to that address. This is just an example to illustrate something asynchronous—it could be anything, like contacting a server to see if the email was on a whitelist or if the user is logged in. We'll need to give the email address to the new promise, but promises don't accept arguments. The way to get around this is to wrap the promise in a function that does, like so:

var sendEmail = function (emailAddress) {
    return new Promise(function (resolve, reject) {
        // Pretend to send an email
        // or do something else asynchronous
        setTimeout(function () {
            resolve('Email sent to ' + emailAddress);
        }, 3000);
    });
};

We're using the setTimeout call here to simply fake a task that takes a few seconds to run asynchronously.

So how do we use our new promise-creating function? Well, since each resolve function used within a then should return a function, then we can use it in a similar way to our synchronous tasks.

myPromise
    .then(function (result) {
        return JSON.parse(result);
    })
    .then(function (parsedJSON) {
        return parsedJSON.email.toLowerCase();
    })
    .then(function (emailAddress) {
        return sendEmail(emailAddress)
    })
    .then(function (result) {
        // Outputs "Email sent to [email protected]"
        console.log(result);
    }, function (err) {
        console.error(err);
    });

Let's go over this flow just to summarise what's going on. Our original promise myPromise requests a piece of JSON. When that JSON is received (we don't know when), we turn the JSON into a JavaScript object and return that value. 

Once that's done, we take the email address out of the JSON and make it lowercase. Then we send an email to that address, and again we don't know when it's going to complete, but when it does we'll output a success message to the console. No heavy nesting in sight.

Conclusion

I hope this has been a useful introduction to Promises, and has given you good reason to start using them in your JavaScript projects. If you want to learn more about Promises in greater detail, check out Jake Archibald's excellent HTML5 Rocks article on this very subject.