cleanups and adaptation to plugin API

- adding deprecation warning for old API
- making plugin API default in README and warning about deprecated old
  API
- adapted example to use new API and linked dependencies so no npm
  install is needed to run it
- renamed hack-prelude since it's no longer a hack
- upgrading browserify
- increasing peerdep browserify version range
- adding browerify-tool keyword

README.md

@@ -4,23 +4,30 @@ browserify v2 version of [proxyquire](https://github.com/thlorenz/proxyquire).
 
 Proxies browserify's require in order to make overriding dependencies during testing easy while staying **totally unobstrusive**.
 
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
 **Table of Contents**  *generated with [DocToc](http://doctoc.herokuapp.com/)*
 
 - [Features](#features)
 - [Installation](#installation)
 - [Example](#example)
 - [API](#api)
+  - [proxyquire.plugin()](#proxyquireplugin)
   - [proxyquire.browserify()](#proxyquirebrowserify)
-  - [proxyquire(request: String, stubs: Object)](#proxyquirerequest:-string-stubs:-object)
+    - [Deprecation Warning](#deprecation-warning)
+  - [proxyquire(request: String, stubs: Object)](#proxyquirerequest-string-stubs-object)
     - [Important Magic](#important-magic)
   - [noCallThru](#nocallthru)
 - [More Examples](#more-examples)
 
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+
 ## Features
 
 - **no changes to your code** are necessary
 - non overriden methods of a module behave like the original
-- mocking framework agnostic, if it can stub a function then it works with proxyquireify
+- mocking framework agnostic, if it can stub a function then it works with **proxyquireify**
 - "use strict" compliant
 - [automatic injection](https://github.com/thlorenz/proxyquireify#important-magic) of `require` calls to ensure the
   module you are testing gets bundled 
@@ -61,11 +68,13 @@ console.log(foo());
 **browserify.build.js**:
 
 ```js
+var browserify = require('browserify');
 var proxyquire = require('proxyquireify');
 
-proxyquire.browserify()
+browserify()
+  .plugin(proxyquire.plugin)
   .require(require.resolve('./foo.test'), { entry: true })
-  .bundle({ debug: true })
+  .bundle()
   .pipe(fs.createWriteStream(__dirname + '/bundle.js'));
 ```
 
@@ -75,21 +84,9 @@ load it in the browser and see:
 
 ## API
 
-### proxyquire.browserify()
-
-To be used in build script instead of `browserify()`, autmatically adapts browserify to work for tests and injects
-require overrides into all modules via a browserify transform.
-
-```js
-proxyquire.browserify()
-  .require(require.resolve('./test'), { entry: true })
-  .bundle()
-  .pipe(fs.createWriteStream(__dirname + '/bundle.js'));
-```
-
 ### proxyquire.plugin()
 
-Instead of being used instead of `browserify()`, proxyquireify can also be used as a browserify plugin.
+**proxyquireify** functions as a browserify plugin and needs to be registered with browserify like so:
 
 ```js
 var browserify = require('browserify');
@@ -102,13 +99,35 @@ browserify()
   .pipe(fs.createWriteStream(__dirname + '/bundle.js'));
 ```
 
-The plugin is also exported from the file plugin.js so that you can use proxyquireify when running browserify
-from the command line.
+Alternatively you can register **proxyquireify** as a plugin from the command line like so:
 
 ```sh
 browserify -p proxyquireify/plugin test.js > bundle.js
 ```
 
+### proxyquire.browserify()
+
+#### Deprecation Warning
+
+This API to setup **proxyquireify** was used prior to [browserify plugin](https://github.com/substack/node-browserify#bpluginplugin-opts) support.
+
+It has not been removed yet to make upgrading **proxyquireify** easier for now, but it **will be deprecated in future
+versions**. Please consider using the plugin API (above) instead.
+
+****
+
+To be used in build script instead of `browserify()`, autmatically adapts browserify to work for tests and injects
+require overrides into all modules via a browserify transform.
+
+```js
+proxyquire.browserify()
+  .require(require.resolve('./test'), { entry: true })
+  .bundle()
+  .pipe(fs.createWriteStream(__dirname + '/bundle.js'));
+```
+
+****
+
 ### proxyquire(request: String, stubs: Object)
 
 - **request**: path to the module to be tested e.g., `../lib/foo`
@@ -126,13 +145,13 @@ var foo = proxyquire('./foo', { './bar': barStub })
 
 #### Important Magic 
 
-In order for browserify to include the module you are testing in the bundle, proxyquireify will inject a
+In order for browserify to include the module you are testing in the bundle, **proxyquireify** will inject a
 `require()` call for every module you are proxyquireing. So in the above example `require('./foo')` will be injected at
 the top of your test file.
 
 ### noCallThru
 
-By default proxyquireify calls the function defined on the *original* dependency whenever it is not found on the stub.
+By default **proxyquireify** calls the function defined on the *original* dependency whenever it is not found on the stub.
 
 If you prefer a more strict behavior you can prevent *callThru* on a per module or per stub basis.
 

examples/foobar/build.js

@@ -1,9 +1,10 @@
-var fs         =  require('fs')
-  , proxyquire =  require('proxyquireify')
+var fs         = require('fs')
+  , proxyquire = require('proxyquireify')
+  , browserify = require('browserify')
   ;
 
-proxyquire.browserify()
+browserify()
+  .plugin(proxyquire.plugin)
   .require(require.resolve('./test'), { entry: true })
   .bundle({ debug: true })
-  .pipe(require('mold-source-map').transformSourcesRelativeTo(__dirname))
   .pipe(fs.createWriteStream(__dirname + '/bundle.js'));

examples/foobar/package.json

@@ -3,12 +3,9 @@
   "version": "0.0.0",
   "description": "proxyquireify foobar example",
   "scripts": {
-    "test": "node build && opener index.html"
+    "test": "node build && open index.html"
   },
   "dependencies": {
-    "browserify": "~2.10.0",
-    "opener": "~1.3.0",
-    "proxyquireify": "~0.2.0"
   },
   "devDependencies": {},
   "keywords": [],

index.js

@@ -96,8 +96,8 @@ proxyquire._proxy = function (require_, request) {
 
 if (require.cache) {
   // only used during build, so prevent browserify from including it
-  var hackPreludePath = './lib/hack-prelude';
-  var hackPrelude = require(hackPreludePath);
-  proxyquire.browserify = hackPrelude.browserify;
-  proxyquire.plugin = hackPrelude.plugin;
+  var replacePreludePath = './lib/replace-prelude';
+  var replacePrelude = require(replacePreludePath);
+  proxyquire.browserify = replacePrelude.browserify;
+  proxyquire.plugin = replacePrelude.plugin;
 }

lib/hack-prelude.js → lib/replace-prelude.js

@@ -21,5 +21,7 @@ var plugin = exports.plugin = function (bfy, opts) {
 
 // Maintain support for the old interface
 exports.browserify = function (files) {
+  console.error('You are setting up proxyquireify via the old API which will be deprecated in future versions.');
+  console.error('It is recommended to use it as a browserify-plugin instead - see the example in the README.');
   return require('browserify')(files).plugin(plugin);
 };

package.json

@@ -16,7 +16,7 @@
     "through": "~2.2.7"
   },
   "devDependencies": {
-    "browserify": "~3.44.2",
+    "browserify": "~4.1.5",
     "mold-source-map": "~0.2.0",
     "tap": "~0.4.8",
     "tape": "~2.12.3"
@@ -30,6 +30,7 @@
     "proxyquire",
     "browser",
     "browserify",
+    "browserify-tool",
     "client"
   ],
   "author": {
@@ -42,6 +43,6 @@
     "node": ">=0.6"
   },
   "peerDependencies": {
-    "browserify": ">= 3.0.0 < 4"
+    "browserify": ">= 3.0.0 < 5"
   }
 }

plugin.js

@@ -1,3 +1,3 @@
 // This file allows using proxyquireify as a browserify plugin named
 // 'proxyquireify/plugin'
-module.exports = require('./lib/hack-prelude').plugin;
+module.exports = require('./lib/replace-prelude').plugin;