lookup-deps

Simple API for getting metadata from locally installed npm packages (in node_modules).

What does it do!?

Builds a recursive tree of all dependencies currently installed in node_modules. Allows you to easily get information from the package.json of any locally installed module.

Examples:

Get the version of the specified dependency:

deps.get('markdown-utils', 'version');
//=> '0.1.0'

Use glob patterns to get the specified property from every dependency:

deps.get('*', 'homepage')

// returns an object like this:
{ globby: 'https://github.com/sindresorhus/globby',
 'is-relative': 'https://github.com/jonschlinkert/is-relative',
 'is-absolute': 'https://github.com/jonschlinkert/is-absolute', ...}

If an object is returned with null values, this means that the package wasn't found at the given path. e.g. it was symlinked by npm.

To get around this, you can pass {findup: true} to the constructor and [findup-sync] will be used to find the nearest match. This is disabled by default since this is an exception to the rule and it considerably slows down searches.

Install

Install with npm:

npm i lookup-deps --save-dev

Run tests

npm test

Usage

var Deps = require('lookup-deps');
var deps = new Deps();

API

Lookup

Create a new instance of Lookup.

• config {Object}: Optionally pass a default config object instead of package.json For now there is no reason to do this.
• options {Object}

var Lookup = require('lookup-deps');
var deps = new Lookup();

.get

Get a value from the cache.

• name {Object}: The module to get.
• props {String}: Property paths.
• returns: {Object}

// get an entire package.json
deps.get('markdown-utils');
//=> { pkg: { name: 'markdown-utils', version: '0.3.0', ... }

// or, get a specific value
deps.get('markdown-utils', 'version');
//=> '0.3.0'

.exists

Check to see if a module exists (or at least is on the cache).

• name {String}: The name to check.
• returns: {String}

deps.exists('markdown-utils');
//=> true

.depsKeys

Get the keys for dependencies for the specified package.

• config {Object|String}: The name of the module, or package.json config object.
• returns: {Object}

deps.depsKeys('markdown-utils');
//=> [ 'is-absolute', 'kind-of', 'relative', ... ]

.findPkg

• filepath {String}
• returns: {String}

Find a package.json for the given module by name, starting the search at the given cwd.

.tree

Build a dependency tree by recursively reading in package.json files for projects in node_modules.

• cwd {String}: The root directory to search from.
• returns: {Object}

deps.tree('./');

.filter

Filter the entire cache object to have only packages with names that match the given glob patterns.

• patterns {String|Array}: Glob patterns to use for filtering modules.
• keyPatterns {String|Array}: Glob patterns to use for filtering the keys on each object.
• returns {Object}: Filtered object.

You may also filter the keys on each object by passing additional glob patterns as a second argument.

deps.filter('markdown-*');
//=> {'markdown-utils': {...}}

// exclude the `readme` key from package.json objects
deps.filter('markdown-*', ['*', '!readme']);
//=> {'markdown-utils': {...}}

.getParents

Returns an object of all modules that have the given module as a dependency. Glob patterns may be used for filtering.

• patterns {String|Array}: Glob patterns to use for filtering.
• returns {Object}: Object of parent modules.

deps.getParents('*');

.names

Return a list of names of all resolved packages from node_modules that match the given glob patterns. If no pattern is provided the entire list is returned.

• patterns {String|Array}: Glob patterns to use for filtering.
• returns {Array}: Array of keys.

deps.names('markdown-*');
//=> ['markdown-utils']

.find

Find a module or modules using glob patterns, and return an object filtered to have only the specified props. Note that package.json objects are stored on the pkg property for each module.

• patterns {String}
• props {String}
• returns: {Object}

Properties are specified using object paths:

deps.find('for-*', 'pkg.repository.url');

// results in:
// { 'for-own': 'git://github.com/jonschlinkert/for-own.git',
//   'for-in': 'git://github.com/jonschlinkert/for-in.git' }

.lookup

A convenience proxy for the .find() method to specifically search the pkg object of each module on the cache.

• patterns {String}
• props {String}
• returns: {Object}

deps.lookup('for-*', 'repository.url');

// results in:
// { 'for-own': 'git://github.com/jonschlinkert/for-own.git',
//   'for-in': 'git://github.com/jonschlinkert/for-in.git' }

.paths

Get the path to a module or modules, relative to the current working directory. Glob patterns may be used.

• patterns {String}
• returns: {String}

deps.paths('*');

.pkg

Get the package.json objects for the given module or modules. Glob patterns may be used.

• patterns {String}
• returns: {String}

deps.pkg('markdown-utils');

.dependencies

Get the dependencies for the given modules. Glob patterns may be used.

• patterns {String}
• returns: {Object}

deps.dependencies('multi*');
//=> { multimatch: { 'array-differ': '^1.0.0', ... } }

.devDependencies

Get the devDependencies for the given modules. Glob patterns may be used.

• patterns {String}
• returns: {Object}

deps.devDependencies('multi*');
//=> { multimatch: { 'array-differ': '^1.0.0', ... } }

.keywords

Get the keywords for the given modules.

• patterns {String}
• returns: {String}

deps.keywords('multi*');
//=> { multimatch: [ 'minimatch', 'match', ... ] }

.homepage

Get the homepage for the specified modules.

• patterns {String}
• returns: {String}

deps.homepage('markdown-*');
//=> { 'markdown-utils': 'https://github.com/jonschlinkert/markdown-utils' }

.links

Get a list of markdown-formatted links, from the homepage properties of the specified modules.

• patterns {String}
• returns: {String}

deps.links('markdown-*');
//=> [markdown-utils](https://github.com/jonschlinkert/markdown-utils)

.reflinks

Get a list of markdown-formatted links, from the homepage properties of the specified modules.

• patterns {String}
• returns: {String}

deps.reflinks('markdown-*');
//=> [markdown-utils]: https://github.com/jonschlinkert/markdown-utils

Author

Jon Schlinkert

• github/jonschlinkert
• twitter/jonschlinkert

License

Copyright (c) 2014-2015 Jon Schlinkert
Released under the MIT license

This file was generated by verb on February 03, 2015.