Promises in AngularJS, Explained as a Cartoon

One morning, a father says to his son: "Go and get the weather forecast, son!"

Every Sunday morning, a father asks his son to go and find out the weather forecast for the afternoon, by using his super-strong telescope to look across the horizon from the tallest hill by their house. The son promises his dad he will go and get the weather forecast. He creates a promise with his dad at the door when he leaves.

At that point, the dad decides if the weather tomorrow is good, he'll prepare a fishing trip for tomorrow. If it's bad he won't. Also, if the son is unable to get a forecast, he'll stay in as well.

After 30mins or so, the son comes back. Different things happen from week-to-week:

How does this look in code?

The dad is controlling the logic in this situation, and he's dealing with the Son as if he's a service.

We've already stated the logic, the father asks the son to get the weather forecast, and as the son can't tell him immediately, and the father has other things to do while he waits, the son makes a promise he shall return with the weather. When the dad has the forecast, he'll either pack up the boat, or stay inside. The important thing to note here, is the son's trip up the hill shouldn't 'block' the dad from doing anything, so this is why the situation is perfect for the creation of a promise, which can be resolved (fulfilled or rejected) later on.

Using Angular's then() function we can specify what the Dad needs to do in the event of each outcome. The then() function accepts 2 functions as parameters: a function to be executed when the promise is fulfilled, and a function to be executed when the promise is rejected.

Controller: FatherCtrl

The father is controlling the situation here:

        // function somewhere in father-controller.js
        var makePromiseWithSon = function() {
            // This service's function returns a promise, but we'll deal with that shortly
            SonService.getWeather()
                // then() called when son gets back
                .then(function(data) {
                    // promise fulfilled
                    if (data.forecast==='good') {
                        prepareFishingTrip();
                    } else {
                        prepareSundayRoastDinner();
                    }
                }, function(error) {
                    // promise rejected, could log the error with: console.log('error', error);
                    prepareSundayRoastDinner();
                });
        };
    

Service: SonService

The Son is being used as a service, he climbs the hill and tried to see the weather. We'll suppose when the son is looking through his telescope and looking for the approaching weather, it's analogous to using a weather API, in the sense that it's an asynchronous operation, he may get a variable answer, and there may be a problem (say, a 500 response, foggy skies).

The response from the 'Fishing Weather API' will be returned with the promise, if it was fulfilled. It will be in the format: { "forecast": "good" }

    app.factory('SonService', function ($http, $q) {
        return {
            getWeather: function() {
                // the $http API is based on the deferred/promise APIs exposed by the $q service
                // so it returns a promise for us by default
                return $http.get('https://fishing-weather-api.com/sunday/afternoon')
                    .then(function(response) {
                        if (typeof response.data === 'object') {
                            return response.data;
                        } else {
                            // invalid response
                            return $q.reject(response.data);
                        }

                    }, function(response) {
                        // something went wrong
                        return $q.reject(response.data);
                    });
            }
        };
    });
    

Summary

This analogy demonstrates the asynchronous nature of the request the dad makes to his son, for the weather forecast. The dad doesn't want to wait at the door in anticipation when the son leaves, because he has other stuff to do. Instead, he makes a promise at the door, and decides what will happen in either of the 3 scenarios (good weather/bad weather/no forecast). The son immediately gives a promise to his dad when he leaves, and will resolve or reject it on his return.

The son is dealing with an asynchronous service (searching the sky with his telescope/using a weather API) to get data, but all of this is correctly abstracted away from his old man, who doesn't really understand technology!