Skip to content

Commit 3c024ac

Browse files
ruyadornowraithgar
ruyadorno
and
wraithgar
authoredAug 1, 2022
feat: add npm query cmd (#5000)
Co-authored-by: Gar <[email protected]>
·
v11.2.0arborist-v5.4.0
1 parent 050284d commit 3c024ac

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

60 files changed

+8391
-9
lines changed
 

‎docs/content/commands/npm-query.md

+236
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,236 @@
1+
---
2+
title: npm-query
3+
section: 1
4+
description: Dependency selector query
5+
---
6+
7+
### Synopsis
8+
9+
<!-- AUTOGENERATED USAGE DESCRIPTIONS START -->
10+
<!-- automatically generated, do not edit manually -->
11+
<!-- see lib/commands/query.js -->
12+
13+
```bash
14+
npm query <selector>
15+
```
16+
17+
<!-- automatically generated, do not edit manually -->
18+
<!-- see lib/commands/query.js -->
19+
20+
<!-- AUTOGENERATED USAGE DESCRIPTIONS END -->
21+
22+
### Description
23+
24+
The `npm query` command allows for usage of css selectors in order to retrieve
25+
an array of dependency objects.
26+
27+
### Piping npm query to other commands
28+
29+
```bash
30+
# find all dependencies with postinstall scripts & uninstall them
31+
npm query ":attr(scripts, [postinstall])" | jq 'map(.name)|join("\n")' -r | xargs -I {} npm uninstall {}
32+
33+
# find all git dependencies & explain who requires them
34+
npm query ":type(git)" | jq 'map(.name)' | xargs -I {} npm why {}
35+
```
36+
37+
### Extended Use Cases & Queries
38+
39+
```stylus
40+
// all deps
41+
*
42+
43+
// all direct deps
44+
:root > *
45+
46+
// direct production deps
47+
:root > .prod
48+
49+
// direct development deps
50+
:root > .dev
51+
52+
// any peer dep of a direct deps
53+
:root > * > .peer
54+
55+
// any workspace dep
56+
.workspace
57+
58+
// all workspaces that depend on another workspace
59+
.workspace > .workspace
60+
61+
// all workspaces that have peer deps
62+
.workspace:has(.peer)
63+
64+
// any dep named "lodash"
65+
// equivalent to [name="lodash"]
66+
#lodash
67+
68+
// any deps named "lodash" & within semver range ^"1.2.3"
69+
#lodash@^1.2.3
70+
// equivalent to...
71+
[name="lodash"]:semver(^1.2.3)
72+
73+
// get the hoisted node for a given semver range
74+
#lodash@^1.2.3:not(:deduped)
75+
76+
// querying deps with a specific version
77+
#lodash@2.1.5
78+
// equivalent to...
79+
[name="lodash"][version="2.1.5"]
80+
81+
// has any deps
82+
:has(*)
83+
84+
// deps with no other deps (ie. "leaf" nodes)
85+
:empty
86+
87+
// manually querying git dependencies
88+
[repository^=github:],
89+
[repository^=git:],
90+
[repository^=https://github.com],
91+
[repository^=http://github.com],
92+
[repository^=https://github.com],
93+
[repository^=+git:...]
94+
95+
// querying for all git dependencies
96+
:type(git)
97+
98+
// get production dependencies that aren't also dev deps
99+
.prod:not(.dev)
100+
101+
// get dependencies with specific licenses
102+
[license=MIT], [license=ISC]
103+
104+
// find all packages that have @ruyadorno as a contributor
105+
:attr(contributors, [email=ruyadorno@github.com])
106+
```
107+
108+
### Example Response Output
109+
110+
- an array of dependency objects is returned which can contain multiple copies of the same package which may or may not have been linked or deduped
111+
112+
```json
113+
[
114+
{
115+
"name": "",
116+
"version": "",
117+
"description": "",
118+
"homepage": "",
119+
"bugs": {},
120+
"author": {},
121+
"license": {},
122+
"funding": {},
123+
"files": [],
124+
"main": "",
125+
"browser": "",
126+
"bin": {},
127+
"man": [],
128+
"directories": {},
129+
"repository": {},
130+
"scripts": {},
131+
"config": {},
132+
"dependencies": {},
133+
"devDependencies": {},
134+
"optionalDependencies": {},
135+
"bundledDependencies": {},
136+
"peerDependencies": {},
137+
"peerDependenciesMeta": {},
138+
"engines": {},
139+
"os": [],
140+
"cpu": [],
141+
"workspaces": {},
142+
"keywords": [],
143+
...
144+
},
145+
...
146+
```
147+
148+
### Configuration
149+
150+
<!-- AUTOGENERATED CONFIG DESCRIPTIONS START -->
151+
<!-- automatically generated, do not edit manually -->
152+
<!-- see lib/utils/config/definitions.js -->
153+
#### `global`
154+
155+
* Default: false
156+
* Type: Boolean
157+
158+
Operates in "global" mode, so that packages are installed into the `prefix`
159+
folder instead of the current working directory. See
160+
[folders](/configuring-npm/folders) for more on the differences in behavior.
161+
162+
* packages are installed into the `{prefix}/lib/node_modules` folder, instead
163+
of the current working directory.
164+
* bin files are linked to `{prefix}/bin`
165+
* man pages are linked to `{prefix}/share/man`
166+
167+
<!-- automatically generated, do not edit manually -->
168+
<!-- see lib/utils/config/definitions.js -->
169+
170+
#### `workspace`
171+
172+
* Default:
173+
* Type: String (can be set multiple times)
174+
175+
Enable running a command in the context of the configured workspaces of the
176+
current project while filtering by running only the workspaces defined by
177+
this configuration option.
178+
179+
Valid values for the `workspace` config are either:
180+
181+
* Workspace names
182+
* Path to a workspace directory
183+
* Path to a parent workspace directory (will result in selecting all
184+
workspaces within that folder)
185+
186+
When set for the `npm init` command, this may be set to the folder of a
187+
workspace which does not yet exist, to create the folder and set it up as a
188+
brand new workspace within the project.
189+
190+
This value is not exported to the environment for child processes.
191+
192+
<!-- automatically generated, do not edit manually -->
193+
<!-- see lib/utils/config/definitions.js -->
194+
195+
#### `workspaces`
196+
197+
* Default: null
198+
* Type: null or Boolean
199+
200+
Set to true to run the command in the context of **all** configured
201+
workspaces.
202+
203+
Explicitly setting this to false will cause commands like `install` to
204+
ignore workspaces altogether. When not set explicitly:
205+
206+
- Commands that operate on the `node_modules` tree (install, update, etc.)
207+
will link workspaces into the `node_modules` folder. - Commands that do
208+
other things (test, exec, publish, etc.) will operate on the root project,
209+
_unless_ one or more workspaces are specified in the `workspace` config.
210+
211+
This value is not exported to the environment for child processes.
212+
213+
<!-- automatically generated, do not edit manually -->
214+
<!-- see lib/utils/config/definitions.js -->
215+
216+
#### `include-workspace-root`
217+
218+
* Default: false
219+
* Type: Boolean
220+
221+
Include the workspace root when workspaces are enabled for a command.
222+
223+
When false, specifying individual workspaces via the `workspace` config, or
224+
all workspaces via the `workspaces` flag, will cause npm to operate only on
225+
the specified workspaces, and not on the root project.
226+
227+
This value is not exported to the environment for child processes.
228+
229+
<!-- automatically generated, do not edit manually -->
230+
<!-- see lib/utils/config/definitions.js -->
231+
232+
<!-- AUTOGENERATED CONFIG DESCRIPTIONS END -->
233+
## See Also
234+
235+
* [dependency selector](/using-npm/dependency-selector)
236+

0 commit comments

Comments
 (0)
Please sign in to comment.