configure whether plugins should be nested or not. (#126)

* configure whether plugins should be nested or not.

* rename nesting to scoped.

* document the npm scoped config option

* rename option to maintainScope

* fix typos

* add in specific error message about duplicate package names

Author: Bret Ikehara

README.md

@@ -67,7 +67,8 @@ gulpLoadPlugins({
     lazy: true, // whether the plugins should be lazy loaded on demand
     rename: {}, // a mapping of plugins to rename
     renameFn: function (name) { ... }, // a function to handle the renaming of plugins (the default works)
-    postRequireTransforms: {} // see documentation below
+    postRequireTransforms: {}, // see documentation below
+    maintainScope: true // toggles loading all npm scopes like non-scoped packages
 });
 ```
 
@@ -136,12 +137,22 @@ Note that if you specify the `renameFn` options with your own custom rename func
 
 ## npm Scopes
 
-`gulp-load-plugins` comes with [npm scope](https://docs.npmjs.com/misc/scope) support. The major difference is that scoped plugins are accessible through an object on `plugins` that represents the scope. For example, if the plugin is `@myco/gulp-test-plugin` then you can access the plugin as shown in the following example:
+`gulp-load-plugins` comes with [npm scope](https://docs.npmjs.com/misc/scope) support. By default, the scoped plugins are accessible through an object on `plugins` that represents the scope. When `maintainScope = false`, the plugins are available in the top level just like any other non-scoped plugins.
+
+For example, if the plugin is `@myco/gulp-test-plugin` then you can access the plugin as shown in the following example:
 
 ```js
-var plugins = require('gulp-load-plugins')();
+var scoped = require('gulp-load-plugins')({
+  maintainScope: true,
+});
+
+scoped.myco.testPlugin();
+
+var nonScoped = require('gulp-load-plugins')({
+  maintainScope: false,
+});
 
-plugins.myco.testPlugin();
+nonScoped.testPlugin();
 ```
 
 ## Lazy Loading

index.js

@@ -45,6 +45,7 @@ module.exports = function(options) {
   var camelizePluginName = options.camelize !== false;
   var lazy = 'lazy' in options ? !!options.lazy : true;
   var renameObj = options.rename || {};
+  var maintainScope = 'maintainScope' in options ? !!options.maintainScope : true;
 
   logDebug('Debug enabled with options: ' + JSON.stringify(options));
 
@@ -88,10 +89,14 @@ module.exports = function(options) {
     }
   }
 
-  function defineProperty(object, transform, requireName, name) {
+  function defineProperty(object, transform, requireName, name, maintainScope) {
+    var err;
     if (object[requireName]) {
       logDebug('error: defineProperty ' + name);
-      throw new Error('Could not define the property "' + requireName + '", you may have repeated dependencies in your package.json like' + ' "gulp-' + requireName + '" and ' + '"' + requireName + '"');
+      err = maintainScope ?
+        'Could not define the property "' + requireName + '", you may have repeated dependencies in your package.json like' + ' "gulp-' + requireName + '" and ' + '"' + requireName + '"' :
+        'Could not define the property "' + requireName + '", you may have repeated a dependency in another scope like' + ' "gulp-' + requireName + '" and ' + '"@foo/gulp-' + requireName + '"';
+      throw new Error(err);
     }
 
     if (lazy) {
@@ -139,16 +144,19 @@ module.exports = function(options) {
 
   unique(micromatch(names, pattern)).forEach(function(name) {
     var decomposition;
+    var fObject = finalObject;
     if (scopeTest.test(name)) {
       decomposition = scopeDecomposition.exec(name);
-
-      if (!finalObject.hasOwnProperty(decomposition[1])) {
-        finalObject[decomposition[1]] = {};
+      if (maintainScope) {
+        if (!fObject.hasOwnProperty(decomposition[1])) {
+          finalObject[decomposition[1]] = {};
+        }
+        fObject = finalObject[decomposition[1]];
       }
 
-      defineProperty(finalObject[decomposition[1]], applyTransform, getRequireName(decomposition[2]), name);
+      defineProperty(fObject, applyTransform, getRequireName(decomposition[2]), name, maintainScope);
     } else {
-      defineProperty(finalObject, applyTransform, getRequireName(name), name);
+      defineProperty(fObject, applyTransform, getRequireName(name), name, maintainScope);
     }
   });
 

package.json

@@ -34,7 +34,8 @@
     "Carlos Henrique",
     "iamfrontender <[email protected]>",
     "Brian Woodward",
-    "Zach Schnackel <[email protected]>"
+    "Zach Schnackel <[email protected]>",
+    "Bret K. Ikehara <[email protected]>"
   ],
   "dependencies": {
     "array-unique": "^0.2.1",

test/index.js

@@ -54,6 +54,20 @@ describe('configuration', function() {
       });
     }, /Could not define the property "bar", you may have repeated dependencies in your package.json like "gulp-bar" and "bar"/);
   });
+
+  it("throws a nice error if there're repeated package names pattern in package.json ", function() {
+    assert.throws(function() {
+      gulpLoadPlugins({
+        config: {
+          dependencies: {
+            '@foo/gulp-bar': '*',
+            'gulp-bar': '~0.0.12'
+          }
+        },
+        maintainScope: false
+      });
+    }, /Could not define the property "bar", you may have repeated a dependency in another scope like "gulp-bar" and "@foo\/gulp-bar"/);
+  });
 });
 
 // Contains common tests with and without lazy mode.
@@ -169,7 +183,7 @@ var commonTests = function(lazy) {
     assert(output.indexOf('gulp-load-plugins') !== -1, 'Expected output to be logged to stdout');
   });
 
-  it('supports loading scopped package', function() {
+  it('supports loading scopped package as a nested reference', function() {
     var x = gulpLoadPlugins({
       lazy: lazy,
       config: { dependencies: { '@myco/gulp-test-plugin': '1.0.0' } }
@@ -178,6 +192,16 @@ var commonTests = function(lazy) {
     assert.deepEqual(x.myco.testPlugin(), { name: 'test' });
   });
 
+  it('supports loading scopped package as a top-level reference', function() {
+    var x = gulpLoadPlugins({
+      lazy: lazy,
+      maintainScope: false,
+      config: { dependencies: { '@myco/gulp-test-plugin': '1.0.0' } }
+    });
+
+    assert.deepEqual(x.testPlugin(), { name: 'test' });
+  });
+
   it('supports custom rename functions', function () {
     var x = gulpLoadPlugins({
       renameFn: function () {