add extend() for operator extensability, improve parsing of deep options from environment variables, add stats related options, bump minor version

Author: benholloway

config/add/browser-sync.js

@@ -6,7 +6,7 @@ var glob              = require('glob'),
     BrowserSyncPlugin = require('browser-sync-webpack-plugin');
 
 /**
- * Add browser-sync feature.
+ * Add browser-sync server for Webpack `--watch`.
  * @this {Config} A webpack-configurator instance
  * @param {string} directory Base directory for the server (should point to your compiled application)
  * @param {number} port Server port

config/add/common.js

@@ -9,10 +9,10 @@ var webpack              = require('webpack'),
     OmitTildePlugin      = require('omit-tilde-webpack-plugin');
 
 /**
- * Add common features.
+ * Add configuration common to all modes.
  * @this {Config} A webpack-configurator instance
  * @param {string} loaderRoot The base path in which to locate loaders
- * @param {{appDir:string, globals:object} globals A hash of options
+ * @param {{appDir:string, globals:object, stats:string}} options A hash of options
  * @returns {Config} The given webpack-configurator instance
  */
 function common(loaderRoot, options) {
@@ -46,7 +46,8 @@ function common(loaderRoot, options) {
       },
       node         : {
         fs: 'empty'
-      }
+      },
+      stats        : options.stats
     })
 
     // before compile

config/add/composition.js

@@ -6,15 +6,16 @@ var IndexHTMLPlugin  = require('indexhtml-webpack-plugin'),
     GulpInjectPlugin = require('gulp-inject-webpack-plugin');
 
 /**
- * Detect all compositions in the given base directory.
+ * Add an application for compilation.
  * @this {Config} A webpack-configurator instance
- * @param {{directory:string, htmlFiles:Array, indexFiles:Array}} item A composition item
+ * @param {{namespace:Array.<string>, directory:string, htmlFiles:Array, indexFiles:Array}} item A composition item
  * @returns {Config} The given webpack-configurator instance
  */
 function composition(item) {
   /* jshint validthis:true */
   return this
     .merge({
+      name : ['app'].concat(composition.namespace).join(':'),
       entry: {
         'index-html': item.htmlFiles,
         index       : item.indexFiles

config/app.js

@@ -2,30 +2,23 @@
 
 var path = require('path');
 
-var createConfigurator = require('../lib/create-configurator'),
-    listCompositions   = require('../lib/list-compositions');
+var listCompositions   = require('../lib/list-compositions');
 
 /**
  * Create a list of webpack configurators, one for each application detected.
+ * @param {function} configuratorFactory A factory for the webpack-configurator
  * @param {{appDir:string, buildDir:string, globals:object, unminified:boolean, port:number}} options An options hash
  * @returns {Array.<Config>} A list of configurators, one for each application detected
  */
-function app(options) {
+function app(configuratorFactory, options) {
 
   // there may be any number of compositions in subdirectories
   return listCompositions(options.appDir)
     .map(eachComposition);
 
   function eachComposition(composition, i) {
     var buildDir = path.join(options.buildDir, composition.directory),
-        config   = createConfigurator({
-          addBrowserSync : require('./add/browser-sync'),
-          addClean       : require('./add/clean'),
-          addCommon      : require('./add/common'),
-          addComposition : require('./add/composition'),
-          addConditionals: require('./add/conditionals'),
-          addMinification: require('./add/minification')
-        })
+        config   = configuratorFactory()
           .addClean(buildDir)
           .addCommon(path.resolve(__dirname, '..', 'node_modules'), options)
           .addComposition(composition)
@@ -36,7 +29,6 @@ function app(options) {
           })
           .addMinification(!options.unminified)
           .merge({
-            name  : ['app'].concat(composition.namespace).join('::'),
             output: {
               path: path.resolve(buildDir)
             }

config/release.js

@@ -2,26 +2,18 @@
 
 var path = require('path');
 
-var createConfigurator = require('../lib/create-configurator'),
-    listCompositions   = require('../lib/list-compositions');
+var listCompositions = require('../lib/list-compositions');
 
 /**
  * Create a single webpack configurator for release.
+ * @param {function} configuratorFactory A factory for the webpack-configurator
  * @param {{appDir:string, releaseDir:string, globals:object, unminified:boolean, port:number}} options An options hash
  * @returns {Config} A webpack configurator
  */
-function release(options) {
+function release(configuratorFactory, options) {
   var composition = listCompositions(options.appDir)[0];
   if (composition) {
-    return createConfigurator({
-      addBrowserSync          : require('./add/browser-sync'),
-      addClean                : require('./add/clean'),
-      addCommon               : require('./add/common'),
-      addComposition          : require('./add/composition'),
-      addConditionals         : require('./add/conditionals'),
-      addExternalChunkManifest: require('./add/external-chunk-manifest'),
-      addMinification         : require('./add/minification')
-    })
+    return configuratorFactory()
       .addBrowserSync(options.releaseDir, options.port)
       .addClean(options.releaseDir)
       .addComposition(composition)

config/test.js

@@ -2,22 +2,16 @@
 
 var path = require('path');
 
-var createConfigurator = require('../lib/create-configurator');
-
 /**
  * Create a single webpack configurator for test.
+ * @param {function} configuratorFactory A factory for the webpack-configurator
  * @param {{appDir:string, testDir:string, globals:object, testGlob:string}} options An options hash
  * @returns {Config} A webpack configurator
  */
-function test(options) {
+function test(configuratorFactory, options) {
   var testEntry = path.resolve(options.appDir, 'test.js');
 
-  return createConfigurator({
-    addClean              : require('./add/clean'),
-    addCommon             : require('./add/common'),
-    addConditionals       : require('./add/conditionals'),
-    addTestSuiteGeneration: require('./add/test-suite-generation')
-  })
+  return configuratorFactory()
     .addClean(options.testDir)
     .addCommon(path.resolve(__dirname, '..', 'node_modules'), options)
     .addConditionals({

index.js

@@ -5,15 +5,27 @@ var path = require('path'),
 
 var defaults = require('lodash.defaults');
 
-var defaultOptions = require('./lib/default-options'),
-    parseOptions   = require('./lib/parse-options');
+var defaultOptions         = require('./lib/default-options'),
+    parseOptions           = require('./lib/parse-options'),
+    getConfiguratorFactory = require('./lib/get-configurator-factory');
+
+var DEFAULT_OPERATORS = {
+  addBrowserSync          : require('./config/add/browser-sync'),
+  addClean                : require('./config/add/clean'),
+  addCommon               : require('./config/add/common'),
+  addComposition          : require('./config/add/composition'),
+  addConditionals         : require('./config/add/conditionals'),
+  addExternalChunkManifest: require('./config/add/external-chunk-manifest'),
+  addMinification         : require('./config/add/minification'),
+  addTestSuiteGeneration  : require('./config/add/test-suite-generation')
+};
 
 /**
  * Create a set of accessors that yield webpack configurator(s).
  * @param {...object} [options] Any number of options hashes to be merged
  * @returns {{app:function, test:function, release:function, resolve:function}} A new instance
  */
-function configFactory(options) {
+function create(options) {
 
   // legacy support
   //  where angularity.json is present it should define the port
@@ -27,40 +39,55 @@ function configFactory(options) {
         defaults({port: angularityPort}, defaultOptions())  // merged defaults
       );
 
-  // create and return the instance
-  var instance = {
-    get app() {
-      return require('./config/app')(opt);
-    },
-    get test() {
-      return require('./config/test')(opt);
-    },
-    get release() {
-      return require('./config/release')(opt);
-    },
-    resolve: resolve
-  };
-  return instance;
+  // default is the default operator set
+  return extend(DEFAULT_OPERATORS);
 
   /**
-   * Call the given function with the instance (as this) and resolve() any webpack configurators that it returns.
-   * @param {function(instance:object}:Array.<Config>|Config} fn A method to call with the instance as this
-   * @returns {Array.<object>|object} A webpack configuration or Array thereof
+   * Extend the configurator with the given operators.
+   * @param {object} oldOperators A hash of the existing operators from the parent instance
+   * @param {object} newOperators A hash of operator overrides
+   * @returns {{extend:function, resolve:function, app:Array.<Configurator>, test:Configurator, release:Configurator}}
    */
-  function resolve(fn) {
-    if (typeof fn !== 'function') {
-      throw new Error('The argument given to resolve() must be a function');
-    }
-    else {
-      return [].concat(fn.call(instance))
-        .filter(Boolean)
-        .map(resolveElement);
-    }
+  function extend(oldOperators, newOperators) {
+    var operators           = defaults({}, newOperators, oldOperators),
+        configuratorFactory = getConfiguratorFactory(operators);
+
+    // create and return the instance
+    var instance = {
+      extend : extend.bind(null, operators),
+      resolve: resolve,
+      get app() {
+        return require('./config/app')(configuratorFactory, opt);
+      },
+      get test() {
+        return require('./config/test')(configuratorFactory, opt);
+      },
+      get release() {
+        return require('./config/release')(configuratorFactory, opt);
+      }
+    };
+    return instance;
+
+    /**
+     * Call the given function with the instance (as this) and resolve() any webpack configurators that it returns.
+     * @param {function(instance:object):Config|Array.<Config>} fn A method to call with the instance as this
+     * @returns {Array.<object>|object} A webpack configuration or Array thereof
+     */
+    function resolve(fn) {
+      if (typeof fn !== 'function') {
+        throw new Error('The argument given to resolve() must be a function');
+      }
+      else {
+        return [].concat(fn.call(instance))
+          .filter(Boolean)
+          .map(resolveElement);
+      }
 
-    function resolveElement(configurator) {
-      return configurator.resolve();
+      function resolveElement(configurator) {
+        return configurator.resolve();
+      }
     }
   }
 }
 
-module.exports = configFactory;
+module.exports = create;

lib/create-configurator.js

@@ -10,7 +10,22 @@ function defaultOptions() {
     port      : 55555,
     unminified: false,
     publicPath: undefined,
-    globals   : {}
+    globals   : {},
+    stats     : {
+      hash        : true,
+      version     : true,
+      timings     : true,
+      assets      : true,
+      chunks      : true,
+      modules     : true,
+      reasons     : true,
+      children    : true,
+      source      : true,
+      errors      : true,
+      errorDetails: true,
+      warnings    : true,
+      publicPath  : true
+    }
   };
 }
 

lib/default-options.js

@@ -0,0 +1,24 @@
+'use strict';
+
+var Config = require('webpack-configurator');
+
+/**
+ * Create a factory for webpack-configurator with additional methods as given.
+ * @param {object} operators A hash of methods to add to webpack-configurator
+ * @returns {Config} A webpack-configurator instance with the additional operators
+ */
+function getConfiguratorFactory(operators) {
+  return function configuratorFactory() {
+    var instance = new Config();
+    for (var key in operators) {
+      if (typeof operators[key] === 'function') {
+        instance[key] = operators[key].bind(instance);
+      } else {
+        throw new Error('The operator named "' + key + '" must be function.')
+      }
+    }
+    return instance;
+  }
+}
+
+module.exports = getConfiguratorFactory;