source: trip-planner-front/node_modules/@npmcli/installed-package-contents/README.md@ fa375fe

Last change on this file since fa375fe was 6a3a178, checked in by Ema <ema_spirova@…>, 3 years ago

initial commit

  • Property mode set to 100644
File size: 4.1 KB
Line 
1# @npmcli/installed-package-contents
2
3Get the list of files installed in a package in node_modules, including
4bundled dependencies.
5
6This is useful if you want to remove a package node from the tree _without_
7removing its child nodes, for example to extract a new version of the
8dependency into place safely.
9
10It's sort of the reflection of [npm-packlist](http://npm.im/npm-packlist),
11but for listing out the _installed_ files rather than the files that _will_
12be installed. This is of course a much simpler operation, because we don't
13have to handle ignore files or package.json `files` lists.
14
15## USAGE
16
17```js
18// programmatic usage
19const pkgContents = require('@npmcli/installed-package-contents')
20
21pkgContents({ path: 'node_modules/foo', depth: 1 }).then(files => {
22 // files is an array of items that need to be passed to
23 // rimraf or moved out of the way to make the folder empty
24 // if foo bundled dependencies, those will be included.
25 // It will not traverse into child directories, because we set
26 // depth:1 in the options.
27 // If the folder doesn't exist, this returns an empty array.
28})
29
30pkgContents({ path: 'node_modules/foo', depth: Infinity }).then(files => {
31 // setting depth:Infinity tells it to keep walking forever
32 // until it hits something that isn't a directory, so we'll
33 // just get the list of all files, but not their containing
34 // directories.
35})
36```
37
38As a CLI:
39
40```bash
41$ installed-package-contents node_modules/bundle-some -d1
42node_modules/.bin/some
43node_modules/bundle-some/package.json
44node_modules/bundle-some/node_modules/@scope/baz
45node_modules/bundle-some/node_modules/.bin/foo
46node_modules/bundle-some/node_modules/foo
47```
48
49CLI options:
50
51```
52Usage:
53 installed-package-contents <path> [-d<n> --depth=<n>]
54
55Lists the files installed for a package specified by <path>.
56
57Options:
58 -d<n> --depth=<n> Provide a numeric value ("Infinity" is allowed)
59 to specify how deep in the file tree to traverse.
60 Default=1
61 -h --help Show this usage information
62```
63
64## OPTIONS
65
66* `depth` Number, default `1`. How deep to traverse through folders to get
67 contents. Typically you'd want to set this to either `1` (to get the
68 surface files and folders) or `Infinity` (to get all files), but any
69 other positive number is supported as well. If set to `0` or a
70 negative number, returns the path provided and (if it is a package) its
71 set of linked bins.
72* `path` Required. Path to the package in `node_modules` where traversal
73 should begin.
74
75## RETURN VALUE
76
77A Promise that resolves to an array of fully-resolved files and folders
78matching the criteria. This includes all bundled dependencies in
79`node_modules`, and any linked executables in `node_modules/.bin` that the
80package caused to be installed.
81
82An empty or missing package folder will return an empty array. Empty
83directories _within_ package contents are listed, even if the `depth`
84argument would cause them to be traversed into.
85
86## CAVEAT
87
88If using this module to generate a list of files that should be recursively
89removed to clear away the package, note that this will leave empty
90directories behind in certain cases:
91
92- If all child packages are bundled dependencies, then the
93 `node_modules` folder will remain.
94- If all child packages within a given scope were bundled dependencies,
95 then the `node_modules/@scope` folder will remain.
96- If all linked bin scripts were removed, then an empty `node_modules/.bin`
97 folder will remain.
98
99In the interest of speed and algorithmic complexity, this module does _not_
100do a subsequent readdir to see if it would remove all directory entries,
101though it would be easier to look at if it returned `node_modules` or
102`.bin` in that case rather than the contents. However, if the intent is to
103pass these arguments to `rimraf`, it hardly makes sense to do _two_
104`readdir` calls just so that we can have the luxury of having to make a
105third.
106
107Since the primary use case is to delete a package's contents so that they
108can be re-filled with a new version of that package, this caveat does not
109pose a problem. Empty directories are already ignored by both npm and git.
Note: See TracBrowser for help on using the repository browser.