intercept-require - npm Package Compare versions

Comparing version 0.5.0 to 0.6.0

lib/index.js

@@ -16,3 +16,2 @@ // FORKED FROM https://bitbucket.org/ralphv/require-hook/
   testOnlySubPath: [],
-  alternateProjectPaths: []
 };
@@ -22,6 +21,6 @@
 
-var projectPath, requireListener, config;
+var requireListener, config;
 
 function interceptedRequire (moduleId) {
-  var listenerResult, result;
+  var listenerResult, result, error;
   var info = generateRequireInfo(moduleId);
@@ -45,14 +44,17 @@
   } catch (err) {
-    result = err;
+    result = null;
+    error = err;
   }
 
+  info.error = error;
+
+  // if there's a listener, do listener things
   if (requireListener) {
     listenerResult = requireListener(result, info);
-    result = (listenerResult == null ? result : listenerResult);
+    return (listenerResult == null ? result : listenerResult);
   }
 
-  if (result instanceof Error) {
-    throw result;
-  }
-
+  // otherwise behave normally; throw an error if it occurred
+  // else just return the result of `require()`
+  if (error) throw error;
   return result;
@@ -73,3 +75,2 @@ }
 
-var localModuleRe = /^[\/\.]/;
 function isThirdParty (moduleId) {
@@ -85,2 +86,3 @@ return !isNative(moduleId) && !isLocal(moduleId);
 
+var localModuleRe = /^[\/\.]/;
 function isLocal (moduleId) {
@@ -147,5 +149,4 @@ return localModuleRe.test(moduleId);
 var api = module.exports = {
-  attach: function attach (pPath, settings) {
+  attach: function attach (settings) {
     moduleProto.require = interceptedRequire;
-    projectPath = pPath || process.cwd();
     settings = settings || {};
@@ -158,3 +159,2 @@ config = assign({}, DEFAULT_CONFIG, settings);
     api.resetListener();
-    projectPath = null;
     config = null;
@@ -161,0 +161,0 @@ },

package.json

 {
   "name": "intercept-require",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Intercept calls to require()",
@@ -39,5 +39,5 @@ "keywords": [
     "lint": "jshint",
-    "test": "mocha ./test/index.js"
+    "test": "mocha ./test/index-test.js"
   },
   "main": "index.js"
 }

README.md

@@ -6,14 +6,46 @@ #### forked from [https://bitbucket.org/ralphv/require-hook](https://bitbucket.org/ralphv/require-hook)
 
+## Installation
+
+`npm install intercept-require`
+
+## About
+Intercept, prevent, modify, and short-circuit calls to `require()`. 
+
+
+## API
+
+#### `.attach([Object settings])`
+Replace `Module.prototype.require` with an intercepting function. Calls to `require()` continue to behave normally until a listener is set. `settings` is optional, and accepts two options `Boolean shortCircuit` and `Function shortCircuitMatch<Object info>`. 
+
+Short-circuiting allows a consumer to skip disk I/O entirely. In normal situatons, `intercept-require` makes a real `require()` call and intercepts it _on the way back_. Short-circuiting skips this step. This is probably useful only in obscure cases. Further, in the few cases where short-circuiting is necessary, it's unlikely that all `require()` calls need to be short-circuited. `shortCircuitMatch` is a function which is passed the `info` object and returns whether or not the call should be short-circuited. 
+
+#### `.detach()`
+Restore `Module.prototype.require` to it's original value. This also resets the `listener`, so that if `.attach()` is later called, no listener will initially be set.
+
+#### `.setListener(Function<Object info, Object result> listener)`
+Set the listener that will be invoked on every `require()` call. The listener is passed two arguments: an `info` object that represents some metadata about the `require()` call and the module that was found, and an `result` object which contains the `module.exports` of whatever module would have been found had `require()` been called normally, **unless** the `require()` call throws, in which case `result` will be `undefined` and `info.error` will contain the caught error.
+
+When short-circuiting is active, `result` will be null.
+
+The return value of `setListener()` is passed to the requiring module as the return value of `require()` **unless an error is returned, in which case it will be thrown**. If you want to handle (and possibly recover from) errors, then 
+
+#### `.resetListener()`
+Discard the current `listener`. Until another listener is set, all `require()` calls will behave as normal.
+
+#### `.originalRequire`
+A reference to the original function found at `Module.prototype.require`. It's technically possible that this isn't the built in function if something else has overwritten it before `intercept-require` is run.
+
+
+## Example
 ```js
 var intercept = require("intercept-require");
 intercept.attach();
-// calls to require() are now being intercepted
+// Module.prototype.require is now overwritten with the interceptor...
 
-// no listener is set right now. This works as expected.
+// However, no listener is set right now, so this works as normal.
 require("path");
 
 var lastRequireInfo;
-
 intercept.setListener(function (moduleExport, info) {
-  // moduleExports is whatever was found by the built-in require
+  // moduleExport is whatever was found by the built-in require
   lastRequireInfo = info;
@@ -30,4 +62,5 @@ return moduleExport;
 //    native: false,
-//    extname: path.extname(absPath),
+//    extname: ".js",
 //    thirdParty: true,
+//    exports: [[actual lodash object]]
 //    absPath: /from/root/to/project/node_modules/lodash/lodash.js,
@@ -40,3 +73,20 @@ //    absPathResolvedCorrectly: true,
 
+### Info
+`info` objects adhere to this schema
+```
+{
+  exports: Any,
+  moduleId: String,
+  callingFile: String,
+  extname: String,
+  absPath: String,
+  core: Boolean, 
+  thirdParty: Boolean,
+  local: Boolean,
+  absPathResolvedCorrectly: Boolean,
+  testOnly: Boolean
+}
+```
+
 ### License
 MIT

New alerts

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

23167

16.59%

Lines of code

331

2.48%

Number of lines in readme file

90

125%

Worsened metrics

Number of medium supply chain risk alerts

1

Infinity%

No dependency changes