Running Angular applications inside a Docker container – part 1

Introduction

This is the first post in a series of posts in which I will deploy an Angular2 application and an Express server inside a Docker container. By the end of the series, I will build a sample application (client and server) and use Nginx with HAProxy to proxy the requests to their intended servers and also dynamically balance the requests when we add or remove servers from the cluster.

What is Docker?

Docker is an open-source software that enables you to automate the deployment of any application into software containers. Containers, unlinke virtual machines, share the operating system on which they are running. This means that containers are much more efficient in using system resources resulting in more instances of your application running on the same hardware.

Prerequisites

  1. Install Docker with brew install docker if you are on a Mac or use your OS intaller from https://www.docker.com/community-edition#/download.
  2. Make sure you have NPM installed on your system.
  3. Install AngularCLI by running npm install -g @angular/cli.

Creating the Angular application.

We will use the Angular CLI to generate a sample Angular app:

  • Create a new directory for your project: mkdir ng-2-docker
  • Generate a new angular app. I will name it client: cd ng-2-docker ng new client
  • Start the development server by running ng serve
  • Open your browser and navigate to http://localhost:4200

If you see the message “app works!” you are good to go.

“Dockerizing” the client application.

We begin by creating a Dockerfile inside the client application folder. This file is like a blueprint for the docker container. We will create a new image from the base nodejs 7 image, copy all the application source files into our image, install de dependencies and then run the application.

ng-2-docker/client/Dockerfile

#  Create a new image from the base nodejs 7 image.
FROM node:7
# Create the target directory in the imahge
RUN mkdir -p /usr/src/app
# Set the created directory as the working directory
WORKDIR /usr/src/app
# Copy the package.json inside the working directory
COPY package.json /usr/src/app
# Install required dependencies
RUN npm install
# Copy the client application source files. You can use .dockerignore to exlcude files. Works just as .gitignore does.
COPY . /usr/src/app
# Open port 4200. This is the port that our development server uses
EXPOSE 4200
# Start the application. This is the same as running ng serve.
CMD ["npm", "start"]

Before building our image we just need to change one thing. By default, the webpack-dev-server is not accessible from other hosts. In order to make it available we need to add a parameter into our package.json file.

ng-2-docker/client/package.json

From this:

...
"scripts": {
    "ng": "ng",
    "start": "ng serve",
    "build": "ng build",
    "test": "ng test",
    "lint": "ng lint",
    "e2e": "ng e2e"
  },
...

Into this:

...
"scripts": {
    "ng": "ng",
    "start": "ng serve -H 0.0.0.0",
    "build": "ng build",
    "test": "ng test",
    "lint": "ng lint",
    "e2e": "ng e2e"
  },
...

Now we need to build our image. Make sure you are in the client directory and then run:

docker build -t ng-2-docker/client .

This will build our custom nodejs image that will run our Angular client application.
In order to test our image we need to deploy it in a container: docker run --rm -p 80:4200 ng-2-docker/client

  • –rm parameter will immediately remove the container when it stops.
  • -p parameter maps the container’s 4200 port to port 80 on your local machine.
  • The last part of the command it’s the image that we’ve just built.

We can test our application by opening http://localhost in your browser.
If you see the message “app works!” then you are successfully running your Angular application inside d docker container. You can also run docker ps and you should see one running container.

Putting it all together with Docker Compose

Mapping container’s port to local machine’s port it’s ok for what we need but in a real production environment you would most probably use Nginx to reverse proxy the requests to your application server/s. When a request comes on port 80 in your Nginx server, it will be forwarded to port 4200 into your application server (webpack-dev-server in our example). In order to be able to easily orchestrate multiple images and containers we are going to use docker-compose. This utility comes pre-installed with Docker.

First, we are going to create our Nginx image. We will start from a base Nginx image and just add our own default configuration to proxy the requests to our application server.

  • Create new folder named nginx in the root folder of our project: mkdir nginx
  • Into this new folder create 2 files: Dockerfile and default.conf

ng-2-docker/nginx/default.conf

server {
    location / {
            proxy_set_header Host $host;
            proxy_set_header X-Real-IP $remote_addr;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header X-Forwarded-Proto $scheme;
            proxy_pass http://client:4200/;
    }
}

The config above will instruct Nginx (which will run in a separate container) to proxy all request coming on / to the angular client application running in another container on port 4200.

Now for the Dockerfile:

ng-2-docker/nginx/Dockerfile

#  Create a new image from the base nginx image.
FROM nginx
# Overwrite nginx's default configuration file with our own.
COPY default.conf /etc/nginx/conf.d/

Now, int root of the project create a new file called docker-compose.yml

ng-2-docker/docker-compose.yml

version: '2'

services:

  # Build the container using the client Dockerfile
  client:
      build: ./client

  # Build the container using the nginx Dockerfile
  nginx:
    build: ./nginx
    # Map Nginx port 80 to the local machine's port 80
    ports:
      - "80:80"
    # Link the client container so that Nginx will have access to it
    links:
      - client

Now in the root folder run docker-compose up -d --build --remove-orphans and everything should magically work. Test it at http://localhost.

Useful docker-compose commands:

  • docker-compose ps list running containers
  • docker-compose stop stops our comntainers
  • docker-compose start starts our containers
  • docker-compose up -d --build --remove-orphans re-builds the containers. Useful if you modify any configuration or source file
  • docker-compose logs brings up the container logs

Editing code without container re-build?

This is all fine and dandy but it’s a bit of a headache to re-build the containers everytime you modify a css file. In order to map the client container’s code We just need to add a line of code into our docker-compose.yml file.

ng-2-docker/docker-compose.yml

...
  # Build the container using the client Dockerfile
  client:
      build: ./client
  # This line maps the contents of the client folder into the container.
      volumes:
        - ./client:/usr/src/app
...

In order to test our changes run:

  • docker-compose up -d --build --remove-orphans to re-build the image
  • Open your browser at http://localhost. You should see app works!
  • Edit ng-2-docker/client/src/app/app.component.ts and change the title value to “app works with Docker!”
  • Refresh your browser and see the magic happening.

What’s next?

In the next post we will create an API server with Express and MongoDB and connect our client application to it.

P.S: The code is available here

Using ts-serializer to serialize and deserialize JSON Objects

Serializing?

Serialization is the process of converting complex objects into a data format that can be easily stored or sent across a network connection. In JavaScript, serialization and deserialization of objects can be achieved by using JSON.stringify() and JSON.parse().

Example

 // Let's say you have a simple json response from your server.
 var jsonResponse = "{firstName:\"John\", lastName:\"Doe\"}";

 // If you want to deserialize this object, you can use JSON.parse().
 var jsonParsed = JSON.parse(jsonResponse);

 // An object with the correct properties will be returned
 console.log(jsonParsed.firstName); // Prints 'John'
 console.log(jsonParsed.lastName); // Prints 'Doe'

 // If you want to serialize the object back into a string represantation, you can use JSON.stringify()
 var serializedJson = JSON.stringify(parsedJson);
 console.log(serializedJson); // Prints '{firstName:"John", lastName:"Doe"}'

The Problem?

Things start to get complicated when you are using TypeScript or ES6 and the response from the server doesn’t really match your client data structure. In this case you have an extra step of copying the properties from the parsed json response into your custom model object. When you want to send the data back to the server you have to copy the properties again into their original format.

Example

 // The response from the server
 let response:string = "{first_name:\"John\", last_name:\"Doe\"}";

 // Your model class
 class UserProfile {
     firstName:string;
     lastName:string;
 }

 let jsonParsed = JSON.parse(response);

 var userProfile = new UserProfile();
 userProfile.firstName = jsonParsed.first_name;
 userProfile.lastName = jsonParsed.last_name;

 // When you want to send the data back to the server you have to do the same things as above but in reverse.
 let dataToSend = {
     first_name: userProfile.firstName,
     last_name: userProfile.lastName
 };

 let dataAsString = JSON.stringify(dataToSend);

 console.log(dataAsString); // Prints {first_name:"John", last_name:"Doe"}

 // It's easy to see that when you have lots of properties this gets very messy, very quickly

Solution? Introducing TS Serializer

Some time ago I have started using TypeScript for most of my projects. One of those projects had a very different data structure between the server and the client. After getting very frustated with writing serialization and deserialization methods for my data models, I came up with the ideea of ts-serializer. ts-serializer is a collection of typescript decorators and helper classes that allows the developer to easily serialize and deserialize complex objects to and from JSON objects.

Installation

Using NPM

npm install --save ts-serializer

Build from Git

git clone https://github.com/dpopescu/ts-serializer.git
cd ts-serializer
npm install
npm run build

The library will be in the dist folder

Usage

You start by importing the library decorators and the Serializable abstract class

 import {Serialize, SerializeProperty, Serializable} from 'ts-serializer';

In order to mark a class as serializable, you need to use the Serialize decorator and extend the abstract Serializable class.

 @Serialize({})
 class Profile extends Serializable {
 }

The Serialize decorator implements in the target class the serialize and deserialize methods required by the Serializable class.

By default, the library does not serialize class properties if are not marked for serialization. In order to declare a property as serializable you use the SerializeProperty decorator.

 @Serialize({})
 class Profile extends Serializable {
     @SerializeProperty({})
     firstName:string;
     @SerializeProperty({})
     lastName:string;
 }

After the class and the class properties are marked as serializable, you can use the serialize and deserialize methods and ts-serializer will take care of things for you.

Full Example

import {Serialize, SerializeProperty, Serializable} from 'ts-serializer';

@Serialize({})
 class User extends Serializable {
     @SerializeProperty({
        map: 'first_name'
     })
     firstName:string;
     @SerializeProperty({
        map: 'last_name'
     })
     lastName:string;
 }

@Serialize({})
 class Profile extends Serializable {
     @SerializeProperty({
        type: User
     })
     user: User;
 }

 let data = {
    user: {
        first_name: 'John',
        last_name: 'Doe'
    }
 };

 let instance:Profile = new Profile();
 instance.deserialize(data);

 console.log(instance.user.firstName); // Prints 'John'
 console.log(instance.user.lastName); // Prints 'Doe'

 console.log(instance.serialize()); // Prints {"user":{"first_name":"John", "last_name":"Doe"}}

 console.log(instance.user.serialize()); // Prints {"first_name":"John", "last_name":"Doe"}

For more information about the library check out serializer.dpopescu.me and ts-serializer Github page

Catching global errors in Angular 2

Angular 2 already has a very good error handler. When an error randomly occurs in your code, the Angular’s error handler will catch it and will print the error details in the console. The error details will also include the line number with a link to the source file. In most cases this should be more then enough to help you understand what is happening in your application.

Why would I need a custom error handler?

You can use a custom error handler to format the error messages that are logged into the browser’s console, to catch custom business errors in your application (Authentication/Authorization errors, HTTP 404, etc.) or maybe you want to also send the errors to you backend server for analytics or other reasons. All of the above are valid use cases of using a custom error handler.

Creating a custom error handler

Writing your own error handler is straightforward. You will need to extend Angular’s ErrorHandler class and override the handleError method. This method receives a wrapper of the original error as a parameter. You can find the original error in the error.originalError property. The default implementation uses console.error() to print the error details in the browser’s console.

CustomErrorHandler.ts

import {ErrorHandler} from '@angular/core';

export class CustomErrorHandler extends ErrorHandler {
    constructor(){
        super(false);
    }

    public handleError(error: any): void {
        // You can add your own logic here.
        // It is not required to delegate to the original implementation
        super.handleError(error);
    }
}

Extending Angular’s Error Handler

If you want to use your own custom handler you will need to somehow replace the one that Angular is using. Fortunately enough, Angular’s awesome DI engine will allows you to provide custom implementations for different classes.

AppModule.ts:

import {BrowserModule} from '@angular/platform-browser';
import {ErrorHandler} from '@angular/core';
import {AppComponent} from './app.component';

import {CustomErrorHandler} from './CustomErrorHandler';

@NgModule({
    declarations: [ AppComponent ],
    imports: [ BrowserModule ],
    bootstrap: [ AppComponent ],
    providers: [
        {provide: ErrorHandler, useClass: CustomErrorHandler}
    ]
})
export class AppModule {}

In the code above take a look at the providers field in the @NGModule decorator. With the above configuration in place, every time Angular’s DI engine will request an instance of ErrorHandler will receive an instance of our custom implementation CustomErrorHandler.

Creating custom error classes

Sometimes it’s useful to create custom error classes that you can throw in different parts of your application. For example, when the user is doesn’t have access to a specific part of the application you can throw a custom AuthorizationError.

Creating the custom error class

AuthorizationError.ts:

export class AuthorizationError {
    toString() {
        return 'You are not authorized to view this content!!!';
    }
}

Updating the CustomErrorHandler class

CustomErrorHandler.ts:

import {ErrorHandler} from '@angular/core';
import {AuthorizationError} from './AuthorizationError';

export class CustomErrorHandler extends ErrorHandler {
    constructor(){
        super(false);
    }

    public handleError(error: any): void {
        if(error.originalError instanceof AuthorizationError){
            console.info(`[CUSTOM ERROR]:::${error.originalError.toString()}`);
        } else {
            super.handleError(error);
        }
    }
}

Using the new error in your code

app.component.html:

<button (click)="throwCustomError()">Throw Authorization Error</button>

app.component.ts:

import {Component} from '@angular/core';
import {AuthorizationError} from './AuthorizationError';

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
  styleUrls: ['./app.component.css']
})
export class AppComponent {
  throwCustomError() {
    throw new AuthorizationError();
  }
}

Now when you press the Throw Authorization Error button you will see our custom error logging in the browser’s console:

[CUSTOM ERROR]:::You are not authorized to view this content!!!

If you look closely at the CustomErrorHandler class, everything that is not of type AuthorizationError will be delegated to the original Angular’s ErrorHandler.

Using HTTP Interceptors in Angular 2

What are HTTP Interceptors?

In Angular 1.x there was an option to register objects as HTTP Interceptors. You could then use those interceptors to perform different operations and transformations on all HTTP calls made by your application. This was a very powerful feature of the framework because not only allowed setting things like base path for the REST API endpoint, CSRF headers and many other things but also transforming or caching responses from the server.

So what’s different in Angular 2?

Well, after looking at the documentation you won’t be able to find any reference to interceptors in the new version of the framework. At least for now, interceptors are not currently supported out of the box. You could just use the classic way of doing things and just extend the HTTP class in Angular 2 but that’s not very pretty.

Introducing the XHRBackend

Angular 2 uses this class to create all HTTP connections. By taking advantage of the Angular’s great DI engine you could potentially extend the base XHRBackend class and provide our custom implementation to the application. By taking control of the creation of the HTTP connections you will be able to implement the classic Angular interceptors this way.

Let’s look at some code

Let’s start by creating our own XHRBackend.

MyXHRBackend.ts

import {XHRBackend, Request, XHRConnection, Response} from '@angular/http';
import {Observable} from 'rxjs';
import 'rxjs/add/operator/catch';
import 'rxjs/add/observable/throw';

export class MyXHRBackend extends XHRBackend {

  createConnection(request: Request): XHRConnection {
    let connection: XHRConnection = super.createConnection(request);
    // Before returning the connection we try to catch all possible errors(4XX,5XX and so on)
    connection.response = connection.response.catch(this.processResponse);
    return connection;
  }

  processResponse(response:Response){
    switch (response.status) {
      case 401:
        // You could redirect to login page here
        return Observable.throw('your custom error here');
      case 403:
        // You could redirect to forbidden page here
        return Observable.throw('your custom error here');
      case 404:
        // You could redirect to 404 page here
        return Observable.throw('your custom error here');
      default:
        return Observable.throw(response);
    }
  }

}

The above XHRBackend extension will catch all 401, 403 and 404 errors.
In order to tell Angular to use our implementation instead of the default class we will use Angular’s great DI features. We just need to add our custom class to the providers list in the application main module.

AppModule.ts

import {NgbModule} from '@ng-bootstrap/ng-bootstrap';
import {HttpModule, XHRBackend} from '@angular/http';
import {AppComponent} from './app.component';
import {MyXHRBackend} from './MyXHRBackend';

@NgModule({
  declarations: [
    AppComponent
  ],
  imports: [
    HttpModule
  ],
  providers: [
    {provide: XHRBackend, useClass: MyXHRBackend}
  ],
  bootstrap: [AppComponent]
})
export class AppModule {
}

By providing our custom implementation of the XHRBackend, Angular’s HTTP class will use this implementation for all http calls. This means that if any http call encounters 401, 403 or 404 errors we can act accordingly in our application.

Dynamic loading of AngularJS components

Last week, I had the opportunity to speak about dynamic loading AngularJS modules and how can you achieve that using Webpack’s require.ensure method. The code and slides for the presentation can be found here. In the presentation I’ve only described how can you dynamically register router states. The basic ideea is to have some sort of mechanism to load application modules on demand and once they’re loaded, to register those new angular components in the main application in order to use them. Unfortunately, Angular register’s all of it’s components in the configuration phase so if you try to register a new directive or service after the configuration phase has ended, the component won’t be available for Angular to use.

Let’s take this simple example:

<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8">
        <!-- Include your required JS files here -->
        <!-- I'm using Webpack so everything is automatically included for me -->
        <title>Angular modular test app</title>
    </head>
<body>
    <!-- Use our application directive -->
    <app></app>
</body>
</html>
/**
* Create a test app.
*/
var app = angular.module('test', []);

/**
* Create an application directive
* I'm using the new Angular 1.5 syntax for components.
*/
app.component('app', {
    controller: function(){
        this.showNewDirective = false;

        // We only show the new directive after a button press.
        this.loadDirective = function(){
        this.showNewDirective = true;
        };
    },
    // In the directive template we are using an undefined directive "new-directive".
    template: '<button ng-click="$ctrl.loadDirective()" ng-if="!$ctrl.showNewDirective">Load new directive</button>
    ' +
    '<new-directive ng-if="$ctrl.showNewDirective">New directive not loaded</new-directive>'
});

The application looks like this:
Screen Shot 2016-02-29 at 12.25.57 PM
Once we press the button we will see the default “New directive not loaded” text because our “<new-directive>” was not yet defined.
Screen Shot 2016-02-29 at 12.25.45 PM

Now let’s modify our code to register the “<new-directive>” when we press the button.

app.component('app', {
    controller: function () {
        this.showNewDirective = false;

        // We only show the new directive after a button press.
        this.loadDirective = function () {
            // Register the new directive before showing it
            app.component('newDirective', {
                controller: function () {

                },
                template: '
<h1>New directive is here</h1>
'
                });
            this.showNewDirective = true;
        };
    },
    // In the directive template we are using an undefined directive "new-directive".
    template: '<button ng-click="$ctrl.loadDirective()" ng-if="!$ctrl.showNewDirective">Load new directive</button>
    ' +
    '<new-directive ng-if="$ctrl.showNewDirective">New directive not loaded</new-directive>'
});

Once you click the button again, you would expect that the new directive is showed because we registered it before we showed it. The actual result is this:

Screen Shot 2016-02-29 at 12.25.45 PM

This happens because once the config phase has ended, angular’s component method doesn’t use the same $compileProvider to register new components. With just this little piece of code added to the “App.js” file:

app.config(function ($compileProvider) {
    // Save the original $compileProvider to use it for dynamic registering
    app.component = function(name, object) {
        $compileProvider.component(name, object);
    return (this);
    };
});

If we press the button now we should see this:
Screen Shot 2016-02-29 at 3.44.58 PM

If we want this to work for all Angular’s components we need to change our config method into this:

app.config(function ($controllerProvider, $provide, $compileProvider, $filterProvider) {
    // Register directives handler
    app.component = function(name, object) {
        $compileProvider.component(name, object);
    return (this);
    };
    // Register controller handler
    app.controller = function( name, constructor ) {
        $controllerProvider.register( name, constructor );
    return( this );
    };
    // Register services handlers
    app.service = function( name, constructor ) {
        $provide.service( name, constructor );
    return( this );
    };
    app.factory = function( name, factory ) {
        $provide.factory( name, factory );
    return( this );
    };
    // Register filters handler
    app.filter = function( name, factory ) {
        $filterProvider.register( name, factory );
    return( this );
    };
});

Now you have a way to lazy load angular modules. Please don’t make your users download 5MB of javascript if they’re only going to use 2MB. Application modules like Admin, Settings, Profile, etc. should be loaded on demand.

Implementing a modern JS Logger

I  my last post I’ve talked about using ES decorators in your Js code. This time, I’ll try and implement a fairly simple Js Logger using class and method decorators. The idea is to have a decorator that logs something to the console every time a method is called without having to add the logging code in the method itself.

Let’s start by creating a class that will be used to test our logger.

class Person {
    constructor(name = 'Bob', age = 28){
        this._name = name;
        this._age = age;
    }

    set name(value){
        this._name = value;
    }

    setAge(value){
        this._age = value;
    }
}

Decorators are not allowed on class constructors so if we want to log something every time a new instance of Person is created, we need to decorate the class and wrap the constructor with our custom code.

Let’s create the Log decorator.

function Log(target) {

    // Create a wrapper over original constructor
    const LoggerWrapper = function () {
        // Log something every time a new instance is created
        console.log('A new instance was created');

        // Call the original constructor
        target.apply(this, arguments);
    };

    // Copy the original prototype and constructor function to the new one.
    LoggerWrapper.prototype = Object.create(target.prototype);
    LoggerWrapper.prototype.constructor = target;

    // Return the new constructor.
    return LoggerWrapper;
}

Now if we use the Log decorator on Person class we should see something in the console every time a new instance is created.

@Log
class Person {
    constructor(name = 'Bob', age = 28) {
        this._name = name;
        this._age = age;
    }

    set name(value) {
        this._name = value;
    }

    setAge(value) {
        this._age = value;
    }
}

const firstPerson = new Person(); // A new instance was created
const secondPerson = new Person(); // A new instance was created

So far, so good but this logger is not very useful if we cannot set our custom message. In order to do that, we need to modify our Log decorator to return a function instead of the target class.

function Log(message) {
    return function(target){
        // Create a wrapper over original constructor
        const LoggerWrapper = function () {
            // Log something every time a new instance is created
            console.log(message);

            // Call the original constructor
            target.apply(this, arguments);
        };

        // Copy the original prototype and constructor function to the new one.
        LoggerWrapper.prototype = Object.create(target.prototype);
        LoggerWrapper.prototype.constructor = target;

        // Return the new constructor.
        return LoggerWrapper;
    }
}

Now we can update our Person class to use the new decorator.

@Log('A new instance was created')
class Person {
    constructor(name = 'Bob', age = 28) {
        this._name = name;
        this._age = age;
    }

    set name(value) {
        this._name = value;
    }

    setAge(value) {
        this._age = value;
    }
}

const person = new Person(); // A new instance was created

Everything works exactly like before but now we can specify what message we want to log.

Now that we have this in place, we can replace our console.log with a Logger class and we should also add a logging level parameter.

We start by creating a LogLevel class.

class LogLevel {
    static DEBUG = 0;
    static INFO = 1;
    static WARN = 2;
    static ERROR = 3;
}

A Logger class.

class Logger {
    static log(message, logLevel = LogLevel.INFO) {
        // Use different console methods based on the supplied logLevel. Default is INFO.
        switch (logLevel) {
            case LogLevel.DEBUG:
                console.log(Logger.getFormattedMessage(message));
                break;
            case LogLevel.INFO:
                console.info(Logger.getFormattedMessage(message));
                break;
            case LogLevel.WARN:
                console.warn(Logger.getFormattedMessage(message));
                break;
            case LogLevel.ERROR:
                console.error(Logger.getFormattedMessage(message));
                break;
        }
    }

    // Add the time to the message
    static getFormattedMessage(message) {
        return `[${new Date().toJSON()}] - ${message}`;
    }
}

And finally we update the Log decorator to add the logging level and use our new Logger class.

function Log(message, logLevel) {
    return function(target){
        // Create a wrapper over original constructor
        const LoggerWrapper = function () {
            // Log something every time a new instance is created
            Logger.log(message, logLevel);

            // Call the original constructor
            target.apply(this, arguments);
        };

        // Copy the original prototype and constructor function to the new one.
        LoggerWrapper.prototype = Object.create(target.prototype);
        LoggerWrapper.prototype.constructor = target;

        // Return the new constructor.
        return LoggerWrapper;
    }
}

Now the output should be something like this:

[2016-02-04T16:10:10.795Z] - A new instance was created

Much better isn’t it? The only problem with using console.log to log stuff is that the browser console will tell you that the “logging” happened in Logger.js file (were the console.log is actually called) and not your class constructor. We can easily fix this by also logging the class name.

We need to update the Logger to accept a target parameter.

class Logger {
    static log(message, logLevel = LogLevel.INFO, target) {
        // Use different console methods based on the supplied logLevel. Default is INFO.
        switch (logLevel) {
            case LogLevel.DEBUG:
                console.log(Logger.getFormattedMessage(message, target));
                break;
            case LogLevel.INFO:
                console.info(Logger.getFormattedMessage(message, target));
                break;
            case LogLevel.WARN:
                console.warn(Logger.getFormattedMessage(message, target));
                break;
            case LogLevel.ERROR:
                console.error(Logger.getFormattedMessage(message, target));
                break;
        }
    }

    // Add the time to the message
    static getFormattedMessage(message, target) {
        return `[${new Date().toJSON()}][${target.name}] - ${message}`;
    }
}

and the Log decorator to send that target.

function Log(message, logLevel) {
    return function(target){
        // Create a wrapper over original constructor
        const LoggerWrapper = function () {
            // Log something every time a new instance is created
            Logger.log(message, logLevel, this.constructor);

            // Call the original constructor
            target.apply(this, arguments);
        };

        // Copy the original prototype and constructor function to the new one.
        LoggerWrapper.prototype = Object.create(target.prototype);
        LoggerWrapper.prototype.constructor = target;

        // Return the new constructor.
        return LoggerWrapper;
    }
}

After this our output will be (notice that the class name is now present in the log):

[2016-02-04T16:23:47.321Z][Person] - A new instance was created

All good for now but what if we want to use this decorator to also log something when a class method is called? In order to do this, we need to modifyour Log decorator because a method decorator needs to return the method/property descriptor and not a constructor function.

function Log(message, logLevel) {
    return function () {
        const [target, name, descriptor] = arguments;

        if (!descriptor) {
            // Create a wrapper over original constructor
            const LoggerWrapper = function () {
                // Log something every time a new instance is created
                Logger.log(message, logLevel, this.constructor);

                // Call the original constructor
                target.apply(this, arguments);
            };

            // Copy the original prototype and constructor function to the new one.
            LoggerWrapper.prototype = Object.create(target.prototype);
            LoggerWrapper.prototype.constructor = target;

            // Return the new constructor.
            return LoggerWrapper;
        }
        else {
            // If the annotated method is not a setter or getter
            if (descriptor.value) {
                // save the original method
                const method = descriptor.value;
                // and wrap it with our custom code
                descriptor.value = function (value) {
                    Logger.log(message, logLevel, target.constructor);
                    method.call(this, value);
                };
            }
            return descriptor;
        }
    }
}

Now we can use our awesome decorator on methods also.

@Log('A new instance was created')
class Person {
    constructor(name = 'Bob', age = 28) {
        this._name = name;
        this._age = age;
    }

    set name(value) {
        this._name = value;
    }

    @Log('A new age was set')
    setAge(value) {
        this._age = value;
    }
}

const person = new Person(); // [2016-02-04T16:37:14.109Z][Person] - A new instance was created
person.setAge(20); // [2016-02-04T16:37:14.110Z][Person] - A new age was set

This decorator can be extended further to automatically log the parameters passed to the constructor/method and maybe also print the method name in the logs. This can be done easily because we can use the arguments in the wrapped functions. Do you have any other improvement ideas?

P.S: Try to update the decorator to work with setters also 😛 It needs just a small change.

Practical ES7 decorators

1ifm00n-npudywtdbzag3rq

Decorators, a.k.a annotations, are a new feature coming in ES7. A decorator is basically an expression that evaluates to a function, takes the target object as a parameter and returns the modified object. Decorators are very similar to Annotations in Java, but unlike Java annotations, decorators are applied at runtime.

If you are reading this and your background is Python or Java, you may begin to imagine what decorators are good at but for the rest of you here are some nice examples:

Class decorators

// We begin by declaring the decorator.
function SimpleDecorator(targetClass){
    // We define a new static property
    targetClass.decorated = true;
    // And a new instance property;
    targetClass.prototype.alsoDecorated = true;
    return targetClass;
}

// Applying the decorator is very easy
@SimpleDecorator
class SimpleClass {

}

const instance = new SimpleClass();

console.log(SimpleClass.decorated); // -> true
console.log(instance.alsoDecorated); // -> true

Pretty easy right? A class decorator allows as to “decorate” a class with both static and instance properties or methods.The decorator takes the class in question as a parameter and returns it after it makes all the necesary modifications to it.

A decorator can also take additional parameters.

// If we want to set additional parameters, our decorator must return a function.
function SetClassId(classId){
    return function(targetClass){
        targetClass.prototype.classId = classId;
        return targetClass;
    };
}

// Pass a random value from 0 to 999 as a class id
@SetClassId(parseInt(Math.random()*999))
class SimpleClass {

}

// As you can see all instances got the same value.
// That's because the decorator is executed once on class definition.
console.log(new SimpleClass().classId); // -> 754
console.log(new SimpleClass().classId); // -> 754
console.log(new SimpleClass().classId); // -> 754

Let’s try to implement a Singleton decorator. The decorator will add a static getInstance() method that will return the same class instance every time it’s called.

// Decorator definition
function Singleton(targetClass) {
    // We will hold the instance reference in a Symbol.
    // A Symbol is a unique, immutable property of an object introduced in ES6.
    const instance = Symbol('__instance__');
    // We define the static method for retrieving the instance.
    targetClass.getInstance = function () {
        // If no instance has been created yet, we create one
        if (!targetClass[instance]) {
            targetClass[instance] = new targetClass();
        }
        // Return the saved instance.
        return targetClass[instance];
    };

    return targetClass;
}

@Singleton
class Counter {
    constructor() {
        this._count = 0;
    }

    increment() {
        this._count++;
    }

    get count() {
        return this._count;
    }
}
// Get two different references of the Counter instance.
const a = Counter.getInstance();
const b = Counter.getInstance();

console.log(a.count); // -> 0
a.increment();
// because a and b point to the same instance of Counter, b.count is also incremented.
console.log(b.count); // -> 1

Method decorators

Decorators will work on class methods also. If the decorator function took just one parameter when decorating a class, when decorating a method the parameter list changes a bit. The function will take three parameters when decorating a method.

  1. Class instance reference.
  2. Method name.
  3. Object property descriptor.

Formatting data using method decorators:

// Method decorators take three parameters
function Format(target, name, descriptor){
    // Keep a reference to the original getter
    const getter = descriptor.get;
    descriptor.get = function(){
        // Call the original getter and return the modified result.
        return getter.call(this).toUpperCase();
    };
    return descriptor;
}

class Person {
    constructor(name){
        this._name = name;
    }

    @Format
    get name(){
        return this._name;
    }
}

const dude = new Person('bob');

console.log(dude.name); // -> BOB

Validating data using method decorators:

// Method decorators take three parameters
function Format(target, name, descriptor){
    // Keep a reference to the original getter
    const getter = descriptor.get;
    descriptor.get = function(){
        // Call the original getter and return the modified result.
        return getter.call(this).toUpperCase();
    };
    return descriptor;
}

function Validate(target, name, descriptor) {
    // Keep a reference to the original setter
    const setter = descriptor.set;
    descriptor.set = function (value) {
        // If the provided value is invalid throw an error
        if (value < 0) {
            console.log('Value must be positive');
        } else {
            setter.call(this, value);
        }
    };
    return descriptor;
}

class Person {
    constructor(name) {
        this._name = name;
    }

    @Format     
    get name() {
        return this._name;
    }

    @Validate     
    set age(value) {
        this._age = value;
    }
}

const dude = new Person('bob');

console.log(dude.name); // -> BOB
dude.age = -10; // -> Value must be positive

Closing thoughts

Although no browser supports these features yet, you can still use them in your production code. For transpiling ES6 code into ES5, I recommend Babel. Combine this with Webpack and you’ll get yourself a state of the art building and developing environment.

P.S: In order to transpile decorators with Babel, you’ll need to use stage-1 preset.

P.P.S: Babel 6 doesn’t support decorators yet. You have 2 workarounds:

  1. Use Babel 5.
  2. Use Babel 6 with babel-plugin-transform-decorators-legacy plugin.

That’s it. Go build something awesome.