# module-deps

walk the dependency graph to generate json output that can be fed into
[browser-pack](https://github.com/substack/browser-pack)

[![build status](https://secure.travis-ci.org/substack/module-deps.png)](http://travis-ci.org/substack/module-deps)

# example

``` js
var mdeps = require('module-deps');
var JSONStream = require('JSONStream');

var md = mdeps();
md.pipe(JSONStream.stringify()).pipe(process.stdout);
md.end({ file: __dirname + '/files/main.js' });
```

output:

```
$ node example/deps.js
[
{"id":"/Users/substack/src/module-deps/example/files/bar.js","source":"module.exports = function (n) {\n    return n * 100;\n};\n","deps":{},"file":"/Users/substack/src/module-deps/example/files/bar.js","sortKey":"!/Users/substack/src/module-deps/example/files/main.js:00000000!/Users/substack/src/module-deps/example/files/foo.js:00000000!/Users/substack/src/module-deps/example/files/bar.js"}
,
{"id":"/Users/substack/src/module-deps/example/files/foo.js","source":"var bar = require('./bar');\n\nmodule.exports = function (n) {\n    return n * 111 + bar(n);\n};\n","deps":{"./bar":"/Users/substack/src/module-deps/example/files/bar.js"},"file":"/Users/substack/src/module-deps/example/files/foo.js","sortKey":"!/Users/substack/src/module-deps/example/files/main.js:00000000!/Users/substack/src/module-deps/example/files/foo.js"}
,
{"file":"/Users/substack/src/module-deps/example/files/main.js","id":"/Users/substack/src/module-deps/example/files/main.js","source":"var foo = require('./foo');\nconsole.log('main: ' + foo(5));\n","deps":{"./foo":"/Users/substack/src/module-deps/example/files/foo.js"},"sortKey":"!/Users/substack/src/module-deps/example/files/main.js","entry":true}
]
```

and you can feed this json data into
[browser-pack](https://github.com/substack/browser-pack):

```
$ node example/deps.js | browser-pack | node
main: 1055
```

# usage

```
usage: module-deps [files]

  generate json output from each entry file

```

# methods

``` js
var mdeps = require('module-deps')
```

## var d = mdeps(opts={})

Return an object transform stream `d` that expects entry filenames or
`{ id: ..., file: ... }` objects as input and produces objects for every
dependency from a recursive module traversal as output.

Each file in `files` can be a string filename or a stream.

Optionally pass in some `opts`:

* `opts.transform` - a string or array of string transforms (see below)

* `opts.transformKey` - an array path of strings showing where to look in the
package.json for source transformations. If falsy, don't look at the
package.json at all.

* `opts.resolve` - custom resolve function using the
`opts.resolve(id, parent, cb)` signature that
[browser-resolve](https://github.com/shtylman/node-browser-resolve) has

* `opts.filter` - a function (id) to skip resolution of some module `id` strings.
If defined, `opts.filter(id)` should return truthy for all the ids to include
and falsey for all the ids to skip.

* `opts.postFilter` - a function (id, file, pkg) that gets called after `id` has
been resolved. Return false to skip this file.

* `opts.packageFilter` - transform the parsed package.json contents before using
the values. `opts.packageFilter(pkg, dir)` should return the new `pkg` object to
use.

* `opts.noParse` - an array of absolute paths to not parse for dependencies. Use
this for large dependencies like jquery or threejs which take forever to parse.

* `opts.cache` - an object mapping filenames to file objects to skip costly io

* `opts.packageCache` - an object mapping filenames to their parent package.json
contents for browser fields, main entries, and transforms

* `opts.fileCache` - an object mapping filenames to raw source to avoid reading
from disk.

* `opts.paths` - array of global paths to search. Defaults to splitting on `':'`
in `process.env.NODE_PATH`

* `opts.ignoreMissing` - ignore files that failed to resolve

# input objects

Input objects should be string filenames or objects with these parameters:

* `row.file` - filename
* `row.expose` - name to be exposed as
* `row.noparse` when true, don't parse the file contents for dependencies

or objects can specify transforms:

* `row.transform` - string name, path, or function
* `row.options` - transform options as an object
* `row.global` - boolean, whether the transform is global

# events

## d.on('transform', function (tr, file) {})

Every time a transform is applied to a `file`, a `'transform'` event fires with
the instantiated transform stream `tr`.

## d.on('file', function (file) {})

Every time a file is read, this event fires with the file path.

## d.on('missing', function (id, parent) {})

When `opts.ignoreMissing` is enabled, this event fires for each missing package.

## d.on('package', function (pkg) {})

Every time a package is read, this event fires. The directory name of the
package is available in `pkg.__dirname`.

# transforms

module-deps can be configured to run source transformations on files before
parsing them for `require()` calls. These transforms are useful if you want to
compile a language like [coffeescript](http://coffeescript.org/) on the fly or
if you want to load static assets into your bundle by parsing the AST for
`fs.readFileSync()` calls.

If the transform is a function, it should take the `file` name as an argument
and return a through stream that will be written file contents and should output
the new transformed file contents.

If the transform is a string, it is treated as a module name that will resolve
to a module that is expected to follow this format:

``` js
var through = require('through2');
module.exports = function (file) { return through() };
```

You don't necessarily need to use the
[through2](https://github.com/rvagg/through2) module to create a
readable/writable filter stream for transforming file contents, but this is an
easy way to do it.

When you call `mdeps()` with an `opts.transform`, the transformations you
specify will not be run for any files in node_modules/. This is because modules
you include should be self-contained and not need to worry about guarding
themselves against transformations that may happen upstream.

Modules can apply their own transformations by setting a transformation pipeline
in their package.json at the `opts.transformKey` path. These transformations
only apply to the files directly in the module itself, not to the module's
dependants nor to its dependencies.

# output objects

The objects emitted from module-deps include file contents, metadata, and
dependencies.

* source: the complete source code of the file as a string
* file: the filename
* sortKey: a string that consists of the dependency path from root to this
  file, along with line numbers of the require statements. This makes it possible
  to sort the results in order written in the source.
* deps: an object that maps between the string given to the `require` method
  and the filename it resolves to

## package.json transformKey

Transform keys live at a configurable location in the package.json denoted by
the `opts.transformKey` array.

For a transformKey of `['foo','bar']`, the transformKey can be a single string
(`"fff"`):

``` json
{
  "foo": {
    "bar": "fff"
  }
}
```

or an array of strings (`["fff","ggg"]`):

``` json
{
  "foo": {
    "bar": ["fff","ggg"]
  }
}
```

If you want to pass options to the transforms, you can use a 2-element array
inside of the primary array. Here `fff` gets an options object with `{"x":3}`
and `ggg` gets `{"y":4}`:

``` json
{
  "foo": {
    "bar": [["fff",{"x":3}],["ggg",{"y":4}]]
  }
}
```

# usage

```
module-deps [FILES] OPTIONS

  Generate json output for the entry point FILES.

OPTIONS are:

  -t TRANSFORM  Apply a TRANSFORM.
  -g TRANSFORM  Apply a global TRANSFORM.

```

# install

With [npm](http://npmjs.org), to get the module do:

```
npm install module-deps
```

and to get the `module-deps` command do:

```
npm install -g module-deps
```

# license

MIT