What are "decorators" and how are they used?

I'm curious what exactly decorators are in AngularJS. There isn't much information online for decorators save for a blurb in the AngularJS documentation and a brief (albeit interesting) mention in a youtube video.

As the Angular guys put it a decorator is:

> Decoration of service, allows the decorator to intercept the service > instance creation. The returned instance may be the original instance, > or a new instance which delegates to the original instance.

I don't really know what that means, and I'm not sure why you would separate this logic from the service itself. For example if I wanted to return something different under different conditions I would just pass different arguments to the relevant functions or use another function sharing that private state.

I'm still kind of an AngularJS noob so I'm sure it's just ignorance and/or bad habits I've picked up.

A good use case of $provide.decorator is when you need to do minor "tweak" on some third-party/upstream service, on which your module depends, while leaving the service intact (because you are not the owner/maintainer of the service). Here is a demonstration on plunkr.

Decorators allow us to separate out cross-cutting concerns and allow services to preserve the single-responsibility-principle without worrying about "infrastructure" code.

Practical uses of decorators:

• Caching: if we have a service which makes potentially expensive HTTP calls, we can wrap the service in a caching decorator which checks local storage before making the external call.
• Debugging/Tracing: have a switch depending on your development/production configuration which decorates your services with debugging or tracing wrappers.
• Throttling : wrap frequently triggered calls in a debouncing wrapper. Allows us to easily interact with rate-limited services, for example.

In all these cases, we limit the code in the service to its main responsibility.

decorator can intercept service instance created by factory, service, value, provider, and gives the options to change some instance(service) that is otherwise not configurable / with options.

It can also provide mock up instances for testing purpose, for example $http.

In simple word we can say that it’s like an extension method. For Ex. We have a class and it has two methods and at run time we want to add more method in it then we use Decorator.

We cannot use $provide.decorator with constants because we cannot change the constants they are heaving read only property.

In short decorators can be described as follows :-

> A decorator function intercepts the creation of a service, allowing it > to override or modify the behavior of the service.

It uses the $provide service by angular and modify or replaces the implementation of another service

$provide.decorator('service to decorate',['$delegate', function($delegate) {
  // $delegate - The original service instance, 
  //             which can be replaced, monkey patched, 
  //             configured, decorated or delegated to. 
  //             ie here what is there in the 'service to decorate'
 
  //   This function will be invoked, 
  //   when the service needs to be provided 
  //   and should return the decorated service instance.
  return $delegate;
}]);

Example:

$provide.decorator('$log', ['$delegate', function($delegate) {
  // This will change implementation of log.war to log.error
  $delegate.warn = $delegate.error; 
  return $delegate;
}]);

Applications

In addition to @JBland answer.

• Application wide locale settings :-

You can find an example here

• Changiging default behaviour of and existing implementation of a service by angular service :-

  You can find an eample here

• Switching behavior of a function in different environments.