Promise (Deferred) Motivation

In JavaScript, asynchronous methods usually use callbacks in order to inform a success or a failure state. The Geolocation api, for example, requires success and failure callbacks in order to get the current position:

1
2
3
4
5
6
7
8
9
10

function success(position) {
  var coords = position.coords;
  console.log('Your current position is ' + coords.latitude + ' X ' + coords.longitude);
}

function error(err) {
  console.warn('ERROR(' + err.code + '): ' + err.message);
}

navigator.geolocation.getCurrentPosition(success, error);

Another example is XMLHttpRequest (used to perform ajax calls). It has onreadystatechange callback property that is called whenever the readyState attribute changes:

1
2
3
4
5
6
7
8
9
10

var xhr = new window.XMLHttpRequest();
xhr.open('GET', 'http://www.webdeveasy.com', true);
xhr.onreadystatechange = function() {
    if (xhr.readyState === 4) {
        if (xhr.status === 200) {
            console.log('Success');
        }
    }
};
xhr.send();

There are many other examples of asynchronicity in JavaScript. Working with callbacks gets complicated when there is a need to synchronize several asynchronous operations.

Sequentially Executing (Pyramid Of Doom)

Assume we have N asynchronous methods: async1(success, failure), async2(success, failure), …, asyncN(success, failure) and we want to execute them sequentially, one after another, upon success. Each method gets success and failure callbacks so the code will be:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

async1(function() {
    async2(function() {
        async3(function() {
            async4(function() {
                ....
                    ....
                        ....
                           asyncN(null, null);
                        ....
                    ....
                ....
            }, null);
        }, null);
    }, null);
}, null);

And here we get the famous callback pyramid of doom. Although there are nicer ways to write this code (separate that waterfall into functions for example), this is really hard to read and maintain.

Parallel Executing

Assume we have N asynchronous methods: async1(success, failure), async2(success, failure), …, asyncN(success, failure) and we want to execute them parallely and alert a message at the end of all. Each method gets success and failure callbacks so the code will be:

1
2
3
4
5
6
7
8
9
10
11
12
13
14

var counter = N;

function success() {
    counter --;
    if (counter === 0) {
        alert('done!');
    }
}

async1(success);
async2(success);
....
....
asyncN(success);

We declared a counter with initial value equals to the total asynchronous methods to execute. When each method is done, we decrease the counter by one and check whether this was the last execution. This solution is not simple for implementation or maintain, especially when each asynchronous method passes a result value to success(). In such case we will have to keep the results of each execution.

In both examples, at the time of execution of an asynchronic operation, we had to specify how it will be handled using a success callback. In other words, when we use callbacks, the asynchronic operation needs a reference to its continuation, but this continuation might not be its business. This can lead to tightly coupled modules and services which makes it difficult when reusing or testing code.

What are Promise and Deferred?

A deferred represents the result of an asynchronic operation. It exposes an interface that can be used for signaling the state and the result of the operation it represents. It also provides a way to get the associated promise instance.
A promise provides an interface for interacting with it’s related deferred, and so, allows for interested parties to get access to the state and the result of the deferred operation.
When creating a deferred, it’s state is pending and it doesn’t have any result. When we resolve() or reject() the deferred, it changes it’s state to resolved or rejected. Still, we can get the associated promise immediately after creating a deferred and even assign interactions with it’s future result. Those interactions will occur only after the deferred rejected or resolved.

When it comes to coupling, by using promises we can easily create an asynchronic operation before even decide what’s going to happen after the resolve. This is why coupling is looser. An asynchronic operation doesn’t have to know how it continues, it only has to signal when it is ready.

While deferred has methods for changing the state of an operation, a promise exposes only methods needed to handle and figure out the state, but not methods that can change the state. This is why in a function, returning a promise and not a deferred is a good practice. This prevents from external code to interfere the progress or the state of an operation.

There are several implementations of promises in different languages (JavaScript, JAVA, C++, Python and more) and frameworks (NodeJS, jQuery for JavaScript). AngularJS has a promise implementation under the $q service.

How to use Deferrers and Promises

After understanding promises and their motivation, now is the time to see how to use Deferrers and Promises. As said before, there are several implementations of promises, and so, different implementations may have different ways of usage. This section will use the AngularJS implementation of promise - the $q service. Still, if you use a different implementation of promises, don’t worry, most of the methods I’ll describe here are equal for all implementations and if not, there is always an equivalent method.

Basic usage

First things first, let’s create a deferred!

1

var myFirstDeferred = $q.defer();

As simple as can be, myFirstDeferred holds a deferred that can be resolved or rejected whenever an asynchronous operation is done. Assume we have an asynchronous method async(success, failure) that gets success and failure callbacks as parameters. When async is done, we want to resolve or reject myFirstDeferred with the result (value or error reason):

1
2
3
4
5

async(function(value) {
    myFirstDeferred.resolve(value);
}, function(errorReason) {
    myFirstDeferred.reject(errorReason);
});

Since $q’s resolve and reject methods don’t depend on a context in order to work, we can simply write:

1

async(myFirstDeferred.resolve, myFirstDeferred.reject);

Taking the promise out of myFirstDeferred and assigning operations upon success or failure is pretty easy:

1
2
3
4
5
6
7
8

var myFirstPromise = myFirstDeferred.promise;

myFirstPromise
    .then(function(data) {
        console.log('My first promise succeeded', data);
    }, function(error) {
        console.log('My first promise failed', error);
    });

Keep on mind that we can assign the success and failure operations right after creating the deferred (even before calling to async()) and that we can assign as many operations as we like:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

var anotherDeferred = $q.defer();
anotherDeferred.promise
    .then(function(data) {
        console.log('This success method was assigned BEFORE calling to async()', data);
    }, function(error) {
        console.log('This failure method was assigned BEFORE calling to async()', error);
    });

async(anotherDeferred.resolve, anotherDeferred.reject);

anotherDeferred.promise
    .then(function(data) {
        console.log('This ANOTHER success method was assigned AFTER calling to async()', data);
    }, function(error) {
        console.log('This ANOTHER failure method was assigned AFTER calling to async()', error);
    });

If async() successes, both success methods will occur. The same is for failure.
A good approach is to wrap asynchronous operations with a function that returns a promise. This way the caller will be able to assign success and failure callbacks the way he likes, but will not be able to interfere the deferred state:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

function getData() {
    var deferred = $q.defer();
    async(deferred.resolve, deferred.reject);
    return deferred.promise;
}
...
... // Later, in a different file
var dataPromise = getData()
...
...
... // Much later, at the bottom of that file :)
dataPromise
    .then(function(data) {
        console.log('Success!', data);
    }, function(error) {
        console.log('Failure...', error);
    });

Up to here, when we used promises, we assigned both success and failure callbacks. But, there is also a way to assign only success or only failure functions:

1
2
3
4
5
6
7
8

promise.then(function() {
    console.log('Assign only success callback to promise');
});

promise.catch(function() {
    console.log('Assign only failure callback to promise');
    // This is a shorthand for `promise.then(null, errorCallback)`
});

Passing only success callback to promise.then() will assign only success callback and using promise.catch() will assign only failure callback. catch() is actually a shorthand for promise.then(null, errorCallback).
In case we want to perform the same operation both on fulfillment or rejection of a promise, we can use promise.finally():

1
2
3

promise.finally(function() {
    console.log('Assign a function that will be invoked both upon success and failure');
});

This is equivalent to:

1
2
3
4

var callback = function() {
    console.log('Assign a function that will be invoked both upon success and failure');
};
promise.then(callback, callback);

Chaining values and promises

Assume we have an asynchronous function async() that returns a promise. I have this interesting block of code:

1
2
3
4

var promise1 = async();
var promise2 = promise1.then(function(x) {
    return x+1;
});

As you can understand from that code, promise1.then() returns another promise, and I named it promise2. When promise1 is resolved with a value x, the success callback executes and returns x+1. At this point promise2 is resolved with x+1.
Another similar example:

1
2
3
4
5

var promise2 = async().then(function(data) {
    console.log(data);
    ... // Do something with data
    // Returns nothing!
});

Here, when the promise that returned from async() is resolved, the success callback does it’s job and then promise2 is resolved with no data (undefined).
As you can see, promises can chain values and are always resolved after the callback occurs with the returned value.
In order to demonstrate it, here is a silly example that uses promises (there is no really a need to use promises here):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

// Let's imagine this is really an asynchronous function
function async(value) {
    var deferred = $q.defer();
    var asyncCalculation = value / 2;
    deferred.resolve(asyncCalculation);
    return deferred.promise;
}

var promise = async(8)
    .then(function(x) {
        return x+1;
    })
    .then(function(x) {
        return x*2;
    })
    .then(function(x) {
        return x-1;
    });

promise.then(function(x) {
    console.log(x);
});

This promises chain starts with calling to async(8) which fulfills the promise with the value 4. This value passes through all the success callbacks and so the value 9 is logged ((8 / 2 + 1) * 2 - 1).

What happens if we chain another promise (and not a value)? Assume we have two asynchronous functions, async1() and async2(), each returns a promise. Let’s see the following:

1
2
3
4
5
6

var promise = async1()
    .then(function(data) {
        // Assume async2() needs the response of async1() in order to work
        var async2Promise = async2(data);
        return async2Promise;
});

Here, unlike the previous example, the success callback performs another asynchronous operation and returns a promise. The value returned from async1().then() is a promise as expected, but now it can be resolved or rejected according to async2Promise and with it’s resolve value or reject reason.
Since async2() gets data as a parameter which is the value that async1() is resolved with, and since async2() returns a promise, we can simply write:

1
2

var promise = async1()
    .then(async2);

Here is another demonstration (again, the usage of promises in async1() and async2() is not mandatory and for demonstration purposes only):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

// Let's imagine those are really asynchronous functions
function async1(value) {
    var deferred = $q.defer();
    var asyncCalculation = value * 2;
    deferred.resolve(asyncCalculation);
    return deferred.promise;
}
function async2(value) {
    var deferred = $q.defer();
    var asyncCalculation = value + 1;
    deferred.resolve(asyncCalculation);
    return deferred.promise;
}

var promise = async1(10)
    .then(function(x) {
        return async2(x);
    });

promise.then(function(x) {
    console.log(x);
});

First, we call async1(10) which fulfills the promise and resolves it with the value 20. Then the success callback is executed and async2(20) returns a promise that is fulfilled with the value 21. Therefore promise is resolved with the value 21 and this is what logged.
A nice thing is that I can write the same example but with more readable code:

1
2
3
4
5
6
7

function logValue(value) {
    console.log(value);
}

async1(10)
    .then(async2)
    .then(logValue);

It is easy to see that first we call to async1(), then we call to async2() and at the end we call to logValue(). Each method gets the previous resolved value as a parameter. Naming functions with proper names will also make it easy to understand.
All the previous examples with promises chaining were pretty optimistic since they all succeeded. But in case a promise is rejected for any reason, the chained promise will also be rejected:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

// Let's imagine those are really asynchronous functions
function async1(value) {
    var deferred = $q.defer();
    var asyncCalculation = value * 2;
    deferred.resolve(asyncCalculation);
    return deferred.promise;
}
function async2(value) {
    var deferred = $q.defer();
    deferred.reject('rejected for demonstration!');
    return deferred.promise;
}

var promise = async1(10)
    .then(function(x) {
        return async2(x);
    });

promise.then(
    function(x) { console.log(x); },
    function(reason) { console.log('Error: ' + reason); });

As you can understand from this example, Error: rejected for demonstration! will be logged eventually. Promises can chain promises and are resolved or rejected according to the chained promise (with the chained promise resolve value or reject reason).
Here is a more advanced example of promises chaining:

1
2
3
4
5

async1()
    .then(async2)
    .then(async3)
    .catch(handleReject)
    .finally(freeResources);

In this example we invoked async1(), async2() and async3() one after another, synchronously. In case of any rejection in any one of those methods, the success invocation will stop and handleReject() will occur. At the end, freeResources() will occur no matter of success and failure. For instance, if async2() will return a rejected promise, async3() will not occur and handleReject() will be invoked with the rejection reason of async2(). And at the end freeResources() will occur.

Useful methods

$q has several helper methods that can be a great help when using promises. As I said before, other promises implementations have the same methods, probably with a different name.

Sometimes we need to return a rejected promise. Instead of creating a new promise and rejecting it, we can use $q.reject(reason). $q.reject(reason) returns a rejected promise with a reason. Example:

1
2
3
4
5
6
7
8
9
10
11
12
13

var promise = async().then(function(value) {
        if (isSatisfied(value)) {
            return value;
        } else {
            return $q.reject('value is not satisfied');
        }
    }, function(reason) {
        if (canRecovered(reason)) {
            return newPromiseOrValue;
        } else {
            return $q.reject(reason);
        }
    });

If async() is resolved with a satisfied value, the value is chained and thus promise will be resolved with it. If the value is not satisfied, a rejected promise is chained and promise will be rejected. If async() is rejected with a reason that can be recovered, a new value or promise will be chained. If the reason cannot be recovered, a rejected promise is chained and eventually promise will be rejected.

Similar to $q.reject(reason), sometimes we need to return a resolved promise with a value. Instead of creating a new promise and resolving it, we can use $q.when(value).

1
2
3
4
5
6
7
8

function getDataFromBackend(query) {
    var data = searchInCache(query);
    if (data) {
        return $q.when(data);
    } else {
        return makeAsyncBackendCall(query);
    }
}

In this example I wrote a function that should retrieve a data from my backend. But, before performing the backend call, the function searches the data in the cache. Since I want this function to always return a promise, in case the data is found in the cache, the function returns $q.when(data).
A cool thing with $q.when(value) is that if value is a 3rd party thenable promise (like jQuery’s Deferred), this method can wrap it and convert it into a $q promise. This way we can easily use other promises implementations with AngularJS.
$.ajax() of jQuery, for example, returns such thenable promise. The following converts it into angular $q promise:

1
2
3
4
5
6

var jQueryPromise = $.ajax({
    ...
    ...
    ...
});
var angularPromise = $q.when(jQueryPromise);

Sometimes we need to perform several asynchronous operations, no matter the order, and to be notified when they all done. $q.all(promisesArr) can help us with that. Assume we have N methods that return promises: async1(), ..., asyncN(). The following code will log done only when all operations are resolved successfully:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

var allPromise = $q.all([
    async1(),
    async2(),
    ....
    ....
    asyncN()
]);

allPromise.then(function(values) {
    var value1 = values[0],
        value2 = values[1],
        ....
        ....
        valueN = values[N];

        console.log('done');
});

$q.all(promisesArr) returns a promise that is resolved only when all the promises in promisesArr are resolved. Keep in mind that if any of the promises is rejected, the resulting promise will be rejected as well.

Up to here we have learned how to create a deferred, how to reject and resolve it and how to get an access to it’s promise. We also seen some useful helping methods that can make our code cleaner and more readable. I think that now is the time for a practical tutorial.

Promises tutorial using $q service

Let’s say we have an amazing application with an amazing registration form. In order to register, a user has to supply his current geolocation coordinates, his photo and a username. To perform the registration action, our backend architecture requires the following from the frontend:

1. Provide geolocation longitude and latitude if possible
2. Upload the user photo to our photos storage server and provide a url of it
3. Reserve the username upon username selection and provide username reservation id

For supporting that, let’s create the following simple functions (I decided to make this separation of functions in order to explain better). Look carefully and see that those methods are asynchronous and this is where promises come in:

Function that retrieves the current geolocation coordinates

1
2
3
4
5
6
7
8

function getGeolocationCoordinates() {
    var deferred = $q.defer();
    navigator.geolocation.getCurrentPosition(
        function(position) { deferred.resolve(position.coords); },
        function(error) { deferred.resolve(null); }
    );
    return deferred.promise;
}

getGeolocationCoordinates() declares a deferred and then asks the browser for the current position. Since the geolocation coordinates are not mandatory, both the success and failure callbacks that are provided to navigator.geolocation.getCurrentPosition() resolve the deferred with some result. In case of failure the result will be null. At the end, the deferred’s promise is returned.

Function that reads a local file and returns it’s content

1
2
3
4
5
6
7
8
9
10
11
12

function readFile(fileBlob) {
    var deferred = $q.defer();
    var reader = new FileReader();
    reader.onload = function () { deferred.resolve(reader.result); };
    reader.onerror = function () { deferred.reject(); };
    try {
        reader.readAsDataURL(fileBlob);
    } catch (e) {
        deferred.reject(e);
    }
    return deferred.promise;
}

readFile() gets a file blob (the output of <input type="file"> field) and uses FileReader to read it’s content. Before reading the data and returning a promise, readFile() assigned onload and onerror callbacks that resolve and reject the deferred accordingly with the result. Notice that I decided to wrap reader.readAsDataURL(fileBlob); with try {} catch() {} block in order to handle run time exceptions. In case of an exception, the deferred is rejected.

Function that gets file content and uploads it to files storage

1
2
3
4
5
6
7
8
9

function uploadFile(fileData) {
    var jQueryPromise = $.ajax({
        method: 'POST',
        url: '<endpoint for our files storage upload action>',
        data: fileData
    });

    return $q.when(jQueryPromise);
}

Since everyone knows jQuery, I decided to use $.ajax() in uploadFile(). $.ajax() returns a promise, which is actually what we need. But, this promise is a jQuery’s promise implementation and not $q. Fortunately, here we can use $q.when(value) method, so uploadFile() uses it and returns a promise.

Function that reserves a username and returns the reservation id

1
2
3
4
5

function reserveUsername(username) {
    return $http.post('<endpoint for username reservation action>', {
        username: username
    });
}

Here I used $http service of AngularJS. $http.post() returns a promise which indicates the post status. This promise is created by $q service inside $http.post() and this will be the return value.

Now that we have all the methods needed for registration, let’s wrap them in a service called appService (you can see the complete app-service.js at the end of this tutorial).

Application Controller

Our application controller is pretty simple. It uses $scope, $q and appCervice which are injected in the controller definition. The controller also contains several methods for handling the data (at the end of this tutorial you can find the full source code of this controller).

Longitude and Latitude

I don’t want the user to be able to enter values for longitude and latitude, the only way to set values on those fields is by getting the geolocation from the device. Here is a markup of two input elements, they are both bound to model and have a readonly attribute.

1
2
3
4
5
6
7
8

<div>
    Longitude
    <input type="text" readonly="readonly" ng-model="coords.longitude" />
</div>
<div>
    Latitude
    <input type="text" readonly="readonly" ng-model="coords.latitude" />
</div>

In the controller, all we have to do is to call getGeolocationCoordinates() and set the coordinates data when we get the result:

1
2
3
4

appService.getGeolocationCoordinates()
    .then(function setCoords(coordsData) {
        $scope.coords = coordsData;
    });

User name

Here is the markup for user name input. I also added error support by showing the error message and adding an error class in case of an error. Whenever the username input changes, $scope.reserveUsername() is called.

1
2
3
4
5
6
7

<div ng-class="{ error: usernameError }">
    User Name
    <div>
        <input type="text" ng-model="username" ng-change="reserveUsername()" />
        <div ng-bind="usernameError"></div>
    </div>
</div>

$scope.reserveUsername() should use appService to reserve the new username, set username reservation data upon success and set an error upon failure.

1
2
3
4
5
6
7
8
9
10
11
12

var reservationPromise = $q.reject('No username reservation had made');
$scope.reserveUsername = function() {
    var newUsername = $scope.username;
    reservationPromise = appService.reserveUsername(newUsername)
        .then(function setUsernameReservation(reservation) {
            $scope.reservation = reservation;
        })
        .catch(function setUsernameError() {
            $scope.usernameError = error;
            return $q.reject($scope.usernameError);
        });
}

First, reservationPromise is initialized with a rejected promise to handle a case where no reservation will be made.
When $scope.reserveUsername() happened, a backend reservation occurs. On success, setUsernameReservation() doesn’t return a promise and reservationPromise is resolved (values chaining causes the resulted promise to de resolved). On failure, setUsernameError() returns a rejected promise and so reservationPromise is rejected with an error message (promises chaining causes the resulted promise to be resolved or rejected according to the chained promise).

User Photo

The user photo field contains several components: the file input, a placeholder for the selected photo url, a placeholder for the selected image and a placeholder for an error message. I also used here a directive I wrote, named filePathChanged, that triggers a function whenever the user selects a file. You can see the code of the directive down this page.

1
2
3
4
5
6
7

<div ng-class="{ error: photoError }">
    Select Photo
    <input type="file" file-path-changed="fileSelected(files)">
    <span ng-bind="photoError"></span>
    <span ng-if="photoUrl" ng-bind="photoUrl"></span>
    <img ng-if="photoData" ng-src="" />
</div>

Let’s see the implementation of $scope.fileSelected(files).

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

var photoPromise = $q.reject('No user photo selected');
$scope.fileSelected = function(files) {
    if (files && files.length > 0) {
        var filePath = files[0];

        photoPromise = appService.readFile(filePath)
            .then(function setPhotoData(photoData) {
                $scope.photoData = photoData;
                return photoData;
            })
            .then(appService.uploadFile)
            .then(function setPhotoUrl(photoUrl) {
                $scope.photoUrl = photoUrl;
            })
            .catch(function setPhotoError(error) {
                $scope.photoError = 'An error has occurred: ' + error;
                return $q.reject($scope.photoError);
            });
    }
};

This code is simple. First we verify that a file is supplied. Next we read the file using appService.readFile() and set the photo data in a model. Then we upload the file data, get a url for the photo and set the photo url in a model. In case of any error we set the error message in a model and chain rejected promise.

Registration

Our last step is the registration button. We have to create a function that collects the longitude and latitude, the selected photo url and the reservation id of the chosen username. In any case of an error with the username reservation or the photo handling, this function has to reflect an error message. Remember, the longitude and latitude are not mandatory so if they are not available at the time of the registration - it will not stop the process.

1
2
3
4
5
6
7
8
9
10
11
12
13
14

$scope.register = function() {
    $q.all([
        reservationPromise,
        photoPromise
    ]).then(function doRegistrationCall() {
        var longitude = $scope.data.coords && $scope.data.coords.longitude;
        var latitude = $scope.data.coords && $scope.data.coords.latitude;
        var reservationId = $scope.data.reservation.token;
        var photoUrl = $scope.data.photoUrl;
        doRegistration(longitude, latitude, reservationId, photoUrl);
    }, function setSubmitError(error) {
        $scope.submitError = error;
    });
};

Here we used $q.all() because we want to perform an operation after username reservation and photo handling are both done. In case of any rejection we mark that the registration failed by assigning submitError model. In this example, doRegistration() is a method that does the registration call to the backend.

That’s all! our registration process is now complete.
Here is the full source of our small application.

app-service.js

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69

window.module.factory('appService', ['jquery', '$http', '$q', function($, $http, $q) {
    function getGeolocationCoordinates() {
        var deferred = $q.defer();
        navigator.geolocation.getCurrentPosition(
            function(position) { deferred.resolve(position.coords); },
            function(error) { deferred.resolve(null); }
        );
        return deferred.promise;
    }

    function readFile(fileBlob) {
        var deferred = $q.defer();
        var reader = new FileReader();
        reader.onload = function () { deferred.resolve(reader.result); };
        reader.onerror = function () { deferred.reject(); };
        try {
            reader.readAsDataURL(fileBlob);
        } catch (e) {
            deferred.reject(e);
        }
        return deferred.promise;
    }

    function uploadFile(fileData) {
        // var jQueryPromise = $.ajax({
        //     method: 'POST',
        //     url: '<endpoint for our files storage upload action>',
        //     data: fileData
        // });

        var deferred = $.Deferred();
        setTimeout(function() {
            deferred.resolve('www.myimage.com/123');
        }, 200);

        var jQueryPromise = deferred.promise();

        return $q.when(jQueryPromise);
    }

    var reserveCount = 0;
    function reserveUsername(username) {
        // return $http.post('<endpoint for username reservation action>', {
        //     username: username
        // });
        var deferred = $q.defer();
        setTimeout(function() {
            if (reserveCount > 0 && reserveCount % 3 === 0) {
                deferred.reject('error reserving "' + username + '"');
            } else {
                var token = 'token' + reserveCount;
                deferred.resolve({
                    token: token,
                    username: username
                });
            }
            reserveCount ++;
        }, 300);

        return deferred.promise;
    }

    return {
        getGeolocationCoordinates: getGeolocationCoordinates,
        readFile: readFile,
        uploadFile: uploadFile,
        reserveUsername: reserveUsername
    };
}]);

Note: in order to mimic uploadFile() and reserveUsername() without implementing a backend, I’ve created a custom code that sometimes is resolved and sometimes is rejected.
Now we can proceed with the controller implementation.

app-controller.js

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89

window.module.controller('appController', ['$scope', '$q', 'appService', function($scope, $q, appService) {

    $scope.data = { errors: { } };
    function setCoords(coordsData) {
        $scope.data.coords = coordsData;
    }
    function setPhotoData(photoData) {
        return $scope.data.photoData = photoData;
    }
    function setPhotoUrl(photoUrl) {
        return $scope.data.photoUrl = photoUrl;
    }
    function clearPhotoError() {
        delete $scope.data.errors.photo;
    }
    function setPhotoError(error) {
        $scope.data.errors.photo = 'An error has occurred: ' + error;
        return $q.reject($scope.data.errors.photo);
    }
    function clearUsernameError() {
        delete $scope.data.errors.username;
    }
    function setUsernameError(error) {
        $scope.data.errors.username = error;
        return $q.reject($scope.data.errors.username);
    }
    function setUsernameReservation(reservation) {
        $scope.data.reservation = reservation;
    }

    function setSubmitError(error) {
        $scope.data.errors.submit = error;
    }
    function clearSubmitError() {
        delete $scope.data.errors.submit;
    }

    function doRegistration(longitude, latitude, reservationId, photoUrl) {
        $scope.data.success = true;
        $scope.storedJSON = JSON.stringify({
            longitude: longitude,
            latitude: latitude,
            reservationId: reservationId,
            photoUrl: photoUrl
        });
    }

    appService.getGeolocationCoordinates()
        .then(setCoords);

    var photoPromise = $q.reject('No user photo selected');
    $scope.fileSelected = function(files) {
        if (files && files.length > 0) {
            var filePath = files[0];

            clearPhotoError();
            photoPromise = appService.readFile(filePath)
                .then(setPhotoData)
                .then(appService.uploadFile)
                .then(setPhotoUrl)
                .catch(setPhotoError);
        }
    };

    var reservationPromise = $q.reject('No username reservation had made');
    $scope.reserveUsername = function() {
        var newUsername = $scope.data.username;
        clearUsernameError();
        reservationPromise = appService.reserveUsername(newUsername)
            .then(setUsernameReservation)
            .catch(setUsernameError);
    }

    $scope.register = function() {
        $q.all([
            reservationPromise,
            photoPromise
        ]).then(function() {
            var longitude = $scope.data.coords && $scope.data.coords.longitude;
            var latitude = $scope.data.coords && $scope.data.coords.latitude;
            var reservationId = $scope.data.reservation.token;
            var photoUrl = $scope.data.photoUrl;
            clearSubmitError();
            doRegistration(longitude, latitude, reservationId, photoUrl);
        }, function(error) {
            setSubmitError(error);
        });
    };
}]);

index.html

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78

<!doctype html>
<html>
<head>
    <meta charset="utf-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <title></title>

    <script src="http://ajax.googleapis.com/ajax/libs/jquery/2.0.3/jquery.min.js"></script>
    <script type="text/javascript">
        window.jQuery || document.write('<script src="/scripts/libs/jquery.js"><\/script>');
    </script>

    <script src="http://ajax.googleapis.com/ajax/libs/angularjs/1.2.14/angular.min.js"></script>
    <script type="text/javascript">
        window.angular || document.write('<script src="/scripts/libs/angular.js"><\/script>');
    </script>

    <link rel="stylesheet" href="/style/semantic.css" />
    <link rel="stylesheet" href="/style/app.css" />
</head>
<body ng-app="demo-app">
    <form class="ui form segment" ng-controller="appController">
        <div class="two fields">
            <div class="field">
                <label for="longitude">Longitude</label>
                <input id="longitude" type="text" readonly="readonly" ng-model="data.coords.longitude" placeholder="No Longitude" />
            </div>
            <div class="field">
                <label for="latitude">Latitude</label>
                <input id="latitude" type="text" readonly="readonly" ng-model="data.coords.latitude" placeholder="No Latitude" />
            </div>
        </div>
        <div class="field username" ng-class="{ error: data.errors.username }">
            <label for="username">User Name</label>
            <div class="ui labeled icon input">
                <input id="username" type="text" ng-model="data.username" ng-change="reserveUsername()" placeholder="User Name" />
                <div class="ui red label pointing above" ng-bind="data.errors.username"></div>
                <i class="circular ban circle icon"></i>
                <i class="circular checkmark icon" ng-if="data.reservation"></i>
                <div class="ui corner label">
                    <i class="icon asterisk"></i>
                </div>
            </div>
        </div>

        <div class="inline field user-photo" ng-class="{ error: data.errors.photo }">
            <label for="file" class="ui icon button">
                <i class="file icon"></i>
                Select Photo
            </label>
            <input type="file" id="file" file-path-changed="fileSelected(files)">
            <span class="ui red label" ng-bind="data.errors.photo"></span>
            <span class="ui green label" ng-if="data.photoUrl" ng-bind="data.photoUrl"></span>
            <div class="ui segment" ng-if="data.photoData">
                <img class="rounded ui image" ng-src="" />
            </div>
        </div>

        <div class="field">
            <div class="ui blue submit button" ng-click="register()">Register</div>
        </div>

        <div class="field">
            <span class="ui red label" ng-if="data.errors.submit" ng-bind="data.errors.submit"></span>
            <span class="ui green label" ng-if="data.success">
                Registration Seccess with ,
                ,
                username = , photo url = 
            </span>
        </div>
    </form>

    <script type="text/javascript" src="scripts/module.js"></script>
    <script type="text/javascript" src="scripts/directives.js"></script>
    <script type="text/javascript" src="scripts/app-service.js"></script>
    <script type="text/javascript" src="scripts/app-controller.js"></script>
</body>
</html>

Here I used a nice CSS framework named Semantic UI in order to produce a better looking UI. Therefore this markup contains many classes and other elements.

directives.js

We only have one directive named filePathChanged.

1
2
3
4
5
6
7
8
9
10
11
12
13

window.module.directive('filePathChanged', function() {
    return {
        restrict: 'A',
        scope: {
            filePathChanged: '&'
        },
        link: function (scope, element, attrs) {
            element.bind('change', function() {
                scope.filePathChanged({ files: element.prop('files') });
            });
        }
    };
});

Summary

After reading this article you should know by now that working with callbacks might make a hard life especially when synchronization is needed (parallel and sequentially executing). You were introduced with the deferrers and promises solution and saw how to use it. Through this article you saw explanations and examples of important promises methods and learned about promises chaining. At the end you got a practical tutorial. Here is a short list to summarize the methods mentioned in this article:

• var deferred = $q.defer(); - creates a new deferred
• deferred.resolve(value); - resolves a deferred with a value
• deferred.reject(reason); - rejects a deferred with a reason
• var promise = deferred.promise; - gets a promise from deferred
• promise.then(success, failure); - assigns callbacks for success (resolve) and failure (reject)
• promise.catch(failure); - assigns failure callback (equals to promise.then(null, failure))
• promise.finally(always); - assign a callback to be called both on success or failure
• var promise = $q.reject(reason); - returns rejected promise with a reason
• var promise = $q.when(valueOrPromise); - wraps value or other implementation of thenable promise with AngularJS promise
• var promise = $q.all(promisesArr); - returns a promise that will be resolved only when all promises in `promisesArr` are resolved

Here are three additional links:

• The tutorial application in action
• The tutorial source on GitHub
• The tutorial source zip file

I really hope you liked this article! Good luck, NaorYe

Let me show you an example. This demo page includes two pages. The first page contains nothing but a link to the second page. When clicking on the link, we are redirected to the second page that contains an iframe. At this point, looking on the browser’s history will show us only the first page as expected:

In order to demonstrate navigation inside an iframe, the iframe in the second page contains a page with an anchor. This anchor refers to a different page. A click on the anchor causes navigation inside the iframe, but also adds a new history entry of the second page:

Pressing back will not return us back to the first page. Instead, it will change the iframe’s page and this is not the desired behavior.
What we really want is the iframe’s navigation not to interfere the browser’s navigation. Pressing the back button should take us back to the first page and not to the previous iframe’s page.

It appears that any location change in the iframe is stored in the browser’s history.

Once the problem is understood, the solution is pretty simple. Whenever the user navigates inside the iframe, we don’t want to add a new entry to the history. In order to do that, I’d like to explain a bit about anchors.

How anchors work?

When an anchor is clicked, it navigates to the new page and the new location is added to the browser’s hitory. But, if the url is the same as the current url, no history entry is added and the anchor only performs a page refresh. It is easy to verify what I am saying here by creating a page that contains a link to itself. Clicking on this anchor only refreshes the page and no history entry is added.

history.replaceState() To The Rescue

Luckily HTML5 gave us a great API for controlling the history. window.history exposes useful methods that let us manipulate the contents of the history stack. Among these methods we can find the replaceState() method. history.replaceState() can modify the current history entry and associate it with the current document.
Assuming we have the following anchor inside an iframe’s page: <a href="iframe2.html">iframe page 2</a>. Clicking on it redirects us to page2.html and adds a new history entry for that page. If the current location, prior to the anchor’s action, is the same as the anchor’s url, then no new history entry will be added.
Let’s manipulate the history and set the current location to the anchor’s url before the anchor performs it’s action:

1
2
3
4
5
6
7

var anchors = document.getElementsByTagName('a');
for (var i = 0; i < anchors.length; i++) {
    var anchor = anchors[i];
    anchor.addEventListener('click', function(event) {
        history.replaceState(null, null, anchor.href);
    }, false);
}

This script runs through all the page’s anchors and attaches a click event. Whenever the user clicks on an anchor, the current location is replaced with the anchor’s href. And here we prevented from another history entry to be added.
Keep in mind that this script has to run at the end of the page, after the DOM has loaded.
Here You can see the solution. Navigating inside the iframe doesn’t create history entry:

I spent a lot of time trying to understand the behavior of anchors and history and finding a solution for the back button issue. I hope you’ll find this explanation interesting and useful.
Thanks for reading, NaorYe

What are Interceptors?

The $httpProvider provider contains an array of interceptors. An interceptor is simply a regular service factory that is registered to that array. This is how we create an interceptor:

1
2
3
4
5
6
7
8
9
10
11

module.factory('myInterceptor', ['$log', function($log) {
    $log.debug('$log is here to show you that this is a regular factory with injection');

    var myInterceptor = {
        ....
        ....
        ....
    };

    return myInterceptor;
}]);

And then add it by it’s name to $httpProvider.interceptors array:

1
2
3

module.config(['$httpProvider', function($httpProvider) {
    $httpProvider.interceptors.push('myInterceptor');
}]);

Interceptors allow you to:

• Intercept a request by implementing the request function: This method is called before $http sends the request to the backend, so you can modify the configurations and make other actions. This function receives the request configuration object as a parameter and has to return a configuration object or a promise. Returning an invalid configuration object or promise that will be rejected, will make the $http call to fail.

• Intercept a response by implementing the response function: This method is called right after $http receives the response from the backend, so you can modify the response and make other actions. This function receives a response object as a parameter and has to return a response object or a promise. The response object includes the request configuration, headers, status and data that returned from the backend. Returning an invalid response object or promise that will be rejected, will make the $http call to fail.

• Intercept request error by implementing the requestError function: Sometimes a request can’t be sent or it is rejected by an interceptor. Request error interceptor captures requests that have been canceled by a previous request interceptor. It can be used in order to recover the request and sometimes undo things that have been set up before a request, like removing overlays and loading indicators, enabling buttons and fields and so on.

• Intercept response error by implementing the responseError function: Sometimes our backend call fails. Other times it might be rejected by a request interceptor or by a previous response interceptor. In those cases, response error interceptor can help us to recover the backend call.

Asynchronous Operations

Sometimes there is a need to make some asynchronous operations inside the interceptor. Luckily AngularJS allows us to return a promise that will be resolved later. This will defer the request sending in case of request interceptor and will defer the response resolving in case of response interceptor.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

module.factory('myInterceptor', ['$q', 'someAsyncService', function($q, someAsyncService) {
    var requestInterceptor = {
        request: function(config) {
            var deferred = $q.defer();
            someAsyncService.doAsyncOperation().then(function() {
                // Asynchronous operation succeeded, modify config accordingly
                ...
                deferred.resolve(config);
            }, function() {
                // Asynchronous operation failed, modify config accordingly
                ...
                deferred.resolve(config);
            });
            return deferred.promise;
        }
    };

    return requestInterceptor;
}]);

In this example, the request interceptor makes an asynchronous operation and updates the config according to the results. Then it continues with the modified config. If deferred is rejected, the http request will fail.
The same applies for response interceptor:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

module.factory('myInterceptor', ['$q', 'someAsyncService', function($q, someAsyncService) {
    var responseInterceptor = {
        response: function(response) {
            var deferred = $q.defer();
            someAsyncService.doAsyncOperation().then(function() {
                // Asynchronous operation succeeded, modify response accordingly
                ...
                deferred.resolve(response);
            }, function() {
                // Asynchronous operation failed, modify response accordingly
                ...
                deferred.resolve(response);
            });
            return deferred.promise;
        }
    };

    return responseInterceptor;
}]);

Only when deferred is resolved, the request will succeed. If deferred is rejected, the request will fail.

Examples

In this section I’ll provide some examples to AngularJS Interceptors in order to give a good understanding of how to use them and how they can help you. Keep in mind that the solutions I provide here are not necessarily the best or the most accurate solutions.

Session Injector (request interceptor)

There are two ways of implementing server side authentication. The first one is to use the traditional Cookie-Based Authentication that uses server side cookies to authenticate the user on each request. The other approach is Token-Based Authentication. When the user logs in, he gets sessionToken from the backend. This sessionToken identifies the user in the server and is sent to the server on each request.
The following sessionInjector adds x-session-token header to each intercepted request (in case the current user is logged in):

1
2
3
4
5
6
7
8
9
10
11
12
13
14

module.factory('sessionInjector', ['SessionService', function(SessionService) {
    var sessionInjector = {
        request: function(config) {
            if (!SessionService.isAnonymus) {
                config.headers['x-session-token'] = SessionService.token;
            }
            return config;
        }
    };
    return sessionInjector;
}]);
module.config(['$httpProvider', function($httpProvider) {
    $httpProvider.interceptors.push('sessionInjector');
}]);

And now creating a get request:

1

$http.get('https://api.github.com/users/naorye/repos');

The configuration object before intercepted by sessionInjector:

1
2
3
4
5
6
7
8
9
10
11
12
13

{
    "transformRequest": [
        null
    ],
    "transformResponse": [
        null
    ],
    "method": "GET",
    "url": "https://api.github.com/users/naorye/repos",
    "headers": {
        "Accept": "application/json, text/plain, */*"
    }
}

The configuration object after intercepted by sessionInjector:

1
2
3
4
5
6
7
8
9
10
11
12
13
14

{
    "transformRequest": [
        null
    ],
    "transformResponse": [
        null
    ],
    "method": "GET",
    "url": "https://api.github.com/users/naorye/repos",
    "headers": {
        "Accept": "application/json, text/plain, */*",
        "x-session-token": 415954427904
    }
}

Timestamp Marker (request and response interceptors)

Let’s measure the time it takes to get a backend response using interceptors. It is done by adding a timestamp for each request and response:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

module.factory('timestampMarker', [function() {
    var timestampMarker = {
        request: function(config) {
            config.requestTimestamp = new Date().getTime();
            return config;
        },
        response: function(response) {
            response.config.responseTimestamp = new Date().getTime();
            return response;
        }
    };
    return timestampMarker;
}]);
module.config(['$httpProvider', function($httpProvider) {
    $httpProvider.interceptors.push('timestampMarker');
}]);

And now we can do:

1
2
3
4

$http.get('https://api.github.com/users/naorye/repos').then(function(response) {
    var time = response.config.responseTimestamp - response.config.requestTimestamp;
    console.log('The request took ' + (time / 1000) + ' seconds.');
});

Here you can find an example for the Timestamp Marker.

Request Recover (request error interceptor)

In order to demonstrate a request error interceptor we have to simulate a situation where a previous interceptor rejects the request. Our request error interceptor will get the rejection reason and will recover the request.
Let’s create two interceptors: requestRejector and requestRecoverer.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

module.factory('requestRejector', ['$q', function($q) {
    var requestRejector = {
        request: function(config) {
            return $q.reject('requestRejector');
        }
    };
    return requestRejector;
}]);
module.factory('requestRecoverer', ['$q', function($q) {
    var requestRecoverer = {
        requestError: function(rejectReason) {
            if (rejectReason === 'requestRejector') {
                // Recover the request
                return {
                    transformRequest: [],
                    transformResponse: [],
                    method: 'GET',
                    url: 'https://api.github.com/users/naorye/repos',
                    headers: {
                        Accept: 'application/json, text/plain, */*'
                    }
                };
            } else {
                return $q.reject(rejectReason);
            }
        }
    };
    return requestRecoverer;
}]);
module.config(['$httpProvider', function($httpProvider) {
    $httpProvider.interceptors.push('requestRejector');
    // Removing 'requestRecoverer' will result to failed request
    $httpProvider.interceptors.push('requestRecoverer');
}]);

And now, if we do the following, we will get the log success even though requestRejector rejected the request:

1
2
3
4
5

$http.get('https://api.github.com/users/naorye/repos').then(function() {
    console.log('success');
}, function(rejectReason) {
    console.log('failure');
});

Here you can find an example for the Request Recover.

Session Recoverer (response error interceptor)

There are times, in our single page application, where the session gets lost. Such situation might happen due to session expiration or a server error. Let’s create an interceptor that will recover the session and resend the original request again automatically (for situations where the session expired).
For the example purposes, let’s assume that the http status code for session expiration is 419.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

module.factory('sessionRecoverer', ['$q', '$injector', function($q, $injector) {
    var sessionRecoverer = {
        responseError: function(response) {
            // Session has expired
            if (response.status == 419){
                var SessionService = $injector.get('SessionService');
                var $http = $injector.get('$http');
                var deferred = $q.defer();

                // Create a new session (recover the session)
                // We use login method that logs the user in using the current credentials and
                // returns a promise
                SessionService.login().then(deferred.resolve, deferred.reject);

                // When the session recovered, make the same backend call again and chain the request
                return deferred.promise.then(function() {
                    return $http(response.config);
                });
            }
            return $q.reject(response);
        }
    };
    return sessionRecoverer;
}]);
module.config(['$httpProvider', function($httpProvider) {
    $httpProvider.interceptors.push('sessionRecoverer');
}]);

This way, whenever a backend call fails due to session expiration, sessionRecoverer creates a new session and performs the backend call again.

Summary

In this article I explained about AngularJS interceptors. I presented request, response, requestError and responseError interceptors and described how and when to use them. I also provided real world useful examples that can help you in your development.

I hope you enjoyed reading this article as much as I enjoyed writing it!
Good Luck!
NaorYe

What is wrong with $log?

Nothing! Really, $log is doing it’s work. It is a simple service for logging, including a default implementation that writes messages into the browser’s console. And that’s it. But when talking about logging, I’d like a service that will print my messages nicely, something like a timestamp and maybe a hint about where the message was created. I would also like to turn off all the messages during application configuration when running on production, and maybe expose a way to turn it on. I know $logProvider has the debugEnabled(flag) method, but I would like to turn off all the other kinds of messages (like info() and error()) and not only debug. Later on I may want to add colors to my messages and maybe aggregate all the error() messages and send them somehow to me. This is why I was looking to create a new logging mechanism.
While thinking about a way of implementation, I considered using a service decorator but then realized that I might want more than modifying the behavior of $log, like add or remove methods, or change the way $log’s methods work. Eventually I decided to use a service provider.

A little about AngularJS services

This section might be a little confusing, but it is really important to understand. When we call module.provider(), we are actually calling the provider() method of the $provide service. $provide.provider() is exposed on angular.Module. The same is for module.service() and module.factory(), they are methods of $provide service that are exposed on angular.Module. Therefore the following blocks are the same thing:

1
2
3

module.provider('providerName', function() { ... });
module.service('serviceName', function() { ... });
module.factory('factoryName', function() { ... });

1
2
3
4
5
6
7
8
9

module.config(['$provide', function($provide) {
    $provide.provider('providerName', function() { ... });
});
module.config(['$provide', function($provide) {
    $provide.service('serviceName', function() { ... });
});
module.config(['$provide', function($provide) {
    $provide.factory('factoryName', function() { ... });
});

More than that, $provide.service() and $provide.factory() are actually an easy way to use $provide.provider():

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

$provide.service('serviceName', function() {
    this.name = 'The Catcher in the Rye';
    this.author = 'J. D. Salinger';
});
// Equals to
$provide.provider('serviceName', function() {
    this.$get = function($injector) {
        return $injector.instantiate(function() {
            this.name = 'The Catcher in the Rye';
            this.author = 'J. D. Salinger';
        });
    };
});

$provide.factory('factoryName', function() {
    return { name: 'The Catcher in the Rye', author: 'J. D. Salinger' };
});
// Equals to
$provide.provider('serviceName', function() {
    this.$get = function($injector) {
        return $injector.invoke(function() {
            return { name: 'The Catcher in the Rye', author: 'J. D. Salinger' };
        });
    };
});

As we all can see, AngularJS only knows service provider ($provide.provider()) and all other ways of creating services are derived.

What service provider gives?

Besides of creating the service, service provider allows to configure the service on module.config() block. Look on the following appColor example service that is defined by a service provider:

1
2
3
4
5
6
7
8
9

$provide.provider('appColor', function() {
    var color = 'Green';
    this.setColor = function(newColor) {
        color = newColor;
    };
    this.$get = function() {
        return color;
    };
});

Whenever we ask from Angular to inject appColor, we get the color variable that returned from the $get method. But on module.config() blocks we can ask for appColorProvider which exposes the provider and all it’s methods and attributes. This let us configure the service before other code consumes it:

1
2
3
4
5
6
7
8
9

module.config(['appColorProvider', function(appColorProvider) {
    appColorProvider.setColor('Blue');
});
...
...
module.run(['appColor', function(appColor) {
    // Will log: 'Application color is Blue'
    console.log('Application color is ' + appColor);
});

As you can see, service provider gave us access to the “provider” part, where we can set methods or variables and which can be accessed during configuration only. And this is what I was looking for when thinking about creating my Logger.

Creating the Logger!

I want to create a Logger service that will print my messages in the following formats (according to the supplied arguments):
<timestamp> - <context>::<method name>('<message>') <timestamp> - <context>: <message>

Before integrating with Angular, let’s create a Logger class that uses $log. First we will create a Logger constructor and a static helper method that will create new instances of Logger.

1
2
3
4
5
6

var Logger = function(context) {
    this.context = context;
};
Logger.getInstance = function(context) {
    return new Logger(context);
};

The constructor gets a context as a parameter.
I want it to be easy to interpolate variables into the message string. Therefore, let’s take Douglas Crockford’s supplant implementation and put it as a helper in Logger:

1
2
3
4
5
6
7
8
9

Logger.supplant = function(str, o) {
    return str.replace(
            /\{([^{}]*)\}/g,
            function (a, b) {
                var r = o[b];
                return typeof r === 'string' || typeof r === 'number' ? r : a;
            }
        );
};

Now it is easy to add a method that returns a formatted timestamp:

1
2
3
4
5
6
7
8

Logger.getFormattedTimestamp = function(date) {
   return Logger.supplant('{0}:{1}:{2}:{3}', [
        date.getHours(),
        date.getMinutes(),
        date.getSeconds(),
        date.getMilliseconds()
    ]);
};

Notice that the last two methods are generic methods and you can take them out and put in your utils service for example.
Now we want to write a generic _log() method that gets the original method of $log (log, info, warn, debug or error) and uses it to print a message according to the given arguments. First I’ll show my implementation and then explain:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

Logger.prototype = {
    // Supports the following arguments: fnName (optional), message (mandatory), supplantData (optional)
    // Length and types of arguments are checked in order to determine the usage
    _log: function(originalFn, args) {
        var now  = Logger.getFormattedTimestamp(new Date());
        var message = '', supplantData = [];
        switch (args.length) {
            case 1:
                message = Logger.supplant("{0} - {1}: {2}", [ now, this.context, args[0] ]);
                break;
            case 3:
                supplantData = args[2];
                message = Logger.supplant("{0} - {1}::{2}(\'{3}\')", [ now, this.context, args[0], args[1] ]);
                break;
            case 2:
                if (typeof args[1] === 'string') {
                    message = Logger.supplant("{0} - {1}::{2}(\'{3}\')", [ now, this.context, args[0], args[1] ]);
                } else {
                    supplantData = args[1];
                    message = Logger.supplant("{0} - {1}: {2}", [ now, this.context, args[0] ]);
                }
                break;
        }

        $log[originalFn].call(null, Logger.supplant(message, supplantData));
    },
    ...
};

_log() method first gets the formatted current date. Then it checks for the arguments length and types and determines which output the user wants to print:

1. If the user supplied one argument, then the argument must be the message itself and _log() will print: <timestamp> - <context>: <message>
2. If the user supplied three arguments, then the first argument is a method name, the second is the message and the third is an object of variables to interpolate with the message. For this, _log() will print: <timestamp> - <context>::<method name>('<message>')
3. If the user provided two arguments, we need to find out whether he supplied a method name or an interpolation object. In order to figure that out, we’ll check the type of the last argument. If it is a string, then it has to be the message itself while the first argument is the method name. Otherwise consider the first argument as the message and the second as array of interpolation variables. The output print will be according to this check.

At the end, _log() calls the required method on $log with the interpolated message.
Now the last thing to do is to implement an overrides to log(), info(), warn(), debug() and error():

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

Logger.prototype = {
    ...
    log: function() {
        this._log('log', arguments);
    },
    info: function() {
        this._log('info', arguments);
    },
    warn: function() {
        this._log('warn', arguments);
    },
    debug: function() {
        this._log('debug', arguments);
    },
    error: function() {
        this._log('error', arguments);
    }
};

Finally we have a Logger! This is how we can use it:

1
2
3
4
5

var logger = Logger.getInstance('Example'); // Name of this file / class / module
logger.log('This is a log'); // Logs: "19:24:1:263 - Example: This is a log"
logger.warn('warn', 'This is a warn'); // Warns: "19:24:1:263 - Example::warn('This is a warn')"
logger.error('This is a {0} error! {1}', [ 'big', 'just kidding' ]); // Shouts: "19:24:1:263 - Example: This is a big error! just kidding"
logger.debug('debug', 'This is a debug for line {0}', [ 8 ]); // Logs: "19:24:1:263 - Example::debug('This is a debug for line 8')"

Now we can finally integrate our new Logger with AngularJS service provider!

Back To AngularJS Service Provider

I wanted to create Logger provider with the ability of disable all the logs. For that I’ve created a provider that wraps our Logger implementation and adds a method to LoggerProvider for enable or disable Logger:

1
2
3
4
5
6
7
8
9
10
11
12
13
14

module.provider('Logger', [function () {
    var isEnabled = true;
    this.enabled = function(_isEnabled) {
        isEnabled = !!_isEnabled;
    };

    // $log injected as a dependency
    this.$get = ['$log', function($log) {
        var Logger = ...
        ... // Logger implementation

        return Logger;
    }];
}]);

The last thing left to do is to change the _log() to do nothing if isEnabled equals to false:

1
2
3
4
5
6

Logger.prototype = {
    _log: function(originalFn, args) {
        if (!isEnabled) {
            return;
        }
        ....

As you can see, Logger is enabled by default. In order to turn it off we just need to do:

1
2
3

module.config(['LoggerProvider', function(LoggerProvider) {
    LoggerProvider.enabled(false);
});

Thats all!

Summary

On this article I discussed the difference between AngularJS factory, service and provider. I showed the similarity and explained that service provider is a base method that all other ways of creating services are derived from. I also explained the options of service provider over other services and the most important thing, created a Logger provider with you!

Here you can find Logger GitHub Repository with the source code and a demo.

NaorYe

Defining a model for controller

Let’s start with a simple example. I would like to display a book view. This is the controller:

1
2
3
4
5
6
7
8
9
10
11
12

app.controller('BookController', ['$scope', function($scope) {
    $scope.book = {
        id: 1,
        name: 'Harry Potter',
        author: 'J. K. Rowling',
        stores: [
            { id: 1, name: 'Barnes & Noble', quantity: 3},
            { id: 2, name: 'Waterstones', quantity: 2},
            { id: 3, name: 'Book Depository', quantity: 5}
        ]
    };
}]);

This controller creates a model of book which can be later used in our template:

1
2
3
4
5
6
7

<div ng-controller="BookController">
    Id: <span ng-bind="book.id"></span>
    <br/>
    Name:<input type="text" ng-model="book.name" />
    <br/>
    Author: <input type="text" ng-model="book.author" />
</div>

In case we would like to get the book data from a backend api, we can also use $http:

1
2
3
4
5
6
7

app.controller('BookController', ['$scope', '$http', function($scope, $http) {
    var bookId = 1;

    $http.get('ourserver/books/' + bookId).success(function(bookData) {
        $scope.book = bookData;
    });
}]);

Notice that bookData is still a JSON object. Later on we would like to do something with this data. For example, update the book, delete it or even do other operations that are not dealing with the backend, like generate a book image url according to requested size or determining whether the book is available. Those methods can be declared on our controller:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

app.controller('BookController', ['$scope', '$http', function($scope, $http) {
    var bookId = 1;

    $http.get('ourserver/books/' + bookId).success(function(bookData) {
        $scope.book = bookData;
    });

    $scope.deleteBook = function() {
        $http.delete('ourserver/books/' + bookId);
    };

    $scope.updateBook = function() {
        $http.put('ourserver/books/' + bookId, $scope.book);
    };

    $scope.getBookImageUrl = function(width, height) {
        return 'our/image/service/' + bookId + '/width/height';
    };

    $scope.isAvailable = function() {
        if (!$scope.book.stores || $scope.book.stores.length === 0) {
            return false;
        }
        return $scope.book.stores.some(function(store) {
            return store.quantity > 0;
        });
    };
}]);