@angular-wave/angular.ts 0.0.6 → 0.0.8

package/src/injector.md

@@ -0,0 +1,740 @@
+/\*\*
+
+- @ngdoc function
+- @module ng
+- @name angular.injector
+- @kind function
+-
+- @description
+- Creates an injector object that can be used for retrieving services as well as for
+- dependency injection (see {@link guide/di dependency injection}).
+-
+- @param {Array.<string|Function>} modules A list of module functions or their aliases. See
+-     {@link angular.module}. The `ng` module must be explicitly added.
+- @param {boolean=} [strictDi=false] Whether the injector should be in strict mode, which
+-     disallows argument name annotation inference.
+- @returns {injector} Injector object. See {@link auto.$injector $injector}.
+-
+- @example
+- Typical usage
+- ```js
+
+  ```
+
+- // create an injector
+- var $injector = angular.injector(['ng']);
+-
+- // use the injector to kick off your application
+- // use the type inference to auto inject arguments, or use implicit injection
+- $injector.invoke(function($rootScope, $compile, $document) {
+-     $compile($document)($rootScope);
+-     $rootScope.$digest();
+- });
+- ```
+
+  ```
+
+-
+- Sometimes you want to get access to the injector of a currently running AngularJS app
+- from outside AngularJS. Perhaps, you want to inject and compile some markup after the
+- application has been bootstrapped. You can do this using the extra `injector()` added
+- to JQuery/jqLite elements. See {@link angular.element}.
+-
+- \*This is fairly rare but could be the case if a third party library is injecting the
+- markup.\*
+-
+- In the following example a new block of HTML containing a `ng-controller`
+- directive is added to the end of the document body by JQuery. We then compile and link
+- it into the current AngularJS scope.
+-
+- ```js
+
+  ```
+
+- var $div = $('<div ng-controller="MyCtrl">{{content.label}}</div>');
+- $(document.body).append($div);
+-
+- angular.element(document).injector().invoke(function($compile) {
+- var scope = angular.element($div).scope();
+- $compile($div)(scope);
+- });
+- ```
+  */
+  ```
+
+/\*\*
+
+- @ngdoc module
+- @name auto
+- @installation
+- @description
+-
+- Implicit module which gets automatically added to each {@link auto.$injector $injector}.
+  \*/
+
+///////////////////////////////////////
+
+/\*\*
+
+- @ngdoc service
+- @name $injector
+-
+- @description
+-
+- `$injector` is used to retrieve object instances as defined by
+- {@link auto.$provide provider}, instantiate types, invoke methods,
+- and load modules.
+-
+- The following always holds true:
+-
+- ```js
+
+  ```
+
+- var $injector = angular.injector();
+- expect($injector.get('$injector')).toBe($injector);
+- expect($injector.invoke(function($injector) {
+-     return $injector;
+- })).toBe($injector);
+- ```
+
+  ```
+
+-
+- ## Injection Function Annotation
+-
+- JavaScript does not have annotations, and annotations are needed for dependency injection. The
+- following are all valid ways of annotating function with injection arguments and are equivalent.
+-
+- ```js
+
+  ```
+
+- // inferred (only works if code not minified/obfuscated)
+- $injector.invoke(function(serviceA){});
+-
+- // annotated
+- function explicit(serviceA) {};
+- explicit.$inject = ['serviceA'];
+- $injector.invoke(explicit);
+-
+- // inline
+- $injector.invoke(['serviceA', function(serviceA){}]);
+- ```
+
+  ```
+
+-
+- ### Inference
+-
+- In JavaScript calling `toString()` on a function returns the function definition. The definition
+- can then be parsed and the function arguments can be extracted. This method of discovering
+- annotations is disallowed when the injector is in strict mode.
+- _NOTE:_ This does not work with minification, and obfuscation tools since these tools change the
+- argument names.
+-
+- ### `$inject` Annotation
+- By adding an `$inject` property onto a function the injection parameters can be specified.
+-
+- ### Inline
+- As an array of injection names, where the last item in the array is the function to call.
+  \*/
+
+/\*\*
+
+- @ngdoc property
+- @name $injector#modules
+- @type {Object}
+- @description
+- A hash containing all the modules that have been loaded into the
+- $injector.
+-
+- You can use this property to find out information about a module via the
+- {@link angular.Module#info `myModule.info(...)`} method.
+-
+- For example:
+-
+- ```
+
+  ```
+
+- var info = $injector.modules['ngAnimate'].info();
+- ```
+
+  ```
+
+-
+- \*\*Do not use this property to attempt to modify the modules after the application
+- has been bootstrapped.\*\*
+  \*/
+
+/\*\*
+
+- @ngdoc method
+- @name $injector#get
+-
+- @description
+- Return an instance of the service.
+-
+- @param {string} name The name of the instance to retrieve.
+- @param {string=} caller An optional string to provide the origin of the function call for error messages.
+- @return {_} The instance.
+  _/
+
+/\*\*
+
+- @ngdoc method
+- @name $injector#invoke
+-
+- @description
+- Invoke the method and supply the method arguments from the `$injector`.
+-
+- @param {Function|Array.<string|Function>} fn The injectable function to invoke. Function parameters are
+- injected according to the {@link guide/di $inject Annotation} rules.
+- @param {Object=} self The `this` for the invoked method.
+- @param {Object=} locals Optional object. If preset then any argument names are read from this
+-                         object first, before the `$injector` is consulted.
+- @returns {_} the value returned by the invoked `fn` function.
+  _/
+
+/\*\*
+
+- @ngdoc method
+- @name $injector#has
+-
+- @description
+- Allows the user to query if the particular service exists.
+-
+- @param {string} name Name of the service to query.
+- @returns {boolean} `true` if injector has given service.
+  \*/
+
+/\*\*
+
+- @ngdoc method
+- @name $injector#instantiate
+- @description
+- Create a new instance of JS type. The method takes a constructor function, invokes the new
+- operator, and supplies all of the arguments to the constructor function as specified by the
+- constructor annotation.
+-
+- @param {Function} Type Annotated constructor function.
+- @param {Object=} locals Optional object. If preset then any argument names are read from this
+- object first, before the `$injector` is consulted.
+- @returns {Object} new instance of `Type`.
+  \*/
+
+/\*\*
+
+- @ngdoc method
+- @name $injector#annotate
+-
+- @description
+- Returns an array of service names which the function is requesting for injection. This API is
+- used by the injector to determine which services need to be injected into the function when the
+- function is invoked. There are three ways in which the function can be annotated with the needed
+- dependencies.
+-
+- #### Argument names
+-
+- The simplest form is to extract the dependencies from the arguments of the function. This is done
+- by converting the function into a string using `toString()` method and extracting the argument
+- names.
+- ```js
+
+  ```
+
+- // Given
+- function MyController($scope, $route) {
+-     // ...
+- }
+-
+- // Then
+- expect(injector.annotate(MyController)).toEqual(['$scope', '$route']);
+- ```
+
+  ```
+
+-
+- You can disallow this method by using strict injection mode.
+-
+- This method does not work with code minification / obfuscation. For this reason the following
+- annotation strategies are supported.
+-
+- #### The `$inject` property
+-
+- If a function has an `$inject` property and its value is an array of strings, then the strings
+- represent names of services to be injected into the function.
+- ```js
+
+  ```
+
+- // Given
+- var MyController = function(obfuscatedScope, obfuscatedRoute) {
+-     // ...
+- }
+- // Define function dependencies
+- MyController['$inject'] = ['$scope', '$route'];
+-
+- // Then
+- expect(injector.annotate(MyController)).toEqual(['$scope', '$route']);
+- ```
+
+  ```
+
+-
+- #### The array notation
+-
+- It is often desirable to inline Injected functions and that's when setting the `$inject` property
+- is very inconvenient. In these situations using the array notation to specify the dependencies in
+- a way that survives minification is a better choice:
+-
+- ```js
+
+  ```
+
+- // We wish to write this (not minification / obfuscation safe)
+- injector.invoke(function($compile, $rootScope) {
+-     // ...
+- });
+-
+- // We are forced to write break inlining
+- var tmpFn = function(obfuscatedCompile, obfuscatedRootScope) {
+-     // ...
+- };
+- tmpFn.$inject = ['$compile', '$rootScope'];
+- injector.invoke(tmpFn);
+-
+- // To better support inline function the inline annotation is supported
+- injector.invoke(['$compile', '$rootScope', function(obfCompile, obfRootScope) {
+-     // ...
+- }]);
+-
+- // Therefore
+- expect(injector.annotate(
+-      ['$compile', '$rootScope', function(obfus_$compile, obfus_$rootScope) {}])
+- ).toEqual(['$compile', '$rootScope']);
+- ```
+
+  ```
+
+-
+- @param {Function|Array.<string|Function>} fn Function for which dependent service names need to
+- be retrieved as described above.
+-
+- @param {boolean=} [strictDi=false] Disallow argument name annotation inference.
+-
+- @returns {Array.<string>} The names of the services which the function requires.
+  \*/
+  /\*\*
+- @ngdoc method
+- @name $injector#loadNewModules
+-
+- @description
+-
+- Add the specified modules to the current injector.
+-
+- This method will add each of the injectables to the injector and execute all of the config and run
+- blocks for each module passed to the method.
+-
+- If a module has already been loaded into the injector then it will not be loaded again.
+-
+- - The application developer is responsible for loading the code containing the modules; and for
+- ensuring that lazy scripts are not downloaded and executed more often that desired.
+- - Previously compiled HTML will not be affected by newly loaded directives, filters and components.
+- - Modules cannot be unloaded.
+-
+- You can use {@link $injector#modules `$injector.modules`} to check whether a module has been loaded
+- into the injector, which may indicate whether the script has been executed already.
+-
+- @example
+- Here is an example of loading a bundle of modules, with a utility method called `getScript`:
+-
+- ```javascript
+
+  ```
+
+- app.factory('loadModule', function($injector) {
+- return function loadModule(moduleName, bundleUrl) {
+-     return getScript(bundleUrl).then(function() { $injector.loadNewModules([moduleName]); });
+- };
+- })
+- ```
+
+  ```
+
+-
+- @param {Array<String|Function|Array>=} mods an array of modules to load into the application.
+-     Each item in the array should be the name of a predefined module or a (DI annotated)
+-     function that will be invoked by the injector as a `config` block.
+-     See: {@link angular.module modules}
+  \*/
+
+/\*\*
+
+- @ngdoc service
+- @name $provide
+-
+- @description
+-
+- The {@link auto.$provide $provide} service has a number of methods for registering components
+- with the {@link auto.$injector $injector}. Many of these functions are also exposed on
+- {@link angular.Module}.
+-
+- An AngularJS **service** is a singleton object created by a **service factory**. These \*\*service
+- factories** are functions which, in turn, are created by a **service provider\*\*.
+- The **service providers** are constructor functions. When instantiated they must contain a
+- property called `$get`, which holds the **service factory** function.
+-
+- When you request a service, the {@link auto.$injector $injector} is responsible for finding the
+- correct **service provider**, instantiating it and then calling its `$get` **service factory**
+- function to get the instance of the **service**.
+-
+- Often services have no configuration options and there is no need to add methods to the service
+- provider. The provider will be no more than a constructor function with a `$get` property. For
+- these cases the {@link auto.$provide $provide} service has additional helper methods to register
+- services without specifying a provider.
+-
+- - {@link auto.$provide#provider provider(name, provider)} - registers a **service provider** with the
+-     {@link auto.$injector $injector}
+- - {@link auto.$provide#constant constant(name, obj)} - registers a value/object that can be accessed by
+-     providers and services.
+- - {@link auto.$provide#value value(name, obj)} - registers a value/object that can only be accessed by
+-     services, not providers.
+- - {@link auto.$provide#factory factory(name, fn)} - registers a service **factory function**
+-     that will be wrapped in a **service provider** object, whose `$get` property will contain the
+-     given factory function.
+- - {@link auto.$provide#service service(name, Fn)} - registers a **constructor function**
+-     that will be wrapped in a **service provider** object, whose `$get` property will instantiate
+-      a new object using the given constructor function.
+- - {@link auto.$provide#decorator decorator(name, decorFn)} - registers a **decorator function** that
+-      will be able to modify or replace the implementation of another service.
+-
+- See the individual methods for more information and examples.
+  \*/
+
+/\*\*
+
+- @ngdoc method
+- @name $provide#provider
+- @description
+-
+- Register a **provider function** with the {@link auto.$injector $injector}. Provider functions
+- are constructor functions, whose instances are responsible for "providing" a factory for a
+- service.
+-
+- Service provider names start with the name of the service they provide followed by `Provider`.
+- For example, the {@link ng.$log $log} service has a provider called
+- {@link ng.$logProvider $logProvider}.
+-
+- Service provider objects can have additional methods which allow configuration of the provider
+- and its service. Importantly, you can configure what kind of service is created by the `$get`
+- method, or how that service will act. For example, the {@link ng.$logProvider $logProvider} has a
+- method {@link ng.$logProvider#debugEnabled debugEnabled}
+- which lets you specify whether the {@link ng.$log $log} service will log debug messages to the
+- console or not.
+-
+- It is possible to inject other providers into the provider function,
+- but the injected provider must have been defined before the one that requires it.
+-
+- @param {string} name The name of the instance. NOTE: the provider will be available under `name +
+             'Provider'` key.
+- @param {(Object|function())} provider If the provider is:
+-
+- - `Object`: then it should have a `$get` method. The `$get` method will be invoked using
+-     {@link auto.$injector#invoke $injector.invoke()} when an instance needs to be created.
+- - `Constructor`: a new instance of the provider will be created using
+-     {@link auto.$injector#instantiate $injector.instantiate()}, then treated as `object`.
+-
+- @returns {Object} registered provider instance
+
+- @example
+-
+- The following example shows how to create a simple event tracking service and register it using
+- {@link auto.$provide#provider $provide.provider()}.
+-
+- ```js
+
+  ```
+
+- // Define the eventTracker provider
+- function EventTrackerProvider() {
+- var trackingUrl = '/track';
+-
+- // A provider method for configuring where the tracked events should been saved
+- this.setTrackingUrl = function(url) {
+-      trackingUrl = url;
+- };
+-
+- // The service factory function
+- this.$get = ['$http', function($http) {
+-      var trackedEvents = {};
+-      return {
+-        // Call this to track an event
+-        event: function(event) {
+-          var count = trackedEvents[event] || 0;
+-          count += 1;
+-          trackedEvents[event] = count;
+-          return count;
+-        },
+-        // Call this to save the tracked events to the trackingUrl
+-        save: function() {
+-          $http.post(trackingUrl, trackedEvents);
+-        }
+-      };
+- }];
+- }
+-
+- describe('eventTracker', function() {
+- var postSpy;
+-
+- beforeEach(module(function($provide) {
+-      // Register the eventTracker provider
+-      $provide.provider('eventTracker', EventTrackerProvider);
+- }));
+-
+- beforeEach(module(function(eventTrackerProvider) {
+-      // Configure eventTracker provider
+-      eventTrackerProvider.setTrackingUrl('/custom-track');
+- }));
+-
+- it('tracks events', inject(function(eventTracker) {
+-      expect(eventTracker.event('login')).toEqual(1);
+-      expect(eventTracker.event('login')).toEqual(2);
+- }));
+-
+- it('saves to the tracking url', inject(function(eventTracker, $http) {
+-      postSpy = spyOn($http, 'post');
+-      eventTracker.event('login');
+-      eventTracker.save();
+-      expect(postSpy).toHaveBeenCalled();
+-      expect(postSpy.mostRecentCall.args[0]).not.toEqual('/track');
+-      expect(postSpy.mostRecentCall.args[0]).toEqual('/custom-track');
+-      expect(postSpy.mostRecentCall.args[1]).toEqual({ 'login': 1 });
+- }));
+- });
+- ```
+  */
+  ```
+
+/\*\*
+
+- @ngdoc method
+- @name $provide#factory
+- @description
+-
+- Register a **service factory**, which will be called to return the service instance.
+- This is short for registering a service where its provider consists of only a `$get` property,
+- which is the given service factory function.
+- You should use {@link auto.$provide#factory $provide.factory(getFn)} if you do not need to
+- configure your service in a provider.
+-
+- @param {string} name The name of the instance.
+- @param {Function|Array.<string|Function>} $getFn The injectable $getFn for the instance creation.
+-                      Internally this is a short hand for `$provide.provider(name, {$get: $getFn})`.
+- @returns {Object} registered provider instance
+-
+- @example
+- Here is an example of registering a service
+- ```js
+
+  ```
+
+- $provide.factory('ping', ['$http', function($http) {
+-     return function ping() {
+-       return $http.send('/ping');
+-     };
+- }]);
+- ```
+
+  ```
+
+- You would then inject and use this service like this:
+- ```js
+
+  ```
+
+- someModule.controller('Ctrl', ['ping', function(ping) {
+-     ping();
+- }]);
+- ```
+  */
+  ```
+
+/\*\*
+
+- @ngdoc method
+- @name $provide#service
+- @description
+-
+- Register a **service constructor**, which will be invoked with `new` to create the service
+- instance.
+- This is short for registering a service where its provider's `$get` property is a factory
+- function that returns an instance instantiated by the injector from the service constructor
+- function.
+-
+- Internally it looks a bit like this:
+-
+- ```
+
+  ```
+
+- {
+- $get: function() {
+-     return $injector.instantiate(constructor);
+- }
+- }
+- ```
+
+  ```
+
+-
+-
+- You should use {@link auto.$provide#service $provide.service(class)} if you define your service
+- as a type/class.
+-
+- @param {string} name The name of the instance.
+- @param {Function|Array.<string|Function>} constructor An injectable class (constructor function)
+-     that will be instantiated.
+- @returns {Object} registered provider instance
+-
+- @example
+- Here is an example of registering a service using
+- {@link auto.$provide#service $provide.service(class)}.
+- ```js
+
+  ```
+
+- var Ping = function($http) {
+-     this.$http = $http;
+- };
+-
+- Ping.$inject = ['$http'];
+-
+- Ping.prototype.send = function() {
+-     return this.$http.get('/ping');
+- };
+- $provide.service('ping', Ping);
+- ```
+
+  ```
+
+- You would then inject and use this service like this:
+- ```js
+
+  ```
+
+- someModule.controller('Ctrl', ['ping', function(ping) {
+-     ping.send();
+- }]);
+- ```
+  */
+  ```
+
+/\*\*
+
+- @ngdoc method
+- @name $provide#value
+- @description
+-
+- Register a **value service** with the {@link auto.$injector $injector}, such as a string, a
+- number, an array, an object or a function. This is short for registering a service where its
+- provider's `$get` property is a factory function that takes no arguments and returns the \*\*value
+- service\*\*. That also means it is not possible to inject other services into a value service.
+-
+- Value services are similar to constant services, except that they cannot be injected into a
+- module configuration function (see {@link angular.Module#config}) but they can be overridden by
+- an AngularJS {@link auto.$provide#decorator decorator}.
+-
+- @param {string} name The name of the instance.
+- @param {\*} value The value.
+- @returns {Object} registered provider instance
+-
+- @example
+- Here are some examples of creating value services.
+- ```js
+
+  ```
+
+- $provide.value('ADMIN_USER', 'admin');
+-
+- $provide.value('RoleLookup', { admin: 0, writer: 1, reader: 2 });
+-
+- $provide.value('halfOf', function(value) {
+-     return value / 2;
+- });
+- ```
+  */
+  ```
+
+/\*\*
+
+- @ngdoc method
+- @name $provide#constant
+- @description
+-
+- Register a **constant service** with the {@link auto.$injector $injector}, such as a string,
+- a number, an array, an object or a function. Like the {@link auto.$provide#value value}, it is not
+- possible to inject other services into a constant.
+-
+- But unlike {@link auto.$provide#value value}, a constant can be
+- injected into a module configuration function (see {@link angular.Module#config}) and it cannot
+- be overridden by an AngularJS {@link auto.$provide#decorator decorator}.
+-
+- @param {string} name The name of the constant.
+- @param {\*} value The constant value.
+- @returns {Object} registered instance
+-
+- @example
+- Here a some examples of creating constants:
+- ```js
+
+  ```
+
+- $provide.constant('SHARD_HEIGHT', 306);
+-
+- $provide.constant('MY_COLOURS', ['red', 'blue', 'grey']);
+-
+- $provide.constant('double', function(value) {
+-     return value * 2;
+- });
+- ```
+  */
+  ```
+
+/\*\*
+
+- @ngdoc method
+- @name $provide#decorator
+- @description
+-
+- Register a **decorator function** with the {@link auto.$injector $injector}. A decorator function
+- intercepts the creation of a service, allowing it to override or modify the behavior of the
+- service. The return value of the decorator function may be the original service, or a new service
+- that replaces (or wraps and delegates to) the original service.
+-
+- You can find out more about using decorators in the {@link guide/decorators} guide.
+-
+- @param {string} name The name of the service to decorate.
+- @param {Function|Array.<string|Function>} decorator This function will be invoked when the service needs to be
+- provided and should return the decorated service instance. The function is called using
+- the {@link auto.$injector#invoke injector.invoke} method and is therefore fully injectable.
+- Local injection arguments:
+-
+- - `$delegate` - The original service instance, which can be replaced, monkey patched, configured,
+-      decorated or delegated to.
+-
+- @example
+- Here we decorate the {@link ng.$log $log} service to convert warnings to errors by intercepting
+- calls to {@link ng.$log#error $log.warn()}.
+- ```js
+
+  ```
+
+- $provide.decorator('$log', ['$delegate', function($delegate) {
+-     $delegate.warn = $delegate.error;
+-     return $delegate;
+- }]);
+- ```
+  */
+  ```