commonjs-walker

commonjs-walker

Analyzes and walks down the dependencies from a commonjs entry and creates a walking tree.

var walker = require('commonjs-walker');

NOTICE that it will not walk down node_modules and any foreign packages.

Supports:

• require() a directory.
• if a module is not find, commonjs-walker will attempt to load the required filename with the added extension of .js, .json, and then .node, according to File Modules

walker(entry, [options,] callback)

walker('/path/to/entry.js', options, function(err, tree, nodes){
	// ...
});

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

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

index.js:

require('./a');
require('b');

a/index.json

{}

Code:

walker('/path/to/index.js', function(err, tree, nodes){
	console.log(tree);
	console.log(nodes);
})

Then, the tree object will be something like:

{
	id: '/path/to/index.js',
	dependents: [],
	isEntryPoint: true,
	unresolvedDependencies: ['./a', './b'],
	dependencies: [
		{
			// use `require.resolve` to the the real path.
			id: '/path/to/a/index.json',
			dependents: [
				tree // points to `index.js`
			],
			dependencies: [],
			unresolvedDependencies: [],
			code: <Buffer>,
			isJson: true
		},
		{
		    id: 'b',
		    isForeign: true,
		    dependents: [tree]
		}
	],
	code: <Buffer>
}

The nodes object is the path->node hashmap.

{
	'/path/to/index.js': tree,
	'/path/to/a.js': tree.dependencies[0]
}

Walks down from a entry point, such as package.main of commonjs, and tries to create a walker.Module instance of the top level.

• entry Path the absolute path of the entry point.
• tree walker.Module tree of walker.Module
• nodes Object the hashmap of <path>: <walker.Module>

options

All options are optional. By default, walker works in a very strict mode.

Option	Type	Default	Description
detectCyclic	Boolean	true	whether should check cyclic dependencies
strictRequire	Boolean	true	whether should check the usage of method require()
allowAbsolutePath	Boolean	true	whether should allow to require an absolute path.
extFallbacks	Array	['.js', '.json', '.node']	see options.extFallbacks section

options.extFallbacks

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. ref

But for browser-side environment, most usually, we do not support extension .node which is why options.extFallbacks.

Especially, only tree values are allowed below:

• ['.js']
• ['.js', '.json'],
• ['.js', '.json', '.node']

Struct: walker.Module

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

For All types

Property	Type	Description
id	String	the id of the module
isEntryPoint	Boolean	whether the current module is the entry point
dependents	Array.<walker.module>	the dependent modules. If there's no dependents, it will be []
isForeign	Boolean	whether the current module is from a foreign package.

isJSON or normal

Property	Type	Description
code	Buffer	the file content of the current module.

For both isForeign and isJSON are false

Property	Type	Description
dependencies	Array.<walker.Module>	the dependencies of the current module. If the module has no dependencies, it will be []
unresolvedDependencies	Array.<String>	the array contains the items require()d by the module.

Class: walker.Error

• code String the enum type of the error
• message String error messages
• stack String the origin error.stack
• data Object the object of the major information of the error, this is useful for i18n.

Error codes

NOT_ALLOW_ABSOLUTE_PATH

MODULE_NOT_FOUND

CYCLIC_DEPENDENCY