feat(angular.info): optionally store and access additional info on modules

This feature allows the developer to store additional meta data about a
module when it is defined by calling `mod.info(infoObject)` on the module
object.

Developers can then access this information by calling `mod.info()` or
`angular.info(moduleName)`.

See this angular/material#3842 for more background.

Closes #12465

Author: petebacondarwin

src/.jshintrc

@@ -81,6 +81,7 @@
     "encodeUriSegment": false,
     "encodeUriQuery": false,
     "angularInit": false,
+    "info": false,
     "bootstrap": false,
     "getTestability": false,
     "snake_case": false,

src/Angular.js

@@ -1504,6 +1504,25 @@ function angularInit(element, bootstrap) {
   }
 }
 
+
+/**
+ * @ngdoc function
+ * @name angular.info
+ * @module ng
+ * @returns { Object }
+ *    An object containing the info about a module or an empty object if
+ *    the module has not been defined.
+ * @description
+ * Get the info about a given module.
+ */
+function info(moduleName) {
+  try {
+    return angularModule(moduleName).info();
+  } catch (e) {
+    return {};
+  }
+}
+
 /**
  * @ngdoc function
  * @name angular.bootstrap

src/AngularPublic.js

@@ -150,7 +150,8 @@ function publishExternalAPI(angular) {
     'getTestability': getTestability,
     '$$minErr': minErr,
     '$$csp': csp,
-    'reloadWithDebugInfo': reloadWithDebugInfo
+    'reloadWithDebugInfo': reloadWithDebugInfo,
+    'info': info
   });
 
   angularModule = setupModuleLoader(window);

src/loader.js

@@ -79,6 +79,9 @@ function setupModuleLoader(window) {
      * @returns {module} new module with the {@link angular.Module} api.
      */
     return function module(name, requires, configFn) {
+
+      var info = {};
+
       var assertNotHasOwnProperty = function(name, context) {
         if (name === 'hasOwnProperty') {
           throw ngMinErr('badname', 'hasOwnProperty is not a valid {0} name', context);
@@ -114,6 +117,37 @@ function setupModuleLoader(window) {
           _configBlocks: configBlocks,
           _runBlocks: runBlocks,
 
+          /**
+           * @ngdoc method
+           * @name angular.Module#info
+           * @module ng
+           *
+           * @param {Object=} info Information about the module
+           * @returns {Object|Module} The current info object for this module if called as a getter,
+           *                          or `this` if called as a setter.
+           *
+           * @description
+           * Additional info about this module
+           * For example you could put the version of the module in here.
+           *
+           * ```js
+           * angular.module('myModule', []).info({ version: '1.0.0' });
+           * ```
+           *
+           * The global method `angular.info()` can be used to retrieve this info:
+           *
+           * ```js
+           * var version = angular.info('myModule').version;
+           * ```
+           */
+          info: function(value) {
+            if (isDefined(value)) {
+              info = value;
+              return this;
+            }
+            return info;
+          },
+
           /**
            * @ngdoc property
            * @name angular.Module#requires

test/.jshintrc

@@ -75,6 +75,7 @@
     "encodeUriSegment": false,
     "encodeUriQuery": false,
     "angularInit": false,
+    "info": false,
     "bootstrap": false,
     "snake_case": false,
     "bindJQuery": false,

test/AngularSpec.js

@@ -1614,6 +1614,21 @@ describe('angular', function() {
     });
   });
 
+
+  describe('info', function() {
+    it('should return the additional info for the named module', function() {
+      angular.module('a', []).info({some: 'thing'});
+      angular.module('b', ['dep'], function configFn() {}).info({other: 'thang'});
+
+      expect(info('a')).toEqual({some: 'thing'});
+      expect(info('b')).toEqual({other: 'thang'});
+    });
+
+    it('should return anh empty object if there is no such module', function() {
+      expect(info('no-such-module')).toEqual({});
+    });
+  });
+
   describe('bootstrap', function() {
     it('should bootstrap app', function() {
       var element = jqLite('<div>{{1+2}}</div>');

test/loaderSpec.js

@@ -26,10 +26,14 @@ describe('module loader', function() {
 
 
   it('should record calls', function() {
+    function config() {}
+    function init() {}
+    function init2() {}
+
     var otherModule = window.angular.module('other', []);
-    otherModule.config('otherInit');
+    otherModule.config(init);
 
-    var myModule = window.angular.module('my', ['other'], 'config');
+    var myModule = window.angular.module('my', ['other'], config);
 
     expect(myModule.
       decorator('dk', 'dv').
@@ -40,7 +44,7 @@ describe('module loader', function() {
       filter('f', 'ff').
       directive('d', 'dd').
       controller('ctrl', 'ccc').
-      config('init2').
+      config(init2).
       constant('abc', 123).
       run('runBlock')).toBe(myModule);
 
@@ -57,13 +61,31 @@ describe('module loader', function() {
       ['$controllerProvider', 'register', ['ctrl', 'ccc']]
     ]);
     expect(myModule._configBlocks).toEqual([
-      ['$injector', 'invoke', ['config']],
-      ['$injector', 'invoke', ['init2']]
+      ['$injector', 'invoke', [config]],
+      ['$injector', 'invoke', [init2]]
     ]);
     expect(myModule._runBlocks).toEqual(['runBlock']);
   });
 
 
+  it('should store additional module info', function() {
+    var myModule = angular.module('myModule', ['dep1']).info({version: '1.0'});
+    var otherModule = angular.module('otherModule', ['dep2'], function someConfig() {}).info({version: '2.0'});
+    var thirdModule = angular.module('thirdModule', ['dep2', 'dep3'], [function someConfig() {}]).info({version: '3.0'});
+    var fourthModule = angular.module('fourthModule', [], [function someConfig() {}]);
+
+    expect(myModule.info()).toEqual({version: '1.0'});
+    expect(otherModule.info()).toEqual({version: '2.0'});
+    expect(thirdModule.info()).toEqual({version: '3.0'});
+    expect(fourthModule.info()).toEqual({});
+
+    expect(angular.info('myModule')).toEqual({version: '1.0'});
+    expect(angular.info('otherModule')).toEqual({version: '2.0'});
+    expect(angular.info('thirdModule')).toEqual({version: '3.0'});
+    expect(angular.info('fourthModule')).toEqual({});
+  });
+
+
   it('should allow module redefinition', function() {
     expect(window.angular.module('a', [])).not.toBe(window.angular.module('a', []));
   });