README.md
1# npm-logical-tree [](https://npm.im/npm-logical-tree) [](https://npm.im/npm-logical-tree) [](https://travis-ci.org/npm/logical-tree) [](https://ci.appveyor.com/project/npm/logical-tree) [](https://coveralls.io/github/npm/logical-tree?branch=latest)
2
3[`npm-logical-tree`](https://github.com/npm/npm-logical-tree) is a Node.js
4library that takes the contents of a `package.json` and `package-lock.json` (or
5`npm-shrinkwrap.json`) and returns a nested tree data structure representing the
6logical relationships between the different dependencies.
7
8## Install
9
10`$ npm install npm-logical-tree`
11
12## Table of Contents
13
14* [Example](#example)
15* [Contributing](#contributing)
16* [API](#api)
17 * [`logicalTree`](#logical-tree)
18 * [`logicalTree.node`](#make-node)
19 * [`tree.isRoot`](#is-root)
20 * [`tree.addDep`](#add-dep)
21 * [`tree.delDep`](#del-dep)
22 * [`tree.getDep`](#get-dep)
23 * [`tree.path`](#path)
24 * [`tree.hasCycle`](#has-cycle)
25 * [`tree.forEach`](#for-each)
26 * [`tree.forEachAsync`](#for-each-async)
27
28### Example
29
30```javascript
31const fs = require('fs')
32const logicalTree = require('npm-logical-tree')
33
34const pkg = require('./package.json')
35const pkgLock = require('./package-lock.json')
36
37logicalTree(pkg, pkgLock)
38// returns:
39LogicalTree {
40 name: 'npm-logical-tree',
41 version: '1.0.0',
42 address: null,
43 optional: false,
44 dev: false,
45 bundled: false,
46 resolved: undefined,
47 integrity: undefined,
48 requiredBy: Set { },
49 dependencies:
50 Map {
51 'foo' => LogicalTree {
52 name: 'foo',
53 version: '1.2.3',
54 address: 'foo',
55 optional: false,
56 dev: true,
57 bundled: false,
58 resolved: 'https://registry.npmjs.org/foo/-/foo-1.2.3.tgz',
59 integrity: 'sha1-rYUK/p261/SXByi0suR/7Rw4chw=',
60 dependencies: Map { ... },
61 requiredBy: Set { ... },
62 },
63 ...
64 }
65}
66```
67
68### Contributing
69
70The npm team enthusiastically welcomes contributions and project participation!
71There's a bunch of things you can do if you want to contribute! The [Contributor
72Guide](CONTRIBUTING.md) has all the information you need for everything from
73reporting bugs to contributing entire new features. Please don't hesitate to
74jump in if you'd like to, or even ask us questions if something isn't clear.
75
76All participants and maintainers in this project are expected to follow [Code of
77Conduct](CODE_OF_CONDUCT.md), and just generally be excellent to each other.
78
79Please refer to the [Changelog](CHANGELOG.md) for project history details, too.
80
81Happy hacking!
82
83### API
84
85#### <a name="logical-tree"></a> `> logicalTree(pkg, lock) -> LogicalTree`
86
87Calculates a logical tree based on a matching `package.json` and
88`package-lock.json` pair. A "logical tree" is a fully-nested dependency graph
89for an npm package, as opposed to a physical tree which might be flattened.
90
91`logical-tree` will represent deduplicated/flattened nodes using the same object
92throughout the tree, so duplication can be checked by object identity.
93
94##### Example
95
96```javascript
97const pkg = require('./package.json')
98const pkgLock = require('./package-lock.json')
99
100logicalTree(pkg, pkgLock)
101// returns:
102LogicalTree {
103 name: 'npm-logical-tree',
104 version: '1.0.0',
105 address: null,
106 optional: false,
107 dev: false,
108 bundled: false,
109 resolved: undefined,
110 integrity: undefined,
111 requiredBy: Set { },
112 dependencies:
113 Map {
114 'foo' => LogicalTree {
115 name: 'foo',
116 version: '1.2.3',
117 address: 'foo',
118 optional: false,
119 dev: true,
120 bundled: false,
121 resolved: 'https://registry.npmjs.org/foo/-/foo-1.2.3.tgz',
122 integrity: 'sha1-rYUK/p261/SXByi0suR/7Rw4chw=',
123 requiredBy: Set { ... },
124 dependencies: Map { ... }
125 },
126 ...
127 }
128}
129```
130
131#### <a name="make-node"></a> `> logicalTree.node(name, [address, [opts]]) -> LogicalTree`
132
133Manually creates a new LogicalTree node.
134
135##### Options
136
137* `opts.version` - version of the node.
138* `opts.optional` - is this node an optionalDep?
139* `opts.dev` - is this node a devDep?
140* `opts.bundled` - is this bundled?
141* `opts.resolved` - resolved address.
142* `opts.integrity` - SRI string.
143
144##### Example
145```javascript
146logicalTree.node('hello', 'subpath:to:@foo/bar', {dev: true})
147```
148
){kind=link}
){kind=link}
){kind=link}
){kind=link}