deptrace

deptrace

A tool for tracing recursive dependency trees asynchronously.

API

constructor(opts)

Create an instance of Deptrace to trace your dependencies.

const tracer = new Deptrace({
  depsFor: function (input) {
    // extract dependencies from something into an array of objects
  },
  lookup: function (dep, parents) {
    // resolve an individual dependency into a dependency object
  },
  format: function (input, deps) {
    // format the result of a dependency after it's associated deps
  }
});

opts.depsFor(input)

Receives an object and must return a promise yielding an array of its dependencies.

Type: Function
Default: null

Example extracting an array of dependencies from the contents of a package.json file.

const Deptrace = require('./');
const archy = require('archy');
const promise = require('bluebird');

const tracer = new Deptrace({
  depsFor: function (input) {
    var deps = input.dependencies || [];
    return promise.resolve(Object.keys(deps).map(function(depName) {
      return {
        name: depName,
        version: deps[depName]
      };  
    }))
  }
});
tracer.graph(require('./package.json')).then(function (graph) {
  console.log(archy(graph));
});

opts.lookup(dep, parents)

Receives each dependency gathered by depsFor, as well as an array of all parent dependencies. Must return a promise. This method is optional and can be used to resolve a more detailed version of a dependency. (e.g. converting the named of the dependency in package.json to the actual package.json of that dependency).

Here is a naive example which can trace dependencies for any npm module for which all dependencies are on github:

const Deptrace = require('./');
const archy = require('archy');
const githubUrlFromGit = require('github-url-from-git');
const promise = require('bluebird');
const request = promise.promisify(require('request').get);
const tracer = new Deptrace({
  depsFor: Deptrace.packageJson('dependencies'),
  lookup: function (dep, parents) {
    return request('http://registry.npmjs.org/'+dep.name).
      get(1).
      then(JSON.parse).
      then(function(pkg) {
        return [
          'https://raw.githubusercontent.com',
          url.parse(githubUrlFromGit(pkg.repository.url)).path,
          '/master/package.json'
        ].join('');
      }).
      then(request).
      get(1).
      then(JSON.parse);
  },
  format: function (input, deps) {
    return promise.resolve({
      label: input.name,
      nodes: deps
    });
  }
});
var requestPkg = require('./node_modules/request/package.json');
tracer.graph(requestPkg).then(function (graph) {
  console.log(archy(graph));
});

opts.format(input, deps)

This method can be used to format the result for each node of the dependency after all of its dependencies have been resolved.

The default implementation (show in the example above) formats the dependency tree to be compatible with archy (as follows):

{
  label: 'parent',
  nodes: [
    {
      label: 'child'
      nodes: [
        {
          label: 'subchild'
          nodes: []
        }
      ]
    }
  ]
}

packageJson(field)

This helper can be used to generate a depsFor method that will extract dependencies from package.json files under the provided key. See example for opts.lookup(deps, parents).