module-walker

Analyzes and walks down the dependencies from a entry of commonjs or es6 module and creates a B+ dependency tree.

• Fully implemented File Modules of nodejs.
• You can define what extensions should commonjs-walker fallback to by options.extensions, which will be very usefull for browser-side modules.

Install

$ npm install module-walker --save

walker(options = {})

const walker = require('module-walker')

let resolve = (nodes) => {
  // nodes
}

walker(options)
  .on('warn', message => {
    console.warn(message)
  })
  .walk(filename)
  .walk(filename)
  .then(resolve, reject)

• nodes Object.<id>:<walker.Node>
• resolve function(nodes)
• reject function(err)

For the example of variable nodes, see the last section below.

options

All options are optional. Default options are typically used for node.js environment in strict mode.

• allowCyclic Boolean=true When false, if cyclic dependencies are detected, it will be reject()ed.
• checkRequireLength Boolean=false When true, require() method only accepts one argument. Otherwise, it will be reject()ed
• allowAbsoluteDependency Boolean=true When false, require()ing an absolute path is not allowed, such as require('/data/a.js'), which has several issues for browser-side module.
• extensions Array=['.js', '.json', '.node'] See options.extensions section.
• requireResolve Boolean=true When true, require.resolve() will be parsed.
• requireAsync Boolean=false Specially, if true, module-walker will parse the usage of require.async(id) for some browser-side module loaders.
• allowNonLiteralRequire Boolean=true Whether should check the usage of method require(). If false, the argument of require() must be an literal string, otherwise it will be reject()ed.
• commentRequire Boolean=false When true, it supports to write

// @require('./controller/a')
// @require('./controller/b')
const Controller = require(`./controller/${type}`)

which is really helpful for browsers

• allowImportExportEverywhere Boolean=false By default, import and export declarations can only appear at a program's top level. Setting this option to true allows them anywhere where a statement is allowed. This option is used for babylon.
• allowReturnOutsideFunction Boolean=false By default, a return statement at the top level raises an error. Set this to true to accept such code. This option is used for babylon.
• sourceType String='module' Indicate the mode the code should be parsed in. Can be either "script" or "module". This option is used for babylon.
• parse function(code, options)=walker.astFromSource Method to parse and return the ast(estree) of the given code. (probably don't use this)
• resolve function(id, options, callback)=walker.resolve Asynchronous method to require.resolve() the given id. (probably don't use this)

options.extensions

type Array

When we require() a path, if path is not found, nodejs will attempt to load the required filename with the added extension of .js, .json, and then .node. Reference via

For browser-side environment, we could use ['.js', '.json'].

Struct: walker.Node

Actually, there is no walker.Node exists. We only use it to declare and describe the structure of the module.

Property | Type | Description -------- | ---- | ----------- foreign | Boolean | whether the current module is from a foreign package. require | Object | The <id>: <path> map. id is the module identifier user require()d in the module file. resolve | Object | similar to require async | Object | similar to async type | Array.<String> | the type of the current node to be required. see example below.

Example

If the file structure of your project is (actually it is a very extreme scenario):

/path/to
       |-- index.js
       |-- a.png
       |-- a
           |-- index.json

index.js:

require('./a')
require('b')
var image = require.resolve('./a.png')

a/index.json

{}

Code:

walker().walk('/path/to/index.js').then(function(nodes){
  console.log(nodes)
});

Then, the nodes object will be something like:

{
  '/path/to/index.js': {
    id: '/path/to/index.js',
    require: {
      './a': '/path/to/a/index.json',
      'b': 'b'
    },
    resolve: {
      './a.png': '/path/to/a.png'
    },
    code: <buffer>
    type: ['require'] // there is a 'require' type for entry node
  },
  '/path/to/a.png': {
    require: {},
    type: ['resolve'] // indicates that this node is `require.resolve()`d
  }
  '/path/to/a/index.json': {
    require: {},
    type: ['require'],
    code: <buffer>
  },
  'b': {
    foreign: true
  }
}

License

MIT