@npmcli/arborist

Inspect and managenode_modules trees.

There's more documentationin the notesfolder.

USAGE

constArborist=require('@npmcli/arborist')constarb=newArborist({// options object// where we're doing stuff.  defaults to cwd.path:'/path/to/package/root',// url to the default registry.  defaults to npm's default registryregistry:'https://registry.npmjs.org',// scopes can be mapped to a different registry'@foo:registry':'https://registry.foo.com/',// Auth can be provided in a couple of different ways.  If none are// provided, then requests are anonymous, and private packages will 404.// Arborist doesn't do anything with these, it just passes them down// the chain to pacote and npm-registry-fetch.// Safest: a bearer token provided by a registry:// 1. an npm auth token, used with the default registrytoken:'deadbeefcafebad',// 2. an alias for the same thing:_authToken:'deadbeefcafebad',// insecure options:// 3. basic auth, username:password, base64 encodedauth:'aXNhYWNzOm5vdCBteSByZWFsIHBhc3N3b3Jk',// 4. username and base64 encoded passwordusername:'isaacs',password:'bm90IG15IHJlYWwgcGFzc3dvcmQ=',// auth configs can also be scoped to a given registry with this// rather unusual pattern:'//registry.foo.com:token':'blahblahblah','//basic.auth.only.foo.com:_auth':'aXNhYWNzOm5vdCBteSByZWFsIHBhc3N3b3Jk',// in fact, ANY config can be scoped to a registry...'//registry.foo.com:always-auth':true,})// READING// returns a promise.  reads the actual contents of node_modulesarb.loadActual().then(tree=>{// tree is also stored at arb.virtualTree})// read just what the package-lock.json/npm-shrinkwrap says// This *also* loads the yarn.lock file, but that's only relevant// when building the ideal tree.arb.loadVirtual().then(tree=>{// tree is also stored at arb.virtualTree// now arb.virtualTree is loaded// this fails if there's no package-lock.json or package.json in the folder// note that loading this way should only be done if there's no// node_modules folder})// OPTIMIZING AND DESIGNING// build an ideal tree from the package.json and various lockfiles.arb.buildIdealTree(options).then(()=>{// next step is to reify that ideal tree onto disk.// options can be:// rm: array of package names to remove at top level// add: Array of package specifiers to add at the top level.  Each of//   these will be resolved with pacote.manifest if the name can't be//   determined from the spec.  (Eg, `github:foo/bar` vs `foo@somespec`.)//   The dep will be saved in the location where it already exists,//   (or pkg.dependencies) unless a different saveType is specified.// saveType: Save added packages in a specific dependency set.//   - null (default) Wherever they exist already, or 'dependencies'//   - prod: definitely in 'dependencies'//   - optional: in 'optionalDependencies'//   - dev: devDependencies//   - peer: save in peerDependencies, and remove any optional flag from//     peerDependenciesMeta if one exists//   - peerOptional: save in peerDependencies, and add a//     peerDepsMeta[name].optional flag// saveBundle: add newly added deps to the bundleDependencies list// update: Either `true` to just go ahead and update everything, or an//   object with any or all of the following fields://   - all: boolean.  set to true to just update everything//   - names: names of packages update (like `npm update foo`)// prune: boolean, default true.  Prune extraneous nodes from the tree.// preferDedupe: prefer to deduplicate packages if possible, rather than//   choosing a newer version of a dependency.  Defaults to false, ie,//   always try to get the latest and greatest deps.// legacyBundling: Nest every dep under the node requiring it, npm v2 style.//   No unnecessary deduplication.  Default false.// At the end of this process, arb.idealTree is set.})// WRITING// Make the idealTree be the thing that's on diskarb.reify({// write the lockfile(s) back to disk, and package.json with any updates// defaults to 'true'save:true,}).then(()=>{// node modules has been written to match the idealTree})

DATA STRUCTURES

Anode_modules tree is a logical graph of dependencies overlaid on aphysical tree of folders.

ANode represents a package folder on disk, either at the root of thepackage, or within anode_modules folder. The physical structure of thefolder tree is represented by thenode.parent reference to the containingfolder, andnode.children map of nodes within itsnode_modulesfolder, where the key in the map is the name of the folder innode_modules, and the value is the child node.

A node without a parent is a top of tree.

ALink represents a symbolic link to a package on disk. This can be asymbolic link to a package folder within the current tree, or elsewhere ondisk. Thelink.target is a reference to the actual node. Links differfrom Nodes in that dependencies are resolved from thetarget location,rather than from the link location.

AnEdge represents a dependency relationship. Each node has anedgesInset, and anedgesOut map. Each edge has atype which specifies whatkind of dependency it represents:'prod' for regular dependencies,'peer' for peerDependencies,'dev' for devDependencies, and'optional' for optionalDependencies.edge.from is a reference to thenode that has the dependency, andedge.to is a reference to the node thatrequires the dependency.

As nodes are moved around in the tree, the graph edges are automaticallyupdated to point at the new module resolution targets. In other words,edge.from,edge.name, andedge.spec are immutable;edge.to isupdated automatically when a node's parent changes.

class Node

All arborist trees areNode objects. ANode refersto a package folder, which may have children innode_modules.

• node.name The name of this node's folder innode_modules.

• node.parent Physical parent node in the tree. The package in whosenode_modules folder this package lives. Null if node is top of tree.

  Settingnode.parent will automatically updatenode.location and allgraph edges affected by the move.

• node.meta AShrinkwrap object which looks upresolved andintegrity values for all modules in this tree. Only relevant onrootnodes.

• node.children Map of packages located in the node'snode_modulesfolder.

• node.package The contents of this node'spackage.json file.

• node.path File path to this package. If the node is a link, then thisis the path to the link, not to the link target. If the node isnot alink, then this matchesnode.realpath.

• node.realpath The full real filepath on disk where this node lives.

• node.location A slash-normalized relative path from the root node tothis node's path.

• node.isLink Whether this represents a symlink. Alwaysfalse for Nodeobjects, alwaystrue for Link objects.

• node.isRoot True if this node is a root node. (Ie, ifnode.root === node.)

• node.root The root node where we are working. If not assigned to someother value, resolves to the node itself. (Ie, the root node'srootproperty refers to itself.)

• node.isTop True if this node is the top of its tree (ie, has noparent, false otherwise).

• node.top The top node in this node's tree. This will be equal tonode.root for simple trees, but link targets will frequently be outsideof (or nested somewhere within) anode_modules hierarchy, and so willhave a differenttop.

• node.dev,node.optional,node.devOptional,node.peer, Indicatorsas to whether this node is a dev, optional, and/or peer dependency.These flags are relevant when pruning dependencies out of the tree ordeciding what to reify. SeePackage Dependency Flags below forexplanations.

• node.edgesOut Edges in the dependency graph indicating nodes that thisnode depends on, which resolve its dependencies.

• node.edgesIn Edges in the dependency graph indicating nodes that dependon this node.

• extraneous True if this package is not required by any other for anyreason. False for top of tree.

• node.resolve(name) Identify the node that will be returned when codein this package runsrequire(name)

• node.errors Array of errors encountered while parsing package.json orversion specifiers.

class Link

Link objects represent a symbolic link within thenode_modules folder.They have most of the same properties and methods asNode objects, with afew differences.

• link.target A Node object representing the package that the linkreferences. If this is a Node already present within the tree, then itwill be the same object. If it's outside of the tree, then it will betreated as the top of its own tree.
• link.isLink Always true.
• link.children This is always an empty map, since links don't have theirown children directly.

class Edge

Edge objects represent a dependency relationship a package node to thepoint in the tree where the dependency will be loaded. As nodes are movedwithin the tree, Edges automatically update to point to the appropriatelocation.

• new Edge({ from, type, name, spec }) Creates a new edge with thespecified fields. After instantiation, none of the fields can bechanged directly.
• edge.from The node that has the dependency.
• edge.type The type of dependency. One of'prod','dev','peer',or'optional'.
• edge.name The name of the dependency. Ie, the key in therelevantpackage.json dependencies object.
• edge.spec The specifier that is required. This can be a version,range, tag name, git url, or tarball URL. Any specifier allowed by npmis supported.
• edge.to Automatically set to the node in the tree that matches thename field.
• edge.valid True ifedge.to satisfies the specifier.
• edge.error A string indicating the type of error if there is a problem,ornull if it's valid. Values, in order of precedence:
  • DETACHED Indicates that the edge has been detached from itsedge.from node, typically because a new edge was created when adependency specifier was modified.
  • MISSING Indicates that the dependency is unmet. Note that this isnot set for unmet dependencies of theoptional type.
  • PEER LOCAL Indicates that apeerDependency is found in thenode's localnode_modules folder, and the node is not the top ofthe tree. This violates thepeerDependency contract, because itmeans that the dependency is not a peer.
  • INVALID Indicates that the dependency does not satisfyedge.spec.
• edge.reload() Re-resolve to find the appropriate value foredge.to.Called automatically from theNode class when the tree is mutated.

Package Dependency Flags

The dependency type of a node can be determined efficiently by looking atthedev,optional, anddevOptional flags on the node object. Theseare updated by arborist when necessary whenever the tree is modified insuch a way that the dependency graph can change, and are relevant whenpruning nodes from the tree.

| extraneous | peer | dev | optional | devOptional | meaning             | prune?            ||------------+------+-----+----------+-------------+---------------------+-------------------||            |      |     |          |             | production dep      | never             ||------------+------+-----+----------+-------------+---------------------+-------------------||     X      | N/A  | N/A |   N/A    |     N/A     | nothing depends on  | always            ||            |      |     |          |             | this, it is trash   |                   ||------------+------+-----+----------+-------------+---------------------+-------------------||            |      |  X  |          |      X      | devDependency, or   | if pruning dev    ||            |      |     |          | not in lock | only depended upon  |                   ||            |      |     |          |             | by devDependencies  |                   ||------------+------+-----+----------+-------------+---------------------+-------------------||            |      |     |    X     |      X      | optionalDependency, | if pruning        ||            |      |     |          | not in lock | or only depended on | optional          ||            |      |     |          |             | by optionalDeps     |                   ||------------+------+-----+----------+-------------+---------------------+-------------------||            |      |  X  |    X     |      X      | Optional dependency | if pruning EITHER ||            |      |     |          | not in lock | of dep(s) in the    | dev OR optional   ||            |      |     |          |             | dev hierarchy       |                   ||------------+------+-----+----------+-------------+---------------------+-------------------||            |      |     |          |      X      | BOTH a non-optional | if pruning BOTH   ||            |      |     |          |   in lock   | dep within the dev  | dev AND optional  ||            |      |     |          |             | hierarchy, AND a    |                   ||            |      |     |          |             | dep within the      |                   ||            |      |     |          |             | optional hierarchy  |                   ||------------+------+-----+----------+-------------+---------------------+-------------------||            |  X   |     |          |             | peer dependency, or | if pruning peers  ||            |      |     |          |             | only depended on by |                   ||            |      |     |          |             | peer dependencies   |                   ||------------+------+-----+----------+-------------+---------------------+-------------------||            |  X   |  X  |          |      X      | peer dependency of  | if pruning peer   ||            |      |     |          | not in lock | dev node heirarchy  | OR dev deps       ||------------+------+-----+----------+-------------+---------------------+-------------------||            |  X   |     |    X     |      X      | peer dependency of  | if pruning peer   ||            |      |     |          | not in lock | optional nodes, or  | OR optional deps  ||            |      |     |          |             | peerOptional dep    |                   ||------------+------+-----+----------+-------------+---------------------+-------------------||            |  X   |  X  |    X     |      X      | peer optional deps  | if pruning peer   ||            |      |     |          | not in lock | of the dev dep      | OR optional OR    ||            |      |     |          |             | heirarchy           | dev               ||------------+------+-----+----------+-------------+---------------------+-------------------||            |  X   |     |          |      X      | BOTH a non-optional | if pruning peers  ||            |      |     |          |   in lock   | peer dep within the | OR:               ||            |      |     |          |             | dev heirarchy, AND  | BOTH optional     ||            |      |     |          |             | a peer optional dep | AND dev deps      |+------------+------+-----+----------+-------------+---------------------+-------------------+

• If none of these flags are set, then the node is required by thedependency and/or peerDependency hierarchy. It should not be pruned.
• Ifbothnode.dev andnode.optional are set, then the node is anoptional dependency of one of the packages in the devDependencyhierarchy. It should be pruned ifeither dev or optional deps arebeing removed.
• Ifnode.dev is set, butnode.optional is not, then the node isrequired in the devDependency hierarchy. It should be pruned if devdependencies are being removed.
• Ifnode.optional is set, butnode.dev is not, then the node isrequired in the optionalDependency hierarchy. It should be pruned ifoptional dependencies are being removed.
• Ifnode.devOptional is set, then the node is a (non-optional)dependency within the devDependency hierarchy,and a dependencywithin theoptionalDependency hierarchy. It should be pruned ifboth dev and optional dependencies are being removed.
• Ifnode.peer is set, then all the same semantics apply as above, exceptthat the dep is brought in by a peer dep at some point, rather than anormal non-peer dependency.

Note:devOptional is only set in the shrinkwrap/package-lock file ifneitherdev noroptional are set, as it would be redundant.