Improve this DocDecorators in AngularJS

What are decorators?

Decorators are a design pattern that is used to separate modification or decoration of a class without modifying the original source code. In AngularJS, decorators are functions that allow a service, directive or filter to be modified prior to its usage.

How to use decorators

There are two ways to register decorators

• $provide.decorator, and
• module.decorator

Each provide access to a $delegate, which is the instantiated service/directive/filter, prior to being passed to the service that required it.

$provide.decorator

The decorator function allows access to a $delegate of the service once it has been instantiated. For example:

angular.module('myApp', [])

.config([ '$provide', function($provide) {

  $provide.decorator('$log', [
    '$delegate',
    function $logDecorator($delegate) {

      var originalWarn = $delegate.warn;
      $delegate.warn = function decoratedWarn(msg) {
        msg = 'Decorated Warn: ' + msg;
        originalWarn.apply($delegate, arguments);
      };

      return $delegate;
    }
  ]);
}]);

After the $log service has been instantiated the decorator is fired. The decorator function has a $delegate object injected to provide access to the service that matches the selector in the decorator. This $delegate will be the service you are decorating. The return value of the function provided to the decorator will take place of the service, directive, or filter being decorated.

The $delegate may be either modified or completely replaced. Given a service myService with a method someFn, the following could all be viable solutions:

Completely Replace the $delegate

angular.module('myApp', [])

.config([ '$provide', function($provide) {

  $provide.decorator('myService', [
    '$delegate',
    function myServiceDecorator($delegate) {

      var myDecoratedService = {
        // new service object to replace myService
      };
      return myDecoratedService;
    }
  ]);
}]);

Patch the $delegate

angular.module('myApp', [])

.config([ '$provide', function($provide) {

  $provide.decorator('myService', [
    '$delegate',
    function myServiceDecorator($delegate) {

      var someFn = $delegate.someFn;

      function aNewFn() {
        // new service function
        someFn.apply($delegate, arguments);
      }

      $delegate.someFn = aNewFn;
      return $delegate;
    }
  ]);
}]);

Augment the $delegate

angular.module('myApp', [])

.config([ '$provide', function($provide) {

  $provide.decorator('myService', [
    '$delegate',
    function myServiceDecorator($delegate) {

      function helperFn() {
        // an additional fn to add to the service
      }

      $delegate.aHelpfulAddition = helperFn;
      return $delegate;
    }
  ]);
}]);

Decorators have different rules for different services. This is because services are registered in different ways. Services are selected by name, however filters and directives are selected by appending "Filter" or "Directive" to the end of the name. The $delegate provided is dictated by the type of service.

1. Multiple directives may be registered to the same selector/name

module.decorator

This function is the same as the $provide.decorator function except it is exposed through the module API. This allows you to separate your decorator patterns from your module config blocks.

Like with $provide.decorator, the module.decorator function runs during the config phase of the app. That means you can define a module.decorator before the decorated service is defined.

Since you can apply multiple decorators, it is noteworthy that decorator application always follows order of declaration:

• If a service is decorated by both $provide.decorator and module.decorator, the decorators are applied in order:

angular
.module('theApp', [])
.factory('theFactory', theFactoryFn)
.config(function($provide) {
  $provide.decorator('theFactory', provideDecoratorFn); // runs first
})
.decorator('theFactory', moduleDecoratorFn); // runs seconds

• If the service has been declared multiple times, a decorator will decorate the service that has been declared last:

angular
  .module('theApp', [])
  .factory('theFactory', theFactoryFn)
  .decorator('theFactory', moduleDecoratorFn)
  .factory('theFactory', theOtherFactoryFn);

// `theOtherFactoryFn` is selected as 'theFactory' provider and it is decorated via `moduleDecoratorFn`.

Example Applications

The following sections provide examples each of a service decorator, a directive decorator, and a filter decorator.

This example shows how we can replace the $log service with our own to display log messages.

Failed interpolated expressions in ng-href attributes can easily go unnoticed. We can decorate ngHref to warn us of those conditions.

Let's say we have created an app that uses the default format for many of our Date filters. Suddenly requirements have changed (that never happens) and we need all of our default dates to be 'shortDate' instead of 'mediumDate'.